befly 3.2.1 → 3.3.1

package/lifecycle/checker.ts

@@ -0,0 +1,165 @@
+/**
+ * 系统检查管理器
+ * 负责在框架启动前执行系统检查
+ */
+
+import { join, basename } from 'pathe';
+import { Logger } from '../lib/logger.js';
+import { calcPerfTime } from '../util.js';
+import { paths } from '../paths.js';
+import { scanAddons, getAddonDir, addonDirExists } from '../util.js';
+
+/**
+ * 系统检查器类
+ */
+export class Checker {
+    /**
+     * 执行所有系统检查
+     */
+    static async run(): Promise<void> {
+        try {
+            const checkStartTime = Bun.nanoseconds();
+
+            const glob = new Bun.Glob('*.{ts}');
+
+            // 统计信息
+            const stats = {
+                totalChecks: 0,
+                passedChecks: 0,
+                failedChecks: 0
+            };
+
+            // 1. 优先执行资源冲突检测（如果存在）
+            try {
+                const conflictCheckPath = join(paths.rootCheckDir, 'conflict.ts');
+                const conflictCheckFile = Bun.file(conflictCheckPath);
+
+                if (await conflictCheckFile.exists()) {
+                    stats.totalChecks++;
+                    const conflictCheckStart = Bun.nanoseconds();
+
+                    const conflictModule = await import(conflictCheckPath);
+                    const conflictCheckFn = conflictModule.default;
+
+                    if (typeof conflictCheckFn === 'function') {
+                        const conflictResult = await conflictCheckFn();
+                        const conflictCheckTime = calcPerfTime(conflictCheckStart);
+
+                        if (typeof conflictResult !== 'boolean') {
+                            Logger.warn(`核心检查 conflict.ts 返回值必须为 true 或 false，当前为 ${typeof conflictResult}，耗时: ${conflictCheckTime}`);
+                            stats.failedChecks++;
+                        } else if (conflictResult === true) {
+                            stats.passedChecks++;
+                            Logger.info(`核心检查 conflict.ts 通过，耗时: ${conflictCheckTime}`);
+                        } else {
+                            Logger.warn(`核心检查未通过: conflict.ts，耗时: ${conflictCheckTime}`);
+                            stats.failedChecks++;
+                            // 资源冲突检测失败，立即终止
+                            Logger.warn('资源冲突检测失败，无法继续启动', {
+                                totalChecks: stats.totalChecks,
+                                passedChecks: stats.passedChecks,
+                                failedChecks: stats.failedChecks
+                            });
+                            process.exit(1);
+                        }
+                    }
+                }
+            } catch (error: any) {
+                Logger.error('执行资源冲突检测时出错:', error);
+                stats.failedChecks++;
+            }
+
+            // 2. 检查目录列表：先核心，后项目，最后 addons
+            // 检查所有 checks 目录
+            const checkDirs = [{ path: paths.rootCheckDir, type: 'core' as const }]; // 添加所有 addon 的 checks 目录
+            const addons = scanAddons();
+            for (const addon of addons) {
+                if (addonDirExists(addon, 'checks')) {
+                    checkDirs.push({
+                        path: getAddonDir(addon, 'checks'),
+                        type: 'addon' as const,
+                        addonName: addon
+                    });
+                }
+            }
+
+            // 按顺序扫描并执行检查函数
+            for (const checkConfig of checkDirs) {
+                const { path: checkDir, type } = checkConfig;
+                const addonName = 'addonName' in checkConfig ? checkConfig.addonName : undefined;
+                const checkTypeLabel = type === 'core' ? '核心' : type === 'project' ? '项目' : `组件${addonName}`;
+                Logger.info(`开始执行${checkTypeLabel}检查，目录: ${checkDir}`);
+
+                for await (const file of glob.scan({
+                    cwd: checkDir,
+                    onlyFiles: true,
+                    absolute: true
+                })) {
+                    const fileName = basename(file);
+                    if (fileName.startsWith('_')) continue; // 跳过以下划线开头的文件
+
+                    // 跳过已经执行过的 conflict.ts
+                    if (type === 'core' && fileName === 'conflict.ts') continue;
+
+                    try {
+                        stats.totalChecks++;
+                        const singleCheckStart = Bun.nanoseconds();
+
+                        // 导入检查模块
+                        const checkModule = await import(file);
+
+                        // 获取 default 导出的检查函数
+                        const checkFn = checkModule.default;
+
+                        // 执行检查函数
+                        if (typeof checkFn === 'function') {
+                            const checkResult = await checkFn();
+                            const singleCheckTime = calcPerfTime(singleCheckStart);
+
+                            // 检查返回值是否为 boolean
+                            if (typeof checkResult !== 'boolean') {
+                                Logger.warn(`${checkTypeLabel}检查 ${fileName} 返回值必须为 true 或 false，当前为 ${typeof checkResult}，耗时: ${singleCheckTime}`);
+                                stats.failedChecks++;
+                            } else if (checkResult === true) {
+                                stats.passedChecks++;
+                                Logger.info(`${checkTypeLabel}检查 ${fileName} 通过，耗时: ${singleCheckTime}`);
+                            } else {
+                                Logger.warn(`${checkTypeLabel}检查未通过: ${fileName}，耗时: ${singleCheckTime}`);
+                                stats.failedChecks++;
+                            }
+                        } else {
+                            const singleCheckTime = calcPerfTime(singleCheckStart);
+                            Logger.warn(`${checkTypeLabel}检查文件 ${fileName} 未找到 default 导出的检查函数，耗时: ${singleCheckTime}`);
+                            stats.failedChecks++;
+                        }
+                    } catch (error: any) {
+                        const singleCheckTime = calcPerfTime(Bun.nanoseconds());
+                        Logger.error(`${checkTypeLabel}检查失败 ${fileName}，耗时: ${singleCheckTime}`, error);
+                        stats.failedChecks++;
+                    }
+                }
+            }
+
+            const totalCheckTime = calcPerfTime(checkStartTime);
+
+            // 输出检查结果统计
+            Logger.info(`系统检查完成! 总耗时: ${totalCheckTime}，总检查数: ${stats.totalChecks}, 通过: ${stats.passedChecks}, 失败: ${stats.failedChecks}`);
+
+            if (stats.failedChecks > 0) {
+                Logger.error('统检查失败，无法继续启动', {
+                    totalChecks: stats.totalChecks,
+                    passedChecks: stats.passedChecks,
+                    failedChecks: stats.failedChecks
+                });
+                process.exit(1);
+            } else if (stats.totalChecks > 0) {
+                Logger.info(`所有系统检查通过!`);
+            } else {
+                Logger.info(`未执行任何检查`);
+            }
+        } catch (error: any) {
+            Logger.error('执行系统检查时发生错误', error);
+            process.exit(1);
+        }
+    }
+}

