一、契约至少包含五件事
请求身份与权限、必填字段、成功数据结构、错误分类以及重试是否安全,应该在实现前写清楚。
字段命名、时间格式、空值语义与分页方式一旦上线,修改成本会远高于讨论成本。
- 身份与权限在契约里写明,调用方不需要额外猜测
- 错误按类别划分,调用方能据此决定是重试还是提示用户
- 重试语义明确,哪些操作可以安全重试一目了然
- 字段命名保持一致,前后端对同一个概念使用同一个名字
二、为失败状态准备样例
网络中断、服务超时、权限不足、数据冲突和重复提交,都应有对应样例和界面反馈。
开发时同时准备错误响应,前端才能完成可测试的状态,而不是在联调最后一晚临时补 UI。
- 超时与请求中断都有对应反馈,不会让界面长时间停在等待状态
- 冲突场景可以被识别并明确报告,而不是静默覆盖已有数据
- 重复提交有防护机制,用户连点几次不会产生多笔数据
- 版本可以追溯,出了问题能定位到当时调用的是哪一个版本
三、契约变更要按版本推进
接口一旦被使用,删除字段和改变语义都属于破坏性变更。通过新增字段、保留旧行为的方式演进,调用方才有时间调整。
把废弃时间写进文档,比标注「已废弃」更有效,因为真正需要的是对方完成迁移的截止日期。
- 破坏性变更一律走新版本,旧版本继续保留一段时间
- 新增字段保持向后兼容,老版本客户端不会因此报错
- 废弃有明确的截止时间,相关方可以按计划完成迁移
- 变更记录可以查询,每次调整都有据可查