befly 3.17.0 → 3.17.2

package/paths.js

@@ -0,0 +1,112 @@
+/**
+ * Befly 框架路径配置
+ *
+ * 提供统一的路径常量，供整个框架使用
+ * 所有路径常量采用具名导出方式，避免通过对象访问
+ *
+ * 路径分类：
+ * - root* 系列：Core 框架内部路径（packages/core/*）
+ * - app* 系列：用户项目路径（process.cwd()/*）
+ *
+ */
+
+import { fileURLToPath } from "node:url";
+
+import { dirname, join, normalize } from "pathe";
+
+// 当前文件的路径信息
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// ==================== Core 框架路径 ====================
+
+/**
+ * Core 框架根目录
+ * @description packages/core/
+ */
+export const coreDir = __dirname;
+
+/**
+ * Core 框架 dist 目录
+ * @description 源码态为 packages/core/dist；dist 运行态为 packages/core/dist
+ */
+export const coreDistDir = normalize(__dirname).endsWith("/dist") ? __dirname : join(__dirname, "dist");
+
+/**
+ * Core 框架检查目录
+ * @description packages/core/checks/
+ * @usage 存放启动检查模块（返回 boolean 的 default 函数）
+ */
+export const coreCheckDir = join(__dirname, "checks");
+
+/**
+ * Core 框架插件目录
+ * @description packages/core/plugins/
+ * @usage 存放内置插件（mysql, logger, redis, tool 等）
+ */
+export const corePluginDir = join(__dirname, "plugins");
+
+/**
+ * Core 框架钩子目录
+ * @description packages/core/hooks/
+ * @usage 存放内置钩子（auth, cors, parser 等）
+ */
+export const coreHookDir = join(__dirname, "hooks");
+
+/**
+ * Core 框架 API 目录
+ * @description packages/core/apis/
+ * @usage 存放框架级别的 API 接口
+ */
+export const coreApiDir = join(__dirname, "apis");
+
+/**
+ * Core 框架表定义目录
+ * @description packages/core/tables/
+ * @usage 存放框架核心表定义（JSON 格式）
+ */
+export const coreTableDir = join(__dirname, "tables");
+
+// ==================== 用户项目路径 ====================
+
+/**
+ * 项目根目录
+ * @description process.cwd()
+ * @usage 用户项目的根目录
+ */
+export const appDir = process.cwd();
+
+/**
+ * 项目检查目录
+ * @description {appDir}/checks/
+ * @usage 存放用户自定义启动检查模块
+ */
+export const appCheckDir = join(appDir, "checks");
+
+/**
+ * 项目插件目录
+ * @description {appDir}/plugins/
+ * @usage 存放用户自定义插件
+ */
+export const appPluginDir = join(appDir, "plugins");
+
+/**
+ * 项目钩子目录
+ * @description {appDir}/hooks/
+ * @usage 存放用户自定义钩子
+ */
+export const appHookDir = join(appDir, "hooks");
+
+/**
+ * 项目 API 目录
+ * @description {appDir}/apis/
+ * @usage 存放用户业务 API 接口
+ */
+export const appApiDir = join(appDir, "apis");
+
+/**
+ * 项目表定义目录
+ * @description {appDir}/tables/
+ * @usage 存放用户业务表定义（JSON 格式）
+ */
+export const appTableDir = join(appDir, "tables");

package/plugins/cache.js

@@ -0,0 +1,16 @@
+/**
+ * 缓存插件 - JavaScript 版本
+ * 负责在服务器启动时缓存接口、菜单和角色权限到 Redis
+ */
+
+import { CacheHelper } from "../lib/cacheHelper.js";
+
+/**
+ * 缓存插件
+ */
+export default {
+    deps: ["logger", "redis", "mysql"],
+    async handler(befly) {
+        return new CacheHelper({ mysql: befly.mysql, redis: befly.redis });
+    }
+};

package/plugins/config.js

@@ -0,0 +1,11 @@
+/**
+ * 配置插件
+ * 提供访问项目配置的能力
+ */
+
+export default {
+    deps: [],
+    handler: (befly) => {
+        return befly.config;
+    }
+};

package/plugins/email.js

