befly 3.18.2 → 3.18.4

package/apis/auth/login.js

@@ -1,7 +1,7 @@
 import { UAParser } from "ua-parser-js";
 
 import adminTable from "../../tables/admin.json";
-import { toSessionTtlSeconds } from "../../utils/toSessionTtlSeconds.js";
+import { toSessionTtlSeconds } from "../../utils/util.js";
 
 export default {
     name: "管理员登录",

package/checks/api.js

@@ -8,7 +8,7 @@ z.config(z.locales.zhCN());
 
 const noTrimString = z.string().refine(isNoTrimStringAllowEmpty, "不允许首尾空格");
 const lowerCamelRegex = /^_?[a-z][a-z0-9]*(?:[A-Z][a-z0-9]*)*$/;
-const apiPathRegex = /^\/api\/(core|app)\/[a-z][a-zA-Z0-9]*(?:\/[a-z][a-zA-Z0-9]*)*$/;
+const apiPathRegex = /^\/api\/(?:core\/[a-z][a-zA-Z0-9]*(?:\/[a-z][a-zA-Z0-9]*)*|(?!app(?:\/|$))[a-z][a-zA-Z0-9]*(?:\/[a-z][a-zA-Z0-9]*)*)$/;
 
 const fieldSchema = z
     .object({

package/checks/hook.js

@@ -17,7 +17,7 @@ const hookSchema = z
         fileName: noTrimString.min(1),
         apiPath: noTrimString.min(1),
         handler: z.custom((value) => typeof value === "function"),
-        deps: z.array(noTrimString)
+        order: z.number()
     })
     .strict();
 

package/checks/menu.js

@@ -5,7 +5,7 @@ import { formatZodIssues } from "../utils/formatZodIssues.js";
 
 z.config(z.locales.zhCN());
 
-const fullMenuPathRegex = /^\/(?:core(?:\/[a-z][a-z0-9]*(?:[A-Z][a-z0-9]*)*)*|(?:(?!app(?:\/|$))[a-z][a-z0-9]*(?:[A-Z][a-z0-9]*)*(?:\/[a-z][a-z0-9]*(?:[A-Z][a-z0-9]*)*)*)?)$/;
+const fullMenuPathRegex = /^\/(?:core(?:\/[a-z][a-z0-9]*(?:[A-Z][a-z0-9]*)*)*|(?:[a-z][a-z0-9]*(?:[A-Z][a-z0-9]*)*(?:\/[a-z][a-z0-9]*(?:[A-Z][a-z0-9]*)*)*)?)$/;
 const childMenuPathRegex = /^\/[a-z][a-z0-9]*(?:[A-Z][a-z0-9]*)*$/;
 
 const childMenuSchema = z
@@ -36,7 +36,7 @@ const menuListSchema = z.array(menuSchema).superRefine((menuList, refineCtx) =>
             if (!fullMenuPathRegex.test(childFullPath)) {
                 refineCtx.addIssue({
                     code: z.ZodIssueCode.custom,
-                    message: "菜单完整路径必须是 /core/xxx 或无前缀路径（禁止 /app 前缀）",
+                    message: "菜单完整路径必须是 /core/xxx 或无前缀路径",
                     path: [menuIndex, "children", childIndex, "path"]
                 });
             }

package/checks/plugin.js

@@ -17,7 +17,7 @@ const pluginSchema = z
         fileName: noTrimString.min(1),
         apiPath: noTrimString.min(1),
         handler: z.custom((value) => typeof value === "function"),
-        deps: z.array(noTrimString)
+        order: z.number()
     })
     .strict();
 

package/hooks/auth.js

