2026-04-18 20:52:27 +08:00

792 lines
24 KiB
JavaScript
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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/<folder> 一致,例如 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<string[]>} */
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/<folder>)
* @returns {Promise<Map<string, string>>}
*/
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<string, Set<string>>} 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<ReturnType<typeof collectWrappersForMethod>>} 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();
}