实战 - Restful APi 格式规范

RESTful是一种API的设计风格，他和GraphQL ，JSON-RPC，WebService类似，用于定义在CS、BS架构下暴露服务端接口。此次设计对接规范，将使用RESTful作为标准。

1. 特征

RESTful风格的特点是：

① URI资源化：

即，URI代表的是资源，而不包含动作。比如，一个班级，有很多学生，我们可以这样表示：/class/students

② 动作由HTTP头里的方法决定：

比如，我们想新增一个学生，我们可以用POST方法：

POST /class/students
{"name": "Jake","age" : 18
}

我们想查看当前有哪些学生，可以用GET方法：

GET /class/students

我们想查看某学生的具体信息，可以用路径指定到某一个ID：

GET /class/students/1

我们想要开除id为1的学生，可以用DELETE方法：

DELETE /class/students/1

HTTP头里面的方法决定了动作后，后端实现也应该严格根据动作来，比如，GET请求不应该对数据造成任何更改，如此，我们对权限控制便非常方便，例如，如果是访客，我们可以只开放GET方法，而对于ADMIN，我们可以开放GET,POST,DELETE等方法。

大多数就是做CRUD，用HTTP头部动作，可以很好满足。

③ 资源的表现由Content-Type决定：

HTTP请求的头信息中Accept和Content-Type字段，是对资源的表现描述。例如，指定是JSON格式，还是HTML格式。

④ 无状态：

无状态是指客户端无状态，例如，你不应该在客户端使用类似的逻辑：

if (hasStudent("Jake")) {getStudentInfo("Jake");
}

因为，hasStudent和getStudentInfo调用之间，可能别人已经将Jake删除了，你的状态维护不一定准确。 你可以直接getStudentInfo(“Jake”)，没有则返回失败即可。 服务端可以维护一些状态，但最好不要维护太多，例如，HTTP登录状态，是应该维护的，但是，记录并强制要求用户A是否请求过某个URL再请求另一个URL，这种设计就不应该了。

⑤ 数据安全：

使用HTTPS协议，加密数据。

我们对接统一采用RESTful方式的HTTPS（为了加密）请求，内容为JSON格式，其中，安全、幂等性、无状态之类的约束，请产品线严格按照Restful规定设计。

2. 优点

① 减少沟通成本：

API是开放给别人使用的，由于有既有的约定，会让沟通成本大大减少，这是API提供者最应该考虑的。

② 能够接纳多种客户端(适用于大多数CS BS架构程序)：

不止是web程序，基本上的CS架构程序，都可以使用RESTful提供API，这样，不论是WEB Client还是Windows APP还是，Mobile APP，都可以轻松使用服务端的API。

③ 思维方式转换为以资源为中心：

传统的方式是以操作为中心，例如create_user, query_students。

类似于面向对象以对象为中心，RESTful推崇以资源为中心，说不上绝对好，但的确会引导大家考虑资源本身，关注内聚性，关注权限，关注资源间关联。

④ 扩展方便：

无状态设计对横向扩展非常方便，因为API之间解耦比较好，资源解耦也比较好。 还有一个叫 hypertext-driven 的东西，类似于自描述，但是用起来也不方便，在CodeReview工具提供的API便是这种方式，优点是服务端可以随意更换URL，缺点是请求前要去查询一下该请求什么路径。例如github的参考https://api.github.com/

⑤ 建立在HTTP协议基础之上：

HTTP协议里面规定的东西很多，例如，缓存，压缩，代理，加密，穿透，等等，都已经让HTTP帮忙完成了，给很多实现减负。

3. 动作

1. GET 获取资源

举例：获取学生Jake的信息。

GET /class/students?name="Jake"

2. POST 创建资源

创建资源，不会指定资源ID，但创建完成后，通常会返回资源的ID，这样后续可以通过资源ID操作此资源。

举例：创建学生。

POST /class/students
{"name": "Jake", "age" : 18, "score": 0}

3. PUT 整体替换

为了定位资源，要求路径上有资源的唯一ID。

举例：替换ID为2的学生的信息为如下新信息。

PUT /class/students/2 
{"name": "Jim","age": 19}# 此操作将原本ID为2的学生的所有属性冲掉了，替换后，ID为2的学生整体内部数据结构变为：
{"id": 2, "name": "Jim","age": 19}

