4. 自动化弃用检测：基于 OpenAPI/Swagger 的弃用标记、代码扫描工具集成、CI/CD 流水线中的弃用检查

API 弃用管理的核心挑战在于“发现滞后”——当服务端标记某个接口为废弃时，消费者往往在数月后通过生产故障才得知。本章构建一套自动化弃用检测体系，将检测时机从“运行时崩溃”前置到“代码提交时”，通过 OpenAPI 规范标记、静态代码扫描与 CI/CD 流水线门禁三个层次，实现弃用信息的零延迟捕获与阻断。

4.1 基于 OpenAPI/Swagger 的弃用标记规范

OpenAPI 3.0 规范原生支持 deprecated: true 字段，可作用于路径、操作或 Schema 级别。标记粒度直接影响检测精度，推荐采用三级标记策略：

# OpenAPI 3.0 弃用标记完整示例
openapi: "3.0.3"
info:
  title: 用户服务 API
  version: "2.1.0"
paths:
  /api/v1/users:
    get:
      deprecated: true
      x-deprecation-info:
        sunset: "2025-06-30"
        migration: "https://docs.example.com/migration-v2"
        replacement: "/api/v2/users"
      parameters:
        - name: format
          in: query
          deprecated: true
          x-deprecation-info:
            sunset: "2025-03-31"
            replacement: "Accept header"
      responses:
        '200':
          description: 用户列表
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      deprecated: true
      x-deprecation-info:
        sunset: "2025-06-30"
        replacement: "UserV2"
      properties:
        id:
          type: integer
        name:
          type: string

4.2 代码扫描工具集成：从规范到源码的跨层检测

仅检测 OpenAPI 规范文件是不够的——消费者代码中可能硬编码了已弃用的 API 路径或参数。需要将检测范围扩展到客户端代码仓库，实现“规范-源码”双向校验。

推荐集成工具链及检测规则：

• Spectral：自定义规则检查 deprecated 标记的完整性与 x-deprecation-info 必填字段。
• openapi-diff：对比两个版本规范，自动识别新增的 deprecated 标记并生成变更报告。
• 自定义 AST 扫描器：针对 Java/Go/Python 客户端代码，解析 HTTP 客户端调用中的 URL 路径，与弃用接口列表做模式匹配。
• API 网关日志分析器：从网关访问日志中提取请求路径，与已知弃用接口做离线匹配，发现“静默调用”。

4.3 CI/CD 流水线中的弃用检查门禁

将弃用检测嵌入 CI/CD 流水线，形成“提交-检测-阻断-通知”的自动化闭环。以下为 Jenkins/GitLab CI 流水线中的典型阶段配置：

# .gitlab-ci.yml 弃用检测阶段示例
stages:
  - lint
  - deprecation-check
  - build
  - test
  - deploy

deprecation-check:
  stage: deprecation-check
  image: node:18-alpine
  script:
    # 1. 安装检测工具
    - npm install -g @stoplight/spectral-cli
    - npm install -g openapi-diff

    # 2. 规范合规检查
    - spectral lint api/openapi.yaml --ruleset .spectral/deprecation-rules.js

    # 3. 版本差异检测（与基线对比）
    - openapi-diff api/openapi-baseline.yaml api/openapi.yaml --markdown > deprecation-report.md

    # 4. 客户端源码扫描
    - python scripts/scan-client-code.py --spec api/openapi.yaml --src ./client/

    # 5. 生成 SARIF 报告
    - python scripts/generate-sarif.py --input deprecation-report.md --output deprecation.sarif

  artifacts:
    paths:
      - deprecation-report.md
      - deprecation.sarif
    when: always

  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request"'
      when: always

门禁策略分为三个等级，可根据团队成熟度逐步收紧：

4.4 灰度验证中的弃用检测联动

弃用检测不应止步于 CI/CD 门禁，还需与灰度发布体系联动，在流量切换过程中实时验证弃用接口的实际调用情况：

灰度联动检测的关键指标与阈值建议：

• 弃用接口调用率：灰度版本中弃用接口的请求占比，超过 5% 触发警告。
• 调用量突增比：与基线相比的调用量变化率，超过 50% 触发硬阻断。
• 错误率关联：弃用接口的 4xx/5xx 错误率是否同步上升，用于判断迁移是否导致兼容性问题。
• 客户端版本分布：调用弃用接口的客户端 SDK 版本分布，识别未升级的消费者。