befly 2.3.3 → 3.0.0

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,19 +1,43 @@
 {
     "name": "befly",
-    "version": "2.3.3",
-    "description": "Befly - 为 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"
+        }
     },
     "bin": {
-        "befly": "./bin/befly.js"
+        "befly": "./bin/befly.ts"
     },
     "scripts": {},
     "keywords": [
@@ -21,10 +45,12 @@
         "api",
         "framework",
         "core",
+        "typescript",
         "javascript",
         "backend",
         "rest",
-        "http"
+        "http",
+        "type-safe"
     ],
     "author": "chensuiyi <bimostyle@qq.com>",
     "homepage": "https://chensuiyi.me",
@@ -37,6 +63,7 @@
         "plugins/",
         "scripts/",
         "tables/",
+        "types/",
         "utils/",
         ".gitignore",
         ".npmignore",
@@ -46,10 +73,19 @@
         ".prettierignore",
         ".prettierrc",
         "bunfig.toml",
+        "tsconfig.json",
         "LICENSE",
+        "main.ts",
         "main.js",
+        "system.ts",
         "system.js",
         "package.json",
         "README.md"
-    ]
-}
+    ],
+    "engines": {
+        "bun": ">=1.3.0"
+    },
+    "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.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(`数据库未启用（DB_ENABLE≠1），跳过初始化`);
+                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;

package/plugins/tool.ts

@@ -0,0 +1,34 @@
+/**
+ * Tool 插件 - TypeScript 版本
+ * 提供数据处理工具
+ */
+
+import { Tool } from '../utils/tool.js';
+import { Logger } from '../utils/logger.js';
+import type { Plugin } from '../types/plugin.js';
+import type { BeflyContext } from '../types/befly.js';
+
+/**
+ * Tool 插件
+ */
+const toolPlugin: Plugin = {
+    name: '_tool',
+    after: ['_redis', '_db'],
+
+    async onInit(befly: BeflyContext): Promise<Tool> {
+        try {
+            const tool = new Tool(befly);
+            Logger.info('Tool 插件初始化成功');
+            return tool;
+        } catch (error: any) {
+            Logger.error({
+                msg: 'Tool 初始化失败',
+                message: error.message,
+                stack: error.stack
+            });
+            throw error;
+        }
+    }
+};
+
+export default toolPlugin;

package/scripts/syncDb/apply.ts

