befly 3.8.19 → 3.8.21

package/hooks/permission.ts

@@ -0,0 +1,54 @@
+// 相对导入
+import { JsonResponse } from '../util.js';
+
+// 类型导入
+import type { Hook } from '../types/hook.js';
+
+/**
+ * 权限检查钩子
+ * - 接口无需权限（auth=false）：直接通过
+ * - 用户未登录：返回 401
+ * - 开发者角色（dev）：最高权限，直接通过
+ * - 其他角色：检查 Redis 中的角色权限集合
+ */
+const hook: Hook = {
+    after: ['parser'],
+    order: 20,
+    handler: async (befly, ctx, next) => {
+        if (!ctx.api) return next();
+
+        // 1. 接口无需权限
+        if (ctx.api.auth === false) {
+            return next();
+        }
+
+        // 2. 用户未登录
+        if (!ctx.user || !ctx.user.userId) {
+            ctx.response = JsonResponse(ctx, '未登录', 401);
+            return;
+        }
+
+        // 3. 开发者权限（最高权限）
+        if (ctx.user.roleCode === 'dev') {
+            return next();
+        }
+
+        // 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;
+        }
+
+        if (!hasPermission) {
+            ctx.response = JsonResponse(ctx, '无权访问', 403);
+            return;
+        }
+
+        await next();
+    }
+};
+export default hook;

package/hooks/rateLimit.ts

@@ -0,0 +1,70 @@
+// 相对导入
+import { Logger } from '../lib/logger.js';
+import { JsonResponse } from '../util.js';
+
+// 类型导入
+import type { Hook } from '../types/hook.js';
+
+/**
+ * 接口限流插件
+ *
+ * 功能：
+ * 1. 基于 Redis 实现滑动窗口或固定窗口限流
+ * 2. 支持配置格式 "count/seconds" (e.g. "10/60")
+ * 3. 针对每个用户(userId)或IP进行限制
+ */
+const hook: Hook = {
+    // 必须在 auth 之后（获取 userId），但在业务逻辑之前
+    after: ['parser'],
+    order: 25,
+
+    handler: async (befly, ctx, next) => {
+        const { api } = ctx;
+
+        // 1. 检查配置
+        if (!api || !api.rateLimit || !befly.redis) {
+            return next();
+        }
+
+        // 2. 解析配置 "10/60" -> count=10, seconds=60
+        const [countStr, secondsStr] = api.rateLimit.split('/');
+        const limitCount = parseInt(countStr, 10);
+        const limitSeconds = parseInt(secondsStr, 10);
+
+        if (isNaN(limitCount) || isNaN(limitSeconds)) {
+            Logger.warn(`[RateLimit] Invalid config: ${api.rateLimit}`);
+            return next();
+        }
+
+        // 3. 生成 Key
+        // 优先使用 userId，否则使用 IP
+        const identifier = ctx.user?.userId || ctx.ip || 'unknown';
+        const apiPath = ctx.route || `${ctx.req.method}${new URL(ctx.req.url).pathname}`;
+        const key = `rate_limit:${apiPath}:${identifier}`;
+
+        try {
+            // 4. 执行限流逻辑 (使用 Redis INCR)
+            // 这是一个简单的固定窗口算法，对于严格场景可能需要 Lua 脚本实现滑动窗口
+            const current = await befly.redis.incr(key);
+
+            // 5. 设置过期时间 (如果是新 Key)
+            if (current === 1) {
+                await befly.redis.expire(key, limitSeconds);
+            }
+
+            // 6. 判断是否超限
+            if (current > limitCount) {
+                ctx.response = JsonResponse(ctx, '请求过于频繁，请稍后再试', 429);
+                return;
+            }
+
+            return next();
+        } catch (err) {
+            Logger.error('[RateLimit] Redis error:', err);
+            // Redis 故障时，默认放行，避免阻塞业务
+            return next();
+        }
+    }
+};
+
+export default hook;

package/hooks/requestId.ts

@@ -0,0 +1,24 @@
+import type { Hook } from '../types/hook.js';
+import { logContextStorage } from '../lib/logger.js';
+
+const hook: Hook = {
+    after: ['errorHandler'],
+    order: 3,
+    handler: async (befly, ctx, next) => {
+        // 生成唯一请求 ID
+        const requestId = crypto.randomUUID();
+        ctx.requestId = requestId;
+
+        // 添加到 CORS 响应头
+        if (!ctx.corsHeaders) {
+            ctx.corsHeaders = {};
+        }
+        ctx.corsHeaders['X-Request-ID'] = requestId;
+
+        // 在 AsyncLocalStorage 上下文中执行后续钩子
+        await logContextStorage.run({ requestId }, async () => {
+            await next();
+        });
+    }
+};
+export default hook;

