57. 【Java】日志框架：SLF4J与Logback

摘要： 本文系统介绍Java日志框架SLF4J+Logback的核心概念与实战应用。从日志框架的必要性出发，对比System.out.println()的局限性，详细讲解SLF4J门面模式的优势、Logback配置方法、日志级别控制、文件输出策略以及异步日志优化。通过完整示例演示如何在项目中集成日志记录，并分享日志最佳实践，帮助开发者构建可维护、高性能的日志系统。

关键词： SLF4J, Logback, Java日志, 日志框架, 日志配置

---

在上一篇文章中，我们学习了 JUnit 5 单元测试，你知道了如何用自动化测试来验证代码的正确性。现在你的代码有了质量保障，跑起来也放心多了。

但还有另一个问题：程序运行的时候，到底发生了什么？

如果你的程序出了 bug，用户说“点了一下按钮，页面没反应”，你怎么知道问题出在哪里？如果是在本地开发，你可以加断点调试；但如果程序已经部署到了服务器上，你没法用 IDE 连上去调试。这时候，你需要的是一份运行日志（Log）——程序在执行过程中留下的“脚印”，它记录了什么时候发生了什么、数据是什么、结果是什么。

日志就像是飞机上的黑匣子。飞机正常飞行时你不需要它，但一旦出了事故，它是你还原真相的唯一线索。

今天，我们就来学习 Java 开发中最主流的日志框架组合：SLF4J + Logback。

---

1. 为什么需要日志框架？—— System.out.println() 为什么不够用？

在之前的文章中，我们大量使用了 System.out.println() 来输出调试信息。在学习和实验阶段，这完全没问题。但在真实项目中，System.out.println() 有太多硬伤：

• 无法控制级别：你没法说“只输出 WARN 级别以上的日志”，所有 println 都会打印，不管是调试信息还是错误信息。
• 无法关闭：生产环境上线后，大量的调试日志会把磁盘写满，而且会让程序变慢。
• 无法分类：所有输出都混在一起，你不知道哪条是来自哪个模块。
• 无法持久化：输出到控制台的内容，一旦滚动就消失了，没法回溯。
• 无法格式化：你没法统一加上时间戳、线程名、类名等上下文信息。

而一个成熟的日志框架能帮你解决所有这些痛点：

• 分级输出：TRACE、DEBUG、INFO、WARN、ERROR，你可以配置只输出某个级别以上的日志。
• 灵活配置：开发环境输出到控制台，生产环境输出到文件，甚至可以输出到远程服务器。
• 分类管理：你可以为不同的包或类设置不同的日志级别。
• 持久化：日志被写入文件，可以按天滚动、压缩、归档，长期保存。
• 统一格式：自动包含时间戳、线程名、类名、行号等上下文信息。
• 性能优化：异步写入、条件编译等机制，保证日志记录对程序性能的影响最小。

打个比方：System.out.println() 就像你在纸上随手写笔记，随写随丢；而日志框架就像一本有目录、有分页、有日期、可归档的专业日志本。

---

2. Java 日志生态 —— 一个“绕来绕去”的故事

Java 的日志框架生态有点复杂，初学者往往会被各种名字搞晕：java.util.logging、Log4j、Log4j 2、Logback、SLF4J、Commons Logging……它们之间是什么关系？

让我用一个简短的“历史故事”帮你理清思路：

1. JDK 1.4（2002年）：Java 自带了 java.util.logging（JUL），但功能比较弱，使用也不方便。
2. Log4j（2001年）：一个第三方日志框架，功能强大，被广泛采用，成为事实标准。
3. Commons Logging（JCL，2003年）：Apache 推出的日志门面（Facade），它本身不实现日志，而是提供一个统一的 API，底层可以切换为 Log4j 或 JUL。
4. SLF4J（2005年）：Simple Logging Facade for Java，一个更现代的门面框架，比 Commons Logging 设计更好，支持占位符 {}。
5. Logback（2006年）：Log4j 的作者（Ceki Gülcü）后来“升级”了 Log4j 的设计，写出了 Logback。Logback 原生实现了 SLF4J 接口，是 SLF4J 的最佳搭档。
6. Log4j 2（2014年）：Apache 对 Log4j 进行了重写，Log4j 2 也支持 SLF4J，但更复杂一些。它在某些场景下性能有优势，但配置也比较复杂。

今天的最佳实践是什么？

绝大多数现代 Java 项目使用 SLF4J（门面）+ Logback（实现） 这个组合。它简单、稳定、配置灵活，而且在 Spring Boot 中是默认集成的。

