befly 3.8.2 → 3.8.4

package/loader/loadApis.ts

@@ -0,0 +1,172 @@
+/**
+ * API 加载器
+ * 负责扫描和加载所有 API 路由（组件、用户）
+ */
+
+import { relative, basename, join } from 'pathe';
+import { existsSync } from 'node:fs';
+import { isPlainObject } from 'es-toolkit/compat';
+import { Logger } from '../lib/logger.js';
+import { calcPerfTime } from '../util.js';
+import { projectApiDir } from '../paths.js';
+import { scanAddons, getAddonDir, addonDirExists } from '../util.js';
+import type { ApiRoute } from '../types/api.js';
+
+/**
+ * API 默认字段定义
+ * 这些字段会自动合并到所有 API 的 fields 中
+ * API 自定义的同名字段可以覆盖这些默认值
+ */
+const DEFAULT_API_FIELDS = {
+    id: {
+        name: 'ID',
+        type: 'number',
+        min: 1,
+        max: null
+    },
+    page: {
+        name: '页码',
+        type: 'number',
+        min: 1,
+        max: 9999
+    },
+    limit: {
+        name: '每页数量',
+        type: 'number',
+        min: 1,
+        max: 100
+    },
+    keyword: {
+        name: '关键词',
+        type: 'string',
+        min: 1,
+        max: 50
+    },
+    state: {
+        name: '状态',
+        type: 'number',
+        min: 0,
+        max: 2
+    }
+} as const;
+
+/**
+ * 扫描用户 API 文件
+ */
+async function scanUserApis(): Promise<Array<{ file: string; routePrefix: string; displayName: string }>> {
+    const apis: Array<{ file: string; routePrefix: string; displayName: string }> = [];
+
+    if (!existsSync(projectApiDir)) {
+        return apis;
+    }
+
+    const glob = new Bun.Glob('**/*.ts');
+
+    for await (const file of glob.scan({
+        cwd: projectApiDir,
+        onlyFiles: true,
+        absolute: true
+    })) {
+        const apiPath = relative(projectApiDir, file).replace(/\.ts$/, '');
+        if (apiPath.indexOf('_') !== -1) continue;
+
+        apis.push({
+            file: file,
+            routePrefix: '',
+            displayName: '用户'
+        });
+    }
+
+    return apis;
+}
+
+/**
+ * 扫描组件 API 文件
+ */
+async function scanAddonApis(): Promise<Array<{ file: string; routePrefix: string; displayName: string }>> {
+    const apis: Array<{ file: string; routePrefix: string; displayName: string }> = [];
+    const glob = new Bun.Glob('**/*.ts');
+    const addons = scanAddons();
+
+    for (const addon of addons) {
+        if (!addonDirExists(addon, 'apis')) continue;
+
+        const addonApiDir = getAddonDir(addon, 'apis');
+        for await (const file of glob.scan({
+            cwd: addonApiDir,
+            onlyFiles: true,
+            absolute: true
+        })) {
+            const apiPath = relative(addonApiDir, file).replace(/\.ts$/, '');
+            if (apiPath.indexOf('_') !== -1) continue;
+
+            apis.push({
+                file: file,
+                routePrefix: `addon/${addon}`,
+                displayName: `组件${addon}`
+            });
+        }
+    }
+
+    return apis;
+}
+
+/**
+ * 初始化单个 API
+ */
+async function initApi(apiRoutes: Map<string, ApiRoute>, apiInfo: { file: string; routePrefix: string; displayName: string }): Promise<void> {
+    const { file, routePrefix, displayName } = apiInfo;
+    const apiDir = routePrefix === '' ? projectApiDir : getAddonDir(routePrefix.replace('addon/', ''), 'apis');
+    const apiPath = relative(apiDir, file).replace(/\.ts$/, '');
+
+    try {
+        // Windows 下路径需要转换为正斜杠格式
+        const filePath = file.replace(/\\/g, '/');
+        const apiImport = await import(filePath);
+        const api = apiImport.default;
+
+        // 设置默认值
+        api.method = api.method || 'POST';
+        api.auth = api.auth !== undefined ? api.auth : true;
+        // 合并默认字段：先设置自定义字段，再用默认字段覆盖（默认字段优先级更高）
+        api.fields = { ...(api.fields || {}), ...DEFAULT_API_FIELDS };
+        api.required = api.required || [];
+
+        // 构建路由
+        api.route = `${api.method.toUpperCase()}/api/${routePrefix ? routePrefix + '/' : ''}${apiPath}`;
+        apiRoutes.set(api.route, api);
+    } catch (error: any) {
+        Logger.error(`[${displayName}] 接口 ${apiPath} 加载失败`, error);
+        process.exit(1);
+    }
+}
+
+/**
+ * 加载所有 API 路由
+ * @param apiRoutes - API 路由映射表
+ */
+export async function loadApis(apiRoutes: Map<string, ApiRoute>): Promise<void> {
+    try {
+        const loadStartTime = Bun.nanoseconds();
+
+        // 阶段1：扫描所有 API
+        const userApis = await scanUserApis();
+        const addonApis = await scanAddonApis();
+
+        // 阶段2：初始化所有 API（用户 → 组件）
+        // 2.1 初始化用户 APIs
+        for (const apiInfo of userApis) {
+            await initApi(apiRoutes, apiInfo);
+        }
+
+        // 2.2 初始化组件 APIs
+        for (const apiInfo of addonApis) {
+            await initApi(apiRoutes, apiInfo);
+        }
+
+        const totalLoadTime = calcPerfTime(loadStartTime);
+    } catch (error: any) {
+        Logger.error('加载 API 时发生错误', error);
+        process.exit(1);
+    }
+}

