关于 RESTFul 参数规则 哪种比较合理? 返回值: code:200,message:'succ', id:'12', name:'course12' code:200,message:'succ', data:{id:'12', name:'course12'} 入参: token:'123456', id:' ..

restful参数规则讨论

本贴最后更新于 1254 天前,其中的信息可能已经天翻地覆

关于 RESTFul 参数规则 哪种比较合理?

返回值:

  1. code:200,message:"succ", id:"12", name:"course12"
  2. code:200,message:"succ", data:{id:"12", name:"course12"}

入参:

  1. token:"123456", id:"12", name:"course12"
  2. token:"123456", data:{id:"12", name:"course12"}

如果做合法性验证??

以及是否增加时间戳验证??

我之前做了时间戳 遇到的比较坑的事是 客户端(手机)的时间不准。。调了系统时间导致 app 没数据了。。。

合法性验证 之前做的 是把所有参数 进行 SHA-1 签名 然后服务端验证参数是否被串改

再补充一个问题

关于接口版本控制,你们是放在 path 里 还是 参数 params 里?

我觉得 path 里直观@PathVariable, 但是不合法就直接被 Spring 返回了

如果放到参数里,可以增加更多控制操作

  • RESTful

    一种软件架构设计风格而不是标准,提供了一组设计原则和约束条件,主要用于客户端和服务器交互类的软件。基于这个风格设计的软件可以更简洁,更有层次,更易于实现缓存等机制。

    23 引用 • 103 回帖 • 134 关注
  • 参数
    6 引用 • 45 回帖
  • 合法性
    1 引用 • 28 回帖
  • 时间戳
    1 引用 • 28 回帖
