feat(FB-06): OpenAPI 驱动的前后端 API 契约对齐 + CI 接入 · #2

qshenzhang/anta-workshopdemo

Public

WeChat Login

Code Issues Pull requests Events Packages Insights

feat(FB-06): OpenAPI 驱动的前后端 API 契约对齐 + CI 接入#2

Merged

Qisen

created 2 weeks ago

feature/foundation-setup

feature/fb-06-api-contract-validation

Edit

OverviewCommits

Files changed

Attachments

Qisen

背景

FB-06 是 foundation-setup 留下的唯一 OPEN 反馈：前后端 API 路径契约没有自动化校验，只能等端到端或人工检查才发现不一致。本轮落地闭环方案。

架构

后端 SpringDoc → OpenApiExportTest → backend/target/openapi.json
                                         ↓
                    openapi-typescript → frontend/src/api/generated/api-types.ts
                                         ↓
                        openapi-fetch → typed apiClient（编译期类型约束）
                                         ↓
                     check-api-contract.mjs → 扫描手写 /api/v1/* 字面量兜底
                                         ↓
                                     .cnb.yml 阻塞合并

6 个 commit

#	Commit	说明
1	`refactor(payment)`	删除 scaffold 生成的 payment 死代码（由新机制首次运行时抓出）
2	`fix(frontend)`	inventory API 路径：`inventorys` → `inventory`（FB-01 修复后前端未同步，同样被抓出）
3	`test(backend)`	`OpenApiExportTest`：mvn test 自动导出 `target/openapi.json`
4	`feat(frontend)`	新增 openapi-typescript/openapi-fetch 依赖 + typed `apiClient` + `check-api-contract.mjs` 校验脚本
5	`chore(ci)`	`.cnb.yml`：push 6 阶段 + PR 完整 verify，对齐 R5 §五真实编译门禁
6	`docs(framework)`	方案沉淀至 `api-docs/SKILL.md §前后端契约对齐`，FB-06 状态改为 RESOLVED

立竿见影的收益

本次实现首次运行契约校验脚本就抓到 2 处真实问题（而非构造示例）：

frontend/src/api/modules/inventory.ts 使用 /api/v1/inventorys/*（FB-01 修复复数后前端没同步）
frontend/src/api/modules/payment.ts + stores/payment.ts + views/payment/* 全是 scaffold 死代码（后端没实现 /api/v1/payments CRUD）

这 2 个问题在原先的工作流里必须等到 E2E 测试或真机运行才会暴露。现在在 CI 的静态阶段就阻塞合并。

方案特点

零运行时依赖：check-api-contract.mjs 只用 Node 标准库，可在任何 CI 环境跑
开发友好：前端跑 npm run gen:api 就能同步最新契约，typed apiClient 路径改错 TS 编译立刻报错
兜底覆盖：字面量扫描能捕获那些还没迁移到 typed client 的旧模块
CI 友好：mvn test 已经会跑 OpenApiExportTest，契约 JSON 自动产出，无需额外 plugin

验证

✅ mvn test-compile BUILD SUCCESS
✅ node --check check-api-contract.mjs 语法通过
✅ 端到端 smoke test：27 前端文件 × 14 后端契约路径，0 违规（修复 2 处后）
✅ 13/13 单元测试稳定
✅ .codebuddy/ lint 0 错误

合并目标

base 选择 feature/foundation-setup 而非 main：因为 foundation-setup 的 PR #1 还没合入 main，这个 PR 需要基于它才能看到代码。PR #1 合入 main 后，此 PR 的 base 可改为 main，或直接 rebase 后一起合。