befly 3.12.4 → 3.13.0

package/dist/types/logger.d.ts

@@ -14,7 +14,7 @@ export interface LoggerConfig {
     dir?: string;
     /** 是否输出到控制台（0/1） */
     console?: LoggerFlag;
-    /** 单文件大小（MB） */
+    /** 单文件最大大小（MB），例如 10 表示 10MB；默认 20MB */
     maxSize?: number;
     /** 日志清洗深度限制（1..10） */
     sanitizeDepth?: number;
@@ -31,17 +31,31 @@ export interface LoggerConfig {
      */
     excludeFields?: string[];
 }
+export type LogLevelName = "debug" | "info" | "warn" | "error";
+export type LoggerRecord = {
+    /** 文本消息（推荐直接放在 record 里） */
+    msg?: string;
+    /** 错误对象（会在运行时被清洗为可序列化结构） */
+    err?: unknown;
+    /** 其他自定义字段 */
+    [key: string]: unknown;
+};
 /**
  * Logger 接口（类型层）。
  *
  * 说明：core/runtime 内部使用的是 Bun 环境的自定义 Logger 实现（异步批量写入）。
- * 对外只承诺常用的 `info/warn/error/debug` 等调用形式（兼容常见 pino 调用风格）。
+ * 对外只承诺常用的 `info/warn/error/debug` 等调用形式（不再兼容 pino 的多签名调用）。
  */
 export interface Logger {
-    info(...args: any[]): any;
-    warn(...args: any[]): any;
-    error(...args: any[]): any;
-    debug(...args: any[]): any;
+    /**
+     * 只接受一个参数（任意类型）：
+     * - plain object（{}）会作为 record 写入
+     * - 其他任何类型会被包装成对象后写入（例如 { msg: "..." } 或 { value: ... }）
+     */
+    info(input: unknown): any;
+    warn(input: unknown): any;
+    error(input: unknown): any;
+    debug(input: unknown): any;
     configure(cfg: LoggerConfig): void;
     setMock(mock: any | null): void;
     /**

package/dist/types/plugin.d.ts

@@ -1,7 +1,18 @@
 /**
  * 插件类型定义
  *
- * 说明：当前 core 插件的默认导出形态是：{ deps?: string[], handler(ctx): any }
+ * 说明：当前 core 插件推荐的默认导出写法（避免声明文件深推导导致的类型问题）：
+ *
+ * const xxxPlugin: Plugin = {
+ *     name: "xxx",
+ *     enable: true,
+ *     deps: [],
+ *     handler: (context) => {
+ *         return any;
+ *     }
+ * };
+ *
+ * export default xxxPlugin;
  */
 import type { BeflyContext } from "./befly";
 export interface Plugin {

package/dist/types/plugin.js

@@ -1,6 +1,17 @@
 /**
  * 插件类型定义
  *
- * 说明：当前 core 插件的默认导出形态是：{ deps?: string[], handler(ctx): any }
+ * 说明：当前 core 插件推荐的默认导出写法（避免声明文件深推导导致的类型问题）：
+ *
+ * const xxxPlugin: Plugin = {
+ *     name: "xxx",
+ *     enable: true,
+ *     deps: [],
+ *     handler: (context) => {
+ *         return any;
+ *     }
+ * };
+ *
+ * export default xxxPlugin;
  */
 export {};

package/dist/utils/formatYmdHms.d.ts

@@ -0,0 +1 @@
+export declare function formatYmdHms(date: Date, format?: "date" | "time" | "dateTime"): string;

package/dist/utils/formatYmdHms.js

@@ -0,0 +1,20 @@
+export function formatYmdHms(date, format = "dateTime") {
+    const y = date.getFullYear();
+    const m = date.getMonth() + 1;
+    const d = date.getDate();
+    const h = date.getHours();
+    const mi = date.getMinutes();
+    const s = date.getSeconds();
+    const mm = m < 10 ? `0${m}` : String(m);
+    const dd = d < 10 ? `0${d}` : String(d);
+    const hh = h < 10 ? `0${h}` : String(h);
+    const mii = mi < 10 ? `0${mi}` : String(mi);
+    const ss = s < 10 ? `0${s}` : String(s);
+    if (format === "date") {
+        return `${y}-${mm}-${dd}`;
+    }
+    if (format === "time") {
+        return `${hh}:${mii}:${ss}`;
+    }
+    return `${y}-${mm}-${dd} ${hh}:${mii}:${ss}`;
+}

package/dist/utils/importDefault.js

@@ -23,7 +23,7 @@ export async function importDefault(file, defaultValue) {
         return value;
     }
     catch (err) {
-        Logger.warn({ err: err, file: file }, "importDefault 导入失败，已回退到默认值");
+        Logger.warn({ err: err, file: file, msg: "importDefault 导入失败，已回退到默认值" });
         return defaultValue;
     }
 }

package/dist/utils/loadMenuConfigs.js

@@ -65,17 +65,17 @@ export async function scanViewsDirToMenuConfigs(viewsDir, prefix, parentPath = "
             const content = await readFile(indexVuePath, "utf-8");
             const scriptSetup = extractScriptSetupBlock(content);
             if (!scriptSetup) {
-                Logger.warn({ path: indexVuePath }, "index.vue 缺少 <script setup>，已跳过该目录菜单同步");
+                Logger.warn({ path: indexVuePath, msg: "index.vue 缺少 <script setup>，已跳过该目录菜单同步" });
                 continue;
             }
             meta = extractDefinePageMetaFromScriptSetup(scriptSetup);
             if (!meta?.title) {
-                Logger.warn({ path: indexVuePath }, "index.vue 未声明 definePage({ meta: { title, order? } })，已跳过该目录菜单同步");
+                Logger.warn({ path: indexVuePath, msg: "index.vue 未声明 definePage({ meta: { title, order? } })，已跳过该目录菜单同步" });
                 continue;
             }
         }
         catch (error) {
-            Logger.warn({ err: error, path: indexVuePath }, "读取 index.vue 失败");
+            Logger.warn({ err: error, path: indexVuePath, msg: "读取 index.vue 失败" });
             continue;
         }
         if (!meta?.title) {
@@ -136,8 +136,9 @@ export async function loadMenuConfigs(addons) {
                 err: error,
                 addon: addon.name,
                 addonSource: addon.source,
-                dir: adminViewsDir
-            }, "扫描 addon views 目录失败");
+                dir: adminViewsDir,
+                msg: "扫描 addon views 目录失败"
+            });
         }
     }
     const menusJsonPath = join(process.cwd(), "menus.json");
