apifox接口审查，并用cursor生成接口

写在前面

该文档内容是根据阮喵喵组长讲解的接口审查做的笔记

接口审查

接口审查核心

通过Apifox文档对后端提供的接口进行审查

难点在对业务的理解程度，需要一定的开发经验

最终要确保这个接口能够充分地满足业务需求，核对双方的业务理解，后端的业务理解比前端的业务理解要深刻，前端对接口进行审查也是验证自己的业务理解

我负责j3组关于“缓存管理”，“商户管理”和“报表配置”的接口
组长把我放到了后端j3组群，有问题直接开会议和他们面对面
结合需求文档、原型、接口审查

与后端沟通规范

找到你的接口；修改接口的状态，修改为有异常；点击评论按钮；对接口做出评论，如果他们改完，我们前端再在评论那边标记为已解决。

基础评审标准

新增接口用post请求，不是get请求

分页接口

页面中的绝大多数请求都是分页接口

1. 分页接口必须是get请求
2. 分页接口有自己的一套规范:
   分页接口请求的页码和页数仅为pageIndex和pageSize两个名称，这些后端也是套模板，如果他们中间穿插其他变量，那么前端套模板的时候这里接口是跑不起来的
   pageIndex和pageSize一定为必填项，如果前端没传，那么后端的分页接口应该主动报400错误，后端本来应该对前端传入的任何值做校验
3. 如果后端返回的数据没有总条数和总页数，那么前端无法渲染出总数

返回值必须被JsonVO包裹

任何接口都必须用 JsonVO 泛型包装。否则前端无法得知业务处理吗code的状态。无法得知业务是否是10000，是业务正常还是失败。
常见的业务接口必须满足该规范，几乎所有的接口数据结构返回值都是code,data,message三个字段

字段命名

1. 接口路由命名：
   可以小驼峰，不能要离谱的（比如一会儿短杆一会儿大驼峰）
   其返回值格式必须是code、message、data的格式。
2. 变量名应该统一为小驼峰
   按照后端规范，其接口的变量名必须为小驼峰，不能直接用下划线划分。
3. 变量名称注释
   如果注解缺漏、不清楚、语义化不强（那么前端理解起来很费劲，到时候去群里面问他们，前端费劲，后端也不爽），要让他们改
   变量只有纯英文注解，如有注解，就等于没有注解
4. 文件接口不需要遵守该规范
   比如接口向前端返回文件时，就不需要满足该规范。

缺漏字段（重头戏）

每一个字段都要对，接口没有提供相应的字段实现功能，那么后续无法实现

变量要设计成枚举，提供具体的中文值

应该做成下面这种

固定选项参数

业务中下拉菜单–固定选项这种样式，在接口文档应该怎么体现呢？（检查记录12条、17条有图片）

组长回答：要求他们自己把对应关系写出来，写在注释内。写到apifox的文档内
比如各种类型变量。比如用户类型、派工类型
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是给前端展示用的，后端不应该存储，更不应该在数据库表内新建一个专门的字段来存储该中文文本。

基础评审–我的检查记录

审查步骤：打开我的负责的需求图，跑项目原型，挨个对接口文档，查看接口的路由、请求参数、返回data、业务逻辑
发现好多问题哦，接口文档已进行“有异常”标记和评论区评论，部分截图记录如下：

小结：已检查“缓存管理”和“报表配置”两部分的所有接口，脑图标记应为24个，实际对照应为25个，接口文档有24个，其中有问题的为20个

1. 分页请求参数命名错误
   

2. 接口重复
   

3. 组ID命名不统一
   

4. (我的理解问题，后端接口没问题)
   有疑问，接口请求可以没有请求参数吗
   可以的，这个接口是下拉菜单获取子项的时候调用，不需要请求参数
   

5. 参数必填；实例值不对
   （1）queryModel查询方式应该为枚举类型，但是本文档没有注明
   （2）不理解字段 ：componentId组件id，该组件还未添加，组件id指的是什么呢，请详细说明
   

6. 针对数据的查询，数据编号应该为必填（报表配置-报表信息）
   

7. 返回数据data和所需不匹配（报表配置-报表信息–关联组件）
   (1) 接口命名没有指出为分页接口，和脑图不一样
   (2) 按照业务需求，报表编号customId应该为必填
   (3) 分页参数命名不符合规范pageQuery.pageIndex ；pageQuery.pageSize
   (4) 返回值没有按照pageDTO包裹

下图命名问题

8. 删除接口，请求参数全是可选（报表配置–报表信息–删除关联组件）

9. 删除参数，请求应为必须（报表配置–报表信息–删除报表信息）

10. 修改请求参数，修改对象id应为必填（报表配置–报表信息–修改报表信息）

11. 报表添加关联组件（报表配置-报表信息–关联组件–添加关联组件）
（1）componentId应为必填
（2）componentName不对，后端应该直接存储组件ID

12. 添加报表组件请求参数不匹配（报表配置–报表组件–添加报表组件）

业务中下拉菜单–固定选项这种样式，在接口文档应该怎么体现呢？
组长回答：要求他们自己把对应关系写出来，写在注释内。写到apifox的文档内
把【代码-文本】的映射关系写到文档内，让全体人员看懂值的映射关系。
比如：
1001 按日派单
2002 按周派单
3003 按月派单

13. 组件添加条件，请求参数缺少组件ID，参数描述不符（报表配置–报表组件–添加条件）

14. 修改条件，请求参数缺少被修改条件ID（报表配置-报表组件–修改条件）

15. 删除报表组件，被删除的ID应为必选（报表配置-报表组件–删除报表组件）

16. 统一参数接口命名不统一（报表配置-报表组件–组件底层统计–PUT和DEL请求）

17. 未提供明确的枚举类型


18. （我的问题，以为缺少接口，这个请求可以用现有的其他接口）
（1）“选择组件”操作，没有提供可调用的接口

用cursor辅助生成API接口和测试用例

主要使用阮组长给的markdown文件，里面有要求，提示词和其他链接

用cursor生成文件

1. 让AI阅读文件
   把提示词文件里面的连接单独复制过来，把上下文复制给它阅读，”你好，请认真阅读文件，并阅读我提供给你的url链接，阅读上下文，并制定接口生成的计划”先沟通一轮确保模型能够阅读
2. 检查他说的规范内容，让它先写一个接口例子
   “请你给出一个例子，比如我生成delete请求，用path传递被删除的id。请生成一段例子，以便我检查你的理解成果，检查你是否按照规范生成。”如果有问题和它交流，让它的例子符合规范
3. 把api文档复制给它
   检查没问题后，把要生成的接口的文档复制给它（接口文档右上角有复制按钮），它会阅读并生成接口文件和对应的测试用力
4. 检查生成的接口文件和测试用例

测试接口文件

1. 首先确保你在正确的目录下
2. 运行测试用例
   pnpm test src/api/j3/report/report-group/report-group.test.ts
   运行成功+测试正常，效果如图