1. 课程导论：OpenAPI 迁移背景、数据契约概念、冒烟检查在迁移中的核心价值

1.1 OpenAPI 迁移背景：从单体到微服务的契约之痛

随着企业业务规模增长，单体架构逐渐暴露出部署耦合、扩展困难、技术栈锁定等问题。越来越多的团队选择将单体应用拆解为微服务，或对遗留系统进行 API 网关迁移。在这一过程中，API 接口的重新定义、路由重写、参数变更、响应结构调整成为高频操作。

迁移的核心挑战并非代码重构本身，而是接口行为的一致性保障。一个典型的迁移场景如下：

这些问题的根源在于：迁移前后，接口的“数据契约”发生了隐性断裂。传统测试往往只关注功能正确性，而忽略了接口结构、类型、约束的精确匹配。

1.2 数据契约概念：API 世界的“宪法”

数据契约（Data Contract） 是指 API 提供方与消费方之间，关于数据交换格式、类型、约束、语义的正式约定。在 OpenAPI 语境下，数据契约通常由 openapi.yaml 或 openapi.json 文件承载，包含以下核心要素：

• 路径与操作：GET /users/{id} 的语义、HTTP 方法、参数位置。
• 请求参数：query、path、header、cookie 参数的类型、是否必填、默认值。
• 请求体：Content-Type、Schema 结构、字段类型与嵌套关系。
• 响应体：状态码对应的 Schema、字段类型、枚举值、格式约束（如 date-time）。
• 安全方案：认证方式、作用域、Token 位置。

数据契约与普通接口文档的区别在于：

1.3 冒烟检查在迁移中的核心价值

冒烟检查（Smoke Testing） 源自硬件测试领域，指在系统通电后先检查是否冒烟——如果冒烟，则立即停止，不再进行后续深度测试。在 OpenAPI 迁移场景中，冒烟检查被定义为：迁移完成后，对核心数据契约进行快速、轻量、自动化的验证，确保接口的基本结构、类型、约束与迁移前一致。

冒烟检查与全面回归测试的区别：

冒烟检查在迁移中的三大核心价值：

1. 早期阻断：在迁移部署后的几分钟内，即可发现路径错误、字段缺失、类型不匹配等致命问题，避免影响下游消费方。
2. 低成本验证：无需搭建复杂的测试环境，仅需一个 HTTP 客户端 + 一份 OpenAPI 规范文件即可执行。
3. 契约对齐保障：强制迁移后的实际接口行为与数据契约保持一致，防止“代码改了，文档忘了”的常见陷阱。

1.4 本课程的学习路径

本课程将围绕以下主线展开：

• 第 2-5 章：数据契约的建模与 OpenAPI 规范深度解析，包括 Schema 定义、参数校验规则、响应结构设计。
• 第 6-10 章：冒烟检查框架的设计与实现，包括检查项分类、断言引擎、报告生成。
• 第 11-15 章：迁移场景实战，包括路径重写、字段映射、协议转换的契约验证。
• 第 16-20 章：自动化集成与 CI/CD 流水线中的冒烟检查实践。
• 第 21-25 章：高级主题，包括版本兼容性检查、多环境契约管理、性能基线。
• 第 26-30 章：工程化落地与团队协作，包括契约评审流程、工具链选型、度量指标。