RESTful api设计风格
简介
REST（Representational State Transfer）：表象层状态转变
RESTful对api进行规范和约束，使得api统一规范，增强api的可读性，便于开发。
设计原则
1、每一个URI代表一种资源
2、客户端通过四个HTTP动词（get、post、put、delete），对服务器端资源进行操作
因此，这种风格的接口url中没有动词，而是通过四个HTTP动词（get、post、put、delete）来代表动作。
Http动词
分别对应四种基本操作：
- GET用来获取资源
- POST用来新建资源（也可以用于更新资源）
- PUT用来更新资源
- DELETE用来删除资源
具体实施
版本控制
如github开放平台的API：http://developer.github.com/v3/ 可以发现，一般的项目加版本v1，v2，v3版本号，为的是兼容一些老版本的接口，这个加版本估计只有大公司大项目才会去使用。
参数命名规范
query parameter可以采用驼峰命名法，也可以采用下划线命名的方式，推荐采用下划线命名的方式，据说后者比前者的识别度要高，其中，做前端开发基本都后后者，而做服务器接口开发基本用前者。
http://example.com/api/users/today_login 获取今天登陆的用户 http://example.com/api/users/today_login&sort=login_desc 获取今天登陆的用户、登陆时间降序排列
url命名规范
API 命名应该采用约定俗成的方式，保持简洁明了。在RESTful架构中，每个url代表一种资源，所以url中不能有动词，只能有名词，并且名词中也应该使用复数。实现者应使用相应的Http动词GET、POST、PUT、PATCH、DELETE、HEAD来操作这些资源即可
不规范的的url，冗余没有意义，形式不固定，不同的开发者还需要了解文档才能调用。
http://example.com/api/getallUsers //GET 获取所有用户 http://example.com/api/getuser/1 //GET 获取标识为1用户信息 http://example.com/api/user/delete/1 //GET/POST 删除标识为1用户信息 http://example.com/api/updateUser/1 //POST 更新标识为1用户信息 http://example.com/api/User/add //POST添加新的用户
规范后的RESTful风格的url，形式固定，可读性强，根据users名词和http动词就可以操作这些资源。名词可以使用驼峰命令或者"_"分割
http://example.com/api/users //GET 获取所有用户信息 http://example.com/api/users/1 //GET 获取标识为1用户信息 http://example.com/api/users/1 //DELETE 删除标识为1用户信息 http://example.com/api/users/1 //Patch 更新标识为1用户部分信息,包含在div中 http://example.com/api/users //POST 添加新的用户
统一返回数据格式
对于合法的请求应该返回统一的数据格式，对于返回数据，通常会包含如下字段。
- code——即一个整数类型的HTTP响应状态码。
- message——即返回给前端的信息，正常返回时是"success"，当值为 "fail" 或 "error" 时，用于显示错误信息。
- data——即前端需要返回的数据。 当值为 "fail" 或 "error" 时，设置为null。
返回成功的响应json格式：
{
"code": 200,
"message": "success",
"data": {
"name": "小明",
"age": 16,
"sex": 0
}
}
返回失败的响应json格式：
{
"code": 401,
"message": "error message",
"data": null
}
http状态码
2**：成功–表示请求已被成功接收。
200（成功）用浏览器打开一个网页，正常情况下都会返回200HTTP状态码。
201（创建成功）代表资源创建成功
3**：重定向（URL跳转），要完成请求必须进行更进一步的操作。
300（多种选择）下载一部片，服务器有 avi、mp4 等格式。
301（永久移动）请求的网页已永久移动到新位置，自动将请求者转到新位置。
304 (页面未修改) ：按F5刷新（第二次访问）。
4**：客户端错误，请求有语法错误或请求无法实现。
400（错误请求）服务器不理解请求的语法。
401（未授权）没有携带认证信息或携带了错误的认证信息，而没有通过认证。（未登录时）
403（禁止）携带了正确的认证信息，服务器认为该用户对该资源无权访问。(https输成了http)
404（未找到）请求的内容不存在。
5**：服务器端错误，服务器未能实现合法的请求。
500（服务器内部错误）服务器自己出现错误。
502（网关错误）服务器作为网关或代理，从上游服务器收到无效响应。
503（服务器不可用）服务器超载或停机维护不可用。
查询参数
在请求数据时，客户端经常会对数据进行过滤和分页等要求，而这些参数推荐采用HTTP Query Parameter的方式实现。
//搜索用户，最近登录 http://example.com/api/users?recently_login_day=3 //搜索用户，按照注册时间降序 http://example.com/api/users?sort=register_time_desc //搜索用户，按照注册时间升序、活跃度降序 http://example.com/api/users?sort=register_time_asc,liveness_desc
复杂参数
xxx
后端案例
GET请求
## url路径传参1
http://localhost:8080/api/user?id=1
后端要获取code参数，可以使用@RequestParam注解
## url路径参数2
http://localhost:8080/api/user/1
后端使用@PathVariable可以接收路径参数1。
POST请求
## Headers传值
在这里我们把Content-Type设置为了json格式。
我们还可以在headers里面加入别的参数，比如token。
后端可以通过HttpServletRequest获取请求头的内容，如：
request.getHeader(string name)
request.getHeaders(String name)
request.getHeaderNames()
### Body传值
一般来说，使用json格式传值，如下图：
后端接受这种数据应该采用@RequestBody
@PostMapping(value = "/user")
public ApiResult addUser(@RequestBody UserDTO userDTO) {
return userService.add(userDTO);
}
