Springboot之logback 配置说明

理解配置文件基础

Logback 的配置通常通过 XML 文件实现。首先需要了解配置文件的加载顺序 和基本结构。

• 配置文件加载顺序 ：Logback 会按以下顺序在类路径（通常是 src/main/resources目录）下查找配置文件：

  1. logback-test.xml

  2. logback.groovy

  3. logback.xml

     如果以上文件均未找到，Logback 会使用默认的基础配置（BasicConfigurator），将日志输出到控制台。

• Spring Boot 项目建议 ：在 Spring Boot 中，建议使用 logback-spring.xml作为配置文件名，这样可以启用 Spring Boot 特有的扩展功能，如多环境配置。

• 基本结构：一个典型的 Logback 配置文件结构如下

  <configuration scan="true" scanPeriod="30 seconds">
    <!-- 定义变量 -->
    <property name="LOG_HOME" value="./logs" />
    <!-- 定义输出目的地 (Appender) -->
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">...</appender>
    <!-- 定义特定包或类的日志级别 -->
    <logger name="com.example.controller" level="DEBUG" />
    <!-- 根日志记录器配置 -->
    <root level="INFO">
      <appender-ref ref="CONSOLE" />
    </root>
  </configuration>

  根节点 <configuration>支持 scan属性（设为 true可开启配置文件变更自动重新加载）和 scanPeriod属性（设置扫描周期）。

⚙️ 核心组件详解

Logback 配置的核心在于理解三个主要组件：Logger 、Appender ​ 和 Layout/Encoder。

🔹 1. Logger：日志记录器

Logger 负责捕获日志信息，你可以为不同的包或类设置不同的日志级别，实现精细化的日志控制。

• 日志级别 ：从低到高依次为 TRACE< DEBUG< INFO< WARN< ERROR。设置某个级别后，级别更高的日志会自动生效。

• 根 Logger <root>：所有 Logger 的最终祖先，必须配置其级别和 Appender。

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

• 特定 Logger <logger> ：为特定的包或类设置单独的日志规则。name属性指定包名或类名，level设置级别，additivity="false"可避免日志向上级（如 root）传递导致重复输出。

  <logger name="com.example.service" level="DEBUG" additivity="false"/>

🔹 2. Appender：日志输出源

Appender 定义了日志的输出目的地。常用的有以下几种类型：

• 控制台输出 (ConsoleAppender)：将日志输出到控制台。

  <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
    <encoder>
      <pattern>%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n</pattern>
      <charset>UTF-8</charset> <!-- 避免中文乱码 -->
    </encoder>
  </appender>

• 文件滚动记录 (RollingFileAppender)：这是最常用的文件输出方式，支持按时间或文件大小进行日志归档和切割，防止单个日志文件过大。

  •   <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>${LOG_HOME}/app.log</file> <!-- 当前正在写入的日志文件 -->
        <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
          <!-- 归档日志文件的命名模式，按天和索引分割 -->
          <fileNamePattern>${LOG_HOME}/app.%d{yyyy-MM-dd}.%i.log.gz</fileNamePattern>
          <!-- 保留最近7天的历史日志 -->
          <maxHistory>7</maxHistory>
          <!-- 单个日志文件最大100MB -->
          <maxFileSize>100MB</maxFileSize>
          <!-- 所有日志文件总大小上限 -->
          <totalSizeCap>2GB</totalSizeCap>
        </rollingPolicy>
        <encoder>
          <pattern>%d{ISO8601} [%thread] %level %logger - %msg%n</pattern>
        </encoder>
      </appender>

🔹 3. Encoder 与 Pattern

Encoder（推荐使用，功能更强大）或 Layout 负责将日志事件转换成字符串格式。

• 常用日志格式占位符​：

  占位符	说明
  %d{pattern}	日期时间，如 %d{yyyy-MM-dd HH:mm:ss.SSS}
  %thread	输出日志的线程名
  %-5level	日志级别（左对齐，宽度5）
  %logger{length}	输出日志的Logger名称，如 %logger{36}表示最长36字符
  %msg	应用程序输出的日志消息内容
  %n	平台相关的换行符
  %highlight()	高亮显示（通常用于控制台，为不同级别的日志着色）
  %X{key}	输出 MDC (Mapped Diagnostic Context) 中存储的变量，用于链路追踪等

💡 高级特性与最佳实践

🔸 多环境配置 (Spring Boot)

在 logback-spring.xml中，可以使用 <springProfile>标签为不同环境（如开发、生产）定义不同的日志配置。

<springProfile name="dev">
  <root level="DEBUG">
    <appender-ref ref="CONSOLE"/>
  </root>
</springProfile>
<springProfile name="prod">
  <root level="INFO">
    <appender-ref ref="FILE"/>
  </root>
</springProfile>

🔸 异步日志

对于性能要求较高的应用，可以使用 AsyncAppender将日志写入操作异步化，减少对主线程的阻塞。

<appender name="ASYNC_FILE" class="ch.qos.logback.classic.AsyncAppender">
  <!-- 不丢失日志。默认情况下，当队列剩余容量低于20%时，会丢弃TRACE, DEBUG, INFO级别的日志，设为0则不丢弃 -->
  <discardingThreshold>0</discardingThreshold>
  <!-- 更改默认的队列的深度，该值会影响性能。默认值为256 -->
  <queueSize>256</queueSize>
  <!-- 添加附加的appender，最多只能添加一个 -->
  <appender-ref ref="FILE"/>
</appender>

🔸 使用 <property>定义变量

可以定义变量来复用配置值，如日志存储路径，使配置更易于维护。

<property name="LOG_HOME" value="/opt/application/logs"/>

💎 配置示例与总结

下面是一个结合了上述知识的完整配置示例，适用于大多数生产环境：

<?xml version="1.0" encoding="UTF-8"?>
<configuration scan="false" scanPeriod="60 seconds">
    <property name="LOG_HOME" value="./logs"/>
    <property name="APP_NAME" value="my-application"/>

    <!-- 输出到控制台 -->
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %highlight(%-5level) %cyan(%logger{50}) - %msg%n</pattern>
            <charset>UTF-8</charset>
        </encoder>
    </appender>

    <!-- 输出到文件，按日期和大小滚动 -->
    <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>${LOG_HOME}/${APP_NAME}.log</file>
        <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
            <fileNamePattern>${LOG_HOME}/${APP_NAME}.%d{yyyy-MM-dd}.%i.log</fileNamePattern>
            <maxHistory>30</maxHistory>
            <maxFileSize>100MB</maxFileSize>
            <totalSizeCap>2GB</totalSizeCap>
        </rollingPolicy>
        <encoder>
            <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{50} - %msg%n</pattern>
            <charset>UTF-8</charset>
        </encoder>
    </appender>

    <!-- 为特定包设置DEBUG级别，用于调试 -->
    <logger name="com.yourcompany.yourapp.service" level="DEBUG" additivity="false">
        <appender-ref ref="FILE"/>
    </logger>

    <!-- 设置Spring框架的日志级别为WARN，减少不必要的输出 -->
    <logger name="org.springframework" level="WARN"/>

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