befly 3.9.38 → 3.9.39

package/utils/modules.ts

@@ -0,0 +1,98 @@
+import type { Hook } from "../types/hook.js";
+import type { Plugin } from "../types/plugin.js";
+
+import { existsSync } from "node:fs";
+
+import { camelCase } from "es-toolkit/string";
+
+import { Logger } from "../lib/logger.js";
+import { scanFiles } from "./scanFiles.js";
+
+/**
+ * 扫描模块（插件或钩子）
+ * @param dir - 目录路径
+ * @param type - 模块类型（core/addon/app）
+ * @param moduleLabel - 模块标签（如"插件"、"钩子"）
+ * @param addonName - 组件名称（仅 type='addon' 时需要）
+ * @returns 模块列表
+ */
+export async function scanModules<T extends Plugin | Hook>(dir: string, type: "core" | "addon" | "app", moduleLabel: string, addonName?: string): Promise<T[]> {
+    if (!existsSync(dir)) return [];
+
+    const items: T[] = [];
+    const files = await scanFiles(dir, "*.ts");
+
+    for (const { filePath, fileName } of files) {
+        // 生成模块名称
+        const name = camelCase(fileName);
+        const moduleName = type === "core" ? name : type === "addon" ? `addon_${camelCase(addonName!)}_${name}` : `app_${name}`;
+
+        try {
+            const normalizedFilePath = filePath.replace(/\\/g, "/");
+            const moduleImport = await import(normalizedFilePath);
+            const item = moduleImport.default;
+
+            item.name = moduleName;
+            // 为 addon 模块记录 addon 名称
+            if (type === "addon" && addonName) {
+                item.addonName = addonName;
+            }
+            items.push(item);
+        } catch (err: any) {
+            const typeLabel = type === "core" ? "核心" : type === "addon" ? `组件${addonName}` : "项目";
+            Logger.error({ err: err, module: fileName }, `${typeLabel}${moduleLabel} 导入失败`);
+            process.exit(1);
+        }
+    }
+
+    return items;
+}
+
+/**
+ * 排序模块（根据依赖关系）
+ * @param modules - 待排序的模块列表
+ * @returns 排序后的模块列表，如果存在循环依赖或依赖不存在则返回 false
+ */
+export function sortModules<T extends { name?: string; after?: string[] }>(modules: T[]): T[] | false {
+    const result: T[] = [];
+    const visited = new Set<string>();
+    const visiting = new Set<string>();
+    const moduleMap: Record<string, T> = Object.fromEntries(modules.map((m) => [m.name!, m]));
+    let isPass = true;
+
+    // 检查依赖是否存在
+    for (const module of modules) {
+        if (module.after) {
+            for (const dep of module.after) {
+                if (!moduleMap[dep]) {
+                    Logger.error({ module: module.name, dependency: dep }, "依赖的模块未找到");
+                    isPass = false;
+                }
+            }
+        }
+    }
+
+    if (!isPass) return false;
+
+    const visit = (name: string): void => {
+        if (visited.has(name)) return;
+        if (visiting.has(name)) {
+            Logger.error({ module: name }, "模块循环依赖");
+            isPass = false;
+            return;
+        }
+
+        const module = moduleMap[name];
+        if (!module) return;
+
+        visiting.add(name);
+        (module.after || []).forEach(visit);
+        visiting.delete(name);
+        visited.add(name);
+        result.push(module);
+    };
+
+    modules.forEach((m) => visit(m.name!));
+
+    return isPass ? result : false;
+}

package/utils/pickFields.ts

@@ -0,0 +1,19 @@
+import { isPlainObject } from "es-toolkit/compat";
+
+/**
+ * 挑选指定字段
+ */
+export const pickFields = <T extends Record<string, any>>(obj: T, keys: string[]): Partial<T> => {
+    if (!obj || (!isPlainObject(obj) && !Array.isArray(obj))) {
+        return {};
+    }
+
+    const result: any = {};
+    for (const key of keys) {
+        if (key in obj) {
+            result[key] = obj[key];
+        }
+    }
+
+    return result;
+};

