befly 2.3.2 → 3.0.0

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 | info | warn | error */
+    LOG_LEVEL: string;
+    /** 日志排除字段（逗号分隔） */
+    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_LEVEL: getEnv('LOG_LEVEL', 'info'),
+    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/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: ['core', 'system', 'admin', 'sys', 'befly', 'app', 'api', 'config', 'utils', 'types']
+} 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,101 @@
+/**
+ * Befly 框架主入口文件 - TypeScript 版本
+ * 提供完整的框架功能：检查系统、加载插件、加载 API、启动 HTTP 服务器
+ */
+
+import { Env } from './config/env.js';
+import { Api } from './utils/api.js';
+import { Yes, No } 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 { calcPerfTime } from './utils/index.js';
+import { scanAddons, hasAddonDir } from './utils/addonHelper.js';
+import { Checker } from './lifecycle/checker.js';
+import { Loader } from './lifecycle/loader.js';
+import { Bootstrap } from './lifecycle/bootstrap.js';
+
+import type { Server } from 'bun';
+import type { Plugin } from './types/plugin.js';
+import type { ApiRoute, ApiHandler } from './types/api.js';
+import type { BeflyContext, BeflyOptions, RequestContext } from './types/befly.js';
+
+/**
+ * Befly 框架核心类
+ */
+export class Befly {
+    /** API 路由映射表 */
+    private apiRoutes: Map<string, ApiRoute>;
+
+    /** 插件列表 */
+    private pluginLists: Plugin[];
+
+    /** 应用上下文 */
+    public appContext: BeflyContext;
+
+    /** 应用配置选项 */
+    private appOptions: BeflyOptions;
+
+    // 原构造函数被替换
+    constructor(options: BeflyOptions = {}) {
+        this.apiRoutes = new Map();
+        this.pluginLists = [];
+        this.appContext = {};
+        this.appOptions = options;
+    }
+
+    /**
+     * 系统检查（已提取到 lifecycle/checker.ts）
+     */
+    async initCheck(): Promise<void> {
+        await Checker.run();
+    }
+
+    /**
+     * 加载插件（已提取到 lifecycle/loader.ts）
+     */
+    async loadPlugins(): Promise<void> {
+        await Loader.loadPlugins(this);
+    }
+
+    /**
+     * 加载API路由（已提取到 lifecycle/loader.ts）
+     */
+    async loadApis(dirName: string, options?: { isAddon?: boolean; addonName?: string }): Promise<void> {
+        await Loader.loadApis(dirName, this.apiRoutes, options);
+    }
+
+    /**
+     * 启动服务器
+     */
+    async listen(callback?: (server: Server) => void): Promise<void> {
+        const serverStartTime = Bun.nanoseconds();
+        Logger.info('开始启动 Befly 服务器...');
+
+        // 执行启动前的检查和加载
+        await this.initCheck();
+        await this.loadPlugins();
+        await this.loadApis('core');
+
+        // 加载 addon APIs
+        const addons = scanAddons();
+        for (const addon of addons) {
+            if (hasAddonDir(addon, 'apis')) {
+                await this.loadApis(addon, { isAddon: true, addonName: addon });
+            }
+        }
+
+        await this.loadApis('app');
+
+        const totalStartupTime = calcPerfTime(serverStartTime);
+        Logger.info(`服务器启动准备完成，总耗时: ${totalStartupTime}`);
+
+        // 启动HTTP服务器（路由处理逻辑已提取到 router/*.ts）
+        await Bootstrap.start(this, callback);
+    }
+}
+
+// 核心类已通过 export class 导出
+export { Env, Api, Jwt, Validator, Crypto2, Logger, Yes, No };
+export type { ApiOptions, FieldRules } from './types/api.js';

package/package.json

