4. 接口定义与契约设计：接口规范、输入输出协议、版本兼容性策略

4.1 接口契约的三层边界

接口契约是模块间协作的“法律文件”，它在调用方与提供方之间划定清晰的语法边界、语义边界与约束边界。三层边界共同构成可验证、可演进、可治理的接口契约模型：

• 语法边界：规定接口的“书写格式”——方法名、参数类型、必选/可选标识、返回值结构；违反语法边界的调用在编译或序列化阶段即可被捕获。
• 语义边界：定义接口的“业务含义”——前置条件、后置条件、业务异常码、幂等语义；违反语义边界的调用需要通过业务规则引擎或契约测试发现。
• 约束边界：承诺接口的“非功能属性”——响应时间百分位、吞吐量上限、安全认证级别、幂等有效期；违反约束边界通常触发熔断、降级或审计告警。

4.2 语法层：接口规范

语法层是契约的最外层，也是工具链支持最成熟的层面。规范必须覆盖以下要素：

以下是一个遵循三层边界的接口定义片段（以 OpenAPI 3.0 风格示意）：

openapi: 3.0.0
info:
  title: 订单查询接口 — 语法层规范
  version: 2.1.0
paths:
  /api/v2/orders/{orderId}:
    get:
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
            pattern: "^ORD\\d{14}$"
        - name: includeItems
          in: query
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: 成功返回
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:    { type: integer, enum: [0] }
                  message: { type: string }
                  data:
                    $ref: '#/components/schemas/OrderDetail'
        '400':
          description: 参数校验失败
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:    { type: integer, enum: [40001,40002] }
                  message: { type: string }
                  traceId: { type: string }

4.3 语义层：输入输出协议

语义层解决“数据代表什么业务含义”的问题。同样一个 status: 1，在不同接口中可能代表“已支付”“已发货”或“已取消”——语义歧义是模块集成中最隐蔽的错误源。

语义层的核心协议元素：

• 前置条件：调用该接口前必须满足的状态（如“订单必须处于待支付状态”）。
• 后置条件：调用成功后系统状态的变化（如“订单状态变更为已支付，库存扣减 1”）。
• 业务异常码：每个异常码对应唯一的业务场景，且拥有独立的错误消息模板。
• 幂等语义：接口是否幂等、幂等键的生成规则、幂等有效期。

4.4 约束层：非功能契约

约束层定义了接口在非功能属性上的承诺，是信任链路的物理基础。约束层契约必须包含：

信任链路：约束层是信任链路的锚点。消费者根据约束层契约决定是否发起调用（如本地限流判断），提供方根据约束层契约进行容量规划和熔断配置。双方信任建立在可度量的 SLA 承诺之上，而非“尽力而为”。

4.5 组件职责：消费者与提供者的对称契约

接口契约定义了对称的职责边界：

• 消费者职责：遵循语法层格式发起请求；满足前置条件后再调用；处理所有定义好的业务异常码；遵守限流策略，实现本地熔断。
• 提供者职责：严格按照 IDL 实现接口；兑现语义后置条件；满足约束层 SLA；对破坏性变更提前至少 2 个版本发布迁移指南。

4.6 版本兼容性策略

版本兼容性是接口治理中最棘手的部分——一次破坏性发布可能导致所有消费者受阻。策略必须回答三个问题：什么算破坏？如何声明？如何迁移？

4.6.1 向后兼容性红线

以下变更属于破坏性变更，禁止在同一个大版本内发布：

• 删除或重命名接口、参数、字段
• 将可选参数改为必选
• 缩小参数类型范围（如 int → short）
• 增加新的前置条件或缩小后置条件
• 降低约束层 SLA（如 P99 从 200ms 改为 500ms）

4.6.2 语义版本号策略

接口版本号必须遵循 MAJOR.MINOR.PATCH 语义：

4.7 选型权衡

接口定义与契约设计没有银弹，以下是三组核心权衡：

4.8 风险点

1. 契约腐化：接口代码与 IDL 不同步，导致消费者拿到过时的契约文件。需通过 CI 门禁检测 IDL 与实现的一致。
2. 隐式契约：未在 IDL 中声明的前置条件、错误码、幂等规则。隐式契约是线上故障的头号根源。
3. 版本爆炸：每个模块维护大量历史版本，导致兼容性测试矩阵呈指数增长。应设置版本生命周期，定期淘汰过旧版本。
4. 兼容性债务：长期只加不减，接口字段膨胀到数百个，维护成本激增。建议每两个 MAJOR 版本做一次接口瘦身。

4.9 落地步骤

4.10 验收标准

第 4 章落地成效通过以下量化指标验收：

• 契约通过率 ≥ 98%：所有核心接口的 CDC 契约测试在 CI 中绿通过。
• 破坏性变更次数 ≤ 2 次/季度：且每次均有提前 2 个版本的迁移通知。
• 隐式契约清零：所有接口的前置条件、异常码、幂等规则均在 IDL 或契约测试中显式声明。
• 版本兼容性覆盖率 100%：CI 中对每个 PR 自动检查是否引入了破坏性变更。