restfulAPI规范

每个公司都应该制定技术规范，规范并不是只有一个标准，制定一套适用于自己团队的规范，每个人严格遵循，在开发效率和角色备份上会有很大的提升。

一、请求方法 :

使用HTTP的方法（POST , DELETE , PUT , GET）来代表资源的增删改查，并使用HTTP状态码来代表不同的结果。

二、接口要求：

接口需要做认证。
接口需要无状态，不能依赖于会话（session）

三、统一前缀：

推荐接口都以/api开头，便于统一处理。

四、分页及排序：

在URL中增加pageSize和pageNum参数用于分页。
在URL中增加sort参数用于排序，默认正序，带-表示倒序。比如：/api/v1/users?sort=-create_user,create_time 代表create_user倒序，create_time正序。
返回的分页数据中，在响应全中，包含如下元素：
        pageSize(和请求值一样)
        pageNum(和请求值一样)
        total（能查出的总记录数）,注：total非必须，可以不传，以提高性能。
        data（此次分页的数据）

五、请求体(Request body)：

文件上传采用multipart/form-data格式。
其它请求均采用application/json格式，不得使用application/x-www-form-urlencoded

六、响应状态码（Response status）：

如无必要，勿增实体。凡是HTTP Response Status能表述的，均使用HTTP的响应状态码。

- 200 : 请求成功，响应体中带有资源的数据。
- 201 : 资源创建成功。
- 202 : 请求已接收。对于耗时较长的需要后台异步处理的，服务在接收请求后，返回202。
- 204 : 响应中无内容。通常是在执行PUT、POST、DELETE后，不返回资源的内容。

- 301 : 如果接口废弃，迁移到新接口中，可以返回301重定向。
- 304 : 资源未修改。和204一样，在响应体中不会带有内容，其区别在于如果针对请求头中的If-Modified-Since或者If-None-Match指定的版本，资源没有修改，则返回304。

- 400 ： 错误请求。通用的客户端错误状态码。通常是由于参数不正确。
- 401 ： 未授权。客户端未能提供有效的认证信息。
- 403 ： 请求被拒绝。客户端已经认证成功，但是无权访问该资源。
- 404 ： 资源不存在。
- 410 ： 如果接口永久废弃不用，可返回410。请慎用。
- 429 ： 请求次数超限。

- 500 ： 服务器内部错误

七、响应头（Response headers）

Content-Type需要与数据保持一致，POJO类的数据统一采用application/json;charset=UTF-8做Content-Type。

八、响应体（Response body）

除文件下载外，响应体均采用JSON格式，JSON不要进行格式化。针对4XX错误和5XX错误，需要提供有供的信息，格式如下：

{
  "code":"",
  "message":""
}

九、认证

外部系统（服务）调用接口时采用oauth2.0的client_credentials方式进行认证。

最后编辑于：2020.07.17 16:39:26