说明：

公司项目中前后端分离项目越来越多。因此，必须有一种统一的机制，方便不同的前端项目与后端进行通信。这导致API构架的流行，甚至出现”APIFirst”的设计思想。所以为规范接口提出以下原则。

所有接口代码编写完成必须测试，且需测试多个边界条件

所有接口出参，数据类型必须与接口文档一致

一、 【强制】 协议使用HTTPS

• API与用户的通信协议，总是使用HTTPs协议，确保交互数据的传输安全。

二、 【推荐】 域名

• [x] 应该尽量将API部署在专用域名之下。

例：https://api.example.com

• [x] 如果确定API很简单，不会有进一步扩展，可以考虑放在主域名下。

例： https://example.org/api/

三、 【强制】 URL规范

1. 页面级的api：把当前页面中需要用到的所有数据通过一个接口一次性返回全部数据
2. 列表中存在搜索条件分为两个接口（分为搜索条件接口及列表数据接口）
3. 迭代接口可使用v1 v2区分版本 目前主要使用在对外接口与APP接口
4. 访问接口可以 域名/v1/列表规则 以 “/”隔开访问接口链接

四、 【强制】 参数（出参和入参）

• 全部为小写，多个单词用下划线分隔

五、【强制】请求加密参数

1. 登录成功后返回加密信息token给前端，后续接口需在header的Authorization字段传递给后台验证。
2. Token加密方式查看响呗超管后台或B2C超管后台

六、 【强制】 常用字段规范

备注：其他自行翻译，遇到统一补充到文档

七、 【强制】 统一响应数据格式

1. 返回数据时只返回接口需要数据，其余数据去除
2. 数据字段格式确定后所有接口需统一返回

返回字段：

'code' => 状态码
'message' => 返回消息，当状态码500时提示错误使用该字段，当状态码200时提示成功使用该字段
'data' => 数据
'error' => 错误信息, 当状态码为400时，行下提示错误使用该字段，格式为
[
    {
        field => 字段名,
        msg => 错误消息
    },
    {
        field => 字段名1,
        msg => 错误消息
    }
]
相同字段名，添加多个情况时返回错误信息：
 [
    {
        field => name,
        msg => '请输入符合要求的名称'
        index => 0
    },
    {
        field => name,
        msg => '请输入符合要求的名称'
        index => 1
    }
]

返回数据字段格式：

列表：list
详情：info
比如状态列表：status_list
例如：
列表
[
    'code' => 204,
    'message' => 项目列表,
    'data' => [
        list => [],
        status_list => []
    ],
    'error' => [],
];
详情
[
    'code' => 204,
    'message' => 项目详情,
    'data' => [
        info => [],
        status_list => [],
        type_list => [],
    ],
    'error' => [],
];

八、 【强制】 响应状态码

具体举例：

九、 【推荐】 安全

1. 安全性：不会改变资源状态，可以理解为只读的；
2. 幂等性：执行1次和执行N次，对资源状态改变的效果是等价的。
3. IP白名单：ip白名单是指将接口的访问权限对部分ip进行开放
4. IP限流：限流是为了更好的维护系统稳定性。使用redis进行接口调用次数统计，ip+接口地址作为key，访问次数作为value，每次请求value+1，设置过期时长来限制接口的调用频率。
5. 请求日志：使用aop全局记录请求日志，快速定位异常请求位置，排查问题原因。
6. 敏感数据脱敏：在接口调用过程中，可能会涉及到订单号等敏感数据，这类数据通常需要脱敏处理，最常用的方式就是加密。加密方式使用安全性比较高的RSA非对称加密。非对称加密算法有两个密钥，这两个密钥完全不同但又完全匹配。只有使用匹配的一对公钥和私钥，才能完成对明文的加密和解密过程。