4.8 KiB
4.8 KiB
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 个版本)。[历史快照]
运行
npm run apiconfig
如需清空待更新接口文件,可执行:
npm run apiconfig:clear-pending
如需清理“已标记删除”的模块与接口,可执行:
npm run apiconfig:clean-marked
执行前会先检查 pending-updates.json:
- 若存在未处理项,脚本会输出:
还有未更新接口等待处理!请处理待更新接口再执行此程序。
- 并终止本次执行,不更新其他产物。
如需改抓取地址,可临时指定:
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 个版本窗口(受保留天数控制)。 - 模块总览文件仅保留每个模块的精简接口清单:
methodisUsedisPlaceholder
module-list与interface-details均新增changes字段,统一汇总模块与接口变化统计:moduleUpdates.added / deleted / updated / split / merged / replacedinterfaceUpdates.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。