package/hooks/requestLogger.ts

@@ -0,0 +1,25 @@
+// 相对导入
+import { Logger } from '../lib/logger.js';
+
+// 类型导入
+import type { Hook } from '../types/hook.js';
+
+/**
+ * 请求日志记录钩子
+ * 记录请求方法、路径、用户信息和响应时间
+ */
+const hook: Hook = {
+    after: ['parser'],
+    order: 30,
+    handler: async (befly, ctx, next) => {
+        await next();
+
+        if (ctx.api) {
+            const apiPath = `${ctx.req.method}${new URL(ctx.req.url).pathname}`;
+            const duration = Date.now() - ctx.now;
+            const user = ctx.user?.userId ? `[User:${ctx.user.userId}]` : '[Guest]';
+            Logger.info(`[${ctx.req.method}] ${apiPath} ${user} ${duration}ms`);
+        }
+    }
+};
+export default hook;

package/hooks/responseFormatter.ts

@@ -0,0 +1,64 @@
+// 相对导入
+import { JsonResponse } from '../util.js';
+
+// 类型导入
+import type { Hook } from '../types/hook.js';
+
+const hook: Hook = {
+    after: ['requestId'],
+    order: 100,
+    handler: async (befly, ctx, next) => {
+        await next();
+
+        // 如果已经有 response，直接返回
+        if (ctx.response) {
+            return;
+        }
+
+        // 如果有 result，格式化为 JSON 响应
+        if (ctx.result !== undefined) {
+            let result = ctx.result;
+
+            // 1. 如果是字符串，自动包裹为成功响应
+            if (typeof result === 'string') {
+                result = {
+                    code: 0,
+                    msg: result,
+                    data: {}
+                };
+            }
+            // 2. 如果是对象，自动补充 code: 0
+            else if (result && typeof result === 'object') {
+                if (!('code' in result)) {
+                    result = {
+                        code: 0,
+                        ...result
+                    };
+                }
+            }
+
+            // 处理 BigInt 序列化问题
+            if (result && typeof result === 'object') {
+                const jsonString = JSON.stringify(result, (key, value) => (typeof value === 'bigint' ? value.toString() : value));
+                ctx.response = new Response(jsonString, {
+                    headers: {
+                        ...ctx.corsHeaders,
+                        'Content-Type': 'application/json'
+                    }
+                });
+            } else {
+                // 简单类型直接返回
+                ctx.response = Response.json(result, {
+                    headers: ctx.corsHeaders
+                });
+            }
+            return;
+        }
+
+        // 如果还没有响应，且不是 OPTIONS 请求，则设置默认 JSON 响应
+        if (ctx.req.method !== 'OPTIONS' && !ctx.response) {
+            ctx.response = JsonResponse(ctx, 'No response generated');
+        }
+    }
+};
+export default hook;

package/hooks/validator.ts

@@ -0,0 +1,34 @@
+// 相对导入
+import { Validator } from '../lib/validator.js';
+import { JsonResponse } from '../util.js';
+
+// 类型导入
+import type { Hook } from '../types/hook.js';
+
+/**
+ * 参数验证钩子
+ * 根据 API 定义的 fields 和 required 验证请求参数
+ */
+const hook: Hook = {
+    after: ['parser'],
+    order: 15,
+    handler: async (befly, ctx, next) => {
+        if (!ctx.api) return next();
+
+        // 无需验证
+        if (!ctx.api.fields) {
+            return next();
+        }
+
+        // 验证参数
+        const result = Validator.validate(ctx.body, ctx.api.fields, ctx.api.required || []);
+
+        if (result.code !== 0) {
+            ctx.response = JsonResponse(ctx, '无效的请求参数格式', 1, result.fields);
+            return;
+        }
+
+        await next();
+    }
+};
+export default hook;

package/lib/database.ts

@@ -4,11 +4,10 @@
  */
 
 import { SQL, RedisClient } from 'bun';
-import { Env } from '../env.js';
 import { Logger } from './logger.js';
 import { DbHelper } from './dbHelper.js';
 import { RedisHelper } from './redisHelper.js';
-import type { BeflyContext } from '../types/befly.js';
+import type { BeflyContext, DatabaseConfig, RedisConfig } from '../types/befly.js';
 import type { SqlClientOptions } from '../types/database.js';
 
 /**
@@ -26,50 +25,49 @@ export class Database {
 
     /**
      * 连接 SQL 数据库
-     * @param options - SQL 客户端配置选项
+     * @param config - 数据库配置
      * @returns SQL 客户端实例
      */
