3. API设计治理原则：RESTful与事件驱动API的设计规范、版本控制、契约优先
在微服务与事件驱动架构（EDA）混合的系统中，API设计治理是保障系统可维护性、可测试性和演进能力的基础。本章聚焦三大核心原则：设计规范（RESTful vs 事件驱动）、版本控制策略以及契约优先的开发流程。这些原则直接决定了后续Mock隔离与调试的可行性。
3.1 RESTful API 与事件驱动 API 的设计规范
两种API风格在治理上存在本质差异，需要分别制定规范。
| 维度 | RESTful API | 事件驱动 API（Kafka） |
|---|---|---|
| 通信模式 | 请求-响应（同步/异步） | 发布-订阅（异步） |
| 资源标识 | URL路径（如 /orders/{id}） | Topic名称（如 order.events.created） |
| 数据格式 | JSON/XML，状态码表达结果 | Avro/Protobuf/JSON Schema，事件体包含类型与版本 |
| 幂等性 | 通过HTTP方法（GET/PUT/DELETE）保证 | 通过事件ID + 消费者去重保证 |
| 错误处理 | HTTP 4xx/5xx + 错误体 | 死信队列（DLQ）+ 重试策略 |
治理要点：在混合架构中，建议为RESTful API和事件API分别建立独立的规范文档。RESTful侧重资源建模与状态码标准化；事件API侧重Topic命名规范、事件Schema演进规则和分区键设计。
3.2 版本控制策略
版本控制是API治理中最具挑战性的环节。RESTful与事件驱动API的版本策略截然不同。
3.2.1 RESTful API 版本控制
- URI路径版本（推荐）：
/v1/orders、/v2/orders。显式、易于路由和缓存。 - 请求头版本：
Accept: application/vnd.company.v1+json。更干净但调试复杂度高。 - 查询参数版本：
/orders?version=1。不推荐，容易导致缓存混乱。
3.2.2 事件驱动 API 版本控制
Kafka消息的版本控制核心在于Schema兼容性。推荐使用Schema Registry管理事件版本。
| 兼容性类型 | 说明 | 适用场景 |
|---|---|---|
| BACKWARD | 新Schema可以读取旧数据（允许删除字段/添加可选字段） | 消费者先升级 |
| FORWARD | 旧Schema可以读取新数据（允许添加字段/删除可选字段） | 生产者先升级 |
| FULL | 同时满足BACKWARD和FORWARD | 严格兼容要求 |
| NONE | 不检查兼容性 | 仅用于开发/测试环境 |
常见陷阱：不要对Kafka Topic进行“版本号命名”（如 order-v1、order-v2）。正确的做法是使用单一Topic，通过Schema Registry管理事件体的版本演进。Topic名称应反映业务领域而非版本。
3.3 契约优先（Contract-First）开发流程
契约优先是API治理的基石。它要求在编写任何实现代码之前，先定义API契约（OpenAPI/Swagger、AsyncAPI、Avro Schema等）。
3.4 契约优先在Kafka场景下的实践要点
在Kafka消息驱动的微服务中，契约优先需要额外关注以下方面：
- Topic契约化：将Topic名称、分区数、保留策略纳入契约文档（如AsyncAPI）。
- Schema注册：所有事件Schema必须在Schema Registry中注册，并指定兼容性策略。
- Mock数据生成：基于契约自动生成符合Schema的Mock事件，用于消费者端隔离测试。
- 消费者契约测试：使用Pact或Spring Cloud Contract验证消费者能否正确处理契约定义的事件。
实践案例：某电商平台在订单服务与库存服务之间使用Avro Schema定义OrderCreated事件。契约定义后，订单团队和库存团队分别基于Mock数据进行开发。集成测试时，双方只需验证Schema兼容性，无需等待对方服务部署完成。该实践将集成周期从3天缩短至4小时。
3.5 设计规范检查清单
在API设计评审阶段，建议使用以下清单进行治理检查：
| 检查项 | RESTful API | 事件驱动 API |
|---|---|---|
| 资源/事件命名规范 | ✅ 复数名词，小写，连字符分隔 | ✅ 领域.实体.动作（如 order.created） |
| 版本策略 | ✅ URI路径版本（/v1/） | ✅ Schema Registry兼容性策略 |
| 契约文件 | ✅ OpenAPI 3.0+ | ✅ AsyncAPI + Avro/Protobuf Schema |
| Mock生成能力 | ✅ 支持（如Prism、WireMock） | ✅ 支持（基于Schema生成Mock事件） |
| 错误响应标准化 | ✅ RFC 7807 Problem Details | ✅ 死信队列 + 错误事件Schema |
| 幂等性保证 | ✅ 方法语义 + 幂等键 | ✅ 事件ID + 去重表 |
治理工具推荐：使用Spectral（OpenAPI lint）、AsyncAPI CLI（事件契约校验）、Apicurio Registry（Schema管理）以及Pact（消费者驱动契约测试）构建完整的API治理工具链。