酒泉网络公司：供应商只交文档不实施时怎样设计双方接口
📱 Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; ClaudeBot/1.0; +claudebot@anthropic.com)
🔗 /bb8cc5e42b81.html
📄
酒泉网络公司：供应商只交文档不实施时怎样设计双方接口
如果供应商只交付文档而不负责实施，接口设计的核心不是把文档写得更厚，而是把“可执行的契约”拆成三部分：数据字段与格式、调用时序与异常分支、验收与变更责任。文档只描述意图，接口必须能被第三方独立实现和测试，否则规模化后每个新接入方都会产生例外。
矛盾现象：样本能跑通，规模一上来就卡住
常见情况是，供应商给一份接口说明，你方开发照着对接，第一两个场景能跑通。等接入方变多、数据来源变杂、异常路径变长，问题集中爆发：字段含义各写各的、错误码没有统一语义、超时和重试没人定义。表面看是文档不够细，实际是接口缺少可验证的边界。
这个现象有两种合理解释，需要分开验证。
- 解释一：文档粒度不足。供应商只写了正常流程，没写空值、超长、并发、重复提交时的行为，导致每个接入方自行猜测。
- 解释二：责任边界没定。文档本身够用，但双方没约定谁负责联调、谁负责数据校验、出问题按什么顺序排查，于是每次异常都变成临时协商。
区分两种解释的证据
不要凭感觉判断，用可观察的证据来区分。
- 让两个互不沟通的开发者分别按文档实现同一个接口，比较结果。如果两人对同一字段的取值、单位、必填性判断不一致，偏向解释一。
- 统计异常处理的归属：如果每次报错都要拉供应商的人才能定位，且定位结论依赖口头补充，偏向解释二。
- 检查文档是否包含可执行的样例。若样例只有请求成功，没有失败响应和边界值，说明文档未覆盖实现所需信息。
需要注意，接口调用量下降或报错数归零，并不能单独证明接口设计正确。它也可能是接入方减少、调用被绕过或错误被上层吞掉的合理解释。判断依据应放在“第三方能否独立复现”上，而不是单一指标。
把文档变成可执行接口的三个动作
动作一：字段契约写成可校验清单
每个字段至少写明：名称、类型、是否必填、取值范围、单位、空值语义、示例。假设一个订单状态字段，文档只写“状态”，实现方可能传数字也可能传字符串。写成枚举清单后，任何一方偏离都能在校验阶段暴露。这个动作的结果是：联调前就能用样例数据自测，减少口头确认。
动作二：定义时序与异常分支
只写请求和响应不够，要写明调用顺序、超时时间、重试规则、幂等要求、失败后双方各自做什么。例如支付回调，若未定义重复通知如何处理，接入方可能重复入账。把“收到重复通知应返回成功且不重复处理”写进接口约定，异常路径才有依据。这一步直接影响下一步：异常分支明确后，联调才可能收敛，而不是每次靠人盯。
动作三：约定验收与变更责任
文档交付不等于接口可用。双方应约定：谁提供测试环境、谁维护样例数据、字段变更提前多久通知、变更由谁回归验证。若供应商只交文档，你方需要承担实现和验证，那么验收标准必须由你方主导定义，否则接口质量无从归属。
不能直接照搬的边界
上述做法在“供应商只交文档、你方自行实施”的前提下成立。若供应商同时提供可运行的服务或沙箱环境，接口设计重点会转向联调与监控，而非单方面补齐文档。若接入方只有一个且双方长期固定协作，口头补充可能暂时够用，但一旦接入方增加或人员更替，例外就会显现。
因此，先确认实施责任落在谁身上，再决定接口文档写到什么程度。责任不清时，再厚的文档也只是把风险推迟到联调阶段。
