@lark-apaas/nestjs-logger 0.1.0-alpha.2 → 0.1.0-alpha.4

package/README.md

@@ -0,0 +1,320 @@
+# NestJS Logger
+
+基于 Pino 的高性能 NestJS 日志库，支持请求追踪、结构化日志和敏感信息脱敏。
+
+## 功能特性
+
+- 基于 Pino 的高性能日志记录
+- 自动 HTTP 请求追踪
+- 请求和响应体日志记录（可配置）
+- 敏感字段自动脱敏
+- 支持多日志级别
+- 独立的 trace 日志文件
+- 请求上下文传递
+
+## 安装
+
+```bash
+npm install @lark-apaas/nestjs-logger
+```
+
+## 基本使用
+
+### 1. 导入模块
+
+```typescript
+import { Module } from '@nestjs/common';
+import { LoggerModule } from '@lark-apaas/nestjs-logger';
+
+@Module({
+  imports: [LoggerModule],
+})
+export class AppModule {}
+```
+
+### 2. 使用 Logger
+
+```typescript
+import { Injectable, Logger } from '@nestjs/common';
+
+@Injectable()
+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);
+  }
+}
+```
+
+## 环境变量配置
+
+### 基础配置
+
+```bash
+# 日志级别: trace, debug, info, warn, error, fatal, silent
+# 注意：HTTP 请求追踪日志使用 verbose 级别（对应 Pino 的 trace）
+# 生产环境默认为 info，不会打印 verbose 级别的日志
+LOGGER_LEVEL=info
+
+# 日志目录
+LOG_DIR=logs
+
+# Node 环境（默认：开发环境使用 debug，生产环境使用 info）
+NODE_ENV=production
+```
+
+### 请求/响应体日志配置
+
+```bash
+# 启用请求体日志（默认：false）
+LOG_REQUEST_BODY=true
+
+# 启用响应体日志（默认：false）
+# 注意：仅记录 Content-Type 为 JSON 的响应
+LOG_RESPONSE_BODY=true
+
+# 注意：即使启用了请求/响应体日志，也需要将日志级别设置为 verbose 才能实际输出
+# 因为 HTTP 请求追踪日志使用的是 verbose 级别
+LOGGER_LEVEL=verbose
+
+# 日志体最大长度，超过会截断（默认：不限制）
+# 不设置此环境变量时，不会进行截断
+LOG_MAX_BODY_LENGTH=10000
+
+# 敏感字段配置（逗号分隔，默认包含常见敏感字段）
+LOG_SENSITIVE_FIELDS=password,token,secret,authorization,cookie,apiKey,accessToken,refreshToken
+```
+
+## 请求/响应体日志
+
+### 日志级别说明
+
+HTTP 请求追踪日志使用 **`verbose` 级别**（对应 Pino 的 `trace` 级别），这意味着：
+
+- **生产环境默认不打印**：生产环境默认日志级别为 `info`，不会输出 verbose 级别的日志
+- **需要显式启用**：要查看 HTTP 请求追踪日志，需要将 `LOGGER_LEVEL` 设置为 `verbose`
+- **细粒度控制**：可以通过日志级别控制是否打印请求追踪，而无需修改 `LOG_REQUEST_BODY` 和 `LOG_RESPONSE_BODY` 配置
+
+### 启用方式
+
+通过环境变量启用：
+
+```bash
+# 方式一：仅启用 HTTP 请求追踪（不包含 body）
+LOGGER_LEVEL=verbose
+
+# 方式二：启用 HTTP 请求追踪 + 请求/响应体
+LOGGER_LEVEL=verbose
+LOG_REQUEST_BODY=true
+LOG_RESPONSE_BODY=true
+```
+
+### 重要说明
+
+1. **仅记录 JSON 响应**：响应体日志只会记录 Content-Type 为 JSON 格式的响应（如 `application/json`、`application/vnd.api+json` 等），其他类型（如文件下载、HTML、图片等）不会被记录。
+
+2. **默认不限制长度**：如果不设置 `LOG_MAX_BODY_LENGTH` 环境变量，日志体不会被截断。建议在生产环境设置合理的限制值。
+
+3. **自动脱敏**：所有敏感字段会自动被替换为 `***MASKED***`。
+
+### 日志输出示例
+
+#### 请求日志（包含请求体）
+
+```json
+{
+  "level": "info",
+  "time": 1234567890,
+  "msg": "HTTP request started",
+  "method": "POST",
+  "path": "/api/users",
+  "trace_id": "req-123-456",
+  "user_id": "user-001",
+  "requestBody": {
+    "username": "john_doe",
+    "email": "john@example.com",
+    "password": "***MASKED***"
+  },
+  "queryParams": {
+    "filter": "active"
+  }
+}
+```
+
+#### 响应日志（包含响应体）
+
+```json
+{
+  "level": "info",
+  "time": 1234567890,
+  "msg": "HTTP request completed",
+  "method": "POST",
+  "path": "/api/users",
+  "trace_id": "req-123-456",
+  "statusCode": 201,
+  "durationMs": 125,
+  "responseBody": {
+    "id": "user-123",
+    "username": "john_doe",
+    "email": "john@example.com",
+    "accessToken": "***MASKED***"
+  }
+}
+```
+
+## 敏感字段脱敏
+
+### 默认脱敏字段
+
+以下字段会自动脱敏（不区分大小写，支持部分匹配）：
+
+- password
+- token
+- secret
+- authorization
+- cookie
+- apiKey
+- accessToken
+- refreshToken
+
+### 自定义敏感字段
+
+通过环境变量配置：
+
+```bash
+LOG_SENSITIVE_FIELDS=password,token,secret,myCustomSecret,privateKey
+```
+
+### 脱敏规则
+
+- 字段匹配不区分大小写
+- 支持部分匹配（例如：`accessToken` 会匹配 `token`）
+- 敏感字段值会被替换为 `***MASKED***`
+- 嵌套对象中的敏感字段也会被脱敏
+
+### 示例
+
+```typescript
+// 原始数据
+{
+  username: "john",
+  password: "secret123",
+  userToken: "abc123",
+  nested: {
+    apiKey: "key123"
+  }
+}
+
+// 脱敏后
+{
+  username: "john",
+  password: "***MASKED***",
+  userToken: "***MASKED***",  // 匹配 'token'
+  nested: {
+    apiKey: "***MASKED***"
+  }
+}
+```
+
+## 数据截断
+
+默认情况下，不会对日志体进行截断。当设置 `LOG_MAX_BODY_LENGTH` 环境变量后，如果请求/响应体超过指定长度，会自动截断：
+
+```json
+{
+  "responseBody": {
+    "_truncated": true,
+    "_originalLength": 50000,
+    "_data": "{ 前 10000 个字符... }..."
+  }
+}
+```
+
+**建议**：在生产环境设置合理的限制值（如 10000），避免单条日志过大。
+
+## 日志级别映射
+
+NestJS LoggerService 级别到 Pino 级别的映射：
+
+- `fatal` → `fatal`
+- `error` → `error`
+- `warn` → `warn`
+- `log` → `info`
+- `debug` → `debug`
+- `verbose` → `trace`
+
+## 日志文件
+
+日志会写入以下文件（默认在 `logs/` 目录）：
+
+- `app.log` - 应用日志
+- `trace.log` - HTTP 请求追踪日志
+
+## 注意事项
+
+### 安全性
+
+1. **生产环境默认不打印 HTTP 追踪日志**：由于使用 verbose 级别，生产环境（info 级别）默认不会输出
+2. **按需启用**：需要查看请求追踪时，将 LOGGER_LEVEL 设置为 verbose
+3. 确保敏感字段配置完整，覆盖所有可能的敏感数据
+4. 定期审查日志内容，确保没有遗漏的敏感信息
+5. **仅 JSON 响应会被记录**，文件下载、HTML 等其他类型不会被记录
+
+### 性能
+
+1. verbose 级别会输出所有 HTTP 请求日志，可能影响性能
+2. 开启请求/响应体日志会增加日志体积和 I/O 开销
+3. 大对象的序列化和脱敏会影响性能
+4. 建议在开发/测试环境使用，生产环境按需临时启用
+
+### 存储
+
+1. 注意日志文件大小，建议配置日志轮转
+2. verbose 级别 + 请求/响应体日志会显著增加日志量
+3. 建议设置 `LOG_MAX_BODY_LENGTH` 限制单条日志大小（默认不限制）
+
+## 最佳实践
+
+### 开发环境
+
+```bash
+NODE_ENV=development
+# 使用 verbose 级别查看 HTTP 请求追踪
+LOGGER_LEVEL=verbose
+LOG_REQUEST_BODY=true
+LOG_RESPONSE_BODY=true
+# 开发环境可以不限制长度，或设置较大值
+# LOG_MAX_BODY_LENGTH=50000
+```
+
+### 生产环境
+
+```bash
+NODE_ENV=production
+# 生产环境使用 info 级别，不会打印 HTTP 请求追踪日志
+LOGGER_LEVEL=info
+# 这两个配置可以保留，只有当 LOGGER_LEVEL=verbose 时才会生效
+LOG_REQUEST_BODY=false
+LOG_RESPONSE_BODY=false
+```
+
+### 故障排查
+
+临时启用详细日志：
+
+```bash
+NODE_ENV=production
+# 临时开启 verbose 级别查看 HTTP 请求追踪
+LOGGER_LEVEL=verbose
+LOG_REQUEST_BODY=true
+LOG_RESPONSE_BODY=true
+LOG_MAX_BODY_LENGTH=10000  # 建议设置限制，避免日志过大
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -14375,6 +14375,7 @@ __export(index_exports, {
   AppLogger: () => AppLogger,
   LoggerContextMiddleware: () => LoggerContextMiddleware,
   LoggerModule: () => LoggerModule,
+  PinoLoggerService: () => PinoLoggerService,
   TRACE_LOGGER: () => TRACE_LOGGER
 });
 module.exports = __toCommonJS(index_exports);
@@ -14521,6 +14522,36 @@ var BasePinoLogger = class _BasePinoLogger {
   fatal(message, ...optionalParams) {
     this.write("fatal", message, optionalParams, true);
   }
+  /**
+  * 记录结构化日志，将 meta 对象合并到日志字段中
+  * @param level 日志级别
+  * @param message 消息文本
+  * @param meta 要合并的元数据对象
+  * @param context 上下文标识
+  */
+  logStructured(level, message, meta, context) {
+    if (!this.levelState.isEnabled(level)) {
+      return;
+    }
+    const requestState = this.contextStore.getContext();
+    const traceId = requestState?.requestId ?? null;
+    const payload = {
+      trace_id: traceId,
+      path: requestState?.path,
+      method: requestState?.method,
+      user_id: requestState?.userId ?? null,
+      app_id: requestState?.appId ?? null,
+      tenant_id: requestState?.tenantId ?? null,
+      pid: process.pid,
+      ...sanitizeValue(meta)
+    };
+    if (context) {
+      payload.context = context;
+    }
+    const pinoLevel = mapLogLevelToPino(level);
+    const sanitizedPayload = sanitizeValue(payload);
+    this.logger[pinoLevel](sanitizedPayload, message);
+  }
   write(level, message, optionalParams, treatStack = false) {
     if (!this.levelState.isEnabled(level)) {
       return;
@@ -14681,7 +14712,7 @@ __name(sanitizeValue, "sanitizeValue");
 // src/module.ts
 var import_common5 = require("@nestjs/common");
 var import_core = require("@nestjs/core");
-var import_config2 = __toESM(require_config2(), 1);
+var import_config3 = __toESM(require_config2(), 1);
 
 // src/config/logger.config.ts
 var import_config = __toESM(require_config2(), 1);
@@ -14703,14 +14734,21 @@ 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" : "debug"));
+  const maxBodyLengthEnv = process.env.LOG_MAX_BODY_LENGTH;
+  const maxBodyLength = maxBodyLengthEnv ? Number(maxBodyLengthEnv) : null;
   return {
     level,
-    logDir: process.env.LOG_DIR || "logs"
+    logDir: process.env.LOG_DIR || "logs",
+    logRequestBody: process.env.LOG_REQUEST_BODY === "true",
+    logResponseBody: process.env.LOG_RESPONSE_BODY === "true",
+    maxBodyLength,
+    sensitiveFields: (process.env.LOG_SENSITIVE_FIELDS || "password,token,secret,authorization,cookie,apiKey,accessToken,refreshToken").split(",").map((f) => f.trim())
   };
 });
 
 // src/interceptor/logging.interceptor.ts
 var import_common3 = require("@nestjs/common");
+var import_config2 = __toESM(require_config2(), 1);
 var import_operators = __toESM(require_operators(), 1);
 function _ts_decorate3(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
@@ -14735,9 +14773,13 @@ var LoggingInterceptor = class {
   }
   traceLogger;
   requestContext;
-  constructor(traceLogger, requestContext) {
+  appLogger;
+  config;
+  constructor(traceLogger, requestContext, appLogger, config) {
     this.traceLogger = traceLogger;
     this.requestContext = requestContext;
+    this.appLogger = appLogger;
+    this.config = config;
   }
   intercept(context, next) {
     if (context.getType() !== "http") {
@@ -14756,7 +14798,6 @@ var LoggingInterceptor = class {
     const baseMeta = {
       method,
       path: url,
-      requestId: req.requestId ?? req.id,
       trace_id: req.requestId ?? req.id,
       user_id: req.userContext?.userId ?? null,
       tenant_id: req.userContext?.tenantId ?? null,
@@ -14764,39 +14805,141 @@ var LoggingInterceptor = class {
       ip: req.ip ?? null,
       pid: process.pid
     };
-    this.traceLogger.log("HTTP request started", baseMeta, "HTTP");
-    return next.handle().pipe((0, import_operators.tap)(() => {
+    this.appLogger.logStructured("log", "HTTP request started", baseMeta, "HTTPTraceInterceptor");
+    const requestMeta = {
+      ...baseMeta
+    };
+    if (this.config.logRequestBody && req.body) {
+      requestMeta["request_body"] = this.sanitizeAndTruncate(req.body);
+    }
+    if (this.config.logRequestBody && Object.keys(req.query || {}).length > 0) {
+      requestMeta["query_params"] = this.sanitizeAndTruncate(req.query);
+    }
+    this.traceLogger.logStructured("verbose", "HTTP request started", requestMeta, "HTTPTraceInterceptor");
+    return next.handle().pipe((0, import_operators.tap)((responseData) => {
       const durationMs = Date.now() - startedAt;
       const statusCode = res.statusCode;
-      this.traceLogger.log("HTTP request completed", {
+      this.appLogger.logStructured("log", "HTTP request completed", {
+        ...baseMeta,
+        status_code: statusCode,
+        duration_ms: durationMs
+      }, "HTTPTraceInterceptor");
+      const responseMeta = {
         ...baseMeta,
-        statusCode,
-        durationMs
-      }, "HTTP");
+        status_code: statusCode,
+        duration_ms: durationMs
+      };
+      if (this.config.logResponseBody && responseData !== void 0) {
+        const contentType = res.getHeader("content-type");
+        const isJsonResponse = this.isJsonContentType(contentType);
+        if (isJsonResponse) {
+          responseMeta["response_body"] = this.sanitizeAndTruncate(responseData);
+        }
+      }
+      this.traceLogger.logStructured("verbose", "HTTP request completed", responseMeta, "HTTPTraceInterceptor");
     }), (0, import_operators.catchError)((error) => {
       const durationMs = Date.now() - startedAt;
       const statusCode = res.statusCode >= 400 ? res.statusCode : 500;
+      const linkMeta = {
+        ...baseMeta,
+        status_code: statusCode,
+        duration_ms: durationMs
+      };
+      if (error instanceof Error) {
+        linkMeta["error_message"] = error.message;
+      }
+      this.appLogger.logStructured("log", "HTTP request failed", linkMeta, "HTTPTraceInterceptor");
       const meta = {
         ...baseMeta,
-        statusCode,
-        durationMs
+        status_code: statusCode,
+        duration_ms: durationMs
       };
       if (error instanceof Error) {
-        this.traceLogger.error(error, meta, "HTTP");
+        meta["error"] = {
+          message: error.message,
+          stack: error.stack
+        };
       } else {
-        this.traceLogger.error("Unknown error thrown", meta, "HTTP");
+        meta["error"] = String(error);
       }
+      this.traceLogger.logStructured("verbose", "HTTP request failed", meta, "HTTPTraceInterceptor");
       throw error;
     }));
   }
+  /**
+  * 对数据进行脱敏和截断处理
+  */
+  sanitizeAndTruncate(data) {
+    try {
+      const sanitized = this.maskSensitiveFields(data);
+      if (this.config.maxBodyLength === null) {
+        return sanitized;
+      }
+      const jsonStr = JSON.stringify(sanitized);
+      if (jsonStr.length > this.config.maxBodyLength) {
+        return {
+          _truncated: true,
+          _originalLength: jsonStr.length,
+          _data: jsonStr.substring(0, this.config.maxBodyLength) + "..."
+        };
+      }
+      return sanitized;
+    } catch (error) {
+      return {
+        _error: "Failed to serialize data",
+        _message: error instanceof Error ? error.message : String(error)
+      };
+    }
+  }
+  /**
+  * 判断是否是 JSON 响应类型
+  */
+  isJsonContentType(contentType) {
+    if (typeof contentType !== "string") {
+      return false;
+    }
+    const contentTypeLower = contentType.toLowerCase();
+    return contentTypeLower.includes("application/json");
+  }
+  /**
+  * 脱敏敏感字段
+  */
+  maskSensitiveFields(data) {
+    if (data === null || data === void 0) {
+      return data;
+    }
+    if (Array.isArray(data)) {
+      return data.map((item) => this.maskSensitiveFields(item));
+    }
+    if (typeof data === "object") {
+      const result = {};
+      for (const [key, value] of Object.entries(data)) {
+        const lowerKey = key.toLowerCase();
+        const isSensitive = this.config.sensitiveFields.some((field) => lowerKey.includes(field.toLowerCase()));
+        if (isSensitive) {
+          result[key] = "***MASKED***";
+        } else if (typeof value === "object" && value !== null) {
+          result[key] = this.maskSensitiveFields(value);
+        } else {
+          result[key] = value;
+        }
+      }
+      return result;
+    }
+    return data;
+  }
 };
 LoggingInterceptor = _ts_decorate3([
   (0, import_common3.Injectable)(),
   _ts_param2(0, (0, import_common3.Inject)(TRACE_LOGGER)),
+  _ts_param2(2, (0, import_common3.Inject)(AppLogger)),
+  _ts_param2(3, (0, import_common3.Inject)(logger_config_default.KEY)),
   _ts_metadata2("design:type", Function),
   _ts_metadata2("design:paramtypes", [
-    typeof import_common3.LoggerService === "undefined" ? Object : import_common3.LoggerService,
-    typeof RequestContextService === "undefined" ? Object : RequestContextService
+    typeof PinoLoggerService === "undefined" ? Object : PinoLoggerService,
+    typeof RequestContextService === "undefined" ? Object : RequestContextService,
+    typeof AppLogger === "undefined" ? Object : AppLogger,
+    typeof import_config2.ConfigType === "undefined" ? Object : import_config2.ConfigType
   ])
 ], LoggingInterceptor);
 
@@ -14914,7 +15057,7 @@ LoggerModule = _ts_decorate5([
   (0, import_common5.Global)(),
   (0, import_common5.Module)({
     imports: [
-      import_config2.ConfigModule.forFeature(logger_config_default)
+      import_config3.ConfigModule.forFeature(logger_config_default)
     ],
     providers: [
       RequestContextService,
@@ -14962,6 +15105,7 @@ LoggerModule = _ts_decorate5([
   AppLogger,
   LoggerContextMiddleware,
   LoggerModule,
+  PinoLoggerService,
   TRACE_LOGGER
 });
 //# sourceMappingURL=index.cjs.map