核心结论
对接前把六件事写成双方确认的交接表:业务字段与主键由谁生成、重复请求如何识别;鉴权用哪个账号、凭证如何轮换;哪些错误可以重试、哪些不能;频率与超时上限;测试环境和数据;版本变更如何通知。接口文档只描述调用方式,不替代这些业务约定。

先看一个假设的例子:项目启动会上,对方发来一份 30 页的接口文档:有哪些地址、每个请求带什么字段、返回什么 JSON。双方都以为可以开工了。三周后联调,订单系统重发了一次超时的创建请求,对方系统多生成了一张订单。再往后,测试环境里能通过的签名,换成正式凭证就失败。
接口文档描述的是怎么调用,不描述双方对业务的共同约定。文档发过来之后,还有六件事需要确认。
接口文档通常缺什么
常见接口文档会写地址、请求方法、字段名、示例报文和返回码列表。它通常不写:业务主键由谁生成、重复请求算不算同一件事、凭证归谁管理、哪些错误可以自动重试、调用频率上限是多少、测试环境是否与正式环境一致、版本变更提前多久通知。
这些内容不属于“技术细节”,它们决定业务会不会重复记账、丢单或卡在无人处理的失败里。对接前要把它们写进一份双方确认的交接表,而不是等联调时在群里逐条问。
业务字段和主键:谁生成,重复请求算什么
先定每个对象的业务主键。订单号、客户编号、物料编码,由哪一方生成,格式是什么,是否允许修改,冲突时以哪边为准。主键不能只在各自的数据库里唯一,它必须在双方之间能对应上。
再定重复请求的识别方式。常见的做法是请求方带一个幂等键,接收方在第一次成功后记住这个键,后续相同键的请求返回第一次的结果,而不是再建一条记录。幂等键由哪一方生成、保存多久、重复时返回什么,都要写明。
金额要写清币种和最小单位,避免一方用元、一方用分。时间要写清时区和格式,跨系统的时间比较很容易差八小时。状态字段不要直接互传内部枚举值,先做一张状态映射表:对方系统的“已确认”对应本系统的哪个状态,对应不上的进入哪个待处理状态。
鉴权与权限:用谁的账号,凭证怎么换
接口通常用独立的系统账号,而不是某个员工的个人账号。员工调岗或离职,不应让接口突然失效;反过来,共享一个管理员账号,也无法知道是哪套系统在调用。
要确认:凭证类型是什么,由谁签发,保存在哪里,多久轮换一次,泄露后如何作废;调用方在对方系统里拥有哪些权限,是否只限必要的读写;是否有 IP 白名单或其他来源限制;每次调用是否留下可追溯的日志。
不要把正式凭证写进前端代码、聊天记录或仓库的示例配置。凭证轮换要有重叠期,先发新凭证、确认调用切换成功,再停用旧凭证,避免轮换当天接口全断。
错误与重试:哪些请求可以重发
- 网络或临时故障
- 受控重试并核对幂等
- 权限、校验或冲突
- 修正原因或人工核对
新建类请求在自动重试前需确认幂等机制和服务端处理结果。
失败不都等于可以重试。按 RFC 9110 第 9.2.2 节,GET、HEAD、OPTIONS、TRACE、PUT、DELETE 是幂等方法,重复发送相同请求的预期效果与发送一次相同;POST 不是。用 POST 创建订单时,没有幂等键就自动重试,可能创建两张订单。
因此重试规则至少分三类:
- 可安全重试:网络超时、连接中断、对方返回 503。可以退避后重试,但要设次数上限和总时长。对方返回 503 并带 Retry-After 时,按它给出的等待时间再试,不立刻重发。见 RFC 9110 第 15.6.4 节。
- 不能自动重试,需要先对账:POST 新建类请求超时,但无法确认对方是否已经处理。先用查询接口按业务主键查一次,确认没有写入再重发。
- 重试没有意义:字段校验失败、权限不足、凭证过期、业务规则拒绝。把错误原文或双方约定的错误码交给人和日志,不要反复重发。
对方返回 409 时,按 RFC 9110 第 15.5.10 节,表示请求与目标资源当前状态冲突,响应应包含足以让人识别冲突的信息。这通常意味着需要人看一眼,而不是自动重试。
错误码表要双方共同维护:每个码对应什么原因、由谁处理、是否可重试、用户看到什么文案。只给对方一段英文堆栈,运营无法处理。
调用频率、超时与批量
频率上限要写成具体数字,并说明是每秒、每分钟还是每天,按账号还是按接口。超过上限时对方返回什么,调用方如何排队或降级,要提前约定。
批量接口要写清单次最多多少条、部分成功时返回什么、失败的行怎么重试。不要假设“批量提交要么全成功要么全失败”,很多接口是逐条处理的。
超时时间也要双方一致。调用方设 10 秒超时,对方实际 30 秒才处理完,调用方会认为失败并重试,造成重复。异步任务更要把“已受理”和“已完成”分开:先拿任务编号,再轮询或等回调。
测试环境、版本与上线切换
测试环境要能覆盖正式环境的主要行为,包括鉴权、错误码和限流。测试凭证与正式凭证分开,测试数据不要使用真实客户资料。双方要约定联调窗口、谁能在测试环境造数据、出现问题时找谁。
接口变更要提前通知:新增字段通常兼容,删除字段、改字段含义、改错误码、改鉴权方式则可能让调用方直接失败。版本号怎么带、旧版本保留多久、切换时双方如何验证,都写进交接表。
上线切换要有回退方案。先小流量或单账号试运行,确认对账一致,再扩大范围。切换当天保留双方的值班人和回退开关。
接口交接表
项目 | 需要确认的内容 | 由谁提供 | 验收方式 |
|---|---|---|---|
业务主键 | 生成方、格式、是否可改、冲突规则 | 双方业务负责人 | 用一张测试订单双向核对 |
幂等 | 幂等键、保存时长、重复请求返回 | 接收方 | 同一请求发送两次,只产生一条记录 |
字段映射 | 状态、金额单位、时区、枚举 | 双方 | 字段对照表逐项签字 |
鉴权 | 账号、凭证轮换、权限范围、日志 | 双方技术负责人 | 用测试凭证与正式凭证各调用一次 |
错误 | 错误码、可重试性、处理人、文案 | 接收方 | 制造一次校验失败与一次 503 |
频率与超时 | 上限、批量大小、部分成功、超时值 | 双方 | 压测或模拟限流 |
测试环境 | 地址、数据、联调窗口、联系人 | 双方 | 一条完整任务在测试环境走通 |
版本变更 | 通知方式、提前期、旧版保留 | 双方 | 变更记录可查 |
这张表不需要很厚,但每一行都要有具体答案和负责人。空着的行,就是联调时会卡住的地方。
先挑一个最小的接口,例如查询一条订单状态,把上面八行填完再开始写代码。查询接口跑通后,再处理创建和修改。业务系统开发中怎样把接口范围写进项目,可参考业务系统开发;现有表格和主数据怎样整理,可参考业务系统准备清单。
AI 接入 ERP 或 OA 的分级与权限边界,见AI 怎么接入 ERP 和 OA。那篇讨论的是 AI 动作级别,不替代本文的接口交接表。