📚 课程目录第4章 OpenAPI规范与兼容性

OpenAPI规范与兼容性：用规范管住接口变脸

讲API兼容性，绕不开一个东西——OpenAPI规范（以前叫Swagger）。我个人习惯把OpenAPI比作API的“合同”。你想想看，前后端联调、微服务之间调用，如果连合同都没有，那接口一变更，对接方完全靠猜，不出问题才怪。

OpenAPI规范能帮我们解决三个核心问题：接口定义标准化、变更可检测、版本有路可循。下面我一个个展开说。

用OpenAPI把接口“写死”

先聊第一块：怎么用OpenAPI定义接口。说实话，很多团队还在用Word文档写接口说明，或者干脆在群里发个JSON示例。我见过太多次因为字段类型写错导致联调通宵的破事。

OpenAPI的YAML/JSON文件就是你的“接口宪法”。你定义好路径、参数、请求体、响应结构，所有消费者以它为准。

一个最小化的OpenAPI 3.0示例：

openapi: "3.0.3"
info:
  title: 用户服务API
  version: "1.2.0"
paths:
  /users/{userId}:
    get:
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      required: [id, name, email]
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
          format: email

这段定义看着简单，但关键信息全在里面了。/users/{userId}这个路径，参数类型是string，响应结构强制包含id、name、email三个字段。哪一天你想把email改成可选，得先问问自己：接口算不算向后兼容？

嗯，这里要注意：字段级别的变更，是兼容性检测的最小粒度。

变更检测：用工具帮你“找茬”

接口定义好了，接下来是变更检测。API不像代码，编译阶段就能发现类型不匹配。我曾经在一个项目里接手一个老旧API，文档和代码早就对不上了，上线后直接导致下游服务大面积报错。

那之后我学乖了，必须用工具做变更检测。目前常用的方案有两种：

工具/方法	适用场景	能检测什么	局限性
openapi-diff	CI流水线中对比两个版本	Breaking变更（删字段、改类型、缩范围）	对枚举值变动不敏感
spectral + 自定义规则	规范一致性校验	字段命名、禁止使用标签、必填字段缺失	不直接做版本对比
手动review + diff工具	小团队快速对齐	肉眼可见的所有差异	容易漏，尤其YAML结构复杂时

我个人最常用openapi-diff，因为它直接告诉你“这个变更是不是Breaking”。

我常用的做法：每次发版前，把新老两版OpenAPI文件扔进openapi-diff。它会输出一个报告，标明哪些是Breaking（破坏性）变更、哪些是Non-breaking（非破坏性）。Breaking变更必须走版本号major升级，这是铁律。

举个例子，如果你把一个字段的type: integer改成type: string，openapi-diff会标红——这玩意破坏兼容性，下游所有强类型解析全炸。

规范版本迁移：从2.0到3.1，别硬来

OpenAPI规范本身也在演进。2.0（Swagger）、3.0、3.1。每次规范大版本升级，你都得掂量掂量：迁移值不值？怎么迁不疼？

我以前带团队做过一次2.0到3.0的迁移，坑踩了不少。最大的坑是什么？2.0里用definitions的地方，3.0改成了components/schemas。你想想看，几百个接口定义，所有ref路径全得改。

不过别慌，有迁移工具。

# 使用 swagger2openapi 工具
npx swagger2openapi old-swagger.yaml -o new-openapi.yaml

# 校验迁移后的规范
npx @apidevtools/swagger-cli validate new-openapi.yaml

但是，工具只是帮你做了语法转换，语义上的兼容性它管不了。比如2.0里的allowEmptyValue在3.0里取消了，你原本依赖这个特性的地方得手动调整。

警告：规范版本迁移≠API版本升级。OpenAPI 2.0转3.0只是表述方式变了，你的API接口能力没变。千万别在迁移规范时顺便改接口逻辑，两件事混在一起，出了问题你根本不知道是谁的锅。

那什么时候该升级规范版本？我建议三种情况考虑：

新项目直接用最新稳定版（现在是3.1，支持JSON Schema 2020-12）
老项目需要新增复杂结构（比如多态、oneOf/anyOf），3.x比2.0灵活太多
团队要统一API管理平台，平台只支持3.x

否则，别为了赶时髦而迁移。老老实实用2.0也没啥问题，只要你的工具链能正常运转。

兼容性检测的最佳实践

最后总结几点我踩过坑之后整理的做法：

OpenAPI文件必须进版本管理，和代码一起CI。我见过有人把YAML放NAS上，更新了也不通知，那跟没定义一样。
CI里加一步openapi-diff。Breaking变更直接阻断发布，让开发去决定是改代码还是升版本。
规范版本迁移单独走一个分支，迁移完做全量回归，别顺手改接口逻辑。
用spectral维护组织级规范。比如禁止接口返回0作为成功码，这种规则一旦定下来，所有新接口自动遵循。

说白了，OpenAPI就是你API的“蓝本”。蓝本不乱，兼容性就有的查、有的管。蓝本一乱，你连变更了什么都不知道，何谈兼容性？