API Diff Skill

对比两个版本的 OpenAPI 文档或生成的 API 文件，检测接口变更。

使用场景

1. 更新 API 后自动检查：运行 api:generate 后自动对比新旧接口
2. 手动对比：对比两个不同的 OpenAPI 文档
3. CI/CD 集成：在部署前检查破坏性 API 变更

如何调用

在生成 API 后自动对比

pnpm run api:generate

生成器会自动调用对比逻辑，检查是否有接口变更。

手动对比两个文档

# 对比两个 OpenAPI markdown 文档
node scripts/apiDiff.js docs/api-specs/user/api1.md docs/api-specs/user/api1-new.md

# 对比整个模块目录
node scripts/apiDiff.js docs/api-specs/user/ docs/api-specs/user-new/

# 对比生成的 API 文件
node scripts/apiDiff.js src/api/user.js src/api/user-new.js

对比维度

1. 接口增删：新增或删除的接口
2. 参数变更：
   • 新增必填参数（破坏性变更）
   • 删除参数（破坏性变更）
   • 参数类型变更（破坏性变更）
   • 新增可选参数（非破坏性）
3. 返回值变更：
   • 返回结构变更
   • 字段类型变更
4. HTTP 方法变更：GET ↔ POST（破坏性变更）

输出格式

对比结果会以以下格式输出：

=== API 变更检测报告 ===

📦 模块: user
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ 新增接口 (1):
  + getUserProfile

⚠️  修改接口 (2):
  ↪ editUserInfo
    ✗ [破坏性] 删除必填参数: sms_code
    ✓ [非破坏性] 新增可选参数: avatar

  ↪ getUserInfo
    ✓ [非破坏性] 新增可选参数: include_profile

❌ 删除接口 (1):
  - deleteUserAccount

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
总计: 1 新增, 2 修改, 1 删除
⚠️  检测到 1 个破坏性变更，请仔细检查业务逻辑！

退出码

• 0: 无变更或仅有非破坏性变更
• 1: 检测到破坏性变更（可用于 CI/CD 失败）

配置选项

可以通过环境变量配置：

# 严格模式：任何变更都返回失败码
API_DIFF_STRICT=true node scripts/apiDiff.js ...

# 输出 JSON 格式（用于程序解析）
API_DIFF_FORMAT=json node scripts/apiDiff.js ...

注意事项

1. 对比逻辑基于 OpenAPI 规范，确保文档格式正确
2. 破坏性变更需要在业务代码中做兼容处理
3. 新增接口通常不需要修改现有代码
4. 删除接口前请确认没有地方在使用