befly 2.3.3 → 3.0.1

package/config/env.ts

@@ -0,0 +1,218 @@
+/**
+ * 环境变量配置 - TypeScript 版本
+ * 类型化所有环境变量
+ */
+
+/**
+ * 环境变量配置接口
+ */
+export interface EnvConfig {
+    // ========== 项目配置 ==========
+    /** 项目模式：development | production | test */
+    NODE_ENV: string;
+    /** 应用名称 */
+    APP_NAME: string;
+    /** MD5 加密盐 */
+    MD5_SALT: string;
+    /** 监听端口 */
+    APP_PORT: number;
+    /** 监听主机 */
+    APP_HOST: string;
+    /** 超级管理员密码 */
+    DEV_PASSWORD: string;
+    /** 请求体大小限制（字节） */
+    BODY_LIMIT: number;
+    /** 是否进行参数验证 */
+    PARAMS_CHECK: string;
+
+    // ========== 日志配置 ==========
+    /** debug日志开关：0 | 1 */
+    LOG_DEBUG: number;
+    /** 日志排除字段（逗号分隔） */
+    LOG_EXCLUDE_FIELDS: string;
+    /** 日志目录 */
+    LOG_DIR: string;
+    /** 是否输出到控制台：0 | 1 */
+    LOG_TO_CONSOLE: number;
+    /** 日志文件最大大小（字节） */
+    LOG_MAX_SIZE: number;
+
+    // ========== 时区配置 ==========
+    /** 时区：Asia/Shanghai */
+    TZ: string;
+
+    // ========== 数据库配置 ==========
+    /** 是否启用数据库：0 | 1 */
+    DB_ENABLE: number;
+    /** 数据库类型：sqlite | mysql | postgresql */
+    DB_TYPE: string;
+    /** 数据库主机 */
+    DB_HOST: string;
+    /** 数据库端口 */
+    DB_PORT: number;
+    /** 数据库用户名 */
+    DB_USER: string;
+    /** 数据库密码 */
+    DB_PASS: string;
+    /** 数据库名称 */
+    DB_NAME: string;
+    /** 是否启用调试：0 | 1 */
+    DB_DEBUG: number;
+    /** 连接池最大连接数 */
+    DB_POOL_MAX: number;
+
+    // ========== Redis 配置 ==========
+    /** 是否启用 Redis：0 | 1 */
+    REDIS_ENABLE: number;
+    /** Redis 主机 */
+    REDIS_HOST: string;
+    /** Redis 端口 */
+    REDIS_PORT: number;
+    /** Redis 用户名 */
+    REDIS_USERNAME: string;
+    /** Redis 密码 */
+    REDIS_PASSWORD: string;
+    /** Redis 数据库索引 */
+    REDIS_DB: number;
+    /** Redis 键前缀 */
+    REDIS_KEY_PREFIX: string;
+
+    // ========== JWT 配置 ==========
+    /** JWT 密钥 */
+    JWT_SECRET: string;
+    /** JWT 过期时间：7d | 30d | 1h */
+    JWT_EXPIRES_IN: string;
+    /** JWT 算法：HS256 | HS384 | HS512 */
+    JWT_ALGORITHM: string;
+
+    // ========== CORS 配置 ==========
+    /** 允许的来源 */
+    ALLOWED_ORIGIN: string;
+    /** 允许的方法 */
+    ALLOWED_METHODS: string;
+    /** 允许的头部 */
+    ALLOWED_HEADERS: string;
+    /** 暴露的头部 */
+    EXPOSE_HEADERS: string;
+    /** 预检请求缓存时间（秒） */
+    MAX_AGE: number;
+    /** 是否允许凭证 */
+    ALLOW_CREDENTIALS: string;
+
+    // ========== 邮件配置 ==========
+    /** 邮件服务器主机 */
+    MAIL_HOST: string;
+    /** 邮件服务器端口 */
+    MAIL_PORT: number;
+    /** 是否使用连接池 */
+    MAIL_POOL: string;
+    /** 是否使用 SSL */
+    MAIL_SECURE: string;
+    /** 邮件用户名 */
+    MAIL_USER: string;
+    /** 邮件密码 */
+    MAIL_PASS: string;
+    /** 发件人名称 */
+    MAIL_SENDER: string;
+    /** 发件人地址 */
+    MAIL_ADDRESS: string;
+
+    // ========== 同步脚本配置 ==========
+    /** 是否合并 ALTER 语句 */
+    SYNC_MERGE_ALTER: string;
+    /** 是否同步在线索引 */
+    SYNC_ONLINE_INDEX: string;
+    /** 是否禁止字段缩小 */
+    SYNC_DISALLOW_SHRINK: string;
+    /** 是否允许类型变更 */
+    SYNC_ALLOW_TYPE_CHANGE: string;
+}
+
+/**
+ * 获取环境变量值（带默认值）
+ */
+const getEnv = (key: string, defaultValue: string = ''): string => {
+    return process.env[key] || defaultValue;
+};
+
+/**
+ * 获取数字类型环境变量
+ */
+const getEnvNumber = (key: string, defaultValue: number = 0): number => {
+    const value = process.env[key];
+    return value ? Number(value) : defaultValue;
+};
+
+/**
+ * 环境变量配置对象
+ */
+export const Env: EnvConfig = {
+    // ========== 项目配置 ==========
+    NODE_ENV: getEnv('NODE_ENV', 'development'),
+    APP_NAME: getEnv('APP_NAME', 'befly'),
+    MD5_SALT: getEnv('MD5_SALT', 'befly'),
+    APP_PORT: getEnvNumber('APP_PORT', 3000),
+    APP_HOST: getEnv('APP_HOST', '0.0.0.0'),
+    DEV_PASSWORD: getEnv('DEV_PASSWORD', ''),
+    BODY_LIMIT: getEnvNumber('BODY_LIMIT', 10485760), // 10MB
+    PARAMS_CHECK: getEnv('PARAMS_CHECK', 'true'),
+
+    // ========== 日志配置 ==========
+    LOG_DEBUG: getEnvNumber('LOG_DEBUG', 0),
+    LOG_EXCLUDE_FIELDS: getEnv('LOG_EXCLUDE_FIELDS', 'password,token,secret'),
+    LOG_DIR: getEnv('LOG_DIR', './logs'),
+    LOG_TO_CONSOLE: getEnvNumber('LOG_TO_CONSOLE', 1),
+    LOG_MAX_SIZE: getEnvNumber('LOG_MAX_SIZE', 10485760), // 10MB
+
+    // ========== 时区配置 ==========
+    TZ: getEnv('TZ', 'Asia/Shanghai'),
+
+    // ========== 数据库配置 ==========
+    DB_ENABLE: getEnvNumber('DB_ENABLE', 1),
+    DB_TYPE: getEnv('DB_TYPE', 'mysql'),
+    DB_HOST: getEnv('DB_HOST', 'localhost'),
+    DB_PORT: getEnvNumber('DB_PORT', 3306),
+    DB_USER: getEnv('DB_USER', 'root'),
+    DB_PASS: getEnv('DB_PASS', ''),
+    DB_NAME: getEnv('DB_NAME', 'befly'),
+    DB_DEBUG: getEnvNumber('DB_DEBUG', 0),
+    DB_POOL_MAX: getEnvNumber('DB_POOL_MAX', 10),
+
+    // ========== Redis 配置 ==========
+    REDIS_ENABLE: getEnvNumber('REDIS_ENABLE', 1),
+    REDIS_HOST: getEnv('REDIS_HOST', 'localhost'),
+    REDIS_PORT: getEnvNumber('REDIS_PORT', 6379),
+    REDIS_USERNAME: getEnv('REDIS_USERNAME', ''),
+    REDIS_PASSWORD: getEnv('REDIS_PASSWORD', ''),
+    REDIS_DB: getEnvNumber('REDIS_DB', 0),
+    REDIS_KEY_PREFIX: getEnv('REDIS_KEY_PREFIX', 'befly'),
+
+    // ========== JWT 配置 ==========
+    JWT_SECRET: getEnv('JWT_SECRET', 'befly-secret'),
+    JWT_EXPIRES_IN: getEnv('JWT_EXPIRES_IN', '7d'),
+    JWT_ALGORITHM: getEnv('JWT_ALGORITHM', 'HS256'),
+
+    // ========== CORS 配置 ==========
+    ALLOWED_ORIGIN: getEnv('ALLOWED_ORIGIN', '*'),
+    ALLOWED_METHODS: getEnv('ALLOWED_METHODS', 'GET, POST, PUT, DELETE, OPTIONS'),
+    ALLOWED_HEADERS: getEnv('ALLOWED_HEADERS', 'Content-Type, Authorization, authorization, token'),
+    EXPOSE_HEADERS: getEnv('EXPOSE_HEADERS', 'Content-Range, X-Content-Range, Authorization, authorization, token'),
+    MAX_AGE: getEnvNumber('MAX_AGE', 86400),
+    ALLOW_CREDENTIALS: getEnv('ALLOW_CREDENTIALS', 'true'),
+
+    // ========== 邮件配置 ==========
+    MAIL_HOST: getEnv('MAIL_HOST', ''),
+    MAIL_PORT: getEnvNumber('MAIL_PORT', 587),
+    MAIL_POOL: getEnv('MAIL_POOL', 'true'),
+    MAIL_SECURE: getEnv('MAIL_SECURE', 'false'),
+    MAIL_USER: getEnv('MAIL_USER', ''),
+    MAIL_PASS: getEnv('MAIL_PASS', ''),
+    MAIL_SENDER: getEnv('MAIL_SENDER', ''),
+    MAIL_ADDRESS: getEnv('MAIL_ADDRESS', ''),
+
+    // ========== 同步脚本配置 ==========
+    SYNC_MERGE_ALTER: getEnv('SYNC_MERGE_ALTER', 'false'),
+    SYNC_ONLINE_INDEX: getEnv('SYNC_ONLINE_INDEX', 'false'),
+    SYNC_DISALLOW_SHRINK: getEnv('SYNC_DISALLOW_SHRINK', 'true'),
+    SYNC_ALLOW_TYPE_CHANGE: getEnv('SYNC_ALLOW_TYPE_CHANGE', 'false')
+};

