96 lines
4.8 KiB
Markdown
96 lines
4.8 KiB
Markdown
# API Doc System Workflow
|
||
|
||
该工作流用于自动抓取 `system` API 文档页面,按 `platform=网页端(web)`、`project=全部(all)` 条件进行校验后,清洗输出模块与接口数据。
|
||
|
||
## 目录结构
|
||
|
||
- `config.mjs`: 抓取地址、筛选条件、输出目录、保留天数配置。
|
||
- `update.mjs`: 抓取、解析、清洗、落盘、历史清理的一体化脚本。
|
||
- `clear-pending.mjs`: 清空 `pending-updates.json` 的辅助脚本。
|
||
- `cleanup-marked.mjs`: 清理已标记删除的模块与接口,并重置待更新记录。
|
||
- `module/`: 按模块分文件夹存储,每个模块每天一份文件(`YYYYMMDD.json`)。[接口详细配置信息]
|
||
- `module-list/`: 每天一份模块总览文件(`YYYYMMDD.json`)。[接口快速一览]
|
||
- `interface-details/`: 全量接口明细归档文件(`YYYYMMDD.json`,按日更新)。[归档记录]
|
||
- `pending-updates.json`: 待更新文件(模块变化 + 接口变化 + 兼容 legacy 结构)。[待更新接口信息]
|
||
- `pending-history/`: 待更新历史快照(`YYYYMMDDHHmmss.json`,保留最近 5 个版本)。[历史快照]
|
||
|
||
## 运行
|
||
|
||
```bash
|
||
npm run apiconfig
|
||
```
|
||
|
||
如需清空待更新接口文件,可执行:
|
||
|
||
```bash
|
||
npm run apiconfig:clear-pending
|
||
```
|
||
|
||
如需清理“已标记删除”的模块与接口,可执行:
|
||
|
||
```bash
|
||
npm run apiconfig:clean-marked
|
||
```
|
||
|
||
执行前会先检查 `pending-updates.json`:
|
||
|
||
- 若存在未处理项,脚本会输出:
|
||
- `还有未更新接口等待处理!请处理待更新接口再执行此程序。`
|
||
- 并终止本次执行,不更新其他产物。
|
||
|
||
如需改抓取地址,可临时指定:
|
||
|
||
```bash
|
||
API_DOC_URL=http://192.168.11.56:6060/api/docs/system npm run apiconfig
|
||
```
|
||
|
||
## 输出说明
|
||
|
||
- 模块文件包含当前模块全部接口信息(接口名、描述、Headers、Params、Response 等)。
|
||
- `module` 是最新接口信息的主数据源,每次执行 `npm run apiconfig` 都会更新当日模块文件。
|
||
- 每个模块快照新增 `changes.fromPreviousSnapshot` 字段,记录本模块相对上一快照的:
|
||
- 模块是否新增/重命名
|
||
- 接口新增/删除
|
||
- 接口 `params` 更新
|
||
- 接口 `response` 更新
|
||
- 每份模块快照新增 `versionWindow`,用于展示最近 5 个版本窗口(受保留天数控制)。
|
||
- 模块总览文件仅保留每个模块的精简接口清单:
|
||
- `method`
|
||
- `isUsed`
|
||
- `isPlaceholder`
|
||
- `module-list` 与 `interface-details` 均新增 `changes` 字段,统一汇总模块与接口变化统计:
|
||
- `moduleUpdates.added / deleted / updated / split / merged / replaced`
|
||
- `interfaceUpdates.added / deleted / paramsUpdated / responseUpdated`
|
||
- 接口明细文件包含当前项目所有接口信息,并带状态字段:
|
||
- `status.isUsed`: 是否使用(默认 `false`)
|
||
- `status.isPlaceholder`: 是否占位(默认 `false`)
|
||
- 状态会优先继承 `module` 目录最近快照中的状态,避免每次执行覆盖人工维护状态。
|
||
- `module-list`、`interface-details`、`pending-updates` 均包含 `versionWindow` 字段,用于展示最近 5 版本窗口信息。
|
||
- 脚本输出增加本地可读时间字段(如 `generatedAtLocal`),终端日志统一显示 `YYYY-MM-DD HH:mm:ss`。
|
||
- 页面中的 `platform/project` 是全局请求头配置项,脚本会校验 `web/all` 选项存在,并将其写入每份产物的 `filter` 字段。
|
||
- `pending-updates.json` 中:
|
||
- `summary`:变化统计汇总
|
||
- `moduleUpdates`:模块级变化(含拆分、合并)
|
||
- `interfaceUpdates`:接口级变化
|
||
- `legacy`:兼容旧结构(按模块聚合 methods)
|
||
|
||
## 待更新接口判定规则
|
||
|
||
- 与上一轮有效快照对比后,以下变化会写入 `pending-updates.json`:
|
||
- 模块更新:新增模块、删除模块、模块替换、旧模块拆分为多个新模块、多个旧模块合并为新模块
|
||
- 接口更新:新增接口、删除接口、`params` 变化、`response` 变化
|
||
- 同时会写入 `pending-history/`,用于保留最近 5 个待更新版本。
|
||
|
||
## 模块文件夹生命周期
|
||
|
||
- 新模块首次出现时自动创建模块文件夹并生成 `_module.lifecycle.json`。
|
||
- 当模块在最新文档中消失时,不删除模块文件夹,而是在该目录新增 `_deleted.YYYYMMDD.json` 删除标记,并将生命周期状态更新为 `deleted`。
|
||
- 若后续文档再次出现该模块,会自动恢复为 `active`,保留历史标记用于回退排查。
|
||
- 若确认无需保留回退数据,可执行 `npm run apiconfig:clean-marked` 物理删除已标记模块,并清理待删接口。
|
||
|
||
## 历史保留(最近 5 版本)
|
||
|
||
- `module/*/YYYYMMDD.json`、`module-list/YYYYMMDD.json`、`interface-details/YYYYMMDD.json` 自动保留最近 5 天快照。
|
||
- `pending-history/YYYYMMDDHHmmss.json` 自动保留最近 5 个版本快照。
|
||
- 如需调整保留数量,可修改 `config.mjs` 中 `retentionDays`。
|