1. API 契约治理概述
1.1 什么是 API 契约
API 契约（API Contract）是服务提供方与消费方之间就接口行为、数据格式、约束条件达成的形式化约定。它不仅是接口文档，更是一组可验证的规则集合，涵盖请求/响应结构、数据类型、边界值、错误码、幂等性语义等维度。
核心定义：API 契约 = 接口签名 + 数据约束 + 行为语义 + 版本承诺。
在微服务架构中，每个服务都通过 API 暴露能力，契约成为服务间协作的“连接协议”。没有明确的契约，服务间的数据交换将依赖隐式假设，极易引发数据不一致问题。
1.2 契约治理的核心目标
契约治理（Contract Governance）是对 API 契约的定义、发布、变更、合规、废弃全生命周期进行系统化管理的过程。其核心目标包括：
| 目标维度 | 具体说明 | 治理手段 |
|---|---|---|
| 一致性 | 确保服务间数据交换格式、类型、约束完全对齐 | 契约校验、类型系统强制 |
| 兼容性 | 契约变更不破坏已有消费方 | 语义版本化、向后兼容检查 |
| 可追溯 | 每次契约变更都有记录，可回溯历史版本 | 契约仓库、变更审计日志 |
| 自动化 | 契约的验证、测试、发布流程自动化 | CI/CD 集成、契约测试套件 |
| 可观测 | 运行时契约违规可被监控和告警 | 契约监控、异常检测 |
实践要点：契约治理不是文档管理，而是数据一致性防线的第一层。在 PostgreSQL 接口设计中，契约直接映射到表结构、字段约束、事务边界，治理缺失将导致数据污染。
1.3 在微服务架构中的重要性
微服务架构天然存在服务间数据依赖，每个服务拥有独立数据库，API 成为数据流通的唯一通道。契约治理在此时承担以下关键角色：
- 解耦基础：契约定义了服务间的“数据边界”，服务只需遵守契约，无需了解对方内部实现。
- 数据一致性保障：通过契约明确字段类型、非空约束、唯一性、外键语义，从接口层面防止脏数据流入。
- 变更风险管理：微服务迭代频繁，契约治理确保接口变更不会引发连锁故障。
- 自动化测试支撑：契约可作为消费者驱动契约测试（CDC）的输入，提前发现不兼容问题。
下图展示了 API 契约在微服务数据流中的核心位置：
1.4 契约治理与 PostgreSQL 数据一致性的关系
PostgreSQL 作为微服务中广泛使用的数据库，其强事务、约束完整性、数据类型系统为契约治理提供了天然的技术底座。契约治理在 PostgreSQL 接口设计中体现为：
- 字段级契约：API 中的字段类型、长度、精度必须与 PostgreSQL 表定义严格对应。
- 约束映射：NOT NULL、UNIQUE、CHECK、FOREIGN KEY 等约束需在 API 契约中显式声明。
- 事务边界契约：接口的幂等性、原子性语义需与数据库事务隔离级别对齐。
- 变更同步：数据库 schema 变更必须触发契约版本更新，防止运行时数据不一致。
常见陷阱：很多团队只维护 API 文档，忽略契约与数据库 schema 的双向校验。当数据库字段类型从 INTEGER 改为 BIGINT 而 API 契约未同步时，消费方可能因数值溢出导致数据写入失败或静默截断。
1.5 契约治理成熟度模型
为帮助团队评估当前状态，以下给出契约治理的四个成熟度等级：
| 等级 | 特征 | 典型表现 |
|---|---|---|
| L0：无治理 | 无显式契约，依赖口头沟通 | 接口频繁断裂，数据不一致频发 |
| L1：文档化 | 有静态 API 文档，但未自动化 | 文档滞后，人工比对效率低 |
| L2：自动化校验 | 契约文件纳入 CI，自动校验兼容性 | 变更可检测，但缺乏运行时监控 |
| L3：全生命周期治理 | 契约定义→发布→变更→废弃全流程自动化 | 数据一致性由系统保障，人工介入极少 |
课程定位：本课程将带领你从 L0/L1 起步，逐步构建 L2/L3 级别的契约治理体系，并深度结合 PostgreSQL 的数据一致性特性。