package/utils/process.ts

@@ -0,0 +1,56 @@
+/**
+ * 进程角色信息
+ */
+export interface ProcessRole {
+    /** 进程角色：primary（主进程）或 worker（工作进程） */
+    role: "primary" | "worker";
+    /** 实例 ID（PM2 或 Bun Worker） */
+    instanceId: string | null;
+    /** 运行环境：bun-cluster、pm2-cluster 或 standalone */
+    env: "bun-cluster" | "pm2-cluster" | "standalone";
+}
+
+/**
+ * 获取当前进程角色信息
+ * @returns 进程角色、实例 ID 和运行环境
+ */
+export function getProcessRole(): ProcessRole {
+    const bunWorkerId = process.env.BUN_WORKER_ID;
+    const pm2InstanceId = process.env.PM2_INSTANCE_ID;
+
+    // Bun 集群模式
+    if (bunWorkerId !== undefined) {
+        return {
+            role: bunWorkerId === "" ? "primary" : "worker",
+            instanceId: bunWorkerId || "0",
+            env: "bun-cluster"
+        };
+    }
+
+    // PM2 集群模式
+    if (pm2InstanceId !== undefined) {
+        return {
+            role: pm2InstanceId === "0" ? "primary" : "worker",
+            instanceId: pm2InstanceId,
+            env: "pm2-cluster"
+        };
+    }
+
+    // 单进程模式
+    return {
+        role: "primary",
+        instanceId: null,
+        env: "standalone"
+    };
+}
+
+/**
+ * 检测当前进程是否为主进程
+ * 用于集群模式下避免重复执行同步任务
+ * - Bun 集群：BUN_WORKER_ID 为空时是主进程
+ * - PM2 集群：PM2_INSTANCE_ID 为 '0' 或不存在时是主进程
+ * @returns 是否为主进程
+ */
+export function isPrimaryProcess(): boolean {
+    return getProcessRole().role === "primary";
+}

package/utils/regex.ts

