Spring Boot 日志处理

约 1045 字大约 3 分钟

2025-08-16

一、日志框架概述

1. 为什么需要专业日志框架

在项目开发中，直接使用System.out.println存在明显问题：

当需要关闭日志时，必须逐行注释
当需要重新开启日志时，又得逐行取消注释
无法灵活控制日志级别和输出格式

2. Spring Boot 默认日志框架

Spring Boot 默认集成了 SLF4J + Logback 组合：

SLF4J：简单日志门面，提供统一的日志接口
Logback：SLF4J 的实现，性能优于 Log4j

Spring Boot 项目无需额外添加依赖，因为 spring-boot-starter 已包含 spring-boot-starter-logging

二、日志级别

日志级别从低到高分为：

TRACE < DEBUG < INFO < WARN < ERROR < FATAL

DEBUG：开发调试信息
INFO：程序运行关键信息（Spring Boot 默认级别）
WARN：警告信息
ERROR：错误信息

三、基本使用方法

1. 添加 Lombok 注解

import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@Slf4j
@RestController
public class LogController {

    @GetMapping("/log")
    public String showLog() {
        log.debug("debug级别的日志信息...");
        log.info("info级别的日志信息...");
        log.warn("warn级别的日志信息...");
        log.error("error级别的日志信息...");
        
        return "ok";
    }
}

2. 在 application.yml 中配置

logging:
  level:
    root: info  # 设置根日志级别
    com.example: debug  # 设置特定包的日志级别
  # file: ./logs/app.log  # 指定日志文件路径

四、自定义 logback-spring.xml 配置

1. 基本结构

在 resources 目录下创建 logback-spring.xml：

<?xml version="1.0" encoding="UTF-8"?>
<configuration scan="true" scanPeriod="30 seconds">
    
    <!-- 定义变量 -->
    <property name="LOG_PATH" value="./logs" />
    
    <!-- 彩色控制台输出 -->
    <property name="CONSOLE_LOG_PATTERN" 
              value="%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n"/>
    
    <!-- 控制台输出 -->
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>${CONSOLE_LOG_PATTERN}</pattern>
            <charset>UTF-8</charset>
        </encoder>
    </appender>
    
    <!-- 按日期滚动的日志文件 -->
    <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>${LOG_PATH}/app.log</file>
        <encoder>
            <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{50} - %msg%n</pattern>
        </encoder>
        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <!-- 每天生成新文件 -->
            <fileNamePattern>${LOG_PATH}/app-%d{yyyy-MM-dd}.log</fileNamePattern>
            <!-- 保留30天历史 -->
            <maxHistory>30</maxHistory>
        </rollingPolicy>
    </appender>
    
    <!-- 开发环境配置 -->
    <springProfile name="dev">
        <root level="debug">
            <appender-ref ref="CONSOLE" />
        </root>
    </springProfile>
    
    <!-- 生产环境配置 -->
    <springProfile name="prod">
        <root level="info">
            <appender-ref ref="FILE" />
        </root>
    </springProfile>
    
</configuration>

2. 常用配置说明

配置项	说明
`scan="true"`	配置文件修改后自动重新加载
`scanPeriod="30 seconds"`	检查配置文件变更的间隔
`property`	定义变量，可通过 `${VAR_NAME}` 引用
`springProfile`	根据环境激活不同配置
`ThresholdFilter`	过滤低于指定级别的日志
`LevelFilter`	精确过滤特定级别的日志

3. 常用 Appender

ConsoleAppender：输出到控制台
RollingFileAppender：滚动文件输出（按时间/大小）

五、多环境日志配置

在 logback-spring.xml 中使用 <springProfile> 标签：

<!-- 开发环境：控制台输出，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>

启动应用时指定环境：

java -jar app.jar --spring.profiles.active=prod

六、实用技巧

1. 按级别分离日志文件

<!-- ERROR级别单独文件 -->
<appender name="ERROR_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
    <file>${LOG_PATH}/error.log</file>
    <filter class="ch.qos.logback.classic.filter.LevelFilter">
        <level>ERROR</level>
        <onMatch>ACCEPT</onMatch>
        <onMismatch>DENY</onMismatch>
    </filter>
    <!-- 其他配置... -->
</appender>

2. 查看 SQL 语句（MyBatis）

在 application.yml 中添加：

logging:
  level:
    # 设置MyBatis Mapper包的级别为DEBUG
    com.example.mapper: debug
    # 显示SQL语句（Spring Data JPA）
    org.hibernate.SQL: debug
    # 显示SQL参数
    org.hibernate.type.descriptor.sql: trace

3. 简单配置示例（推荐初学者使用）

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <property name="LOG_PATH" value="./logs"/>
    
    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>
    
    <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>${LOG_PATH}/app.log</file>
        <encoder>
            <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{50} - %msg%n</pattern>
        </encoder>
        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <fileNamePattern>${LOG_PATH}/app-%d{yyyy-MM-dd}.log</fileNamePattern>
        </rollingPolicy>
    </appender>
    
    <root level="info">
        <appender-ref ref="STDOUT" />
        <appender-ref ref="FILE" />
    </root>
</configuration>

七、常见问题

1. 如何临时提高特定包的日志级别？

在 application.yml 中：

logging:
  level:
    com.example.service: debug
    org.springframework.web: trace

2. 日志文件过大怎么办？

在 RollingFileAppender 中配置：

<rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
    <fileNamePattern>${LOG_PATH}/app-%d{yyyy-MM-dd}.%i.log</fileNamePattern>
    <timeBasedFileNamingAndTriggeringPolicy 
        class="ch.qos.logback.core.rolling.SizeAndTimeBasedFNATP">
        <maxFileSize>100MB</maxFileSize>
    </timeBasedFileNamingAndTriggeringPolicy>
    <maxHistory>30</maxHistory>
</rollingPolicy>

3. 如何格式化 JSON 日志？

添加 Logstash Encoder 依赖：

<dependency>
    <groupId>net.logstash.logback</groupId>
    <artifactId>logstash-logback-encoder</artifactId>
    <version>6.6</version>
</dependency>

然后在配置中：

<encoder class="net.logstash.logback.encoder.LoggingEventCompositeJsonEncoder">
    <providers>
        <timestamp>
            <fieldName>@timestamp</fieldName>
        </timestamp>
        <message/>
        <loggerName>
            <fieldName>logger</fieldName>
        </loggerName>
        <threadName/>
        <logLevel/>
        <stackTrace>
            <fieldName>exception</fieldName>
        </stackTrace>
    </providers>
</encoder>