befly 3.16.11 → 3.17.2

package/index.js

@@ -0,0 +1,326 @@
+/**
+ * Befly 框架主入口文件
+ * 提供简洁的框架接口，核心逻辑已提取到 loader 层
+ */
+
+// 配置
+import beflyConfig from "./configs/beflyConfig.json";
+import beflyMenus from "./configs/beflyMenus.json";
+
+// 检查
+import { checkApi } from "./checks/api.js";
+import { checkConfig } from "./checks/config.js";
+import { checkHook } from "./checks/hook.js";
+import { checkMenu } from "./checks/menu.js";
+import { checkPlugin } from "./checks/plugin.js";
+import { checkTable } from "./checks/table.js";
+// ========== 相对导入（项目内部文件） ==========
+// 基础设施
+import { Connect } from "./lib/connect.js";
+import { Logger } from "./lib/logger.js";
+// 路由处理
+import { apiHandler } from "./router/api.js";
+import { staticHandler } from "./router/static.js";
+// 同步
+import { syncApi } from "./sync/api.js";
+import { syncCache } from "./sync/cache.js";
+import { syncDev } from "./sync/dev.js";
+import { syncMenu } from "./sync/menu.js";
+import { syncDbApply, syncDbCheck } from "./scripts/syncDb/index.js";
+// 工具
+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 { omit } from "./utils/util.js";
+import { sortModules } from "./utils/sortModules.js";
+
+function prefixMenuPaths(menus, prefix) {
+    const output = [];
+    for (const menu of menus) {
+        const nextPath = menu.path === "/" ? `/${prefix}` : `/${prefix}${menu.path}`;
+        const nextMenu = {
+            name: menu.name,
+            path: nextPath,
+            sort: menu.sort
+        };
+        if (Array.isArray(menu.children)) {
+            const children = [];
+            for (const child of menu.children) {
+                children.push({
+                    name: child.name,
+                    path: child.path,
+                    sort: child.sort
+                });
+            }
+            nextMenu.children = children;
+        }
+        output.push(nextMenu);
+    }
+    return output;
+}
+
+async function ensureSyncPrerequisites(ctx) {
+    const missingCtxKeys = [];
+    if (!ctx.redis) missingCtxKeys.push("ctx.redis");
+    if (!ctx.mysql) missingCtxKeys.push("ctx.mysql");
+    if (!ctx.cache) missingCtxKeys.push("ctx.cache");
+    if (missingCtxKeys.length > 0) {
+        throw new Error(`启动失败：${missingCtxKeys.join("、")} 未初始化`, {
+            cause: null,
+            code: "runtime",
+            subsystem: "sync",
+            operation: "ctxCheck",
+            missingCtxKeys: missingCtxKeys
+        });
+    }
+
+    const requiredTables = ["beflyApi", "beflyMenu", "beflyAdmin", "beflyRole"];
+    const missingTables = [];
+
+    for (const table of requiredTables) {
+        const tableExistsResult = await ctx.mysql.tableExists(table);
+        if (!tableExistsResult.data) {
+            missingTables.push(table);
+        }
+    }
+
+    if (missingTables.length > 0) {
+        throw new Error(`同步依赖表缺失: ${missingTables.join("、")}`, {
+            cause: null,
+            code: "runtime",
+            subsystem: "sync",
+            operation: "tableExists",
+            missingTables: missingTables
+        });
+    }
+}
+
+/**
+ * Befly 框架核心类
+ * 职责：管理应用上下文和生命周期
+ */
+export class Befly {
+    /** 应用上下文 */
+    context = {
+        env: {},
+        config: {}
+    };
+
+    // 菜单配置
+    menus = [];
+
+    /** 插件列表 */
+    plugins = [];
+
+    /** 钩子列表 */
+    hooks = [];
+
+    /** API 路由映射表 */
+    apis = {};
+
+    /** create 阶段扫描得到的 API 列表 */
+    scanApis = [];
+
+    /** create 阶段扫描得到的插件列表 */
+    scanPlugins = [];
+
+    /** create 阶段扫描得到的钩子列表 */
+    scanHooks = [];
+
+    /** 是否由工厂创建 */
+    createdByFactory = false;
+
+    /**
+     * 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"), prefixMenuPaths(menus, "app"));
+        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"
+            });
+        }
+
+        instance.scanApis = apis;
+        instance.scanPlugins = plugins;
+        instance.scanHooks = hooks;
+
+        return instance;
+    }
+
+    /**
+     * 启动完整的生命周期流程
+     * @returns HTTP 服务器实例
+     */
+    async start() {
+        try {
+            if (!this.createdByFactory) {
+                throw new Error("请使用 Befly.create(...) 创建实例后再调用 start", {
+                    cause: null,
+                    code: "policy",
+                    subsystem: "start",
+                    operation: "factoryGuard"
+                });
+            }
+
+            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）
+            // 说明：连接职责收敛到启动期单点；插件只消费已连接实例（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"
+                });
+            }
+            await ensureSyncPrerequisites(this.context);
+
+            // 5. 自动同步（PM2 cluster：主进程执行，其它进程等待同步完成）
+            if (isPrimaryProcess(this.context.env)) {
+                await syncApi(this.context, this.scanApis);
+                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"
+                });
+            }
+
+            // 4. 加载所有 API
+            for (const api of this.scanApis) {
+                this.apis[api.apiPath] = api;
+            }
+
+            // 6. 启动 HTTP服务器
+            const apiFetch = apiHandler(this.apis, this.hooks, this.context);
+            const staticFetch = staticHandler(this.context.config.cors);
+
+            const server = Bun.serve({
+                port: this.context.config.appPort || 3000,
+                hostname: this.context.config.appHost || "0.0.0.0",
+                // 开发模式下启用详细错误信息
+                development: this.context.env.RUN_MODE === "development",
+                // 空闲连接超时时间（秒），防止恶意连接占用资源
+                fetch: async (req, server) => {
+                    const url = new URL(req.url);
+
+                    if (url.pathname === "/") {
+                        return Response.json({ code: 0, msg: `${this.context.config.appName} 接口服务已启动` });
+                    }
+
+                    if (url.pathname.startsWith("/api/")) {
+                        return apiFetch(req, server);
+                    }
+
+                    return staticFetch(req);
+                },
+                error: (error) => {
+                    Logger.error("服务启动时发生错误", error);
+                    // 开发模式下返回详细错误信息
+                    if (this.context.env.RUN_MODE === "development") {
+                        return Response.json(
+                            {
+                                code: 1,
+                                msg: "内部服务器错误",
+                                error: error.message,
+                                stack: error.stack
+                            },
+                            { status: 200 }
+                        );
+                    }
+                    return Response.json({ code: 1, msg: "内部服务器错误" }, { status: 200 });
+                }
+            });
+
+            const finalStartupTime = calcPerfTime(serverStartTime);
+
+            Logger.info(`${this.context.config.appName} 启动成功!`);
+            Logger.info(`服务器启动耗时: ${finalStartupTime}`);
+            Logger.info(`服务器监听地址: ${server.url}`);
+            console.log(`${this.context.config.appName} 启动成功!`);
+            console.log(`服务器启动耗时: ${finalStartupTime}`);
+            console.log(`服务器监听地址: ${server.url}`);
+            // 注意：作为库代码，这里不注册 SIGINT/SIGTERM 处理器，也不调用 process.exit。
+            // 宿主应用应自行处理信号并决定退出策略（包括是否调用 server.stop / Connect.disconnect / Logger.flush）。
+            return server;
+        } catch (error) {
+            // 注意：这里不能直接 process.exit(1)
+            // - Logger 是异步缓冲写入，exit 会导致日志来不及 flush（实际项目里表现为“完全没打印”）
+            // - 作为库代码，也不应该强行终止宿主进程
+
+            // 注意：测试要求 start() 失败时必须 Logger.error 一次，所以这里始终调用 error。
+            Logger.error("项目启动失败", error, null, false);
+
+            // 尽力把错误日志落盘/输出后再把异常抛给上层。
+            try {
+                await Logger.flush();
+                await Logger.shutdown();
+            } catch {
+                // ignore
+            }
+
+            throw new Error("运行时错误", {
+                cause: error,
+                code: error?.code || "runtime",
+                subsystem: "start",
+                operation: "start"
+            });
+        }
+    }
+}
+
+async function dbCheck(config = {}) {
+    const mergedConfig = deepMerge(beflyConfig, config);
+    return syncDbCheck(mergedConfig.mysql);
+}
+
+async function dbApply(config = {}) {
+    const mergedConfig = deepMerge(beflyConfig, config);
+    return syncDbApply(mergedConfig.mysql);
+}
+
+export { dbApply, dbCheck, Logger };