befly 3.2.0 → 3.3.0

package/lib/database.ts

@@ -0,0 +1,296 @@
+/**
+ * 数据库连接管理器
+ * 统一管理 SQL 和 Redis 连接
+ */
+
+import { SQL, RedisClient } from 'bun';
+import { Env } from '../config/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 { SqlClientOptions } from '../types/database.js';
+
+/**
+ * 数据库连接管理器
+ * 使用静态方法管理全局单例连接
+ */
+export class Database {
+    private static sqlClient: SQL | null = null;
+    private static redisClient: RedisClient | null = null;
+    private static dbHelper: DbHelper | null = null;
+
+    // ========================================
+    // SQL 连接管理
+    // ========================================
+
+    /**
+     * 连接 SQL 数据库
+     * @param options - SQL 客户端配置选项
+     * @returns SQL 客户端实例
+     */
+    static async connectSql(options: SqlClientOptions = {}): 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 || '');
+
+        let finalUrl: string;
+        if (type === 'sqlite') {
+            finalUrl = database;
+        } else {
+            if (!host || !database) {
+                throw new Error('数据库配置不完整，请检查环境变量');
+            }
+            finalUrl = `${type}://${user}:${password}@${host}:${port}/${database}`;
+        }
+
+        let sql: SQL;
+
+        if (Env.DB_TYPE === 'sqlite') {
+            sql = new SQL(finalUrl);
+        } else {
+            sql = new SQL({
+                url: finalUrl,
+                max: options.max ?? 1,
+                bigint: false,
+                ...options
+            });
+        }
+
+        try {
+            const timeout = options.connectionTimeout ?? 5000;
+
+            const healthCheckPromise = (async () => {
+                let version = '';
+                if (Env.DB_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') {
+                    const v = await sql`SELECT version() AS version`;
+                    version = v?.[0]?.version;
+                } else {
+                    const v = await sql`SELECT VERSION() AS version`;
+                    version = v?.[0]?.version;
+                }
+                return version;
+            })();
+
+            const timeoutPromise = new Promise<never>((_, reject) => {
+                setTimeout(() => {
+                    reject(new Error(`数据库连接超时 (${timeout}ms)`));
+                }, timeout);
+            });
+
+            const version = await Promise.race([healthCheckPromise, timeoutPromise]);
+
+            Logger.info(`数据库连接成功，version: ${version}`);
+
+            this.sqlClient = sql;
+            return sql;
+        } catch (error: any) {
+            Logger.error('数据库连接测试失败', error);
+
+            try {
+                await sql.close();
+            } catch (cleanupError) {}
+
+            throw error;
+        }
+    }
+
+    /**
+     * 断开 SQL 连接
+     */
+    static async disconnectSql(): Promise<void> {
+        if (this.sqlClient) {
+            try {
+                await this.sqlClient.close();
+                Logger.info('SQL 连接已关闭');
+            } catch (error: any) {
+                Logger.warn('关闭 SQL 连接时出错:', error.message);
+            }
+            this.sqlClient = null;
+        }
+
+        if (this.dbHelper) {
+            this.dbHelper = null;
+        }
+    }
+
+    /**
+     * 获取 SQL 客户端实例
+     * @throws 如果未连接则抛出错误
+     */
+    static getSql(): SQL {
+        if (!this.sqlClient) {
+            throw new Error('SQL 客户端未连接，请先调用 Database.connectSql()');
+        }
+        return this.sqlClient;
+    }
+
+    /**
+     * 获取 DbHelper 实例
+     * @throws 如果未连接则抛出错误
+     */
+    static getDbHelper(befly?: BeflyContext): DbHelper {
+        if (!this.dbHelper) {
+            if (!this.sqlClient) {
+                throw new Error('SQL 客户端未连接，请先调用 Database.connectSql()');
+            }
+            // 创建临时 befly 上下文（仅用于 DbHelper）
+            const ctx = befly || {
+                redis: RedisHelper,
+                db: null as any,
+                tool: null as any,
+                logger: null as any
+            };
+            this.dbHelper = new DbHelper(ctx, this.sqlClient);
+        }
+        return this.dbHelper;
+    }
+
+    // ========================================
+    // Redis 连接管理
+    // ========================================
+
+    /**
+     * 连接 Redis
+     * @returns Redis 客户端实例
+     */
+    static async connectRedis(): Promise<RedisClient> {
+        try {
+            // 构建 Redis URL
+            const { REDIS_HOST, REDIS_PORT, REDIS_USERNAME, REDIS_PASSWORD, REDIS_DB } = Env;
+
+            let auth = '';
+            if (REDIS_USERNAME && REDIS_PASSWORD) {
+                auth = `${REDIS_USERNAME}:${REDIS_PASSWORD}@`;
+            } else if (REDIS_PASSWORD) {
+                auth = `:${REDIS_PASSWORD}@`;
+            }
+
+            const url = `redis://${auth}${REDIS_HOST}:${REDIS_PORT}/${REDIS_DB}`;
+
+            const redis = new RedisClient(url, {
+                connectionTimeout: 10000,
+                idleTimeout: 0,
+                autoReconnect: true,
+                maxRetries: 0,
+                enableOfflineQueue: true,
+                enableAutoPipelining: true
+            });
+
+            await redis.ping();
+            Logger.info('Redis 连接成功');
+
+            this.redisClient = redis;
+            return redis;
+        } catch (error: any) {
+            Logger.error('Redis 连接失败', error);
+            throw new Error(`Redis 连接失败: ${error.message}`);
+        }
+    }
+
+    /**
+     * 断开 Redis 连接
+     */
+    static async disconnectRedis(): Promise<void> {
+        if (this.redisClient) {
+            try {
+                this.redisClient.close();
+                Logger.info('Redis 连接已关闭');
+            } catch (error: any) {
+                Logger.warn('关闭 Redis 连接时出错:', error);
+            }
+            this.redisClient = null;
+        }
+    }
+
+    /**
+     * 获取 Redis 客户端实例
+     * @throws 如果未连接则抛出错误
+     */
+    static getRedis(): RedisClient {
+        if (!this.redisClient) {
+            throw new Error('Redis 客户端未连接，请先调用 Database.connectRedis()');
+        }
+        return this.redisClient;
+    }
+
+    // ========================================
+    // 统一连接管理
+    // ========================================
+
+    /**
+     * 连接所有数据库（SQL + Redis）
+     * @param options - 配置选项
+     */
+    static async connect(options?: { sql?: SqlClientOptions; redis?: boolean }): Promise<void> {
+        try {
+            if (options?.sql !== false) {
+                Logger.info('正在初始化 SQL 连接...');
+                await this.connectSql(options?.sql);
+            }
+
+            if (options?.redis !== false) {
+                Logger.info('正在初始化 Redis 连接...');
+                await this.connectRedis();
+            }
+
+            Logger.info('数据库连接初始化完成');
+        } catch (error: any) {
+            Logger.error('数据库初始化失败', error);
+            await this.disconnect();
+            throw error;
+        }
+    }
+
+    /**
+     * 断开所有数据库连接
+     */
+    static async disconnect(): Promise<void> {
+        await this.disconnectSql();
+        await this.disconnectRedis();
+    }
+
+    /**
+     * 检查连接状态
+     */
+    static isConnected(): { sql: boolean; redis: boolean } {
+        return {
+            sql: this.sqlClient !== null,
+            redis: this.redisClient !== null
+        };
+    }
+
+    // ========================================
+    // 测试辅助方法
+    // ========================================
+
+    /**
+     * 设置 mock SQL 客户端（仅用于测试）
+     */
+    static __setMockSql(mockClient: SQL): void {
+        this.sqlClient = mockClient;
+    }
+
+    /**
+     * 设置 mock Redis 客户端（仅用于测试）
+     */
+    static __setMockRedis(mockClient: RedisClient): void {
+        this.redisClient = mockClient;
+    }
+
+    /**
+     * 重置所有连接状态（仅用于测试）
+     */
+    static __reset(): void {
+        this.sqlClient = null;
+        this.redisClient = null;
+        this.dbHelper = null;
+    }
+}

package/{utils → lib}/dbHelper.ts

@@ -3,9 +3,10 @@
  * 提供数据库 CRUD 操作的封装
  */
 
+import { snakeCase } from 'es-toolkit/string';
 import { SqlBuilder } from './sqlBuilder.js';
-import { keysToCamel, arrayKeysToCamel, keysToSnake, fieldClear, convertBigIntFields, toSnakeCase } from './helper.js';
-import { Logger } from './logger.js';
+import { keysToCamel, arrayKeysToCamel, keysToSnake, fieldClear } from '../util.js';
+import { Logger } from '../lib/logger.js';
 import type { WhereConditions } from '../types/common.js';
 import type { BeflyContext } from '../types/befly.js';
 import type { QueryOptions, InsertOptions, UpdateOptions, DeleteOptions, ListResult, TransactionCallback } from '../types/database.js';
@@ -39,7 +40,7 @@ export class DbHelper {
             if (field === '*' || field.includes('(') || field.includes(' ')) {
                 return field;
             }
-            return toSnakeCase(field);
+            return snakeCase(field);
         });
     }
 
@@ -51,51 +52,10 @@ export class DbHelper {
         return orderBy.map((item) => {
             if (typeof item !== 'string' || !item.includes('#')) return item;
             const [field, direction] = item.split('#');
-            return `${toSnakeCase(field.trim())}#${direction.trim()}`;
+            return `${snakeCase(field.trim())}#${direction.trim()}`;
         });
     }
 