@@ -0,0 +1,171 @@
+/**
+ * syncDb 变更应用模块
+ *
+ * 包含：
+ * - 比较字段定义变化
+ * - 应用表结构变更计划
+ */
+
+import { Logger } from '../../utils/logger.js';
+import { parseRule } from '../../utils/tableHelper.js';
+import { IS_MYSQL, IS_PG, IS_SQLITE, CHANGE_TYPE_LABELS, typeMapping } from './constants.js';
+import { logFieldChange, resolveDefaultValue, isStringOrArrayType } from './helpers.js';
+import { executeDDLSafely, buildIndexSQL } from './ddl.js';
+import { rebuildSqliteTable } from './sqlite.js';
+import type { FieldChange, IndexAction, TablePlan, ColumnInfo } from './types.js';
+import type { SQL } from 'bun';
+
+// 是否为计划模式（从环境变量读取）
+const IS_PLAN = process.argv.includes('--plan');
+
+/**
+ * 比较字段定义变化
+ *
+ * 对比现有列信息和新的字段规则，识别变化类型：
+ * - 长度变化（string/array 类型）
+ * - 注释变化（MySQL/PG）
+ * - 数据类型变化
+ * - 默认值变化
+ *
+ * @param existingColumn - 现有列信息
+ * @param newRule - 新的字段规则字符串
+ * @param colName - 列名（未使用，保留参数兼容性）
+ * @returns 变化数组
+ */
+export function compareFieldDefinition(existingColumn: ColumnInfo, newRule: string, colName: string): FieldChange[] {
+    const parsed = parseRule(newRule);
+    const { name: fieldName, type: fieldType, max: fieldMax, default: fieldDefault } = parsed;
+    const changes: FieldChange[] = [];
+
+    // 检查长度变化（string和array类型） - SQLite 不比较长度
+    if (!IS_SQLITE && isStringOrArrayType(fieldType)) {
+        if (existingColumn.length !== fieldMax) {
+            changes.push({
+                type: 'length',
+                current: existingColumn.length,
+                expected: fieldMax
+            });
+        }
+    }
+
+    // 检查注释变化（MySQL/PG 支持列注释）
+    if (!IS_SQLITE) {
+        const currentComment = existingColumn.comment || '';
+        if (currentComment !== fieldName) {
+            changes.push({
+                type: 'comment',
+                current: currentComment,
+                expected: fieldName
+            });
+        }
+    }
+
+    // 检查数据类型变化（按方言）
+    if (existingColumn.type.toLowerCase() !== typeMapping[fieldType].toLowerCase()) {
+        changes.push({
+            type: 'datatype',
+            current: existingColumn.type,
+            expected: typeMapping[fieldType].toLowerCase()
+        });
+    }
+
+    // 使用公共函数处理默认值
+    const expectedDefault = resolveDefaultValue(fieldDefault, fieldType);
+
+    // 检查默认值变化
+    if (String(existingColumn.defaultValue) !== String(expectedDefault)) {
+        changes.push({
+            type: 'default',
+            current: existingColumn.defaultValue,
+            expected: expectedDefault
+        });
+    }
+
+    return changes;
+}
+
+/**
+ * 将表结构计划应用到数据库（执行 DDL/索引/注释等）
+ *
+ * 根据数据库方言和计划内容，执行相应的 DDL 操作：
+ * - SQLite: 新增字段直接 ALTER，其他操作需要重建表
+ * - MySQL: 尝试在线 DDL（INSTANT/INPLACE）
+ * - PostgreSQL: 直接 ALTER
+ *
+ * @param sql - SQL 客户端实例
+ * @param tableName - 表名
+ * @param fields - 字段定义对象
+ * @param plan - 表结构变更计划
+ * @param globalCount - 全局统计对象（用于计数）
+ */
+export async function applyTablePlan(sql: SQL, tableName: string, fields: Record<string, string>, plan: TablePlan, globalCount: Record<string, number>): Promise<void> {
+    if (!plan || !plan.changed) return;
+
+    // SQLite: 仅支持部分 ALTER；需要时走重建
+    if (IS_SQLITE) {
+        if (plan.modifyClauses.length > 0 || plan.defaultClauses.length > 0) {
+            if (IS_PLAN) Logger.info(`[计划] 重建表 ${tableName} 以应用列修改/默认值变化`);
+            else await rebuildSqliteTable(sql, tableName, fields);
+        } else {
+            for (const c of plan.addClauses) {
+                const stmt = `ALTER TABLE "${tableName}" ${c}`;
+                if (IS_PLAN) Logger.info(`[计划] ${stmt}`);
+                else await sql.unsafe(stmt);
+            }
+        }
+    } else {
+        const clauses = [...plan.addClauses, ...plan.modifyClauses];
+        if (clauses.length > 0) {
+            const suffix = IS_MYSQL ? ', ALGORITHM=INSTANT, LOCK=NONE' : '';
+            const stmt = IS_MYSQL ? `ALTER TABLE \`${tableName}\` ${clauses.join(', ')}${suffix}` : `ALTER TABLE "${tableName}" ${clauses.join(', ')}`;
+            if (IS_PLAN) Logger.info(`[计划] ${stmt}`);
+            else if (IS_MYSQL) await executeDDLSafely(sql, stmt);
+            else await sql.unsafe(stmt);
+        }
+    }
+
+    // 默认值专用 ALTER（SQLite 不支持）
+    if (plan.defaultClauses.length > 0) {
+        if (IS_SQLITE) {
+            Logger.warn(`SQLite 不支持修改默认值，表 ${tableName} 的默认值变更已跳过`);
+        } else {
+            const suffix = IS_MYSQL ? ', ALGORITHM=INSTANT, LOCK=NONE' : '';
+            const stmt = IS_MYSQL ? `ALTER TABLE \`${tableName}\` ${plan.defaultClauses.join(', ')}${suffix}` : `ALTER TABLE "${tableName}" ${plan.defaultClauses.join(', ')}`;
+            if (IS_PLAN) Logger.info(`[计划] ${stmt}`);
+            else if (IS_MYSQL) await executeDDLSafely(sql, stmt);
+            else await sql.unsafe(stmt);
+        }
+    }
+
+    // 索引操作
+    for (const act of plan.indexActions) {
+        const stmt = buildIndexSQL(tableName, act.indexName, act.fieldName, act.action);
+        if (IS_PLAN) {
+            Logger.info(`[计划] ${stmt}`);
+        } else {
+            try {
+                await sql.unsafe(stmt);
+                if (act.action === 'create') {
+                    Logger.info(`[索引变化] 新建索引 ${tableName}.${act.indexName} (${act.fieldName})`);
+                } else {
+                    Logger.info(`[索引变化] 删除索引 ${tableName}.${act.indexName} (${act.fieldName})`);
+                }
+            } catch (error: any) {
+                Logger.error(`${act.action === 'create' ? '创建' : '删除'}索引失败: ${error.message}`);
+                Logger.error(`表名: ${tableName}, 索引名: ${act.indexName}, 字段: ${act.fieldName}`);
+                throw error;
+            }
+        }
+    }
+
+    // PG 列注释
+    if (IS_PG && plan.commentActions && plan.commentActions.length > 0) {
+        for (const stmt of plan.commentActions) {
+            if (IS_PLAN) Logger.info(`[计划] ${stmt}`);
+            else await sql.unsafe(stmt);
+        }
+    }
+
+    // 计数
+    globalCount.modifiedTables++;
+}

package/scripts/syncDb/constants.ts

@@ -0,0 +1,70 @@
+/**
+ * syncDb 常量定义模块
+ *
+ * 包含：
+ * - 数据库版本要求
+ * - 系统字段定义
+ * - 索引字段配置
+ * - 字段变更类型标签
+ */
+
+import { Env } from '../../config/env.js';
+
+/**
+ * 数据库版本要求
+ */
+export const DB_VERSION_REQUIREMENTS = {
+    MYSQL_MIN_MAJOR: 8,
+    POSTGRES_MIN_MAJOR: 17,
+    SQLITE_MIN_VERSION: '3.50.0',
+    SQLITE_MIN_VERSION_NUM: 35000 // 3 * 10000 + 50 * 100
+} as const;
+
+/**
+ * 系统字段定义（所有表都包含的固定字段）
+ */
+export const SYSTEM_FIELDS = {
+    ID: { name: 'id', comment: '主键ID' },
+    CREATED_AT: { name: 'created_at', comment: '创建时间' },
+    UPDATED_AT: { name: 'updated_at', comment: '更新时间' },
+    DELETED_AT: { name: 'deleted_at', comment: '删除时间' },
+    STATE: { name: 'state', comment: '状态字段' }
+} as const;
+
+/**
+ * 需要创建索引的系统字段
+ */
+export const SYSTEM_INDEX_FIELDS = ['created_at', 'updated_at', 'state'] as const;
+
+/**
+ * 字段变更类型的中文标签映射
+ */
+export const CHANGE_TYPE_LABELS = {
+    length: '长度',
+    datatype: '类型',
+    comment: '注释',
+    default: '默认值'
+} as const;
+
+/**
+ * MySQL 表配置（支持环境变量自定义）
+ */
+export const MYSQL_TABLE_CONFIG = {
+    ENGINE: Env.MYSQL_ENGINE || 'InnoDB',
+    CHARSET: Env.MYSQL_CHARSET || 'utf8mb4',
+    COLLATE: Env.MYSQL_COLLATE || 'utf8mb4_0900_as_cs'
+} as const;
+
+// 数据库类型判断
+export const DB = (Env.DB_TYPE || 'mysql').toLowerCase();
+export const IS_MYSQL = DB === 'mysql';
+export const IS_PG = DB === 'postgresql' || DB === 'postgres';
+export const IS_SQLITE = DB === 'sqlite';
+
+// 字段类型映射（按方言）
+export const typeMapping = {
+    number: IS_SQLITE ? 'INTEGER' : 'BIGINT',
+    string: IS_SQLITE ? 'TEXT' : IS_PG ? 'character varying' : 'VARCHAR',
+    text: IS_MYSQL ? 'MEDIUMTEXT' : 'TEXT',
+    array: IS_SQLITE ? 'TEXT' : IS_PG ? 'character varying' : 'VARCHAR'
+};