接口联调少返工：把契约写在前面

前后端联调最耗时间的环节，往往不是写代码，而是对齐理解。前端以为字段是字符串，后端返回的是数字；文档写着分页从 1 开始，实际接口从 0 开始；错误码只写了成功和失败，真正出问题时却返回了一个文档里没有的第三种状态。这些偏差都不大，但每一次都要停下来确认、改代码、再测一轮，几天下来，返工就吃掉了原本留给功能本身的时间。

我的做法是把契约写在前面，而且写成能跑的东西，而不是只存在文档里的文字。联调开始之前，先把接口的请求方法、路径、参数、返回结构、错误码和边界情况定下来，落到一份双方都认的契约里。前端按契约先写 Mock，后端按契约先写实现，两边可以并行，互不阻塞。契约一旦定下来，改动就要走变更：改字段、改类型、改错误码，都先改契约再改代码，而不是某一方悄悄改了实现，让另一方在联调时才发现。

契约要写清楚四件事。第一是类型和单位：时间是时间戳还是 ISO 字符串，金额是分还是元，布尔值是 true 还是 0 和 1，这些地方最容易含糊，也最容易在联调时炸出来。第二是分页和排序的默认值：页码从几开始、每页默认多少条、排序字段不存在时怎么处理，默认值不写清楚，前端就要为每一种可能都做兼容。第三是错误语义：同样是失败，是参数错、权限不足、还是服务端异常，错误码和提示文案要能区分，前端才能决定是提示用户重填、引导登录，还是直接上报异常。第四是边界和空值：列表为空时返回空数组还是 null，字段缺失时是省略还是给默认值，删除不存在的资源返回 404 还是幂等成功，这些都要在契约里说清楚，而不是等线上用户踩到。

契约写好之后，还要让它自动发挥作用。最省事的做法是把契约当成测试的输入：后端提测时跑一遍契约测试，返回结构和契约不一致就直接失败，不用等前端联调才发现；前端也可以用契约生成 Mock 数据和类型定义，接口字段一改，类型定义跟着变，编译期就能发现不一致。契约测试不需要覆盖所有业务逻辑，它只守住一件事：双方约定的形状没有被悄悄改掉。这一层守住了，联调时剩下的问题就大多是真正的业务问题，而不是格式问题。

还有一个容易被忽略的点：契约要给演进留口子。接口上线后，新增字段应当向后兼容，老版本客户端忽略不认识的字段；删除或改名是破坏性变更，要走新版本，而不是直接改掉老字段。很多联调返工其实来自演进时的随意：后端觉得加个字段没什么，前端却因为严格校验把新字段当成了异常。把“只增不改、改动走版本”写进团队约定，比事后救火便宜得多。

最后说一句：契约不是为了束缚谁，而是为了让联调时少吵架。写契约花的时间，通常不到一次返工的零头；但它换来的是两边可以并行开发、提测时有据可查、上线后演进有章可循。接口联调的返工，大多不是技术问题，而是对齐问题。把对齐做在前面，返工自然就少了。