befly 3.9.40 → 3.10.0

package/lib/dbUtils.ts

@@ -0,0 +1,450 @@
+import type { WhereConditions } from "../types/common.js";
+
+import { snakeCase } from "es-toolkit/string";
+
+import { fieldClear } from "../utils/fieldClear.js";
+import { keysToSnake } from "../utils/keysToSnake.js";
+
+export class DbUtils {
+    static parseTableRef(tableRef: string): { schema: string | null; table: string; alias: string | null } {
+        if (typeof tableRef !== "string") {
+            throw new Error(`tableRef 必须是字符串 (tableRef: ${String(tableRef)})`);
+        }
+
+        const trimmed = tableRef.trim();
+        if (!trimmed) {
+            throw new Error("tableRef 不能为空");
+        }
+
+        const parts = trimmed.split(/\s+/).filter((p) => p.length > 0);
+        if (parts.length > 2) {
+            throw new Error(`不支持的表引用格式（包含过多片段）。请使用最简形式：table 或 table alias 或 schema.table 或 schema.table alias (tableRef: ${trimmed})`);
+        }
+
+        const namePart = parts[0];
+        const aliasPart = parts.length === 2 ? parts[1] : null;
+
+        const nameSegments = namePart.split(".");
+        if (nameSegments.length > 2) {
+            throw new Error(`不支持的表引用格式（schema 层级过深） (tableRef: ${trimmed})`);
+        }
+
+        const schema = nameSegments.length === 2 ? nameSegments[0] : null;
+        const table = nameSegments.length === 2 ? nameSegments[1] : nameSegments[0];
+
+        return { schema: schema, table: table, alias: aliasPart };
+    }
+
+    /**
+     * 规范化表引用：只 snakeCase schema/table，本身 alias 保持原样。
+     * - 支持：table / table alias / schema.table / schema.table alias
+     */
+    static normalizeTableRef(tableRef: string): string {
+        const parsed = DbUtils.parseTableRef(tableRef);
+
+        const schemaPart = parsed.schema ? snakeCase(parsed.schema) : null;
+        const tablePart = snakeCase(parsed.table);
+
+        let result = schemaPart ? `${schemaPart}.${tablePart}` : tablePart;
+        if (parsed.alias) {
+            result = `${result} ${parsed.alias}`;
+        }
+
+        return result;
+    }
+
+    /**
+     * JOIN 场景下主表的限定符：优先使用 alias；没有 alias 时使用 snakeCase(table)。
+     * 用于构造类似 "o.state$gt" 的 where key，避免出现 "order o.state$gt" 这种带空格的非法 key。
+     */
+    static getJoinMainQualifier(tableRef: string): string {
+        const parsed = DbUtils.parseTableRef(tableRef);
+        if (parsed.alias) {
+            return parsed.alias;
+        }
+        return snakeCase(parsed.table);
+    }
+
+    /**
+     * 字段数组转下划线格式
+     * 支持排除字段语法：['!password', '!token']
+     *
+     * 说明：exclude 模式需要表的所有字段名，因此通过 getTableColumns 回调获取
+     */
+    static async fieldsToSnake(table: string, fields: string[], getTableColumns: (table: string) => Promise<string[]>): Promise<string[]> {
+        if (!fields || !Array.isArray(fields)) {
+            return ["*"];
+        }
+
+        const classified = DbUtils.validateAndClassifyFields(fields);
+
+        // 情况1：查询所有字段
+        if (classified.type === "all") {
+            return ["*"];
+        }
+
+        // 情况2：指定包含字段
+        if (classified.type === "include") {
+            return classified.fields.map((field) => {
+                // 保留函数和特殊字段
+                if (field.includes("(") || field.includes(" ")) {
+                    return field;
+                }
+                return snakeCase(field);
+            });
+        }
+
+        // 情况3：排除字段
+        if (classified.type === "exclude") {
+            const allColumns = await getTableColumns(table);
+            const excludeSnakeFields = classified.fields.map((f) => snakeCase(f));
+
+            const resultFields = allColumns.filter((col) => !excludeSnakeFields.includes(col));
+            if (resultFields.length === 0) {
+                throw new Error(`排除字段后没有剩余字段可查询。表: ${table}, 排除: ${excludeSnakeFields.join(", ")}`);
+            }
+
+            return resultFields;
+        }
+
+        return ["*"];
+    }
+
+    static validateAndClassifyFields(fields?: string[]): {
+        type: "all" | "include" | "exclude";
+        fields: string[];
+    } {
+        // 情况1：空数组或 undefined，表示查询所有
+        if (!fields || fields.length === 0) {
+            return { type: "all", fields: [] };
+        }
+
+        // 检测是否有星号（禁止）
+        if (fields.some((f) => f === "*")) {
+            throw new Error("fields 不支持 * 星号，请使用空数组 [] 或不传参数表示查询所有字段");
+        }
+
+        // 检测是否有空字符串或无效值
+        if (fields.some((f) => !f || typeof f !== "string" || f.trim() === "")) {
+            throw new Error("fields 不能包含空字符串或无效值");
+        }
+
+        // 统计包含字段和排除字段
+        const includeFields = fields.filter((f) => !f.startsWith("!"));
+        const excludeFields = fields.filter((f) => f.startsWith("!"));
+
+        // 情况2：全部是包含字段
+        if (includeFields.length > 0 && excludeFields.length === 0) {
+            return { type: "include", fields: includeFields };
+        }
+
+        // 情况3：全部是排除字段
+        if (excludeFields.length > 0 && includeFields.length === 0) {
+            // 去掉感叹号前缀
+            const cleanExcludeFields = excludeFields.map((f) => f.substring(1));
+            return { type: "exclude", fields: cleanExcludeFields };
+        }
+
+        // 混用情况：报错
+        throw new Error('fields 不能同时包含普通字段和排除字段（! 开头）。只能使用以下3种方式之一：\n1. 空数组 [] 或不传（查询所有）\n2. 全部指定字段 ["id", "name"]\n3. 全部排除字段 ["!password", "!token"]');
+    }
+
+    static orderByToSnake(orderBy: string[]): string[] {
+        if (!orderBy || !Array.isArray(orderBy)) {
+            return orderBy;
+        }
+
+        return orderBy.map((item) => {
+            if (typeof item !== "string" || !item.includes("#")) {
+                return item;
+            }
+
+            const [field, direction] = item.split("#");
+            return `${snakeCase(field.trim())}#${direction.trim()}`;
+        });
+    }
+
+    static processJoinField(field: string): string {
+        // 跳过函数、星号、已处理的字段
+        if (field.includes("(") || field === "*" || field.startsWith("`")) {
+            return field;
+        }
+
+        // 处理别名 AS
+        if (field.toUpperCase().includes(" AS ")) {
+            const parts = field.split(/\s+AS\s+/i);
+            const fieldPart = parts[0].trim();
+            const aliasPart = parts[1].trim();
+            return `${DbUtils.processJoinField(fieldPart)} AS ${aliasPart}`;
+        }
+
+        // 处理表别名.字段名（JOIN 模式下，点号前面通常是别名，不应被 snakeCase 改写）
+        if (field.includes(".")) {
+            const parts = field.split(".");
+            const tableName = parts[0];
+            const fieldName = parts[1];
+            return `${tableName.trim()}.${snakeCase(fieldName)}`;
+        }
+
+        // 普通字段
+        return snakeCase(field);
+    }
+
+    static processJoinWhereKey(key: string): string {
+        // 保留逻辑操作符
+        if (key === "$or" || key === "$and") {
+            return key;
+        }
+
+        // 处理带操作符的字段名（如 user.userId$gt）
+        if (key.includes("$")) {
+            const lastDollarIndex = key.lastIndexOf("$");
+            const fieldPart = key.substring(0, lastDollarIndex);
+            const operator = key.substring(lastDollarIndex);
+
+            if (fieldPart.includes(".")) {
+                const parts = fieldPart.split(".");
+                const tableName = parts[0];
+                const fieldName = parts[1];
+                return `${tableName.trim()}.${snakeCase(fieldName)}${operator}`;
+            }
+
+            return `${snakeCase(fieldPart)}${operator}`;
+        }
+
+        // 处理表名.字段名
+        if (key.includes(".")) {
+            const parts = key.split(".");
+            const tableName = parts[0];
+            const fieldName = parts[1];
+            return `${tableName.trim()}.${snakeCase(fieldName)}`;
+        }
+
+        // 普通字段
+        return snakeCase(key);
+    }
+
+    static processJoinWhere(where: any): any {
+        if (!where || typeof where !== "object") {
+            return where;
+        }
+
+        if (Array.isArray(where)) {
+            return where.map((item) => DbUtils.processJoinWhere(item));
+        }
+
+        const result: any = {};
+        for (const [key, value] of Object.entries(where)) {
+            const newKey = DbUtils.processJoinWhereKey(key);
+
+            if (key === "$or" || key === "$and") {
+                result[newKey] = (value as any[]).map((item) => DbUtils.processJoinWhere(item));
+            } else if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+                result[newKey] = DbUtils.processJoinWhere(value);
+            } else {
+                result[newKey] = value;
+            }
+        }
+
+        return result;
+    }
+
+    static processJoinOrderBy(orderBy: string[]): string[] {
+        if (!orderBy || !Array.isArray(orderBy)) {
+            return orderBy;
+        }
+
+        return orderBy.map((item) => {
+            if (typeof item !== "string" || !item.includes("#")) {
+                return item;
+            }
+
+            const [field, direction] = item.split("#");
+            return `${DbUtils.processJoinField(field.trim())}#${direction.trim()}`;
+        });
+    }
+
+    static addDefaultStateFilter(where: WhereConditions = {}, table?: string, hasJoins: boolean = false): WhereConditions {
+        // 如果用户已经指定了 state 条件，优先使用用户的条件
+        const hasStateCondition = Object.keys(where).some((key) => key.startsWith("state") || key.includes(".state"));
+
+        if (hasStateCondition) {
+            return where;
+        }
+
+        // JOIN 查询时需要指定主表名前缀避免歧义
+        if (hasJoins && table) {
+            // table 可能带别名（"order o"），这里只需要别名/主表引用本身，不做 snakeCase 改写
+            const result: any = {};
+            for (const [key, value] of Object.entries(where)) {
+                result[key] = value;
+            }
+            result[`${table}.state$gt`] = 0;
+            return result;
+        }
+
+        // 默认查询 state > 0 的数据
+        const result: any = {};
+        for (const [key, value] of Object.entries(where)) {
+            result[key] = value;
+        }
+        result.state$gt = 0;
+        return result;
+    }
+
+    /**
+     * Where 条件键名转下划线格式（递归处理嵌套）
+     * 支持操作符字段（如 userId$gt）和逻辑操作符（$or, $and）
+     */
+    static whereKeysToSnake(where: any): any {
+        if (!where || typeof where !== "object") {
+            return where;
+        }
+
+        // 处理数组（$or, $and 等）
+        if (Array.isArray(where)) {
+            return where.map((item) => DbUtils.whereKeysToSnake(item));
+        }
+
+        const result: any = {};
+        for (const [key, value] of Object.entries(where)) {
+            // 保留 $or, $and 等逻辑操作符
+            if (key === "$or" || key === "$and") {
+                result[key] = (value as any[]).map((item) => DbUtils.whereKeysToSnake(item));
+                continue;
+            }
+
+            // 处理带操作符的字段名（如 userId$gt）
+            if (key.includes("$")) {
+                const lastDollarIndex = key.lastIndexOf("$");
+                const fieldName = key.substring(0, lastDollarIndex);
+                const operator = key.substring(lastDollarIndex);
+                const snakeKey = snakeCase(fieldName) + operator;
+                result[snakeKey] = value;
+                continue;
+            }
+
+            // 普通字段：转换键名，递归处理值（支持嵌套对象）
+            const snakeKey = snakeCase(key);
+            if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+                result[snakeKey] = DbUtils.whereKeysToSnake(value);
+            } else {
+                result[snakeKey] = value;
+            }
+        }
+
+        return result;
+    }
+
+    /**
+     * 序列化数组字段（写入数据库前）
+     * 将数组类型的字段转换为 JSON 字符串
+     */
+    static serializeArrayFields(data: Record<string, any>): Record<string, any> {
+        const serialized: Record<string, any> = {};
+
+        for (const [key, value] of Object.entries(data)) {
+            if (value === null || value === undefined) {
+                serialized[key] = value;
+                continue;
+            }
+
+            if (Array.isArray(value)) {
+                serialized[key] = JSON.stringify(value);
+                continue;
+            }
+
+            serialized[key] = value;
+        }
+
+        return serialized;
+    }
+
+    /**
+     * 反序列化数组字段（从数据库读取后）
+     * 将 JSON 字符串转换回数组
+     */
+    static deserializeArrayFields<T = any>(data: Record<string, any> | null): T | null {
+        if (!data) {
+            return null;
+        }
+
+        const deserialized: Record<string, any> = {};
+        for (const [key, value] of Object.entries(data)) {
+            deserialized[key] = value;
+        }
+
+        for (const [key, value] of Object.entries(deserialized)) {
+            if (typeof value !== "string") {
+                continue;
+            }
+
+            if (value.startsWith("[") && value.endsWith("]")) {
+                try {
+                    const parsed = JSON.parse(value);
+                    if (Array.isArray(parsed)) {
+                        deserialized[key] = parsed;
+                    }
+                } catch {
+                    // 解析失败则保持原值
+                }
+            }
+        }
+
+        return deserialized as T;
+    }
+
+    static cleanAndSnakeAndSerializeWriteData(data: Record<string, any>, excludeValues: any[] = [null, undefined]): Record<string, any> {
+        const cleanData = fieldClear(data, { excludeValues: excludeValues });
+        const snakeData = keysToSnake(cleanData);
+        return DbUtils.serializeArrayFields(snakeData);
+    }
+
+    static stripSystemFieldsForWrite(data: Record<string, any>, options: { allowState: boolean }): Record<string, any> {
+        const result: Record<string, any> = {};
+        for (const [key, value] of Object.entries(data)) {
+            // 系统字段不可由用户覆盖
+            if (key === "id") continue;
+            if (key === "created_at") continue;
+            if (key === "updated_at") continue;
+            if (key === "deleted_at") continue;
+            if (!options.allowState && key === "state") continue;
+            result[key] = value;
+        }
+
+        return result;
+    }
+
+    static buildInsertRow(options: { data: Record<string, any>; id: number; now: number }): Record<string, any> {
+        const serializedData = DbUtils.cleanAndSnakeAndSerializeWriteData(options.data);
+        const userData = DbUtils.stripSystemFieldsForWrite(serializedData, { allowState: false });
+
+        const result: Record<string, any> = {};
+        for (const [key, value] of Object.entries(userData)) {
+            result[key] = value;
+        }
+
+        result.id = options.id;
+        result.created_at = options.now;
+        result.updated_at = options.now;
+        result.state = 1;
+        return result;
+    }
+
+    static buildUpdateRow(options: { data: Record<string, any>; now: number; allowState: boolean }): Record<string, any> {
+        const serializedData = DbUtils.cleanAndSnakeAndSerializeWriteData(options.data);
+        const userData = DbUtils.stripSystemFieldsForWrite(serializedData, { allowState: options.allowState });
+
+        const result: Record<string, any> = {};
+        for (const [key, value] of Object.entries(userData)) {
+            result[key] = value;
+        }
+        result.updated_at = options.now;
+        return result;
+    }
+
+    static buildPartialUpdateData(options: { data: Record<string, any>; allowState: boolean }): Record<string, any> {
+        const serializedData = DbUtils.cleanAndSnakeAndSerializeWriteData(options.data);
+        return DbUtils.stripSystemFieldsForWrite(serializedData, { allowState: options.allowState });
+    }
+}

