第3章 接口契约定义：API版本控制、请求响应结构、错误码规范、兼容性策略

接口契约是Agent模块之间通信的法定边界。在解耦架构中，每个模块只依赖契约而不依赖实现，因此契约的质量直接决定系统能否独立演进。本章从边界与分层切入，逐一剖析API版本控制、请求响应结构、错误码规范和兼容性策略这四个核心维度，并给出选型权衡、风险清单、落地步骤与验收标准。

3.1 契约的边界与分层

接口契约的边界划分遵循三条原则：不暴露内部状态、不传递实现细节、不绑定特定框架。任何跨模块的数据交换都必须经过契约定义的通道，禁止绕过契约直接访问内部数据结构。

从分层视角看，契约可分为三个层次：

3.2 API版本控制策略

版本控制是契约演进的交通规则。Agent模块通常采用三种主流策略，各有适用场景：

3.3 请求响应结构标准化

统一的请求响应结构是契约可读性和可调试性的基础。标准化结构应包含元数据层与业务数据层，实现关注点分离。

标准请求结构包含三部分：

• 请求头：版本标识、请求ID、鉴权令牌、幂等键
• 请求体：业务指令与参数（按领域模型组织）
• 元数据：超时策略、追踪上下文、语言偏好

统一响应结构采用固定外壳：

3.4 错误码规范与分层错误体系

错误码是契约中最重要的故障通信渠道。一个结构化的错误码体系能让调用方精确判断故障位置与原因，避免依赖字符串匹配。

分层错误码范围分配：

每个错误响应应附带错误元数据，帮助调用方快速定位：

{
  "request_id": "req-7a1b2c3d",
  "code": 2001,
  "message": "不支持的API版本，当前版本: v1，请求版本: v3",
  "errors": [
    {
      "code": 2001,
      "field": "Accept",
      "reason": "版本号超出支持范围",
      "help_url": "https://api.agent.io/docs/versioning"
    }
  ]
}

3.5 兼容性策略

兼容性策略决定了模块能否独立升级。Agent解耦架构要求同时保证前向兼容与后向兼容：

3.6 选型权衡与决策矩阵

在接口契约定义的四个维度上，架构师需要做出一组关联决策。下表展示了典型权衡点：

3.7 风险点与管控措施

1. 版本泛滥：每个小改动都发布新版本，导致维护成本爆炸。
   管控：设定版本发布门槛（如：新增/修改字段超过3个才允许发版）。
2. 接口膨胀：响应结构不断追加字段，形成超大payload。
   管控：对响应体大小设置告警阈值，超限时要求重构或拆分接口。
3. 兼容性债务累积：长期不做兼容性清理，旧版本约束拖累新功能。
   管控：每季度执行一次契约审计，标记deprecated版本并制定下市时间表。
4. 错误码歧义：不同模块返回相同错误码但含义不同。
   管控：建立组织级错误码注册中心，所有错误码需审批后发布。

3.8 落地步骤

以下步骤适用于新建Agent模块或对现有模块进行契约规范化：

1. 定义契约模板：发布标准化YAML/JSON Schema契约描述文件，包含版本、请求结构、响应结构、错误码枚举。
2. 建立版本策略：确定版本控制方式（推荐Header协商），制定版本生命周期（开发版→稳定版→废弃版）。
3. 实现错误码体系：按照分层范围分配错误码，每个错误码附带help_url字段指向文档。
4. 部署兼容性检查门禁：在CI/CD流水线中插入契约兼容性检查步骤，阻断破坏性变更。
5. 灰度迁移：旧模块接口通过适配层映射到新契约结构，逐步替换直接调用。
6. 契约审计与度量：每月生成契约健康度报告，监控版本数量、错误码覆盖率、兼容性违规次数。

3.9 验收标准