💡 门面模式的好处：你的代码只依赖 SLF4J 的 API，底层的日志实现可以随时替换（从 Logback 换成 Log4j 2，或者换成别的），而你的业务代码不需要改动。

---

3. SLF4J + Logback —— 快速上手

3.1 添加依赖

在 Maven 项目中，只需要添加以下依赖（Spring Boot 项目已经默认包含）：

<dependencies>
    <!-- SLF4J API -->
    <dependency>
        <groupId>org.slf4j</groupId>
        <artifactId>slf4j-api</artifactId>
        <version>2.0.13</version>
    </dependency>
    
    <!-- Logback 实现 -->
    <dependency>
        <groupId>ch.qos.logback</groupId>
        <artifactId>logback-classic</artifactId>
        <version>1.5.6</version>
    </dependency>
</dependencies>

logback-classic 已经包含了 logback-core，所以不需要单独添加。

3.2 最简单的使用

在你的类中，通过 LoggerFactory 获取一个 Logger 实例，然后就可以记录日志了：

package com.example.demo;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class LogDemo {
    // 每个类创建一个 Logger（通常用当前类的全限定名）
    private static final Logger logger = LoggerFactory.getLogger(LogDemo.class);

    public static void main(String[] args) {
        // 不同级别的日志
        logger.trace("这是 TRACE 级别的日志");
        logger.debug("这是 DEBUG 级别的日志");
        logger.info("这是 INFO 级别的日志");
        logger.warn("这是 WARN 级别的日志");
        logger.error("这是 ERROR 级别的日志");

        // 带参数的日志（使用占位符 {}）
        String name = "张三";
        int age = 25;
        logger.info("用户 {} 的年龄是 {} 岁", name, age);

        // 记录异常信息
        try {
            int result = 10 / 0;
        } catch (Exception e) {
            logger.error("计算发生异常", e);
        }
    }
}

运行这段代码，你会看到类似这样的输出（取决于日志配置）：

11:30:45.123 [main] INFO com.example.demo.LogDemo - 这是 INFO 级别的日志
11:30:45.124 [main] WARN com.example.demo.LogDemo - 这是 WARN 级别的日志
11:30:45.124 [main] ERROR com.example.demo.LogDemo - 这是 ERROR 级别的日志
11:30:45.124 [main] INFO com.example.demo.LogDemo - 用户 张三 的年龄是 25 岁
11:30:45.125 [main] ERROR com.example.demo.LogDemo - 计算发生异常
java.lang.ArithmeticException: / by zero
    at com.example.demo.LogDemo.main(LogDemo.java:25)

默认情况下，Logback 只输出 INFO 级别及以上的日志，所以 TRACE 和 DEBUG 没有显示。

3.3 为什么用占位符 {} 而不是字符串拼接？

很多新手会写成：

// ❌ 不推荐
logger.info("用户 " + name + " 的年龄是 " + age + " 岁");

而推荐写成：

// ✅ 推荐
logger.info("用户 {} 的年龄是 {} 岁", name, age);

原因在于性能：如果当前日志级别是 WARN，那么 INFO 级别的日志根本不会被输出。但如果用字符串拼接，Java 仍然会先执行拼接操作（即使最后日志没有被记录），造成性能浪费。而占位符方式会先检查日志级别，决定是否需要执行参数替换，所以更加高效。

---

4. 日志配置 —— logback.xml / logback-spring.xml

Logback 的配置非常灵活。你可以在 src/main/resources 目录下创建一个 logback.xml 或 logback-spring.xml 文件来控制日志的行为。

在 Spring Boot 项目中，建议使用 logback-spring.xml，因为 Spring Boot 会对它做额外的处理（比如支持 profile 配置）。

一个最基本的 logback.xml 配置文件：

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <!-- 控制台输出配置 -->
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <!-- 日志格式 -->
        <encoder>
            <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>

    <!-- 根日志级别：所有日志至少为 INFO -->
    <root level="INFO">
        <appender-ref ref="CONSOLE" />
    </root>
</configuration>

这个配置让日志输出到控制台，格式包含时间、线程、级别、类名和消息。

---

5. 日志级别 —— 控制记录的“精细度”

Logback 定义了五个日志级别（从低到高）：

级别	用途	何时使用
TRACE	最详细的追踪信息	非常细粒度的调试，比如跟踪一个请求的完整流程
DEBUG	调试信息	开发调试时输出变量值、方法进入/退出等
INFO	常规信息	重要的业务事件（用户登录、订单创建、服务启动）
WARN	警告	潜在问题，但程序还能继续运行（比如使用旧的配置）
ERROR	错误	运行时异常、业务失败（比如支付失败）

