befly 3.10.11 → 3.10.13

package/befly.config.ts

@@ -26,7 +26,9 @@ const defaultOptions: BeflyOptions = {
         excludeFields: ["password", "token", "secret"],
         dir: "./logs",
         console: 1,
-        maxSize: 10485760 // 10MB
+        maxSize: 10485760, // 10MB
+        maxStringLen: 100,
+        maxArrayItems: 100
     },
 
     // ========== 数据库配置 ==========
@@ -37,7 +39,8 @@ const defaultOptions: BeflyOptions = {
         username: "root",
         password: "root",
         database: "befly_demo",
-        poolMax: 10
+        poolMax: 10,
+        debug: 0
     },
 
     // ========== Redis 配置 ==========

package/lib/dbHelper.ts

@@ -36,16 +36,18 @@ export class DbHelper {
     private dialect: DbDialect;
     private sql: any = null;
     private isTransaction: boolean = false;
+    private debug: number = 0;
 
     /**
      * 构造函数
      * @param redis - Redis 实例
      * @param sql - Bun SQL 客户端（可选，用于事务）
      */
-    constructor(options: { redis: RedisCacheLike; sql?: any | null; dialect?: DbDialect }) {
+    constructor(options: { redis: RedisCacheLike; sql?: any | null; dialect?: DbDialect; debug?: number }) {
         this.redis = options.redis;
         this.sql = options.sql || null;
         this.isTransaction = !!options.sql;
+        this.debug = options.debug === 1 ? 1 : 0;
 
         // 默认使用 MySQL 方言（当前 core 的表结构/语法也主要基于 MySQL）
         this.dialect = options.dialect ? options.dialect : new MySqlDialect();
@@ -182,12 +184,28 @@ export class DbHelper {
             // 计算执行时间
             const duration = Date.now() - startTime;
 
+            if (this.debug === 1) {
+                Logger.debug(
+                    {
+                        subsystem: "db",
+                        event: "db_sql",
+                        dbEvent: "query",
+                        duration: duration,
+                        sqlPreview: sqlStr,
+                        paramsCount: (params || []).length,
+                        params: params || []
+                    },
+                    "DB"
+                );
+            }
+
             // 慢查询警告（超过 5000ms）
             if (duration > 5000) {
                 Logger.warn(
                     {
                         subsystem: "db",
-                        event: "slow",
+                        event: "db_sql",
+                        dbEvent: "slow",
                         duration: duration,
                         sqlPreview: sqlStr,
                         params: params || [],
@@ -200,12 +218,13 @@ export class DbHelper {
             return result;
         } catch (error: any) {
             const duration = Date.now() - startTime;
-
-            const sqlPreview = sqlStr.length > 200 ? sqlStr.substring(0, 200) + "..." : sqlStr;
             Logger.error(
                 {
+                    subsystem: "db",
+                    event: "db_sql",
+                    dbEvent: "error",
                     err: error,
-                    sqlPreview: sqlPreview,
+                    sqlPreview: sqlStr,
                     params: params || [],
                     duration: duration
                 },
@@ -751,7 +770,7 @@ export class DbHelper {
         // 使用 Bun SQL 的 begin 方法开启事务
         // begin 方法会自动处理 commit/rollback
         return await this.sql.begin(async (tx: any) => {
-            const trans = new DbHelper({ redis: this.redis, sql: tx, dialect: this.dialect });
+            const trans = new DbHelper({ redis: this.redis, sql: tx, dialect: this.dialect, debug: this.debug });
             return await callback(trans);
         });
     }

package/lib/logger.ts

@@ -19,8 +19,21 @@ import { getCtx } from "./asyncContext.js";
 // 为避免相对路径的 logs 目录随着 cwd 变化，使用模块加载时的初始 cwd 作为锚点。
 const INITIAL_CWD = process.cwd();
 
-const MAX_LOG_STRING_LEN = 100;
-const MAX_LOG_ARRAY_ITEMS = 100;
+const DEFAULT_LOG_STRING_LEN = 100;
+const DEFAULT_LOG_ARRAY_ITEMS = 100;
+
+let maxLogStringLen = DEFAULT_LOG_STRING_LEN;
+let maxLogArrayItems = DEFAULT_LOG_ARRAY_ITEMS;
+
+// 为避免递归导致栈溢出/性能抖动：使用非递归遍历，并对深度/节点数做硬限制。
+// 说明：这不是业务数据结构的“真实深度”，而是日志清洗的最大深入层级（越大越重）。
+const DEFAULT_LOG_SANITIZE_DEPTH = 3;
+const DEFAULT_LOG_OBJECT_KEYS = 100;
+const DEFAULT_LOG_SANITIZE_NODES = 500;
+
+let sanitizeDepthLimit = DEFAULT_LOG_SANITIZE_DEPTH;
+let sanitizeObjectKeysLimit = DEFAULT_LOG_OBJECT_KEYS;
+let sanitizeNodesLimit = DEFAULT_LOG_SANITIZE_NODES;
 
 const ONE_YEAR_MS = 365 * 24 * 60 * 60 * 1000;
 
@@ -45,6 +58,15 @@ let config: LoggerConfig = {
     maxSize: 10
 };
 
+function normalizePositiveInt(value: any, fallback: number, min: number, max: number): number {
+    if (typeof value !== "number") return fallback;
+    if (!Number.isFinite(value)) return fallback;
+    const v = Math.floor(value);
+    if (v < min) return fallback;
+    if (v > max) return max;
+    return v;
+}
+
 function resolveLogDir(): string {
     const rawDir = config.dir || "./logs";
     if (nodePathIsAbsolute(rawDir)) {
@@ -121,6 +143,15 @@ export function configure(cfg: LoggerConfig): void {
     didPruneOldLogFiles = false;
     didEnsureLogDir = false;
 
+    // 运行时清洗上限（可配置）
+    sanitizeDepthLimit = normalizePositiveInt(config.sanitizeDepth, DEFAULT_LOG_SANITIZE_DEPTH, 1, 10);
+    sanitizeNodesLimit = normalizePositiveInt(config.sanitizeNodes, DEFAULT_LOG_SANITIZE_NODES, 50, 20000);
+    sanitizeObjectKeysLimit = normalizePositiveInt(config.sanitizeObjectKeys, DEFAULT_LOG_OBJECT_KEYS, 10, 5000);
+
+    // 运行时截断上限（可配置）
+    maxLogStringLen = normalizePositiveInt(config.maxStringLen, DEFAULT_LOG_STRING_LEN, 20, 200000);
+    maxLogArrayItems = normalizePositiveInt(config.maxArrayItems, DEFAULT_LOG_ARRAY_ITEMS, 10, 5000);
+
     // 仅支持数组配置：excludeFields?: string[]
     const userPatterns = Array.isArray(config.excludeFields) ? config.excludeFields : [];
     const patterns = [...BUILTIN_SENSITIVE_KEYS, ...userPatterns]
@@ -301,12 +332,34 @@ function getErrorLogger(): pino.Logger {
 }
 
 function truncateString(val: string, stats: Record<string, number>): string {
-    if (val.length <= MAX_LOG_STRING_LEN) return val;
+    if (val.length <= maxLogStringLen) return val;
     stats.truncatedStrings = (stats.truncatedStrings || 0) + 1;
-    return val.slice(0, MAX_LOG_STRING_LEN);
+    return val.slice(0, maxLogStringLen);
+}
+
+function isSensitiveKey(key: string): boolean {
+    const lower = String(key).toLowerCase();
+    if (sensitiveKeySet.has(lower)) return true;
+
+    for (const suffix of sensitiveSuffixMatchers) {
+        if (lower.endsWith(suffix)) return true;
+    }
+    for (const prefix of sensitivePrefixMatchers) {
+        if (lower.startsWith(prefix)) return true;
+    }
+
+    if (sensitiveContainsRegex) {
+        return sensitiveContainsRegex.test(lower);
+    }
+
+    for (const part of sensitiveContainsMatchers) {
+        if (lower.includes(part)) return true;
+    }
+
+    return false;
 }
 
-function safeToString(val: any, visited: WeakSet<object>, stats: Record<string, number>): string {
+function safeToStringMasked(val: any, visited: WeakSet<object>, stats: Record<string, number>): string {
     if (typeof val === "string") return val;
 
     if (val instanceof Error) {
@@ -334,7 +387,13 @@ function safeToString(val: any, visited: WeakSet<object>, stats: Record<string,
 
     try {
         const localVisited = visited;
-        const replacer = (_k: string, v: any) => {
+        const replacer = (k: string, v: any) => {
+            // JSON.stringify 的根节点 key 为空字符串
+            if (k && isSensitiveKey(k)) {
+                stats.maskedKeys = (stats.maskedKeys || 0) + 1;
+                return "[MASKED]";
+            }
+
             if (v && typeof v === "object") {
                 if (localVisited.has(v as object)) {
                     stats.circularRefs = (stats.circularRefs || 0) + 1;
@@ -354,29 +413,24 @@ function safeToString(val: any, visited: WeakSet<object>, stats: Record<string,
     }
 }
 
-function isSensitiveKey(key: string): boolean {
-    const lower = String(key).toLowerCase();
-    if (sensitiveKeySet.has(lower)) return true;
-
-    for (const suffix of sensitiveSuffixMatchers) {
-        if (lower.endsWith(suffix)) return true;
-    }
-    for (const prefix of sensitivePrefixMatchers) {
-        if (lower.startsWith(prefix)) return true;
-    }
-
-    if (sensitiveContainsRegex) {
-        return sensitiveContainsRegex.test(lower);
-    }
-
-    for (const part of sensitiveContainsMatchers) {
-        if (lower.includes(part)) return true;
+function sanitizeErrorValue(err: Error, stats: Record<string, number>): Record<string, any> {
+    const errObj: Record<string, any> = {
+        name: err.name || "Error",
+        message: truncateString(err.message || "", stats)
+    };
+    if (typeof err.stack === "string") {
+        errObj.stack = truncateString(err.stack, stats);
     }
+    return errObj;
+}
 
-    return false;
+function stringifyPreview(val: any, visited: WeakSet<object>, stats: Record<string, number>): string {
+    stats.valuesStringified = (stats.valuesStringified || 0) + 1;
+    const str = safeToStringMasked(val, visited, stats);
+    return truncateString(str, stats);
 }
 
-function sanitizeNestedValue(val: any, visited: WeakSet<object>, stats: Record<string, number>): any {
+function sanitizeValueLimited(val: any, visited: WeakSet<object>, stats: Record<string, number>): any {
     if (val === null || val === undefined) return val;
     if (typeof val === "string") return truncateString(val, stats);
     if (typeof val === "number") return val;
@@ -384,113 +438,139 @@ function sanitizeNestedValue(val: any, visited: WeakSet<object>, stats: Record<s
     if (typeof val === "bigint") return val;
 
     if (val instanceof Error) {
-        const errObj: Record<string, any> = {
-            name: val.name || "Error",
-            message: truncateString(val.message || "", stats)
-        };
-        if (typeof val.stack === "string") {
-            errObj.stack = truncateString(val.stack, stats);
-        }
-        return errObj;
+        return sanitizeErrorValue(val, stats);
     }
 
-    // 对象/数组：不再深入，转为字符串并截断
-    stats.valuesStringified = (stats.valuesStringified || 0) + 1;
-    const str = safeToString(val, visited, stats);
-    return truncateString(str, stats);
-}
+    // 仅支持数组 + plain object 的结构化清洗，其余类型走字符串预览。
+    const isArr = Array.isArray(val);
+    const isObj = isPlainObject(val);
+    if (!isArr && !isObj) {
+        return stringifyPreview(val, visited, stats);
+    }
 
-function sanitizeObjectFirstLayer(obj: Record<string, any>, visited: WeakSet<object>, stats: Record<string, number>): Record<string, any> {
-    if (visited.has(obj)) {
+    // 防环（根节点）
+    if (visited.has(val as object)) {
         stats.circularRefs = (stats.circularRefs || 0) + 1;
-        return { value: "[Circular]" };
+        return "[Circular]";
     }
-    visited.add(obj);
+    visited.add(val as object);
 
-    const out: Record<string, any> = {};
-    for (const [key, val] of Object.entries(obj)) {
-        if (isSensitiveKey(key)) {
-            stats.maskedKeys = (stats.maskedKeys || 0) + 1;
-            out[key] = "[MASKED]";
-            continue;
+    const rootOut: any = isArr ? [] : {};
+
+    type Frame = { src: any; dst: any; depth: number };
+    const stack: Frame[] = [{ src: val, dst: rootOut, depth: 1 }];
+
+    let nodes = 0;
+
+    const tryAssign = (dst: any, key: string | number, child: any, depth: number) => {
+        if (child === null || child === undefined) {
+            dst[key] = child;
+            return;
+        }
+        if (typeof child === "string") {
+            dst[key] = truncateString(child, stats);
+            return;
+        }
+        if (typeof child === "number" || typeof child === "boolean" || typeof child === "bigint") {
+            dst[key] = child;
+            return;
+        }
+        if (child instanceof Error) {
+            dst[key] = sanitizeErrorValue(child, stats);
+            return;
         }
-        out[key] = sanitizeNestedValue(val, visited, stats);
-    }
-    return out;
-}
 
-function sanitizeArray(arr: any[], visited: WeakSet<object>, stats: Record<string, number>): any[] {
-    const max = MAX_LOG_ARRAY_ITEMS;
-    const len = arr.length;
-    const limit = len > max ? max : len;
+        const childIsArr = Array.isArray(child);
+        const childIsObj = isPlainObject(child);
 
-    const out: any[] = [];
-    for (let i = 0; i < limit; i++) {
-        const item = arr[i];
-        if (item && typeof item === "object" && !Array.isArray(item) && !(item instanceof Error)) {
-            out.push(sanitizeObjectFirstLayer(item as Record<string, any>, visited, stats));
-            continue;
+        if (!childIsArr && !childIsObj) {
+            dst[key] = stringifyPreview(child, visited, stats);
+            return;
         }
-        if (item instanceof Error) {
-            const errObj: Record<string, any> = {
-                name: item.name || "Error",
-                message: truncateString(item.message || "", stats)
-            };
-            if (typeof item.stack === "string") {
-                errObj.stack = truncateString(item.stack, stats);
-            }
-            out.push(errObj);
-            continue;
+
+        // 深度/节点数上限：超出则降级为字符串预览
+        if (depth >= sanitizeDepthLimit) {
+            stats.depthLimited = (stats.depthLimited || 0) + 1;
+            dst[key] = stringifyPreview(child, visited, stats);
+            return;
         }
-        if (typeof item === "string") {
-            out.push(truncateString(item, stats));
-            continue;
+        if (nodes >= sanitizeNodesLimit) {
+            stats.nodesLimited = (stats.nodesLimited || 0) + 1;
+            dst[key] = stringifyPreview(child, visited, stats);
+            return;
         }
-        if (typeof item === "number" || typeof item === "boolean" || item === null || item === undefined) {
-            out.push(item);
-            continue;
+
+        // 防环
+        if (visited.has(child as object)) {
+            stats.circularRefs = (stats.circularRefs || 0) + 1;
+            dst[key] = "[Circular]";
+            return;
+        }
+        visited.add(child as object);
+
+        const childOut: any = childIsArr ? [] : {};
+        dst[key] = childOut;
+        stack.push({ src: child, dst: childOut, depth: depth + 1 });
+    };
+
+    while (stack.length > 0) {
+        const frame = stack.pop() as Frame;
+        nodes = nodes + 1;
+        if (nodes > sanitizeNodesLimit) {
+            // 超出节点上限：不再深入（已入栈的节点会被忽略，留空结构由上层兜底预览）。
+            stats.nodesLimited = (stats.nodesLimited || 0) + 1;
+            break;
         }
-        if (typeof item === "bigint") {
-            out.push(item);
+
+        if (Array.isArray(frame.src)) {
+            const arr = frame.src as any[];
+            const len = arr.length;
+            const limit = len > maxLogArrayItems ? maxLogArrayItems : len;
+
+            for (let i = 0; i < limit; i++) {
+                tryAssign(frame.dst, i, arr[i], frame.depth);
+            }
+
+            if (len > maxLogArrayItems) {
+                stats.arraysTruncated = (stats.arraysTruncated || 0) + 1;
+                stats.arrayItemsOmitted = (stats.arrayItemsOmitted || 0) + (len - maxLogArrayItems);
+            }
+
             continue;
         }
 
-        // 其他类型（包含子数组等）转字符串预览
-        stats.valuesStringified = (stats.valuesStringified || 0) + 1;
-        const str = safeToString(item, visited, stats);
-        out.push(truncateString(str, stats));
-    }
+        if (isPlainObject(frame.src)) {
+            const entries = Object.entries(frame.src as Record<string, any>);
+            const len = entries.length;
+            const limit = len > sanitizeObjectKeysLimit ? sanitizeObjectKeysLimit : len;
+
+            for (let i = 0; i < limit; i++) {
+                const key = entries[i][0];
+                const child = entries[i][1];
+                if (isSensitiveKey(key)) {
+                    stats.maskedKeys = (stats.maskedKeys || 0) + 1;
+                    frame.dst[key] = "[MASKED]";
+                    continue;
+                }
+                tryAssign(frame.dst, key, child, frame.depth);
+            }
+
+            if (len > sanitizeObjectKeysLimit) {
+                stats.objectKeysLimited = (stats.objectKeysLimited || 0) + 1;
+                stats.objectKeysOmitted = (stats.objectKeysOmitted || 0) + (len - sanitizeObjectKeysLimit);
+            }
+
+            continue;
+        }
 
-    if (len > max) {
-        stats.arraysTruncated = (stats.arraysTruncated || 0) + 1;
-        stats.arrayItemsOmitted = (stats.arrayItemsOmitted || 0) + (len - max);
+        // 兜底：理论上不会到这里（frame 只会压入 array/plain object）
     }
 
-    return out;
+    return rootOut;
 }
 
 function sanitizeTopValue(val: any, visited: WeakSet<object>, stats: Record<string, number>): any {
-    if (val === null || val === undefined) return val;
-    if (typeof val === "string") return truncateString(val, stats);
-    if (typeof val === "number") return val;
-    if (typeof val === "boolean") return val;
-    if (typeof val === "bigint") return val;
-    if (val instanceof Error) {
-        const errObj: Record<string, any> = {
-            name: val.name || "Error",
-            message: truncateString(val.message || "", stats)
-        };
-        if (typeof val.stack === "string") {
-            errObj.stack = truncateString(val.stack, stats);
-        }
-        return errObj;
-    }
-    if (Array.isArray(val)) return sanitizeArray(val, visited, stats);
-    if (isPlainObject(val)) return sanitizeObjectFirstLayer(val as Record<string, any>, visited, stats);
-
-    stats.valuesStringified = (stats.valuesStringified || 0) + 1;
-    const str = safeToString(val, visited, stats);
-    return truncateString(str, stats);
+    return sanitizeValueLimited(val, visited, stats);
 }
 
 function sanitizeLogObject(obj: Record<string, any>): Record<string, any> {
@@ -501,7 +581,11 @@ function sanitizeLogObject(obj: Record<string, any>): Record<string, any> {
         arraysTruncated: 0,
         arrayItemsOmitted: 0,
         valuesStringified: 0,
-        circularRefs: 0
+        circularRefs: 0,
+        depthLimited: 0,
+        nodesLimited: 0,
+        objectKeysLimited: 0,
+        objectKeysOmitted: 0
     };
 
     const out: Record<string, any> = {};
@@ -514,7 +598,8 @@ function sanitizeLogObject(obj: Record<string, any>): Record<string, any> {
         out[key] = sanitizeTopValue(val, visited, stats);
     }
 
-    const hasChanges = stats.maskedKeys > 0 || stats.truncatedStrings > 0 || stats.arraysTruncated > 0 || stats.arrayItemsOmitted > 0 || stats.valuesStringified > 0 || stats.circularRefs > 0;
+    const hasChanges =
+        stats.maskedKeys > 0 || stats.truncatedStrings > 0 || stats.arraysTruncated > 0 || stats.arrayItemsOmitted > 0 || stats.valuesStringified > 0 || stats.circularRefs > 0 || stats.depthLimited > 0 || stats.nodesLimited > 0 || stats.objectKeysLimited > 0 || stats.objectKeysOmitted > 0;
 
     if (hasChanges) {
         out.logTrimStats = {
@@ -523,7 +608,11 @@ function sanitizeLogObject(obj: Record<string, any>): Record<string, any> {
             arraysTruncated: stats.arraysTruncated,
             arrayItemsOmitted: stats.arrayItemsOmitted,
             valuesStringified: stats.valuesStringified,
-            circularRefs: stats.circularRefs
+            circularRefs: stats.circularRefs,
+            depthLimited: stats.depthLimited,
+            nodesLimited: stats.nodesLimited,
+            objectKeysLimited: stats.objectKeysLimited,
+            objectKeysOmitted: stats.objectKeysOmitted
         };
     }
 

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "befly",
-    "version": "3.10.11",
-    "gitHead": "b2a7116ecbf488ef3e7e74c5cb1da1ff33a64f2c",
+    "version": "3.10.13",
+    "gitHead": "391e4e5cacb1d46cf37b5aa1179c9fe0a602337d",
     "private": false,
     "description": "Befly - 为 Bun 专属打造的 TypeScript API 接口框架核心引擎",
     "keywords": [

package/plugins/db.ts

@@ -28,8 +28,11 @@ export default {
             const resolvedDbType = rawDbType === "postgres" ? "postgresql" : rawDbType;
             const dialect = getDialectByName(resolvedDbType === "postgresql" || resolvedDbType === "sqlite" ? resolvedDbType : "mysql");
 
+            const dbDebug = befly.config && befly.config.db ? befly.config.db.debug : undefined;
+            const debug = dbDebug === 1 ? 1 : 0;
+
             // 创建数据库管理器实例
-            const dbManager = new DbHelper({ redis: befly.redis, sql: sql, dialect: dialect });
+            const dbManager = new DbHelper({ redis: befly.redis, sql: sql, dialect: dialect, debug: debug });
 
             return dbManager;
         } catch (error: any) {

package/types/befly.d.ts

@@ -37,6 +37,9 @@ export interface DatabaseConfig {
     database?: string;
     /** 连接池最大连接数 @default 1 */
     poolMax?: number;
+
+    /** 是否打印数据库操作日志 (0: 关闭, 1: 开启) @default 0 */
+    debug?: number;
 }
 
 /**

package/types/logger.d.ts

@@ -27,4 +27,39 @@ export interface LoggerConfig {
     console?: number;
     /** 单个日志文件最大大小 (MB) @default 10 */
     maxSize?: number;
+
+    /**
+     * 字符串最大长度（超过会被截断）
+     * - 影响所有结构化字段中的 string（包括 db.debug 打印的 sqlPreview）
+     * - 生产环境建议保持较小值；需要更完整 SQL 时可在开发环境调大
+     * @default 100
+     */
+    maxStringLen?: number;
+
+    /**
+     * 数组最多保留的元素数量（超出部分丢弃）
+     * - 仅影响结构化日志清洗（数组裁剪）
+     * @default 100
+     */
+    maxArrayItems?: number;
+
+    /**
+     * 结构化日志清洗：最大清洗深度（非递归遍历的 depth 上限）
+     * - 值越大，日志更“完整”，但 CPU/内存开销更高
+     * - 建议：生产环境保持较小值（默认 3），开发环境可调大（例如 5）
+     * @default 3
+     */
+    sanitizeDepth?: number;
+
+    /**
+     * 结构化日志清洗：最大遍历节点数（防止超大对象/数组导致性能抖动）
+     * @default 500
+     */
+    sanitizeNodes?: number;
+
+    /**
+     * 结构化日志清洗：对象最多保留的 key 数（超出部分丢弃）
+     * @default 100
+     */
+    sanitizeObjectKeys?: number;
 }