befly 3.8.29 → 3.8.31

package/README.md

@@ -37,12 +37,14 @@ bunx befly init
 
 ```typescript
 // main.ts
-import { Server } from 'befly';
+import { Befly } from 'befly';
 
-await Server({
-    name: 'My API',
-    port: 3000
+const app = new Befly({
+    appName: 'My API',
+    appPort: 3000
 });
+
+await app.start();
 ```
 
 运行项目：
@@ -55,7 +57,7 @@ bun run main.ts
 
 ```typescript
 // apis/user/hello.ts
-import type { ApiRoute } from 'befly';
+import type { ApiRoute } from 'befly/types/index';
 
 export default {
     name: '问候接口',
@@ -79,7 +81,7 @@ export default {
 ### TypeScript 全面支持
 
 ```typescript
-import type { ApiRoute, BeflyContext } from 'befly';
+import type { ApiRoute, BeflyContext } from 'befly/types/index';
 import type { User } from './types/models';
 
 export default {
@@ -194,6 +196,89 @@ DB_NAME=/path/to/database.sqlite
 DB_NAME=:memory:
 ```
 
+## ⚙️ 项目配置文件
+
+Befly 使用 `befly.config.ts` 作为统一配置文件：
+
+```typescript
+// befly.config.ts
+export const beflyConfig = {
+    appName: '我的应用',
+    appPort: 3000,
+    appHost: '0.0.0.0',
+
+    // 数据库配置（优先使用环境变量）
+    db: {
+        type: 'mysql',
+        host: '127.0.0.1',
+        port: 3306,
+        username: 'root',
+        password: 'password',
+        database: 'my_database'
+    },
+
+    // Redis 配置
+    redis: {
+        host: '127.0.0.1',
+        port: 6379,
+        prefix: 'befly:'
+    },
+
+    // CORS 跨域配置
+    cors: {
+        origin: ['http://localhost:5173'],
+        methods: ['GET', 'POST', 'PUT', 'DELETE']
+    },
+
+    // Addon 插件配置
+    addons: {
+        admin: {
+            email: { host: 'smtp.qq.com' }
+        }
+    }
+};
+```
+
+### 数据库连接
+
+框架会自动从 `beflyConfig` 获取配置并建立连接，无需手动传参：
+
+```typescript
+import { Connect } from 'befly/lib/connect';
+
+// 连接 SQL 数据库（配置自动从 beflyConfig.db 获取）
+await Connect.connectSql();
+
+// 连接 Redis（配置自动从 beflyConfig.redis 获取）
+await Connect.connectRedis();
+
+// 同时连接 SQL 和 Redis
+await Connect.connect();
+
+// 获取连接状态
+const status = Connect.getStatus();
+console.log(status.sql.connected); // true/false
+console.log(status.redis.connected); // true/false
+
+// 断开连接
+await Connect.disconnect();
+```
+
+### 配置文件迁移指南
+
+如果你的项目之前使用 `app.config.ts`，请按以下步骤迁移：
+
+1. **重命名文件**：`app.config.ts` → `befly.config.ts`
+2. **更新导出名**：`config` → `beflyConfig`
+
+```typescript
+// 旧写法
+export const config = { ... };
+
+// 新写法
+export const beflyConfig = { ... };
+```
+
 ## 📖 文档
 
 完整文档请访问 [`/docs` 目录](./docs/)：

package/checks/checkApi.ts

@@ -3,7 +3,8 @@ import { existsSync } from 'node:fs';
 
 // 外部依赖
 import { isPlainObject } from 'es-toolkit/compat';
-import { scanAddons, getAddonDir, addonDirExists, scanFiles } from 'befly-util';
+import { scanFiles } from 'befly-shared/scanFiles';
+import { scanAddons, getAddonDir, addonDirExists } from 'befly-shared/addonHelper';
 
 // 相对导入
 import { Logger } from '../lib/logger.js';

package/checks/checkApp.ts

@@ -1,6 +1,6 @@
 // 内部依赖
 import { join } from 'node:path';
-import { existsSync, mkdirSync } from 'node:fs';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 
 // 相对导入
 import { Logger } from '../lib/logger.js';
@@ -24,6 +24,36 @@ export async function checkApp(): Promise<void> {
         if (!existsSync(logsDir)) {
             mkdirSync(logsDir, { recursive: true });
         }
+
+        // 检查并创建 configs 目录和配置文件
+        const configsDir = join(projectDir, 'configs');
+        if (!existsSync(configsDir)) {
+            mkdirSync(configsDir, { recursive: true });
+        }
+
+        // 检查并创建 befly.common.json
+        const beflyJsonPath = join(configsDir, 'befly.common.json');
+        if (!existsSync(beflyJsonPath)) {
+            writeFileSync(beflyJsonPath, '{}', 'utf-8');
+        }
+
+        // 检查并创建 befly.dev.json
+        const beflyDevJsonPath = join(configsDir, 'befly.dev.json');
+        if (!existsSync(beflyDevJsonPath)) {
+            writeFileSync(beflyDevJsonPath, '{}', 'utf-8');
+        }
+
+        // 检查并创建 befly.prod.json
+        const beflyProdJsonPath = join(configsDir, 'befly.prod.json');
+        if (!existsSync(beflyProdJsonPath)) {
+            writeFileSync(beflyProdJsonPath, '{}', 'utf-8');
+        }
+
+        // 检查并创建 befly.local.json
+        const beflyLocalJsonPath = join(configsDir, 'befly.local.json');
+        if (!existsSync(beflyLocalJsonPath)) {
+            writeFileSync(beflyLocalJsonPath, '{}', 'utf-8');
+        }
     } catch (error: any) {
         Logger.error('项目结构检查过程中出错', error);
         throw error;

package/checks/checkTable.ts

@@ -3,14 +3,15 @@ import { existsSync } from 'node:fs';
 
 // 外部依赖
 import { basename } from 'pathe';
-import { scanAddons, getAddonDir, scanFiles } from 'befly-util';
+import { scanFiles } from 'befly-shared/scanFiles';
+import { scanAddons, getAddonDir } from 'befly-shared/addonHelper';
 
 // 相对导入
 import { Logger } from '../lib/logger.js';
 import { projectTableDir } from '../paths.js';
 
 // 类型导入
-import type { FieldDefinition } from '../types/common.js';
+import type { FieldDefinition } from 'befly-shared/types';
 
 /**
  * 表文件信息接口

package/hooks/cors.ts

@@ -1,5 +1,6 @@
 // 相对导入
 import { setCorsOptions } from '../util.js';
+import { beflyConfig } from '../befly.config.js';
 
 // 类型导入
 import type { Hook } from '../types/hook.js';
@@ -24,11 +25,10 @@ const hook: Hook = {
             credentials: 'true'
         };
 
-        const userConfig = (hook as any).config || {};
-        const config = { ...defaultConfig, ...userConfig };
+        const corsConfig = { ...defaultConfig, ...(beflyConfig.cors || {}) };
 
         // 设置 CORS 响应头
-        const headers = setCorsOptions(req, config);
+        const headers = setCorsOptions(req, corsConfig);
 
         ctx.corsHeaders = headers;
 

package/hooks/parser.ts

@@ -1,14 +1,16 @@
 // 外部依赖
 import { isPlainObject, isEmpty } from 'es-toolkit/compat';
-import { pickFields } from 'befly-util';
+import { pickFields } from 'befly-shared/pickFields';
+import { XMLParser } from 'fast-xml-parser';
 
 // 相对导入
-import { Xml } from '../lib/xml.js';
 import { ErrorResponse } from '../util.js';
 
 // 类型导入
 import type { Hook } from '../types/hook.js';
 
+const xmlParser = new XMLParser();
+
 /**
  * 请求参数解析钩子
  * - GET 请求：解析 URL 查询参数
@@ -43,7 +45,7 @@ const hook: Hook = {
                 } else if (contentType.includes('application/xml') || contentType.includes('text/xml')) {
                     // XML 格式
                     const text = await ctx.req.text();
-                    const body = await Xml.parse(text);
+                    const body = xmlParser.parse(text);
                     if (isPlainObject(ctx.api.fields) && !isEmpty(ctx.api.fields)) {
                         ctx.body = pickFields(body, Object.keys(ctx.api.fields));
                     } else {
@@ -51,12 +53,12 @@ const hook: Hook = {
                     }
                 } else {
                     // 不支持的 Content-Type
-                    ctx.response = ErrorResponse(ctx, '无效的请求参数格式');
+                    ctx.response = ErrorResponse(ctx, '无效的请求参数格式', 1, null, { location: 'content-type', value: contentType });
                     return;
                 }
-            } catch (e) {
+            } catch (e: any) {
                 // 解析失败
-                ctx.response = ErrorResponse(ctx, '无效的请求参数格式');
+                ctx.response = ErrorResponse(ctx, '无效的请求参数格式', 1, null, { location: 'body', error: e.message });
                 return;
             }
         }

package/hooks/permission.ts

@@ -1,5 +1,6 @@
 // 相对导入
 import { ErrorResponse } from '../util.js';
+import { RedisKeys } from 'befly-shared/redisKeys';
 
 // 类型导入
 import type { Hook } from '../types/hook.js';
@@ -35,11 +36,17 @@ const hook: Hook = {
         // 4. 角色权限检查
         let hasPermission = false;
         if (ctx.user.roleCode && befly.redis) {
-            // 验证角色权限
-            const apiPath = `${ctx.req.method}${new URL(ctx.req.url).pathname}`;
-            const roleApisKey = `role:apis:${ctx.user.roleCode}`;
-            const isMember = await befly.redis.sismember(roleApisKey, apiPath);
-            hasPermission = isMember === 1;
+            try {
+                // 验证角色权限
+                const apiPath = `${ctx.req.method}${new URL(ctx.req.url).pathname}`;
+                const roleApisKey = RedisKeys.roleApis(ctx.user.roleCode);
+                const isMember = await befly.redis.sismember(roleApisKey, apiPath);
+                hasPermission = isMember === 1;
+            } catch (error) {
+                // Redis 异常时降级为拒绝访问
+                befly.logger.warn({ err: error, route: ctx.route }, 'Redis 权限检查失败');
+                hasPermission = false;
+            }
         }
 
         if (!hasPermission) {

package/hooks/validator.ts

@@ -23,7 +23,7 @@ const hook: Hook = {
         const result = Validator.validate(ctx.body, ctx.api.fields, ctx.api.required || []);
 
         if (result.code !== 0) {
-            ctx.response = ErrorResponse(ctx, '无效的请求参数格式', 1, result.fields);
+            ctx.response = ErrorResponse(ctx, result.firstError || '参数验证失败', 1, null, result.fieldErrors);
             return;
         }
     }

package/lib/cacheHelper.ts

@@ -4,6 +4,8 @@
  */
 
 import { Logger } from './logger.js';
+import { RedisKeys } from 'befly-shared/redisKeys';
+
 import type { BeflyContext } from '../types/befly.js';
 
 /**
@@ -26,29 +28,27 @@ export class CacheHelper {
     async cacheApis(): Promise<void> {
         try {
             // 检查表是否存在
-            const tableExists = await this.befly.db.tableExists('core_api');
+            const tableExists = await this.befly.db.tableExists('addon_admin_api');
             if (!tableExists) {
                 Logger.warn('⚠️ 接口表不存在，跳过接口缓存');
                 return;
             }
 
-            // 从数据库查询所有接口（与 apiAll.ts 保持一致）
+            // 从数据库查询所有接口
             const apiList = await this.befly.db.getAll({
-                table: 'core_api',
+                table: 'addon_admin_api',
                 fields: ['id', 'name', 'path', 'method', 'description', 'addonName', 'addonTitle'],
                 orderBy: ['addonName#ASC', 'path#ASC']
             });
 
             // 缓存到 Redis
-            const result = await this.befly.redis.setObject('apis:all', apiList);
+            const result = await this.befly.redis.setObject(RedisKeys.apisAll(), apiList);
 
             if (result === null) {
                 Logger.warn('⚠️ 接口缓存失败');
-            } else {
-                Logger.info(`✅ 已缓存 ${apiList.length} 个接口到 Redis (Key: apis:all)`);
             }
         } catch (error: any) {
-            Logger.error('⚠️ 接口缓存异常:', error);
+            Logger.error({ err: error }, '⚠️ 接口缓存异常');
         }
     }
 
@@ -58,7 +58,7 @@ export class CacheHelper {
     async cacheMenus(): Promise<void> {
         try {
             // 检查表是否存在
-            const tableExists = await this.befly.db.tableExists('core_menu');
+            const tableExists = await this.befly.db.tableExists('addon_admin_menu');
             if (!tableExists) {
                 Logger.warn('⚠️ 菜单表不存在，跳过菜单缓存');
                 return;
@@ -66,86 +66,97 @@ export class CacheHelper {
 
             // 从数据库查询所有菜单
             const menus = await this.befly.db.getAll({
-                table: 'core_menu',
+                table: 'addon_admin_menu',
                 fields: ['id', 'pid', 'name', 'path', 'icon', 'type', 'sort'],
                 orderBy: ['sort#ASC', 'id#ASC']
             });
 
             // 缓存到 Redis
-            const result = await this.befly.redis.setObject('menus:all', menus);
+            const result = await this.befly.redis.setObject(RedisKeys.menusAll(), menus);
 
             if (result === null) {
                 Logger.warn('⚠️ 菜单缓存失败');
-            } else {
-                Logger.info(`✅ 已缓存 ${menus.length} 个菜单到 Redis (Key: menus:all)`);
             }
         } catch (error: any) {
-            const errorMessage = error?.message || error?.toString?.() || String(error);
-            Logger.warn('⚠️ 菜单缓存异常:', errorMessage);
+            Logger.warn({ err: error }, '⚠️ 菜单缓存异常');
         }
     }
 
     /**
      * 缓存所有角色的接口权限到 Redis
+     * 优化：使用 Promise.all 利用 Bun Redis 自动 pipeline 特性
      */
     async cacheRolePermissions(): Promise<void> {
         try {
             // 检查表是否存在
-            const apiTableExists = await this.befly.db.tableExists('core_api');
-            const roleTableExists = await this.befly.db.tableExists('core_role');
+            const apiTableExists = await this.befly.db.tableExists('addon_admin_api');
+            const roleTableExists = await this.befly.db.tableExists('addon_admin_role');
 
             if (!apiTableExists || !roleTableExists) {
                 Logger.warn('⚠️ 接口或角色表不存在，跳过角色权限缓存');
                 return;
             }
 
-            // 查询所有角色
-            const roles = await this.befly.db.getAll({
-                table: 'core_role',
-                fields: ['id', 'code', 'apis']
-            });
+            // 并行查询角色和接口（利用自动 pipeline）
+            const [roles, allApis] = await Promise.all([
+                this.befly.db.getAll({
+                    table: 'addon_admin_role',
+                    fields: ['id', 'code', 'apis']
+                }),
+                this.befly.db.getAll({
+                    table: 'addon_admin_api',
+                    fields: ['id', 'path', 'method']
+                })
+            ]);
+
+            // 构建接口 ID -> 路径的映射（避免重复过滤）
+            const apiMap = new Map<number, string>();
+            for (const api of allApis) {
+                apiMap.set(api.id, `${api.method}${api.path}`);
+            }
 
-            // 查询所有接口（用于权限映射）
-            const allApis = await this.befly.db.getAll({
-                table: 'core_api',
-                fields: ['id', 'name', 'path', 'method', 'description', 'addonName']
-            });
+            // 收集需要缓存的角色权限
+            const cacheOperations: Array<{ roleCode: string; apiPaths: string[] }> = [];
 
-            // 为每个角色缓存接口权限
-            let cachedRoles = 0;
             for (const role of roles) {
                 if (!role.apis) continue;
 
-                // 解析角色的接口 ID 列表
-                const apiIds = role.apis
-                    .split(',')
-                    .map((id: string) => parseInt(id.trim()))
-                    .filter((id: number) => !isNaN(id));
-
-                // 根据 ID 过滤出接口路径
-                const roleApiPaths = allApis.filter((api: any) => apiIds.includes(api.id)).map((api: any) => `${api.method}${api.path}`);
-
-                if (roleApiPaths.length === 0) continue;
+                // 解析角色的接口 ID 列表并映射到路径
+                const apiPaths: string[] = [];
+                const apiIds = role.apis.split(',');
+
+                for (const idStr of apiIds) {
+                    const id = parseInt(idStr.trim());
+                    if (!isNaN(id)) {
+                        const path = apiMap.get(id);
+                        if (path) {
+                            apiPaths.push(path);
+                        }
+                    }
+                }
 
-                // 使用 Redis Set 缓存角色权限（性能优化：SADD + SISMEMBER）
-                const redisKey = `role:apis:${role.code}`;
+                if (apiPaths.length > 0) {
+                    cacheOperations.push({ roleCode: role.code, apiPaths: apiPaths });
+                }
+            }
 
-                // 先删除旧数据
-                await this.befly.redis.del(redisKey);
+            if (cacheOperations.length === 0) {
+                Logger.info('✅ 没有需要缓存的角色权限');
+                return;
+            }
 
-                // 批量添加到 Set
-                const result = await this.befly.redis.sadd(redisKey, roleApiPaths);
+            // 批量删除旧缓存（利用自动 pipeline）
+            const deletePromises = cacheOperations.map((op) => this.befly.redis.del(RedisKeys.roleApis(op.roleCode)));
+            await Promise.all(deletePromises);
 
-                if (result > 0) {
-                    cachedRoles++;
-                    Logger.debug(`   └ 角色 ${role.code}: ${result} 个接口`);
-                }
-            }
+            // 批量添加新缓存（利用自动 pipeline）
+            const addPromises = cacheOperations.map((op) => this.befly.redis.sadd(RedisKeys.roleApis(op.roleCode), op.apiPaths));
+            const results = await Promise.all(addPromises);
 
-            Logger.info(`✅ 已缓存 ${cachedRoles} 个角色的接口权限`);
+            // 统计成功缓存的角色数
+            const cachedRoles = results.filter((r) => r > 0).length;
         } catch (error: any) {
-            const errorMessage = error?.message || error?.toString?.() || String(error);
-            Logger.warn('⚠️ 角色权限缓存异常:', errorMessage);
+            Logger.warn({ err: error }, '⚠️ 角色权限缓存异常');
         }
     }
 
@@ -169,10 +180,10 @@ export class CacheHelper {
      */
     async getApis(): Promise<any[]> {
         try {
-            const apis = await this.befly.redis.getObject<any[]>('apis:all');
+            const apis = await this.befly.redis.getObject<any[]>(RedisKeys.apisAll());
             return apis || [];
         } catch (error: any) {
-            Logger.error('获取接口缓存失败:', error);
+            Logger.error({ err: error }, '获取接口缓存失败');
             return [];
         }
     }
@@ -183,10 +194,10 @@ export class CacheHelper {
      */
     async getMenus(): Promise<any[]> {
         try {
-            const menus = await this.befly.redis.getObject<any[]>('menus:all');
+            const menus = await this.befly.redis.getObject<any[]>(RedisKeys.menusAll());
             return menus || [];
         } catch (error: any) {
-            Logger.error('获取菜单缓存失败:', error);
+            Logger.error({ err: error }, '获取菜单缓存失败');
             return [];
         }
     }
@@ -198,11 +209,10 @@ export class CacheHelper {
      */
     async getRolePermissions(roleCode: string): Promise<string[]> {
         try {
-            const redisKey = `role:apis:${roleCode}`;
-            const permissions = await this.befly.redis.smembers(redisKey);
+            const permissions = await this.befly.redis.smembers(RedisKeys.roleApis(roleCode));
             return permissions || [];
         } catch (error: any) {
-            Logger.error(`获取角色 ${roleCode} 权限缓存失败:`, error);
+            Logger.error({ err: error, roleCode: roleCode }, '获取角色权限缓存失败');
             return [];
         }
     }
@@ -215,11 +225,10 @@ export class CacheHelper {
      */
     async checkRolePermission(roleCode: string, apiPath: string): Promise<boolean> {
         try {
-            const redisKey = `role:apis:${roleCode}`;
-            const result = await this.befly.redis.sismember(redisKey, apiPath);
+            const result = await this.befly.redis.sismember(RedisKeys.roleApis(roleCode), apiPath);
             return result === 1;
         } catch (error: any) {
-            Logger.error(`检查角色 ${roleCode} 权限失败:`, error);
+            Logger.error({ err: error, roleCode: roleCode }, '检查角色权限失败');
             return false;
         }
     }
@@ -231,15 +240,14 @@ export class CacheHelper {
      */
     async deleteRolePermissions(roleCode: string): Promise<boolean> {
         try {
-            const redisKey = `role:apis:${roleCode}`;
-            const result = await this.befly.redis.del(redisKey);
+            const result = await this.befly.redis.del(RedisKeys.roleApis(roleCode));
             if (result > 0) {
                 Logger.info(`✅ 已删除角色 ${roleCode} 的权限缓存`);
                 return true;
             }
             return false;
         } catch (error: any) {
-            Logger.error(`删除角色 ${roleCode} 权限缓存失败:`, error);
+            Logger.error({ err: error, roleCode: roleCode }, '删除角色权限缓存失败');
             return false;
         }
     }

package/lib/cipher.ts

@@ -4,7 +4,8 @@
  */
 
 import { createSign } from 'node:crypto';
-import type { EncodingType, HashAlgorithm, PasswordHashOptions } from '../types/crypto';
+
+import type { EncodingType, HashAlgorithm, PasswordHashOptions } from 'befly-shared/types';
 
 /**
  * 加密工具类