接口对接总返工,先把这四件事定死

联调反复推倒,往往不是能力问题而是契约没定。本文讲清字段语义、错误码、分页时间、幂等四件事,附评审清单与返工成本。

技术专业区 发布时间:2026-11-18 来原: 巨数科技 7 阅读 0 点赞

接口对接总返工,先把这四件事定死

前后端联调反复推倒,往往不是能力问题,是契约没定。这篇讲清楚接口设计里最容易漏的四件事:字段语义、错误码、分页与时间、幂等,附评审清单和返工成本对照。

一、返工的真实原因

联调延期很少是「谁不努力」,而是双方对同一个字段理解不同。前端以为 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 和在线调试,前端不用等后端,省下的等待时间通常超过接入成本。

错误码要设计多少位? 够用就行。常见是三到四位,按模块分段,留出扩展位,不要一开始就设计成十位编码。

接口对接总返工,先把这四件事定死
点赞(0) 打赏