-    /**
-     * where 条件键名转下划线格式（私有方法，递归处理嵌套）
-     */
-    private whereKeysToSnake(where: any): any {
-        if (!where || typeof where !== 'object') return where;
-
-        // 处理数组（$or, $and 等）
-        if (Array.isArray(where)) {
-            return where.map((item) => this.whereKeysToSnake(item));
-        }
-
-        const result: any = {};
-        for (const [key, value] of Object.entries(where)) {
-            // 保留 $or, $and 等逻辑操作符
-            if (key === '$or' || key === '$and') {
-                result[key] = (value as any[]).map((item) => this.whereKeysToSnake(item));
-                continue;
-            }
-
-            // 处理带操作符的字段名（如 userId$gt）
-            if (key.includes('$')) {
-                const lastDollarIndex = key.lastIndexOf('$');
-                const fieldName = key.substring(0, lastDollarIndex);
-                const operator = key.substring(lastDollarIndex);
-                const snakeKey = toSnakeCase(fieldName) + operator;
-                result[snakeKey] = value;
-                continue;
-            }
-
-            // 普通字段：转换键名，递归处理值（支持嵌套对象）
-            const snakeKey = toSnakeCase(key);
-            if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
-                result[snakeKey] = this.whereKeysToSnake(value);
-            } else {
-                result[snakeKey] = value;
-            }
-        }
-
-        return result;
-    }
-
     /**
      * 统一的查询参数预处理方法
      */