-    static async connectSql(options: SqlClientOptions = {}): Promise<SQL> {
+    static async connectSql(config: DatabaseConfig): Promise<SQL> {
         // 构建数据库连接字符串
-        const type = Env.DB_TYPE || '';
-        const host = Env.DB_HOST || '';
-        const port = Env.DB_PORT;
-        const user = encodeURIComponent(Env.DB_USER || '');
-        const password = encodeURIComponent(Env.DB_PASS || '');
-        const database = encodeURIComponent(Env.DB_NAME || '');
+        const type = config.type || 'mysql';
+        const host = config.host || '127.0.0.1';
+        const port = config.port || 3306;
+        const user = encodeURIComponent(config.username || 'root');
+        const password = encodeURIComponent(config.password || 'root');
+        const database = encodeURIComponent(config.database || 'befly_demo');
 
         let finalUrl: string;
         if (type === 'sqlite') {
             finalUrl = database;
         } else {
             if (!host || !database) {
-                throw new Error('数据库配置不完整，请检查环境变量');
+                throw new Error('数据库配置不完整，请检查配置参数');
             }
             finalUrl = `${type}://${user}:${password}@${host}:${port}/${database}`;
         }
 
         let sql: SQL;
 
-        if (Env.DB_TYPE === 'sqlite') {
+        if (type === 'sqlite') {
             sql = new SQL(finalUrl);
         } else {
             sql = new SQL({
                 url: finalUrl,
-                max: options.max ?? 1,
-                bigint: false,
-                ...options
+                max: config.poolMax ?? 1,
+                bigint: false
             });
         }
 
         try {
-            const timeout = options.connectionTimeout ?? 30000;
+            const timeout = 30000;
 
             const healthCheckPromise = (async () => {
                 let version = '';
-                if (Env.DB_TYPE === 'sqlite') {
+                if (type === 'sqlite') {
                     const v = await sql`SELECT sqlite_version() AS version`;
                     version = v?.[0]?.version;
-                } else if (Env.DB_TYPE === 'postgresql' || Env.DB_TYPE === 'postgres') {
+                } else if (type === 'postgresql' || type === 'postgres') {
                     const v = await sql`SELECT version() AS version`;
                     version = v?.[0]?.version;
                 } else {
@@ -157,21 +155,26 @@ export class Database {
 
     /**
      * 连接 Redis
+     * @param config - Redis 配置
      * @returns Redis 客户端实例
      */
-    static async connectRedis(): Promise<RedisClient> {
+    static async connectRedis(config: RedisConfig = {}): Promise<RedisClient> {
         try {
             // 构建 Redis URL
-            const { REDIS_HOST, REDIS_PORT, REDIS_USERNAME, REDIS_PASSWORD, REDIS_DB } = Env;
+            const host = config.host || '127.0.0.1';
+            const port = config.port || 6379;
+            const username = config.username || '';
+            const password = config.password || '';
+            const db = config.db || 0;
 
             let auth = '';
-            if (REDIS_USERNAME && REDIS_PASSWORD) {
-                auth = `${REDIS_USERNAME}:${REDIS_PASSWORD}@`;
-            } else if (REDIS_PASSWORD) {
-                auth = `:${REDIS_PASSWORD}@`;
+            if (username && password) {
+                auth = `${username}:${password}@`;
+            } else if (password) {
+                auth = `:${password}@`;
             }
 
-            const url = `redis://${auth}${REDIS_HOST}:${REDIS_PORT}/${REDIS_DB}`;
+            const url = `redis://${auth}${host}:${port}/${db}`;
 
             const redis = new RedisClient(url, {
                 connectionTimeout: 30000,

package/lib/dbHelper.ts

@@ -5,7 +5,7 @@
 
 import { snakeCase } from 'es-toolkit/string';
 import { SqlBuilder } from './sqlBuilder.js';
-import { keysToCamel, arrayKeysToCamel, keysToSnake, fieldClear } from '../util.js';
+import { keysToCamel, arrayKeysToCamel, keysToSnake, fieldClear } from 'befly-util';
 import { Logger } from '../lib/logger.js';
 import type { WhereConditions } from '../types/common.js';
 import type { BeflyContext } from '../types/befly.js';
@@ -204,8 +204,8 @@ export class DbHelper {
     /**
      * 清理数据或 where 条件（默认排除 null 和 undefined）
      */
-    private cleanFields<T extends Record<string, any>>(data: T | undefined | null, excludeValues: any[] = [null, undefined], keepValues: Record<string, any> = {}): Partial<T> {
-        return fieldClear(data || ({} as T), excludeValues, keepValues);
+    public cleanFields<T extends Record<string, any>>(data: T, excludeValues: any[] = [null, undefined], keepValues: Record<string, any> = {}): Partial<T> {
+        return fieldClear(data || ({} as T), { excludeValues, keepMap: keepValues });
     }
 
     /**