api-contract-testlisted

> 🔧 项目无关骨架版 · 项目专属配置见 PROJECT-PROFILE.md # Skill · api-contract-test > 一句话定位：以 `code/<仓库名>/v3/api-docs` OpenAPI（后端 OpenAPI 入口见 PROJECT-PROFILE.md § 五）为事实源，比对 `tools/api-collection/` Bruno 集合的请求 / 响应 / 字段 / 枚举 / 分页 / 状态码，输出**契约偏差报告**。发现的 `blocker` / `critical` 偏差自动登记为 `DIFF-XXX`（type=`API_CONTRACT`）。 ## 触发条件 - 用户明确要求「跑契约对比 / API 偏差核查」 - 同步代码（`sync-research-code` 技能）后必跑 - 基线发布前必跑 - 后端发布新接口或字段变更后必跑 ## 输入 | 输入 | 是否必填 | 示例 | |---|---|---| | 当前生效基线 | ✅ | `B1.0.x` | | OpenAPI 来源 | ✅ | 拉取 `http://localhost:8080/v3/api-docs` 或既有 `reports/<版本>/openapi.json` | | Bruno 环境 | ✅ | `Local` / `Staging` | | 报告输出位置 | ✅ | `test/reports/<版本>/api-contract-diff.md` | ## 工具 - **Bruno CLI**：`bru run --env <env> --reporter-json <out.json>` - **OpenAPI 拉取**：`curl http://localhost:8080/v3/api-docs > openapi.json`（启动后端后） - **解析**：可用 Node `openapi-types` / `yaml` / `jsonpath` 或纯文本对比 ## 步骤 1. **基线锁定 + 目录校验** - 确认 `test/reports/<版本>/` 目录存在 2. **OpenAPI 拉取并归档** - 启动后端（启动命令见 PROJECT-PROFILE.md § 五，如 Java 的 `./mvnw -B spring-boot:run`） - `curl <后端 OpenAPI 入口，见 PROJECT-PROFILE § 五> > test/reports/<版本>/openapi.json` - 校验 JSON 可解析、`paths` 段非空 3. **Bruno 集合扫描** - 遍历 `test/tools/api-collection/**/*.bru` - 解析每个 `.bru` 的 `meta` / `<method>` 段 / `assert` 段 / `headers` / `body` 4. **路径对比（Path Drift）** - OpenAPI 中存在但 Bruno 缺：登记为「Bruno 缺失」（提示补 .bru） - Bruno 中存在但 OpenAPI 缺：登记为「OpenAPI 缺失」（提示后端确认） - 两侧路径模板不一致（如 `/orders/{id}` vs `/orders/{orderId}`）：登记为「path drift」 5. **字段对比（Field Drif