Spring Boot 中的日志记录详解

1. 概述

本文将深入探讨 Spring Boot 中主流的日志方案。你会了解到如何配置 Logback 和 Log4j2，如何通过 Lombok 简化日志代码，以及一些常见“踩坑”点。

如果你需要更深入掌握 Logback，推荐阅读《Logback 使用指南》；而关于 Log4j2 的核心组件（Appender、Layout、Filter），可参考《Log4j2 入门指南》。

2. 初始项目搭建

使用 Spring Initializr 快速生成一个 Spring Boot 项目是最推荐的方式，具体步骤可参考我们的《Spring Boot 快速入门》。

创建一个核心类 LoggingController 来演示日志输出：

@RestController
public class LoggingController {

    Logger logger = LoggerFactory.getLogger(LoggingController.class);

    @RequestMapping("/")
    public String index() {
        logger.trace("A TRACE Message");
        logger.debug("A DEBUG Message");
        logger.info("An INFO Message");
        logger.warn("A WARN Message");
        logger.error("An ERROR Message");

        return "Howdy! Check out the Logs to see the output...";
    }
}

启动应用后，访问 http://localhost:8080/ 即可触发日志输出，查看控制台即可看到结果。

3. 零配置日志（Zero Configuration Logging）

Spring Boot 的设计哲学之一就是“约定优于配置”，日志系统也不例外。你几乎不需要任何配置就能跑起来。

3.1 默认使用 Logback

✅ 关键点：只要引入了任意一个 Spring Boot Starter（比如 spring-boot-starter-web），就会自动引入 spring-boot-starter-logging，它默认集成的是 Logback。

底层依赖的是 Spring 自带的 spring-jcl（Spring Java Commons Logging），你完全不需要手动引入。

启动应用后访问首页，控制台输出如下：

⚠️ 注意：默认日志级别是 INFO，因此 TRACE 和 DEBUG 级别的日志不会显示。

如果想临时开启更详细的日志，可以使用命令行参数：

java -jar target/spring-boot-logging-0.0.1-SNAPSHOT.jar --trace

或者 --debug，Spring Boot 会自动调整日志级别。

3.2 日志级别控制

Spring Boot 提供了多种方式来精细化控制日志级别：

方式一：JVM 参数

-Dlogging.level.org.springframework=TRACE 
-Dlogging.level.com.baeldung=TRACE

方式二：Maven 命令行

mvn spring-boot:run \
  -Dspring-boot.run.arguments=--logging.level.org.springframework=TRACE,--logging.level.com.baeldung=TRACE

方式三：Gradle 命令行

./gradlew bootRun -Pargs=--logging.level.org.springframework=TRACE,--logging.level.com.baeldung=TRACE

方式四：`application.properties`

logging.level.root=WARN
logging.level.com.baeldung=TRACE

方式五：日志框架配置文件（如 `logback-spring.xml`）

<logger name="org.springframework" level="INFO" />
<logger name="com.baeldung" level="INFO" />

✅ 优先级规则：如果同一包的日志级别在多个地方被设置，最终生效的是级别最低的那个（TRACE < DEBUG < INFO < WARN < ERROR）。例如，一处设 INFO，另一处设 TRACE，则最终为 TRACE。

4. Logback 自定义配置

默认配置适合快速验证，但生产环境需要更精细的控制，比如：

区分控制台和文件输出
自定义日志格式和颜色
文件滚动策略（按时间/大小）

配置文件加载机制

Spring Boot 会自动加载 classpath 下的以下文件（按优先级）：

logback-spring.xml ✅ 推荐使用，支持 Spring Profile
logback.xml
logback-spring.groovy
logback.groovy

官方文档明确建议使用 -spring 后缀变体。

示例：`logback-spring.xml`

<?xml version="1.0" encoding="UTF-8"?>
<configuration>

    <property name="LOGS" value="./logs" />

    <appender name="Console"
        class="ch.qos.logback.core.ConsoleAppender">
        <layout class="ch.qos.logback.classic.PatternLayout">
            <Pattern>
                %black(%d{ISO8601}) %highlight(%-5level) [%blue(%t)] %yellow(%C{1.}): %msg%n%throwable
            </Pattern>
        </layout>
    </appender>

    <appender name="RollingFile"
        class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>${LOGS}/spring-boot-logger.log</file>
        <encoder
            class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
            <Pattern>%d %p %C{1.} [%t] %m%n</Pattern>
        </encoder>

        <rollingPolicy
            class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <!-- 每天或文件达到 10MB 时滚动 -->
            <fileNamePattern>${LOGS}/archived/spring-boot-logger-%d{yyyy-MM-dd}.%i.log</fileNamePattern>
            <timeBasedFileNamingAndTriggeringPolicy
                class="ch.qos.logback.core.rolling.SizeAndTimeBasedFNATP">
                <maxFileSize>10MB</maxFileSize>
            </timeBasedFileNamingAndTriggeringPolicy>
        </rollingPolicy>
    </appender>
    
    <!-- 根日志器：INFO 级别 -->
    <root level="info">
        <appender-ref ref="RollingFile" />
        <appender-ref ref="Console" />
    </root>

    <!-- com.baeldung 包：TRACE 级别，关闭累加性 -->
    <logger name="com.baeldung" level="trace" additivity="false">
        <appender-ref ref="RollingFile" />
        <appender-ref ref="Console" />
    </logger>

</configuration>

运行效果：

可以看到，日志已按配置输出到控制台和 ./logs/ 目录，并启用了滚动归档。

5. 切换到 Log4j2

