软件研发接口API规范

说明：

公司项目中前后端分离项目越来越多。因此，必须有一种统一的机制，方便不同的前端项目与后端进行通信。这导致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/列表规则 以 "/"隔开访问接口链接

路由名称	说明
xxx_list	列表
xxx_add	添加
xxx_add_post	添加提交
xxx_edit	修改
xxx_edit_post	修改提交
xxx_info	详情
xxx_delete	删除
xxx_search	搜索结果

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

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

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

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

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

参数名	类型	说明
id	int	主键
table_name_id	int	外键
name	sting	名称
description	sting	描述
content	sting	内容
seo_title	sting	SEO标题
seo_keywords	sting	SEO关键词
seo_description	sting	SEO描述
status	int	状态
list_order	int	排序
type	int	类型
create_time	int	添加时间
update_time	int	修改时间
page	int	页码
limit	int	每页多少条

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

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

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' => [],
];

八、 【强制】 响应状态码

分类	描述
1xx	信息，服务器收到请求，需要请求者继续执行操作
2xx	成功
3xx	重定向，需要进一步的操作以完成请求
4xx	客户端错误，请求包含语法错误或无法完成请求
5xx	服务端错误

具体举例：

状态码	描述
200	成功弹框提示（涉及数据添加、修改、删除等提交的操作）
201	成功确认弹框状态码
204	成功不提示（仅用于获取数据）
301	成功不提示（仅用于获取数据）
302	暂时重定向
400	错误行下提示（提交的表单数据验证未通过情况使用）
401	未登录（未授权）
403	没有权限
500	错误弹框提示（添加、修改、删除等提交操作失败 & 参数错误 & 数据验证不允许执行该操作）

九、 【推荐】 安全

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

	安全性	幂等性
GET	√	√
POST	×	×
PUT	×	√
GDELETEET	×	√