# API 文档更新工作流(`script/update-api-doc.cjs`) > 本文档说明 `methods/*.json`(接口文档 SSOT)与 `methods/changes/*.json`(变更记录)的**唯一合规写入方式**: > 通过 `npm run doc:api:update -- --spec=` 执行,禁止直接手写这两个目录下的 JSON。 > 内容以 `script/update-api-doc.cjs` 实际实现为准;回归测试见 `test/scripts/update_api_doc.test.cjs`(13 用例)。 ## 1. 命令用法 ```powershell npm run doc:api:update -- --spec= # 正式写入(主文档 + 变更记录) npm run doc:api:update -- --spec= --dry-run # 只校验并打印计划,不写任何文件 npm run doc:api:update -- --spec= --doc-only # 只写 methods/.json,跳过变更记录 npm run doc:api:update -- --help # 打印用法、选项与 spec.newDoc 说明(-h 等价) ``` - `--spec=`:必填;相对路径按项目根目录(`process.cwd()`)解析。缺省报 `Missing required --spec= argument.`;文件不存在报 `Spec file not found: `。 - 脚本底层等价于 `node ./script/update-api-doc.cjs --spec=`,npm 层需要 `--` 分隔符传递参数。 ## 2. spec 结构(固定 spec JSON) ```json { "docName": "system", "docMeta": { "version": "1.2.0", "updatedAt": "2026-09-12" }, "group": { "groupName": "分组展示名", "module": "分组 module" }, "methods": [ { "method": "...", "description": "...", "isNeedAuth": true, "isNeedLogin": false, "headers": [], "params": [], "response": [], "errors": [], "notes": [] } ], "deleteMethods": [ "要删除的.method" ], "change": { "version": "唯一版本号", "date": "2026-09-12", "type": "updated", "summary": "...", "methods": [ "..." ], "notes": [ "..." ] } } ``` | 字段 | 必填 | 说明 | |---|---|---| | `docName` | 是 | 目标文档名;仅允许字母、数字、下划线、横线(`^[a-z0-9_-]+$`)。对应 `methods/.json` 与 `methods/changes/.json` | | `docMeta` | 否 | `{ version, updatedAt, description }` 均可选;写入后覆盖主文档根部的 `version` / `updatedAt` / `description`(`description` 为字符串时生效,可用于更正根说明文案) | | `group` | 是 | `{ groupName, module }` 均为非空字符串。定位已有分组时**先按 `module` 匹配,再按 `groupName`**;找不到则新建分组 | | `methods` | 是 | 至少 1 条 method 文档;按 `group` + `method` 做 upsert,不覆盖其它分组/方法 | | `deleteMethods` | 否 | 要删除的 method 名数组;不能与 `methods` 中的 method 重名,否则报 `Method conflict` | | `change` | 否 | 变更记录对象(`--doc-only` 模式下可省略)。详见第 5 节 | ### 2.1 method 文档条目(`methods[]` 每一条) - 必填键:`method` / `description` / `isNeedAuth`(boolean)/ `isNeedLogin`(boolean)/ `headers`(数组)/ `params`(数组)/ `response`(数组)/ `errors`(数组)。 - `notes` 可选(字符串数组,写入后保留在 method 文档内)。 ### 2.2 upsert 语义 - method 不存在 → `inserted`(追加到目标分组 list 尾部)。 - method 已存在且在同一分组 → `updated`(整条覆盖)。 - method 已存在但在其它分组 → `moved`(从原分组移除后写入目标分组)。 - `deleteMethods` 命中 → `deleted`;未命中 → `delete-not-found`(不报错,仅提示)。 - 脚本逐条打印 `inserted:` / `updated:` / `moved:` / `deleted:` / `delete-not-found:` 行。 ## 3. 字段级硬性校验(报错即拒绝写入) | 校验点 | 规则 | |---|---| | `docName` | 非空字符串,仅字母/数字/下划线/横线 | | `docMeta.description`(可选) | 若提供必须为字符串(可为空串,表示清空根说明);非字符串报 `spec.docMeta.description must be a string.` | | `group.groupName` / `group.module` | 非空字符串 | | `methods[].method` / `description` | 非空字符串;spec 内 method 名不允许重复(`Duplicate method in spec.methods`) | | `methods[].isNeedAuth` / `isNeedLogin` | **必须为 boolean** | | `methods[].headers` / `params` / `response` / `errors` | 必须为数组 | | `headers[]` / `params[]` / `response[]` 每一项 | `name` / `type` / `description` 非空字符串;**`required` 必须为 boolean**(非布尔报 `xxx.required must be a boolean`) | | `source` 字段 | **仅 `params[]` 允许**(`allowSource=true`,如 `query` / `body`);`headers[]` / `response[]` 不校验 `source`,因此不要在这两处写 `source` | | 可选 `list` 字段 | 必须是数组,且每一项必须含 `value` 键 | | `errors[]` 每一项 | 必须含 `code` 键(数字或字符串均可,如 `400` / `5xx`)+ 非空字符串 `message` | | `deleteMethods[]` | 字符串数组;与 `methods[]` 中的 method 重名时报 `Method conflict` | | `change` | 见第 5 节 | ## 4. 新增文档能力(`spec.newDoc`,2026-09-12 新增) 目标 `methods/.json` **不存在**时,spec 必须提供 `newDoc`,脚本自动生成文档骨架后再应用 `group` / `methods`;否则报: ``` Target doc file not found: (provide spec.newDoc to create it) ``` ### 4.1 `newDoc` 字段与规则 | 字段 | 规则 | |---|---| | `module` | **必填**,非空字符串 → 新文档根 `module` | | `description` | 可选,string;缺省 `""` | | `http` | 可选,object;缺省 `{ "path": "", "method": "POST" }` | | `headers` | 可选,array;缺省 `[]` | | `version` / `updatedAt` / `methods` | **保留键**:由骨架统一管理(`version`/`updatedAt` 取自 `docMeta`,`methods` 固定为 `{ groups: [] }`),写在 `newDoc` 里不生效、不参与透传,也不报错 | | 其它未知字段 | 仅接受 plain JSON 值(null/字符串/数字/布尔/对象/数组,递归校验),**原样透传**到新文档根(供未来扩展) | ### 4.2 骨架与落盘行为 - 新文档骨架:`{ module, description, version, updatedAt, http, headers, methods: { groups: [] } }`;`version` 取 `docMeta.version`(缺省 `0.0.0`),`updatedAt` 取 `docMeta.updatedAt`(缺省本地今天 `YYYY-MM-DD`)。 - `methods/changes/.json` 不存在时视为空数组,正式写入时自动创建(目录递归创建),内容为仅含本次 `change` 的数组。 - **新建文件统一为 2 空格缩进 + LF**;已存在的文件保留原缩进与 EOL 风格(最小 diff)。 - doc **已存在**时 `spec.newDoc` 被忽略(与不传 `newDoc` 落盘结果逐字节一致,有测试覆盖)。 - dry-run 对将要新建的文件打印 `created: <相对路径>` 计划行,但不写盘。 ### 4.3 示例(一次完成新建 + 写入) ```powershell npm run doc:api:update -- --spec=temp/api-doc-create.json --dry-run npm run doc:api:update -- --spec=temp/api-doc-create.json ``` ## 5. 变更记录(`methods/changes/.json`) - `change` 必填键:`version`(非空字符串,**不得与既有记录重复**,重复报 `Duplicate change version detected`)/ `date` / `summary` / `methods`(字符串数组)/ `notes`(字符串数组)。 - `type` 可选(如 `added` / `updated`)。 - 新记录**插入数组头部**(`unshift`),与现有约定一致;历史记录不回改。 - 建议记录至少包含:`version`、`date`、`summary`、`methods`、`notes`。 ## 6. 推荐流程 1. 核对代码与调用链(`controller / systemMethods / systems / model / test`),确定 method、参数、响应、错误码的真实口径。 2. 在 `temp/apiDoc/` 下先备份对应时间点的 `methods/.json` 与 `methods/changes/.json`(自动归档与人工回档都在该目录)。 3. 组织固定 spec JSON(可从已有 spec 或 `docs/api-doc-update-spec.example.json` 复制后编辑)。 4. 先执行 dry-run 校验并查看 `inserted:` / `updated:` / `deleted:` / `created:` 计划行。 5. 确认无误后正式执行写入。 6. 校验落盘文件:`JSON.parse` 可解析、缩进/EOL 与写入前一致(新建文件为 2 空格 + LF)。 7. 再同步 `docs/*.md` / `README.md` 等解释性文档。 ## 7. `--doc-only` 的适用场景 - 仅修补 `methods/.json` 本身、**不追加变更记录**时使用(例如变更记录 `version` 与既有记录重复且只想修正主文档,慎用)。 - `--doc-only` 下 spec 可省略 `change`;若提供了 `change` 仍会做字段校验(不写 changes 文件)。 - 注意:`--doc-only` 属于旁路,正式接口变更仍应走完整流程(主文档 + 变更记录)。 ## 8. 环境变量钩子(仅测试用) - `WMS_API_DOC_METHODS_DIR`:覆盖主文档目录(默认 `methods/`)。 - `WMS_API_DOC_CHANGES_DIR`:覆盖变更记录目录(默认 `methods/changes/`)。 - 脚本在**模块加载时**读取这两个变量(`path.resolve` 解析)。仅用于测试目录隔离(如 `test/scripts/update_api_doc.test.cjs` 注入临时目录),业务运行不要设置。 ## 9. 输出样例 dry-run(新建场景): ``` docName: sample group: sample (示例分组) inserted: sample.echo updated: - moved: - deleted: - delete-not-found: - change version: 2026.09.12-sample created: methods/sample.json created: methods/changes/sample.json dry-run: validated successfully, no files were written. ``` 正式写入(既有文档): ``` docName: openapi_callback group: callback (出站回调事件) inserted: deliveryorder.cancel updated: entryorder.confirm, entryorder.match, deliveryorder.confirm, stockout.confirm moved: - deleted: order.cancel delete-not-found: - change version: 2026.09.12-openapi-callback-protocol-align wrote: methods/openapi_callback.json wrote: methods/changes/openapi_callback.json ``` ## 10. 常见坑(校验报错对照) | 报错 / 现象 | 原因与处理 | |---|---| | `Missing required --spec= argument.` | 未传 `--spec=`(npm 调用需加 `--` 分隔符) | | `Spec file not found: ` | spec 路径不存在或相对路径解析基准不对(按项目根解析) | | `spec.docName must contain only letters, numbers, underscore, or dash.` | `docName` 含非法字符 | | `spec.methods must contain at least one method doc.` | `methods` 为空数组 | | `spec.methods[0].response[0].required must be a boolean.` | `required` 不是布尔(写了字符串 `"true"` 等) | | `Duplicate method in spec.methods: xxx` | spec 内 method 名重复 | | `Method conflict: xxx appears in both spec.methods and spec.deleteMethods.` | 同一 method 同时出现在增改与删除列表 | | `Target doc file not found: (provide spec.newDoc to create it)` | 目标文档不存在且未提供 `spec.newDoc` | | `spec.newDoc.module must be a non-empty string.` | `newDoc` 缺 `module` 或为空白字符串 | | `spec.newDoc.custom must be a plain JSON value.` | `newDoc` 未知透传字段不是 plain JSON 值(如函数) | | `Duplicate change version detected: xxx` | changes 中已有同 `version` 记录;更换 version,或确认只想补主文档时用 `--doc-only` | | 变更记录里方法名带 `spec.` 前缀报错 | 字段路径为 spec 内路径提示,指向的仍是 method 文档字段本身 | ## 11. 回归测试 ```powershell node test/scripts/update_api_doc.test.cjs ``` 覆盖 13 用例:`spec.newDoc` 新建骨架、保留键不透传、doc 已存在时 `newDoc` 被忽略、changes 自动创建、`--doc-only` 不建 changes、dry-run 不写盘、`--help` 输出、新建文件 2 空格 + LF 等。