@@ -0,0 +1,27 @@
+/**
+ * 邮件插件
+ * 提供邮件发送功能，支持 SMTP 配置
+ */
+
+import { EmailHelper } from "../lib/emailHelper.js";
+
+/** 默认配置 */
+const defaultConfig = {
+    host: "smtp.qq.com",
+    port: 465,
+    secure: true,
+    user: "",
+    pass: "",
+    fromName: "Befly System"
+};
+
+export default {
+    deps: ["mysql", "logger", "config"],
+    async handler(befly) {
+        // 从 befly.config.email 获取配置
+        const emailConfigRaw = (befly.config ? befly.config["email"] : undefined) || {};
+        const emailConfig = Object.assign({}, defaultConfig, emailConfigRaw);
+
+        return new EmailHelper(befly, emailConfig);
+    }
+};

package/plugins/logger.js

@@ -0,0 +1,20 @@
+/**
+ * 日志插件
+ * 提供全局日志功能
+ */
+
+import { Logger } from "../lib/logger.js";
+
+/**
+ * 日志插件
+ */
+export default {
+    deps: [],
+    async handler(befly) {
+        // 配置 Logger
+        if (befly.config && befly.config.logger) {
+            Logger.configure(befly.config.logger);
+        }
+        return Logger;
+    }
+};

package/plugins/mysql.js

@@ -0,0 +1,36 @@
+/**
+ * 数据库插件
+ * 初始化数据库连接和 SQL 管理器
+ */
+
+import { Connect } from "../lib/connect.js";
+import { DbHelper } from "../lib/dbHelper/index.js";
+import { Logger } from "../lib/logger.js";
+
+/**
+ * 数据库插件
+ */
+export default {
+    deps: ["logger", "redis"],
+    async handler(befly) {
+        try {
+            // 创建数据库管理器实例
+            const dbManager = new DbHelper({
+                redis: befly.redis,
+                dbName: befly.config?.mysql?.database,
+                sql: Connect.getMysql(),
+                idMode: befly.config?.mysql?.idMode
+            });
+
+            return dbManager;
+        } catch (error) {
+            Logger.error("数据库初始化失败", error, { runMode: befly.config?.runMode });
+            throw new Error("数据库初始化失败", {
+                cause: error,
+                code: "runtime",
+                subsystem: "db",
+                operation: "init"
+            });
+        }
+    }
+};

package/plugins/redis.js

@@ -0,0 +1,34 @@
+/**
+ * Redis 插件
+ * 初始化 Redis 连接和助手工具
+ */
+
+import { Connect } from "../lib/connect.js";
+import { Logger } from "../lib/logger.js";
+import { RedisHelper } from "../lib/redisHelper.js";
+
+/**
+ * Redis 插件
+ */
+export default {
+    deps: ["logger"],
+    async handler(befly) {
+        const env = befly.config?.runMode;
+        const redisPrefix = befly.config?.redis?.prefix;
+        try {
+            // 启动期已建立 Redis 连接；这里仅校验连接存在
+            Connect.getRedis();
+
+            // 返回 RedisHelper 实例
+            return new RedisHelper(redisPrefix);
+        } catch (error) {
+            Logger.error("Redis 初始化失败", error, { env: env });
+            throw new Error("Redis 初始化失败", {
+                cause: error,
+                code: "runtime",
+                subsystem: "redis",
+                operation: "init"
+            });
+        }
+    }
+};

package/plugins/tool.js