package/config/fields.ts

@@ -0,0 +1,55 @@
+/**
+ * 通用字段定义
+ *
+ * 用于在 API 和表定义中复用常见字段规则
+ *
+ * 格式：`字段标签|数据类型|最小值|最大值|默认值|是否必填|正则表达式`
+ *
+ * 说明：
+ * - 字段标签：用于显示的中文名称
+ * - 数据类型：string、number、boolean、array_string、array_text 等
+ * - 最小值：string 类型表示最小长度，number 类型表示最小数值，array 类型表示最小元素个数
+ * - 最大值：string 类型表示最大长度，number 类型表示最大数值，array 类型表示最大元素个数
+ * - 默认值：字段的默认值，无默认值时填 null
+ * - 是否必填：0 表示非必填，1 表示必填
+ * - 正则表达式：用于验证字段值的正则表达式，无验证时填 null
+ *
+ * 类型说明：
+ * - array_string: 短数组，存储为 VARCHAR，建议设置 max 限制（如 0-100）
+ * - array_text: 长数组，存储为 MEDIUMTEXT，min/max 可设为 null 表示不限制
+ *
+ * 正则表达式别名：
+ * - 使用 @ 前缀可以引用内置正则表达式别名，例如：
+ *   - @number: 纯数字
+ *   - @alphanumeric: 字母+数字
+ *   - @email: 邮箱格式
+ *   - @phone: 中国手机号
+ *   - @chinese: 纯中文
+ * - 完整别名列表见 config/regexAliases.ts
+ *
+ * 示例：
+ * - '用户ID|array_text|null|null|null|0|@number' - 数字数组
+ * - '标签|array_string|0|50|null|0|@alphanumeric' - 字母数字数组
+ */
+
+export const Fields = {
+    _id: 'ID|number|1|null|null|1|null',
+    email: '邮箱|string|5|100|null|1|^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$',
+    phone: '手机号|string|11|11|null|1|^1[3-9]\\d{9}$',
+    page: '页码|number|1|9999|1|0|null',
+    limit: '每页数量|number|1|100|10|0|null',
+    title: '标题|string|1|200|null|0|null',
+    description: '描述|string|0|500|null|0|null',
+    keyword: '关键词|string|1|50|null|1|null',
+    keywords: '关键词列表|array_string|0|50|null|0|null',
+    enabled: '启用状态|number|0|1|1|0|^(0|1)$',
+    date: '日期|string|10|10|null|0|^\\d{4}-\\d{2}-\\d{2}$',
+    datetime: '日期时间|string|19|25|null|0|^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}',
+    filename: '文件名|string|1|255|null|0|null',
+    url: '网址|string|5|500|null|0|^https?://',
+    tag: '标签|array_string|0|10|null|0|null',
+    startTime: '开始时间|number|0|9999999999999|null|0|null',
+    endTime: '结束时间|number|0|9999999999999|null|0|null'
+} as const;
+
+export default Fields;

