restful api接口规范_开发实践：一份复杂业务系统的 RESTFul 接口规范

Flink 从入门到精通 系列文章

来源 | https://urlify.cn/JB3aAj

1. 从需求入手

• 对象：增删改查

• 对象列表：获取

• 对象的复杂处理：挖掘、整理、汇总

2. 资源分类

• 对象型：**/project/1

• 列表型：**/projects

• 算法型：**/project/search?input=**

3. 设计 URI

3.1. URI 命名

• 有意义的单词，全部小写

• 多个单词时，使用下划线分隔，设计良好的 URI 通常会避免多个单词

• 不推荐使用缩写

3.2. URI 结构

几点：

• 路径变量：表示层次结构

• 路径标点：表示非层次结构

3.2.1. 路径变量

id为8的deal的评论列表：

• /deal/8/comments

id为8的商家下第88条评论：

• /merchant/8/comment/88

上述通过实体关联关系进行路径导航，一般是 id 导航；如果实体之间关联层级过深，则，使用查询参数，替代路径层级导航。

• 路径层级：GET /zoo/1/area/2/animal/3

• 查询参数：GET /zoo/1?area=2&animal=3

组合实体的访问：必须通过父实体的 id导航访问。组合实体不是first-class的实体，它的生命周期完全依赖父实体，无法独立存在，在实现上通常是对数据库表中某些列的抽象，不直接对应表，也无id。

3.2.2. 路径标点

”.”表达不同的representation，约定 Response 返回的数据格式

• /deal/6.json

• /deal/8.xml

3.3. URI 对外暴露的方法

GET，获取服务器的资源：

• 安全性：服务器端响应 GET 请求并不会对服务器造成副作用

• 不要使用 GET 方法来修改服务器端的状态信息

POST，创建资源：

• 创建从属资源

• 客户端无法确定对应 URI

• POST 请求，不安全，也不是幂等的，因此，发布 POST 请求需要小心

备注：幂等，多次操作与只进行一次的效果相同。

PUT，创建资源和更新资源：

• 与 POST 创建资源的区别：客户端知道 URI，具有幂等性

• 在网络环境差的情况下，可将 POST 创建资源重构成 PUT 创建资源

DELETE，删除资源：

• 资源划分粒度要使得，删除资源不用带参数

• 具备幂等性

HTTP 请求返回码：

• 建议：HTTP 头部的返回码统一用200(OK)，具体状态在 body 中使用参数标识

• body 中返回码的值，与 HTTP 协议中返回码的值保持一致，便于大家统一理解

HTTP 常见状态码：

• 操作成功，2xx：200，ok；201，created

• Client Error，4xx：400，bad request；401，未授权；404，not found

• Server Error，5xx：500，internal server error

小结

REST，Representational States Transfer，表现层状态转化 & 有状态传输，本质上：REST 关注于资源，将所有的内容看做一个资源：图片、文本、计算，为每一个资源分配唯一的地址，并对这些资源进行规范的操作。

几个方面：

• 资源的地址：URI，URL(URI 是抽象，URL 是具体实现)

• 资源的形式：实体文件如：图片，文本，html，json。甚至一些算法及服务

• 对资源的操作：GETPOSTPUTDELETE

4. URL 补充

避免层级过深的 URL，/ 在 URL 中表示层级，按实体关联关系进行对象导航，通常是 id 导航。

过深的 URL 层级导航，容易造成 URL 迅速膨胀，例如：GET /zoo/1/area/2/animal/3，推荐使用查询参数，替代路径中的实体导航，例如：GET /zoo/1?area=2&animal=3

5. 请求及返回内容的规范

几点：

• json和xml对象的属性，必须 使用驼峰法命名：一个单词时全部小写，多个单词时第一个单词小写，后续的单词首字母大写；

• 单个对象：对象包含在 data 元素中{}；

• 多个对象：data 是一个 list[{},{},…]，paging 包含分页信息{offset,limit,total}

• 错误与异常：error 元素中，包含{code, type, message}

1. `// 单个对象`
2. `{`
3. `"data" : {`
4. `"bdId" : 8,`
5. `"bdName": "Rongjun