@@ -0,0 +1,155 @@
+/**
+ * 工具插件
+ * 提供常用的工具函数
+ */
+
+import { isNumber, isString } from "../utils/is.js";
+
+/**
+ * 成功响应
+ * @param msg - 消息
+ * @param data - 数据（可选）
+ * @param other - 其他字段（可选）
+ * @returns 成功响应对象
+ */
+export function Yes(msg, data = {}, other = {}) {
+    const out = {
+        code: 0,
+        msg: msg,
+        data: data
+    };
+    if (other && typeof other === "object") {
+        for (const key of Object.keys(other)) {
+            out[key] = other[key];
+        }
+    }
+    return out;
+}
+
+/**
+ * 失败响应
+ * @param msg - 消息
+ * @param data - 数据（可选）
+ * @param other - 其他字段（可选）
+ * @returns 失败响应对象
+ */
+export function No(msg, data = null, other = {}) {
+    const out = {
+        code: 1,
+        msg: msg,
+        data: data
+    };
+    if (other && typeof other === "object") {
+        for (const key of Object.keys(other)) {
+            out[key] = other[key];
+        }
+    }
+    return out;
+}
+
+/**
+ * 统一响应函数
+ *
+ * 自动识别数据类型并设置正确的 Content-Type：
+ * - 对象 → application/json
+ * - 字符串 → text/plain
+ * - 可通过 options.contentType 手动指定
+ *
+ * @param ctx 请求上下文
+ * @param data 响应数据（对象或字符串）
+ * @param options 响应选项
+ * @returns Response 对象
+ */
+export function Raw(ctx, data, options = {}) {
+    const status = isNumber(options.status) ? options.status : 200;
+    const contentType = options.contentType;
+    const headers = options.headers || {};
+
+    // 自动判断 Content-Type
+    let finalContentType = contentType;
+    let body;
+
+    if (isString(data)) {
+        // 字符串类型
+        body = data;
+        if (!finalContentType) {
+            // 自动判断：XML 或纯文本
+            finalContentType = data.trim().startsWith("<") ? "application/xml" : "text/plain";
+        }
+    } else {
+        // JSON 序列化（对象/数组/原始值均可）
+        body = JSON.stringify(data);
+        finalContentType = finalContentType || "application/json";
+    }
+
+    // 合并响应头
+    const responseHeaders = {};
+    const corsHeaders = ctx.corsHeaders;
+    if (corsHeaders && typeof corsHeaders === "object") {
+        for (const key of Object.keys(corsHeaders)) {
+            responseHeaders[key] = corsHeaders[key];
+        }
+    }
+    responseHeaders["Content-Type"] = finalContentType;
+    if (headers && typeof headers === "object") {
+        for (const key of Object.keys(headers)) {
+            responseHeaders[key] = headers[key];
+        }
+    }
+
+    return new Response(body, {
+        status: status,
+        headers: responseHeaders
+    });
+}
+
+/**
+ * 计算 md5（hex）
+ * @param value 输入字符串
+ * @returns md5 hex
+ */
+export function md5(value) {
+    if (!isString(value) || value.length < 1) {
+        throw new Error("md5 输入必须是非空字符串", {
+            cause: null,
+            code: "validation",
+            subsystem: "tool",
+            operation: "md5"
+        });
+    }
+    const hasher = new Bun.CryptoHasher("md5");
+    hasher.update(value);
+    return hasher.digest("hex");
+}
+
+/**
+ * 计算 sha256（hex）
+ * @param value 输入字符串
+ * @returns sha256 hex
+ */
+export function sha256(value) {
+    if (!isString(value) || value.length < 1) {
+        throw new Error("sha256 输入必须是非空字符串", {
+            cause: null,
+            code: "validation",
+            subsystem: "tool",
+            operation: "sha256"
+        });
+    }
+    const hasher = new Bun.CryptoHasher("sha256");
+    hasher.update(value);
+    return hasher.digest("hex");
+}
+
+export default {
+    deps: [],
+    handler: () => {
+        return {
+            Yes: Yes,
+            No: No,
+            Raw: Raw,
+            md5: md5,
+            sha256: sha256
+        };
+    }
+};

package/router/api.js

