MyBatis SQL 日誌配置全攻略：Log4j2/Log4j/SLF4J 多框架整合與精細控制

MyBatis SQL 日誌輸出完整指南：從基礎配置到生產環境精細控制

MyBatis 內建日誌工廠自動適配 SLF4J、Log4j2、Log4j、JDK Logging、StdOut 等實現。本文詳細講解如何配置 Mapper 接口/語句級別的 SQL 日誌輸出，實現開發調試與生產監控的靈活切換。

一、日誌實現自動發現順序

MyBatis 按以下優先級自動綁定日誌實現 (org.apache.ibatis.logging.LogFactory)：

1. SLF4J (含 Logback、Log4j2 SLF4J 綁定)
2. Log4j2 (org.apache.logging.log4j)
3. Log4j (log4j 1.x)
4. JDK Logging (java.util.logging)
5. StdOut (System.out) — 預設回退

建議：統一使用 **SLF4J + Logback/Log4j2**，避免多框架衝突。

二、Log4j2 配置範例 (推薦)

1. Maven 依賴

<dependency>
    <groupId>org.apache.logging.log4j</groupId>
    <artifactId>log4j-slf4j2-impl</artifactId> <!-- SLF4J 綁定 Log4j2 -->
    <version>2.23.1</version>
</dependency>
<dependency>
    <groupId>org.apache.logging.log4j</groupId>
    <artifactId>log4j-api</artifactId>
    <version>2.23.1</version>
</dependency>
<dependency>
    <groupId>org.apache.logging.log4j</groupId>
    <artifactId>log4j-core</artifactId>
    <version>2.23.1</version>
</dependency>

2. log4j2.xml 精細控制配置

<Configuration status="WARN" monitorInterval="60">
    <Properties>
        <Property name="sqlPattern">[%d{HH:mm:ss.SSS}] [%t] %-5level %c{1.} - %msg%n</Property>
    </Properties>
    
    <Appenders>
        <Console name="Console" target="SYSTEM_OUT">
            <PatternLayout pattern="${sqlPattern}"/>
        </Console>
        <RollingFile name="SqlFile" fileName="logs/sql.log" filePattern="logs/sql-%d{yyyy-MM-dd}.log.gz">
            <PatternLayout pattern="${sqlPattern}"/>
            <Policies>
                <TimeBasedTriggeringPolicy interval="1"/>
                <SizeBasedTriggeringPolicy size="50 MB"/>
            </Policies>
            <DefaultRolloverStrategy max="30"/>
        </RollingFile>
    </Appenders>
    
    <Loggers>
        <!-- 1. Mapper 接口級別：輸出該接口所有語句 SQL + 參數 + 結果 -->
        <Logger name="com.myapp.mapper.UserMapper" level="DEBUG" additivity="false">
            <AppenderRef ref="SqlFile"/>
        </Logger>
        
        <!-- 2. 單條語句級別：僅輸出 selectUserById 的 SQL -->
        <Logger name="com.myapp.mapper.UserMapper.selectUserById" level="DEBUG" additivity="false">
            <AppenderRef ref="SqlFile"/>
        </Logger>
        
        <!-- 3. 包級別：整個 mapper 包 -->
        <Logger name="com.myapp.mapper" level="DEBUG" additivity="false">
            <AppenderRef ref="SqlFile"/>
        </Logger>
        
        <!-- 4. 只輸出 SQL 不輸出參數/結果 (TRACE 級別才有參數/結果) -->
        <Logger name="com.myapp.mapper" level="DEBUG" additivity="false"> <!-- DEBUG=SQL, TRACE=參數/結果 -->
            <AppenderRef ref="SqlFile"/>
        </Logger>
        
        <Root level="INFO">
            <AppenderRef ref="Console"/>
        </Root>
    </Loggers>
</Configuration>

三、Logback 配置範例 (Spring Boot 預設)

<configuration>
    <appender name="SQL_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>logs/sql.log</file>
        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <fileNamePattern>logs/sql-%d{yyyy-MM-dd}.log.gz</fileNamePattern>
            <maxHistory>30</maxHistory>
        </rollingPolicy>
        <encoder>
            <pattern>[%d{HH:mm:ss.SSS}] [%thread] %-5level %logger{10} - %msg%n</pattern>
        </encoder>
    </appender>
    
    <!-- Mapper 接口 -->
    <logger name="com.myapp.mapper.UserMapper" level="DEBUG" additivity="false">
        <appender-ref ref="SQL_FILE"/>
    </logger>
    
    <!-- 單條語句 -->
    <logger name="com.myapp.mapper.UserMapper.selectUserById" level="DEBUG" additivity="false">
        <appender-ref ref="SQL_FILE"/>
    </logger>
    
    <root level="INFO">
        <appender-ref ref="CONSOLE"/>
    </root>
</configuration>

四、MyBatis 映射文件 vs 註解映射：Logger 名稱規則

結論：無論註解還是 XML，**Logger 名稱完全一致**，配置無差別。

五、日誌級別語義對照表

生產環境建議：Mapper 設置 DEBUG 只看 SQL；問題排查時臨時改 TRACE 看參數結果 (熱重載生效)。

六、Spring Boot 整合零配置

application.yml

logging:
  level:
    com.myapp.mapper: DEBUG  # 包級別開啟 SQL 日誌
    # com.myapp.mapper.UserMapper.selectById: DEBUG  # 單條語句
  pattern:
    console: "[%d{HH:mm:ss.SSS}] [%thread] %-5level %logger{15} - %msg%n"
  file:
    name: logs/application.log
logback:
  rollingpolicy:
    max-history: 30

七、進階技巧與避坑

1. P6Spy / Druid StatFilter：JDBC 層面攔截，**無需修改代碼/配置 Logger**，支援格式化 SQL、慢查詢統計、參數格式化，生產環境首選。
2. MyBatis 內建 StdOut：無日誌框架時，控制台直接輸出，配置 settings.logImpl=STDOUT_LOGGING 或無依賴自動回退。
3. 參數佔位符：MyBatis 3.5+ 支援 logPrefix 自定義前綴區分多租戶/數據源。
4. 大結果集效能：TRACE 級別序列化結果集極慢，**嚴禁生產常開**。
5. 多租戶/動態數據源：Logger 名稱加入租戶 ID 前綴，配合 MDC 實現日誌隔離。

八、總結

• MyBatis SQL 日誌本質是 **Logger 名稱 = Mapper 命名空間 + 語句 ID**。
• 配置 Logger 級別為 DEBUG 即可輸出 SQL 與參數，TRACE 額外輸出結果集。
• 推薦 **Log4j2/Logback + RollingFile** 生產部署，additivity="false" 避免重複輸出。
• 生產環境強烈建議接入 **P6Spy** 或 **Druid 監控**，非侵入式、效能影響微乎其微。