资讯中心:PHP 接口开发怎么验收:文档、幂等和错误码
四项验收标准
| 标准 | 说明 |
|---|---|
| 文档 | 第三方不看代码能自测 |
| 幂等 | 重复请求不产生重复数据 |
| 错误码 | 每类失败可区分 |
| 日志 | 每次调用可追溯 |
文档怎么验
- 是否列出全部字段与类型。
- 是否标明必填与可选。
- 是否给出请求示例与返回示例。
- 是否说明错误码含义。
标准是:拿文档给另一个人,他能在 30 分钟内跑通一次调用。
幂等怎么验
- 同一请求连续发送两次,观察数据是否重复。
- 网络超时重试后,是否产生两条记录。
- 支付、下单、库存类接口是否用唯一标识去重。
常见做法:客户端传唯一请求号,服务端按请求号判重。
错误码怎么验
- 参数错误、权限不足、资源不存在、业务冲突、系统异常,是否各有独立码。
- 是否区分“可重试”与“不可重试”。
- 返回信息是否足够定位,但不泄露内部细节。
日志怎么验
- 每次调用是否记录请求号、耗时、结果状态。
- 失败调用是否能查到入参与出参摘要。
- 日志是否可按请求号串联。
验收清单
- 文档字段完整、示例可直接跑。
- 重复调用不产生重复数据。
- 错误码分类清晰且有含义说明。
- 日志可定位单次调用全过程。
- 超时与限流有明确返回。
- 敏感信息不在日志中明文出现。
常见不合格表现
- 所有错误都返回同一条“操作失败”。
- 文档只有字段名,没有示例。
- 重试导致重复下单。
- 日志只在成功时写。
边界
验收标准按常规 HTTP 接口整理。涉及第三方对接或金融类业务,需按其规范补充安全与对账要求。
相关阅读: