接口对接总返工,先把这四件事定死
联调反复推倒,往往不是能力问题而是契约没定。本文讲清字段语义、错误码、分页时间、幂等四件事,附评审清单与返工成本。
接口对接总返工,先把这四件事定死
前后端联调反复推倒,往往不是能力问题,是契约没定。这篇讲清楚接口设计里最容易漏的四件事:字段语义、错误码、分页与时间、幂等,附评审清单和返工成本对照。
一、返工的真实原因
联调延期很少是「谁不努力」,而是双方对同一个字段理解不同。前端以为 status 是 0/1,后端给的是字符串 "paid";前端以为空数组表示没有数据,后端返回 null;时间字段一个给时间戳,一个给 2026-11-18 10:00:00。
这类问题不会被单元测试发现,因为单测只测自己那一侧。它只在联调那天集中爆发,然后就是三天的来回改。
更麻烦的是它会上瘾:每次项目都用「先跑起来再对齐」的流程,下一次依然返工。真正省时间的做法,是把契约提前定死,而不是靠沟通弥补。
二、四件事,定死就不会返工
第一件:字段语义与类型
三个要点必须书面写清:字段名、类型、可空性。空值尤其要说清——是 null、空字符串、空数组,还是不返回这个键。前端的判空逻辑依赖这个约定,差一种就出一次白屏。
金额字段建议一律用整数分,避免浮点误差;布尔用 true/false,不要用 0/1 或 "Y"/"N" 混着来;枚举给出完整取值表,别让前端去猜第三第四个值是什么。
第二件:错误码与提示
错误响应必须有两种信息:机器能判断的码、人能看懂的文案。只有文案没有码,前端没法做差异化处理;只有码没有文案,用户看到一串数字。
约定要包含:业务错误码的段位(比如 1xxx 参数错误、2xxx 权限、3xxx 业务状态)、HTTP 状态码与业务码的关系、以及「同一类错误不同场景」怎么区分。
一个常见坑是把所有失败都返回 200,靠 body 里的 code 区分。这在部分网关和日志系统里会丢掉异常统计,排查时找不到错误率。
第三件:分页、排序与时间
分页三选一要说清:页码分页(page/size)、游标分页(cursor)、偏移分页(offset/limit)。列表数据会变动时,页码分页会漏数据或重复,这是真实发生的线上问题。
排序要有默认值。不写默认排序,数据库返回顺序不稳定,前端看到列表顺序每次刷新都变。
时间统一时区与格式。服务端建议统一 UTC 存储、接口出口统一带时区或统一用时间戳,避免跨时区用户看到「八小时前」。
第四件:幂等与并发
下单、支付、提交表单这类接口,必须能被重复调用而不产生多份数据。做法是客户端带一个请求唯一键,服务端做去重。没有这个机制,用户手抖点两下,就是两笔订单。
并发场景还要约定锁的粒度。库存扣减、优惠券领取,靠「先查再改」一定超卖,得用原子更新或队列。
三、返工成本有多贵
按一个中等项目算:接口 40 个,联调阶段每个接口平均返工 0.5 次,每次 0.5 人天,光返工就是 10 人天。这还没算测试回归和上线延期。
延期一周的市场侧损失,通常远大于这 10 人天。所以接口评审不是流程负担,它是最便宜的保险。
另一个隐性成本是维护。字段语义含糊的接口,半年后连原作者都要重新读代码才知道返回值含义,新人接手成本翻倍。
四、我们怎么定这份契约
第一步,出接口清单。按业务模块列,标明调用方、频率、是否对外。0.5 人天。
第二步,定公共规范。字段命名、错误码段位、分页方式、时间格式、幂等键,一次定完,全项目复用。0.5 人天。
第三步,写接口文档并评审。文档要能直接生成 mock,前端不等后端就能开工。1 人天。
第四步,联调前跑一遍契约测试。用 mock 数据校验字段类型与必填,把问题挡在联调之前。0.5 人天。
排错表:
| 症状 | 根因 | 处理 |
|---|---|---|
| 列表偶发重复或漏项 | 用页码分页且数据在变动 | 换游标分页 |
| 前端白屏 | 空值约定不一致 | 文档写清 null/空数组语义 |
| 用户重复下单 | 接口无幂等 | 客户端带唯一键,服务端去重 |
| 排障找不到错误率 | 失败也返回 200 | 用 HTTP 状态码 + 业务码双层 |
| 列表顺序每次不同 | 无默认排序 | 指定排序字段与方向 |
评审前照这张单打勾:字段类型与可空性已写、金额用整数分、枚举值完整、错误码分段、失败不返回 200、分页方式明确、默认排序已定、时间格式统一、幂等键已设计、文档可生成 mock。十条缺一条,联调就会多一天。
五、明确判断
接口契约该不该提前定,不看项目大小,看参与人数。两个人以内、周期两周的活,口头对齐勉强能过;三个以上角色、跨团队、要对外,不写文档就是给自己埋雷。
判断标准很简单:如果联调第一天你还在解释「这个字段是什么意思」,说明契约没定完。
最不该做的:把返工当成协作成本。返工是可预防的,只是预防的动作发生在项目前期,收益在后期才显现,所以总被跳过。
常见问题
小项目也要写接口文档吗? 要,但可以很轻。一页纸写清字段、错误码、分页方式就够,不必上完整规范。
用 Swagger 这类工具值不值? 值。它能生成 mock 和在线调试,前端不用等后端,省下的等待时间通常超过接入成本。
错误码要设计多少位? 够用就行。常见是三到四位,按模块分段,留出扩展位,不要一开始就设计成十位编码。