Log4j 入門實戰（一）：從零搭建日誌系統核心配置

前言：為什麼選擇 Log4j？

Log4j 是 Apache 基金會經典的 Java 日誌框架，憑藉靈活配置、多輸出目標、分級控制、高性能等特性，長期佔據 Java 日誌領域統治地位。雖然 Log4j 2.x 和 SLF4J+Logback 逐漸成為主流，但理解 Log4j 1.x 核心機制對維護老項目、掌握日誌框架設計思想極有價值。

一、核心三大組件

二、極速上手：5 分鐘搭建第一個日誌系統

2.1 Maven 依賴

<dependency>
    <groupId>log4j</groupId>
    <artifactId>log4j</artifactId>
    <version>1.2.17</version>
</dependency>

2.2 log4j.properties 核心配置（放入 src/main/resources）

### 根 Logger 配置：級別 DEBUG，掛載兩個 Appender
log4j.rootLogger=DEBUG, console, file

### ConsoleAppender：控制台輸出
log4j.appender.console=org.apache.log4j.ConsoleAppender
log4j.appender.console.Target=System.out
log4j.appender.console.layout=org.apache.log4j.PatternLayout
log4j.appender.console.layout.ConversionPattern=%d{yyyy-MM-dd HH:mm:ss} [%t] %-5p %c - %m%n

### FileAppender：文件輸出（帶滾動）
log4j.appender.file=org.apache.log4j.RollingFileAppender
log4j.appender.file.File=logs/app.log
log4j.appender.file.MaxFileSize=10MB
log4j.appender.file.MaxBackupIndex=10
log4j.appender.file.layout=org.apache.log4j.PatternLayout
log4j.appender.file.layout.ConversionPattern=%d{yyyy-MM-dd HH:mm:ss} [%t] %-5p %c - %m%n

2.3 Java 代碼調用

import org.apache.log4j.Logger;

public class Log4jDemo {
    private static final Logger logger = Logger.getLogger(Log4jDemo.class);

    public static void main(String[] args) {
        logger.debug("調試信息：進入主方法");
        logger.info("業務信息：用戶登錄成功");
        logger.warn("警告信息：緩存命中率低於 50%");
        logger.error("錯誤信息：數據庫連接失敗", new SQLException("Connection timeout"));
        logger.fatal("致命錯誤：系統崩潰");
    }
}

2.4 運行效果

2024-01-15 10:30:45 [main] DEBUG Log4jDemo - 調試信息：進入主方法
2024-01-15 10:30:45 [main] INFO  Log4jDemo - 業務信息：用戶登錄成功
2024-01-15 10:30:45 [main] WARN  Log4jDemo - 警告信息：緩存命中率低於 50%
2024-01-15 10:30:45 [main] ERROR Log4jDemo - 錯誤信息：數據庫連接失敗
java.sql.SQLException: Connection timeout
    at Log4jDemo.main(Log4jDemo.java:18)
2024-01-15 10:30:45 [main] FATAL Log4jDemo - 致命錯誤：系統崩潰

三、核心配置詳解：PatternLayout 轉換符號大全

ConversionPattern 控制每條日誌的輸出格式，常用符號：

格式修飾符：%20c（右對齊寬度 20）、%-20c（左對齊）、%.30c（截斷超長）。

四、進階配置：多環境隔離與異步日誌

4.1 多環境配置隔離

使用 log4j-dev.properties、log4j-prod.properties，通過 JVM 參數 -Dlog4j.configuration=file:/path/to/log4j-prod.properties 或 Spring Profile 動態加載。

4.2 異步日誌提升性能（Log4j 1.x 需配合 Disruptor 或自定義 AsyncAppender）

log4j.appender.async=org.apache.log4j.AsyncAppender
log4j.appender.async.BufferSize=512
log4j.appender.async.AppenderRef=file
log4j.rootLogger=DEBUG, async

五、避坑指南與最佳實踐

1. Logger 實例靜態化：private static final Logger logger = Logger.getLogger(Xxx.class); 避免重複創建。
2. 級別守護：生產環境根 Logger 設為 INFO 或 WARN，關鍵模塊單獨開 DEBUG：
   log4j.logger.com.example.core=DEBUG
3. 避免字符串拼接：使用參數化日誌 logger.debug("用戶 {} 登錄, IP: {}", username, ip);（需 SLF4J 門面支撐）。
4. 異常堆棧必傳：logger.error("操作失敗", e); 而非 logger.error("操作失敗: " + e.getMessage());
5. 文件滾動策略：生產環境強制使用 RollingFileAppender 或 DailyRollingFileAppender，防止單文件過大導致磁盤寫滿、查閱困難。

六、下期預告

下篇將深入講解 Log4j 進階配置詳解：多 Appender 組合、自定義 Layout、JDBCAppender 入庫、SMTPAppender 郵件告警、Log Factor 5 可視化分析、以及遷移到 Log4j 2.x / SLF4J+Logback 的最佳路徑。