@@ -0,0 +1,225 @@
+/**
+ * 内置正则表达式别名
+ * 用于表单验证和数据校验
+ * 命名规范：小驼峰格式
+ */
+export const RegexAliases = {
+    // ============================================
+    // 数字类型
+    // ============================================
+    /** 正整数（不含0） */
+    number: "^\\d+$",
+    /** 整数（含负数） */
+    integer: "^-?\\d+$",
+    /** 浮点数 */
+    float: "^-?\\d+(\\.\\d+)?$",
+    /** 正整数（不含0） */
+    positive: "^[1-9]\\d*$",
+    /** 负整数 */
+    negative: "^-\\d+$",
+    /** 零 */
+    zero: "^0$",
+
+    // ============================================
+    // 字符串类型
+    // ============================================
+    /** 纯字母 */
+    word: "^[a-zA-Z]+$",
+    /** 字母和数字 */
+    alphanumeric: "^[a-zA-Z0-9]+$",
+    /** 字母、数字和下划线 */
+    alphanumeric_: "^[a-zA-Z0-9_]+$",
+    /** 字母、数字、下划线和短横线 */
+    alphanumericDash_: "^[a-zA-Z0-9_-]+$",
+    /** 小写字母 */
+    lowercase: "^[a-z]+$",
+    /** 大写字母 */
+    uppercase: "^[A-Z]+$",
+
+    // ============================================
+    // 中文
+    // ============================================
+    /** 纯中文 */
+    chinese: "^[\\u4e00-\\u9fa5]+$",
+    /** 中文和字母 */
+    chineseWord: "^[\\u4e00-\\u9fa5a-zA-Z]+$",
+
+    // ============================================
+    // 常用格式
+    // ============================================
+    /** 邮箱地址 */
+    email: "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$",
+    /** 中国大陆手机号 */
+    phone: "^1[3-9]\\d{9}$",
+    /** 固定电话（区号-号码） */
+    telephone: "^0\\d{2,3}-?\\d{7,8}$",
+    /** URL 地址 */
+    url: "^https?://",
+    /** IPv4 地址 */
+    ip: "^((25[0-5]|2[0-4]\\d|[01]?\\d\\d?)\\.){3}(25[0-5]|2[0-4]\\d|[01]?\\d\\d?)$",
+    /** IPv6 地址 */
+    ipv6: "^([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}$",
+    /** 域名 */
+    domain: "^(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\\.)+[a-zA-Z]{2,}$",
+
+    // ============================================
+    // 特殊格式
+    // ============================================
+    /** UUID */
+    uuid: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
+    /** 十六进制字符串 */
+    hex: "^[0-9a-fA-F]+$",
+    /** Base64 编码 */
+    base64: "^[A-Za-z0-9+/=]+$",
+    /** MD5 哈希 */
+    md5: "^[a-f0-9]{32}$",
+    /** SHA1 哈希 */
+    sha1: "^[a-f0-9]{40}$",
+    /** SHA256 哈希 */
+    sha256: "^[a-f0-9]{64}$",
+
+    // ============================================
+    // 日期时间
+    // ============================================
+    /** 日期 YYYY-MM-DD */
+    date: "^\\d{4}-\\d{2}-\\d{2}$",
+    /** 时间 HH:MM:SS */
+    time: "^\\d{2}:\\d{2}:\\d{2}$",
+    /** ISO 日期时间 */
+    datetime: "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}",
+    /** 年份 */
+    year: "^\\d{4}$",
+    /** 月份 01-12 */
+    month: "^(0[1-9]|1[0-2])$",
+    /** 日期 01-31 */
+    day: "^(0[1-9]|[12]\\d|3[01])$",
+
+    // ============================================
+    // 代码相关
+    // ============================================
+    /** 变量名 */
+    variable: "^[a-zA-Z_][a-zA-Z0-9_]*$",
+    /** 常量名（全大写） */
+    constant: "^[A-Z][A-Z0-9_]*$",
+    /** 包名（小写+连字符） */
+    package: "^[a-z][a-z0-9-]*$",
+
+    // ============================================
+    // 证件相关
+    // ============================================
+    /** 中国身份证号（18位） */
+    idCard: "^\\d{17}[\\dXx]$",
+    /** 护照号 */
+    passport: "^[a-zA-Z0-9]{5,17}$",
+
+    // ============================================
+    // 账号相关（国内常用）
+    // ============================================
+    /** 银行卡号（16-19位数字） */
+    bankCard: "^\\d{16,19}$",
+    /** 微信号（6-20位，字母开头，可包含字母、数字、下划线、减号） */
+    wechat: "^[a-zA-Z][a-zA-Z0-9_-]{5,19}$",
+    /** QQ号（5-11位数字，首位非0） */
+    qq: "^[1-9]\\d{4,10}$",
+    /** 支付宝账号（手机号或邮箱） */
+    alipay: "^(1[3-9]\\d{9}|[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,})$",
+    /** 用户名（4-20位，字母开头，可包含字母、数字、下划线） */
+    username: "^[a-zA-Z][a-zA-Z0-9_]{3,19}$",
+    /** 昵称（2-20位，支持中文、字母、数字） */
+    nickname: "^[\\u4e00-\\u9fa5a-zA-Z0-9]{2,20}$",
+
+    // ============================================
+    // 密码强度
+    // ============================================
+    /** 弱密码（至少6位） */
+    passwordWeak: "^.{6,}$",
+    /** 中等密码（至少8位，包含字母和数字） */
+    passwordMedium: "^(?=.*[a-zA-Z])(?=.*\\d).{8,}$",
+    /** 强密码（至少8位，包含大小写字母、数字和特殊字符） */
+    passwordStrong: "^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d)(?=.*[!@#$%^&*]).{8,}$",
+
+    // ============================================
+    // 其他常用
+    // ============================================
+    /** 车牌号（新能源+普通） */
+    licensePlate: "^[京津沪渝冀豫云辽黑湘皖鲁新苏浙赣鄂桂甘晋蒙陕吉闽贵粤青藏川宁琼使领][A-Z][A-HJ-NP-Z0-9]{4,5}[A-HJ-NP-Z0-9挂学警港澳]$",
+    /** 邮政编码 */
+    postalCode: "^\\d{6}$",
+    /** 版本号（语义化版本） */
+    semver: "^\\d+\\.\\d+\\.\\d+(-[a-zA-Z0-9.]+)?(\\+[a-zA-Z0-9.]+)?$",
+    /** 颜色值（十六进制） */
+    colorHex: "^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$",
+
+    // ============================================
+    // 空值
+    // ============================================
+    /** 空字符串 */
+    empty: "^$",
+    /** 非空 */
+    notempty: ".+"
+} as const;
+
+/**
+ * 正则别名类型
+ */
+export type RegexAliasName = keyof typeof RegexAliases;
+
+// ============================================
+// 正则表达式缓存（性能优化）
+// ============================================
+const regexCache = new Map<string, RegExp>();
+
+/**
+ * 获取正则表达式字符串
+ * @param name 正则别名（以 @ 开头）或自定义正则字符串
+ * @returns 正则表达式字符串
+ */
+export function getRegex(name: string): string {
+    if (name.startsWith("@")) {
+        const alias = name.slice(1) as RegexAliasName;
+        return RegexAliases[alias] || name;
+    }
+    return name;
+}
+
+/**
+ * 获取编译后的正则表达式对象（带缓存）
+ * @param pattern 正则别名或正则字符串
+ * @param flags 正则标志（如 'i', 'g'）
+ * @returns 编译后的 RegExp 对象
+ */
+export function getCompiledRegex(pattern: string, flags?: string): RegExp {
+    const regexStr = getRegex(pattern);
+    const cacheKey = `${regexStr}:${flags || ""}`;
+
+    let cached = regexCache.get(cacheKey);
+    if (!cached) {
+        cached = new RegExp(regexStr, flags);
+        regexCache.set(cacheKey, cached);
+    }
+    return cached;
+}
+
+/**
+ * 验证值是否匹配正则（使用缓存）
+ * @param value 要验证的值
+ * @param pattern 正则别名或正则字符串
+ * @returns 是否匹配
+ */
+export function matchRegex(value: string, pattern: string): boolean {
+    return getCompiledRegex(pattern).test(value);
+}
+
+/**
+ * 清除正则缓存
+ */
+export function clearRegexCache(): void {
+    regexCache.clear();
+}
+
+/**
+ * 获取缓存大小
+ */
+export function getRegexCacheSize(): number {
+    return regexCache.size;
+}