@@ -0,0 +1,140 @@
+/**
+ * API路由处理器
+ * 处理 /api/* 路径的请求
+ */
+
+import { Logger } from "../lib/logger.js";
+// 相对导入
+import { getClientIp } from "../utils/getClientIp.js";
+import { FinalResponse } from "../utils/response.js";
+import { genShortId } from "../utils/util.js";
+
+/**
+ * API处理器工厂函数
+ * @param apis - API路由映射表
+ * @param hooks - 钩子列表
+ * @param context - 应用上下文
+ */
+export function apiHandler(apis, hooks, context) {
+    return async (req, server) => {
+        // 1. 生成请求 ID
+        const requestId = genShortId();
+
+        // 2. 创建请求上下文
+        const url = new URL(req.url);
+        // 只用接口路径做存在性判断与匹配：不要把 method 拼进 key
+        // 说明：apisMap 的 key 来源于 scanFiles/loadApis 生成的 path（例如 /api/core/xxx）
+
+        const clientIp = getClientIp(req, server);
+
+        const now = Date.now();
+
+        const ctx = {
+            method: req.method,
+            body: {},
+            req: req,
+            now: now,
+            ip: clientIp,
+            headers: req.headers,
+            requestId: requestId,
+            corsHeaders: {
+                "X-Request-ID": requestId
+            }
+        };
+
+        const apiData = apis[url.pathname];
+        if (apiData) {
+            ctx.apiPath = apiData.apiPath;
+            ctx.apiName = apiData.name;
+            ctx.filePath = apiData.filePath;
+            ctx.handler = apiData.handler;
+            ctx.method = apiData.method;
+            ctx.body = apiData.body;
+            ctx.auth = apiData.auth;
+            ctx.fields = apiData.fields;
+            ctx.required = apiData.required;
+        }
+
+        try {
+            // 4. 串联执行所有钩子
+            for (const hook of hooks) {
+                await hook.handler(context, ctx);
+
+                // 如果钩子已经设置了 response，停止执行
+                if (ctx.response) {
+                    return ctx.response;
+                }
+            }
+
+            // hooks 全部通过后记录请求日志（拦截请求仅由 ErrorResponse 记录）
+            if (ctx.handler && req.method !== "OPTIONS") {
+                const logData = {
+                    event: "request",
+                    requestId: requestId,
+                    method: req.method,
+                    apiPath: ctx.apiPath,
+                    apiName: ctx.apiName,
+                    ip: clientIp,
+                    now: now,
+                    userId: ctx.userId,
+                    nickname: ctx.nickname,
+                    roleCode: ctx.roleCode,
+                    roleType: ctx.roleType
+                };
+
+                if (ctx.body && Object.keys(ctx.body).length > 0) {
+                    logData["body"] = ctx.body;
+                }
+
+                Logger.info("请求", logData);
+            }
+
+            // 5. 执行 API handler
+            if (!ctx.handler) {
+                if (req.method !== "OPTIONS") {
+                    ctx.response = Response.json(
+                        {
+                            code: 1,
+                            msg: "接口不存在"
+                        },
+                        {
+                            headers: ctx.corsHeaders
+                        }
+                    );
+                }
+            } else if (ctx.handler) {
+                const result = await ctx.handler(context, ctx);
+
+                if (result instanceof Response) {
+                    ctx.response = result;
+                } else {
+                    ctx.result = result;
+                }
+            }
+
+            // 7. 返回响应（自动处理 response/result/日志）
+            return FinalResponse(ctx);
+        } catch (err) {
+            // 全局错误处理
+            const errorPath = ctx.apiPath ? ctx.apiPath : req.url;
+            Logger.error("请求错误", err, {
+                path: errorPath,
+                requestId: requestId,
+                method: req.method,
+                apiPath: ctx.apiPath,
+                apiName: ctx.apiName,
+                ip: clientIp,
+                now: now,
+                userId: ctx.userId,
+                nickname: ctx.nickname,
+                roleCode: ctx.roleCode,
+                roleType: ctx.roleType
+            });
+            ctx.result = {
+                code: 1,
+                msg: "内部服务错误"
+            };
+            return FinalResponse(ctx);
+        }
+    };
+}

package/router/static.js

@@ -0,0 +1,71 @@
+/**
+ * 静态文件路由处理器
+ * 处理 /* 路径的静态文件请求
+ */
+
+// 外部依赖
+import { join } from "pathe";
+
+import { Logger } from "../lib/logger.js";
+// 相对导入
+import { appDir } from "../paths.js";
+import { setCorsOptions } from "../utils/cors.js";
+
+/**
+ * 静态文件处理器工厂
+ */
+export function staticHandler(corsConfig = undefined) {
+    return async (req) => {
+        // 设置 CORS 响应头
+        const corsHeaders = setCorsOptions(req, corsConfig);
+
+        const url = new URL(req.url);
+        const filePath = join(appDir, "public", url.pathname);
+
+        try {
+            // OPTIONS预检请求
+            if (req.method === "OPTIONS") {
+                return new Response(null, {
+                    status: 204,
+                    headers: corsHeaders
+                });
+            }
+
+            const file = Bun.file(filePath);
+            if (await file.exists()) {
+                const headers = {};
+                if (corsHeaders && typeof corsHeaders === "object") {
+                    for (const key of Object.keys(corsHeaders)) {
+                        headers[key] = corsHeaders[key];
+                    }
+                }
+                headers["Content-Type"] = file.type || "application/octet-stream";
+                return new Response(file, {
+                    headers: headers
+                });
+            } else {
+                return Response.json(
+                    {
+                        code: 1,
+                        msg: "文件未找到"
+                    },
+                    {
+                        headers: corsHeaders
+                    }
+                );
+            }
+        } catch (error) {
+            Logger.error("静态文件处理失败", error);
+
+            return Response.json(
+                {
+                    code: 1,
+                    msg: "文件读取失败"
+                },
+                {
+                    headers: corsHeaders
+                }
+            );
+        }
+    };
+}