@@ -1,42 +1,69 @@
 {
     "name": "befly",
-    "version": "2.3.2",
-    "description": "Buma - 为 Bun 专属打造的 API 接口框架核心引擎",
+    "version": "3.0.0",
+    "description": "Befly - 为 Bun 专属打造的 TypeScript API 接口框架核心引擎",
     "type": "module",
     "private": false,
     "publishConfig": {
         "access": "public",
         "registry": "https://registry.npmjs.org"
     },
-    "main": "main.js",
+    "main": "main.ts",
+    "types": "main.ts",
     "exports": {
-        ".": "./main.js"
+        ".": {
+            "types": "./main.ts",
+            "default": "./main.ts"
+        },
+        "./types": {
+            "types": "./types/index.ts",
+            "default": "./types/index.ts"
+        },
+        "./types/*": {
+            "types": "./types/*.ts",
+            "default": "./types/*.ts"
+        },
+        "./utils": {
+            "types": "./utils/index.ts",
+            "default": "./utils/index.ts"
+        },
+        "./utils/*": {
+            "types": "./utils/*.ts",
+            "default": "./utils/*.ts"
+        },
+        "./config": {
+            "types": "./config/env.ts",
+            "default": "./config/env.ts"
+        }
     },
-    "scripts": {
-        "ra": "bun run ../release.js --major",
-        "rb": "bun run ../release.js --minor",
-        "rc": "bun run ../release.js --patch"
+    "bin": {
+        "befly": "./bin/befly.ts"
     },
+    "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,17 +73,19 @@
         ".prettierignore",
         ".prettierrc",
         "bunfig.toml",
+        "tsconfig.json",
         "LICENSE",
+        "main.ts",
         "main.js",
+        "system.ts",
         "system.js",
         "package.json",
         "README.md"
     ],
-    "simple-git-hooks": {
-        "pre-commit": "bunx --bun lint-staged"
+    "engines": {
+        "bun": ">=1.3.0"
     },
-    "lint-staged": {
-        "*.{js,css,scss,less,ts,jsx,vue,html,json,md,yaml}": "bunx --bun prettier --write --cache --ignore-unknown"
-    },
-    "gitHead": "1dc5f118a723969456559e758e2ba889f4601224"
-}
+    "devDependencies": {
+        "@types/bun": "latest"
+    }
+}

package/plugins/{db.js → db.ts}

@@ -1,29 +1,40 @@
+/**
+ * 数据库插件 - TypeScript 版本
+ * 初始化数据库连接和 SQL 管理器
+ */
+
 import { Env } from '../config/env.js';
 import { Logger } from '../utils/logger.js';
 import { createSqlClient } from '../utils/index.js';
-import { SqlManager } from '../utils/sqlManager.js';
-
-// 统一使用 utils/index.js 提供的 createSqlClient
+import { SqlHelper } from '../utils/sqlHelper.js';
+import type { Plugin } from '../types/plugin.js';
+import type { BeflyContext } from '../types/befly.js';
 
-export default {
+/**
+ * 数据库插件
+ */
+const dbPlugin: Plugin = {
+    name: '_db',
     after: ['_redis'],
-    async onInit(befly) {
-        let sql = null;
+
+    async onInit(befly: BeflyContext): Promise<SqlHelper | Record<string, never>> {
+        let sql: any = null;
 
         try {
-            if (Env.MYSQL_ENABLE === 1) {
+            if (Env.DB_ENABLE === 1) {
                 // 创建 Bun SQL 客户端（内置连接池），并确保连接验证成功后再继续
                 sql = await createSqlClient();
 
-                // 创建数据库管理器实例（迁移到 utils/sqlManager.js）
-                const dbManager = new SqlManager(sql, befly);
+                // 创建数据库管理器实例，直接传入 sql 对象
+                const dbManager = new SqlHelper(befly, sql);
 
+                Logger.info('数据库插件初始化成功');
                 return dbManager;
             } else {
-                Logger.warn(`MySQL 未启用，跳过初始化`);
+                Logger.warn('数据库未启用（DB_ENABLE≠1），跳过初始化');
                 return {};
             }
-        } catch (error) {
+        } catch (error: any) {
             Logger.error({
                 msg: '数据库初始化失败',
                 message: error.message,
@@ -34,7 +45,7 @@ export default {
             if (sql) {
                 try {
                     await sql.close();
-                } catch (cleanupError) {
+                } catch (cleanupError: any) {
                     Logger.error('清理连接池失败:', cleanupError);
                 }
             }
@@ -44,3 +55,5 @@ export default {
         }
     }
 };
+
+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,51 @@
+/**
+ * Redis 插件 - TypeScript 版本
+ * 初始化 Redis 连接和助手工具
+ */
+
+import { Env } from '../config/env.js';
+import { Logger } from '../utils/logger.js';
+import { RedisHelper, initRedisClient, getRedisClient } from '../utils/redisHelper.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 客户端（带连接测试）
+                await initRedisClient();
+
+                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({
+                msg: 'Redis 初始化失败',
+                message: error.message,
+                code: error.code,
+                stack: error.stack
+            });
+
+            // 插件内禁止直接退出进程，抛出异常交由主流程统一处理
+            throw error;
+        }
+    }
+};
+
+export default redisPlugin;