package/config/regexAliases.ts

@@ -0,0 +1,51 @@
+/**
+ * 内置正则表达式别名
+ *
+ * 使用方式：在字段定义的 regex 位置使用 @别名 格式
+ * 例如：'字段名|array_text|null|null|null|0|@number'
+ */
+
+export const RegexAliases = {
+    // 数字类型
+    number: '^\\d+$', // 纯数字
+    integer: '^-?\\d+$', // 整数（含负数）
+    float: '^-?\\d+(\\.\\d+)?$', // 浮点数
+    positive: '^[1-9]\\d*$', // 正整数（不含0）
+
+    // 字符串类型
+    word: '^[a-zA-Z]+$', // 纯字母
+    alphanumeric: '^[a-zA-Z0-9]+$', // 字母+数字
+    alphanumeric_: '^[a-zA-Z0-9_]+$', // 字母+数字+下划线
+    lowercase: '^[a-z]+$', // 小写字母
+    uppercase: '^[A-Z]+$', // 大写字母
+
+    // 中文
+    chinese: '^[\\u4e00-\\u9fa5]+$', // 纯中文
+    chinese_word: '^[\\u4e00-\\u9fa5a-zA-Z]+$', // 中文+字母
+
+    // 常用格式
+    email: '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$', // 邮箱
+    phone: '^1[3-9]\\d{9}$', // 中国手机号
+    url: '^https?://', // URL
+    ip: '^((25[0-5]|2[0-4]\\d|[01]?\\d\\d?)\\.){3}(25[0-5]|2[0-4]\\d|[01]?\\d\\d?)$', // IPv4
+
+    // 特殊格式
+    uuid: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$', // UUID
+    hex: '^[0-9a-fA-F]+$', // 十六进制
+    base64: '^[A-Za-z0-9+/=]+$', // Base64
+
+    // 日期时间
+    date: '^\\d{4}-\\d{2}-\\d{2}$', // YYYY-MM-DD
+    time: '^\\d{2}:\\d{2}:\\d{2}$', // HH:MM:SS
+    datetime: '^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}', // ISO 8601
+
+    // 代码相关
+    variable: '^[a-zA-Z_][a-zA-Z0-9_]*$', // 变量名
+    constant: '^[A-Z][A-Z0-9_]*$', // 常量名（大写）
+
+    // 空值
+    empty: '^$', // 空字符串
+    notempty: '.+' // 非空
+} as const;
+
+export type RegexAliasName = keyof typeof RegexAliases;