虽然 Logback 是默认选项，但 Log4j2 在性能和功能上更具优势（如异步日志）。切换步骤如下：

步骤一：排除默认日志依赖

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <exclusions>
        <exclusion>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-logging</artifactId>
        </exclusion>
    </exclusions>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-log4j2</artifactId>
</dependency>

步骤二：添加 `log4j2-spring.xml`

<?xml version="1.0" encoding="UTF-8"?>
<Configuration>
    <Appenders>
        <Console name="Console" target="SYSTEM_OUT">
            <PatternLayout
                pattern="%style{%d{ISO8601}}{black} %highlight{%-5level }[%style{%t}{bright,blue}] %style{%C{1.}}{bright,yellow}: %msg%n%throwable" />
        </Console>

        <RollingFile name="RollingFile"
            fileName="./logs/spring-boot-logger-log4j2.log"
            filePattern="./logs/$${date:yyyy-MM}/spring-boot-logger-log4j2-%d{-dd-MMMM-yyyy}-%i.log.gz">
            <PatternLayout>
                <pattern>%d %p %C{1.} [%t] %m%n</pattern>
            </PatternLayout>
            <Policies>
                <OnStartupTriggeringPolicy />
                <SizeBasedTriggeringPolicy size="10 MB" />
                <TimeBasedTriggeringPolicy />
            </Policies>
        </RollingFile>
    </Appenders>

    <Loggers>
        <Root level="info">
            <AppenderRef ref="Console" />
            <AppenderRef ref="RollingFile" />
        </Root>

        <Logger name="com.baeldung" level="trace" />
    </Loggers>
</Configuration>

运行效果：

✅ 输出风格与 Logback 明显不同，确认已成功切换。

📌 扩展：Log4j2 还支持 YAML 和 JSON 配置，详见官方文档。

6. 直接使用 Log4j2（绕过 SLF4J）

上述配置中，日志仍通过 SLF4J API 输出。如果你想使用 Log4j2 的原生 API（如结构化日志、异步日志等高级特性），可以直接调用：

import org.apache.logging.log4j.Logger;
import org.apache.logging.log4j.LogManager;

@RestController
public class NativeLog4j2Controller {

    private static final Logger logger = LogManager.getLogger(NativeLog4j2Controller.class);

    @RequestMapping("/native")
    public String index() {
        logger.trace("A TRACE Message");
        logger.debug("A DEBUG Message");
        // ... 其他日志
        return "Using native Log4j2 API";
    }
}

⚠️ 缺点：代码与 Log4j2 强耦合，未来切换日志框架需要重写。

7. 使用 Lombok 简化日志代码

每次手动声明 Logger 实例很繁琐。Lombok 可以通过注解自动生成。

7.1 添加依赖

<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <version>1.18.30</version>
    <scope>provided</scope>
</dependency>

7.2 常用注解

`@Slf4j`（推荐）

使用 SLF4J API，底层可自由切换 Logback 或 Log4j2。

@RestController
@Slf4j
public class LombokLoggingController {
 
    @RequestMapping("/lombok")
    public String index() {
        log.trace("A TRACE Message");
        log.debug("A DEBUG Message");
        // ...
        return "Check logs";
    }
}

`@CommonsLog`

生成 org.apache.commons.logging.Log 实例，兼容性好。

`@Log4j2`

直接使用 Log4j2 原生 API，生成 org.apache.logging.log4j.Logger 实例。

@RestController
@Log4j2
public class LombokLoggingController {
    // log 已自动生成
}

✅ 建议：日常开发推荐 @Slf4j，兼顾简洁与灵活性。

8. 警惕 Java Util Logging

Spring Boot 支持通过 logging.properties 使用 JDK 自带的 java.util.logging，但强烈不推荐。

⚠️ 原因：

在可执行 JAR 包中存在类加载问题
功能弱，配置繁琐
与主流框架集成差

📌 Spring 4 项目需手动排除 commons-logging 避免冲突；Spring 5+ 已自动处理。

9. Windows 下的 ANSI 颜色支持（JANSI）

Linux/macOS 终端天然支持 ANSI 颜色，但 Windows CMD 默认不支持。

解决方案：JANSI

Logback 配置

<configuration>
    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        <withJansi>true</withJansi>
        <encoder>
            <pattern>[%thread] %highlight(%-5level) %cyan(%logger{15}) - %msg %n</pattern>
        </encoder>
    </appender>
</configuration>

Log4j2 配置

从 Log4j2 2.10 开始，JANSI 不再默认启用。需显式添加依赖并设置：

<!-- 添加 jansi 依赖 -->
<dependency>
    <groupId>org.fusesource.jansi</groupId>
    <artifactId>jansi</artifactId>
    <version>2.4.0</version>
</dependency>

并在 log4j2.xml 中确保未设置 log4j.skipJansi=true。

⚠️ 注意：

JANSI 依赖本地库，只能被一个类加载器加载，Web 应用需将 JAR 放在容器 classpath
Spring Boot 的 Banner 仍为黑白，不受 JANSI 影响

10. 总结

本文系统梳理了 Spring Boot 日志体系的核心要点：

✅ 默认方案：spring-boot-starter-logging + Logback，开箱即用
✅ 生产推荐：切换至 Log4j2，性能更优，功能更强
✅ 代码简化：使用 Lombok @Slf4j 消除样板代码
❌ 避免踩坑：慎用 JUL，注意 Windows 颜色支持限制

所有示例代码已托管至 GitHub：https://github.com/dev-example/spring-boot-logging

Persistence

REST

Security