API 设计规范

说明

Restful 不是一种规范，而是一种风格，它不是强制性的，所以对于风格来说，大家观点都是不一致的，每个人设计出来的 Restful 风格的接口很难一样。

并且，对于实际的业务来说，越复杂的业务越难遵守这种风格，但是，对于一个团队来说，最忌讳的就是不统一！！！

这里强调统一性，是为了尽量设计出基于Restful风格的演进的API风格，某些特定场景下是可以不遵守的，比如，对于登陆/登出，怎么看都不认为它是一个资源，所以登陆接口大致设计成 /api/v1/users/login，这明显是不符合Restful风格的，但是我们不能说这是不正确的！

所以，以下规范应尽量遵守，找到一个API设计的平衡点！！！！

版本控制

版本控制主要用于 App、微信小程序、软件客户端等与系统不可同时实时更新的情况，来满足需要兼容旧版本的场景。
采用多版本并存，增量发布的方式。

版本号：v {n} n 代表版本号，分为整形和浮点型
整型：大功能版本发布形式；具有当前版本状态下的所有 API 接口，例如：v1,v2
浮点型：为小版本号，只具备补充 api 的功能，其他 api 都默认调用对应大版本号的 api 例如：v1.1 v2.2

将版本号放入 URL 中：
https://api.example.com/v{n}/
这种方法比较方便和直观，版本号主要以整型为主。
将版本号放在请求头（Request Headers）中

headers:{
    version: 'v{n}'
    ...
}

版本号可使用整型、浮点型等，这里我们选择使用第一种

URI 设计规范

参考：
https://blog.restcase.com/7-rules-for-rest-api-uri-design/
https://blog.restcase.com/5-basic-rest-api-design-guidelines/

在 URI 末尾不要出现斜杠 / 【强制】
在 URI 中使用斜杠/是表达层级关系（多级资源应使用斜杠 / 进行分割）【除特殊情况，否则强制】
在 URI 中可以使用连接符 - 来提升可读性。比如 http://xxx.com/xx-yy 比 http://xxx.com/xx_yy 的可读性更好。【强制】
在 URI 中不应出现下划线字符 _ 【强制】
在 URI 中尽量使用小写字母【强制】
在 URI 中不允许出现文件扩展名，比如接口为 /xxx/api ，不要写成 /xxx/api.json，这样是不合法的【强制】
在 URI 中资源名词使用复数形式【强制】
在 URI 中不能有动词，只能有名词，而且所用的名词往往与数据库的表名对应【除特殊情况，否则强制】

请求方式

对于资源的具体操作类型，由 HTTP 动词表示，此处强调：能利用 HTTP 动词的尽量利用！

说明：之所以说尽量，有时候遇到比如批量删除资源时或者批量修改资源时，我们可能会使用 POST 方式（新建一个接口）进行多个资源的参数传递！虽然违背了Restful风格，但是最终还是以实际项目需求为准！！！

常用的 HTTP 动词有以下五个：

GET：表示从服务器获取资源（一个或多个）
POST：表示在服务器新建一个资源
PUT：表示更新资源（客户端提供改变后的完整资源）
PATCH：表示更新资源中的某个数据（提供被更新的资源数据）
DELETE：表示从服务器删除资源

请求参数

地址栏参数

Restful 地址栏参数/api/v1/product/100 100 表示产品号，获取产品为 100 的详情
GET 方式的查询，此种方式主要用于过滤查询，规则如下：

?limit=10：指定返回记录的数量
?offset=10：指定返回记录的开始位置
?page=2&page_size=100：指定第几页，以及每页的记录数
?sort=name,desc&sort=type,asc：指定返回结果按照哪个属性排序，以及排序顺序，例如此处按name生序，type降序排序
?product_type=1：指定筛选条件，例如此处，产品类型为1

请求体 body 数据
主要用于提交新建数据等
请求头
用于存放请求格式信息、版本号、token 密钥、语言等信息

{
    Accept: 'application/json',     //json格式
    version: 'v1.0'                       //版本号
    Authorization: 'Bearer {access_token}',   //认证token
    language: 'zh'                      //语言
}

统一返回格式

{
    code: 0,                         //状态码
    msg: 'ok',                       //提示信息
    data: {}                          //主体数据
}

状态码

状态码分为：HTTP状态码，业务状态码

HTTP 状态码

使用合适的状态码很重要，不应该全部都是用 200 状态码来标识操作或返回的结果

常用状态码：

Code	描述
200	请求成功
201	正在处理该请求
302	重定向跳转
400	请求字段不合法
401	缺少调用凭证/身份认证失败
403	授权不通过
404	资源不存在
405	方法不支持
502	网关异常
504	网关超时

业务状态码

根据不同的系统或模块划分状态码，建议状态码保持 5 位数，从 10000 开始

非 Restful API 的需求

我们一般以 Restful API 作为接口的设计规范，但是实际业务开展过程中，可能会出现各种API不是简单的Restful规范就能够实现的，因此，需要有部分API打破Restful规范的原则，来优化或满足数据请求的交互。

组合型

服务端组装数据，然后返回：

把当前页面中需要用到的所有数据通过一个接口一次性返回全部数据，如 Dashboard 页面：

/api/v1/dashboard // 返回 Dashboard 所用到的所有数据

这类API有个非常不好的地方：只要业务需求变动，这个API的结构就需要跟着变更。

单例型

客户端根据需求分别请求对应API接口，在客户端完成数据组装。

这种模式服务端相对简单，接口复用率高

每个接口作用单一，如一个 Web 首页，可能有轮播图、分类、推荐商品，则需要分别请求：

/api/v1/banners //轮播
/api/v1/categories //分类
/api/v1/product?is_recommend=1 //商品

实际开发过程中可根据实际需要结合使用

目录CONTENT