系统与上线/2026-11-12/6 分钟

接口联调之前,先把契约和失败状态说清楚

前后端各自“合理”的理解,往往在联调时才变成问题。与其边写边猜,不如先用一份小契约覆盖成功响应、失败响应和重复请求。

一、契约至少包含五件事

请求身份与权限、必填字段、成功数据结构、错误分类以及重试是否安全,应该在实现前写清楚。

字段命名、时间格式、空值语义与分页方式一旦上线,修改成本会远高于讨论成本。

  • 身份与权限在契约里写明,调用方不需要额外猜测
  • 错误按类别划分,调用方能据此决定是重试还是提示用户
  • 重试语义明确,哪些操作可以安全重试一目了然
  • 字段命名保持一致,前后端对同一个概念使用同一个名字

二、为失败状态准备样例

网络中断、服务超时、权限不足、数据冲突和重复提交,都应有对应样例和界面反馈。

开发时同时准备错误响应,前端才能完成可测试的状态,而不是在联调最后一晚临时补 UI。

  • 超时与请求中断都有对应反馈,不会让界面长时间停在等待状态
  • 冲突场景可以被识别并明确报告,而不是静默覆盖已有数据
  • 重复提交有防护机制,用户连点几次不会产生多笔数据
  • 版本可以追溯,出了问题能定位到当时调用的是哪一个版本

三、契约变更要按版本推进

接口一旦被使用,删除字段和改变语义都属于破坏性变更。通过新增字段、保留旧行为的方式演进,调用方才有时间调整。

把废弃时间写进文档,比标注「已废弃」更有效,因为真正需要的是对方完成迁移的截止日期。

  • 破坏性变更一律走新版本,旧版本继续保留一段时间
  • 新增字段保持向后兼容,老版本客户端不会因此报错
  • 废弃有明确的截止时间,相关方可以按计划完成迁移
  • 变更记录可以查询,每次调整都有据可查

想把这些方法用在自己的项目上?

联系我们