package/config/reserved.ts

@@ -0,0 +1,96 @@
+/**
+ * 核心保留名称配置
+ * 定义框架保留的资源名称，防止用户和 addon 使用
+ */
+
+/**
+ * 保留名称配置
+ */
+export const RESERVED_NAMES = {
+    /**
+     * 核心表前缀（禁止用户使用）
+     */
+    tablePrefix: ['sys_'],
+
+    /**
+     * 核心 API 路由前缀（禁止用户使用）
+     */
+    apiRoutes: ['/api/health', '/api/tool'],
+
+    /**
+     * 核心插件名（禁止用户使用）
+     */
+    plugins: ['db', 'logger', 'redis', 'tool'],
+
+    /**
+     * 禁止用作 addon 名称
+     */
+    addonNames: ['app', 'api']
+} as const;
+
+/**
+ * 检测表名是否使用了保留前缀
+ */
+export function isReservedTableName(tableName: string): boolean {
+    return RESERVED_NAMES.tablePrefix.some((prefix) => tableName.startsWith(prefix));
+}
+
+/**
+ * 检测 API 路由是否使用了保留路径
+ */
+export function isReservedRoute(route: string): boolean {
+    // 移除方法前缀（如 POST/GET）
+    const path = route.replace(/^(GET|POST|PUT|DELETE|PATCH|OPTIONS|HEAD)\//i, '/');
+    return RESERVED_NAMES.apiRoutes.some((reserved) => path.startsWith(reserved));
+}
+
+/**
+ * 检测插件名是否使用了保留名称
+ */
+export function isReservedPluginName(pluginName: string): boolean {
+    // 检测核心插件名
+    if (RESERVED_NAMES.plugins.includes(pluginName)) {
+        return true;
+    }
+    // 检测是否使用点号命名空间但前缀是保留名称
+    if (pluginName.includes('.')) {
+        const prefix = pluginName.split('.')[0];
+        return RESERVED_NAMES.plugins.includes(prefix);
+    }
+    return false;
+}
+
+/**
+ * 检测 addon 名称是否使用了保留名称
+ */
+export function isReservedAddonName(addonName: string): boolean {
+    return RESERVED_NAMES.addonNames.includes(addonName.toLowerCase());
+}
+
+/**
+ * 获取保留前缀列表（用于错误提示）
+ */
+export function getReservedTablePrefixes(): string[] {
+    return [...RESERVED_NAMES.tablePrefix];
+}
+
+/**
+ * 获取保留路由列表（用于错误提示）
+ */
+export function getReservedRoutes(): string[] {
+    return [...RESERVED_NAMES.apiRoutes];
+}
+
+/**
+ * 获取保留插件名列表（用于错误提示）
+ */
+export function getReservedPlugins(): string[] {
+    return [...RESERVED_NAMES.plugins];
+}
+
+/**
+ * 获取保留 addon 名称列表（用于错误提示）
+ */
+export function getReservedAddonNames(): string[] {
+    return [...RESERVED_NAMES.addonNames];
+}

package/main.ts

@@ -0,0 +1,47 @@
+/**
+ * Befly 框架主入口文件
+ * 提供简洁的框架接口，核心逻辑已提取到 lifecycle 层
+ */
+
+import { Env } from './config/env.js';
+import { Fields } from './config/fields.js';
+import { Yes, No, cleanData } from './utils/index.js';
+import { Logger } from './utils/logger.js';
+import { Jwt } from './utils/jwt.js';
+import { Validator } from './utils/validate.js';
+import { Crypto2 } from './utils/crypto.js';
+import { DbHelper } from './utils/dbHelper.js';
+import { createSqlClient, getRedis, getSql, getDbHelper, initDatabase, closeDatabase } from './utils/database.js';
+import { RedisHelper } from './utils/redisHelper.js';
+import { Lifecycle } from './lifecycle/lifecycle.js';
+
+import type { Server } from 'bun';
+import type { BeflyContext, BeflyOptions } from './types/befly.js';
+
+/**
+ * Befly 框架核心类
+ * 职责：管理应用上下文和生命周期
+ */
+export class Befly {
+    /** 生命周期管理器 */
+    private lifecycle: Lifecycle;
+
+    /** 应用上下文 */
+    public appContext: BeflyContext;
+
+    constructor(options: BeflyOptions = {}) {
+        this.lifecycle = new Lifecycle(options);
+        this.appContext = {};
+    }
+
+    /**
+     * 启动服务器
+     * @param callback - 启动完成后的回调函数
+     */
+    async listen(callback?: (server: Server) => void): Promise<void> {
+        await this.lifecycle.start(this.appContext, callback);
+    }
+}
+
+// 核心类和工具导出（只导出运行时代码，不导出类型）
+export { Env, Fields, Jwt, Validator, Crypto2, Logger, Yes, No, cleanData, DbHelper, createSqlClient, RedisHelper, getRedis, getSql, getDbHelper, initDatabase, closeDatabase };

package/package.json

@@ -1,42 +1,50 @@
 {
     "name": "befly",
-    "version": "2.3.3",
-    "description": "Befly - 为 Bun 专属打造的 API 接口框架核心引擎",
+    "version": "3.0.1",
+    "description": "Befly - 为 Bun 专属打造的 TypeScript API 接口框架核心引擎",
     "type": "module",
     "private": false,
     "publishConfig": {
         "access": "public",
         "registry": "https://registry.npmjs.org"
     },
-    "main": "main.js",
+    "main": "main.ts",
+    "types": "./types/index.d.ts",
     "exports": {
-        ".": "./main.js"
+        ".": {
+            "default": "./main.ts"
+        },
+        "./types": {
+            "types": "./types/index.d.ts",
+            "default": "./types/index.d.ts"
+        }
     },
-    "bin": {
-        "befly": "./bin/befly.js"
+    "scripts": {
+        "bundler": "bun build ./main.ts --outfile ./main.single.ts --minify --target bun"
     },
-    "scripts": {},
     "keywords": [
         "bun",
         "api",
         "framework",
         "core",
+        "typescript",
         "javascript",
         "backend",
         "rest",
-        "http"
+        "http",
+        "type-safe"
     ],
     "author": "chensuiyi <bimostyle@qq.com>",
     "homepage": "https://chensuiyi.me",
     "license": "Apache-2.0",
     "files": [
-        "bin/",
         "apis/",
         "checks/",
         "config/",
         "plugins/",
         "scripts/",
         "tables/",
+        "types/",
         "utils/",
         ".gitignore",
         ".npmignore",
@@ -46,10 +54,17 @@
         ".prettierignore",
         ".prettierrc",
         "bunfig.toml",
+        "tsconfig.json",
         "LICENSE",
+        "main.ts",
         "main.js",
+        "system.ts",
         "system.js",
         "package.json",
         "README.md"
-    ]
-}
+    ],
+    "engines": {
+        "bun": ">=1.3.0"
+    },
+    "gitHead": "f96bac1a1c829e265284a6f619da680fffd1a075"
+}

