API Doc System Workflow
该工作流用于抓取 system API 文档页面,按 platform=网页端(web)、project=全部(all) 条件进行校验后,清洗输出模块与接口数据。
目录结构
core/: 核心实现目录(config.mjs、update.mjs、clear-pending.mjs)。scripts/: 脚本入口目录(update.mjs、clear-pending.mjs、apidata.mjs)。system/: 系统模式配置目录(如workflow-mode.json)。config.mjs: 兼容转发入口(实际定义位于core/config.mjs)。scripts/agent/: 从api-doc-agent迁移的 Agent 脚本(run.mjs、api-list-update、interface-availability)。data/: 数据目录,按功能分类存放产物。data/module/<folder>/module.json: 模块接口明细(覆盖更新)。data/module-list/module-list.json: 模块总览(覆盖更新)。data/interface-details/interface-details.json: 全量接口明细(覆盖更新)。data/pending-updates.json: 待更新文件(模块变化 + 接口变化)。
运行
npm run apiconfig
如需清空待更新接口文件,可执行:
npm run apiconfig:clear-pending
执行前会先检查 pending-updates.json:
- 若文件内容不是
{}(存在未处理项),脚本会输出:请先处理待更新接口再更新接口信息!
- 并终止本次执行,不更新其他产物。
Apidata 抓取脚本
新增 apidata 请求脚本,用于按配置发起接口请求并写入响应结果(支持提取登录 token)。
运行命令:
npm run apiconfig:apidata
配置文件:workflows/api-doc-system/apidata/config.json
config.json仅存放待请求接口配置(不存放爬虫地址、版本等信息)。requests: 请求列表method: 接口 method(会拼接到?method=xxx)body: 请求 JSON(可省略,默认{})needAuth: 是否携带登录 token(可省略;除user.login外默认true)
- 脚本内部固定请求地址:
http://192.168.11.56:6060/system?v=1.0。 - 脚本默认携带请求头:
platform: web、project: all。
示例配置(登录获取 token):
{
"requests": [
{
"method": "user.login",
"body": {
"username": "yjm",
"password": "111111"
}
},
{
"method": "order.list",
"body": {}
},
{
"method": "order.manualOutboundOrder",
"body": {}
},
{
"method": "order.badgeCount",
"body": {}
}
]
}
说明:
- 脚本会按
requests顺序串行执行。 - 当某次响应中包含
data.token(如user.login)时,后续needAuth=true的接口会自动携带Authorization: Bearer <token>。
数据文件:workflows/api-doc-system/apidata/data.json
- 每次执行会先清空该文件,再写入本次抓取结果。
- 输出结构为数组项:
{ 接口, message, data }。 - 同步更新:
workflows/api-doc-agent/config/响应.md(写入本次结果)。
如需改抓取地址,可临时指定:
API_DOC_URL=http://192.168.11.56:6060/api/docs/system npm run apiconfig
Agent 脚本入口:
npm run apiagent -- --script list
输出说明(去历史回档)
- 模块文件包含当前模块全部接口信息(接口名、描述、Headers、Params、Response 等)。
module是最新接口信息的主数据源,每次执行npm run apiconfig都会覆盖更新module.json。- 每个模块快照新增
changes.fromPreviousSnapshot字段,记录本模块相对上一快照的:- 模块是否新增/重命名
- 接口新增/删除
- 接口
params更新 - 接口
response更新
- 模块总览文件仅保留每个模块的精简接口清单:
method
module-list/module-list.json每次执行覆盖更新,避免每日堆积快照文件。module-list与interface-details均新增changes字段,统一汇总模块与接口变化统计:moduleUpdates.added / deleted / updatedinterfaceUpdates.added / deleted / paramsUpdated / responseUpdated
- 接口明细文件包含当前项目所有接口信息,并带状态字段:
status.isUsed: 是否使用(默认false)status.isPlaceholder: 是否占位(默认false)
- 状态会优先继承
module目录最近快照中的状态,避免每次执行覆盖人工维护状态。 - 脚本输出增加本地可读时间字段(如
generatedAtLocal),终端日志统一显示YYYY-MM-DD HH:mm:ss。 - 页面中的
platform/project是全局请求头配置项,脚本会校验web/all选项存在,并将其写入每份产物的filter字段。 pending-updates.json中:- 无任何变化时文件会被重置为
{}。 - 有变化时写入模块/接口变更清单,复杂迁移统一折叠为“新增 + 删除”。
summary:包含moduleAdded、moduleDeleted、interfaceAdded、interfaceDeleted、interfaceParamsUpdated、interfaceResponseUpdated、totalChangedItemsinterfaceUpdates:包含added、deleted、paramsUpdated、responseUpdated
- 无任何变化时文件会被重置为
待更新接口判定规则
- 与上一轮有效快照对比后,以下变化会写入
pending-updates.json:- 模块更新:新增模块、删除模块(拆分/合并/替换统一按增删处理)
- 接口更新:新增接口、删除接口、
params变化、response变化
模块文件夹生命周期
- 新模块首次出现时自动创建模块文件夹并生成
_module.lifecycle.json。 - 运行
npm run apiconfig时会先完成与上一轮数据的差异对比并写入pending-updates.json。 - 对比完成后,当前文档中不存在的旧模块文件夹会被直接物理删除(不再保留
_deleted.YYYYMMDD.json软删除标记)。 - 目录内仅保留本轮解析到的最新模块数据,避免历史目录残留影响结构一致性。
结构优化说明
- 入口脚本统一放在
scripts/。 - 数据统一放在
data/,减少根目录散落文件。 - 采用覆盖写入模式,避免重复历史文件导致目录混乱与资源浪费。