package/{lifecycle → loader}/loadPlugins.ts

@@ -9,7 +9,7 @@ import { camelCase } from 'es-toolkit/string';
 import { Logger } from '../lib/logger.js';
 import { calcPerfTime } from '../util.js';
 import { corePluginDir, projectPluginDir } from '../paths.js';
-import { Addon } from '../lib/addon.js';
+import { scanAddons, getAddonDir, addonDirExists } from '../util.js';
 import type { Plugin } from '../types/plugin.js';
 import type { BeflyContext } from '../types/befly.js';
 
@@ -80,12 +80,12 @@ async function scanCorePlugins(loadedPluginNames: Set<string>): Promise<Plugin[]
 async function scanAddonPlugins(loadedPluginNames: Set<string>): Promise<Plugin[]> {
     const plugins: Plugin[] = [];
     const glob = new Bun.Glob('*.ts');
-    const addons = Addon.scan();
+    const addons = scanAddons();
 
     for (const addon of addons) {
-        if (!Addon.dirExists(addon, 'plugins')) continue;
+        if (!addonDirExists(addon, 'plugins')) continue;
 
-        const addonPluginsDir = Addon.getDir(addon, 'plugins');
+        const addonPluginsDir = getAddonDir(addon, 'plugins');
         for await (const file of glob.scan({
             cwd: addonPluginsDir,
             onlyFiles: true,
@@ -103,9 +103,9 @@ async function scanAddonPlugins(loadedPluginNames: Set<string>): Promise<Plugin[
             }
 
             try {
-                const plugin = require(file);
-                const pluginInstance = plugin.default;
-                pluginInstance.pluginName = pluginFullName;
+                const pluginImport = await import(file);
+                const plugin = pluginImport.default;
+                plugin.pluginName = pluginFullName;
                 plugins.push(pluginInstance);
                 loadedPluginNames.add(pluginFullName);
             } catch (err: any) {
@@ -145,9 +145,9 @@ async function scanUserPlugins(loadedPluginNames: Set<string>): Promise<Plugin[]
         }
 
         try {
-            const plugin = require(file);
-            const pluginInstance = plugin.default;
-            pluginInstance.pluginName = pluginFullName;
+            const pluginImport = await import(file);
+            const plugin = pluginImport.default;
+            plugin.pluginName = pluginFullName;
             plugins.push(pluginInstance);
             loadedPluginNames.add(pluginFullName);
         } catch (err: any) {

package/main.ts

@@ -1,44 +1,136 @@
 /**
  * Befly 框架主入口文件
- * 提供简洁的框架接口，核心逻辑已提取到 lifecycle 层
+ * 提供简洁的框架接口，核心逻辑已提取到 loader 层
  */
 
 import { Env } from './env.js';
-import { Yes, No, keysToSnake, keysToCamel, arrayKeysToCamel, pickFields, fieldClear, calcPerfTime } from './util.js';
+
 import { Logger } from './lib/logger.js';
 import { Cipher } from './lib/cipher.js';
 import { Jwt } from './lib/jwt.js';
 import { Database } from './lib/database.js';
-import { Lifecycle } from './lifecycle/lifecycle.js';
+import { loadPlugins } from './loader/loadPlugins.js';
+import { loadApis } from './loader/loadApis.js';
+import { rootHandler } from './router/root.js';
+import { apiHandler } from './router/api.js';
+import { staticHandler } from './router/static.js';
 import { coreDir } from './paths.js';
 import { DbHelper } from './lib/dbHelper.js';
 import { RedisHelper } from './lib/redisHelper.js';
-import { Addon } from './lib/addon.js';
-import { checkDefault } from './check.js';
+import { checkTable, checkApi, checkApp } from './check.js';
+import {
+    //
+    Yes,
+    No,
+    keysToSnake,
+    keysToCamel,
+    arrayKeysToCamel,
+    pickFields,
+    fieldClear,
+    calcPerfTime,
+    scanAddons,
+    getAddonDir,
+    addonDirExists
+} from './util.js';
 
 import type { Server } from 'bun';
 import type { BeflyContext } from './types/befly.js';
+import type { Plugin } from './types/plugin.js';
+import type { ApiRoute } from './types/api.js';
 /**
  * Befly 框架核心类
  * 职责：管理应用上下文和生命周期
  */
 export class Befly {
-    /** 生命周期管理器 */
-    private lifecycle: Lifecycle;
+    /** API 路由映射表 */
+    private apiRoutes: Map<string, ApiRoute> = new Map();
+
+    /** 插件列表 */
+    private pluginLists: Plugin[] = [];
 
     /** 应用上下文 */
     public appContext: BeflyContext;
 
     constructor() {
-        this.lifecycle = new Lifecycle();
         this.appContext = {};
     }
 
+    /**
+     * 启动完整的生命周期流程
+     * @returns HTTP 服务器实例
+     */
+    private async start(): Promise<Server> {
+        const serverStartTime = Bun.nanoseconds();
+
+        // 1. 加载所有 API（动态导入必须在最前面，避免 Bun 1.3.2 的崩溃 bug）
+        await loadApis(this.apiRoutes);
+
+        // 2. 执行项目结构检查
+        const appCheckResult = await checkApp();
+        if (!appCheckResult) {
+            Logger.error('项目结构检查失败，程序退出');
+            process.exit(1);
+        }
+
+        // 3. 执行表定义检查
+        const tableCheckResult = await checkTable();
+        if (!tableCheckResult) {
+            Logger.error('表定义检查失败，程序退出');
+            process.exit(1);
+        }
+
+        // 4. 执行 API 定义检查
+        const apiCheckResult = await checkApi();
+        if (!apiCheckResult) {
+            Logger.error('API 定义检查失败，程序退出');
+            process.exit(1);
+        }
+
+        // 5. 加载插件
+        await loadPlugins({
+            pluginLists: this.pluginLists,
+            appContext: this.appContext
+        });
+
+        // 4. 启动 HTTP 服务器
+        const totalStartupTime = calcPerfTime(serverStartTime);
+
+        return await this.startServer();
+    }
+
+    /**
+     * 启动 HTTP 服务器
+     * @returns HTTP 服务器实例
+     */
+    private async startServer(): Promise<Server> {
+        const startTime = Bun.nanoseconds();
+
+        const server = Bun.serve({
+            port: Env.APP_PORT,
+            hostname: Env.APP_HOST,
+            routes: {
+                '/': rootHandler,
+                '/api/*': apiHandler(this.apiRoutes, this.pluginLists, this.appContext),
+                '/*': staticHandler
+            },
+            error: (error: Error) => {
+                Logger.error('服务启动时发生错误', error);
+                return Response.json({ code: 1, msg: '内部服务器错误' });
+            }
+        });
+
+        const finalStartupTime = calcPerfTime(startTime);
+        Logger.info(`${Env.APP_NAME} 服务器启动成功! 服务器启动耗时: ${finalStartupTime}`);
+        Logger.info(`服务器监听地址: http://${Env.APP_HOST}:${Env.APP_PORT}`);
+
+        return server;
+    }
+
     /**
      * 启动服务器并注册优雅关闭处理
      */
     async listen(): Promise<Server> {
-        const server = await this.lifecycle.start(this.appContext);
+        const server = await this.start();
 
         const gracefulShutdown = async (signal: string) => {
             // 1. 停止接收新请求
@@ -76,9 +168,10 @@ export {
     Database,
     DbHelper,
     RedisHelper,
-    Addon,
     coreDir,
-    checkDefault
+    checkTable,
+    checkApi,
+    checkApp
 };
 
 // 工具函数命名空间导出
@@ -88,5 +181,8 @@ export const utils = {
     arrayKeysToCamel: arrayKeysToCamel,
     pickFields: pickFields,
     fieldClear: fieldClear,
-    calcPerfTime: calcPerfTime
+    calcPerfTime: calcPerfTime,
+    scanAddons: scanAddons,
+    getAddonDir: getAddonDir,
+    addonDirExists: addonDirExists
 };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "befly",
-    "version": "3.8.2",
+    "version": "3.8.4",
     "description": "Befly - 为 Bun 专属打造的 TypeScript API 接口框架核心引擎",
     "type": "module",
     "private": false,
@@ -39,8 +39,8 @@
     "license": "Apache-2.0",
     "files": [
         "lib/",
-        "lifecycle/",
-        "plugins/",
+        "loader/",
+        "middleware/",
         "router/",
         "types/",
         ".gitignore",
@@ -69,5 +69,5 @@
         "es-toolkit": "^1.41.0",
         "pathe": "^2.0.3"
     },
-    "gitHead": "c0844203f8fee734d2a8742f3b77b67bf0874681"
+    "gitHead": "40b4c3e6591454ff060416a6275142792e7de66c"
 }

package/paths.ts

@@ -89,3 +89,10 @@ export const projectApiDir = join(projectDir, 'apis');
  * @usage 存放用户业务表定义（JSON 格式）
  */
 export const projectTableDir = join(projectDir, 'tables');
+
+/**
+ * 项目组件目录
+ * @description {projectDir}/addons/
+ * @usage 存放本地组件（优先级高于 node_modules 中的组件）
+ */
+export const projectAddonsDir = join(projectDir, 'addons');

package/util.ts

@@ -5,7 +5,7 @@ import { isEmpty, isPlainObject } from 'es-toolkit/compat';
 import { snakeCase, camelCase, kebabCase } from 'es-toolkit/string';
 import { Env } from './env.js';
 import { Logger } from './lib/logger.js';
-import { projectDir } from './paths.js';
+import { projectDir, projectAddonsDir } from './paths.js';
 import type { KeyValue } from './types/common.js';
 import type { JwtPayload, JwtSignOptions, JwtVerifyOptions } from './types/jwt';
 import type { Plugin } from './types/plugin.js';
@@ -171,3 +171,87 @@ export const calcPerfTime = (startTime: number, endTime: number = Bun.nanosecond
         return `${elapsedSeconds.toFixed(2)} 秒`;
     }
 };
+
+// ========================================
+// Addon 工具函数
+// ========================================
+
+/**
+ * 扫描所有可用的 addon
+ * 优先从本地 addons/ 目录加载，其次从 node_modules/@befly-addon/ 加载
+ * @returns addon 名称数组
+ */
+export const scanAddons = (): string[] => {
+    const addons = new Set<string>();
+
+    // 1. 扫描本地 addons 目录（优先级高）
+    // if (existsSync(projectAddonsDir)) {
+    //     try {
+    //         const localAddons = fs.readdirSync(projectAddonsDir).filter((name) => {
+    //             const fullPath = join(projectAddonsDir, name);
+    //             try {
+    //                 const stat = statSync(fullPath);
+    //                 return stat.isDirectory() && !name.startsWith('_');
+    //             } catch {
+    //                 return false;
+    //             }
+    //         });
+    //         localAddons.forEach((name) => addons.add(name));
+    //     } catch (err) {
+    //         // 忽略本地目录读取错误
+    //     }
+    // }
+
+    // 2. 扫描 node_modules/@befly-addon 目录
+    const beflyDir = join(projectDir, 'node_modules', '@befly-addon');
+    if (existsSync(beflyDir)) {
+        try {
+            const npmAddons = fs.readdirSync(beflyDir).filter((name) => {
+                // 如果本地已存在，跳过 npm 包版本
+                if (addons.has(name)) return false;
+
+                const fullPath = join(beflyDir, name);
+                try {
+                    const stat = statSync(fullPath);
+                    return stat.isDirectory();
+                } catch {
+                    return false;
+                }
+            });
+            npmAddons.forEach((name) => addons.add(name));
+        } catch {
+            // 忽略 npm 目录读取错误
+        }
+    }
+
+    return Array.from(addons).sort();
+};
+
+/**
+ * 获取 addon 的指定子目录路径
+ * 优先返回本地 addons 目录，其次返回 node_modules 目录
+ * @param name - addon 名称
+ * @param subDir - 子目录名称
+ * @returns 完整路径
+ */
+export const getAddonDir = (name: string, subDir: string): string => {
+    // 优先使用本地 addons 目录
+    // const localPath = join(projectAddonsDir, name, subDir);
+    // if (existsSync(localPath)) {
+    //     return localPath;
+    // }
+
+    // 降级使用 node_modules 目录
+    return join(projectDir, 'node_modules', '@befly-addon', name, subDir);
+};
+
+/**
+ * 检查 addon 子目录是否存在
+ * @param name - addon 名称
+ * @param subDir - 子目录名称
+ * @returns 是否存在
+ */
+export const addonDirExists = (name: string, subDir: string): boolean => {
+    const dir = getAddonDir(name, subDir);
+    return existsSync(dir) && statSync(dir).isDirectory();
+};

package/lib/addon.ts

@@ -1,77 +0,0 @@
-/**
- * Addon 管理工具类
- * 提供 addon 的扫描、路径获取等功能
- */
-
-import fs from 'node:fs';
-import { join } from 'pathe';
-import { existsSync, statSync, readdirSync } from 'node:fs';
-import { projectDir } from '../paths.js';
-
-/**
- * Addon 管理类
- */
-export class Addon {
-    /**
-     * 扫描所有可用的 addon
-     * @returns addon 名称数组
-     */
-    static scan(): string[] {
-        const beflyDir = join(projectDir, 'node_modules', '@befly-addon');
-
-        if (!existsSync(beflyDir)) {
-            return [];
-        }
-
-        try {
-            return fs
-                .readdirSync(beflyDir)
-                .filter((name) => {
-                    // addon 名称格式：admin, demo 等（不带 addon- 前缀）
-                    const fullPath = join(beflyDir, name);
-                    try {
-                        const stat = statSync(fullPath);
-                        return stat.isDirectory();
-                    } catch {
-                        return false;
-                    }
-                })
-                .sort();
-        } catch {
-            return [];
-        }
-    }
-
-    /**
-     * 获取 addon 的指定子目录路径
-     * @param name - addon 名称
-     * @param subDir - 子目录名称
-     * @returns 完整路径
-     */
-    static getDir(name: string, subDir: string): string {
-        return join(projectDir, 'node_modules', '@befly-addon', name, subDir);
-    }
-
-    /**
-     * 检查 addon 子目录是否存在
-     * @param name - addon 名称
-     * @param subDir - 子目录名称
-     * @returns 是否存在
-     */
-    static dirExists(name: string, subDir: string): boolean {
-        const dir = this.getDir(name, subDir);
-        return existsSync(dir) && statSync(dir).isDirectory();
-    }
-
-    /**
-     * 获取插件目录列表
-     * @param addonsDir - addons 根目录路径
-     * @returns 插件名称数组
-     */
-    static getDirs(addonsDir: string): string[] {
-        return readdirSync(addonsDir).filter((name) => {
-            const addonPath = join(addonsDir, name);
-            return statSync(addonPath).isDirectory() && !name.startsWith('_');
-        });
-    }
-}

package/lifecycle/bootstrap.ts

@@ -1,49 +0,0 @@
-/**
- * 服务启动引导器
- * 负责组装和启动Bun HTTP服务器
- */
-
-import { Logger } from '../lib/logger.js';
-import { calcPerfTime } from '../util.js';
-import { Env } from '../env.js';
-import { rootHandler } from '../router/root.js';
-import { apiHandler } from '../router/api.js';
-import { staticHandler } from '../router/static.js';
-
-import type { Server } from 'bun';
-import type { BeflyContext } from '../types/befly.js';
-import type { ApiRoute } from '../types/api.js';
-import type { Plugin } from '../types/plugin.js';
-
-/**
- * 引导器类
- */
-export class Bootstrap {
-    /**
-     * 启动HTTP服务器
-     * @param befly - Befly实例（需要访问 apiRoutes, pluginLists, appContext）
-     */
-    static async start(befly: { apiRoutes: Map<string, ApiRoute>; pluginLists: Plugin[]; appContext: BeflyContext }): Promise<Server> {
-        const startTime = Bun.nanoseconds();
-
-        const server = Bun.serve({
-            port: Env.APP_PORT,
-            hostname: Env.APP_HOST,
-            routes: {
-                '/': rootHandler,
-                '/api/*': apiHandler(befly.apiRoutes, befly.pluginLists, befly.appContext),
-                '/*': staticHandler
-            },
-            error: (error: Error) => {
-                Logger.error('服务启动时发生错误', error);
-                return Response.json({ code: 1, msg: '内部服务器错误' });
-            }
-        });
-
-        const finalStartupTime = calcPerfTime(startTime);
-        Logger.info(`${Env.APP_NAME} 服务器启动成功! 服务器启动耗时: ${finalStartupTime}`);
-        Logger.info(`服务器监听地址: http://${Env.APP_HOST}:${Env.APP_PORT}`);
-
-        return server;
-    }
-}