3. API契约概念
在微服务架构中，服务之间的通信不再是简单的函数调用，而是通过网络协议进行的远程交互。这种分布式环境天然引入了不确定性：服务提供者的接口可能被修改、字段可能被重命名、响应格式可能发生变化。为了消除这种不确定性，API契约应运而生——它是一份服务间通信的“正式合同”，明确规定了请求与响应的结构、类型、边界和约束。
3.1 什么是API契约？
API契约是服务提供者与消费者之间达成的一份技术协议。它定义了：
- 端点（Endpoint）：资源路径与HTTP方法（GET、POST、PUT、DELETE等）。
- 请求格式：请求头、查询参数、路径参数、请求体结构及数据类型。
- 响应格式：状态码、响应体结构、错误模型。
- 安全约束：认证方式、权限范围。
- 业务规则：字段必填性、枚举值范围、长度限制。
3.2 OpenAPI / Swagger 规范
OpenAPI规范（原名Swagger规范）是目前业界最广泛使用的RESTful API契约标准。它使用JSON或YAML格式描述API的全部细节，由OpenAPI Initiative（OAI）维护，版本已演进到3.1.x。
| 特性 | 说明 |
|---|---|
| 规范版本 | OpenAPI 3.0.x（主流）、3.1.x（兼容JSON Schema 2020-12） |
| 描述格式 | YAML（推荐）或JSON |
| 核心结构 | info、servers、paths、components、security |
| 工具生态 | Swagger UI、Swagger Editor、OpenAPI Generator、Postman、Stoplight |
| 契约验证 | 支持请求/响应校验、数据模型校验、枚举约束校验 |
以下是一个简化的OpenAPI 3.0契约片段，描述了一个用户查询接口：
openapi: "3.0.3"
info:
title: 用户服务API
version: "1.0.0"
paths:
/users/{userId}:
get:
summary: 根据用户ID获取用户信息
parameters:
- name: userId
in: path
required: true
schema:
type: string
format: uuid
responses:
"200":
description: 成功返回用户对象
content:
application/json:
schema:
$ref: "#/components/schemas/User"
"404":
description: 用户不存在
components:
schemas:
User:
type: object
required:
- id
- name
- email
properties:
id:
type: string
format: uuid
name:
type: string
maxLength: 100
email:
type: string
format: email
3.3 契约作为服务间“合同”的作用
契约在微服务生态中扮演着法律合同般的角色。它带来的核心价值包括：
- 解耦开发：提供者和消费者可以并行开发，只要双方遵守同一份契约。
- 防止回归：契约测试在CI流水线中自动运行，一旦提供者破坏了契约，测试立即失败。
- 文档即代码：契约本身就是最新的API文档，避免文档与实现脱节。
- 版本演进：通过契约版本号管理API变更，支持向后兼容性检查。
- 自动化工具链：从契约自动生成客户端SDK、服务端桩代码、测试用例。
3.4 消费者视角 vs 提供者视角
同一份契约，从不同角色看，关注点截然不同。理解这两个视角是设计契约测试策略的前提。
| 维度 | 消费者视角 | 提供者视角 |
|---|---|---|
| 核心关注 | 我能否正确调用接口？响应结构是否符合预期？ | 我的接口是否满足所有消费者的需求？ |
| 测试重点 | 请求构造正确性、响应解析正确性、错误处理 | 接口行为与契约一致、不破坏已有消费者 |
| 契约使用方式 | 读取契约生成客户端代码或Mock服务 | 读取契约生成服务端桩代码或验证中间件 |
| 变更影响 | 契约变更可能导致消费者代码编译失败或运行时错误 | 契约变更需要通知所有消费者，并评估兼容性 |
| 典型工具 | OpenAPI Generator（生成Go客户端）、Prism（Mock服务） | Dredd、Spectral（契约校验）、Pact（消费者驱动契约） |
在Go Web服务开发中，消费者视角的契约测试通常由集成测试或契约测试框架（如Pact）实现；提供者视角的契约测试则通过契约校验中间件或API测试工具（如Dredd）在CI中自动执行。
3.5 契约在微服务通信中的位置
下面的SVG图展示了契约如何作为服务间通信的“合同”居中协调，连接消费者与提供者两个角色。
上图清晰地展示了：消费者通过读取契约生成客户端代码和Mock服务，提供者则依据契约实现接口并通过校验中间件保证一致性。契约位于中心，成为双方共同遵守的“合同”。
3.6 消费者驱动契约 vs 提供者驱动契约
在实际工程中，契约的生成和验证有两种主流模式：
| 模式 | 发起方 | 工作流程 | 适用场景 |
|---|---|---|---|
| 消费者驱动契约 | 消费者 | 消费者编写期望的交互 → 生成契约 → 提供者验证 | 多个消费者、提供者需要同时满足所有消费者的需求 |
| 提供者驱动契约 | 提供者 | 提供者发布契约 → 消费者按契约实现调用 | 单一消费者、提供者主导API设计 |
在Go Web服务开发中，推荐采用消费者驱动契约模式，因为它更贴近微服务“服务自治”的理念——每个消费者只声明自己需要的接口子集，提供者只需保证这些子集不被破坏，而不必维护一份庞大的全局契约。
github.com/pact-foundation/pact-go 实现消费者驱动契约测试。消费者测试生成契约文件（JSON格式），提供者测试读取该文件并验证实际接口行为是否匹配。
3.7 契约的版本管理与兼容性
契约不是静态的，它会随着业务需求演进。管理契约变更的核心原则是向后兼容：
- 兼容变更：添加可选字段、扩展枚举值、增加端点。消费者无需修改代码即可正常工作。
- 破坏性变更：删除字段、修改字段类型、重命名端点、移除端点。必须升级API主版本号。
- 版本策略：使用语义化版本（SemVer）管理契约版本，并在契约文件中显式声明
version字段。 - 兼容性检查工具：
openapi-diff、spectral、oasdiff可以在CI中自动检测破坏性变更。
下面的SVG图展示了契约版本演进的典型生命周期：
3.8 本章小结
- API契约是服务间通信的正式合同，使用OpenAPI/Swagger规范描述。
- 契约提供了解耦开发、防止回归、文档即代码、自动化工具链等核心价值。
- 消费者视角关注调用正确性和响应解析；提供者视角关注接口一致性和兼容性。
- 推荐采用消费者驱动契约模式，使用Pact等工具在Go项目中落地。
- 契约版本管理遵循语义化版本原则，破坏性变更必须升级主版本号。