Apache Commons Logging 實戰：統一日誌門面與 Log4j 整合完整指南

Jakarta Commons Logging (JCL) 提供輕量級、與具體日誌實現解耦的門面介面，讓中間件/框架開發者無綁定地記錄日誌，應用層再決定具體實現 (Log4j、JDK 1.4、LogKit 等)。本文從核心概念、快速上手、開發流程、日誌級別規範，到 Log4j 整合實戰與輸出對比，完整呈現 JCL 使用全貌。

核心架構與自動發現機制

JCL 兩大核心抽象：

• Log：基本記錄器介面
• LogFactory：負責建立 Log 實例的工廠

LogFactory 自動發現順序 (找到即停止)：

1. 查找 org.apache.commons.logging.Log 系統屬性
2. 查找同名 Context ClassLoader 資源
3. Classpath 有 log4j → 使用 Log4JLogger 包裝器
4. 運行在 JDK 1.4+ → 使用 Jdk14Logger 包裝器
5. 回退使用內建 SimpleLog (輸出至 System.err)

內建實現類：

• org.apache.commons.logging.impl.Log4JLogger - Log4j 包裝
• org.apache.commons.logging.impl.Jdk14Logger - JDK Logging 包裝
• org.apache.commons.logging.impl.LogKitLogger - Avalon LogKit 包裝
• org.apache.commons.logging.impl.SimpleLog - 簡易實現，輸出至 stderr
• org.apache.commons.logging.impl.NoOpLog - 空實現，不輸出任何內容

快速上手四步驟

1. 部署： commons-logging.jar + log4j.jar 放入專案 lib 並加入 Classpath
2. 指定實現： 建立 commons-logging.properties (Classpath 根目錄)：

   # 使用 Log4j 作為底層實現
   org.apache.commons.logging.Log=org.apache.commons.logging.impl.Log4JCategoryLog
   
   # 可選：JDK 1.4 Logging
   # org.apache.commons.logging.Log=org.apache.commons.logging.impl.Jdk14Logger
   
   # 可選：簡易日誌
   # org.apache.commons.logging.Log=org.apache.commons.logging.impl.SimpleLog

3. 取得 Logger：

   import org.apache.commons.logging.Log;
   import org.apache.commons.logging.LogFactory;
   
   public class MyClass {
       private static final Log log = LogFactory.getLog(MyClass.class);
       // ...
   }

4. 記錄日誌： log.debug("...")、log.info("...") 等

Log 介面完整方法列表

按嚴重度高到低：

fatal(Object message)
fatal(Object message, Throwable t)
error(Object message)
error(Object message, Throwable t)
warn(Object message)
warn(Object message, Throwable t)
info(Object message)
info(Object message, Throwable t)
debug(Object message)
debug(Object message, Throwable t)
trace(Object message)
trace(Object message, Throwable t)

防護方法 (避免不必要的字串構建開銷)：

isFatalEnabled()
isErrorEnabled()
isWarnEnabled()
isInfoEnabled()
isDebugEnabled()
isTraceEnabled()

// 使用範例
if (log.isDebugEnabled()) {
    log.debug("耗時操作結果: " + expensiveComputation());
}

日誌級別規範與最佳實踐

原則： 生產環境 Logger 級別通常不低於 INFO，DEBUG/TRACE 僅開發/除錯時啟用。

整合 Log4j 實戰對比

無配置檔案 (使用 SimpleLog)

// Test.java
package sample;
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;

public class Test {
    private static Log log = LogFactory.getLog(Test.class);
    public void log() {
        log.debug("Debug info.");
        log.info("Info info");
        log.warn("Warn info");
        log.error("Error info");
        log.fatal("Fatal info");
    }
    public static void main(String[] args) {
        new Test().log();
    }
}

輸出 (輸出至 stderr，含類別/方法/行號)：

DEBUG sample.Test.log(Test.java:13) Debug info.
INFO sample.Test.log(Test.java:14) Info info
WARN sample.Test.log(Test.java:15) Warn info
ERROR sample.Test.log(Test.java:16) Error info
FATAL sample.Test.log(Test.java:17) Fatal info

加入 Log4j 配置

1. 加入 log4j.jar
2. commons-logging.properties 指定 Log4JCategoryLog
3. log4j.properties 配置輸出格式：

   log4j.rootLogger=info, stdout
   log4j.appender.stdout=org.apache.log4j.ConsoleAppender
   log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
   log4j.appender.stdout.layout.ConversionPattern=%5p [%t] - %m%n

輸出 (依 PatternLayout 格式，DEBUG 被 rootLogger 級別 INFO 過濾)：

INFO [main] - Info info
WARN [main] - Warn info
ERROR [main] - Error info
FATAL [main] - Fatal info

進階特性

• 可序列化： JCL 物件可跨 RMI 傳遞，易於從字元/位元組流提取與存儲
• 名稱映射配置： 可將 XML 設定中的名稱映射至 Java 名稱，避免 XML 變更導致代碼修改
• 動態切換： 無需重編譯即可切換底層日誌實現 (修改 properties 或系統屬性)

相關資源

本系列文檔：

1. Apache Log4j 配置說明
2. Apache Log4j 使用實例
3. Apache Commons-logging 使用實例 (本文)
4. 如何自建 Appender 擴展 Log4j 框架

本文出自「子孑」部落格，轉載請保留出處：https://zhangjunhd.blog.51cto.com/113473/25135