befly 2.3.3 → 3.0.1

package/utils/logger.ts

@@ -0,0 +1,191 @@
+/**
+ * 日志系统 - TypeScript 版本
+ * 提供分级日志记录和文件管理功能
+ */
+
+import path from 'path';
+import { appendFile, stat } from 'node:fs/promises';
+import { formatDate } from './index.js';
+import { Colors } from './colors.js';
+import { Env } from '../config/env.js';
+import type { LogLevel } from '../types/common.js';
+
+/**
+ * 日志消息类型
+ */
+type LogMessage = string | number | boolean | null | undefined | Record<string, any> | any[];
+
+/**
+ * 日志器类
+ */
+export class Logger {
+    /** 日志目录 */
+    static logDir: string = Env.LOG_DIR || 'logs';
+
+    /** 单个日志文件最大大小（字节） */
+    static maxFileSize: number = Env.LOG_MAX_SIZE || 50 * 1024 * 1024; // 50MB
+
+    /** 当前使用的日志文件缓存 */
+    private static currentFiles: Map<string, string> = new Map();
+
+    /**
+     * 记录日志
+     * @param level - 日志级别
+     * @param message - 日志消息
+     */
+    static async log(level: LogLevel, message: LogMessage): Promise<void> {
+        // debug 日志特殊处理：仅当 LOG_DEBUG=1 时才记录
+        if (level === 'debug' && Env.LOG_DEBUG !== 1) return;
+
+        // 格式化消息
+        const timestamp = formatDate();
+        const colorMap = {
+            info: Colors.greenBright,
+            debug: Colors.cyanBright,
+            warn: Colors.yellowBright,
+            error: Colors.redBright
+        };
+
+        // 处理消息内容
+        let content = '';
+        if (typeof message === 'object' && message !== null && Object.keys(message).length > 0) {
+            content = JSON.stringify(message, null, 0).replace(/\\"/g, '"');
+        } else {
+            content = String(message);
+        }
+
+        // 带颜色的控制台消息
+        const coloredLevelStr = colorMap[level](level.toUpperCase().padStart(5));
+        const coloredMessage = `[${timestamp}] ${coloredLevelStr} - ${content}`;
+
+        // 控制台输出
+        if (Env.LOG_TO_CONSOLE === 1) {
+            console.log(coloredMessage);
+        }
+
+        // 文件输出（去除 ANSI 颜色代码）
+        const plainLevelStr = level.toUpperCase().padStart(5);
+        const plainMessage = `[${timestamp}] ${plainLevelStr} - ${content}`;
+        await this.writeToFile(plainMessage, level);
+    }
+
+    /**
+     * 写入日志文件
+     * @param message - 格式化后的消息
+     * @param level - 日志级别
+     */
+    static async writeToFile(message: string, level: LogLevel = 'info'): Promise<void> {
+        try {
+            // 确定文件前缀
+            const prefix = level === 'debug' ? 'debug' : new Date().toISOString().split('T')[0];
+
+            // 检查缓存的当前文件是否仍然可用
+            let currentLogFile = this.currentFiles.get(prefix);
+
+            if (currentLogFile) {
+                try {
+                    const stats = await stat(currentLogFile);
+                    if (stats.size >= this.maxFileSize) {
+                        this.currentFiles.delete(prefix);
+                        currentLogFile = undefined;
+                    }
+                } catch {
+                    this.currentFiles.delete(prefix);
+                    currentLogFile = undefined;
+                }
+            }
+
+            // 查找或创建新文件
+            if (!currentLogFile) {
+                const glob = new Bun.Glob(`${prefix}.*.log`);
+                const files = await Array.fromAsync(glob.scan(this.logDir));
+
+                // 按索引排序并查找可用文件
+                const getIndex = (f: string) => parseInt(f.match(/\.(\d+)\.log$/)?.[1] || '0');
+                files.sort((a, b) => getIndex(a) - getIndex(b));
+
+                let foundFile = false;
+                for (let i = files.length - 1; i >= 0; i--) {
+                    const filePath = path.join(this.logDir, files[i]);
+                    try {
+                        const stats = await stat(filePath);
+                        if (stats.size < this.maxFileSize) {
+                            currentLogFile = filePath;
+                            foundFile = true;
+                            break;
+                        }
+                    } catch {
+                        continue;
+                    }
+                }
+
+                // 没有可用文件，创建新文件
+                if (!foundFile) {
+                    const maxIndex = files.length > 0 ? Math.max(...files.map(getIndex)) : -1;
+                    currentLogFile = path.join(this.logDir, `${prefix}.${maxIndex + 1}.log`);
+                }
+
+                this.currentFiles.set(prefix, currentLogFile);
+            }
+
+            await appendFile(currentLogFile, message + '\n', 'utf8');
+        } catch (error: any) {
+            console.error('写入日志文件失败:', error?.message || error);
+        }
+    }
+
+    /**
+     * 记录错误日志
+     * @param name - 错误名称/位置
+     * @param error - 错误对象或消息
+     */
+    static async error(name: string, error?: any): Promise<void> {
+        if (!error) {
+            return this.log('error', name);
+        }
+
+        // 构建错误消息
+        const parts = [name];
+        if (error?.message || error?.stack) {
+            if (error.message) parts.push(error.message);
+            if (error.stack) parts.push('\n' + error.stack);
+        } else {
+            const errorStr = typeof error === 'object' ? JSON.stringify(error) : String(error);
+            parts.push(errorStr);
+        }
+
+        await this.log('error', parts.join(' - '));
+    }
+
+    /**
+     * 记录警告日志
+     * @param message - 日志消息
+     */
+    static async warn(message: LogMessage): Promise<void> {
+        await this.log('warn', message);
+    }
+
+    /**
+     * 记录信息日志
+     * @param message - 日志消息
+     */
+    static async info(message: LogMessage): Promise<void> {
+        await this.log('info', message);
+    }
+
+    /**
+     * 记录调试日志
+     * 受 LOG_DEBUG 环境变量控制，仅当 LOG_DEBUG=1 时才记录
+     * @param message - 日志消息
+     */
+    static async debug(message: LogMessage): Promise<void> {
+        await this.log('debug', message);
+    }
+
+    /**
+     * 清除文件缓存
+     */
+    static clearCache(): void {
+        this.currentFiles.clear();
+    }
+}

package/utils/redisHelper.ts

@@ -0,0 +1,321 @@
+/**
+ * Redis 助手 - TypeScript 版本
+ * 提供 Redis 操作的便捷方法
+ */
+
+import { RedisClient } from 'bun';
+import { Env } from '../config/env.js';
+import { Logger } from './logger.js';
+import { getRedis } from './database.js';
+
+/**
+ * Redis 键前缀
+ */
+const prefix = Env.REDIS_KEY_PREFIX ? `${Env.REDIS_KEY_PREFIX}:` : '';
+
+/**
+ * 获取 Redis 客户端
+ * @returns Redis 客户端实例
+ * @throws 如果客户端未初始化
+ */
+function getClient(): RedisClient {
+    const client = getRedis();
+    if (!client) {
+        throw new Error('Redis 客户端未初始化，请先调用 initDatabase() 或 initRedisOnly()');
+    }
+    return client;
+}
+
+/**
+ * Redis 助手对象
+ */
+export const RedisHelper = {
+    /**
+     * 设置对象到 Redis
+     * @param key - 键名
+     * @param obj - 对象
+     * @param ttl - 过期时间（秒）
+     * @returns 操作结果
+     */
+    async setObject<T = any>(key: string, obj: T, ttl: number | null = null): Promise<string | null> {
+        try {
+            const client = getClient();
+            const data = JSON.stringify(obj);
+            const pkey = `${prefix}${key}`;
+
+            if (ttl) {
+                return await client.setEx(pkey, ttl, data);
+            }
+            return await client.set(pkey, data);
+        } catch (error: any) {
+            Logger.error('Redis setObject 错误', error);
+            return null;
+        }
+    },
+
+    /**
+     * 从 Redis 获取对象
+     * @param key - 键名
+     * @returns 对象或 null
+     */
+    async getObject<T = any>(key: string): Promise<T | null> {
+        try {
+            const client = getClient();
+            const pkey = `${prefix}${key}`;
+            const data = await client.get(pkey);
+            return data ? JSON.parse(data) : null;
+        } catch (error: any) {
+            Logger.error('Redis getObject 错误', error);
+            return null;
+        }
+    },
+
+    /**
+     * 从 Redis 删除对象
+     * @param key - 键名
+     */
+    async delObject(key: string): Promise<void> {
+        try {
+            const client = getClient();
+            const pkey = `${prefix}${key}`;
+            await client.del(pkey);
+        } catch (error: any) {
+            Logger.error('Redis delObject 错误', error);
+        }
+    },
+
+    /**
+     * 生成基于时间的唯一 ID
+     * 格式: 秒级时间戳(10位) + 4位自增 = 14位纯数字
+     * 容量: 10000/秒 = 864,000,000/天
+     * 范围: 到 2286年9月
+     * @returns 唯一 ID (14位纯数字)
+     */
+    async genTimeID(): Promise<number> {
+        const client = getClient();
+        const timestamp = Math.floor(Date.now() / 1000); // 秒级时间戳
+        const key = `${prefix}time_id_counter:${timestamp}`;
+
+        const counter = await client.incr(key);
+        await client.expire(key, 1);
+
+        const counterSuffix = (counter % 10000).toString().padStart(4, '0');
+
+        return Number(`${timestamp}${counterSuffix}`);
+    },
+
+    /**
+     * 批量生成基于时间的唯一 ID
+     * 格式: 秒级时间戳(10位) + 4位自增 = 14位纯数字
+     * @param count - 需要生成的 ID 数量
+     * @returns ID 数组 (14位纯数字)
+     */
+    async genTimeIDBatch(count: number): Promise<number[]> {
+        if (count <= 0) {
+            return [];
+        }
+
+        // 限制单次批量生成数量（每秒最多10000个）
+        const MAX_BATCH_SIZE = 10000;
+        if (count > MAX_BATCH_SIZE) {
+            throw new Error(`批量大小 ${count} 超过最大限制 ${MAX_BATCH_SIZE}`);
+        }
+
+        const client = getClient();
+        const timestamp = Math.floor(Date.now() / 1000); // 秒级时间戳
+        const key = `${prefix}time_id_counter:${timestamp}`;
+
+        // 使用 INCRBY 一次性获取 N 个连续计数
+        const startCounter = await client.incrBy(key, count);
+        await client.expire(key, 1);
+
+        // 生成 ID 数组
+        const ids: number[] = [];
+        for (let i = 0; i < count; i++) {
+            const counter = startCounter - count + i + 1; // 计算每个 ID 的计数值
+            const counterSuffix = (counter % 10000).toString().padStart(4, '0');
+            ids.push(Number(`${timestamp}${counterSuffix}`));
+        }
+
+        return ids;
+    },
+
+    /**
+     * 设置字符串值
+     * @param key - 键名
+     * @param value - 值
+     * @param ttl - 过期时间（秒）
+     */
+    async setString(key: string, value: string, ttl: number | null = null): Promise<string | null> {
+        try {
+            const client = getClient();
+            const pkey = `${prefix}${key}`;
+            if (ttl) {
+                return await client.setEx(pkey, ttl, value);
+            }
+            return await client.set(pkey, value);
+        } catch (error: any) {
+            Logger.error('Redis setString 错误', error);
+            return null;
+        }
+    },
+
+    /**
+     * 获取字符串值
+     * @param key - 键名
+     */
+    async getString(key: string): Promise<string | null> {
+        try {
+            const client = getClient();
+            const pkey = `${prefix}${key}`;
+            return await client.get(pkey);
+        } catch (error: any) {
+            Logger.error('Redis getString 错误', error);
+            return null;
+        }
+    },
+
+    /**
+     * 检查键是否存在
+     * @param key - 键名
+     */
+    async exists(key: string): Promise<number> {
+        try {
+            const client = getClient();
+            const pkey = `${prefix}${key}`;
+            return await client.exists(pkey);
+        } catch (error: any) {
+            Logger.error('Redis exists 错误', error);
+            return 0;
+        }
+    },
+
+    /**
+     * 设置过期时间
+     * @param key - 键名
+     * @param seconds - 秒数
+     */
+    async expire(key: string, seconds: number): Promise<number> {
+        try {
+            const client = getClient();
+            const pkey = `${prefix}${key}`;
+            return await client.expire(pkey, seconds);
+        } catch (error: any) {
+            Logger.error('Redis expire 错误', error);
+            return 0;
+        }
+    },
+
+    /**
+     * 获取剩余过期时间
+     * @param key - 键名
+     */
+    async ttl(key: string): Promise<number> {
+        try {
+            const client = getClient();
+            const pkey = `${prefix}${key}`;
+            return await client.ttl(pkey);
+        } catch (error: any) {
+            Logger.error('Redis ttl 错误', error);
+            return -1;
+        }
+    },
+
+    /**
+     * 向 Set 中添加一个或多个成员
+     * @param key - 键名
+     * @param members - 成员数组
+     * @returns 成功添加的成员数量
+     */
+    async sadd(key: string, members: string[]): Promise<number> {
+        try {
+            if (members.length === 0) return 0;
+
+            const client = getClient();
+            const pkey = `${prefix}${key}`;
+            return await client.sadd(pkey, ...members);
+        } catch (error: any) {
+            Logger.error('Redis sadd 错误', error);
+            return 0;
+        }
+    },
+
+    /**
+     * 判断成员是否在 Set 中
+     * @param key - 键名
+     * @param member - 成员
+     * @returns 1 表示存在，0 表示不存在
+     */
+    async sismember(key: string, member: string): Promise<number> {
+        try {
+            const client = getClient();
+            const pkey = `${prefix}${key}`;
+            return await client.sismember(pkey, member);
+        } catch (error: any) {
+            Logger.error('Redis sismember 错误', error);
+            return 0;
+        }
+    },
+
+    /**
+     * 获取 Set 的成员数量
+     * @param key - 键名
+     * @returns 成员数量
+     */
+    async scard(key: string): Promise<number> {
+        try {
+            const client = getClient();
+            const pkey = `${prefix}${key}`;
+            return await client.scard(pkey);
+        } catch (error: any) {
+            Logger.error('Redis scard 错误', error);
+            return 0;
+        }
+    },
+
+    /**
+     * 获取 Set 的所有成员
+     * @param key - 键名
+     * @returns 成员数组
+     */
+    async smembers(key: string): Promise<string[]> {
+        try {
+            const client = getClient();
+            const pkey = `${prefix}${key}`;
+            return await client.smembers(pkey);
+        } catch (error: any) {
+            Logger.error('Redis smembers 错误', error);
+            return [];
+        }
+    },
+
+    /**
+     * 删除键
+     * @param key - 键名
+     * @returns 删除的键数量
+     */
+    async del(key: string): Promise<number> {
+        try {
+            const client = getClient();
+            const pkey = `${prefix}${key}`;
+            return await client.del(pkey);
+        } catch (error: any) {
+            Logger.error('Redis del 错误', error);
+            return 0;
+        }
+    },
+
+    /**
+     * 测试 Redis 连接
+     * @returns ping 响应结果
+     */
+    async ping(): Promise<string> {
+        try {
+            const client = getClient();
+            return await client.ping();
+        } catch (error: any) {
+            Logger.error('Redis ping 错误', error);
+            throw error;
+        }
+    }
+};

package/utils/requestContext.ts

@@ -0,0 +1,167 @@
+/**
+ * 请求上下文类
+ * 提供统一的请求数据访问接口和类型安全
+ */
+
+/**
+ * 标准请求上下文类
+ */
+export class RequestContext {
+    /** 原始请求对象 */
+    public readonly request: Request;
+
+    /** 请求开始时间（毫秒） */
+    public readonly startTime: number;
+
+    /** 请求体参数 (GET/POST 解析后的数据) */
+    public body: Record<string, any> = {};
+
+    /** 用户信息 (认证后填充) */
+    public user: Record<string, any> = {};
+
+    /** 自定义状态 (用于在中间件间传递数据) */
+    public state: Record<string, any> = {};
+
+    /** 响应数据 (由 handler 设置) */
+    public response?: any;
+
+    constructor(req: Request) {
+        this.request = req;
+        this.startTime = Date.now();
+    }
+
+    // ========== 便捷访问器 ==========
+
+    /**
+     * 获取请求方法
+     */
+    get method(): string {
+        return this.request.method;
+    }
+
+    /**
+     * 获取请求 URL
+     */
+    get url(): string {
+        return this.request.url;
+    }
+
+    /**
+     * 获取请求头对象
+     */
+    get headers(): Headers {
+        return this.request.headers;
+    }
+
+    /**
+     * 获取客户端 IP 地址
+     */
+    get ip(): string | null {
+        return this.request.headers.get('x-forwarded-for') || this.request.headers.get('x-real-ip') || this.request.headers.get('cf-connecting-ip') || null;
+    }
+
+    /**
+     * 获取 User-Agent
+     */
+    get userAgent(): string | null {
+        return this.request.headers.get('user-agent');
+    }
+
+    /**
+     * 获取 Content-Type
+     */
+    get contentType(): string | null {
+        return this.request.headers.get('content-type');
+    }
+
+    // ========== 工具方法 ==========
+
+    /**
+     * 获取请求头
+     * @param name - 请求头名称
+     */
+    header(name: string): string | null {
+        return this.request.headers.get(name);
+    }
+
+    /**
+     * 获取参数值
+     * @param key - 参数键名
+     */
+    get(key: string): any {
+        return this.body[key];
+    }
+
+    /**
+     * 设置参数值
+     * @param key - 参数键名
+     * @param value - 参数值
+     */
+    set(key: string, value: any): void {
+        this.body[key] = value;
+    }
+
+    /**
+     * 检查参数是否存在
+     * @param key - 参数键名
+     */
+    has(key: string): boolean {
+        return key in this.body;
+    }
+
+    /**
+     * 获取所有参数
+     */
+    all(): Record<string, any> {
+        return { ...this.body };
+    }
+
+    /**
+     * 计算请求耗时（毫秒）
+     */
+    getElapsedTime(): number {
+        return Date.now() - this.startTime;
+    }
+
+    /**
+     * 获取格式化的请求信息（用于日志）
+     */
+    getRequestInfo(): Record<string, any> {
+        return {
+            method: this.method,
+            url: this.url,
+            ip: this.ip,
+            userAgent: this.userAgent,
+            elapsedTime: this.getElapsedTime()
+        };
+    }
+
+    /**
+     * 设置响应数据
+     * @param data - 响应数据
+     */
+    setResponse(data: any): void {
+        this.response = data;
+    }
+
+    /**
+     * 判断用户是否已登录
+     */
+    isAuthenticated(): boolean {
+        return !!this.user.id;
+    }
+
+    /**
+     * 获取用户 ID
+     */
+    getUserId(): number | null {
+        return this.user.id || null;
+    }
+
+    /**
+     * 获取用户角色
+     */
+    getUserRole(): string | null {
+        return this.user.role || this.user.roleType || null;
+    }
+}