@@ -152,7 +153,7 @@ export async function loadMenuConfigs(addons) {
             }
         }
         catch (error) {
-            Logger.warn({ err: error }, "读取项目 menus.json 失败");
+            Logger.warn({ err: error, msg: "读取项目 menus.json 失败" });
         }
     }
     return allMenus;

package/dist/utils/loggerUtils.d.ts

@@ -0,0 +1,18 @@
+export type SensitiveKeyMatcher = {
+    exactSet: Set<string>;
+    contains: string[];
+};
+export type LogSanitizeOptions = {
+    maxStringLen: number;
+    maxArrayItems: number;
+    sanitizeDepth: number;
+    sanitizeNodes: number;
+    sanitizeObjectKeys: number;
+    sensitiveKeyMatcher: SensitiveKeyMatcher;
+};
+export declare function buildSensitiveKeyMatcher(options: {
+    builtinPatterns: string[];
+    userPatterns: unknown;
+}): SensitiveKeyMatcher;
+export declare function isSensitiveKey(key: string, matcher: SensitiveKeyMatcher): boolean;
+export declare function sanitizeLogObject(obj: Record<string, any>, options: LogSanitizeOptions): Record<string, any>;

package/dist/utils/loggerUtils.js

@@ -0,0 +1,167 @@
+import { isPlainObject } from "./util";
+export function buildSensitiveKeyMatcher(options) {
+    const patterns = [];
+    for (const item of options.builtinPatterns) {
+        const trimmed = String(item).trim();
+        if (trimmed.length > 0) {
+            patterns.push(trimmed.toLowerCase());
+        }
+    }
+    if (Array.isArray(options.userPatterns)) {
+        for (const item of options.userPatterns) {
+            const trimmed = String(item).trim();
+            if (trimmed.length > 0) {
+                patterns.push(trimmed.toLowerCase());
+            }
+        }
+    }
+    const exactSet = new Set();
+    const contains = [];
+    for (const pat of patterns) {
+        if (!pat.includes("*")) {
+            exactSet.add(pat);
+            continue;
+        }
+        const core = pat.replace(/\*+/g, "").trim();
+        if (!core) {
+            continue;
+        }
+        contains.push(core);
+    }
+    return { exactSet: exactSet, contains: contains };
+}
+export function isSensitiveKey(key, matcher) {
+    const lower = String(key).toLowerCase();
+    if (matcher.exactSet.has(lower))
+        return true;
+    for (const part of matcher.contains) {
+        if (lower.includes(part))
+            return true;
+    }
+    return false;
+}
+function truncateString(value, maxLen) {
+    if (value.length <= maxLen)
+        return value;
+    return value.slice(0, maxLen);
+}
+function sanitizeErrorValue(err, options) {
+    const out = {
+        name: err.name || "Error",
+        message: truncateString(err.message || "", options.maxStringLen)
+    };
+    if (typeof err.stack === "string") {
+        out.stack = truncateString(err.stack, options.maxStringLen);
+    }
+    return out;
+}
+function safeToStringMasked(value, options, visited) {
+    if (typeof value === "string")
+        return value;
+    if (value instanceof Error) {
+        try {
+            return JSON.stringify(sanitizeErrorValue(value, options));
+        }
+        catch {
+            return `${value.name || "Error"}: ${value.message || ""}`;
+        }
+    }
+    if (value && typeof value === "object") {
+        if (visited.has(value)) {
+            return "[Circular]";
+        }
+    }
+    try {
+        const localVisited = visited;
+        const replacer = (k, v) => {
+            if (k && isSensitiveKey(k, options.sensitiveKeyMatcher)) {
+                return "[MASKED]";
+            }
+            if (v && typeof v === "object") {
+                if (localVisited.has(v)) {
+                    return "[Circular]";
+                }
+                localVisited.add(v);
+            }
+            return v;
+        };
+        return JSON.stringify(value, replacer);
+    }
+    catch {
+        try {
+            return String(value);
+        }
+        catch {
+            return "[Unserializable]";
+        }
+    }
+}
+function stringifyPreview(value, options, visited) {
+    const s = safeToStringMasked(value, options, visited);
+    return truncateString(s, options.maxStringLen);
+}
+function sanitizeAny(value, options, state, depth, visited) {
+    if (value === null || value === undefined)
+        return value;
+    if (typeof value === "string") {
+        return truncateString(value, options.maxStringLen);
+    }
+    if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
+        return value;
+    }
+    if (value instanceof Error) {
+        return sanitizeErrorValue(value, options);
+    }
+    const isArr = Array.isArray(value);
+    const isObj = isPlainObject(value);
+    if (!isArr && !isObj) {
+        return stringifyPreview(value, options, visited);
+    }
+    if (visited.has(value)) {
+        return "[Circular]";
+    }
+    if (depth >= options.sanitizeDepth) {
+        return stringifyPreview(value, options, visited);
+    }
+    if (state.nodes >= options.sanitizeNodes) {
+        return stringifyPreview(value, options, visited);
+    }
+    visited.add(value);
+    state.nodes = state.nodes + 1;
+    if (isArr) {
+        const arr = value;
+        const out = [];
+        const limit = arr.length > options.maxArrayItems ? options.maxArrayItems : arr.length;
+        for (let i = 0; i < limit; i++) {
+            out[i] = sanitizeAny(arr[i], options, state, depth + 1, visited);
+        }
+        return out;
+    }
+    const obj = value;
+    const out = {};
+    const entries = Object.entries(obj);
+    const limit = entries.length > options.sanitizeObjectKeys ? options.sanitizeObjectKeys : entries.length;
+    for (let i = 0; i < limit; i++) {
+        const key = entries[i][0];
+        const child = entries[i][1];
+        if (isSensitiveKey(key, options.sensitiveKeyMatcher)) {
+            out[key] = "[MASKED]";
+            continue;
+        }
+        out[key] = sanitizeAny(child, options, state, depth + 1, visited);
+    }
+    return out;
+}
+export function sanitizeLogObject(obj, options) {
+    const visited = new WeakSet();
+    const state = { nodes: 0 };
+    const out = {};
+    for (const [key, val] of Object.entries(obj)) {
+        if (isSensitiveKey(key, options.sensitiveKeyMatcher)) {
+            out[key] = "[MASKED]";
+            continue;
+        }
+        out[key] = sanitizeAny(val, options, state, 0, visited);
+    }
+    return out;
+}