@@ -103,7 +63,7 @@ export class DbHelper {
         const cleanWhere = this.cleanFields(options.where);
 
         return {
-            table: toSnakeCase(options.table),
+            table: snakeCase(options.table),
             fields: this.fieldsToSnake(options.fields || ['*']),
             where: this.whereKeysToSnake(cleanWhere),
             orderBy: this.orderByToSnake(options.orderBy || []),
@@ -138,6 +98,92 @@ export class DbHelper {
         return fieldClear(data || ({} as T), excludeValues, keepValues);
     }
 
+    /**
+     * 转换数据库 BIGINT 字段为数字类型（私有方法）
+     * 当 bigint: false 时，Bun SQL 会将大于 u32 的 BIGINT 返回为字符串，此方法将其转换为 number
+     *
+     * 转换规则：
+     * 1. 白名单中的字段会被转换
+     * 2. 所有以 'Id' 或 '_id' 结尾的字段会被自动转换
+     * 3. 所有以 'At' 或 '_at' 结尾的字段会被自动转换（时间戳字段）
+     * 4. 其他字段保持不变
+     */
+    private convertBigIntFields<T = any>(arr: Record<string, any>[], fields: string[] = ['id', 'pid', 'sort']): T[] {
+        if (!arr || !Array.isArray(arr)) return arr as T[];
+
+        return arr.map((item) => {
+            const converted = { ...item };
+
+            // 遍历对象的所有字段
+            for (const [key, value] of Object.entries(converted)) {
+                // 跳过 undefined 和 null
+                if (value === undefined || value === null) {
+                    continue;
+                }
+
+                // 判断是否需要转换：
+                // 1. 在白名单中
+                // 2. 以 'Id' 结尾（如 userId, roleId, categoryId）
+                // 3. 以 '_id' 结尾（如 user_id, role_id）
+                // 4. 以 'At' 结尾（如 createdAt, updatedAt）
+                // 5. 以 '_at' 结尾（如 created_at, updated_at）
+                const shouldConvert = fields.includes(key) || key.endsWith('Id') || key.endsWith('_id') || key.endsWith('At') || key.endsWith('_at');
+
+                if (shouldConvert && typeof value === 'string') {
+                    const num = Number(value);
+                    if (!isNaN(num)) {
+                        converted[key] = num;
+                    }
+                }
+                // number 类型保持不变（小于 u32 的值）
+            }
+
+            return converted as T;
+        }) as T[];
+    }
+
+    /**
+     * Where 条件键名转下划线格式（递归处理嵌套）（私有方法）
+     * 支持操作符字段（如 userId$gt）和逻辑操作符（$or, $and）
+     */
+    private whereKeysToSnake(where: any): any {
+        if (!where || typeof where !== 'object') return where;
+
+        // 处理数组（$or, $and 等）
+        if (Array.isArray(where)) {
+            return where.map((item) => this.whereKeysToSnake(item));
+        }
+
+        const result: any = {};
+        for (const [key, value] of Object.entries(where)) {
+            // 保留 $or, $and 等逻辑操作符
+            if (key === '$or' || key === '$and') {
+                result[key] = (value as any[]).map((item) => this.whereKeysToSnake(item));
+                continue;
+            }
+
+            // 处理带操作符的字段名（如 userId$gt）
+            if (key.includes('$')) {
+                const lastDollarIndex = key.lastIndexOf('$');
+                const fieldName = key.substring(0, lastDollarIndex);
+                const operator = key.substring(lastDollarIndex);
+                const snakeKey = snakeCase(fieldName) + operator;
+                result[snakeKey] = value;
+                continue;
+            }
+
+            // 普通字段：转换键名，递归处理值（支持嵌套对象）
+            const snakeKey = snakeCase(key);
+            if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+                result[snakeKey] = this.whereKeysToSnake(value);
+            } else {
+                result[snakeKey] = value;
+            }
+        }
+
+        return result;
+    }
+
     /**
      * 执行 SQL（使用 sql.unsafe，带慢查询日志）
      */
@@ -176,7 +222,7 @@ export class DbHelper {
      */
     async tableExists(tableName: string): Promise<boolean> {
         // 将表名转换为下划线格式
-        const snakeTableName = toSnakeCase(tableName);
+        const snakeTableName = snakeCase(tableName);
 
         const result = await this.executeWithConn('SELECT COUNT(*) as count FROM information_schema.TABLES WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ?', [snakeTableName]);
 
@@ -228,7 +274,7 @@ export class DbHelper {
         const camelRow = keysToCamel<T>(row);
 
         // 转换 BIGINT 字段（id, pid 等）为数字类型
-        return convertBigIntFields<T>([camelRow])[0];
+        return this.convertBigIntFields<T>([camelRow])[0];
     }
 
     /**
@@ -288,7 +334,7 @@ export class DbHelper {
 
         // 转换 BIGINT 字段（id, pid 等）为数字类型
         return {
-            lists: convertBigIntFields<T>(camelList),
+            lists: this.convertBigIntFields<T>(camelList),
             total: total,
             page: prepared.page,
             limit: prepared.limit,
@@ -335,7 +381,7 @@ export class DbHelper {
         const camelResult = arrayKeysToCamel<T>(result);
 
         // 转换 BIGINT 字段（id, pid 等）为数字类型
-        return convertBigIntFields<T>(camelResult);
+        return this.convertBigIntFields<T>(camelResult);
     }
 
     /**
@@ -349,7 +395,7 @@ export class DbHelper {
         const cleanData = this.cleanFields(data);
 
         // 转换表名：小驼峰 → 下划线
-        const snakeTable = toSnakeCase(table);
+        const snakeTable = snakeCase(table);
 
         // 处理数据（自动添加必要字段）
         // 字段名转换：小驼峰 → 下划线
@@ -405,7 +451,7 @@ export class DbHelper {
         }
 
         // 转换表名：小驼峰 → 下划线
-        const snakeTable = toSnakeCase(table);
+        const snakeTable = snakeCase(table);
 
         // 批量生成 ID（一次性从 Redis 获取 N 个 ID）
         const ids = await this.befly.redis.genTimeIDBatch(dataList.length);
@@ -459,7 +505,7 @@ export class DbHelper {
         const cleanWhere = this.cleanFields(where);
 
         // 转换表名：小驼峰 → 下划线
-        const snakeTable = toSnakeCase(table);
+        const snakeTable = snakeCase(table);
 
         // 字段名转换：小驼峰 → 下划线
         const snakeData = keysToSnake(cleanData);
@@ -507,7 +553,7 @@ export class DbHelper {
         const { table, where } = options;
 
         // 转换表名：小驼峰 → 下划线
-        const snakeTable = toSnakeCase(table);
+        const snakeTable = snakeCase(table);
 
         // 清理条件字段
         const cleanWhere = this.cleanFields(where);
@@ -666,8 +712,8 @@ export class DbHelper {
      */
     async increment(table: string, field: string, where: WhereConditions, value: number = 1): Promise<number> {
         // 转换表名和字段名：小驼峰 → 下划线
-        const snakeTable = toSnakeCase(table);
-        const snakeField = toSnakeCase(field);
+        const snakeTable = snakeCase(table);
+        const snakeField = snakeCase(field);
 
         // 验证表名格式（只允许字母、数字、下划线）
         if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(snakeTable)) {