📚 课程目录第4章迁移场景分析

4. 迁移场景分析：服务拆分、网关升级、协议转换、版本升级等典型迁移场景

OpenAPI 迁移并非单一操作，而是由多种底层架构变更驱动的复合工程。不同的迁移场景对数据契约的破坏模式、影响范围、回滚策略截然不同。本章逐一拆解四种典型场景，并给出每种场景下冒烟检查的针对性设计。

4.1 服务拆分（单体 → 微服务）

单体应用拆分为多个微服务时，原本的内部方法调用变为跨进程 HTTP/RPC 通信。数据契约从“隐式约定”变为“显式接口定义”，最容易出现字段丢失、类型不兼容、边界模糊等问题。

  典型破坏模式：
  字段下沉：原单体返回 20 个字段，拆分后 A 服务只返回 12 个，B 服务返回 8 个，调用方需合并。
类型窄化：原字段为 integer(int64)，拆分后变为 integer(int32)，大数值溢出。
必填变可选：原接口 required 字段在拆分后因数据源不同变为 nullable。

检查维度	单体基线	拆分后契约	冒烟检查项
字段数量	20	12 + 8（需合并）	字段覆盖率 ≥ 95%
数据类型	int64	int32	类型宽度不降级
必填约束	required	optional	非空率 ≥ 99.9%

4.2 网关升级（API Gateway 替换）

网关升级（如从 Kong 迁移到 APISIX，或自研网关替换）可能引入路由重写、Header 转换、请求/响应拦截等中间层逻辑。数据契约在网关层被“透传”或“改写”，冒烟检查必须覆盖网关前后的契约一致性。

实践建议：在网关前后各部署一个契约探针，同时捕获原始请求和网关转发后的请求，对比 OpenAPI 请求/响应结构是否一致。重点关注 Header 丢失、路径参数重写、响应体截断三类问题。

网关行为	契约风险	冒烟检查方法
路径重写	路径参数名变更（如 `/v1/users/{id}` → `/api/users/{userId}`）	参数名映射校验
Header 转换	认证 Header 被剥离或重命名	Header 白名单检查
响应体拦截	网关注入额外字段或截断长响应	响应体 Schema 严格匹配

4.3 协议转换（REST ↔ gRPC / GraphQL）

协议转换是数据契约破坏的高发区。REST 的 JSON 无类型约束与 gRPC 的强类型 Protobuf 之间转换时，null 与 0、"" 与 undefined、浮点精度、枚举值映射等问题极易引发线上故障。

高风险区：

null 语义丢失：REST 中 null 表示“未设置”，gRPC 中 null 需用 google.protobuf.StringValue 包装，转换遗漏导致默认值污染。
浮点精度：JSON 的 number 转为 gRPC 的 float 时，双精度→单精度可能丢失小数位。
枚举越界：REST 传入未定义的枚举值，gRPC 直接拒绝或转为 UNRECOGNIZED。

// REST 响应示例
{
  "user": {
    "name": "Alice",
    "age": null,        // 语义：年龄未设置
    "score": 1234567.89 // 双精度浮点
  }
}

// gRPC 转换后（错误）
message User {
  string name = 1;
  int32 age = 2;       // null → 0，语义丢失
  float score = 3;     // 精度丢失 → 1234567.875
}

4.4 版本升级（OpenAPI 2.0 → 3.0 / 3.1）

OpenAPI 规范版本升级本身不改变业务逻辑，但规范差异可能导致工具链解析失败、校验规则变化、文档生成异常。冒烟检查需覆盖规范兼容性、工具链适配、示例数据迁移三方面。

差异点	OpenAPI 2.0	OpenAPI 3.0 / 3.1	冒烟检查
响应定义	`definitions`	`components/schemas`	引用路径正确性
请求体	`body` + `formData`	`requestBody` + `content`	Content-Type 覆盖
安全方案	`securityDefinitions`	`components/securitySchemes`	认证流程连通性
示例	无标准字段	`example` / `examples`	示例数据 Schema 匹配

4.5 场景对比与冒烟策略选择

不同迁移场景的冒烟检查策略侧重点不同。下表给出各场景的推荐检查优先级和工具选型参考。

迁移场景	最高风险项	推荐检查工具	检查频率
服务拆分	字段覆盖率	openapi-diff + 自定义字段扫描	每次部署前
网关升级	Header 丢失	网关前后抓包对比	灰度阶段持续
协议转换	null 语义	protobuf-json 互转测试	全量回归
版本升级	引用路径	openapi-diff + 工具链集成测试	一次迁移 + 回归

  核心原则：无论哪种迁移场景，冒烟检查都应覆盖“契约结构一致性”和“运行时数据兼容性”两个层面。前者通过静态对比 OpenAPI 规范文件实现，后者通过真实请求-响应采样验证。两者缺一不可。