配置级别：你可以为不同的包设置不同的级别。例如：

<!-- 把 com.example 包的级别设为 DEBUG -->
<logger name="com.example" level="DEBUG" />

<!-- 把 org.springframework 包的级别设为 WARN，减少 Spring 的噪音 -->
<logger name="org.springframework" level="WARN" />

<!-- 根级别设为 INFO -->
<root level="INFO">
    <appender-ref ref="CONSOLE" />
</root>

这样，com.example 下的日志会输出 DEBUG 及以上级别的日志，而 Spring 的日志只输出 WARN 及以上级别，既不影响调试，又不会被 Spring 的日志淹没。

---

6. 日志输出到文件 —— 持久化存储

在实际项目中，控制台日志通常只用于开发和调试。生产环境需要把日志写入文件，方便长期保存和检索。

<!-- 文件输出配置 -->
<appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
    <!-- 日志文件路径 -->
    <file>logs/myapp.log</file>
    
    <!-- 日志格式 -->
    <encoder>
        <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
    </encoder>
    
    <!-- 滚动策略：按天滚动 -->
    <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
        <!-- 每天生成一个日志文件，压缩归档 -->
        <fileNamePattern>logs/myapp.%d{yyyy-MM-dd}.log.gz</fileNamePattern>
        <!-- 保留 30 天的日志 -->
        <maxHistory>30</maxHistory>
    </rollingPolicy>
</appender>

<root level="INFO">
    <appender-ref ref="CONSOLE" />
    <appender-ref ref="FILE" />
</root>

这样配置后，日志会写入 logs/myapp.log 文件，每天凌晨自动滚动生成一个新的文件，同时把旧的日志压缩成 .gz 文件归档，最多保留 30 天。

---

7. 常见的日志配置模式

7.1 开发环境 vs 生产环境

在 Spring Boot 项目中，你可以根据 profile 使用不同的配置：

<!-- logback-spring.xml -->
<configuration>
    <!-- 开发环境：DEBUG 级别，彩色输出 -->
    <springProfile name="dev">
        <root level="DEBUG">
            <appender-ref ref="CONSOLE" />
        </root>
    </springProfile>

    <!-- 生产环境：INFO 级别，输出到文件 -->
    <springProfile name="prod">
        <root level="INFO">
            <appender-ref ref="FILE" />
        </root>
    </springProfile>
</configuration>

7.2 异步日志 —— 提升性能

日志写入文件是一个 I/O 操作，如果同步写入，每个日志记录都要等待磁盘写入完成，会拖慢业务线程。Logback 提供了 AsyncAppender，让你异步写入日志，业务线程只需要把日志放进内存队列，由后台线程负责写入。

<appender name="ASYNC_FILE" class="ch.qos.logback.classic.AsyncAppender">
    <appender-ref ref="FILE" />
    <!-- 队列大小 -->
    <queueSize>512</queueSize>
    <!-- 如果队列满了，是否丢弃日志（true=丢弃，false=阻塞业务线程） -->
    <discardingThreshold>0</discardingThreshold>
</appender>

<root level="INFO">
    <appender-ref ref="ASYNC_FILE" />
</root>

异步日志在高并发场景下能显著提升性能，但需要权衡日志丢失的风险（极端情况下队列满了会丢弃日志）。

---

8. 在代码中优雅地使用日志

8.1 使用 @Slf4j 注解（Lombok）

如果你使用 Lombok，可以省去手动声明 Logger 的样板代码：

import lombok.extern.slf4j.Slf4j;

@Slf4j
public class MyService {
    public void doSomething() {
        log.info("执行 doSomething 方法");
        // 直接使用 log 变量，不需要手动声明
    }
}

⚠️ 注意：使用 Lombok 需要在 pom.xml 中添加 Lombok 依赖，并在 IDEA 中安装 Lombok 插件。

8.2 日志的最佳实践

✅ 推荐做法：

1. 记录有意义的上下文信息：不只是 "登录失败"，而是 "用户 {} 登录失败，原因：{}"，包含用户名和错误原因。
2. 异常一定要记录完整的堆栈：logger.error("操作失败", e)，而不是 logger.error("操作失败：" + e.getMessage())。
3. 使用 isDebugEnabled() 保护昂贵的日志构造：

   if (logger.isDebugEnabled()) {
       logger.debug("复杂的调试信息: {}", expensiveToString());
   }
   

4. 统一使用 SLF4J API：保持代码中只有 org.slf4j.Logger 的引用，避免直接依赖具体实现。
5. 合理使用日志级别：DEBUG 用于开发和测试，INFO 用于重要的业务事件，WARN 用于可恢复的问题，ERROR 用于需要人工介入的错误。