package/plugins/db.ts

@@ -0,0 +1,60 @@
+/**
+ * 数据库插件 - TypeScript 版本
+ * 初始化数据库连接和 SQL 管理器
+ */
+
+import { Env } from '../config/env.js';
+import { Logger } from '../utils/logger.js';
+import { createSqlClient } from '../utils/database.js';
+import { DbHelper } from '../utils/dbHelper.js';
+import type { Plugin } from '../types/plugin.js';
+import type { BeflyContext } from '../types/befly.js';
+
+/**
+ * 数据库插件
+ */
+const dbPlugin: Plugin = {
+    name: '_db',
+    after: ['_redis'],
+
+    async onInit(befly: BeflyContext): Promise<DbHelper | Record<string, never>> {
+        let sql: any = null;
+
+        try {
+            if (Env.DB_ENABLE === 1) {
+                // 创建 Bun SQL 客户端（内置连接池），并确保连接验证成功后再继续
+                // 从环境变量读取连接超时配置
+                const connectionTimeout = process.env.DB_CONNECTION_TIMEOUT ? parseInt(process.env.DB_CONNECTION_TIMEOUT) : 5000;
+
+                sql = await createSqlClient({
+                    connectionTimeout
+                });
+
+                // 创建数据库管理器实例，直接传入 sql 对象
+                const dbManager = new DbHelper(befly, sql);
+
+                Logger.info('数据库插件初始化成功');
+                return dbManager;
+            } else {
+                Logger.warn('数据库未启用（DB_ENABLE≠1），跳过初始化');
+                return {};
+            }
+        } catch (error: any) {
+            Logger.error('数据库初始化失败', error);
+
+            // 清理资源
+            if (sql) {
+                try {
+                    await sql.close();
+                } catch (cleanupError: any) {
+                    Logger.error('清理连接池失败:', cleanupError);
+                }
+            }
+
+            // 插件内禁止直接退出进程，抛出异常交由主流程统一处理
+            throw error;
+        }
+    }
+};
+
+export default dbPlugin;

