API_DIFF_GUIDE.md
7.24 KB
API 变更检测工具使用指南
概述
API 变更检测工具是 OpenAPI 转 API 文档生成器的增强功能，可以自动检测接口变更并识别破坏性变更，帮助开发者在更新接口时及时发现潜在问题。
工作原理
- 基线建立：首次运行时自动建立 API 基线
- 变更检测：后续运行时对比当前版本与基线版本
- 分类标记：自动区分破坏性变更和非破坏性变更
- 自动更新：检测完成后自动更新基线
使用方式
自动检测（推荐）
每次运行 API 生成器时自动检测变更：
node scripts/generateApiFromOpenAPI.js
输出示例：
=== OpenAPI 转 API 文档生成器 ===
输入目录: /Users/huyirui/program/itomix/git/manulife-weapp/docs/openAPI
输出目录: /Users/huyirui/program/itomix/git/manulife-weapp/src/api
💾 备份当前 OpenAPI 文档...
找到 2 个模块: order, user
处理模块: order
找到 2 个 API 文档
✓ getDetail: 获取订单详情
✓ getList: 获取订单列表
📝 生成文件: /Users/huyirui/program/itomix/git/manulife-weapp/src/api/order.js
处理模块: user
找到 2 个 API 文档
✓ editUserInfo: 修改我的信息
✓ getUserInfo: 查询我的信息
📝 生成文件: /Users/huyirui/program/itomix/git/manulife-weapp/src/api/user.js
✅ API 文档生成完成！
🔍 开始检测 API 变更...
=== API 变更检测报告 ===
📦 对比范围: 2 个旧接口 → 2 个新接口
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⚠️ 修改接口 (1):
↪ getUserInfo - 查询我的信息
✓ [非破坏性] 新增可选 query 参数: include_profile
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
总计: 0 新增, 1 修改, 0 删除
✅ 未检测到破坏性变更
📝 更新 API 基线...
手动检测
可以独立运行对比脚本：
# 对比两个 OpenAPI 文档
node scripts/apiDiff.js docs/openAPI/user/getUserInfo.md docs/openAPI/user/getUserInfo-new.md
# 对比两个模块目录
node scripts/apiDiff.js docs/openAPI/user/ docs/openAPI/user-new/
变更类型说明
非破坏性变更（✓）
这些变更不会影响现有代码：
- 新增可选参数：客户端可以不传，不影响现有调用
- 删除可选参数：服务端不再接收，但客户端不传也没问题
- 必填参数变可选：限制放宽，兼容性提升
- 返回值新增字段：客户端可以选择性使用
破坏性变更（✗）
这些变更需要检查业务逻辑：
- 新增必填参数：现有调用会缺少参数
- 删除必填参数：现有调用可能传了被删除的参数
- 可选参数变必填：现有调用可能不传该参数
- 参数类型变更：可能导致类型错误
- HTTP 方法变更：GET ↔ POST 会导致调用失败
- 删除接口：所有调用该接口的地方需要修改
输出格式
文本格式（默认）
=== API 变更检测报告 ===
📦 对比范围: 2 个旧接口 → 2 个新接口
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ 新增接口 (1):
+ getUserProfile - 获取用户详细资料
⚠️ 修改接口 (2):
↪ editUserInfo - 修改我的信息
✗ [破坏性] 删除必填 body 参数: sms_code
✓ [非破坏性] 新增可选 body 参数: avatar
↪ getUserInfo - 查询我的信息
✓ [非破坏性] 新增可选 query 参数: include_profile
❌ 删除接口 (1):
- deleteUserAccount - 删除用户账号
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
总计: 1 新增, 2 修改, 1 删除
⚠️ 检测到 1 个破坏性变更，请仔细检查业务逻辑！
JSON 格式
设置环境变量输出 JSON 格式（便于程序解析）：
API_DIFF_FORMAT=json node scripts/apiDiff.js <oldPath> <newPath>
输出示例：
{
"summary": {
"added": 1,
"modified": 2,
"removed": 1,
"breakingChanges": 1
},
"added": [
{
"name": "getUserProfile",
"summary": "获取用户详细资料",
"method": "GET",
"path": "/srv/"
}
],
"modified": [
{
"name": "editUserInfo",
"summary": "修改我的信息",
"breakingChanges": [
"删除必填 body 参数: sms_code"
],
"nonBreakingChanges": [
"新增可选 body 参数: avatar"
]
}
],
"removed": [
{
"name": "deleteUserAccount",
"summary": "删除用户账号",
"method": "POST",
"path": "/srv/"
}
]
}
CI/CD 集成
严格模式
任何变更都返回失败码：
API_DIFF_STRICT=true node scripts/apiDiff.js <oldPath> <newPath>
检查退出码
node scripts/apiDiff.js <oldPath> <newPath>
EXIT_CODE=$?
if [ $EXIT_CODE -eq 1 ]; then
echo "检测到破坏性变更或启用严格模式"
exit 1
fi
退出码：
-
0: 无破坏性变更 -
1: 检测到破坏性变更或严格模式下有任何变更
配置选项
| 环境变量 | 说明 | 默认值 |
|---|---|---|
API_DIFF_FORMAT |
输出格式 (text/json) | text |
API_DIFF_STRICT |
严格模式 (true/false) | false |
存储位置
-
基线文件：
.tmp/openAPI-temp/ -
临时备份：
.tmp/openAPI-backup/
这些目录已添加到 .gitignore，不会被提交到 git。
常见问题
Q: 首次运行显示"首次运行，已建立基线"？
A: 这是正常的。首次运行时会建立 API 基线，从第二次开始才会检测变更。
Q: 如何重置基线？
A: 删除 .tmp 目录即可：
rm -rf .tmp
Q: 检测到破坏性变更怎么办？
A:
- 仔细检查变更内容
- 确认是否真的需要这个变更
- 如果需要，搜索所有调用该接口的代码并更新
- 如果是第三方接口变更，联系后端确认
Q: 可以对比生成的 JS 文件吗？
A: 当前版本不支持对比生成的 JS 文件，请对比 OpenAPI 文档。
Q: 为什么有些参数没有检测到变更？
A: 工具会自动过滤 a 和 f 参数（业务标识符），专注于业务参数。
最佳实践
- 每次更新接口后运行检测：及时发现问题
- 仔细阅读破坏性变更报告：不要忽略警告
- 在 CI/CD 中集成：自动化检测流程
- 定期审查非破坏性变更：确保接口设计合理
- 保留接口变更历史：便于追溯问题
技术实现
核心文件
-
scripts/apiDiff.js- 核心对比逻辑 -
scripts/generateApiFromOpenAPI.js- 集成调用 -
.claude/custom_skills/api-diff/skill.md- Skill 文档
对比维度
- 接口级别：新增、删除、修改
- 参数级别：名称、类型、是否必填
- HTTP 方法：GET ↔ POST
- 返回值：结构、字段类型
检测逻辑
- 基于参数名称和类型对比
- 智能识别必填/可选参数变化
- 自动分类破坏性/非破坏性变更
- 支持模块级别和接口级别对比
贡献
如果发现问题或有改进建议，欢迎提交 Issue 或 Pull Request。