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);
}