package/lifecycle/cluster.ts

@@ -0,0 +1,241 @@
+/**
+ * Cluster Manager - 集群管理器
+ * 负责多进程启动、自动重启、优雅关闭
+ */
+
+import { join } from 'pathe';
+import type { Subprocess } from 'bun';
+import { Logger } from '../lib/logger.js';
+
+export interface ClusterOptions {
+    /** 实例数量（数字或 'max'） */
+    instances: number | 'max';
+    /** 起始端口 */
+    startPort: number;
+    /** 主机地址 */
+    host: string;
+    /** 项目根目录 */
+    projectRoot: string;
+    /** main.ts 文件路径 */
+    mainFile: string;
+    /** 环境变量 */
+    env?: Record<string, string>;
+}
+
+interface WorkerInfo {
+    id: number;
+    port: number;
+    process: Subprocess;
+    restartCount: number;
+    lastRestartTime: number;
+}
+
+export class ClusterManager {
+    private workers: Map<number, WorkerInfo> = new Map();
+    private isShuttingDown = false;
+    private readonly MAX_RESTARTS = 10; // 最大重启次数
+    private readonly RESTART_DELAY = 1000; // 重启延迟（毫秒）
+    private readonly RESTART_WINDOW = 60000; // 重启计数窗口（1分钟）
+
+    constructor(private options: ClusterOptions) {}
+
+    /**
+     * 启动集群
+     */
+    async start(): Promise<void> {
+        const instances = this.getInstanceCount();
+        const { startPort, host } = this.options;
+
+        Logger.info(`启动集群模式: ${instances} 个实例\n`);
+        Logger.info(`端口范围: ${startPort} - ${startPort + instances - 1}`);
+        Logger.info(`主机地址: ${host}`);
+        Logger.info(`环境: production\n`);
+
+        // 启动所有 Worker
+        for (let i = 0; i < instances; i++) {
+            const port = startPort + i;
+            this.spawnWorker(i, port);
+        }
+
+        // 监听进程信号
+        this.setupSignalHandlers();
+
+        Logger.info(`集群启动成功！\n`);
+        this.printWorkerStatus();
+    }
+
+    /**
+     * 获取实例数量
+     */
+    private getInstanceCount(): number {
+        const { instances } = this.options;
+
+        if (instances === 'max') {
+            return navigator.hardwareConcurrency || 4;
+        }
+
+        const count = typeof instances === 'string' ? parseInt(instances) : instances;
+
+        if (isNaN(count) || count < 1) {
+            Logger.warn(`无效的实例数量 "${instances}"，使用默认值 4`);
+            return 4;
+        }
+
+        return count;
+    }
+
+    /**
+     * 启动单个 Worker
+     */
+    private spawnWorker(id: number, port: number): void {
+        const { projectRoot, mainFile, host, env = {} } = this.options;
+
+        Logger.info(`启动 Worker ${id} (端口 ${port})...`);
+
+        // 检查环境变量文件
+        const envFile = join(projectRoot, '.env.production');
+
+        const proc = Bun.spawn(['bun', 'run', '--env-file=.env.production', mainFile], {
+            cwd: projectRoot,
+            stdout: 'inherit',
+            stderr: 'inherit',
+            stdin: 'inherit',
+            env: {
+                ...process.env,
+                ...env,
+                NODE_ENV: 'production',
+                APP_PORT: port.toString(),
+                APP_HOST: host,
+                CLUSTER_MODE: '1',
+                CLUSTER_WORKER_ID: id.toString(),
+                CLUSTER_INSTANCES: this.getInstanceCount().toString(),
+                FORCE_COLOR: '1'
+            }
+        });
+
+        // 保存 Worker 信息
+        this.workers.set(id, {
+            id,
+            port,
+            process: proc,
+            restartCount: 0,
+            lastRestartTime: 0
+        });
+
+        // 监听进程退出
+        this.watchWorker(id, port);
+    }
+
+    /**
+     * 监听 Worker 退出并自动重启
+     */
+    private async watchWorker(id: number, port: number): Promise<void> {
+        const worker = this.workers.get(id);
+        if (!worker) return;
+
+        const exitCode = await worker.process.exited;
+
+        // 如果正在关闭，不重启
+        if (this.isShuttingDown) {
+            Logger.info(`Worker ${id} (端口 ${port}) 已退出`);
+            return;
+        }
+
+        Logger.warn(`Worker ${id} (端口 ${port}) 异常退出，退出码: ${exitCode}`);
+
+        // 检查重启次数
+        if (!this.canRestart(worker)) {
+            Logger.error(`Worker ${id} 重启次数过多，停止重启`);
+            return;
+        }
+
+        // 延迟重启
+        Logger.info(`${this.RESTART_DELAY / 1000} 秒后重启 Worker ${id}...`);
+        await Bun.sleep(this.RESTART_DELAY);
+
+        // 更新重启计数
+        this.updateRestartCount(worker);
+
+        // 重新启动
+        this.spawnWorker(id, port);
+    }
+
+    /**
+     * 检查是否可以重启
+     */
+    private canRestart(worker: WorkerInfo): boolean {
+        const now = Date.now();
+        const timeSinceLastRestart = now - worker.lastRestartTime;
+
+        // 如果距离上次重启超过窗口期，重置计数
+        if (timeSinceLastRestart > this.RESTART_WINDOW) {
+            worker.restartCount = 0;
+        }
+
+        return worker.restartCount < this.MAX_RESTARTS;
+    }
+
+    /**
+     * 更新重启计数
+     */
+    private updateRestartCount(worker: WorkerInfo): void {
+        worker.restartCount++;
+        worker.lastRestartTime = Date.now();
+    }
+
+    /**
+     * 设置信号处理器
+     */
+    private setupSignalHandlers(): void {
+        const signals: NodeJS.Signals[] = ['SIGTERM', 'SIGINT', 'SIGHUP'];
+
+        signals.forEach((signal) => {
+            process.on(signal, () => {
+                this.gracefulShutdown(signal);
+            });
+        });
+    }
+
+    /**
+     * 优雅关闭
+     */
+    private async gracefulShutdown(signal: NodeJS.Signals): Promise<void> {
+        if (this.isShuttingDown) return;
+        this.isShuttingDown = true;
+
+        Logger.info(`\n收到 ${signal} 信号，正在关闭集群...`);
+
+        // 向所有 Worker 发送 SIGTERM
+        for (const [id, worker] of this.workers.entries()) {
+            Logger.info(`关闭 Worker ${id} (端口 ${worker.port})...`);
+            worker.process.kill('SIGTERM');
+        }
+
+        // 等待所有进程退出，最多 5 秒
+        const timeout = setTimeout(() => {
+            Logger.warn('等待超时，强制关闭所有 Worker');
+            for (const worker of this.workers.values()) {
+                worker.process.kill('SIGKILL');
+            }
+            process.exit(1);
+        }, 5000);
+
+        // 等待所有进程退出
+        await Promise.all(Array.from(this.workers.values()).map((w) => w.process.exited));
+
+        clearTimeout(timeout);
+        Logger.info('集群已安全关闭');
+        process.exit(0);
+    }
+
+    /**
+     * 打印 Worker 状态
+     */
+    private printWorkerStatus(): void {
+        Logger.info('Worker 列表:');
+        for (const worker of this.workers.values()) {
+            Logger.info(`  - Worker ${worker.id}: http://${this.options.host}:${worker.port}`);
+        }
+        Logger.info('');
+    }
+}