package/dist/utils/response.js

@@ -19,8 +19,9 @@ export function ErrorResponse(ctx, msg, code = 1, data = null, detail = null, re
             reason: msg,
             reasonCode: reasonCode,
             code: code,
-            detail: detail
-        }, "request blocked");
+            detail: detail,
+            msg: "request blocked"
+        });
     }
     return Response.json({
         code: code,
@@ -42,8 +43,9 @@ export function FinalResponse(ctx) {
     if (ctx.api && ctx.requestId) {
         // requestId/route/user/duration 等字段由 ALS 统一注入，避免在 msg 中重复拼接
         Logger.info({
-            event: "request_done"
-        }, "request done");
+            event: "request_done",
+            msg: "request done"
+        });
     }
     // 1. 如果已经有 response，直接返回
     if (ctx.response) {

package/dist/utils/sortModules.js

@@ -28,7 +28,7 @@ export function sortModules(items, options = {}) {
     for (const item of items) {
         const name = getName(item);
         if (typeof name !== "string" || name.trim() === "") {
-            Logger.error({ item: item }, `${moduleLabel} 名称解析失败（getName 返回空字符串）`);
+            Logger.error({ item: item, msg: `${moduleLabel} 名称解析失败（getName 返回空字符串）` });
             isPass = false;
             continue;
         }
@@ -36,8 +36,9 @@ export function sortModules(items, options = {}) {
             Logger.error({
                 name: name,
                 first: nameToItem[name],
-                second: item
-            }, `${moduleLabel} 名称重复，无法根据 deps 唯一定位`);
+                second: item,
+                msg: `${moduleLabel} 名称重复，无法根据 deps 唯一定位`
+            });
             isPass = false;
             continue;
         }
@@ -50,18 +51,18 @@ export function sortModules(items, options = {}) {
         const name = getName(item);
         const deps = getDeps(item);
         if (!Array.isArray(deps)) {
-            Logger.error({ module: name, item: item }, `${moduleLabel} 的 deps 必须是数组`);
+            Logger.error({ module: name, item: item, msg: `${moduleLabel} 的 deps 必须是数组` });
             isPass = false;
             continue;
         }
         for (const dep of deps) {
             if (typeof dep !== "string") {
-                Logger.error({ module: name, dependency: dep, item: item }, `${moduleLabel} 的 deps 必须是字符串数组`);
+                Logger.error({ module: name, dependency: dep, item: item, msg: `${moduleLabel} 的 deps 必须是字符串数组` });
                 isPass = false;
                 continue;
             }
             if (!nameToItem[dep]) {
-                Logger.error({ module: name, dependency: dep }, `${moduleLabel} 依赖未找到`);
+                Logger.error({ module: name, dependency: dep, msg: `${moduleLabel} 依赖未找到` });
                 isPass = false;
             }
         }
@@ -73,7 +74,7 @@ export function sortModules(items, options = {}) {
         if (visited.has(name))
             return;
         if (visiting.has(name)) {
-            Logger.error({ module: name }, `${moduleLabel} 循环依赖`);
+            Logger.error({ module: name, msg: `${moduleLabel} 循环依赖` });
             isPass = false;
             return;
         }

package/dist/utils/util.d.ts

@@ -4,6 +4,8 @@
  * - 仅在 packages/core 内部使用；core 对外不承诺这些路径导出。
  */
 export declare function isPlainObject(value: unknown): value is Record<string, any>;
+export declare function escapeRegExp(input: string): string;
+export declare function normalizePositiveInt(value: any, fallback: number, min: number, max: number): number;
 /**
  * 激进空值判断（项目约定）：
  * - null/undefined => empty

package/dist/utils/util.js

@@ -10,6 +10,22 @@ export function isPlainObject(value) {
     const proto = Object.getPrototypeOf(value);
     return proto === Object.prototype || proto === null;
 }
+const REGEXP_SPECIAL = /[\\^$.*+?()[\]{}|]/g;
+export function escapeRegExp(input) {
+    return String(input).replace(REGEXP_SPECIAL, "\\$&");
+}
+export function normalizePositiveInt(value, fallback, min, max) {
+    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;
+}
 /**
  * 激进空值判断（项目约定）：
  * - null/undefined => empty

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "befly",
-    "version": "3.12.4",
-    "gitHead": "3134590bb2c795ec9e32dcccb44f5f6f03f98c1c",
+    "version": "3.13.0",
+    "gitHead": "340c00e4dd05b62d89d25c01922c27cb35bd99af",
     "private": false,
     "description": "Befly - 为 Bun 专属打造的 TypeScript API 接口框架核心引擎",
     "keywords": [