异常：

① 如果Playload为空，返回失败。

② 如果Playload为{}，是正确的，表示清空（重置），例如上述示例内部数据结构将变为：{“id”: 2}

4. PATCH 部分替换

为了定位资源，要求路径上有资源的唯一ID。

举例：更新ID为2的学生的年龄从之前的18岁更新为20岁。

PATCH /class/students/2 
{"age": 20}# 这里，ID为2的学生的其他属性保留，整体内部数据结构变成：
{"id": 2, "name": "Jake", "age" : 20, "score": 0}

异常：

① 如果Playload为空或{}，返回失败。

② 对于嵌套的结构，如果是正常书写，表示整体替换；如果是点分结构，表示部分更新。

比如：

{"id": 2, "name": "Jake", "age" : 20, "score": {"English": 86, "Chinese":88, "math":99}}

子结构更新：

PATCH /class/students/2
{"score": {"math":100}}# 替换后为：
{"id": 2, "name": "Jake", "age" : 20, "score": {"math":100}}

子结构更新：

PATCH /class/students/2
{"score.math": 100}# 替换后为：
{"id": 2, "name": "Jake", "age" : 20, "score": {"English": 86, "Chinese":88, "math":100}}

③ 对于数组，标准用法是表示整体替换，而不能增删。

比如：

{"id": 2, "name":"Jake", "friends": ["Jim", "Marry", "Jake"]}

执行整体替换：

PATCH /class/students/2
{"friends": ["Bob"]}# 替换后为：
{"id": 2, "name":"Jake", "friends": ["Bob"]}

为了支持增加和删除功能，我们在URL参数上，附带_arrayop=[add,remove]，用于表示增删数组。

例如：

{"id": 2, "name":"Jake", "friends": ["Jim", "Marry", "Jake"]}

PATCH /class/students/2?_arrayop=add
{"friends": ["Bob"]}# 增加后为：
{"id": 2, "name":"Jake", "friends": ["Jim", "Marry", "Jake", "Bob"]}

PATCH /class/students/2?_arrayop=remove
{"friends": ["Jim"]}# 删除后为：
{"id": 2, "name":"Jake", "friends": ["Marry", "Jake"]}

这种做法的缺陷是，一个_arrayop控制了整个Playload的array动作，所以，同一Playload如果需要多种动作的情况，请拆分为多次请求。

5. DELETE 删除资源

DELETE里面能不能带payload，这个RFC 7231 "Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content"是这么规定的：A payload within a DELETE request message has no defined semantics; sending a payload body on a DELETE request might cause some existing implementations to reject the request.

所以，并没有禁止，是否支持依赖于服务端实现，比如某些版本的Tomcat或 Jetty就会忽略payload。

而OpenAPI3.0定义里面描述为：

The request body applicable for this operation. The requestBody is only supported in HTTP methods where the HTTP 1.1 specification RFC7231 has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody SHALL be ignored by consumers.

说明，对OpenAPI规范而言，这种模棱两可的描述，是明确要ignored的。

经过我们的实践，发现DELETE带payload需求很多，所以，我们明确一下，支持DELETE带payload的行为，假如遇到实现不支持时，请使用DELETE Over POST实现。

举例：

删除ID为2的学生。

DELETE /class/students/2

删除有Jim这个朋友的所有学生。

DELETE /class/students
{"friends": ["Jim"]}

或表达为DELETE Over POST：

POST /class/students?_method=DELETE
{"friends": ["Jim"]}

4. 示例

@AllArgsConstructor
@Data
public class Person {private String id;private String name;private int age;
}

@RequestMapping("/api/v1/user")
@RestController
public class UserController {@PostMappingpublic String insertUser( @Validated @RequestBody Person person){System.out.println(person);return "person";}@DeleteMappingpublic String deleteUser(@Validated @RequestBody Person person){System.out.println(person);return "person";}
}

@RequestMapping("/api/v1/user")
@RestController
public class UserController {@PatchMappingpublic String updateUser(@Validated @RequestBody List<String> ids){System.out.println(ids);return "person";}@DeleteMappingpublic String deleteUser(@Validated @RequestBody List<String> ids){System.out.println(ids);return "person";}
}