@lark-apaas/nestjs-logger 1.0.1-alpha.0 → 1.0.1-alpha.2

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个参数 |
+| **消息格式** | 支持格式化占位符 | 纯文本消息 |
+| **元数据** | 需要手动拼接到消息中 | 作为独立字段存储，便于查询 |
+| **使用场景** | 日常日志、错误日志 | 需要结构化查询的业务日志 |
+
 ## 环境变量配置
 
 ### 基础配置
@@ -99,6 +174,14 @@ HTTP 请求追踪日志使用 **`verbose` 级别**（对应 Pino 的 `trace` 级
 - **需要显式启用**：要查看 HTTP 请求追踪日志，需要将 `LOGGER_LEVEL` 设置为 `verbose`
 - **细粒度控制**：可以通过日志级别控制是否打印请求追踪，而无需修改 `LOG_REQUEST_BODY` 和 `LOG_RESPONSE_BODY` 配置
 
+### 响应体记录规则
+
+**只针对 JSON 响应记录 body**：
+- 自动检测 `Content-Type` 是否包含 `application/json`
+- 只有 JSON 响应才会记录 `response_body` 字段
+- 文件下载、HTML 页面等非 JSON 响应不会记录 body，避免日志污染
+- 这样可以显著减少日志体积，同时保持日志的可读性
+
 ### 启用方式
 
 通过环境变量启用：
@@ -121,7 +204,11 @@ LOG_RESPONSE_BODY=true
 
 2. **默认不限制长度**：如果不设置 `LOG_MAX_BODY_LENGTH` 环境变量，日志体不会被截断。建议在生产环境设置合理的限制值。
 
-3. **响应数据处理**：日志库会尝试序列化所有响应数据，对于无法序列化的数据（如 Buffer、Stream）会返回类型信息。
+3. **响应体过滤**：
+   - 只记录 JSON 响应的 body（检测 Content-Type）
+   - 文件下载、HTML、图片等非 JSON 响应不会记录 body
+   - 避免记录无法序列化的数据（如 Buffer、Stream）
+   - 显著减少日志体积，提高日志可读性
 
 ### 日志输出示例
 
@@ -250,9 +337,18 @@ NestJS LoggerService 级别到 Pino 级别的映射：
 
 3. **实现原理**：
    - **拦截响应方法**：在 Interceptor 中拦截 `res.json()` 和 `res.send()`，存储响应体到 `res.__finalResponseBody`
+   - **类型检测**：通过 `Content-Type` header 判断是否为 JSON 响应，只记录 JSON 类型的 body
    - **延迟记录**：不在 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

@@ -14382,7 +14382,6 @@ module.exports = __toCommonJS(index_exports);
 
 // src/service/app-logger.service.ts
 var import_common2 = require("@nestjs/common");
-var import_util = require("util");
 
 // src/helper/constants.ts
 var PINO_ROOT_LOGGER = Symbol("PINO_ROOT_LOGGER");
@@ -14678,8 +14677,12 @@ var BasePinoLogger = class _BasePinoLogger {
           messageText: message
         };
       }
+      const allMessages = [
+        message,
+        ...extras.map((e) => String(e))
+      ].join(" ");
       return {
-        messageText: (0, import_util.format)(message, ...extras)
+        messageText: allMessages
       };
     }
     if (typeof message === "object" && message !== null) {
@@ -14784,7 +14787,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 +14877,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", () => {
@@ -14890,16 +14894,41 @@ var LoggingInterceptor = class {
         duration_ms: durationMs
       };
       const finalResponseBody = res.__finalResponseBody;
-      if (this.config.logResponseBody && finalResponseBody !== void 0) {
+      const contentType = res.getHeader("content-type");
+      const isJsonResponse = typeof contentType === "string" && contentType.includes("application/json");
+      if (this.config.logResponseBody && finalResponseBody !== void 0 && isJsonResponse) {
         responseMeta["response_body"] = this.sanitizeAndTruncate(finalResponseBody);
       }
       const isError = statusCode >= 400;
       const appLog = this.appLogger[isError ? "error" : "log"].bind(this.appLogger);
       const traceLevel = isError ? "error" : "verbose";
+      const shouldLogBody = this.config.logResponseBody && isJsonResponse && finalResponseBody !== void 0;
       if (isError) {
-        appLog("HTTP request failed\n url=%s \n status_code=%d \n duration_ms=%d \n response_body=%o", req.url, statusCode, durationMs, finalResponseBody ?? {});
+        if (shouldLogBody) {
+          appLog(`HTTP request failed
+url=${req.url}
+status_code=${statusCode}
+duration_ms=${durationMs}
+response_body=${JSON.stringify(finalResponseBody ?? {})}`, "HTTPTraceInterceptor");
+        } else {
+          appLog(`HTTP request failed
+url=${req.url}
+status_code=${statusCode}
+duration_ms=${durationMs}`, "HTTPTraceInterceptor");
+        }
       } else {
-        appLog("HTTP request completed\n url=%s \n status_code=%d \n duration_ms=%d \n response_body=%o", req.url, statusCode, durationMs, finalResponseBody ?? {});
+        if (shouldLogBody) {
+          appLog(`HTTP request completed
+url=${req.url}
+status_code=${statusCode}
+duration_ms=${durationMs}
+response_body=${JSON.stringify(finalResponseBody ?? {})}`, "HTTPTraceInterceptor");
+        } else {
+          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");
     });