package/utils/response.ts

@@ -0,0 +1,115 @@
+import type { RequestContext } from "../types/context.js";
+
+import { Logger } from "../lib/logger.js";
+
+/**
+ * 创建错误响应（专用于 Hook 中间件）
+ * 在钩子中提前拦截请求时使用
+ * @param ctx - 请求上下文
+ * @param msg - 错误消息
+ * @param code - 错误码，默认 1
+ * @param data - 附加数据，默认 null
+ * @param detail - 详细信息，用于标记具体提示位置，默认 null
+ * @param reasonCode - 拦截原因标识（用于统计/聚合），默认 null
+ * @returns Response 对象
+ */
+export function ErrorResponse(ctx: RequestContext, msg: string, code: number = 1, data: any = null, detail: any = null, reasonCode: string | null = null): Response {
+    // 记录拦截日志
+    if (ctx.requestId) {
+        // requestId/route/user/duration 等字段由 ALS 统一注入，避免在 msg 中重复拼接
+        Logger.info(
+            {
+                event: "request_blocked",
+                reason: msg,
+                reasonCode: reasonCode,
+                code: code,
+                detail: detail
+            },
+            "request blocked"
+        );
+    }
+
+    return Response.json(
+        {
+            code: code,
+            msg: msg,
+            data: data,
+            detail: detail
+        },
+        {
+            headers: ctx.corsHeaders
+        }
+    );
+}
+
+/**
+ * 创建最终响应（专用于 API 路由结尾）
+ * 自动处理 ctx.response/ctx.result，并记录请求日志
+ * @param ctx - 请求上下文
+ * @returns Response 对象
+ */
+export function FinalResponse(ctx: RequestContext): Response {
+    // 记录请求日志
+    if (ctx.api && ctx.requestId) {
+        // requestId/route/user/duration 等字段由 ALS 统一注入，避免在 msg 中重复拼接
+        Logger.info(
+            {
+                event: "request_done"
+            },
+            "request done"
+        );
+    }
+
+    // 1. 如果已经有 response，直接返回
+    if (ctx.response) {
+        return ctx.response;
+    }
+
+    // 2. 如果有 result，格式化为响应
+    if (ctx.result !== undefined) {
+        let result = ctx.result;
+
+        // 如果是字符串，自动包裹为成功响应
+        if (typeof result === "string") {
+            result = {
+                code: 0,
+                msg: result
+            };
+        }
+        // 如果是对象，自动补充 code: 0
+        else if (result && typeof result === "object") {
+            if (!("code" in result)) {
+                result = {
+                    code: 0,
+                    ...result
+                };
+            }
+        }
+
+        // 处理 BigInt 序列化问题
+        if (result && typeof result === "object") {
+            const jsonString = JSON.stringify(result, (key, value) => (typeof value === "bigint" ? value.toString() : value));
+            return new Response(jsonString, {
+                headers: {
+                    ...ctx.corsHeaders,
+                    "Content-Type": "application/json"
+                }
+            });
+        } else {
+            return Response.json(result, {
+                headers: ctx.corsHeaders
+            });
+        }
+    }
+
+    // 3. 默认响应：没有生成响应
+    return Response.json(
+        {
+            code: 1,
+            msg: "未生成响应"
+        },
+        {
+            headers: ctx.corsHeaders
+        }
+    );
+}