❌ 避免的做法：

1. 记录敏感信息：密码、身份证号、银行卡号、Token 等，绝对不能出现在日志中。
2. 在循环中记录大量日志：尤其是 DEBUG 级别的日志，在循环中输出会严重影响性能。
3. 吞掉异常：catch (Exception e) { } 而不记录任何日志，会让问题无法追踪。
4. 用 System.out.println() 代替日志：在正式项目中，所有输出都应该走日志框架。

---

9. 综合示例 —— 在“图书管理系统”中集成日志

我们把之前写的图书管理系统改造一下，加入日志记录。

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class LibraryService {
    private static final Logger logger = LoggerFactory.getLogger(LibraryService.class);

    public Book borrowBook(String userId, String isbn) 
            throws BookNotFoundException, BookNotAvailableException {
        logger.info("用户 {} 尝试借阅图书 {}", userId, isbn);
        
        // ... 业务逻辑 ...
        
        if (bookNotFound) {
            logger.warn("用户 {} 借阅失败，图书 {} 不存在", userId, isbn);
            throw new BookNotFoundException(isbn);
        }
        
        if (!book.isAvailable()) {
            logger.warn("用户 {} 借阅失败，图书 {} 库存不足", userId, isbn);
            throw new BookNotAvailableException(isbn);
        }
        
        // 借阅成功
        logger.info("用户 {} 成功借阅图书 {}", userId, isbn);
        return book;
    }

    public void returnBook(String userId, String isbn) {
        logger.info("用户 {} 归还图书 {}", userId, isbn);
        // ... 归还逻辑 ...
        logger.info("用户 {} 归还图书 {} 成功", userId, isbn);
    }
}

配置日志级别为 INFO 时，INFO、WARN、ERROR 会被记录，DEBUG 和 TRACE 被忽略。当需要深入调试时，可以把 com.example.library 包的级别临时改成 DEBUG，就能看到更详细的日志了。

---

10. 日志框架的演进与 JDK 21

在 JDK 21 中，日志框架没有大的变化，但有两个值得注意的点：

1. 系统模块（System Logger）：JDK 内部使用了 System.Logger API，它提供了一个统一的接口，可以把 JDK 内部的日志桥接到 SLF4J 等框架中。
2. 虚拟线程的日志：在虚拟线程中，日志格式中的 [thread] 会显示虚拟线程的名称，你可以给虚拟线程命名来增强可读性：

   Thread vt = Thread.ofVirtual().name("vt-request-", 0).start(() -> {
       logger.info("处理请求...");  // 会显示虚拟线程名
   });
   

---

11. 今天的总结

今天我们学习了日志框架：

• 为什么需要日志：System.out.println() 无法满足生产环境的需求，需要分级、可配置、可持久化的日志框架。
• SLF4J + Logback：当前最主流的组合，SLF4J 是门面（API），Logback 是实现。
• 日志级别：TRACE < DEBUG < INFO < WARN < ERROR，可以精细控制输出内容。
• 配置：通过 logback.xml 配置控制台输出、文件输出、滚动策略、异步日志。
• 最佳实践：
  • 使用占位符 {} 而不是字符串拼接。
  • 记录异常时包含完整堆栈。
  • 不要记录敏感信息。
  • 使用 @Slf4j 注解简化声明。
• 虚拟线程日志：虚拟线程名称会自动显示在日志中，增强可读性。

日志是程序的“黑匣子”，也是运维人员的“眼睛”。学会正确使用日志框架，你在排查问题时会有完全不一样的体验——不再是“猜哪里出了问题”，而是直接看日志文件里的记录，精准定位。

---

动手试试

1. 在你现有的项目中添加 SLF4J + Logback 依赖，把 System.out.println() 替换成日志记录。
2. 配置一个 logback.xml，让日志同时输出到控制台和文件，并设置不同的日志级别。
3. 写一个包含多个包的项目，为不同的包设置不同的日志级别（比如 com.example.core 为 DEBUG，com.example.web 为 INFO）。
4. 在你的代码中故意抛出一个异常，用 logger.error("出错啦", e) 记录，观察日志中是否包含完整的堆栈。
5. 尝试配置异步日志，观察在高频日志输出时的性能表现（可以用 JMH 测试，或者简单对比同步和异步的吞吐量）。

下一篇文章，我们将学习 JDBC —— Java 与数据库的桥梁，让你的程序能够持久化地存储和查询数据。

我们下一篇见。😃

📌 获取本系列示例代码请访问 GitCode。