28 回帖   
请输入回帖内容...
  • zempty  

    社区巡逻队日常巡检,楼主你好!楼主再见!🚜🚜🚜

  • 88250

    ####返回值

    • HTTP Status Code 最好只是用来做特殊的场景,比如 401、403、404 等,建议统一返回 200,见下一条
    • 一般正常情况都返回 [HTTP] 200,业务是否正常通过一个 bool 型 flag 进行判断,并带上 errorcode 作为业务错误返回码,正常业务返回 0
    • 数据段使用 data 一个字段统一封装,方便客户端解析 (看不懂你上面 name="course12" 这个结构,不是 JSON 吧)

    ####合法性校验

    • 客户端请求时使用私钥 app-secret、一个随机数 rand 、时间戳 timestamp 生成哈希出(可用 SHA1)一个签名 signature,然后在 HTTP 头里带上:
      • 应用标识 app-key
      • rand
      • timestamp
      • signature
    • 服务端接收到这些信息后通过 app-key 查库找到 secret,并按照客户端的哈希算法计算签名是否正确,如果和发送过来的签名一致,就继续业务处理
    • 服务端业务处理后,返回:
      • rand
      • timestamp
      • signature
        这三个参数给客户端,客户端再次按照一开始的逻辑计算 signature,然后和服务端带过来的 signature 做对比,如果一样就说明 OK

    基本的校验思路就是这样,另外,一定要走 [HTTPS] 。

    ####版本

    我个人偏向在 path 里面带版本号,一些 [RESTFul] 、HTTP API 最佳实践的文章里也推荐这个做法,好处是:

    • 版本固化,客户端不宜出错
    • 服务端版本分明,天然的路由控制

    以上。

    PS 记得给我感谢 😆

  • crick77  

    @88250

    返回值

    • 统一返回 200 是正确的 可以确认是否连接到接口处理
    • code 不建议使用 bool,不推荐 0,因为 int 默认是 0,boolean 有些语言 也会对 0 有默认,所以如果是 int 建议使用 1、2,更推荐 String,没有歧义,最近遇到的一个问题是 int 经过 JSON 转换之后变成了 double (1 变成了 1.0)
    • 是把返回的业务参数和 系统参数(状态 code,描述 message)等放在一个 map 中进行 JSON 转换,写错了 是 name:"course12"

    版本

    “服务端版本分明,天然的路由控制” 是说

    @RequestMapping(value={"/api/v1/bag/add"})

    而不是

    @RequestMapping(value={"/api/{versiokn}/bag/add"})

    ??

    合法性这个我再看一遍 不过我说的时间戳的坑 你一般把时间戳校验多长时间,我遇到过太多次 手机时间不准的 ,如果时间校验期限是几天的话 觉得也没有什么意义了

  • zonghua  

    Spring MVC 不支持组路由

    1460380783612

    你们每个 url 都要写一个版本的参数

  • crick77  

    @zonghua

    @Controller
    @RequestMapping("/api/{version}/bag")
    public class BagApi extends BaseApiController {
    
    	@Autowired
    	private IBagService bagService;
    
    	@RequestMapping(value={"/add"})
    	
    

    是不是不太好?

  • crick77  

    @88250

    还有一个坑 就是中文签名 iOS 和 Android 两种的编码不一样

  • zonghua  

    @crick77 可以这样写的咩?version这个参数注入到哪里了?

  • 88250

    @crick77

    • 成功标识是 bool,errorcode 是 int
    • 版本那个是的,服务端路由配置写死,不要动态
    • 其实我们没校验时间戳,因为你说的问题....
  • zonghua  

    @88250 写死?然后有前端的 Nginx 进行 URL 重写?

  • zonghua  

    不同版本的服务在不同服务器?

  • 88250

    @zonghua path 写死就固化了版本啊,不同版本不同实现,清晰明了

  • crick77  

    @zonghua
    public ModelAndView add(@PathVariable String version, @Valid BagDomainPo bag, BindingResult result

  • crick77  

    @88250

    还是觉得 bool 不太好,不同语言标准不一样了, 还是 String 最稳妥
    版本这个写死我觉得对, 虽然现在是动态的 + enum+switch 但我觉得 动态的话和 params 一样了 没有什么优势
    时间戳去掉吧。。。再追问一个,如果前后台分离 我想在 HTML 里也调用 API,那么 你怎么做这个 app-secret

  • 88250

    @crick77

    • 成功标识和 msg 要分开啊
    • 那就加 token 吧,用 secret 生成一个 token,然后再校验
  • crick77  

    @88250 各种疑问都问了吧
    RESTFul 你怎么做单元?
    看一下我现在写的? 不知道为什么会报错

    public class BagApiTest extends BaseUnitTest {
    
    	@Autowired
    	private BagApi bagApi;
    
    	@Autowired
    	private RequestMappingHandlerAdapter handlerAdapter;
    	private MockHttpServletRequest request;
    	private MockHttpServletResponse response;
    
    	@Before
    	public void setUp() {
    		request = new MockHttpServletRequest();
    		response = new MockHttpServletResponse();
    	}
    
    	@Test
    	public void addTest() throws Exception{
    		request.setRequestURI("/api/1/bag/add.do");  
    		request.setMethod("POST");  
    		Map<String, Object> params = new HashMap<String, Object>();
    		request.addParameters(params);
    
    		// 执行URI对应的action    
    		ModelAndView mv = handlerAdapter.handle(request, response, new HandlerMethod(bagApi, "add"));  
    		Map<String,Object> result = mv.getModel();
    		System.out.println(result);
    	}
    }
    

    BaseUnitTest 里加载 app-context.xml 等环境信息 现在报的错误是

    java.lang.NoSuchMethodException: wang.crick.jdtc.webservices.bag.BagApi.add()

  • 88250

    @crick77 用 Spring 和测试套件整合的方式,具体我不记得了,你加油

  • crick77  

    @88250

    • 是分开的, 成功标识是 “1”or “2” , msg 是信息
    • 我现在的想法是用 jedis 作一个模拟的 session 管理,生成 token 把用户信息存起来
  • crick77  

    @88250
    等我调通了把代码放出来, Spring 不同版本的差别现在已经这么大了么。。。。

    还想做接口调用次数及 ip 记录 和 可视化的 Web 端接口模拟参数调试

    看看我这一个月的通宵能做出来多少吧

  • 88250

    @crick77 加油加油,注意休息哈 ~

  • crick77  

    @88250

    报错是因为 HandlerMethod 没有指定入参类型
    指定之后 因为参数有@PathVariable 所以报错, 解决方法正在查找

    在思考 是通过 http 请求的方式单元测试 还是通过反射机制

  • 88250

    @crick77 最好是发 HTTP 请求,这样测试路径比较真实

  • muyuballs  

    @88250 社区的接口也应该参考一下 RESTFul 吧~~

  • 88250

    @Qiao 木已成舟了,只能慢慢改了....

  • Vanessa  

    楼主科普下呗,不用又忘记了

  • yangyujiao  

    貌似我们是第二种吧。。

  • crick77  

    @yangyujiao 入参第一种 返回第二种 这样比较靠谱

  • crick77  

    @88250
    调通了 之前是 spring3.1 利用 RequestMappingHandlerAdapter 通过反射 测试方法
    现在是 3.2.9 通过 MockMvc 模拟方法测试 MockMvc 开头的这几个类 封装的方法不错 够用了 测试用例完善一下 就可以赶赶任务了
    测试有时间的话 再写一篇 挺有意思的 4.0 之后的测试更简单

    public class BagApiTest extends BaseUnitTest {
    
    	@Autowired
    	private WebApplicationContext wac;
    
    	private MockMvc mockMvc;
    
    	@Before
    	public void setup() {
    		this.mockMvc = MockMvcBuilders.webAppContextSetup(this.wac).build();
    	}
    
    	@Test
    	public void addTest() throws Exception {
    
    		MockHttpServletRequestBuilder requestBuilder = MockMvcRequestBuilders.post("/api/1/bag/add.do");
    		requestBuilder.param("specId", GuidKeyGenerator.getUUIDKey());
    
    		ResultActions result = mockMvc.perform(requestBuilder);
    
    		MvcResult mvc = result.andExpect(MockMvcResultMatchers.status().isOk())
    //				.andDo(MockMvcResultMatchers.print())
    				.andReturn();
    
    		Map<String, Object> resultMap = mvc.getModelAndView().getModel();
    	}
    }
    
  • 88250

    @crick77 嗯多谢分享 ~

请输入回帖内容 ...