Logback使用和常用配置

news2025/4/1 14:41:11

Logback 是 Spring Boot 默认集成的日志框架，相比 Log4j，它性能更高、配置更灵活，并且天然支持 Spring Profile 多环境配置。以下是详细配置步骤及常用配置示例。

一、添加依赖（非 Spring Boot 项目）

若项目未使用 Spring Boot，需手动添加 Logback 依赖：

<!-- Maven 依赖 -->
<dependencies>
    <!-- Logback 核心 -->
    <dependency>
        <groupId>ch.qos.logback</groupId>
        <artifactId>logback-classic</artifactId>
        <version>1.4.14</version>
    </dependency>
    <!-- 支持 Spring Profile 配置 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-logging</artifactId>
        <version>3.2.0</version>
    </dependency>
</dependencies>

二、Logback 配置文件

配置文件名为 logback-spring.xml（Spring 推荐命名,logback-spring.xml，SpringBoot会自动加载），放置在 src/main/resources 目录下。

完整配置示例

<?xml version="1.0" encoding="UTF-8"?>
<configuration scan="true" scanPeriod="30 seconds">
    <!-- 通用日志格式 -->
    <property name="LOG_PATTERN" value="%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n" />
    <!-- 日志文件路径 -->
    <property name="LOG_DIR" value="logs" />
    <property name="LOG_FILE" value="${LOG_DIR}/app.log" />

    <!-- 控制台输出（开发环境） -->
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>${LOG_PATTERN}</pattern>
        </encoder>
        <!-- 仅 dev 环境启用 name ="dev" dev是application.yaml文件中的spring.profiles.active的值 -->
        <springProfile name="dev">
            <filter class="ch.qos.logback.classic.filter.ThresholdFilter">
                <level>DEBUG</level>
            </filter>
        </springProfile>
    </appender>

    <!-- 滚动文件输出（生产环境） -->
    <appender name="ROLLING_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>${LOG_FILE}</file>
        <encoder>
            <pattern>${LOG_PATTERN}</pattern>
        </encoder>
        <!-- 滚动策略：按时间 + 大小 -->
        <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
            <fileNamePattern>${LOG_DIR}/app-%d{yyyy-MM-dd}.%i.log.gz</fileNamePattern>
            <maxFileSize>100MB</maxFileSize>
            <maxHistory>30</maxHistory>
            <totalSizeCap>10GB</totalSizeCap>
        </rollingPolicy>
    </appender>

    <!-- 异步日志（提升性能） -->
    <appender name="ASYNC" class="ch.qos.logback.classic.AsyncAppender">
        <queueSize>1024</queueSize>
        <discardingThreshold>0</discardingThreshold>
        <appender-ref ref="ROLLING_FILE" />
    </appender>

    <!-- 日志记录器配置 -->
    <root level="INFO">
        <appender-ref ref="CONSOLE" />
        <appender-ref ref="ASYNC" />
    </root>

    <!-- MyBatis SQL 日志 -->
    <logger name="com.example.mapper" level="DEBUG" additivity="false">
        <appender-ref ref="CONSOLE" />
    </logger>

    <!-- Spring 框架日志降级 -->
    <logger name="org.springframework" level="WARN" />
</configuration>

注：日志文件如果不是logback-spring.xml的名字，springProfile配置会读取不到`dev`或`prod`等环境变量的值

三、核心配置详解

1. 全局配置

<configuration scan="true" scanPeriod="30 seconds">
启用配置文件热更新，每隔 30 秒检查配置变化。
<property>
定义变量（如 LOG_PATTERN），便于复用。

2. 输出器（Appenders）

a. 控制台输出（ConsoleAppender）

<encoder>：定义日志格式，%d 表示时间，%thread 为线程名，%-5level 左对齐日志级别。
<springProfile>：根据 Spring Profile 动态启用（如仅 dev 环境输出 DEBUG 级别）。

b. 滚动文件输出（RollingFileAppender）

<rollingPolicy>：
- SizeAndTimeBasedRollingPolicy：按时间和文件大小滚动。
- fileNamePattern：归档文件名（%i 为滚动序号，.gz 自动压缩）。
- maxFileSize：单个文件最大大小（触发滚动）。
- maxHistory：保留最近 30 天日志。
- totalSizeCap：日志总量上限（避免磁盘占满）。

c. 异步输出（AsyncAppender）

<queueSize>：异步队列大小（默认 256，增大可减少阻塞）。
<discardingThreshold>：队列剩余容量阈值（0 表示队列满时丢弃 INFO 以下日志）。

3. 日志记录器（Loggers）

<root>：根记录器，所有日志的默认配置。
<logger>：
- name：包或类名（如 com.example.mapper）。
- level：日志级别（优先级高于 root）。
- additivity="false"：禁止向上传递日志事件（避免重复输出）。

四、Spring Profile 多环境配置

通过 springProfile 标签实现环境差异化配置：

<!-- 开发环境：输出 DEBUG 到控制台 name ="dev" dev是application.yaml文件中的spring.profiles.active的值 -->
<springProfile name="dev">
    <root level="DEBUG">
        <appender-ref ref="CONSOLE" />
    </root>
</springProfile>

<!-- 生产环境：仅输出 ERROR 到文件 name ="prod" prod是application.yaml文件中的spring.profiles.active的值-->
<springProfile name="prod">
    <root level="INFO">
        <appender-ref ref="ASYNC" />
    </root>
    <logger name="com.example" level="WARN" />
</springProfile>

五、代码中使用日志

在类中通过 SLF4J API 记录日志：

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

@Service
public class UserService {
    private static final Logger logger = LoggerFactory.getLogger(UserService.class);

    public void createUser(String username) {
        logger.debug("创建用户: {}", username);  // DEBUG 级别需配置对应 Logger
        logger.info("用户创建成功: {}", username);
    }
}

六、常见问题排查

日志未输出
- 检查 logback-spring.xml 是否在 src/main/resources 目录。
- 确认依赖无冲突（排除其他日志框架如 Log4j）。
- 检查日志级别是否允许（如 DEBUG 需 Logger 和 Root 均开启）。
滚动文件未生成
- 确认 LOG_DIR 路径存在且有写入权限。
- 检查 fileNamePattern 是否符合预期（如日期格式）。
性能问题
- 使用异步 Appender 并增加 queueSize。
- 避免高频输出 DEBUG 日志（生产环境关闭）。