package/lib/logger.ts

@@ -4,8 +4,9 @@
 
 import type { LoggerConfig } from "../types/logger.js";
 
+import { existsSync, mkdirSync } from "node:fs";
 import { readdir, stat, unlink } from "node:fs/promises";
-import { join as nodePathJoin } from "node:path";
+import { isAbsolute as nodePathIsAbsolute, join as nodePathJoin, resolve as nodePathResolve } from "node:path";
 
 import { isPlainObject } from "es-toolkit/compat";
 import { escapeRegExp } from "es-toolkit/string";
@@ -14,6 +15,10 @@ import pino from "pino";
 
 import { getCtx } from "./asyncContext.js";
 
+// 注意：Logger 可能在运行时/测试中被 process.chdir() 影响。
+// 为避免相对路径的 logs 目录随着 cwd 变化，使用模块加载时的初始 cwd 作为锚点。
+const INITIAL_CWD = process.cwd();
+
 const MAX_LOG_STRING_LEN = 100;
 const MAX_LOG_ARRAY_ITEMS = 100;
 
@@ -32,6 +37,7 @@ let slowInstance: pino.Logger | null = null;
 let errorInstance: pino.Logger | null = null;
 let mockInstance: pino.Logger | null = null;
 let didPruneOldLogFiles: boolean = false;
