0%

研发规约-RESTful接口约定

Posted on 2021-01-05

RESTful风格简介

定义

REST = REpresentational State Transfer = 表现层状态转移

REST描述的是在网络中Client/Server的一种交互风格，并非强制性规范。

名词&资源

URL中只使用名词来指定资源，原则上不使用动词，“资源”是REST的核心。

例如: http://localhost/profiles/1 获取个人资料

动词&操作

用HTTP协议里的动词来实现资源的添加，修改，删除等操作。

GET 用来获取资源
POST 新建资源
PUT 更新资源
DELETE 删除资源

例如:

DELETE http://localhost/friends/1 删除好友
POST http://localhost/friends/1 添加好友
UPDATE http://localhost/profiles/1 更新个人资料

状态&结果

用HTTP Status Code传递Server的状态信息。例如200表示成功，500表示服务器内部错误等。

RESTful接口约定

命名规则

举例:
http://ip:port/{domain}/{service_name}/{version}/{api_name}?{pathparam}={somevalue}&{pathparam}={somevalue}
http://10.161.66.60/act/resourceremain/v1/resources?serialNumber=18601969575&netTypeCode=50&xAcceptMode=2

{domain}：服务所属域信息，如act。小型工程可省略。
{service_name}：服务名，如resourceremain。小型工程可省略。
{version}: API版本号，如v1。小型工程可省略。
{api_name}: 接口名称，如resources。

说明:

URL中字母都是小写。
每个URL代表一种资源，URL不能有动词，只能是名词。如show，get，update，query，delete等不能出现在URL中。
利用HTTP请求的动词表示对资源操作的行为。
对于资源的描述的名词应该是层级嵌套的方式，比如/companys/departments/projects。通过这种对于信息层级描述的方式，更利于实体的抽象。
路径终点的命名使用复数形式，比如/books。一般一个URL路径表示的资源会映射为数据库一系列表的记录的集合，因此使用复数更直观。

HTTP方法

对于资源的具体操作类型，由HTTP动词表示，常用的HTTP动词有下面五个:

GET方法从服务器取出资源(一项或多项)
POST方法在服务器新建一个资源
PUT方法在服务器更新资源（客户端提供改变后的完整资源）
PATCH方法在服务器更新资源（客户端提供改变的属性）
DELETE方法从服务器删除资源

示例:

GET /books：列出所有书
POST /books：新建一个书
GET /books/{id} 获取某本书的信息
PUT /books/{id} 更新某本书的信息（提供该书的全部属性）
PUT /books/{id} 更新某本书的信息（仅提供该书需要改变的属性）
DELETE /books/{id} 删除某个书
GET /books/{id}/notes 列出本书的所有笔记
DELETE /books/{id}/notes/{id} 删除某本书的某条笔记

过滤信息

如果记录数量很多，API应该提供参数，过滤返回结果。参数名仅做参考。

?limit=10：指定返回记录的数量
?offset=10：指定返回记录的开始位置。
?page=2&per_page=100：指定第几页，以及每页的记录数。
?start_size&file_size：指定请求的起始条数，以及请求记录条数。
?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
?animal_type_id=1：指定筛选条件。

参数的设计允许存在冗余，即允许API路径和URL参数偶尔有重复。比如，GET /zoo/ID/animals 与 GET /animals?zoo_id=ID 的含义是相同的。

状态码

服务器向用户返回的状态码和提示信息，常见的有以下一些:

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格式）。
408 REQUEST_TIMEOUT - 请求超时
409 CONFLICT - 冲突，大部分业务异常可以选择使用此状态
410 Gone -[GET]：用户请求的资源被永久删除，且不会再得到的。
422 Unprocesable entity - [POST/PUT/PATCH]：当创建一个对象时，发生一个验证错误。
500 INTERNAL SERVER ERROR - [ * ]：服务器发生错误，用户将无法判断发出的请求是否成功。

成功&异常处理

2XX

状态码200/201，表示成功。响应报文中，直接返回业务信息，不需要添加冗余的code/message等表示状态字段。例如:

{
    "name": "1.docx",
    "path": "/tmp/1.docx"
}

状态码204，表示成功，且不需要返回任何信息。响应报文为空即可。

公司框架中，响应报文强制包含状态信息，可无视以本条约定

4XX

状态码是4xx，表示普通的业务异常。应向用户返回出错信息。例如:

{
    "code" "9999",
    "message": "可向用户展示的错误信息",
    "devMessage": "更详细报错信息，用于前端调试"
}

所有可捕获的业务异常，都应该使用4xx来表示，具体分类细节可自由定义。常用的错误码有:

404 NOT_FOUND
408 REQUEST_TIMEOUT
409 CONFLICT
422 UNPROCESSABLE_ENTITY

5XX

状态码5xx，表示服务内部异常。如服务积压、数据库连接异常等。

此类异常应在框架的公共异常处理部分统一处理，业务代码中无须进行实现。

一般统一归类到500 INTERNAL SERVER ERROR 下即可。