refactor(logging): centralize console output

src/utils/logger.ts

@@ -2,6 +2,9 @@ import pino, { type Logger as PinoLogger, type LoggerOptions } from "pino";
 
 import { AppEnvUtil } from "./app-env";
 
+type LogArgs = unknown[];
+type PinoLogArgs = Parameters<PinoLogger["debug"]>;
+
 /**
  * 全局 pino root logger（单例，进程级复用）。
  *
@@ -45,20 +48,77 @@ export class Logger {
     this.logger = rootLogger.child({ component });
   }
 
-  debug(...args: Parameters<PinoLogger["debug"]>): void {
-    this.logger.debug(...args);
+  debug(...args: LogArgs): void {
+    this.logger.debug(...Logger.normalizeLogArgs(args));
   }
-  info(...args: Parameters<PinoLogger["info"]>): void {
-    this.logger.info(...args);
+  info(...args: LogArgs): void {
+    this.logger.info(...Logger.normalizeLogArgs(args));
   }
-  warn(...args: Parameters<PinoLogger["warn"]>): void {
-    this.logger.warn(...args);
+  warn(...args: LogArgs): void {
+    this.logger.warn(...Logger.normalizeLogArgs(args));
   }
-  error(...args: Parameters<PinoLogger["error"]>): void {
-    this.logger.error(...args);
+  error(...args: LogArgs): void {
+    this.logger.error(...Logger.normalizeLogArgs(args));
   }
-  fatal(...args: Parameters<PinoLogger["fatal"]>): void {
-    this.logger.fatal(...args);
+  fatal(...args: LogArgs): void {
+    this.logger.fatal(...Logger.normalizeLogArgs(args));
+  }
+
+  /**
+   * 把日志中的任意数据转成人眼友好的多行文本。
+   * - object / array: pretty JSON
+   * - JSON string: parse 后 pretty JSON
+   * - FormData / File: 使用轻量描述，避免直接输出二进制
+   */
+  static formatValue(value: unknown): string {
+    if (value === undefined || value === null) return "";
+
+    if (typeof FormData !== "undefined" && value instanceof FormData) {
+      const entries: string[] = [];
+      value.forEach((entryValue, key) => {
+        if (typeof File !== "undefined" && entryValue instanceof File) {
+          entries.push(`${key}=File(${entryValue.name})`);
+        } else {
+          entries.push(`${key}=${String(entryValue)}`);
+        }
+      });
+      return `FormData{\n  ${entries.join(",\n  ")}\n}`;
+    }
+
+    if (typeof value === "string") {
+      const trimmed = value.trim();
+      if (trimmed.length === 0) return "";
+      try {
+        return JSON.stringify(JSON.parse(trimmed), null, 2);
+      } catch {
+        return value;
+      }
+    }
+
+    try {
+      return JSON.stringify(value, null, 2);
+    } catch {
+      return String(value);
+    }
+  }
+
+  private static normalizeLogArgs(args: LogArgs): PinoLogArgs {
+    const [first, second, ...rest] = args;
+    if (typeof first !== "string" || second === undefined) return args as PinoLogArgs;
+
+    if (second instanceof Error) {
+      return [{ err: second }, first, ...rest] as PinoLogArgs;
+    }
+
+    if (
+      typeof second === "object" &&
+      second !== null &&
+      !Array.isArray(second)
+    ) {
+      return [second, first, ...rest] as PinoLogArgs;
+    }
+
+    return args as PinoLogArgs;
   }
 
   /** 透传 raw pino logger（高级用法：自定义 binding / child / serializers） */