+let didEnsureLogDir: boolean = false;
 let config: LoggerConfig = {
     debug: 0,
     dir: "./logs",
@@ -39,11 +45,34 @@ let config: LoggerConfig = {
     maxSize: 10
 };
 
+function resolveLogDir(): string {
+    const rawDir = config.dir || "./logs";
+    if (nodePathIsAbsolute(rawDir)) {
+        return rawDir;
+    }
+    return nodePathResolve(INITIAL_CWD, rawDir);
+}
+
+function ensureLogDirExists(): void {
+    if (didEnsureLogDir) return;
+    didEnsureLogDir = true;
+
+    const dir = resolveLogDir();
+    try {
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+    } catch (error: any) {
+        // 不能在 Logger 初始化前调用 Logger 本身，直接抛错即可
+        throw new Error(`创建 logs 目录失败: ${dir}. ${error?.message || error}`);
+    }
+}
+
 async function pruneOldLogFiles(): Promise<void> {
     if (didPruneOldLogFiles) return;
     didPruneOldLogFiles = true;
 
-    const dir = config.dir || "./logs";
+    const dir = resolveLogDir();
     const now = Date.now();
     const cutoff = now - ONE_YEAR_MS;
 
@@ -90,6 +119,7 @@ export function configure(cfg: LoggerConfig): void {
     slowInstance = null;
     errorInstance = null;
     didPruneOldLogFiles = false;
+    didEnsureLogDir = false;
 
     // 仅支持数组配置：excludeFields?: string[]
     const userPatterns = Array.isArray(config.excludeFields) ? config.excludeFields : [];
@@ -172,6 +202,8 @@ export function getLogger(): pino.Logger {
 
     if (instance) return instance;
 
+    ensureLogDirExists();
+
     // 启动时清理过期日志（异步，不阻塞初始化）
     void pruneOldLogFiles();
 
@@ -183,7 +215,7 @@ export function getLogger(): pino.Logger {
         target: "pino-roll",
         level: level,
         options: {
-            file: join(config.dir || "./logs", "app"),
+            file: join(resolveLogDir(), "app"),
             frequency: "daily",
             size: `${config.maxSize || 10}m`,
             mkdir: true,
@@ -212,6 +244,8 @@ function getSlowLogger(): pino.Logger {
     if (mockInstance) return mockInstance;
     if (slowInstance) return slowInstance;
 
+    ensureLogDirExists();
+
     void pruneOldLogFiles();
 
     const level = config.debug === 1 ? "debug" : "info";
@@ -223,7 +257,7 @@ function getSlowLogger(): pino.Logger {
                     target: "pino-roll",
                     level: level,
                     options: {
-                        file: join(config.dir || "./logs", "slow"),
+                        file: join(resolveLogDir(), "slow"),
                         // 只按大小分割（frequency 默认不启用）
                         size: `${config.maxSize || 10}m`,
                         mkdir: true
@@ -240,6 +274,8 @@ function getErrorLogger(): pino.Logger {
     if (mockInstance) return mockInstance;
     if (errorInstance) return errorInstance;
 
+    ensureLogDirExists();
+
     void pruneOldLogFiles();
 
     // error 专属文件：只关注 error 及以上
@@ -251,7 +287,7 @@ function getErrorLogger(): pino.Logger {
                     target: "pino-roll",
                     level: "error",
                     options: {
-                        file: join(config.dir || "./logs", "error"),
+                        file: join(resolveLogDir(), "error"),
                         // 只按大小分割（frequency 默认不启用）
                         size: `${config.maxSize || 10}m`,
                         mkdir: true

package/lib/redisHelper.ts

@@ -10,6 +10,7 @@ import { Logger } from "./logger.js";
 
 /**
  * Redis 助手类
+ * 约定：除构造函数外，方法默认不抛异常；失败时返回 null/false/0/[] 并记录日志。
  */
 export class RedisHelper {
     private client: RedisClient;