import { mkdir, readdir, readFile, writeFile, stat } from "node:fs/promises"; import path from "node:path"; import { crawlApi } from "../apidata/crawler.mjs"; const APIDATA_DIR = path.join("workflows", "api-doc-system", "apidata"); const APIDATA_CONFIG_FILE = path.join(APIDATA_DIR, "config.json"); const APIDATA_DATA_FILE = path.join(APIDATA_DIR, "data.json"); const RESPONSE_MARKDOWN_FILE = path.join("workflows", "api-doc-agent", "config", "响应.md"); const MODULE_DATA_ROOT = path.join("workflows", "api-doc-system", "data", "module"); const MODULE_LIST_FILE = path.join("workflows", "api-doc-system", "data", "module-list", "module-list.json"); const CRAWLER_CONFIG = { baseUrl: "http://192.168.11.56:6060/system", version: "1.0", timeoutMs: 20000, }; const LOGIN_METHOD = "user.login"; /** apidata/config.json 未配置 successMessages 时使用;可在 config 中写 successMessages 数组覆盖 */ const DEFAULT_SUCCESS_MESSAGES = ["ok", "成功", "登录成功"]; function normalizeSuccessMessageKey(value) { return String(value ?? "") .trim() .toLowerCase(); } function resolveSuccessMessages(rawConfig) { const arr = rawConfig?.successMessages; if (Array.isArray(arr) && arr.length > 0) { const cleaned = arr.map((x) => String(x).trim()).filter(Boolean); if (cleaned.length > 0) { return cleaned; } } return [...DEFAULT_SUCCESS_MESSAGES]; } /** message 与成功名单某项在 trim + 小写比较下一致则视为成功(英文 ok 与 OK 等价) */ function isResponseMessageOk(message, successMessages) { const key = normalizeSuccessMessageKey(message); if (!key) { return false; } const allow = new Set(successMessages.map((x) => normalizeSuccessMessageKey(x)).filter(Boolean)); return allow.has(key); } /** * @param {Array<{ 接口: string, message: string, code?: unknown, data: unknown }>} rows * @param {string[]} successMessages */ function buildDataOverview(rows, successMessages) { const total = rows.length; let success = 0; /** @type {{ 接口: string, message: string, code: unknown }[]} */ const 失败接口 = []; for (const row of rows) { if (isResponseMessageOk(row.message, successMessages)) { success += 1; } else { 失败接口.push({ 接口: row.接口, message: String(row.message ?? ""), code: row.code ?? null, }); } } return { 当前请求数: total, 成功数: success, 全部请求数: total, 成功数与全部请求数: `${success}/${total}`, 成功判定名单: [...successMessages], 失败接口, }; } function ensurePlainObject(value, fallbackValue = {}) { if (!value || typeof value !== "object" || Array.isArray(value)) { return fallbackValue; } return value; } async function readJson(filePath) { const content = await readFile(filePath, "utf8"); return JSON.parse(content); } async function writeJson(filePath, data) { await mkdir(path.dirname(filePath), { recursive: true }); await writeFile(filePath, `${JSON.stringify(data, null, 2)}\n`, "utf8"); } function normalizeConfigRequest(item) { const method = String(item?.method ?? "").trim(); if (!method) { return null; } return { method, body: ensurePlainObject(item?.body, {}), needAuth: item?.needAuth ?? method !== LOGIN_METHOD, }; } function normalizeConfig(rawConfig) { const rawRequests = Array.isArray(rawConfig) ? rawConfig : rawConfig?.requests; const requests = Array.isArray(rawRequests) ? rawRequests.map(normalizeConfigRequest).filter(Boolean) : []; if (requests.length === 0) { throw new Error("apidata/config.json 缺少有效接口配置,请至少提供一个 method"); } return { requests, }; } function printHelp() { console.log(` apidata — 按 config.json 请求远端并写入 apidata/data.json 与 api-doc-agent/config/响应.md(响应.md 仅含各接口 method 与 data) 成功判定: 响应 message 与「成功判定名单」某项在 trim 且英文忽略大小写后一致即成功(默认含 ok、成功、登录成功)。 可在 apidata/config.json 根级设置 successMessages 数组覆盖默认名单。 失败接口: 写入 data.json 时会在每条失败记录上附加「模块目录」(来自 data/module-list/module-list.json)、 「api封装」(在 src/api 中匹配到的 export)及「引用页面」(扫描 src/views、src/components、src/layout 下 .vue/.ts/.tsx 的引用路径,相对仓库根)。 用法: npm run apiconfig:apidata npm run apiconfig:apidata -- [选项] [模块名 ...] 选项: -c, -r, --clear 清空除 ${LOGIN_METHOD} 外的请求项(无模块名时仅保留登录) -n, --no-clear 指定模块时仍保留 config 中其它模块的请求(默认:指定模块时会先清空) -h, --help 显示本说明 模块名: 与 data/module/ 一致,例如 order.index、order.revieworder(大小写不敏感) 指定一个或多个模块时,默认会先「清空除登录外的条目」,再写入这些模块在 module.json 中的全部 method。 示例: npm run apiconfig:apidata npm run apiconfig:apidata -- order.index order.revieworder npm run apiconfig:apidata -- -c npm run apiconfig:apidata -- --no-clear order.index `); } /** * @param {string[]} argv process.argv.slice(2) */ export function parseApidataCli(argv) { const flags = { clear: false, noClear: false, help: false }; const positionals = []; for (const arg of argv) { if (arg === "--") { continue; } if (arg === "-h" || arg === "--help") { flags.help = true; continue; } if (arg === "-c" || arg === "-r" || arg === "--clear") { flags.clear = true; continue; } if (arg === "-n" || arg === "--no-clear") { flags.noClear = true; continue; } if (arg.startsWith("-")) { throw new Error(`未知参数: ${arg}(使用 --help 查看说明)`); } positionals.push(arg.trim()); } const modules = positionals.filter(Boolean); let clearOld = false; if (flags.help) { return { flags, modules, clearOld, help: true }; } if (flags.noClear && flags.clear) { throw new Error("不能同时使用 --clear 与 --no-clear"); } if (modules.length > 0) { clearOld = !flags.noClear; } else { clearOld = flags.clear; } return { flags, modules, clearOld, help: false }; } async function listModuleFolders() { const entries = await readdir(MODULE_DATA_ROOT, { withFileTypes: true }); return entries.filter((e) => e.isDirectory()).map((e) => e.name); } async function resolveModuleFolder(userInput) { const name = String(userInput ?? "").trim(); if (!name) { return null; } const folders = await listModuleFolders(); const exact = folders.find((f) => f === name); if (exact) { return exact; } const lower = name.toLowerCase(); const ci = folders.find((f) => f.toLowerCase() === lower); if (ci) { return ci; } return null; } async function loadMethodsFromModuleFolder(folder) { const filePath = path.join(MODULE_DATA_ROOT, folder, "module.json"); const raw = await readJson(filePath); const list = Array.isArray(raw?.interfaces) ? raw.interfaces : []; const methods = []; for (const item of list) { const m = String(item?.method ?? "").trim(); if (m) { methods.push(m); } } return methods; } function requestEntry(method, body = {}) { return { method, body: ensurePlainObject(body, {}), }; } /** * @param {{ existingRaw: object, modules: string[], clearOld: boolean }} opts */ async function buildAndWriteConfig(opts) { const { existingRaw, modules, clearOld } = opts; const existing = normalizeConfig(existingRaw); const loginReq = existing.requests.find((r) => r.method === LOGIN_METHOD); const methodToRequest = new Map(); for (const r of existing.requests) { methodToRequest.set(r.method, { method: r.method, body: { ...r.body }, needAuth: r.needAuth }); } const unknownModules = []; const moduleMethodsOrdered = []; for (const mod of modules) { const folder = await resolveModuleFolder(mod); if (!folder) { unknownModules.push(mod); continue; } const methods = await loadMethodsFromModuleFolder(folder); for (const m of methods) { moduleMethodsOrdered.push(m); } } const seenMethod = new Set(); const uniqueModuleMethods = []; for (const m of moduleMethodsOrdered) { if (seenMethod.has(m)) { continue; } seenMethod.add(m); uniqueModuleMethods.push(m); } if (unknownModules.length) { const available = (await listModuleFolders()).sort().join(", "); throw new Error( `未找到模块: ${unknownModules.join(", ")}\n` + `data/module 下可用 folder: ${available}`, ); } const moduleMethodSet = new Set(uniqueModuleMethods); let nextRequests = []; if (clearOld) { if (loginReq) { nextRequests.push(requestEntry(LOGIN_METHOD, loginReq.body)); } else { throw new Error(`清空模式下需要在 config.json 中保留 ${LOGIN_METHOD} 及 body,以便后续接口鉴权`); } for (const m of uniqueModuleMethods) { if (m === LOGIN_METHOD) { continue; } nextRequests.push(requestEntry(m, {})); } } else if (modules.length > 0) { const merged = []; for (const r of existing.requests) { if (r.method === LOGIN_METHOD) { merged.push({ method: r.method, body: { ...r.body } }); continue; } if (moduleMethodSet.has(r.method)) { continue; } merged.push({ method: r.method, body: { ...r.body } }); } for (const m of uniqueModuleMethods) { if (m === LOGIN_METHOD) { continue; } const prev = methodToRequest.get(m); merged.push(requestEntry(m, prev?.body ?? {})); } nextRequests = merged; const hasLogin = nextRequests.some((r) => r.method === LOGIN_METHOD); if (!hasLogin) { throw new Error(`config 中须包含 ${LOGIN_METHOD},或先使用清空模式生成配置`); } } else { nextRequests = existing.requests.map((r) => ({ method: r.method, body: { ...r.body } })); } nextRequests.sort((a, b) => { if (a.method === LOGIN_METHOD) { return -1; } if (b.method === LOGIN_METHOD) { return 1; } return 0; }); const out = { requests: nextRequests.map((r) => ({ method: r.method, body: r.body ?? {}, })), }; const prevSm = existingRaw?.successMessages; if (Array.isArray(prevSm) && prevSm.length > 0) { const cleaned = prevSm.map((x) => String(x).trim()).filter(Boolean); if (cleaned.length > 0) { out.successMessages = cleaned; } } await writeJson(APIDATA_CONFIG_FILE, out); console.log(`已更新 ${APIDATA_CONFIG_FILE}(共 ${out.requests.length} 条请求)`); return out; } /** * 响应.md 仅含「接口 method + 响应 data」,不含数据一览、message 等。 * @param {Array<{ 接口: string, message?: string, code?: unknown, data: unknown }>} rows */ function buildMethodDataOnlyForMarkdown(rows) { return rows.map((row) => ({ 接口: row.接口, data: row.data ?? null, })); } function createResponseMarkdown(rows) { const slim = buildMethodDataOnlyForMarkdown(rows); return ["```json", JSON.stringify(slim, null, 2), "```", ""].join("\n"); } function escapeRegex(s) { return String(s).replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); } function toPosix(p) { return p.split(path.sep).join("/"); } /** @returns {Promise} */ async function walkFilesRecursive(rootDir, { extensions } = {}) { const out = []; let st; try { st = await stat(rootDir); } catch { return out; } if (!st.isDirectory()) { return out; } const entries = await readdir(rootDir, { withFileTypes: true }); for (const e of entries) { const full = path.join(rootDir, e.name); if (e.isDirectory()) { out.push(...(await walkFilesRecursive(full, { extensions }))); } else if (e.isFile()) { if (extensions && extensions.length > 0) { const ext = path.extname(e.name).toLowerCase(); if (!extensions.includes(ext)) { continue; } } out.push(full); } } return out; } /** * 从 module-list.json 构建 method -> folder(module.json 所在目录名,对应 src/api/) * @returns {Promise>} */ async function loadMethodToFolderFromModuleList() { const map = new Map(); try { const raw = await readJson(MODULE_LIST_FILE); const modules = Array.isArray(raw?.modules) ? raw.modules : []; for (const mod of modules) { const folder = String(mod?.folder ?? "").trim(); const interfaces = Array.isArray(mod?.interfaces) ? mod.interfaces : []; for (const it of interfaces) { const m = String(it?.method ?? "").trim(); if (m && folder && !map.has(m)) { map.set(m, folder); } } } } catch { // 无 module-list 时仅全量扫描 src/api } return map; } /** * @param {string} apiFileAbs * @param {string} repoRoot */ function apiFileToImportPath(apiFileAbs, repoRoot) { const rel = toPosix(path.relative(repoRoot, apiFileAbs)); const withoutExt = rel.replace(/\.ts$/i, ""); if (withoutExt.startsWith("src/")) { return "@" + withoutExt.slice("src".length); } return "@" + withoutExt; } /** * 解析单文件:method 字符串对应的封装(export function / export const fn = ( / 聚合对象上的属性) * @returns {{ kind: 'function', exportName: string } | { kind: 'objectProperty', objectName: string, propName: string }}[] */ function extractWrappersFromApiSource(content, methodStr) { const needleSingle = `method: '${methodStr}'`; const needleDouble = `method: "${methodStr}"`; if (!content.includes(needleSingle) && !content.includes(needleDouble)) { return []; } const lines = content.split(/\r?\n/); let currentExport = null; /** @type {Map>} method -> function export names */ const methodToFnExports = new Map(); const exportFnRe = /export\s+function\s+(\w+)\s*\(/; const exportConstFnRe = /export\s+const\s+(\w+)\s*=\s*(?:async\s*)?\(/; const methodLineRe = /method:\s*['"]([^'"]+)['"]/; function addFnExport(meth, name) { if (!meth || !name) { return; } if (!methodToFnExports.has(meth)) { methodToFnExports.set(meth, new Set()); } methodToFnExports.get(meth).add(name); } for (const line of lines) { let m = line.match(exportFnRe); if (m) { currentExport = m[1]; } else { m = line.match(exportConstFnRe); if (m) { currentExport = m[1]; } } const mm = line.match(methodLineRe); if (mm && currentExport) { addFnExport(mm[1], currentExport); } } const fnNames = methodToFnExports.get(methodStr); if (!fnNames || fnNames.size === 0) { return []; } /** @type {any[]} */ const wrappers = []; for (const fnName of fnNames) { wrappers.push({ kind: "function", exportName: fnName }); for (const { objectName, propName } of findObjectPropertyAliases(content, fnName)) { wrappers.push({ kind: "objectProperty", objectName, propName }); } } return wrappers; } /** * @param {string} content * @param {string} fnName * @returns {{ objectName: string, propName: string }[]} */ function findObjectPropertyAliases(content, fnName) { const re = new RegExp(`\\b(\\w+)\\s*:\\s*${escapeRegex(fnName)}\\b`, "g"); const results = []; let m; while ((m = re.exec(content)) !== null) { const propName = m[1]; const before = content.slice(0, m.index); const objs = [...before.matchAll(/export\s+const\s+(\w+)\s*=\s*\{/g)]; if (objs.length === 0) { continue; } const objectName = objs[objs.length - 1][1]; results.push({ objectName, propName }); } return results; } /** * @param {string} importPath */ function importsFromPath(content, importPath) { return new RegExp(`from\\s*['"]${escapeRegex(importPath)}['"]`).test(content); } /** * import { a, b } from 'path'(支持多行) */ function namedImportDeclaresSymbol(content, importPath, symbol) { if (!importsFromPath(content, importPath)) { return false; } const ep = escapeRegex(importPath); const blocks = [...content.matchAll(new RegExp(`import\\s*\\{([\\s\\S]*?)\\}\\s*from\\s*['"]${ep}['"]`, "g"))]; for (const b of blocks) { if (new RegExp(`\\b${escapeRegex(symbol)}\\b`).test(b[1])) { return true; } } return false; } function namespaceAlias(content, importPath) { const ep = escapeRegex(importPath); const m = content.match(new RegExp(`import\\s*\\*\\s*as\\s+(\\w+)\\s+from\\s*['"]${ep}['"]`)); return m ? m[1] : null; } function viewUsesFunctionExport(content, importPath, exportName) { const alias = namespaceAlias(content, importPath); if (alias && new RegExp(`\\b${escapeRegex(alias)}\\.${escapeRegex(exportName)}\\s*\\(`).test(content)) { return true; } if (namedImportDeclaresSymbol(content, importPath, exportName)) { if (new RegExp(`(?:^|[^.\\w])${escapeRegex(exportName)}\\s*\\(`).test(content)) { return true; } } return false; } function viewUsesObjectProperty(content, importPath, objectName, propName) { if (!namedImportDeclaresSymbol(content, importPath, objectName)) { return false; } return new RegExp( `\\b${escapeRegex(objectName)}\\.${escapeRegex(propName)}\\s*\\(`, ).test(content); } /** * 扫描整个 src/api(module-list 的 folder 仅写入失败项的「模块目录」,不排除其它目录下的同名 method 封装) * @param {string} repoRoot * @param {string} methodStr */ async function collectWrappersForMethod(repoRoot, methodStr) { const srcApi = path.join(repoRoot, "src", "api"); const tsFiles = await walkFilesRecursive(srcApi, { extensions: [".ts"] }); const seen = new Set(); /** @type {{ relFile: string, importPath: string, kind: string, exportName?: string, objectName?: string, propName?: string }[]} */ const out = []; for (const abs of tsFiles) { let text; try { text = await readFile(abs, "utf8"); } catch { continue; } const wrappers = extractWrappersFromApiSource(text, methodStr); if (wrappers.length === 0) { continue; } const relFile = toPosix(path.relative(repoRoot, abs)); const importPath = apiFileToImportPath(abs, repoRoot); for (const w of wrappers) { const key = w.kind === "function" ? `${relFile}|fn|${w.exportName}` : `${relFile}|obj|${w.objectName}.${w.propName}`; if (seen.has(key)) { continue; } seen.add(key); if (w.kind === "function") { out.push({ relFile, importPath, kind: "function", exportName: w.exportName }); } else { out.push({ relFile, importPath, kind: "objectProperty", objectName: w.objectName, propName: w.propName, }); } } } return out; } /** 失败接口「引用页面」扫描目录(相对 src/) */ const APIDATA_USAGE_SCAN_SEGMENTS = ["views", "components", "layout"]; /** * @param {string} repoRoot * @param {Awaited>} wrappers */ async function findViewsUsingWrappers(repoRoot, wrappers) { if (wrappers.length === 0) { return []; } const candidates = []; for (const seg of APIDATA_USAGE_SCAN_SEGMENTS) { const root = path.join(repoRoot, "src", seg); const files = await walkFilesRecursive(root, { extensions: [".vue", ".ts", ".tsx"] }); candidates.push(...files); } const hits = new Set(); for (const abs of candidates) { let content; try { content = await readFile(abs, "utf8"); } catch { continue; } for (const w of wrappers) { let ok = false; if (w.kind === "function") { ok = viewUsesFunctionExport(content, w.importPath, w.exportName); } else if (w.kind === "objectProperty") { ok = viewUsesObjectProperty(content, w.importPath, w.objectName, w.propName); } if (ok) { hits.add(toPosix(path.relative(repoRoot, abs))); break; } } } return [...hits].sort(); } /** * 为「失败接口」补充 api 封装与引用页面路径(views / components / layout) * @param {Array<{ 接口: string, message: string, code: unknown }>} failedList */ async function enrichFailedInterfacesWithUsage(failedList) { const repoRoot = process.cwd(); const methodToFolder = await loadMethodToFolderFromModuleList(); const enriched = []; for (const item of failedList) { const methodStr = String(item.接口 ?? "").trim(); const folder = methodToFolder.get(methodStr) ?? null; const wrappers = await collectWrappersForMethod(repoRoot, methodStr); const 引用页面 = await findViewsUsingWrappers(repoRoot, wrappers); const api封装 = wrappers.map((w) => { if (w.kind === "function") { return { 文件: w.relFile, 方法名: w.exportName }; } return { 文件: w.relFile, 方法名: `${w.objectName}.${w.propName}`, 说明: "聚合对象方法", }; }); enriched.push({ ...item, 模块目录: folder, api封装, 引用页面, }); } return enriched; } async function runCrawlFromConfigFile() { const rawConfig = await readJson(APIDATA_CONFIG_FILE); const successMessages = resolveSuccessMessages(rawConfig); const config = normalizeConfig(rawConfig); const rows = []; let authToken = null; for (const req of config.requests) { const result = await crawlApi({ baseUrl: CRAWLER_CONFIG.baseUrl, version: CRAWLER_CONFIG.version, method: req.method, body: req.body, timeoutMs: CRAWLER_CONFIG.timeoutMs, token: req.needAuth ? authToken : null, }); if (result.response?.data?.token) { authToken = result.response.data.token; } const res = result.response; rows.push({ 接口: req.method, message: res && typeof res === "object" && !Array.isArray(res) ? String(res.message ?? "") : "", code: res && typeof res === "object" && !Array.isArray(res) && "code" in res ? res.code : null, data: res && typeof res === "object" && !Array.isArray(res) ? res.data ?? null : null, }); } const 数据一览 = buildDataOverview(rows, successMessages); 数据一览.失败接口 = await enrichFailedInterfacesWithUsage(数据一览.失败接口); const payload = { 数据一览, 详情: rows, }; await writeJson(APIDATA_DATA_FILE, payload); await mkdir(path.dirname(RESPONSE_MARKDOWN_FILE), { recursive: true }); await writeFile(RESPONSE_MARKDOWN_FILE, createResponseMarkdown(rows), "utf8"); console.log(`已写入接口响应数据: ${APIDATA_DATA_FILE}`); console.log( `数据一览: 当前请求数=${数据一览.当前请求数} 成功数/全部请求数=${数据一览.成功数与全部请求数} 失败数=${数据一览.失败接口.length}`, ); if (数据一览.失败接口.length) { for (const item of 数据一览.失败接口) { console.log(` 失败: ${item.接口} — code=${JSON.stringify(item.code)} — ${item.message}`); } } console.log(`已更新响应文档: ${RESPONSE_MARKDOWN_FILE}`); } export async function runApidata() { const cli = parseApidataCli(process.argv.slice(2)); if (cli.help) { printHelp(); return; } const existingRaw = await readJson(APIDATA_CONFIG_FILE); if (cli.modules.length > 0 || cli.clearOld) { console.log( `apidata: clearOld=${cli.clearOld}, modules=[${cli.modules.join(", ")}]`, ); await buildAndWriteConfig({ existingRaw, modules: cli.modules, clearOld: cli.clearOld, }); } await runCrawlFromConfigFile(); }