OpenAPI规范同步工作流，包含差异报告和/api-sync命令

# 在此项目中设置 OpenAPI 规范同步工作流 我想要与其他仓库中相同的后端规范工作流：一个脚本，用于将实时 OpenAPI 规范与本地快照进行差异比较，并生成一份**面向前端**的变更报告，外加一个 `/api-sync` 斜杠命令，用于将该报告转化为分阶段计划。 开始前请根据仓库填写以下内容（只有在你无法确定时才问我）： - **规范来源**：自己查找 - 请参阅第 0 部分。在查看之前不要问我 URL。你找到的任何内容都将成为脚本的默认值，可通过 `OPENAPI_URL` 环境变量覆盖。 - **快照路径**：`api-spec/openapi.yaml` · **报告路径**：`api-spec/CHANGES.md` - **要交叉引用的源根目录**：`src/`（根据此仓库的布局进行调整） - **响应验证库**：zod（如果此仓库使用其他库，请调整） - **快照是否纳入 git？** 将 yaml 文件**加入 gitignore**（太大/对历史记录来说太嘈杂），但**提交 `CHANGES.md`** - 生成的报告是变更内容及时间的持久记录。同时忽略 `api-spec/openapi-*.yaml` 和 `api-spec/CHANGES-*.md`（带日期的手动归档）。 首先阅读此仓库（包管理器、脚本约定、API 调用和响应模式的编写方式），并匹配其风格。不要凭空编造路径 - 使用 grep 查找真实路径。 --- ## 第 0 部分 - 在编写任何内容之前先找到规范 首先执行此操作并告诉我你发现了什么。不要猜测 URL，并且在此步骤无结果之前不要问我。 **1. 文档 - 最便宜的地方，通常也是正确的。** `README.md`、`CLAUDE.md`、`AGENTS.md`、`CONTRIBUTING.md`、`docs/` 下的任何内容、`.github/`、`.cursor/rules/`、`*.http`/`*.rest` 临时文件或 wiki 检出。URL 通常出现在散文文本中（“API 文档：…/swagger”）、设置步骤中或后端仓库链接旁边： ```bash grep -rniE 'swagger|openapi|api-?docs|redoc|\/v3\/api-docs' --include='*.md' --include='*.mdx' --include='*.txt' --include='*.http' --include='*.rest' . | grep -v node_modules ``` 两个注意事项：**Swagger UI 链接**（`…/swagger-ui/index.html`、`…/docs`、`…/redoc`）是 HTML 页面，不是规范 - 从中推导出机器 URL（`/swagger-ui/index.html` → `/v3/api-docs`，`/docs` → `/openapi.json`，`/redoc` → 其 HTML 中的 `spec-url`），并使用 curl 验证。此外，文档 URL 可能**已过时** - 在采用之前确认其是否响应，并告诉我 README 是否指向了无效位置。 **2. 仓库中或附近已有的规范文件** - 通常有人会放置一个： ```bash find . -path ./node_modules -prune -o -iregex '.*\(swagger\|openapi\|api-docs\).*\.\(ya?ml\|json\)' -print git ls-files | grep -iE 'swagger|openapi|api-docs' ``` 同时检查 `node_modules/.cache/`、`.next/cache/`、`dist/`、`build/`、`coverage/` 以及任何被 gitignore 的 `api/`、`api-spec/`、`docs/`、`schemas/` 文件夹 - 之前的代码生成运行通常会在那里留下副本。过时的缓存副本仍然有用：它是**用于初始化快照的基线**，因此第一次真正的差异比较是有意义的，而不是“一切都是新的”。如果找到，请说明其年龄（`git log -1` / 文件修改时间），然后再决定是否信任它。 **3. 已指定来源的生成器配置** - 这是信号最强的命中，因为它指向团队实际使用的任何 URL 或路径： ```bash grep -rniE 'openapi|swagger|api-docs' --include='*.json' --include='*.ts' --include='*.js' --include='*.mjs' --include='*.yaml' --include='*.yml' --include='.env*' --include='Makefile' --include='*.sh' -l . | grep -v node_modules ``` 特别查找：`openapi-typescript` / `orval.config.*` / `kubb.config.*` / `swagger-typescript-api` / `@hey-api/openapi-ts` 配置、package.json 中类似 `openapi` 的 npm 脚本、`.env*` API 基础 URL、`docker-compose.yml` 服务 URL、CI 工作流步骤，或已提交的生成客户端，其头部注释引用了其源规范。 **4. 从 API 基础 URL 推导。** 如果只找到基础 URL，请在问我之前探测该后端框架的常规路径 - FastAPI `/openapi.json`、Spring/springdoc `/v3/api-docs`（+ `.yaml`）、ASP.NET `/swagger/v1/swagger.json`、NestJS `/api-json`、Rails/rswag `/api-docs/v1/swagger.yaml`，以及普通的 `/openapi.yaml` 和 `/swagger.json`： ```bash curl -sS -o /dev/null -w '%{http_code} %{content_type} %{url_effective}\n' <BASE>/openapi.json ``` 报告哪些路径有响应。如果它们都需要认证，请说明 - 不要将令牌硬编码到脚本中。 **5. 都不行？** 然后问我，并告诉我你排除了哪些选项。 ### 如果规范无法通过 HTTP 访问 不要强行设计获取方式。将来源设为单个 `SPEC_SOURCE`，它可以是 **URL、本地路径或 shell 命令**（例如后端仓库自己的 `make openapi`，或兄弟检出中的生成文件），按此顺序解析：`--to <file>` 标志 → `OPENAPI_URL` 环境变量 → 你发现的默认值。下游的所有内容 - 差异比较、报告、快照 - 均不变。在 `CLAUDE.md` 中说明此仓库使用哪个选项以及如何刷新它。 ## 第 1 部分 - `scripts/sync-api.mjs` 一个依赖轻量的 Node ESM 脚本（`js-yaml` 是唯一的新依赖；使用仓库的包管理器）。标志： ``` node scripts/sync-api.mjs 获取远程 → 与快照差异比较 → 写入报告 + 覆盖快照 node scripts/sync-api.mjs --check 仅差异比较，快照不变，如有漂移则退出 1（适合 CI） node scripts/sync-api.mjs --from <file> 与 <file> 差异比较，而不是快照 node scripts/sync-api.mjs --to <file> 将 <file> 视为“远程”而不是获取（离线） node scripts/sync-api.mjs --json 同时将原始差异以 JSON 形式打印到标准输出 ``` 在 package.json 中添加 `"sync:api": "node scripts/sync-api.mjs"`。 **如果尚不存在快照**：将获取的规范写为快照，打印“已初始化 - 在后端发布后重新运行以查看差异”，退出 0。切勿将整个 API 报告为“新增”。例外：如果第 0 部分发现了较旧的缓存/放置规范，则改为从**该规范**初始化快照，并在首次运行时与实时规范进行真实差异比较 - 告诉我缓存副本的日期，以便我知道基线的含义。 ### 必须差异比较的内容 将 `paths` 展平为 `"GET /a/b"` → 操作映射，并分别差异比较操作 *和* `components.schemas`： **操作** - 新增 / 移除 / 变更 - 参数：新参数（标记 `required`）、必填↔可选翻转、枚举值新增/移除 - 按 `in:name`（或 `$ref` 参数的 `ref:Name`）键控参数，而不是按数组索引 - 请求体和成功响应模式：如果 `$ref` 名称变更，报告重命名；如果形状是**内联**的（无 `$ref`），则在此处差异比较其属性 - 未命名模式在此处或无处差异比较。将 `allOf: [$ref]` 包装器解析为基础名称，并将 `oneOf`/`anyOf` 联合渲染为 `A | B`（增加/减少联合成员是真实的行为变更）。 - 新增/移除非 2xx 状态码 - 安全要求变更、新标记为 `deprecated` **模式** - 属性新增（标记必填）/ 移除 / 重新类型化 - 枚举值新增或移除（在模式上以及每个属性上，包括 `items.enum`） - 必填↔可选翻转 ### 使此报告值得拥有的两件事 1. **从响应文本中提取 `error_code`。** 机器错误码通常只在每个非 2xx 响应的 `description` 文本中记录（“… already an active member (already_member)”），因此我们需要处理的新分支在模式级差异中看起来像*没有变化*。按**上下文而非词汇**解析它们：`(...)` 内的标记、类似 `error_code` 的文本后的标记，以及出现在某个模式的字面 `error_code` 枚举中的任何 snake_case 标记。**不要**过滤掉与字段名或枚举值冲突的标记 - 这些冲突正是最重要的代码。丢弃由“字段 X”措辞引入的标记（这些是字段名，不是代码）。报告新增的代码，对于不再被记录的代码，在源代码中 grep `"that_code"` 并说明**哪个文件对其进行了分支** - 那是死分支。 2. **将每个变更与实际代码交叉引用。** 通过 `git ls-files --cached --others --exclude-standard <src root>` 一次性加载每个源文件（包括未跟踪文件，以便本次会话添加的调用点计入；跳过已列出但从工作树中删除的文件），然后： - **路径的调用点**：将路径参数转换为单段通配符，并要求匹配以引号/反引号/`?` 结尾，以便 `/orgs/{id}` 不匹配 `/orgs/${id}/archive`。每个移除/变更的操作列出其调用点，或“⛔ 无调用点”。 - **模式镜像**：找到保存规范模式的响应验证镜像的文件 - 在任何位置匹配 `fooBarSchema`，以及**仅在 `schemas.ts` 内部**匹配裸 PascalCase 名称（在其他位置会与无关的 TS 标识符冲突）。根据此仓库实际使用的命名约定进行调整 - 先 grep。 - 路径已在 `src/` 中引用的新操作会得到“⚠️ 路径已被引用 - 检查方法”的注释。 ### 报告格式（`api-spec/CHANGES.md`） 头部包含生成日期、基线标签、规范 `info.version`，以及前后操作和模式计数；然后是一个小的新增/移除/变更表；然后是以下顺序的部分： - `## 🔴 移除的操作 - 如果我们调用则破坏`（附调用点） - `## 🟡 变更的操作`（每个变更的嵌套项目符号 + 调用点） - `## 🟢 新增的操作`，按路径区域分组（第一段，对此 API 的前缀进行合理的特殊处理）- 摘要、响应模式、请求体模式 - `## 🔴 移除的模式`（附镜像文件） - `## 🟡 变更的模式` - **镜像的优先排序并加粗显示镜像文件**，因为这些可能今天就会破坏解析；其余仅供参考 - `## 🟢 新增的模式`（一行逗号分隔） 如果没有变化，正文恰好为“自上次快照以来无变化。”在文件顶部加上“请勿手动编辑”。 在决策不显而易见的地方为脚本添加注释（error_code 启发式、路径匹配器的结尾锚点、为何包含未跟踪文件）- 未来的我会阅读这些。 ## 第 2 部分 - `.claude/commands/api-sync.md` 一个斜杠命令（`/api-sync [scope]`，scope 可选，也接受 `implement`），用于运行工作流。前置元数据：`description` + `argument-hint`。步骤： 1. **差异比较** - 运行 `npm run sync:api`，读取 `api-spec/CHANGES.md`。指出报告可能标记但无法决定的两个判断调用：实时调用点上变更的**请求体**即使没有模式镜像也是可操作的（我们手动构建请求体），而新的**`error_code`** 是我们尚未拥有的分支 - 如果是字段错误，它必须内联渲染在字段上，而不仅仅是 toast。如果报告说无变化，请说明并停止 - 不要凭空创造工作。 2. **将每个项目分类为**：破坏性（P0）· 静默错误 - 镜像模式增加了必填字段或枚举值增长到我们的验证器拒绝的程度（P0）· 现在不完整 - 手动构建的请求体增加了字段，或我们未分支的新 `error_code`（P1）· 取消模拟屏幕（P1）· 扩展屏幕（P2）· 全新功能（P3）· 仅后端（丢弃）。切勿跳过任何项目；如果无处适合，将其列为开放问题。对照代码验证每个分类，而不是假设 - 打开指定的镜像文件，grep 模拟夹具，确认屏幕存在。 3. **编写计划** - 在 `ROADMAP.md`（或此仓库的等效文件；如果没有则创建一个）中写入带日期的部分，按这些优先级排序，并分阶段使每个阶段可独立交付。每个项目：变更的端点和文件、用户之后可以做什么而今天不能（工作的重点 - 不是“连接端点 X”）、以及是否被阻塞以及由谁阻塞。每个项目一行。然后更新此仓库维护的任何覆盖率/跟踪文档。 4. **在聊天中报告** - 用一段通俗语言说明后端交付的内容、当前损坏的内容及要修复的文件、每个阶段一行，以及仅针对后端开发人员的真实问题。到此为止；仅当参数包含 `implement` 时，构建**仅第 1 阶段**，然后运行此仓库的类型检查 + lint，并在继续之前报告。 ## 第 3 部分 - 接入 - 添加 gitignore 条目。 - 在 `CLAUDE.md` 中添加简短的**后端变更工作流**部分（如果缺失则创建）：快照是本地且被 gitignore 的，`CHANGES.md` 是提交的记录，`CHANGES.md` 是生成的因此切勿手动编辑，当后端开发人员说已发布时使用 `/api-sync`，`npm run sync:api -- --check` 用于检测漂移，以及在大后端变更前归档带日期的 `api-spec/openapi-YYYY-MM-DD.yaml` 作为提交的参考点的习惯。 - 通过运行脚本一次来初始化快照，并向我展示第一份报告 - 外加一行说明规范来源，以及如果从缓存副本初始化，其过时程度。