前后端联调阶段的返工，很多时候不是能力问题，而是信息不对称：字段含义不一致、分页约定不同、异常状态没有覆盖。契约先行的核心，是把这些约定提前写清楚，让双方在同一个基础上开发。

契约应该包含什么

一份可用的接口契约，至少应该说明请求参数、响应结构、分页约定、错误码与边界情况。对于展示型网站，还需要明确 SEO 相关字段、多语言字段与缓存策略。

  • 字段命名与类型保持稳定，避免前后端各有一套理解；
  • 分页统一为 page、pageSize、total、list；
  • 错误响应包含可展示的提示信息与可追踪的错误码。

用示例驱动讨论

相比抽象的字段表，一段真实的请求与响应示例更容易暴露问题。我们会用示例数据走一遍完整流程：列表如何翻页、详情如何取关联内容、空状态返回什么。

契约不是文档写完就结束，而是每次变更都要被双方看见、确认并记录。

让变更可见

项目进入开发后，接口变更不可避免。关键不是杜绝变更，而是让变更可控：谁提出、影响哪些页面、前端何时可以开始适配。把这些信息放进同一个协作流程，联调就不再是一场互相等待。