前端接口审查标准
以下前端接口审查标准，由前端组长编写。
基础评审标准
新增接口用 post 请求，不是 get 请求
分页接口
分页接口遵循以下严格的规范。
分页接口必须是 get 请求
必须统一为 get 请求，不要乱搞别的请求类型。
该接口不应该是 post 请求
分页接口请求的页码和页数仅为 pageIndex 和 pageSize
按照规范，仅为pageIndex和pageSize，两个名称。
分页接口的 pageIndex 和 pageSize 必须设计成必填项
分页接口必须要求前端上传明确的页码和页数。如果前端没有提供页码和页数，那么后端的分页接口应该主动报 400 错误，要求前端补全分页字段。
提供必填校验的正确接口
未提供参数校验的错误接口
分页列表页返回值必须为 PageDTO
必须严格套模板，返回为 PageDTO ，否则数据结构不统一。影响开发进度。
不允许私自新建规范外的变量
分页接口统一的变量仅为 pageIndex 和 pageSize，不允许新建其他多余的 pageNum。
不允许对规范内的变量改名
返回值必须被 JsonVO 包裹
常见的业务接口必须满足该规范
任何接口都必须用 JsonVO 泛型包装。否则前端无法得知业务处理吗 code 的状态。无法得知业务是否是 10000，是业务正常还是失败。
其返回值格式必须是code、message、data的格式。
文件接口不需要遵守该规范
比如接口向前端返回文件时，就不需要满足该规范。
字段命名
接口路由命名
一会小驼峰：
小驼峰
一会又是短杆加大驼峰：
短杆加大驼峰
这样的接口路由命名肯定是不合适的，要求他们统一接口命名风格。
变量名应该统一为小驼峰
按照后端规范，其接口的变量名必须为小驼峰，不能直接用下划线划分。
下划线划分的接口
变量名称注释
变量名称注释缺漏，不清楚，语义化不强。
缺漏变量注释
变量只有纯英文注释，等于没有注释
缺漏字段
接口没有提供相应的字段实现功能。比如以下的接口，按照原型是要求上传用户的身份证号的。
原型要求上传身份证号
接口缺漏身份证号
没有提供身份证号字段，无法满足业务需求。
变量没有提供明确的枚举值
比如各种类型变量。比如用户类型、派工类型。
workOrderType，派工类型。在数据库内存储的值为：
- 1001 按日派工
- 2002 按周派工
- 3003 按月派工
那么后端的注释，就应该包含上述的映射关系。包含【取值-文本】的映射关系。
如果该变量的注释没有提供该映射关系，那么前端在对接字段时，不得不询问后端workOrderType派工类型的取值是如何映射的，前端如何显示出来。会产生额外的沟通成本
查询信息类的接口必须提供额外的文本字段
继续以workOrderType派工类型为例子。
比如以下种类的后端接口：
- 分页列表接口
- 根据 id 查询信息接口
- 查询全部列表接口（下拉列表用）
- 查询某某树的接口
像这一类接口，都必须提供一个额外的字段。用于给前端展示出来。
比如，根据 id 查询信息接口，按照该要求应该返回以下数据：
{
"workOrderType": "1001",
"workOrderTypeText": "按日派工"
}比如，分页列表接口，应该返回：
[
{
"someOne": "用户甲",
"workOrderType": "1001",
"workOrderTypeText": "按日派工"
},
{
"someOne": "用户乙",
"workOrderType": "3003",
"workOrderTypeText": "按月派工"
}
]前端不做文本翻译，整个文本翻译的过程全权交给后端，前端不应该额外地在本地存储一套文本翻译数据。否则容易出现数据更新不及时的错误，给生产环境的业主带来误解，让产品经理容易挨骂。
数据写入类接口不应该接受纯文本
比如上述workOrderType派工类型字段，以下的类型的接口属于写入写表类的接口：
- 新增接口
- 修改接口
这两类接口属于写表的接口。前端在传递workOrderType时，不可能也不应该传递中文文本。后端在存储时，也不应该去存储中文文本，应该存储 1001、2002、3003 这样的值。
不要额外存储中文字段
真正有意义的业务变量，是workOrderType，不是workOrderTypeText。workOrderTypeText是给前端展示用的，后端不应该存储，更不应该在数据库表内新建一个专门的字段来存储该中文文本。
删除接口需要传递的业务 id 必须是必填项
绝大多数的删除接口，都必须要传递有意义的业务 id，并且该业务 id 必须设置成必填项，且要求校验。
详情
比如以下例子，删除物业公司，只需要传递唯一一个storeId物业公司 ID 就行了，其他字段都是多余的。
且该 id 必须是必填项。前端不能漏传，后端必须主动校验。
业务评审
视情况而定。具体业务具体分析。
apifox 的进阶使用
评论接口功能
设置接口状态
根据状态筛选接口
历史教程
以下是上一次项目的参考教程：
贡献者
ruan-cat