接口定义书 — 出事最多的那份文档

在 LabHub 中继续学习

一句话总结

接口定义书不是说明文档，而是两个组织共同签署的协议。如果缺少各响应代码的处置方式与非功能项，发生故障时，空白处就会被相互追责填满。

概念图: 两个组织共同签署的协议 · 没有达成一致的事项 · 事后追溯双方约定由谁做什么 · 路由

为什么这是个问题

大多数集成事故不是源于代码，而是源于没有达成一致的事项：双方理解的字段长度不同；没有规定超时后应重发还是查询；响应代码 9500 被一方理解为可重试，另一方却理解为必须停止。

这些问题在开发期间不会暴露，因为大家只测试正常流程。上线后第一次发生故障，定义书中没写的事项就会全部变成“我们以为这应该由你们处理”。因此，定义书必须能够事后追溯双方约定由谁做什么，而这需要签字确认。

连接数量增长有多快

五个系统相互直接连接（P2P），需要多少条连接？

N(N-1)/2
 5개 →   10
10개 →   45
20개 →  190
50개 → 1,225

这就是 EAI（Enterprise Application Integration）概念出现的原因。把中心放在中间，连接数就变为 N，每个系统只需了解如何与中心集成。

中心承担四项工作。

路由——这份报文要发给谁
转换——发送格式 → 接收格式（映射）
保证——失败重试、顺序与去重
监控——什么在何时交换了多少条

韩国金融机构中还会增加更多层级。

[인터넷뱅킹 · 모바일 · ATM · 텔러]
              ↓
           MCI (Multi Channel Integration)   ← 채널 통합
              ↓
           EAI                               ← 내부 시스템 간
              ↓
[코어뱅킹 · CRM · 리스크 · 수신 · 여신]
              ↓
           FEP (Front-End Processor)         ← 대외 기관
              ↓
[금융결제원 · 카드사 · 보험사 · 신용정보원]

记住MCI 面向渠道，FEP 面向外部机构，会议中就不会迷失。这些区间中相当一部分至今仍使用定长报文 + TCP 套接字。对只接触过 JSON REST 的人很陌生，但在要求全天候运行、每笔响应仅数毫秒的区间，这仍是合理选择。

公共数据模型（CDM）的算术

五个系统使用不同格式时，双向映射数量为 N(N-1) = 20。若建立公共模型，每个系统只需实现“自身 ↔ 公共”两条映射，共 N×2 = 10 个。新增一个系统的成本也从 2N 降为2。

这就是主张建立“标准报文”的依据。但现实中，协商公共模型本身就可能成为一个项目。因此，集成对象不超过三个时，直接采用 P2P 也可能更好。 基于数字判断与追逐潮流完全不同。

接口定义书必须包含什么

现场有句经验：“接口定义书里没有的内容，双方一定实现得不一样。” 因为公司不同、开发人员不同、测试日程也不同。

（1）识别信息

接口 ID（例如 IF-ORD-001，应有统一体系）
业务名称、发送系统、接收系统、负责人及联系方式
集成方式：REST / SOAP / 文件 / MQ / DB 链接 / 套接字
周期：实时 / 准实时（N 分钟）/ 日批处理（注明时刻）

（2）报文布局

每个字段都要写明名称 / 类型 / 长度 / 是否必填 / 样例值 / 备注。以下内容若缺失，一定会发生事故。

项目	不写会怎样
字符集	一方 UTF-8、一方 EUC-KR → 韩文乱码
日期格式	`YYYYMMDD`、`YYYY-MM-DD` 还是 ISO8601
金额小数位	以元还是角为单位？如何舍入？
符号表示	负数写成 `-1000`、尾部符号，还是独立符号字段？
空值表示	空字符串、空格填充，还是字符串 `NULL`
超长处理	截断还是报错

尤其要小心韩文占 3 字节的问题。若向长度为 20 的列写入 10 个韩文字符，UTF-8 下会达到 30 字节而无法写入。定义书只写“长度 20”，一方会按字符数实现，另一方会按字节数实现。必须连单位一起写成**“20 字节（UTF-8）”。**

（3）响应代码体系与接收方动作

这是最常遗漏的内容。虽然列出了代码，却没有写明每个代码对应什么动作。

代码	含义	接收方动作
`0000`	正常	正常处理
`9001`	缺少必填值	禁止重试，修正数据后重发
`9002`	认证失败	禁止重试，通知负责人
`9003`	重复请求	视为正常（幂等）
`9500`	对方系统临时错误	重试（退避）
`9999`	未知错误	重试一次后送入 DLQ

关键是区分**“可以重试的错误”与“不能重试的错误”**。定义书未写明时，开发人员要么全部重试，要么全部放弃。前者会把错误数据发送一百次，后者会让业务因临时故障停摆。

（4）非功能项

预计数量（日常／峰值）、最大报文大小
超时（连接／响应）、重试次数与间隔
故障联系机制、恢复目标时间
保留期限（原始报文、日志）
是否包含个人信息，以及需要加密的字段

定义书是协议——必须签字

接口定义书不是我方单独编写的设计文档，而更像是双方签署的合同。因此必须做到三点。

在文档内保留版本与修订历史。“你们看的是旧版本”在现场经常发生。
获得双方负责人的确认，邮件回复也可作为证据。
变更必须由双方协商。 一方新增字段，可能直接让对方解析器崩溃；尤其是定长报文，只偏移一个字符，后续字段就会全部损坏。

集成开发的标准顺序

因为对方系统尚未准备好而导致开发停滞，是 SI 常见风险。因此应按以下顺序推进。

1. 인터페이스정의서 확정 (양쪽 서명)
2. ★ Mock 서버 구축 — 정의서대로 응답하는 가짜 상대 시스템
3. 우리 쪽 개발 + Mock 으로 단위테스트
4. 상대 시스템 준비되면 연동 테스트 (개발계)
5. 오류 케이스 테스트 ← 여기가 진짜 테스트다
6. 운영 리허설 (방화벽·인증서·계정 포함)

跳过第 2 步，我方日程就会被对方日程绑定。 还有很多项目会跳过第 5 步，只确认正常场景就上线，直到第一次故障才发现没有重处理流程。

第 6 步括号中的内容尤其重要。开发环境正常、生产环境失败，多数并非代码问题，而是防火墙策略、证书、账户权限三者之一。这三项从申请到生效通常需要数天，迁移当天才发现就已经太晚。

在实际项目中

定义书不完整的代价，总是很晚才出现，而且由别人付出时间。

双方理解的字段长度不同。 我方截到 16 个字符，对方按 20 个字符接收。正常数据中看不出来，直到某天出现较长订单号，尾部被截断后仍静默入库。因为不是报错而是无声的数据污染，往往几周后才发现。
未规定响应代码对应的动作。 对 9500，我方理解为重试，对方理解为“停止并咨询”。故障时我方认真执行的重试，在对方看来就是流量轰炸。
缺少非功能项。 每秒最多接收多少条、最大报文多大都没写时，只能在上线首日通过真实流量得知上限。

因此，评审定义书时要看的不是已有句子，而是空白项。没有写下来的事项就是尚未达成一致的事项，而未达成一致的事项会在故障时变成争议。