befly 3.9.40 → 3.10.1

package/README.md

@@ -165,7 +165,7 @@ await befly.db.delData({
 
 同步到数据库：
 
-请参考：`docs/reference/sync.md`（`syncDb` / `syncAll` 等同步流程说明）。
+请参考：`docs/reference/sync.md`（`syncTable` / `syncData` 等同步流程说明）。
 
 ## 🗄️ 数据库配置
 
@@ -220,7 +220,7 @@ export const beflyConfig = {
     redis: {
         host: "127.0.0.1",
         port: 6379,
-        prefix: "befly:"
+        prefix: "befly"
     },
 
     // CORS 跨域配置
@@ -238,21 +238,54 @@ export const beflyConfig = {
 };
 ```
 
+> 注意：`redis.prefix` 不要包含 `:`（系统会自动拼接分隔符）。
+
 ### 数据库连接
 
-框架会自动从 `beflyConfig` 获取配置并建立连接，无需手动传参：
+通常你不需要手动连接（框架启动期会完成连接并注入插件实例）。
+
+如果你在自定义脚本/测试中需要手动连接，请显式传入配置片段（不要依赖全局单例配置）：
 
 ```typescript
 import { Connect } from "befly/lib/connect";
 
-// 连接 SQL 数据库（配置自动从 beflyConfig.db 获取）
-await Connect.connectSql();
+// 连接 SQL 数据库
+await Connect.connectSql({
+    type: "mysql",
+    host: "127.0.0.1",
+    port: 3306,
+    username: "root",
+    password: "root",
+    database: "befly_demo",
+    poolMax: 1
+});
 
-// 连接 Redis（配置自动从 beflyConfig.redis 获取）
-await Connect.connectRedis();
+// 连接 Redis
+await Connect.connectRedis({
+    host: "127.0.0.1",
+    port: 6379,
+    db: 0,
+    prefix: "befly"
+});
 
-// 同时连接 SQL 和 Redis
-await Connect.connect();
+// 或：同时连接 SQL 和 Redis
+await Connect.connect({
+    db: {
+        type: "mysql",
+        host: "127.0.0.1",
+        port: 3306,
+        username: "root",
+        password: "root",
+        database: "befly_demo",
+        poolMax: 1
+    },
+    redis: {
+        host: "127.0.0.1",
+        port: 6379,
+        db: 0,
+        prefix: "befly"
+    }
+});
 
 // 获取连接状态
 const status = Connect.getStatus();
@@ -263,19 +296,14 @@ console.log(status.redis.connected); // true/false
 await Connect.disconnect();
 ```
 
-### 配置文件迁移指南
+### 配置文件（当前约定）
 
-如果你的项目之前使用 `app.config.ts`，请按以下步骤迁移：
-
-1. **重命名文件**：`app.config.ts` → `befly.config.ts`
-2. **更新导出名**：`config` → `beflyConfig`
+配置文件名为 `befly.config.ts`，导出名为 `beflyConfig`：
 
 ```typescript
-// 旧写法
-export const config = { ... };
-
-// 新写法
-export const beflyConfig = { ... };
+export const beflyConfig = {
+    // ...
+};
 ```
 
 ## 📖 文档

package/befly.config.ts

@@ -5,6 +5,7 @@
  */
 import type { BeflyOptions } from "./types/befly.js";
 
+import { compileDisableMenuGlobRules } from "./utils/disableMenusGlob.js";
 import { scanConfig } from "./utils/scanConfig.js";
 
 /** 默认配置 */
@@ -46,7 +47,7 @@ const defaultOptions: BeflyOptions = {
         username: "",
         password: "",
         db: 0,
-        prefix: "befly_demo:"
+        prefix: "befly_demo"
     },
 
     // ========== 认证配置 ==========
@@ -80,7 +81,7 @@ const defaultOptions: BeflyOptions = {
     // ========== 禁用配置 ==========
     disableHooks: [],
     disablePlugins: [],
-    hiddenMenus: [],
+    disableMenus: ["**/404", "**/403", "**/500", "**/login"],
 
     // ========== Addon 配置 ==========
     addons: {}
@@ -106,6 +107,22 @@ export async function loadBeflyConfig(options: LoadBeflyConfigOptions = {}): Pro
         defaults: defaultOptions
     });
 
+    // 配置校验：redis.prefix 作为 key 前缀，由 RedisHelper 统一拼接 ":"。
+    // 因此 prefix 本身不允许包含 ":"，否则会导致 key 结构出现空段或多段分隔（例如 "prefix::key"），
+    // 在 RedisInsight 等工具里可能显示 [NO NAME] 空分组，且容易造成 key 管理混乱。
+    const redisPrefix = (config as any)?.redis?.prefix;
+    if (typeof redisPrefix === "string") {
+        const trimmedPrefix = redisPrefix.trim();
+        if (trimmedPrefix.includes(":")) {
+            throw new Error(`配置错误：redis.prefix 不允许包含 ':'（RedisHelper 会自动拼接分隔符 ':'），请改为不带冒号的前缀，例如 'befly_demo'，当前值=${redisPrefix}`);
+        }
+    }
+
+    // 预编译 disableMenus 的 Bun.Glob 规则：
+    // - 提前暴露配置错误（fail-fast）
+    // - 后续 checkMenu 会复用同一进程级缓存
+    compileDisableMenuGlobRules((config as any)?.disableMenus);
+
     return config as BeflyOptions;
 }
 

package/checks/checkApi.ts

@@ -1,94 +1,96 @@
-// 内部依赖
-import { existsSync } from "node:fs";
-
-// 外部依赖
 import { isPlainObject } from "es-toolkit/compat";
+import { omit } from "es-toolkit/object";
 
 import { Logger } from "../lib/logger.js";
-import { projectApiDir } from "../paths.js";
-import { scanAddons, getAddonDir, addonDirExists } from "../utils/addonHelper.js";
-// 相对导入
-import { scanFiles } from "../utils/scanFiles.js";
-
-/**
- * 检查所有 API 定义
- */
-export async function checkApi(): Promise<void> {
-    try {
-        // 收集所有 API 文件
-        const allApiFiles: Array<{ file: string; displayName: string; apiPath: string }> = [];
-
-        // 收集项目 API 文件
-        if (existsSync(projectApiDir)) {
-            const files = await scanFiles(projectApiDir);
-            for (const { filePath, relativePath } of files) {
-                allApiFiles.push({
-                    file: filePath,
-                    displayName: "用户",
-                    apiPath: relativePath
-                });
-            }
-        }
 
-        // 收集组件 API 文件
-        const addons = scanAddons();
-        for (const addon of addons) {
-            if (!addonDirExists(addon, "apis")) continue;
-            const addonApiDir = getAddonDir(addon, "apis");
-
-            const files = await scanFiles(addonApiDir);
-            for (const { filePath, relativePath } of files) {
-                allApiFiles.push({
-                    file: filePath,
-                    displayName: `组件${addon}`,
-                    apiPath: relativePath
-                });
+export async function checkApi(apis: any[]): Promise<void> {
+    let hasError = false;
+
+    for (const api of apis) {
+        try {
+            if (typeof api?.name !== "string" || api.name.trim() === "") {
+                Logger.warn(omit(api, ["handler"]), "接口的 name 属性必须是非空字符串");
+                hasError = true;
+                continue;
             }
-        }
 
-        // 合并进行验证逻辑
-        for (const item of allApiFiles) {
-            const { apiPath } = item;
+            if (typeof api?.handler !== "function") {
+                Logger.warn(omit(api, ["handler"]), "接口的 handler 属性必须是函数");
+                hasError = true;
+                continue;
+            }
 
-            try {
-                // Windows 下路径需要转换为正斜杠格式
-                const filePath = item.file.replace(/\\/g, "/");
-                const apiImport = await import(filePath);
-                const api = apiImport.default;
+            // routePath / routePrefix 由 scanFiles 系统生成：必须是严格的 pathname
+            if (typeof api?.routePath !== "string" || api.routePath.trim() === "") {
+                Logger.warn(omit(api, ["handler"]), "接口的 routePath 属性必须是非空字符串（由系统生成）");
+                hasError = true;
+            } else {
+                const routePath = api.routePath.trim();
 
-                // 验证必填属性：name 和 handler
-                if (typeof api.name !== "string" || api.name.trim() === "") {
-                    Logger.warn(`[${item.displayName}] 接口 ${apiPath} 的 name 属性必须是非空字符串`);
-                    continue;
-                }
-                if (typeof api.handler !== "function") {
-                    Logger.warn(`[${item.displayName}] 接口 ${apiPath} 的 handler 属性必须是函数`);
-                    continue;
+                // 不允许出现 "POST/api/..." 等 method 前缀
+                if (/^(GET|POST|PUT|PATCH|DELETE|OPTIONS|HEAD)\b/i.test(routePath)) {
+                    Logger.warn(omit(api, ["handler"]), "接口的 routePath 不允许包含 method 前缀，应为 url.pathname（例如 /api/app/xxx）");
+                    hasError = true;
                 }
 
-                // 验证可选属性的类型（如果提供了）
-                const validMethods = ["GET", "POST", "GET,POST", "POST,GET"];
-                if (api.method && !validMethods.includes(api.method.toUpperCase())) {
-                    Logger.warn(`[${item.displayName}] 接口 ${apiPath} 的 method 属性必须是有效的 HTTP 方法 (GET, POST, GET,POST, POST,GET)`);
+                if (!routePath.startsWith("/api/")) {
+                    Logger.warn(omit(api, ["handler"]), "接口的 routePath 必须以 /api/ 开头");
+                    hasError = true;
                 }
-                if (api.auth !== undefined && typeof api.auth !== "boolean") {
-                    Logger.warn(`[${item.displayName}] 接口 ${apiPath} 的 auth 属性必须是布尔值 (true=需登录, false=公开)`);
-                }
-                if (api.fields && !isPlainObject(api.fields)) {
-                    Logger.warn(`[${item.displayName}] 接口 ${apiPath} 的 fields 属性必须是对象`);
-                }
-                if (api.required && !Array.isArray(api.required)) {
-                    Logger.warn(`[${item.displayName}] 接口 ${apiPath} 的 required 属性必须是数组`);
+
+                if (routePath.includes(" ")) {
+                    Logger.warn(omit(api, ["handler"]), "接口的 routePath 不允许包含空格");
+                    hasError = true;
                 }
-                if (api.required && api.required.some((item: any) => typeof item !== "string")) {
-                    Logger.warn(`[${item.displayName}] 接口 ${apiPath} 的 required 属性必须是字符串数组`);
+
+                if (routePath.includes("/api//")) {
+                    Logger.warn(omit(api, ["handler"]), "接口的 routePath 不允许出现 /api//（重复斜杠）");
+                    hasError = true;
                 }
-            } catch (error: any) {
-                Logger.error(`[${item.displayName}] 接口 ${apiPath} 解析失败`, error);
             }
+
+            if (typeof api?.routePrefix !== "string" || api.routePrefix.trim() === "") {
+                Logger.warn(omit(api, ["handler"]), "接口的 routePrefix 属性必须是非空字符串（由系统生成）");
+                hasError = true;
+            }
+
+            if (api.method && !["GET", "POST", "GET,POST", "POST,GET"].includes(String(api.method).toUpperCase())) {
+                Logger.warn(omit(api, ["handler"]), "接口的 method 属性必须是有效的 HTTP 方法 (GET, POST, GET,POST, POST,GET)");
+                hasError = true;
+            }
+
+            if (api.auth !== undefined && typeof api.auth !== "boolean") {
+                Logger.warn(omit(api, ["handler"]), "接口的 auth 属性必须是布尔值 (true=需登录, false=公开)");
+                hasError = true;
+            }
+
+            if (api.fields && !isPlainObject(api.fields)) {
+                Logger.warn(omit(api, ["handler"]), "接口的 fields 属性必须是对象");
+                hasError = true;
+            }
+
+            if (api.required && !Array.isArray(api.required)) {
+                Logger.warn(omit(api, ["handler"]), "接口的 required 属性必须是数组");
+                hasError = true;
+            }
+
+            if (api.required && api.required.some((reqItem: any) => typeof reqItem !== "string")) {
+                Logger.warn(omit(api, ["handler"]), "接口的 required 属性必须是字符串数组");
+                hasError = true;
+            }
+        } catch (error: any) {
+            Logger.error(
+                {
+                    err: error,
+                    item: api
+                },
+                "接口解析失败"
+            );
+            hasError = true;
         }
-    } catch (error: any) {
-        Logger.error("API 定义检查过程中出错", error);
-        throw error;
+    }
+
+    if (hasError) {
+        throw new Error("接口结构检查失败");
     }
 }

package/checks/checkHook.ts

@@ -0,0 +1,48 @@
+import { isPlainObject } from "es-toolkit/compat";
+import { omit } from "es-toolkit/object";
+
+import { Logger } from "../lib/logger.js";
+
+export async function checkHook(hooks: any[]): Promise<void> {
+    let hasError = false;
+
+    for (const hook of hooks) {
+        try {
+            if (!isPlainObject(hook)) {
+                Logger.warn(omit(hook, ["handler"]), "钩子导出必须是对象（export default { deps, handler }）");
+                hasError = true;
+                continue;
+            }
+
+            if (!Array.isArray((hook as any).deps)) {
+                Logger.warn(omit(hook, ["handler"]), "钩子的 deps 属性必须是字符串数组");
+                hasError = true;
+                continue;
+            }
+
+            if ((hook as any).deps.some((depItem: any) => typeof depItem !== "string")) {
+                Logger.warn(omit(hook, ["handler"]), "钩子的 deps 属性必须是字符串数组");
+                hasError = true;
+            }
+
+            if (typeof (hook as any).handler !== "function") {
+                Logger.warn(omit(hook, ["handler"]), "钩子的 handler 属性必须是函数");
+                hasError = true;
+                continue;
+            }
+        } catch (error: any) {
+            Logger.error(
+                {
+                    err: error,
+                    item: hook
+                },
+                "钩子解析失败"
+            );
+            hasError = true;
+        }
+    }
+
+    if (hasError) {
+        throw new Error("钩子结构检查失败");
+    }
+}

package/checks/checkMenu.ts

@@ -0,0 +1,168 @@
+import type { MenuConfig } from "../types/sync.js";
+import type { AddonInfo } from "../utils/scanAddons.js";
+
+import { Logger } from "../lib/logger.js";
+import { compileDisableMenuGlobRules, isMenuPathDisabledByGlobRules } from "../utils/disableMenusGlob.js";
+import { loadMenuConfigs } from "../utils/loadMenuConfigs.js";
+
+function isValidMenuPath(path: string): { ok: boolean; reason: string } {
+    if (!path) {
+        return { ok: false, reason: "path 不能为空" };
+    }
+    if (!path.startsWith("/")) {
+        return { ok: false, reason: "path 必须以 / 开头" };
+    }
+    if (path.length > 1 && path.endsWith("/")) {
+        return { ok: false, reason: "path 末尾不能是 /（根路径 / 除外）" };
+    }
+    if (path.includes("//")) {
+        return { ok: false, reason: "path 不能包含 //" };
+    }
+    if (path.includes("..")) {
+        return { ok: false, reason: "path 不能包含 .." };
+    }
+    return { ok: true, reason: "" };
+}
+
+type CheckMenuOptions = {
+    disableMenus?: string[];
+};
+
+type DisableMenuRule = ReturnType<typeof compileDisableMenuGlobRules>[number];
+
+function filterMenusByDisableRules(mergedMenus: MenuConfig[], rules: DisableMenuRule[]): MenuConfig[] {
+    if (rules.length === 0) {
+        return mergedMenus;
+    }
+
+    const filtered: MenuConfig[] = [];
+
+    for (const menu of mergedMenus) {
+        const menuPath = typeof (menu as any)?.path === "string" ? String((menu as any).path).trim() : "";
+        if (menuPath && isMenuPathDisabledByGlobRules(menuPath, rules)) {
+            continue;
+        }
+
+        const children = Array.isArray((menu as any)?.children) ? ((menu as any).children as MenuConfig[]) : null;
+        if (children && children.length > 0) {
+            const nextChildren = filterMenusByDisableRules(children, rules);
+            if (nextChildren.length > 0) {
+                (menu as any).children = nextChildren;
+            } else {
+                delete (menu as any).children;
+            }
+        }
+
+        filtered.push(menu);
+    }
+
+    return filtered;
+}
+
+export const checkMenu = async (addons: AddonInfo[], options: CheckMenuOptions = {}): Promise<MenuConfig[]> => {
+    let hasError = false;
+
+    const mergedMenus = await loadMenuConfigs(addons);
+
+    const disableRules = compileDisableMenuGlobRules(options.disableMenus);
+    const filteredMenus = filterMenusByDisableRules(mergedMenus, disableRules);
+
+    const stack: Array<{ menu: any; depth: number }> = [];
+    for (const m of filteredMenus) {
+        stack.push({ menu: m, depth: 1 });
+    }
+
+    const pathSet = new Set<string>();
+
+    while (stack.length > 0) {
+        const current = stack.pop() as { menu: any; depth: number };
+        const menu = current?.menu;
+        const depth = typeof current?.depth === "number" ? current.depth : 0;
+
+        if (menu === null || typeof menu !== "object") {
+            hasError = true;
+            Logger.warn({ menu: menu }, "菜单节点必须是对象");
+            continue;
+        }
+
+        if (depth > 3) {
+            hasError = true;
+            Logger.warn({ path: menu?.path, depth: depth }, "菜单层级超过 3 级（最多三级）");
+            continue;
+        }
+
+        const children = menu.children;
+        if (typeof children !== "undefined" && !Array.isArray(children)) {
+            hasError = true;
+            Logger.warn({ path: menu?.path, childrenType: typeof children }, "菜单 children 必须是数组");
+            continue;
+        }
+
+        if (Array.isArray(children) && children.length > 0) {
+            if (depth >= 3) {
+                hasError = true;
+                Logger.warn({ path: menu?.path, depth: depth }, "菜单层级超过 3 级（最多三级）");
+            } else {
+                for (const child of children) {
+                    stack.push({ menu: child, depth: depth + 1 });
+                }
+            }
+        }
+
+        const path = typeof menu.path === "string" ? menu.path.trim() : "";
+        const name = typeof menu.name === "string" ? menu.name.trim() : "";
+        const sort = typeof menu.sort === "number" ? menu.sort : 999999;
+
+        // 标准化输出（用于后续 syncMenu 直接使用）
+        if (typeof menu.path === "string") {
+            menu.path = path;
+        }
+        if (typeof menu.name === "string") {
+            menu.name = name;
+        }
+        if (typeof menu.sort === "undefined") {
+            menu.sort = sort;
+        }
+
+        if (!path) {
+            hasError = true;
+            Logger.warn({ menu: menu }, "菜单缺少 path（必须是非空字符串）");
+            continue;
+        }
+
+        const pathCheck = isValidMenuPath(path);
+        if (!pathCheck.ok) {
+            hasError = true;
+            Logger.warn({ path: path, reason: pathCheck.reason }, "菜单 path 不合法");
+        }
+
+        if (!name) {
+            hasError = true;
+            Logger.warn({ path: path, menu: menu }, "菜单缺少 name（必须是非空字符串）");
+        }
+
+        if (typeof menu.sort !== "undefined" && typeof menu.sort !== "number") {
+            hasError = true;
+            Logger.warn({ path: path, sort: menu.sort }, "菜单 sort 必须是 number");
+        }
+
+        if (typeof menu.sort === "number" && (!Number.isFinite(menu.sort) || menu.sort < 1)) {
+            hasError = true;
+            Logger.warn({ path: path, sort: menu.sort }, "菜单 sort 最小值为 1");
+        }
+
+        if (pathSet.has(path)) {
+            hasError = true;
+            Logger.warn({ path: path }, "菜单 path 重复（严格模式禁止重复 path）");
+            continue;
+        }
+
+        pathSet.add(path);
+    }
+
+    if (hasError) {
+        throw new Error("菜单结构检查失败");
+    }
+
+    return filteredMenus;
+};

package/checks/checkPlugin.ts

@@ -0,0 +1,48 @@
+import { isPlainObject } from "es-toolkit/compat";
+import { omit } from "es-toolkit/object";
+
+import { Logger } from "../lib/logger.js";
+
+export async function checkPlugin(plugins: any[]): Promise<void> {
+    let hasError = false;
+
+    for (const plugin of plugins) {
+        try {
+            if (!isPlainObject(plugin)) {
+                Logger.warn(omit(plugin, ["handler"]), "插件导出必须是对象（export default { deps, handler }）");
+                hasError = true;
+                continue;
+            }
+
+            if (!Array.isArray((plugin as any).deps)) {
+                Logger.warn(omit(plugin, ["handler"]), "插件的 deps 属性必须是字符串数组");
+                hasError = true;
+                continue;
+            }
+
+            if ((plugin as any).deps.some((depItem: any) => typeof depItem !== "string")) {
+                Logger.warn(omit(plugin, ["handler"]), "插件的 deps 属性必须是字符串数组");
+                hasError = true;
+            }
+
+            if (typeof (plugin as any).handler !== "function") {
+                Logger.warn(omit(plugin, ["handler"]), "插件的 handler 属性必须是函数");
+                hasError = true;
+                continue;
+            }
+        } catch (error: any) {
+            Logger.error(
+                {
+                    err: error,
+                    item: plugin
+                },
+                "插件解析失败"
+            );
+            hasError = true;
+        }
+    }
+
+    if (hasError) {
+        throw new Error("插件结构检查失败");
+    }
+}