package/sql/admin.sql

@@ -0,0 +1,18 @@
+CREATE TABLE IF NOT EXISTS `admin` (
+    `id` BIGINT NOT NULL,
+    `nickname` VARCHAR(50) NOT NULL DEFAULT '',
+    `username` VARCHAR(30) NOT NULL DEFAULT '',
+    `password` VARCHAR(500) NOT NULL DEFAULT '',
+    `email` VARCHAR(100) NOT NULL DEFAULT '',
+    `phone` VARCHAR(20) NOT NULL DEFAULT '',
+    `avatar` VARCHAR(500) NOT NULL DEFAULT '',
+    `role_code` VARCHAR(50) NOT NULL DEFAULT '',
+    `role_type` VARCHAR(5) NOT NULL DEFAULT 'user',
+    `last_login_time` BIGINT NOT NULL DEFAULT 0,
+    `last_login_ip` VARCHAR(50) NOT NULL DEFAULT '',
+    `state` TINYINT NOT NULL DEFAULT 1,
+    `created_at` BIGINT NOT NULL DEFAULT 0,
+    `updated_at` BIGINT NOT NULL DEFAULT 0,
+    `deleted_at` BIGINT NULL DEFAULT NULL,
+    PRIMARY KEY (`id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

package/sql/api.sql

@@ -0,0 +1,12 @@
+CREATE TABLE IF NOT EXISTS `api` (
+    `id` BIGINT NOT NULL,
+    `name` VARCHAR(100) NOT NULL DEFAULT '',
+    `auth` VARCHAR(200) NOT NULL DEFAULT '',
+    `path` VARCHAR(200) NOT NULL DEFAULT '',
+    `parent_path` VARCHAR(200) NOT NULL DEFAULT '',
+    `state` TINYINT NOT NULL DEFAULT 1,
+    `created_at` BIGINT NOT NULL DEFAULT 0,
+    `updated_at` BIGINT NOT NULL DEFAULT 0,
+    `deleted_at` BIGINT NULL DEFAULT NULL,
+    PRIMARY KEY (`id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

package/sql/dict.sql

@@ -0,0 +1,13 @@
+CREATE TABLE IF NOT EXISTS `dict` (
+    `id` BIGINT NOT NULL,
+    `type_code` VARCHAR(50) NOT NULL DEFAULT '',
+    `key` VARCHAR(50) NOT NULL DEFAULT '',
+    `label` VARCHAR(100) NOT NULL DEFAULT '',
+    `sort` INT NOT NULL DEFAULT 0,
+    `remark` VARCHAR(200) NOT NULL DEFAULT '',
+    `state` TINYINT NOT NULL DEFAULT 1,
+    `created_at` BIGINT NOT NULL DEFAULT 0,
+    `updated_at` BIGINT NOT NULL DEFAULT 0,
+    `deleted_at` BIGINT NULL DEFAULT NULL,
+    PRIMARY KEY (`id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

package/sql/dictType.sql

@@ -0,0 +1,12 @@
+CREATE TABLE IF NOT EXISTS `dict_type` (
+    `id` BIGINT NOT NULL,
+    `code` VARCHAR(50) NOT NULL DEFAULT '',
+    `name` VARCHAR(50) NOT NULL DEFAULT '',
+    `description` VARCHAR(200) NOT NULL DEFAULT '',
+    `sort` INT NOT NULL DEFAULT 0,
+    `state` TINYINT NOT NULL DEFAULT 1,
+    `created_at` BIGINT NOT NULL DEFAULT 0,
+    `updated_at` BIGINT NOT NULL DEFAULT 0,
+    `deleted_at` BIGINT NULL DEFAULT NULL,
+    PRIMARY KEY (`id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;