@lark-apaas/nestjs-logger 1.0.1-alpha.1 → 1.0.1-alpha.3

package/README.md

@@ -36,7 +36,9 @@ import { LoggerModule } from '@lark-apaas/nestjs-logger';
 export class AppModule {}
 ```
 
-### 2. 使用 Logger
+### 2. 使用 Logger（完全兼容 NestJS 官方 API）
+
+本库完全遵循 NestJS 官方 Logger API，无缝替换官方 Logger。
 
 ```typescript
 import { Injectable, Logger } from '@nestjs/common';
@@ -46,14 +48,87 @@ export class MyService {
   private readonly logger = new Logger(MyService.name);
 
   doSomething() {
+    // 简单日志
     this.logger.log('This is an info log');
-    this.logger.debug('This is a debug log');
-    this.logger.warn('This is a warning');
-    this.logger.error('This is an error', error.stack);
+
+    // 带 context 的日志（最后一个参数）
+    this.logger.log('User logged in', 'AuthModule');
+    //                                ↑ context
+
+    // 多个参数会用空格连接
+    this.logger.log('User', userId, 'logged in from', ip);
+    // 输出: User 123 logged in from 192.168.1.1
+
+    // 使用模板字符串
+    this.logger.log(`User ${userId} logged in from ${ip}`);
+
+    // 多参数 + context
+    this.logger.log('Processing order', orderId, 'OrderService');
+    //                                             ↑ context
+  }
+
+  handleError() {
+    try {
+      // 业务逻辑
+    } catch (error) {
+      // Error 日志 + stack trace（官方推荐方式）
+      this.logger.error('Failed to process', error.stack);
+      //                                     ↑ 第一个参数自动识别为 stack
+
+      // Error + stack + context
+      this.logger.error('Payment failed', error.stack, 'PaymentService');
+      //                                  ↑ stack      ↑ context
+    }
   }
 }
 ```
 
+**参数规则（与 NestJS 官方一致）**：
+- **最后一个字符串参数**：自动识别为 `context`
+- **Error/Fatal 方法的第一个参数**：如果是 stack trace 格式，自动识别为 `stack`
+- **多个参数**：会用空格连接成一个字符串
+- **不支持格式化占位符**：不支持 `%s`, `%d`, `%o` 等占位符，请使用模板字符串
+
+### 3. 使用 logStructured 记录结构化日志（扩展功能）
+
+除了标准的 Logger API，本库还提供了 `logStructured()` 方法用于记录结构化日志：
+
+```typescript
+import { Inject, Injectable } from '@nestjs/common';
+import { AppLogger } from '@lark-apaas/nestjs-logger';
+
+@Injectable()
+export class MyService {
+  constructor(
+    @Inject(AppLogger) private readonly logger: AppLogger,
+  ) {}
+
+  doSomething() {
+    // 使用 logStructured 记录结构化日志
+    this.logger.logStructured(
+      'log',  // 日志级别
+      'User action completed',  // 消息
+      {  // 元数据对象（会合并到日志字段中）
+        action: 'create_order',
+        order_id: '123',
+        amount: 100,
+      },
+      'MyService',  // context（可选）
+    );
+  }
+}
+```
+
+**两种方式对比**：
+
+| 特性 | 标准 Logger API | logStructured API |
+|------|----------------|-------------------|
+| **用途** | 常规日志，兼容 NestJS 官方 | 结构化日志，将 meta 合并到字段 |
+| **Context** | 最后一个参数自动识别 | 显式传递第4个参数 |
+| **消息格式** | 使用模板字符串拼接 | 纯文本消息 |
+| **元数据** | 需要手动拼接到消息中 | 作为独立字段存储，便于查询 |
+| **使用场景** | 日常日志、错误日志 | 需要结构化查询的业务日志 |
+
 ## 环境变量配置
 
 ### 基础配置
@@ -240,7 +315,7 @@ NestJS LoggerService 级别到 Pino 级别的映射：
 
 日志会写入以下文件（默认在 `logs/` 目录）：
 
-- `app.log` - 应用日志
+- `server.log` - 应用日志
 - `trace.log` - HTTP 请求追踪日志
 
 ## 注意事项
@@ -266,6 +341,14 @@ NestJS LoggerService 级别到 Pino 级别的映射：
    - **延迟记录**：不在 Interceptor 的 `tap()` 或 `catchError()` 中记录日志，而是在 `finish` 事件中统一记录
    - **完整信息**：此时可以获取 Exception Filter 处理后的最终状态码和响应体，确保日志准确性
 
+4. **Logger API 兼容性**：
+   - **完全兼容 NestJS 官方**：实现与 `@nestjs/common` 的 Logger 完全一致的 API
+   - **参数解析规则**：
+     - 最后一个字符串参数自动识别为 `context`
+     - Error/Fatal 方法的第一个参数如果是 stack trace 格式，自动识别为 `stack`
+   - **无缝替换**：可以直接替换项目中的官方 Logger，无需修改业务代码
+   - **扩展功能**：提供 `logStructured()` 方法用于结构化日志场景
+
 ### 安全性
 
 1. **生产环境默认不打印 HTTP 追踪日志**：由于使用 verbose 级别，生产环境（info 级别）默认不会输出详细日志

package/dist/index.cjs

@@ -14678,8 +14678,12 @@ var BasePinoLogger = class _BasePinoLogger {
           messageText: message
         };
       }
+      const allMessages = [
+        message,
+        ...extras.map((e) => stringifyParam(e))
+      ].join(" ");
       return {
-        messageText: (0, import_util.format)(message, ...extras)
+        messageText: allMessages
       };
     }
     if (typeof message === "object" && message !== null) {
@@ -14739,6 +14743,18 @@ function mapLogLevelToPino(level) {
   }
 }
 __name(mapLogLevelToPino, "mapLogLevelToPino");
+function stringifyParam(param) {
+  if (typeof param === "string") {
+    return param;
+  }
+  const inspectOptions = {
+    depth: 4,
+    colors: false,
+    compact: true
+  };
+  return (0, import_util.inspect)(param, inspectOptions);
+}
+__name(stringifyParam, "stringifyParam");
 function sanitizeValue(value) {
   if (value === null || value === void 0) {
     return value;
@@ -14784,7 +14800,7 @@ function normalizeLevel(level) {
 }
 __name(normalizeLevel, "normalizeLevel");
 var logger_config_default = (0, import_config.registerAs)("logger", () => {
-  const level = normalizeLevel(process.env.LOGGER_LEVEL || (process.env.NODE_ENV === "production" ? "info" : "trace"));
+  const level = normalizeLevel(process.env.LOGGER_LEVEL || (process.env.NODE_ENV === "production" ? "trace" : "trace"));
   const maxBodyLengthEnv = process.env.LOG_MAX_BODY_LENGTH;
   const maxBodyLength = maxBodyLengthEnv ? Number(maxBodyLengthEnv) : null;
   return {
@@ -14874,7 +14890,8 @@ var LoggingInterceptor = class {
     if (this.config.logRequestBody && Object.keys(req.query || {}).length > 0) {
       requestMeta["query_params"] = this.sanitizeAndTruncate(req.query);
     }
-    this.appLogger.log("HTTP request started \n url=%s \n request_query=%o \n request_body=%o", req.url, requestMeta["query_params"] ?? {}, requestMeta["request_body"] ?? {});
+    this.appLogger.log(`HTTP request started
+url=${req.url}`, "HTTPTraceInterceptor");
     this.traceLogger.logStructured("verbose", "HTTP request started", requestMeta, "HTTPTraceInterceptor");
     let logged = false;
     res.on("finish", () => {
@@ -14901,15 +14918,29 @@ var LoggingInterceptor = class {
       const shouldLogBody = this.config.logResponseBody && isJsonResponse && finalResponseBody !== void 0;
       if (isError) {
         if (shouldLogBody) {
-          appLog("HTTP request failed\n url=%s \n status_code=%d \n duration_ms=%d \n response_body=%o", req.url, statusCode, durationMs, finalResponseBody);
+          appLog(`HTTP request failed
+url=${req.url}
+status_code=${statusCode}
+duration_ms=${durationMs}
+response_body=${JSON.stringify(finalResponseBody ?? {})}`, "HTTPTraceInterceptor");
         } else {
-          appLog("HTTP request failed\n url=%s \n status_code=%d \n duration_ms=%d", req.url, statusCode, durationMs);
+          appLog(`HTTP request failed
+url=${req.url}
+status_code=${statusCode}
+duration_ms=${durationMs}`, "HTTPTraceInterceptor");
         }
       } else {
         if (shouldLogBody) {
-          appLog("HTTP request completed\n url=%s \n status_code=%d \n duration_ms=%d \n response_body=%o", req.url, statusCode, durationMs, finalResponseBody);
+          appLog(`HTTP request completed
+url=${req.url}
+status_code=${statusCode}
+duration_ms=${durationMs}
+response_body=${JSON.stringify(finalResponseBody ?? {})}`, "HTTPTraceInterceptor");
         } else {
-          appLog("HTTP request completed\n url=%s \n status_code=%d \n duration_ms=%d", req.url, statusCode, durationMs);
+          appLog(`HTTP request completed
+url=${req.url}
+status_code=${statusCode}
+duration_ms=${durationMs}`, "HTTPTraceInterceptor");
         }
       }
       this.traceLogger.logStructured(traceLevel, isError ? "HTTP request failed" : "HTTP request completed", responseMeta, "HTTPTraceInterceptor");