befly 3.8.19 → 3.8.20

package/sync/syncMenu.ts

@@ -0,0 +1,331 @@
+/**
+ * SyncMenu 命令 - 同步菜单数据到数据库
+ * 说明：根据 menu.json 配置文件增量同步菜单数据（最多3级：父级、子级、孙级）
+ *
+ * 流程：
+ * 1. 扫描项目根目录和所有 addon 的 menu.json 配置文件
+ * 2. 项目的 menu.json 优先级最高，可以覆盖 addon 的菜单配置
+ * 3. 文件不存在或格式错误时默认为空数组
+ * 4. 根据菜单的 path 字段检查是否存在
+ * 5. 存在则更新其他字段（name、sort、type、pid）
+ * 6. 不存在则新增菜单记录
+ * 7. 强制删除配置中不存在的菜单记录
+ * 注：state 字段由框架自动管理（1=正常，2=禁用，0=删除）
+ */
+
+import { join } from 'pathe';
+import { existsSync } from 'node:fs';
+import { Database } from '../lib/database.js';
+import { RedisHelper } from '../lib/redisHelper.js';
+import { scanAddons, getAddonDir } from 'befly-util';
+import { Logger } from '../lib/logger.js';
+import { projectDir } from '../paths.js';
+
+import type { SyncMenuOptions, MenuConfig, BeflyOptions } from '../types/index.js';
+
+/**
+ * 读取菜单配置文件
+ * 如果文件不存在或不是数组格式，返回空数组
+ */
+async function readMenuConfig(filePath: string): Promise<MenuConfig[]> {
+    try {
+        if (!existsSync(filePath)) {
+            return [];
+        }
+
+        const content = await import(filePath, { with: { type: 'json' } });
+
+        // 验证是否为数组
+        if (!Array.isArray(content.default)) {
+            return [];
+        }
+
+        return content.default;
+    } catch (error: any) {
+        Logger.warn(`读取菜单配置失败 ${filePath}: ${error.message}`);
+        return [];
+    }
+}
+
+/**
+ * 为 addon 菜单的 path 添加前缀
+ * 规则：
+ * 1. 所有路径必须以 / 开头
+ * 2. 所有路径都添加 /addon/{addonName} 前缀（包括根路径 /）
+ * 3. 递归处理所有层级的子菜单
+ * 4. 项目菜单不添加前缀
+ */
+function addAddonPrefix(menus: MenuConfig[], addonName: string): MenuConfig[] {
+    return menus.map((menu) => {
+        const newMenu = { ...menu };
+
+        // 处理当前菜单的 path（包括根路径 /）
+        if (newMenu.path && newMenu.path.startsWith('/')) {
+            newMenu.path = `/addon/${addonName}${newMenu.path}`;
+        }
+
+        // 递归处理子菜单
+        if (newMenu.children && newMenu.children.length > 0) {
+            newMenu.children = addAddonPrefix(newMenu.children, addonName);
+        }
+
+        return newMenu;
+    });
+}
+
+/**
+ * 合并菜单配置
+ * 优先级：项目 menu.json > addon menu.json
+ * 支持三级菜单结构：父级、子级、孙级
+ */
+function mergeMenuConfigs(allMenus: Array<{ menus: MenuConfig[]; addonName: string }>): MenuConfig[] {
+    /**
+     * 递归合并指定层级的菜单（限制最多3层）
+     * @param menus 待合并的菜单数组
+     * @param depth 当前深度（1=父级, 2=子级, 3=孙级）
+     * @returns 合并后的菜单数组
+     */
+    function mergeLevel(menus: MenuConfig[], depth: number = 1): MenuConfig[] {
+        const menuMap = new Map<string, MenuConfig>();
+
+        for (const menu of menus) {
+            if (!menu.path) continue;
+
+            const existing = menuMap.get(menu.path);
+            if (existing) {
+                // 合并子菜单
+                if (menu.children?.length > 0) {
+                    existing.children = existing.children || [];
+                    existing.children.push(...menu.children);
+                }
+            } else {
+                menuMap.set(menu.path, { ...menu });
+            }
+        }
+
+        // 递归处理子菜单（限制最多3层）
+        if (depth < 3) {
+            for (const menu of menuMap.values()) {
+                if (menu.children?.length > 0) {
+                    menu.children = mergeLevel(menu.children, depth + 1);
+                }
+            }
+        }
+
+        return Array.from(menuMap.values());
+    }
+
+    // 收集所有菜单（扁平化）
+    const allFlatMenus = allMenus.flatMap(({ menus }) => menus);
+
+    return mergeLevel(allFlatMenus, 1);
+}
+
+/**
+ * 收集配置文件中所有菜单的 path（最多3级）
+ * 子级菜单使用独立路径
+ */
+function collectPaths(menus: MenuConfig[]): Set<string> {
+    const paths = new Set<string>();
+
+    for (const menu of menus) {
+        if (menu.path) {
+            paths.add(menu.path);
+        }
+        if (menu.children && menu.children.length > 0) {
+            for (const child of menu.children) {
+                if (child.path) {
+                    paths.add(child.path);
+                }
+                // 第三层菜单
+                if (child.children && child.children.length > 0) {
+                    for (const grandChild of child.children) {
+                        if (grandChild.path) {
+                            paths.add(grandChild.path);
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    return paths;
+}
+
+/**
+ * 递归同步单个菜单（限制最多3层）
+ * @param helper 数据库帮助类
+ * @param menu 菜单配置
+ * @param pid 父级菜单ID
+ * @param existingMenuMap 现有菜单映射
+ * @param depth 当前深度（1=父级, 2=子级, 3=孙级）
+ * @returns 菜单ID
+ */
+async function syncMenuRecursive(helper: any, menu: MenuConfig, pid: number, existingMenuMap: Map<string, any>, depth: number = 1): Promise<number> {
+    const existing = existingMenuMap.get(menu.path || '');
+    let menuId: number;
+
+    if (existing) {
+        menuId = existing.id;
+
+        // 检查是否需要更新
+        const needUpdate = existing.pid !== pid || existing.name !== menu.name || existing.sort !== (menu.sort || 0);
+
+        if (needUpdate) {
+            await helper.updData({
+                table: 'addon_admin_menu',
+                where: { id: existing.id },
+                data: {
+                    pid: pid,
+                    name: menu.name,
+                    sort: menu.sort || 0
+                }
+            });
+        }
+    } else {
+        menuId = await helper.insData({
+            table: 'addon_admin_menu',
+            data: {
+                pid: pid,
+                name: menu.name,
+                path: menu.path || '',
+                sort: menu.sort || 0
+            }
+        });
+    }
+
+    // 递归处理子菜单（限制最多3层）
+    if (depth < 3 && menu.children?.length > 0) {
+        for (const child of menu.children) {
+            await syncMenuRecursive(helper, child, menuId, existingMenuMap, depth + 1);
+        }
+    }
+
+    return menuId;
+}
+
+/**
+ * 同步菜单（三层结构：父级、子级、孙级）
+ * 子级菜单使用独立路径
+ */
+async function syncMenus(helper: any, menus: MenuConfig[]): Promise<void> {
+    // 批量查询所有现有菜单，建立 path -> menu 的映射
+    const allExistingMenus = await helper.getAll({
+        table: 'addon_admin_menu',
+        fields: ['id', 'pid', 'name', 'path', 'sort']
+    });
+    const existingMenuMap = new Map<string, any>();
+    for (const menu of allExistingMenus) {
+        if (menu.path) {
+            existingMenuMap.set(menu.path, menu);
+        }
+    }
+
+    for (const menu of menus) {
+        try {
+            await syncMenuRecursive(helper, menu, 0, existingMenuMap, 1);
+        } catch (error: any) {
+            Logger.error(`同步菜单 "${menu.name}" 失败`, error.message || String(error));
+            throw error;
+        }
+    }
+}
+
+/**
+ * 删除配置中不存在的菜单（强制删除）
+ */
+async function deleteObsoleteRecords(helper: any, configPaths: Set<string>): Promise<void> {
+    const allRecords = await helper.getAll({
+        table: 'addon_admin_menu',
+        fields: ['id', 'path'],
+        where: { state$gte: 0 }
+    });
+
+    for (const record of allRecords) {
+        if (record.path && !configPaths.has(record.path)) {
+            await helper.delForce({
+                table: 'addon_admin_menu',
+                where: { id: record.id }
+            });
+        }
+    }
+}
+
+/**
+ * SyncMenu 命令主函数
+ */
+export async function syncMenuCommand(config: BeflyOptions, options: SyncMenuOptions = {}): Promise<void> {
+    try {
+        if (options.plan) {
+            Logger.debug('[计划] 同步菜单配置到数据库（plan 模式不执行）');
+            return;
+        }
+
+        // 1. 扫描所有 addon 的 menu.json 配置文件
+        const allMenus: Array<{ menus: MenuConfig[]; addonName: string }> = [];
+
+        const addonNames = scanAddons();
+
+        for (const addonName of addonNames) {
+            const addonMenuPath = getAddonDir(addonName, 'menu.json');
+            if (existsSync(addonMenuPath)) {
+                const addonMenus = await readMenuConfig(addonMenuPath);
+                if (addonMenus.length > 0) {
+                    // 为 addon 菜单添加路径前缀
+                    const menusWithPrefix = addAddonPrefix(addonMenus, addonName);
+                    allMenus.push({ menus: menusWithPrefix, addonName: addonName });
+                }
+            }
+        }
+
+        // 2. 读取项目根目录的 menu.json（优先级最高，不添加前缀）
+        const projectMenuPath = join(projectDir, 'menu.json');
+        const projectMenus = await readMenuConfig(projectMenuPath);
+        if (projectMenus.length > 0) {
+            allMenus.push({ menus: projectMenus, addonName: 'project' });
+        } // 3. 合并菜单配置（项目配置优先）
+        const mergedMenus = mergeMenuConfigs(allMenus);
+
+        // 连接数据库（SQL + Redis）
+        await Database.connect();
+
+        const helper = Database.getDbHelper();
+
+        // 4. 检查表是否存在（addon_admin_menu 来自 addon-admin 组件）
+        const exists = await helper.tableExists('addon_admin_menu');
+
+        if (!exists) {
+            Logger.debug('表 addon_admin_menu 不存在，跳过菜单同步（需要安装 addon-admin 组件）');
+            return;
+        }
+
+        // 5. 收集配置文件中所有菜单的 path
+        const configPaths = collectPaths(mergedMenus);
+
+        // 6. 同步菜单
+        await syncMenus(helper, mergedMenus);
+
+        // 7. 删除文件中不存在的菜单（强制删除）
+        await deleteObsoleteRecords(helper, configPaths);
+
+        // 8. 获取最终菜单数据（用于缓存）
+        const allMenusData = await helper.getAll({
+            table: 'addon_admin_menu',
+            fields: ['id', 'pid', 'name', 'path', 'sort'],
+            orderBy: ['sort#ASC', 'id#ASC']
+        });
+
+        // 9. 缓存菜单数据到 Redis
+        try {
+            const redisHelper = new RedisHelper();
+            await redisHelper.setObject('menus:all', allMenusData);
+        } catch (error: any) {
+            Logger.warn(`Redis 缓存菜单数据失败: ${error.message}`);
+        }
+    } catch (error: any) {
+        Logger.error('菜单同步失败', error);
+        throw error;
+    } finally {
+        await Database?.disconnect();
+    }
+}

package/tsconfig.json

@@ -33,9 +33,7 @@
         "isolatedModules": true,
 
         // 输出
-        "declaration": true,
-        "declarationMap": true,
-        "sourceMap": true,
+        "noEmit": true,
         "removeComments": false,
         "importHelpers": false,
 
@@ -45,7 +43,7 @@
         "checkJs": false,
 
         // Bun 特定
-        "types": ["bun-types"],
+        "types": ["bun"],
 
         // 路径
         "baseUrl": ".",

package/types/api.d.ts

@@ -84,6 +84,12 @@ export interface ApiRoute<T = any, R = any> {
     /** 必填字段（可选，默认 []） */
     required?: string[];
 
+    /** 缓存配置（可选，单位：秒） */
+    cache?: number;
+
+    /** 限流配置（可选，格式：次数/秒，如 "10/60" 表示 60秒内10次） */
+    rateLimit?: string;
+
     /** 路由路径（运行时生成） */
     route?: string;
 }

package/types/befly.d.ts

@@ -12,46 +12,170 @@ import type { Database } from 'bun:sqlite';
 import type { DbHelper } from '../lib/dbHelper.js';
 import type { RedisHelper } from '../lib/redisHelper.js';
 import type { Cipher } from '../lib/cipher.js';
+import type { CacheHelper } from '../lib/cacheHelper.js';
 
 /**
- * Befly 应用选项
+ * 日志配置
  */
-export interface BeflyOptions {
-    /** 应用名称 */
-    name?: string;
+export interface LoggerConfig {
+    /** 是否开启调试模式 (0: 关闭, 1: 开启) @default 1 */
+    debug?: number;
+    /** 日志排除字段 (逗号分隔) @default 'password,token,secret' */
+    excludeFields?: string;
+    /** 日志目录 @default './logs' */
+    dir?: string;
+    /** 是否输出到控制台 (0: 关闭, 1: 开启) @default 1 */
+    console?: number;
+    /** 单个日志文件最大大小 (字节) @default 10485760 (10MB) */
+    maxSize?: number;
+}
 
-    /** 监听主机 */
+/**
+ * 数据库配置
+ */
+export interface DatabaseConfig {
+    /** 是否启用数据库 (0: 关闭, 1: 开启) @default 0 */
+    enable?: number;
+    /** 数据库类型 ('mysql' | 'postgres' | 'sqlite') @default 'sqlite' */
+    type?: string;
+    /** 数据库主机 @default '127.0.0.1' */
     host?: string;
-
-    /** 监听端口 */
+    /** 数据库端口 @default 3306 */
     port?: number;
+    /** 数据库用户名 @default 'root' */
+    username?: string;
+    /** 数据库密码 @default '' */
+    password?: string;
+    /** 数据库名称 @default 'befly' */
+    database?: string;
+    /** 连接池最大连接数 @default 1 */
+    poolMax?: number;
+}
 
-    /** 是否启用 CORS */
-    cors?: boolean | CorsOptions;
-
-    /** 静态文件目录 */
-    staticDir?: string;
+/**
+ * Redis 配置
+ */
+export interface RedisConfig {
+    /** Redis 主机 @default '127.0.0.1' */
+    host?: string;
+    /** Redis 端口 @default 6379 */
+    port?: number;
+    /** Redis 用户名 @default '' */
+    username?: string;
+    /** Redis 密码 @default '' */
+    password?: string;
+    /** Redis 数据库索引 @default 0 */
+    db?: number;
+    /** Redis Key 前缀 @default 'befly:' */
+    prefix?: string;
+}
 
-    /** 上传文件目录 */
-    uploadDir?: string;
+/**
+ * JWT 配置
+ */
+export interface AuthConfig {
+    /** JWT 密钥 @default 'befly-secret' */
+    secret?: string;
+    /** 过期时间 @default '7d' */
+    expiresIn?: string | number;
+    /** 签名算法 @default 'HS256' */
+    algorithm?: string;
+}
 
-    /** 最大请求体大小 */
-    maxBodySize?: number;
+/**
+ * CORS 配置
+ */
+export interface CorsConfig {
+    /** 允许的来源 @default '*' */
+    origin?: string;
+    /** 允许的方法 @default 'GET,HEAD,PUT,PATCH,POST,DELETE' */
+    methods?: string;
+    /** 允许的头 @default 'Content-Type,Authorization' */
+    allowedHeaders?: string;
+    /** 暴露的头 @default '' */
+    exposedHeaders?: string;
+    /** 预检请求缓存时间 (秒) @default 86400 */
+    maxAge?: number;
+    /** 是否允许凭证 @default 'true' */
+    credentials?: string;
+}
 
-    /** 自定义配置 */
+/**
+ * Befly 构造函数选项（最多 2 级结构）
+ */
+export interface BeflyOptions {
+    // ========== 核心参数 ==========
+    /** 运行环境 ('development' | 'production') @default 'development' */
+    nodeEnv?: string;
+    /** 应用名称 @default 'Befly App' */
+    appName?: string;
+    /** 应用端口 @default 3000 */
+    appPort?: number;
+    /** 应用主机 @default '0.0.0.0' */
+    appHost?: string;
+    /** 开发者邮箱 (用于 syncDev) @default 'dev@qq.com' */
+    devEmail?: string;
+    /** 开发者密码 (用于 syncDev) */
+    devPassword?: string;
+    /** 请求体大小限制 (字节) @default 1048576 (1MB) */
+    bodyLimit?: number;
+    /** 时区 @default 'Asia/Shanghai' */
+    tz?: string;
+
+    // ========== 插件配置 ==========
+    /** 日志插件配置 */
+    logger?: LoggerConfig;
+    /** 数据库插件配置 */
+    db?: DatabaseConfig;
+    /** Redis 插件配置 */
+    redis?: RedisConfig;
+    /** 认证插件配置 */
+    auth?: AuthConfig;
+    /** CORS 插件配置 */
+    cors?: CorsConfig;
+    /** 禁用的钩子列表 */
+    disableHooks?: string[];
+    /** 禁用的插件列表 */
+    disablePlugins?: string[];
+    /** 其他插件配置 */
     [key: string]: any;
 }
 
 /**
- * CORS 配置选项
- */
-export interface CorsOptions {
-    origin?: string | string[] | boolean;
-    methods?: string[];
-    allowedHeaders?: string[];
-    exposedHeaders?: string[];
-    credentials?: boolean;
-    maxAge?: number;
+ * Befly 应用上下文
+ * 包含所有插件挂载的实例
+ */
+export interface BeflyContext extends KeyValue {
+    // ========== 核心插件（带下划线前缀） ==========
+    /** 数据库助手 (db 插件) */
+    _db?: DbHelper;
+
+    /** Redis 助手 (redis 插件) */
+    _redis?: RedisHelper;
+
+    /** 日志器 (logger 插件) */
+    _logger?: typeof Logger;
+
+    /** 缓存助手 (cache 插件) */
+    _cache?: CacheHelper;
+
+    // ========== 核心插件便捷访问（无前缀） ==========
+    /** 数据库助手便捷访问 */
+    db?: DbHelper;
+
+    /** Redis 助手便捷访问 */
+    redis?: RedisHelper;
+
+    /** 日志器便捷访问 */
+    logger?: typeof Logger;
+
+    /** 缓存助手便捷访问 */
+    cache?: CacheHelper;
+
+    // ========== 动态插件 ==========
+    /** 组件插件：addon_{addonName}_{pluginName} */
+    /** 项目插件：app_{pluginName} */
+    [key: string]: any;
 }
 
 /**
@@ -122,9 +246,9 @@ export interface Befly {
     handleRequest(request: Request): Promise<Response>;
 
     /**
-     * 注册中间件
+     * 注册钩子
      */
-    use(middleware: Function): void;
+    use(hook: Function): void;
 
     /**
      * 获取配置

package/types/context.d.ts

@@ -1,7 +1,33 @@
 /**
  * 请求上下文类型定义
- * 实现代码位于 util.ts，类型定义位于 types/util.d.ts
  */
 
-// 重新导出 RequestContext 接口
-export type { RequestContext } from './util.js';
+import type { ApiRoute } from './api.js';
+
+/**
+ * 请求上下文接口
+ */
+export interface RequestContext {
+    /** 请求体参数 */
+    body: Record<string, any>;
+    /** 用户信息 */
+    user: Record<string, any>;
+    /** 原始请求对象 */
+    req: Request;
+    /** 请求开始时间（毫秒） */
+    now: number;
+    /** 客户端 IP 地址 */
+    ip?: string;
+    /** API 路由路径（如 POST/api/user/login） */
+    route?: string;
+    /** 当前请求的 API 路由对象 */
+    api?: ApiRoute;
+    /** 响应对象（如果设置了此属性，将直接返回该响应） */
+    response?: Response;
+    /** 原始处理结果（未转换为 Response 对象前） */
+    result?: any;
+    /** 请求唯一 ID */
+    requestId?: string;
+    /** CORS 响应头 */
+    corsHeaders?: Record<string, string>;
+}

package/types/hook.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Befly 钩子系统类型定义
+ */
+
+import type { BeflyContext } from './befly.js';
+import type { RequestContext } from './context.js';
+
+/**
+ * 钩子处理函数类型
+ */
+export type Next = () => Promise<void>;
+export type HookHandler = (befly: BeflyContext, ctx: RequestContext, next: Next) => Promise<void> | void;
+
+/**
+ * 钩子配置类型
+ */
+export interface Hook {
+    /** 钩子名称（运行时动态添加，由文件名生成） */
+    name?: string;
+
+    /** 依赖的钩子列表（在这些钩子之后执行） */
+    after?: string[];
+
+    /** 执行顺序（数字越小越先执行，同级别时使用） */
+    order?: number;
+
+    /** 钩子处理函数 */
+    handler: HookHandler;
+
+    /** 钩子配置 */
+    config?: Record<string, any>;
+
+    /** 钩子描述 */
+    description?: string;
+}

package/types/index.ts

@@ -2,4 +2,17 @@
  * 类型定义导出
  */
 
-export * from './env.js';
+export * from './addon.js';
+export * from './api.js';
+export * from './befly.js';
+export * from './common.js';
+export * from './context.js';
+export * from './crypto.js';
+export * from './database.js';
+export * from './jwt.js';
+export * from './logger.js';
+export * from './plugin.js';
+export * from './redis.js';
+export * from './tool.js';
+export * from './validator.js';
+export * from './sync.js';

package/types/plugin.d.ts

@@ -13,16 +13,15 @@ export type PluginInitFunction = (befly: BeflyContext) => Promise<any> | any;
 /**
  * 插件请求处理钩子函数类型
  */
-export type PluginGetHook = (befly: BeflyContext, ctx: RequestContext, req: Request) => Promise<void> | void;
+export type Next = () => Promise<void>;
 
 /**
  * 插件配置类型
  */
 export interface Plugin {
-    /** 插件名称 */
-    name: string;
-
-    /** 插件名称（运行时动态添加，与 name 相同） */
+    /** 插件名称（运行时动态添加，由文件名生成） */
+    name?: string;
+    /** @deprecated use name instead */
     pluginName?: string;
 
     /** 依赖的插件列表（在这些插件之后执行） */
@@ -31,8 +30,8 @@ export interface Plugin {
     /** 插件初始化函数 */
     onInit?: PluginInitFunction;
 
-    /** 请求处理钩子（在每个 API 请求时执行） */
-    onGet?: PluginGetHook;
+    /** 插件配置 */
+    config?: Record<string, any>;
 
     /** 插件描述 */
     description?: string;