有次联调,对方问“这个字段是必填吗”,我说文档里写了。打开一看,文档最后更新是半年前。
那天我们靠微信群对了两小时字段。
每个字段四件事
名称、类型、是否必填、取值范围。再加一句示例值,基本就不会有歧义。
嵌套结构要单独列,不要用“同上”省略。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| orderId | string(32) | 是 | 订单号,雪花 ID |
| amount | int | 是 | 金额,单位分 |
| status | int | 是 | 1 待付 / 2 已付 / 3 已取消 |
| remark | string(200) | 否 | 备注,超长截断 |
表 1 接口字段表:四列缺一不可
接口完备率:一个能查的指标
我们把“文档化的字段数 ÷ 实际字段数”作为发布门槛,低于 95% 不允许上线。
这个数由脚本扫描代码里的 DTO 自动比对,不靠人自查。
接口完备率 = 已文档化字段数 ÷ 实际字段数 × 100%含错误码与示例;低于 95% 的接口在 CI 里直接失败。
文档和代码一起改
文档滞后是常态,因为它是“另外一件事”。我们把它塞进同一个提交:改接口必须改文档,否则评审不过。
这一条执行三个月后,完备率从 62% 升到 97%。
提示词:找文档和代码的差
我会把 DTO 定义和文档表格一起贴进去,让它对差集。
可直接复制的提示词整段复制
下面是一个接口的 DTO 定义与现有文档字段表。请:
1. 找出代码中存在但文档缺失的字段;
2. 找出文档中存在但代码已删除的字段;
3. 检查必填标记与代码校验注解是否一致;
4. 指出缺少取值范围说明的枚举字段;
输出表格:字段 / 问题类型 / 建议补充。不要重写文档。
文档不是写给新人的,是写给三个月后的自己。
那时候你一定不记得 remark 字段为什么限 200 字。