日志系统

相关源文件

• .gitignore
• Readme.md
• integration/graphql-schema-first/src/main.ts
• packages/common/Readme.md
• packages/common/services/console-logger.service.ts
• packages/common/services/index.ts
• packages/common/services/logger.service.ts
• packages/common/services/utils/index.ts
• packages/common/services/utils/is-log-level-enabled.util.ts
• packages/common/test/services/logger.service.spec.ts
• packages/common/test/services/utils/is-log-level-enabled.util.spec.ts
• packages/core/Readme.md
• packages/core/injector/abstract-instance-resolver.ts
• packages/core/injector/helpers/silent-logger.ts
• packages/core/injector/lazy-module-loader/lazy-module-loader.ts
• packages/microservices/Readme.md
• packages/platform-express/Readme.md
• packages/platform-fastify/Readme.md
• packages/platform-socket.io/Readme.md
• packages/platform-ws/Readme.md
• packages/testing/Readme.md
• packages/websockets/Readme.md
• readme_jp.md
• readme_kr.md

NestJS 日志系统提供了一个灵活且可配置的应用程序日志记录机制。它提供了多种日志级别、格式化选项，并支持控制台输出和自定义实现。本文档介绍了日志系统的工作原理、接口以及如何针对不同用例进行配置和扩展。

概述

NestJS 内置的日志系统由几个关键组件组成：

1. 一个定义了标准日志方法的 LoggerService 接口
2. 一个实现此接口的默认 Logger 类
3. 一个提供增强的控制台输出的 ConsoleLogger
4. 用于日志级别管理的实用函数
5. 支持自定义日志记录器实现

日志系统支持基于实例和静态的日志方法、日志缓冲、上下文感知日志以及可调节的日志级别。

来源： packages/common/services/logger.service.ts packages/common/services/console-logger.service.ts

Logger Service 接口

日志系统的基础是 LoggerService 接口。它定义了所有日志记录器实现必须遵循的契约，并提供了不同日志级别的各种方法。

LoggerService 接口定义在 packages/common/services/logger.service.ts14-50 并且包含以下方法：

请注意，debug、verbose、fatal 和 setLogLevels 是可选方法，用问号表示；而 log、error 和 warn 是必需的。

来源： packages/common/services/logger.service.ts14-50

日志级别

NestJS 支持六个日志级别，按严重性递增的层次排列：

LogLevel 类型定义为这些值的联合。

分配给每个级别的数字值用于内部确定特定日志级别是否已启用。较高的值表示较高的严重性。

来源： packages/common/services/logger.service.ts9 packages/common/services/utils/is-log-level-enabled.util.ts3-10

默认日志记录实现

Logger 类是 LoggerService 接口的默认实现。它同时提供了实例方法和静态方法用于日志记录。

实例方法

实例方法允许进行特定于上下文的日志记录。

实例在多个日志调用中维护其上下文，非常适合特定组件的日志记录。

静态方法

静态方法提供了一种便捷的方式来记录日志，而无需创建实例。

静态方法适用于快速日志记录，无需注入或实例化日志记录器。

日志缓冲

Logger 类包含一个缓冲机制，允许将日志临时存储起来，并在准备就绪时刷新。

这在应用程序引导过程中特别有用，因为有些组件可能在日志系统完全配置之前就记录了消息。

来源： packages/common/services/logger.service.ts80-107 packages/common/services/logger.service.ts275-297

控制台日志记录器

ConsoleLogger 提供了增强的日志记录功能，具有以下特点：

1. 可自定义的时间戳格式
2. 着色输出（基于日志级别）
3. 上下文前缀
4. 用于结构化日志记录的 JSON 格式
5. 错误堆栈跟踪格式化

配置示例

ConsoleLogger 可用的选项包括：

选项	类型	描述
logLevels	LogLevel[]	启用的日志级别
timestamp	布尔值	是否包含时间戳
prefix	字符串	所有日志消息的前缀
json	布尔值	以 JSON 格式输出日志
colors	布尔值	是否为输出着色
context	字符串	日志消息的上下文
compact	boolean | number	对象的紧凑格式

来源： packages/common/services/console-logger.service.ts15-88 packages/common/services/console-logger.service.ts91-98

配置日志级别

日志系统允许您选择性地启用日志级别以控制详细程度。

isLogLevelEnabled 实用函数用于确定是否应显示日志级别。

此函数不仅检查级别是否被明确包含，还比较数字值以确定一个级别是否与层次结构中的另一个级别相同或更高。

来源： packages/common/services/utils/is-log-level-enabled.util.ts17-33

自定义日志记录器

您可以创建自定义日志记录器，方法是：

1. 直接实现 LoggerService 接口
2. 扩展 ConsoleLogger 或 Logger 类

对于需要静默日志的情况，NestJS 提供了一个 SilentLogger，它实现了无操作方法。

自定义日志记录器示例

覆盖默认日志记录器

来源： packages/common/services/logger.service.ts303-324 packages/core/injector/helpers/silent-logger.ts3-12

上下文中的日志记录

NestJS 鼓励使用基于上下文的日志记录来识别日志消息的来源。

这种方法可以轻松识别是哪个组件生成了每条日志消息，从而便于调试和监控。

服务中基于上下文的日志记录示例

来源： packages/common/services/logger.service.ts105-111 packages/common/services/logger.service.ts132-139

与 NestJS 应用程序生命周期的集成

日志系统与 NestJS 应用程序生命周期紧密集成。在应用程序引导过程中，日志可以被缓冲，直到应用程序准备就绪。

对于延迟加载的模块，您可以配置是显示还是静默日志。

来源： packages/common/services/logger.service.ts275-297 packages/core/injector/lazy-module-loader/lazy-module-loader.ts57-60

最佳实践

1. 始终使用上下文：始终提供上下文（类名、模块名）以使日志可追溯。

2. 选择适当的日志级别:

   • verbose：非常详细的信息（用于深度调试）
   • debug：开发过程中有用的详细信息
   • log：关于正常操作的一般信息
   • warn：可能的问题，但不会阻止操作
   • error：阻止预期功能的问题
   • fatal：需要立即关注的关键问题

3. 按环境配置:

4. 在生产环境中启用 JSON 格式:

5. 为复杂需求创建专门的日志记录器:

   • 数据库日志记录
   • 安全审计日志记录
   • 性能监控

来源： packages/common/services/logger.service.ts packages/common/services/console-logger.service.ts