@@ -1,7 +1,7 @@
-import { toSessionTtlSeconds } from "../utils/toSessionTtlSeconds.js";
+import { toSessionTtlSeconds } from "../utils/util.js";
 
 export default {
-    deps: [],
+    order: 1,
     handler: async (befly, ctx) => {
         const authHeader = ctx.headers.get("authorization");
         const ttlSeconds = toSessionTtlSeconds(befly.config?.session?.expireDays);

package/hooks/parser.js

@@ -13,7 +13,7 @@ const xmlParser = new XMLParser();
  * - body: "raw" 时跳过解析，由 handler 自行处理原始请求
  */
 export default {
-    deps: ["auth"],
+    order: 2,
     handler: async (befly, ctx) => {
         // apiBody=raw 模式：跳过解析，保留原始请求供 handler 自行处理
         // 适用于：微信回调、支付回调、webhook 等需要手动解密/验签的场景

package/hooks/permission.js

@@ -12,7 +12,7 @@ import { isValidPositiveInt } from "../utils/is.js";
  * - 其他角色：检查 Redis 中的角色权限集合
  */
 export default {
-    deps: ["validator"],
+    order: 4,
     handler: async (befly, ctx) => {
         // 1. 接口无需权限
         if (ctx.apiAuth === false) {

package/hooks/validator.js

@@ -9,7 +9,7 @@ import { snakeCase } from "../utils/util.js";
  * 根据 API 定义的 fields 和 required 验证请求参数
  */
 export default {
-    deps: ["parser"],
+    order: 3,
     handler: async (befly, ctx) => {
         // 仅保留 fields 中声明的字段，并支持 snake_case 入参回退（例如 agent_id -> agentId）
         const rawBody = isPlainObject(ctx.body) ? ctx.body : {};

package/index.js

@@ -32,7 +32,6 @@ import { calcPerfTime } from "./utils/calcPerfTime.js";
 import { scanSources } from "./utils/scanSources.js";
 import { isPrimaryProcess } from "./utils/is.js";
 import { deepMerge } from "./utils/deepMerge.js";
-import { sortModules } from "./utils/sortModules.js";
 
 function prefixMenuPaths(menus, prefix) {
     const output = [];
@@ -95,164 +94,113 @@ async function ensureSyncPrerequisites(ctx) {
     }
 }
 
-/**
- * Befly 框架核心类
- * 职责：管理应用上下文和生命周期
- */
-export class Befly {
-    /** 应用上下文 */
-    context = {
-        env: {},
-        config: {}
-    };
-
-    // 菜单配置
-    menus = [];
-
-    /** 插件列表 */
-    plugins = [];
-
-    /** 钩子列表 */
-    hooks = [];
-
-    /** API 路由映射表 */
-    apis = {};
+export async function dbCheck(mysqlConfig) {
+    return syncDbCheck(mysqlConfig);
+}
 
-    /** create 阶段扫描得到的 API 列表 */
-    scanApis = [];
+export async function dbApply(mysqlConfig) {
+    return syncDbApply(mysqlConfig);
+}
 
-    /** create 阶段扫描得到的插件列表 */
-    scanPlugins = [];
+export async function createBefly(env = {}, config = {}, menus = []) {
+    const mergedConfig = deepMerge(beflyConfig, config);
+    const mergedMenus = deepMerge(prefixMenuPaths(beflyMenus, "core"), menus);
 
-    /** create 阶段扫描得到的钩子列表 */
-    scanHooks = [];
+    const configHasError = await checkConfig(mergedConfig);
+    const { apis, tables, plugins, hooks } = await scanSources();
 
-    /** 是否由工厂创建 */
-    createdByFactory = false;
+    const apiHasError = await checkApi(apis);
+    const tableHasError = await checkTable(tables);
+    const pluginHasError = await checkPlugin(plugins);
+    const hookHasError = await checkHook(hooks);
+    const menuHasError = await checkMenu(mergedMenus);
 
-    /**
-     * A 方案：异步工厂，先做预检，失败则不返回实例。
-     */
-    static async create(env = {}, config = {}, menus = []) {
-        const instance = new Befly();
-        instance.context.env = env;
-        instance.context.config = deepMerge(beflyConfig, config);
-        instance.menus = deepMerge(prefixMenuPaths(beflyMenus, "core"), menus);
-        instance.createdByFactory = true;
-
-        const configHasError = await checkConfig(instance.context.config);
-        const { apis, tables, plugins, hooks } = await scanSources();
-
-        const apiHasError = await checkApi(apis);
-        const tableHasError = await checkTable(tables);
-        const pluginHasError = await checkPlugin(plugins);
-        const hookHasError = await checkHook(hooks);
-        const menuHasError = await checkMenu(instance.menus);
-
-        if (configHasError || apiHasError || tableHasError || pluginHasError || hookHasError || menuHasError) {
-            throw new Error("检查失败：存在配置/结构问题", {
-                cause: null,
-                code: "policy",
-                subsystem: "checks",
-                operation: "checkAll"
-            });
-        }
+    if (configHasError || apiHasError || tableHasError || pluginHasError || hookHasError || menuHasError) {
+        throw new Error("检查失败：存在配置/结构问题", {
+            cause: null,
+            code: "policy",
+            subsystem: "checks",
+            operation: "checkAll"
+        });
+    }
 
-        instance.scanApis = apis;
-        instance.scanPlugins = plugins;
-        instance.scanHooks = hooks;
+    return new Befly({
+        env: env,
+        config: mergedConfig,
+        menus: mergedMenus,
+        apis: apis,
+        hooks: hooks,
+        plugins: plugins,
+        createdByFactory: true
+    });
+}
 
-        return instance;
+/**
+ * Befly 框架核心类
+ * 职责：管理应用上下文和生命周期
+ */
+export class Befly {
+    constructor(init = {}) {
+        this.context = {
+            env: init.env || {},
+            config: init.config || {}
+        };
+        this.menus = Array.isArray(init.menus) ? init.menus : [];
+        this.hooks = Array.isArray(init.hooks) ? init.hooks : [];
+        this.apis = Array.isArray(init.apis) ? init.apis : [];
+        this.plugins = Array.isArray(init.plugins) ? init.plugins : [];
+        this.createdByFactory = init.createdByFactory === true;
     }
 
-    ensureCreatedByFactory(methodName) {
+    ensureCreatedByFactory() {
         if (this.createdByFactory) {
             return;
         }
 
-        throw new Error(`请使用 Befly.create(...) 创建实例后再调用 ${methodName}`, {
+        throw new Error("请使用 createBefly(...) 创建实例后再调用 start", {
             cause: null,
             code: "policy",
-            subsystem: methodName === "start" ? "start" : "syncDb",
+            subsystem: "start",
             operation: "factoryGuard"
         });
     }
 
-    async dbCheck() {
-        this.ensureCreatedByFactory("dbCheck");
-
-        return syncDbCheck(this.context.config.mysql);
-    }
-
-    async dbApply() {
-        this.ensureCreatedByFactory("dbApply");
-
-        return syncDbApply(this.context.config.mysql);
-    }
-
     /**
      * 启动完整的生命周期流程
      * @returns HTTP 服务器实例
      */
     async start() {
         try {
-            this.ensureCreatedByFactory("start");
+            this.ensureCreatedByFactory();
 
             const serverStartTime = Bun.nanoseconds();
-            if (!Array.isArray(this.scanApis) || !Array.isArray(this.scanPlugins) || !Array.isArray(this.scanHooks)) {
-                throw new Error("请使用 Befly.create(...) 完成预检后再调用 start", {
-                    cause: null,
-                    code: "policy",
-                    subsystem: "start",
-                    operation: "preflightGuard"
-                });
-            }
 
-            // 1. 启动期建立基础连接（SQL + Redis）
+            // 启动期建立基础连接（SQL + Redis）
             // 说明：连接职责收敛到启动期单点；插件只消费已连接实例（Connect.getSql/getRedis）。
             await Connect.connectRedis(this.context.config.redis);
             await Connect.connectMysql(this.context.config.mysql);
 
-            // 2. 加载插件
-            const sortedPlugins = sortModules(this.scanPlugins);
-            if (sortedPlugins) {
-                for (const item of sortedPlugins) {
-                    const pluginInstance = await item.handler(this.context);
-                    this.context[item.fileName] = pluginInstance;
-                }
-            } else {
-                throw new Error("插件依赖关系错误", {
-                    cause: null,
-                    code: "policy"
-                });
+            // 加载插件
+            for (const item of this.plugins.sort((a, b) => a.order - b.order)) {
+                this.context[item.fileName] = await item.handler(this.context);
             }
             await ensureSyncPrerequisites(this.context);
 
-            // 5. 自动同步（PM2 cluster：主进程执行，其它进程等待同步完成）
+            // 自动同步（PM2 cluster：主进程执行，其它进程等待同步完成）
             if (isPrimaryProcess(this.context.env)) {
-                await syncApi(this.context, this.scanApis);
+                await syncApi(this.context, this.apis);
                 await syncMenu(this.context, this.menus);
                 await syncDev(this.context);
                 await syncCache(this.context);
             }
 
-            // 3. 加载钩子
-            const sortedHooks = sortModules(this.scanHooks);
-            if (sortedHooks) {
-                this.hooks = sortedHooks;
-            } else {
-                throw new Error("钩子依赖关系错误", {
-                    cause: null,
-                    code: "policy"
-                });
-            }
+            // 加载钩子
+            this.hooks = this.hooks.sort((a, b) => a.order - b.order);
 
-            // 4. 加载所有 API
-            for (const api of this.scanApis) {
-                this.apis[api.apiPath] = api;
-            }
+            // 加载所有 API
+            this.apis = Object.fromEntries(this.apis.map((api) => [api.apiPath, api]));
 
-            // 6. 启动 HTTP服务器
+            // 启动 HTTP服务器
             const apiFetch = apiHandler(this.apis, this.hooks, this.context);
             const staticFetch = staticHandler(this.context.config.cors);
 

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "befly",
-    "version": "3.18.2",
-    "gitHead": "f6fdc07aded11161f7722df5da27bc9166692caf",
+    "version": "3.18.4",
+    "gitHead": "403482610311798cc566fb6b550c069740fa413c",
     "private": false,
     "description": "Befly - 为 Bun 专属打造的 JavaScript API 接口框架核心引擎",
     "keywords": [

package/plugins/cache.js

@@ -9,7 +9,7 @@ import { CacheHelper } from "../lib/cacheHelper.js";
  * 缓存插件
  */
 export default {
-    deps: ["logger", "redis", "mysql"],
+    order: 6,
     async handler(befly) {
         return new CacheHelper({ mysql: befly.mysql, redis: befly.redis });
     }

package/plugins/config.js

@@ -4,7 +4,7 @@
  */
 
 export default {
-    deps: [],
+    order: 1,
     handler: (befly) => {
         return befly.config;
     }

package/plugins/email.js

@@ -16,7 +16,7 @@ const defaultConfig = {
 };
 
 export default {
-    deps: ["mysql", "logger", "config"],
+    order: 7,
     async handler(befly) {
         // 从 befly.config.email 获取配置
         const emailConfigRaw = (befly.config ? befly.config["email"] : undefined) || {};

package/plugins/logger.js

@@ -9,7 +9,7 @@ import { Logger } from "../lib/logger.js";
  * 日志插件
  */
 export default {
-    deps: [],
+    order: 2,
     async handler(befly) {
         // 配置 Logger
         if (befly.config && befly.config.logger) {

package/plugins/mysql.js

@@ -11,7 +11,7 @@ import { Logger } from "../lib/logger.js";
  * 数据库插件
  */
 export default {
-    deps: ["logger", "redis"],
+    order: 5,
     async handler(befly) {
         try {
             // 创建数据库管理器实例

package/plugins/redis.js

@@ -11,7 +11,7 @@ import { RedisHelper } from "../lib/redisHelper.js";
  * Redis 插件
  */
 export default {
-    deps: ["logger"],
+    order: 4,
     async handler(befly) {
         const env = befly.config?.runMode;
         const redisPrefix = befly.config?.redis?.prefix;

package/plugins/tool.js

@@ -142,7 +142,7 @@ export function sha256(value) {
 }
 
 export default {
-    deps: [],
+    order: 3,
     handler: () => {
         return {
             Yes: Yes,

package/sync/api.js

@@ -7,8 +7,9 @@ const getApiParentPath = (apiPath) => {
         .filter((s) => s.length > 0);
 
     // segments 示例：
-    // - /api/app/test/hi -> ["api","app","test","hi"]
-    const take = 3;
+    // - /api/core/test/hi -> ["api","core","test","hi"]
+    // - /api/test/hi -> ["api","test","hi"]
+    const take = segments[1] === "core" ? 3 : 2;
     const parentSegments = segments.slice(0, Math.min(take, segments.length));
     if (parentSegments.length === 0) return "";
     return `/${parentSegments.join("/")}`;

package/utils/scanFiles.js

@@ -13,7 +13,7 @@ import { isPlainObject } from "./is.js";
 //   fileName: "auth",
 //   apiPath: "/api/core/auth",
 //   name: "auth",
-//   deps: [ "cors" ],
+//   order: 1,
 //   handler: [AsyncFunction: handler],
 // }
 // 🔥[ plugins ]-112 {
@@ -24,7 +24,7 @@ import { isPlainObject } from "./is.js";
 //   fileName: "cache",
 //   apiPath: "/api/core/cache",
 //   name: "cache",
-//   deps: [ "logger", "redis", "mysql" ],
+//   order: 1,
 //   handler: [AsyncFunction: handler],
 // }
 // 🔥[ tables ]-112 {

package/utils/util.js

@@ -357,6 +357,24 @@ export function keyBy(items, getKey) {
     return out;
 }
 
+/**
+ * 将 session 有效天数转换为秒。
+ */
+export function toSessionTtlSeconds(ttlDays) {
+    if (typeof ttlDays === "number" && Number.isFinite(ttlDays) && ttlDays > 0) {
+        return Math.floor(ttlDays * 24 * 60 * 60);
+    }
+
+    if (typeof ttlDays === "string") {
+        const parsed = Number(ttlDays.trim());
+        if (Number.isFinite(parsed) && parsed > 0) {
+            return Math.floor(parsed * 24 * 60 * 60);
+        }
+    }
+
+    return 7 * 24 * 60 * 60;
+}
+
 /**
  * 生成短 ID
  * 由时间戳（base36）+ 随机字符组成，约 13 位

package/utils/sortModules.js

@@ -1,75 +0,0 @@
-import { Logger } from "../lib/logger.js";
-
-/**
- * 按 deps 拓扑排序 scanSources 扫描得到的插件/钩子。
- *
- * 说明：
- * - 输入为 scanSources/scanFiles 的条目数组：每个条目包含 fileName 与 deps。
- * - deps 里的字符串会与 fileName 匹配。
- * - 若出现：重复 name、缺失依赖、循环依赖，则返回 false。
- */
-export function sortModules(items) {
-    const result = [];
-    const visited = new Set();
-    const visiting = new Set();
-
-    const nameToItem = {};
-    let isPass = true;
-
-    // 1) 建表 + 重名检查
-    for (const item of items) {
-        if (nameToItem[item.fileName]) {
-            Logger.error("模块 名称重复，无法根据 deps 唯一定位", null, {
-                name: item.fileName,
-                first: nameToItem[item.fileName],
-                second: item
-            });
-            isPass = false;
-            continue;
-        }
-
-        nameToItem[item.fileName] = item;
-    }
-
-    if (!isPass) return false;
-
-    // 2) 依赖存在性检查
-    for (const item of items) {
-        for (const dep of item.deps) {
-            if (!nameToItem[dep]) {
-                Logger.error("模块 依赖未找到", null, { module: item.fileName, dependency: dep });
-                isPass = false;
-            }
-        }
-    }
-
-    if (!isPass) return false;
-
-    // 3) 拓扑排序（DFS）
-    const visit = (name) => {
-        if (visited.has(name)) return;
-        if (visiting.has(name)) {
-            Logger.error("模块 循环依赖", null, { module: name });
-            isPass = false;
-            return;
-        }
-
-        const item = nameToItem[name];
-        if (!item) return;
-
-        visiting.add(name);
-        for (const dep of item.deps) {
-            visit(dep);
-        }
-        visiting.delete(name);
-
-        visited.add(name);
-        result.push(item);
-    };
-
-    for (const item of items) {
-        visit(item.fileName);
-    }
-
-    return isPass ? result : false;
-}

package/utils/toSessionTtlSeconds.js

@@ -1,14 +0,0 @@
-export function toSessionTtlSeconds(ttlDays) {
-    if (typeof ttlDays === "number" && Number.isFinite(ttlDays) && ttlDays > 0) {
-        return Math.floor(ttlDays * 24 * 60 * 60);
-    }
-
-    if (typeof ttlDays === "string") {
-        const parsed = Number(ttlDays.trim());
-        if (Number.isFinite(parsed) && parsed > 0) {
-            return Math.floor(parsed * 24 * 60 * 60);
-        }
-    }
-
-    return 7 * 24 * 60 * 60;
-}