package/utils/route.ts

@@ -0,0 +1,23 @@
+/**
+ * 标准化接口权限路径（用于写入/读取权限缓存时保持一致）
+ * 规则（简化版）：method 大写；path 为空则为 '/'；确保以 '/' 开头
+ * 说明：当前框架内 api.path 来源于目录结构生成、请求侧使用 URL.pathname，默认不包含 query/hash，且不期望出现尾部斜杠等异常输入。
+ */
+export function normalizeApiPath(method: string, path: string): string {
+    const normalizedMethod = (method || "").toUpperCase();
+    let normalizedPath = path || "/";
+
+    if (!normalizedPath.startsWith("/")) {
+        normalizedPath = "/" + normalizedPath;
+    }
+
+    return `${normalizedMethod}${normalizedPath}`;
+}
+
+/**
+ * 生成路由 Key（用于路由匹配 / 权限缓存 / 日志等场景统一使用）
+ * 格式：METHOD/path
+ */
+export function makeRouteKey(method: string, pathname: string): string {
+    return normalizeApiPath(method, pathname);
+}

package/utils/scanConfig.ts

@@ -0,0 +1,142 @@
+import { existsSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { isPlainObject } from "es-toolkit";
+import { get, set } from "es-toolkit/compat";
+import { mergeAndConcat } from "merge-anything";
+
+/**
+ * 加载配置选项
+ * - 该类型为 scanConfig 专用：按“就近放置”原则直接与实现放在同文件，避免拆到单独的 *Types.ts 造成目录噪音。
+ */
+export interface LoadConfigOptions {
+    /** 当前工作目录，默认 process.cwd() */
+    cwd?: string;
+    /** 目录数组：要搜索的目录路径（相对于 cwd） */
+    dirs: string[];
+    /** 文件数组：要匹配的文件名 */
+    files: string[];
+    /** 文件扩展名，默认 ['.js', '.ts', '.json'] */
+    extensions?: string[];
+    /** 加载模式：'first' = 返回第一个找到的配置（默认），'merge' = 合并所有配置 */
+    mode?: "merge" | "first";
+    /** 指定要提取的字段路径数组，如 ['menus', 'database.host']，为空则返回完整对象 */
+    paths?: string[];
+    /** 默认配置，会与找到的配置合并（优先级最低） */
+    defaults?: Record<string, any>;
+}
+
+/**
+ * 扫描并合并配置文件（矩阵搜索：dirs × files）
+ * @param options - 加载选项
+ * @returns 合并后的配置对象（或第一个找到的配置）
+ */
+export async function scanConfig(options: LoadConfigOptions): Promise<Record<string, any>> {
+    const {
+        //
+        cwd = process.cwd(),
+        dirs,
+        files,
+        extensions = [".js", ".ts", ".json"],
+        mode = "first",
+        paths,
+        defaults = {}
+    } = options;
+
+    // 参数验证
+    if (!Array.isArray(dirs) || dirs.length === 0) {
+        throw new Error("dirs 必须是非空数组");
+    }
+    if (!Array.isArray(files) || files.length === 0) {
+        throw new Error("files 必须是非空数组");
+    }
+
+    const configs: Record<string, any>[] = [];
+
+    // 矩阵搜索：dirs × files × extensions
+    for (const dir of dirs) {
+        // 如果是绝对路径则直接使用，否则拼接 cwd
+        const fullDir = isAbsolute(dir) ? dir : join(cwd, dir);
+
+        for (const file of files) {
+            for (const ext of extensions) {
+                const fileName = file.endsWith(ext) ? file : file + ext;
+                const filePath = join(fullDir, fileName);
+
+                if (existsSync(filePath)) {
+                    try {
+                        const importUrl = pathToFileURL(filePath).href + `?t=${Date.now()}`;
+
+                        // 动态导入配置文件（使用 import 断言处理 JSON）
+                        let data: any;
+
+                        if (ext === ".json") {
+                            // JSON 文件使用 import 断言
+                            const module = await import(importUrl, { with: { type: "json" } });
+                            data = module.default;
+                        } else {
+                            // JS/TS 文件使用动态导入
+                            const module = await import(importUrl);
+                            data = module.default || module;
+
+                            // 处理 async 函数导出（如 defineAddonConfig）
+                            if (data instanceof Promise) {
+                                data = await data;
+                            }
+                        }
+
+                        // 验证配置数据
+                        if (!isPlainObject(data)) {
+                            continue;
+                        }
+
+                        configs.push(data);
+
+                        // 如果模式为 'first'，找到第一个配置后立即返回
+                        if (mode === "first") {
+                            const firstConfig = mergeAndConcat(defaults, data);
+
+                            // 如果指定了 paths，则只返回指定路径的字段
+                            if (paths && paths.length > 0) {
+                                const result: Record<string, any> = {};
+                                for (const path of paths) {
+                                    const value = get(firstConfig, path);
+                                    if (value !== undefined) {
+                                        set(result, path, value);
+                                    }
+                                }
+                                return result;
+                            }
+
+                            return firstConfig;
+                        }
+
+                        // 找到后跳过同名文件的其他扩展名
+                        break;
+                    } catch {
+                        // 保持静默：继续尝试下一个候选配置文件
+                    }
+                }
+            }
+        }
+    }
+
+    // 合并配置（使用 mergeAndConcat 深度合并）
+    // 合并顺序：defaults ← configs[0] ← configs[1] ← ...
+    const finalConfig = mergeAndConcat(defaults, ...configs);
+
+    // 如果指定了 paths，则只返回指定路径的字段
+    if (paths && paths.length > 0) {
+        const result: Record<string, any> = {};
+        for (const path of paths) {
+            const value = get(finalConfig, path);
+            if (value !== undefined) {
+                set(result, path, value);
+            }
+        }
+        return result;
+    }
+
+    return finalConfig;
+}