SLF4J + Logback 在 Java 專案中的完整配置實戰指南

Logback 作為 Log4j 創始人設計的新一代日誌框架，憑藉更高效能、原生支援 SLF4J、熱重載配置、豐富的 Appender 與 Filter 機制，已成為 Java 生產環境的首選。本文從核心概念、Maven 依賴、logback.xml 完整配置範例、進階功能（非同步、資料庫、Hibernate SQL 追蹤）到實戰最佳實踐，一次講透。

為什麼選 Logback？核心優勢速覽

• 效能提升 10 倍+：核心重寫，關鍵路徑優化，初始化記憶體佔用更低。
• 原生實作 SLF4J API：零綁定，切換日誌實作只需換 jar，業務碼零修改。
• 配置熱重載：scan="true" 修改 logback.xml 即時生效，無需重啟應用。
• 強大的 Filter 與 SiftingAppender：依使用者、Session、Logger 名稱動態分流、分級、分檔。
• 自動壓縮、清理舊檔：SizeAndTimeBasedFNATP + maxHistory 一行搞定。
• 堆疊追蹤攜帶套件版本：排查依賴衝突更直觀。

Maven 依賴 (SLF4J 2.x + Logback 1.4+)

<dependencies>
  <dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-api</artifactId>
    <version>2.0.9</version>
  </dependency>
  <dependency>
    <groupId>ch.qos.logback</groupId>
    <artifactId>logback-classic</artifactId>
    <version>1.4.11</version>
  </dependency>
  <dependency>
    <groupId>ch.qos.logback</groupId>
    <artifactId>logback-core</artifactId>
    <version>1.4.11</version>
  </dependency>
  
  <dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>log4j-over-slf4j</artifactId>
    <version>2.0.9</version>
  </dependency>
</dependencies>

生產級 logback.xml 完整範例 (含註解)

<?xml version="1.0" encoding="UTF-8"?>
<configuration scan="true" scanPeriod="30 seconds" debug="false">

  <!-- 全域變數 -->
  <property name="LOG_HOME" value="${user.home}/logs/myapp" />
  <property name="APP_NAME" value="myapp" />
  <property name="PATTERN_CONSOLE" value="%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n" />
  <property name="PATTERN_FILE" value="%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36}:%line - %msg%n" />

  <!-- Console Appender -->
  <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
    <encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
      <pattern>${PATTERN_CONSOLE}</pattern>
      <charset>UTF-8</charset>
    </encoder>
  </appender>

  <!-- Rolling File Appender：按天 + 檔案大小雙觸發，自動壓縮 .gz -->
  <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.gz</fileNamePattern>
      <maxFileSize>100MB</maxFileSize>
      <maxHistory>30</maxHistory>
      <totalSizeCap>3GB</totalSizeCap>
    </rollingPolicy>
    <encoder>
      <pattern>${PATTERN_FILE}</pattern>
      <charset>UTF-8</charset>
    </encoder>
  </appender>

  <!-- 非同步 Appender：高併發下降低業務執行緒阻塞 -->
  <appender name="ASYNC_FILE" class="ch.qos.logback.classic.AsyncAppender">
    <queueSize>512</queueSize>
    <discardingThreshold>0</discardingThreshold> <!-- 不丟棄 -->
    <appender-ref ref="FILE" />
  </appender>

  <!-- 第三方套件靜音 -->
  <logger name="org.springframework" level="WARN" additivity="false">
    <appender-ref ref="ASYNC_FILE" />
  </logger>
  <logger name="org.hibernate" level="WARN" additivity="false">
    <appender-ref ref="ASYNC_FILE" />
  </logger>
  <!-- Hibernate SQL 追蹤 (除錯時暫時開 DEBUG) -->
  <logger name="org.hibernate.SQL" level="DEBUG" additivity="false">
    <appender-ref ref="ASYNC_FILE" />
  </logger>
  <logger name="org.hibernate.type.descriptor.sql.BasicBinder" level="TRACE" additivity="false">
    <appender-ref ref="ASYNC_FILE" />
  </logger>

  <!-- 業務包預設 INFO，輸出到非同步檔案 -->
  <logger name="com.mycompany" level="INFO" additivity="true">
    <appender-ref ref="ASYNC_FILE" />
  </logger>

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

</configuration>

關鍵配置細節解析

1. SizeAndTimeBasedRollingPolicy = 時間 + 大小雙重觸發

• %d{yyyy-MM-dd}：每天產生新檔。
• %i：同一天若超過 maxFileSize (100MB) 自動分卷 (0,1,2...)。
• .gz 結尾：自動 gzip 壓縮，非同步進行，不阻塞寫入。
• maxHistory=30：保留 30 天，超過自動刪除。
• totalSizeCap=3GB：總大小上限，防止磁碟爆滿。

2. AsyncAppender 非同步寫入

• 業務執行緒只將日誌事件丟入 BlockingQueue (預設 256，此處調大至 512)，專屬背景執行緒落盤。
• discardingThreshold=0：隊列滿時阻塞而非丟棄，保證不丟日誌（高峰期可能略微增加延遲，但資料安全）。

3. additivity="false" 避免重複輸出

預設 additivity=true，子 Logger 會同時輸出到自己與 Root 的 Appender。設為 false 並顯式指定 appender-ref，可精確控制輸出目的地，避免 Console 重複、檔案重複。

Java 程式碼中正確使用 SLF4J API

@Slf4j // Lombok 自動產生 private static final Logger log = LoggerFactory.getLogger(ThisClass.class);
public class OrderService {

    public void createOrder(OrderDTO dto) {
        log.info("開始建立訂單 userId={}, items={}", dto.getUserId(), dto.getItems()); // 佔位符延遲字串拼接
        try {
            // 業務邏輯...
            log.debug("訂單明細儲存成功 orderNo={}", orderNo);
        } catch (Exception e) {
            log.error("建立訂單失敗 userId={}", dto.getUserId(), e); // 最後一個參數傳 Throwable，自動印堆疊
            throw new BizException("ORDER_CREATE_FAILED", e);
        }
    }
}

進階技巧：MDC 追蹤請求鏈路、動態調整日誌級別

MDC (Mapped Diagnostic Context) 注入 TraceId

// Filter / Interceptor 中
MDC.put("traceId", UUID.randomUUID().toString().replace("-", ""));
try {
    chain.doFilter(request, response);
} finally {
    MDC.remove("traceId");
}

Pattern 加入 %X{traceId} 即可在每行日誌看到追蹤 ID，配合 ELK / Loki 快速串聯微服務鏈路。

JMX / Actuator 運行時動態調整 Level

Spring Boot Actuator 暴露 /actuator/loggers，可不重啟將 com.mycompany 從 INFO 降為 DEBUG 觀察細節，觀察完再改回 INFO。

避坑清單

總結

Logback + SLF4J 是 Java 日誌的「黃金組合」：以介面隔離實作、以非同步保效能、以滾動策略控磁碟、以 MDC 串鏈路。掌握上述配置模板與最佳實踐，即可在從單體到微服務的各類專案中穩健落地，專注業務而非日誌基建。