Chat
极客
故事
架构
友链
诸葛的博客

restful web 详解

2019/07/24

1.资源与描述

http协议语义，8种不同类型

  • GET 获取某个资源表述
  • DELETE 销毁某个资源
  • POST 基于给定的表述信息，在当前资源的下一级创建新的资源
  • PUT 用给定的表述信息替换资源当前状态
  • HEAD 获取服务器发送过来的报文信息
  • OPTIONS 获取这个资源所能响应的http方法列表
  • PATCH 根据提供的表述信息修改资源的部分状态
  • LINK 将其它资源链接到当前资源
  • UNLINK 销毁当前资源和其他某些资源的连接关系

2.接口的幂等性

  1. 安全性：不会改变资源状态，可以理解为只读的；
  2. 幂等性：执行1次和执行N次，对资源状态改变的效果是等价的。
  • GET， 第一次获取结果、第二次也是获取结果对资源都不会造成影响，幂等。
  • DELETE，第一次删除数据，第二次不在再删除，幂等。
  • POST，第一次新增数据，第二次也会再次新增，非幂等。
  • PUT， 第一次更新数据，第二次不会再次更新，幂等。
  • PATCH，第一次更新数据，第二次不会再次更新，非幂等。

如下图所示： ||安全性|幂等性| |:-|:-:|-:| |GET|√|√| |POST|×|×| |PUT|×|√| |DELETE|×|√|

3.状态码

  • 200 OK - [GET]：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。
  • 201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功。
  • 202 Accepted - [*]：表示一个请求已经进入后台排队（异步任务）
  • 204 NO CONTENT - [DELETE]：用户删除数据成功。
  • 400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。
  • 401 Unauthorized - [*]：表示用户没有权限（令牌、用户名、密码错误）。
  • 403 Forbidden - [*] 表示用户得到授权（与401错误相对），但是访问是被禁止的。
  • 404 NOT FOUND - [*]：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。
  • 406 Not Acceptable - [GET]：用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）。
  • 410 Gone -[GET]：用户请求的资源被永久删除，且不会再得到的。
  • 422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时，发生一个验证错误。
  • 500 INTERNAL SERVER ERROR - [*]：服务器发生错误，用户将无法判断发出的请求是否成功

4.URI规范

  1. 不用大写；
  2. 用中杠-不用下杠_；
  3. 参数列表要encode；
  4. URI中的名词表示资源集合，使用复数形式。

资源集合 vs 单个资源

URI表示资源的两种方式：资源集合、单个资源。

资源集合：

/zoos //所有动物园
/zoos/1/animals //id为1的动物园中的所有动物

单个资源：

/zoos/1 //id为1的动物园
/zoos/1;2;3 //id为1，2，3的动物园

避免层级过深的URI

/在url中表达层级，用于按实体关联关系进行对象导航，一般根据id导航。

过深的导航容易导致url膨胀，不易维护，如 GET /zoos/1/areas/3/animals/4，尽量使用查询参数代替路径中的实体导航，如GET /animals?zoo=1&area=3；

5.Request

GET：查询

GET /zoos
GET /zoos/1
GET /zoos/1/employees

POST：创建单个资源。POST一般向“资源集合”型uri发起

POST /animals  //新增动物
POST /zoos/1/employees //为id为1的动物园雇佣员工

PUT：更新单个资源（全量），客户端提供完整的更新后的资源。与之对应的是 PATCH，PATCH 负责部分更新，客户端提供要更新的那些字段。PUT/PATCH一般向“单个资源”型uri发起

PUT /animals/1
PUT /zoos/1

DELETE：删除

DELETE /zoos/1/employees/2
DELETE /zoos/1/employees/2;4;5
DELETE /zoos/1/animals  //删除id为1的动物园内的所有动物

6.复杂查询

|| 示例|备注| |:-|:-:|-:| |过滤条件 |?type=1&age=16|允许一定的uri冗余，如/zoos/1与/zoos?id=1| |排序|?sort=age,desc|| |投影 |?whitelist=id,name,email|| |分页|?limit=10&offset=3||

7.Response

  1. 不要包装： response 的 body 直接就是数据，不要做多余的包装。错误示例： 
    {
 "success":true,
 "data":{"id":1,"name":"xiaotuan"},
}

  2. 各HTTP方法成功处理后的数据格式： || response 格式| |:-|:-:| |GET|单个对象、集合| |POST|新增成功的对象| |PUT/PATCH|更新成功的对象| |DELETE|空|

  3. json格式的约定：
    1. 时间用长整形(毫秒数)，客户端自己按需解析（moment.js）
    2. 不传null字段

8.分页response

 {
    "paging":{"limit":10,"offset":0,"total":729},
    "data":[{},{},{}...]
}

9.错误处理

  1. 不要发生了错误但给2xx响应，
  2. 客户端可能会缓存成功的http请求；
  3. 正确设置http状态码，不要自定义； 对第三点的实现稍微多说一点：

Java 服务器端一般用异常表示 RESTful API 的错误。API 可能抛出两类异常：业务异常和非业务异常。业务异常由自己的业务代码抛出，表示一个用例的前置条件不满足、业务规则冲突等，比如参数校验不通过、权限校验失败。非业务类异常表示不在预期内的问题，通常由类库、框架抛出，或由于自己的代码逻辑错误导致，比如数据库连接失败、空指针异常、除0错误等等。

业务类异常必须提供2种信息：

  1. 如果抛出该类异常，HTTP 响应状态码应该设成什么；
  2. 异常的文本描述；

在Controller层使用统一的异常拦截器：

  1. 设置 HTTP 响应状态码：对业务类异常，用它指定的 HTTP code；对非业务类异常，统一500；
  2. Response Body的错误码：异常类名
  3. Response Body的错误描述：对业务类异常，用它指定的错误文本；对非业务类异常，线上可以统一文案如“服务器端错误，请稍后再试”，开发或测试环境中用异常的stacktrace，服务器端提供该行为的开关。

常用的http状态码及使用场景： |状态码|使用场景| |:-|:-:| |400 bad request|常用在参数校验| |401 unauthorized|未经验证的用户，常见于未登录。如果经过验证后依然没权限，应该 403（即 authentication 和 authorization 的区别）。| |403 forbidden |无权限| |404 not found|资源不存在| |500 internal server error |非业务类异常| |503 service unavaliable |由容器抛出，自己的代码不要抛这个异常|

10.API的演进

版本 常见的三种方式：

  1. 在uri中放版本信息：GET /v1/users/1
  2. Accept Header：Accept: application/json+v1
  3. 自定义 Header：X-Api-Version: 1

用第一种，虽然没有那么优雅，但最明显最方便。

11.URI失效

随着系统发展，总有一些API失效或者迁移，对失效的API，返回404 not found 或 410 gone；对迁移的API，返回 301 重定向。


（转载本站文章请注明作者和出处 诸葛的博客）

Show Disqus Comments

Post Directory