ly-api-scanner

扫描前端(尤其 Vue 2/3) 项目中的接口调用：结合 src/api/apiList 定义与实际页面 (views/**/*.vue) 使用，输出单 Sheet Excel，按模块分块，自动归属真实页面并中文语义化接口说明。

核心特性（精简单表模式）

| 能力 | 说明 | |------|------| | 单 Sheet 输出 | 仅 API分组，无多余汇总表，适合直接分享或二次过滤。| | 模块分组 | 模块 = Vue 叶子目录名 / 接口路径业务段 / Host 归一化；忽略泛目录 api|apis|service|services。| | 去重策略 | 同模块同 API路径 一行；跨模块允许重复。| | 行号聚合 | 聚合出现行号(升序去重, 逗号分隔)。| | 页面归属 | 递归追溯 Vue -> js -> js -> ... -> API，导出函数反向匹配，最大化找到真实页面。| | 噪声过滤 | 未能归属到任何 Vue 的纯 JS 调用行自动剔除。| | 中文说明 | 注释优先，其次语义关键词映射（查询/新增/删除/更新/详情/导出/导入）。| | 安全写入 | 文件被占用或存在冲突自动加时间戳。|

与传统“只扫 apiList / 只扫代码”的差异

| 方案 | 问题 | ly-api-scanner 解决方式 | |------|------|-------------------------| | 只读 apiList | 无法知道是否被页面实际使用 | 同时扫描页面实际引用与代码调用 | | 直接 grep 代码 | 得到封装 JS 而非真实页面 | 递归依赖 & 函数反查映射到 Vue | | 多 Sheet 报表 | 维护成本高，样式易破 | 单 Sheet 且文本分块标题 ▶ 模块：xxx |

1.1.0 新增 / 改进

| 功能 | 说明 | |------|------| | 递归依赖追溯 | 构建 js->js & vue->js 图，向上追溯真实页面 | | 导出函数反查 | 解析导出函数，在 Vue 中检索调用实现归属 | | 未命中过滤 | 过滤无法归属页面的纯 JS/API 行 | | 模块名优化 | 泛目录回退父级，减少“api”模块泛滥 | | Host/IP 处理 | 提取业务段，弱化环境差异 | | 中文描述增强 | 关键字映射标准化说明 |

升级提示：1.0.x 如需保留旧“显示封装 JS”行为，可提 Issue 讨论 --keep-js-file 开关。

1.1.0 新增 / 改进

| 功能 | 说明 | |------|------| | 递归依赖追溯 | 通过构建 js -> js & vue -> js 依赖图，向上追溯映射到 Vue 页面 | | 导出函数反查 | 解析中间 JS 导出的函数名，在所有 Vue 中按调用标记归属，解决仅函数封装的场景 | | 未命中 Vue 过滤 | 仍无法归属页面的纯 JS/API 行自动剔除，避免噪声 | | 模块名优化 | 叶子目录为 api/apis/service/services 时回退父级，减少“api”泛模块 | | Host/IP 处理 | 对以 //host 开头接口提取后续业务段作为模块，弱化环境差异 | | 中文描述增强 | ensureChinese 多关键词映射，统一“查询/新增/删除/更新/详情/导出/导入” 等 |

升级提示：1.0.x 如需保留旧行为（显示封装 JS 文件而不是 vue）暂未保留开关；若确有需要可提 Issue 增加 --keep-js-file 选项。

安装 & 使用

npm install --save-dev ly-api-scanner

# 临时执行
npx ly-api-scanner --include-literals --wrappers service,http,request,apiClient,api --overwrite

# 或在 package.json scripts 中
"scripts": {
  "scan": "ly-api-scanner --include-literals --wrappers service,http,request,apiClient,api --overwrite"
}

npm run scan

CLI 参数一览

Usage: ly-api-scanner [options]