package/lifecycle/lifecycle.ts

@@ -0,0 +1,139 @@
+/**
+ * 生命周期管理器
+ * 统一管理框架的启动流程：检查、加载插件、加载API、启动服务器
+ */
+
+import { Logger } from '../lib/logger.js';
+import { calcPerfTime } from '../util.js';
+import { scanAddons, addonDirExists } from '../util.js';
+import { Checker } from './checker.js';
+import { Loader } from './loader.js';
+import { Bootstrap } from './bootstrap.js';
+
+import type { Server } from 'bun';
+import type { Plugin } from '../types/plugin.js';
+import type { ApiRoute } from '../types/api.js';
+import type { BeflyContext, BeflyOptions } from '../types/befly.js';
+
+/**
+ * 生命周期管理类
+ */
+export class Lifecycle {
+    /** API 路由映射表 */
+    private apiRoutes: Map<string, ApiRoute> = new Map();
+
+    /** 插件列表 */
+    private pluginLists: Plugin[] = [];
+
+    /** 应用配置选项 */
+    private options: BeflyOptions;
+
+    constructor(options: BeflyOptions = {}) {
+        this.options = options;
+    }
+
+    /**
+     * 启动完整的生命周期流程
+     * @param appContext - 应用上下文
+     * @param callback - 启动完成后的回调函数
+     */
+    async start(appContext: BeflyContext, callback?: (server: Server) => void): Promise<void> {
+        const serverStartTime = Bun.nanoseconds();
+        Logger.info('开始启动 Befly 服务器...');
+
+        // 1. 执行系统检查
+        await Checker.run();
+
+        // 2. 加载插件
+        await Loader.loadPlugins({ pluginLists: this.pluginLists, appContext });
+
+        // 3. 加载所有 API（addon + app）
+        await this.loadAllApis();
+
+        // 4. 缓存数据到 Redis（接口、菜单、角色权限）
+        if (appContext.cache && appContext.redis) {
+            await appContext.cache.cacheAll();
+        } else {
+            Logger.warn('⚠️ Redis 或 Cache 插件未启用，跳过数据缓存');
+        }
+
+        // 5. 启动 HTTP 服务器
+        const totalStartupTime = calcPerfTime(serverStartTime);
+        Logger.info(`服务器启动准备完成，总耗时: ${totalStartupTime}`);
+
+        await Bootstrap.start(
+            {
+                apiRoutes: this.apiRoutes,
+                pluginLists: this.pluginLists,
+                appContext,
+                appOptions: this.options
+            },
+            callback
+        );
+    }
+
+    /**
+     * 加载所有 API 路由
+     * 包括 core APIs、addon APIs 和 app APIs
+     */
+    private async loadAllApis(): Promise<void> {
+        Logger.info('========== 开始加载所有 API 路由 ==========');
+        const totalLoadStart = Bun.nanoseconds();
+
+        // 1. 加载 Core APIs
+        Logger.info('========== 开始加载核心 APIs ==========');
+        const coreApiLoadStart = Bun.nanoseconds();
+        try {
+            await Loader.loadApis('core', this.apiRoutes, { where: 'core' });
+            const coreApiLoadTime = calcPerfTime(coreApiLoadStart);
+            Logger.info(`========== 核心 APIs 加载完成，耗时: ${coreApiLoadTime} ==========`);
+        } catch (error: any) {
+            const coreApiLoadTime = calcPerfTime(coreApiLoadStart);
+            Logger.error(`核心 APIs 加载失败，耗时: ${coreApiLoadTime}`, error);
+            throw error;
+        }
+
+        // 2. 加载 addon APIs
+        const addons = scanAddons();
+        Logger.info(`扫描到 ${addons.length} 个 addon: ${addons.join(', ')}`);
+
+        for (const addon of addons) {
+            const addonLoadStart = Bun.nanoseconds();
+            const hasApis = addonDirExists(addon, 'apis');
+            Logger.info(`[组件 ${addon}] APIs 目录存在: ${hasApis}`);
+
+            if (hasApis) {
+                Logger.info(`[组件 ${addon}] ===== 开始加载 APIs =====`);
+                try {
+                    await Loader.loadApis(addon, this.apiRoutes, { where: 'addon', addonName: addon });
+                    const addonLoadTime = calcPerfTime(addonLoadStart);
+                    Logger.info(`[组件 ${addon}] ===== APIs 加载完成，耗时: ${addonLoadTime} =====`);
+                } catch (error: any) {
+                    const addonLoadTime = calcPerfTime(addonLoadStart);
+                    Logger.error(`[组件 ${addon}] APIs 加载失败，耗时: ${addonLoadTime}`, error);
+                    throw error; // 重新抛出错误，让上层处理
+                }
+            }
+        }
+
+        Logger.info('========== 组件 APIs 全部加载完成 ==========');
+
+        // 3. 加载用户 APIs
+        Logger.info('========== 开始加载用户 APIs ==========');
+
+        const userApiLoadStart = Bun.nanoseconds();
+        try {
+            // 加载 app APIs
+            await Loader.loadApis('app', this.apiRoutes, { where: 'app' });
+            const userApiLoadTime = calcPerfTime(userApiLoadStart);
+            Logger.info(`========== 用户 APIs 加载完成，耗时: ${userApiLoadTime} ==========`);
+        } catch (error: any) {
+            const userApiLoadTime = calcPerfTime(userApiLoadStart);
+            Logger.error(`用户 APIs 加载失败，耗时: ${userApiLoadTime}`, error);
+            throw error;
+        }
+
+        const totalLoadTime = calcPerfTime(totalLoadStart);
+        Logger.info(`========== 所有 API 路由加载完成！总耗时: ${totalLoadTime} ==========`);
+    }
+}