package/plugins/logger.ts

@@ -0,0 +1,28 @@
+/**
+ * 日志插件 - TypeScript 版本
+ * 提供全局日志功能
+ */
+
+import { Logger } from '../utils/logger.js';
+import type { Plugin } from '../types/plugin.js';
+import type { BeflyContext } from '../types/befly.js';
+
+/**
+ * 日志插件
+ */
+const loggerPlugin: Plugin = {
+    name: '_logger',
+    after: [],
+
+    async onInit(befly: BeflyContext): Promise<typeof Logger> {
+        try {
+            Logger.info('日志插件初始化成功');
+            return Logger;
+        } catch (error: any) {
+            // 插件内禁止直接退出进程，抛出异常交由主流程统一处理
+            throw error;
+        }
+    }
+};
+
+export default loggerPlugin;

package/plugins/redis.ts

@@ -0,0 +1,47 @@
+/**
+ * Redis 插件 - TypeScript 版本
+ * 初始化 Redis 连接和助手工具
+ */
+
+import { Env } from '../config/env.js';
+import { Logger } from '../utils/logger.js';
+import { RedisHelper } from '../utils/redisHelper.js';
+import { initRedisOnly } from '../utils/database.js';
+import type { Plugin } from '../types/plugin.js';
+import type { BeflyContext } from '../types/befly.js';
+
+/**
+ * Redis 插件
+ */
+const redisPlugin: Plugin = {
+    name: '_redis',
+    after: ['_logger'],
+
+    async onInit(befly: BeflyContext): Promise<typeof RedisHelper | Record<string, never>> {
+        try {
+            if (Env.REDIS_ENABLE === 1) {
+                // 初始化 Redis 客户端（统一使用 database.ts 的连接管理）
+                await initRedisOnly();
+
+                Logger.info('Redis 插件初始化成功', {
+                    host: Env.REDIS_HOST,
+                    port: Env.REDIS_PORT,
+                    db: Env.REDIS_DB
+                });
+
+                // 返回工具对象，向下游以相同 API 暴露
+                return RedisHelper;
+            } else {
+                Logger.warn('Redis 未启用，跳过初始化');
+                return {};
+            }
+        } catch (error: any) {
+            Logger.error('Redis 初始化失败', error);
+
+            // 插件内禁止直接退出进程，抛出异常交由主流程统一处理
+            throw error;
+        }
+    }
+};
+
+export default redisPlugin;