Options:
	-s, --src <dir>              源代码目录 (默认: src)
	-o, --out <dir>              输出目录 (默认: output)
	-i, --include <glob>         包含文件模式 (默认: **/*.{js,vue})
	-w, --wrappers <names>       自定义封装请求函数名 (逗号/分号分隔)
			--include-literals       扫描普通字符串/模板字面量中以后缀结尾的路径
			--suffixes <list>        接口后缀列表 (默认: .do) 例: .do,.action
			--overwrite              允许覆盖已存在 api-stat.xlsx
			--no-suffix-timestamp    关闭时间戳重命名备份
			--verbose                输出详细日志
			--debug-json             生成 api-stat.raw.json 调试文件
			--keep-definitions       保留 apiList 定义行（默认只输出实际引用）
			--group-by <mode>        仅保留 module（兼容参数，不建议修改）
	-V, --version                显示版本号
	-h, --help                   查看帮助

典型命令

npx ly-api-scanner --include-literals --wrappers service,http,apiClient \
	--suffixes .do,.action --verbose --debug-json --overwrite

• 模块名推断：
  1. 如果来源文件位于 views/**/.../<leaf>/<file>.vue（任意深度），使用该文件所在的“叶子目录名” <leaf> 作为模块；
  2. 如果文件直接放在 views/ 根下（views/A.vue），模块 = A（去掉扩展名）；
  3. 其它（如纯 JS、定义文件）仍按接口路径首个业务段（剔除常见前缀 ly,api,v1,v2,mp）或 host 取模块；
  4. 若不同路径层级出现同名叶子目录（例如 views/order/list/... 与 views/sale/order/detail/... 都落在模块 order），它们会合并在同一个模块块中（当前为设计取舍）。
• 同一模块下相同 API路径 仅输出一行；多次出现的行号全部收集并用逗号排序拼接。
• 不同模块允许存在相同 API（互不去重）。
• 行号聚合策略：升序去重；若无行号（仅来自定义且未引用）为空。
• 分块之间插入分隔行：-----------------------------。

api-stat.raw.json（--debug-json）可用于对比调试：含原始捕获信息。

说明列生成策略

1. 优先取接口定义（apiList）中该 API 对象上一行 // 注释。
2. 若无注释：对末段（去掉后缀及查询串）进行关键词语义映射：
   • list|query|search => 查询
   • save|create|add|new => 新增/保存
   • delete|remove|del => 删除
   • update|edit|modify => 更新
   • detail|info => 详情
   • export|download => 导出
   • import|upload => 导入
3. 若仍无匹配返回末段分词友好名。
4. 不再附加页面标题，保持接口本身含义简洁。

支持的匹配模式

• axios('...') / request('...') / fetch('...')
• axios.get|post|put|delete('/path') 及 this.service.post('/path') 等链式封装（需通过 --wrappers 指定 service 名）
• axios({ url: '/path' }) / service({ url: '/path' })
• uni.request({ url: '...' }) / $.ajax({ url: '...' })
• 对象字面量属性 url: '/xxx.do'、APIUrl: '/xxx.do'
• （可选）纯字符串/模板字面量中以指定后缀结尾：开启 --include-literals

安全写策略

写入 api-stat.xlsx 时：

• 若同名文件存在且未指定 --overwrite 且允许时间戳，自动重命名 api-stat-YYYYMMDDHHmmss.xlsx
• 若文件被占用 (EBUSY) 会自动回退时间戳文件

本地调试（可选）

git clone <repo>
cd ly-api-scanner && npm install && npm link
cd <your-project> && npm link ly-api-scanner
ly-api-scanner --debug-json --verbose

FAQ

Q: 仍然看到 js 文件? 说明该调用无法确定归属 Vue（动态 import / 运行时拼接 / 间接调用未解析）。后续计划增加 AST 更精确解析及可选 --keep-js-file。

Q: 为什么某些接口没出现? 可能不符合后缀过滤或路径不是以 / 开头；可用 --include-literals 并扩展 --suffixes。

Q: Excel 样式能否加粗 / 着色? 当前采用开源 xlsx 基础写法，未做样式；考虑后续生成 Markdown/HTML 再配合外部渲染。

Q: 多个页面都使用同一接口，只显示一个文件? 目前取稳定第一个；计划加入 --all-vue-files 或附加列显示计数。

Roadmap（下一步计划）

• 可选开关：输出所有出现文件（新增“文件列表”列）
• 标记未被页面引用的“孤立接口”区段
• 外部自定义词典（路径片段 -> 中文模块/说明）
• 绝对 URL 规范化（剥离协议与主机）
• Markdown / HTML 报告导出
• AST 分析（变量拼接与模板字符串更精确）

贡献

欢迎 Issue / PR：建议附上(接口路径 + 调用代码片段 + 期望归属页面) 便于快速复现。