日志框架集成

MyBatis 内置日志工厂 org.apache.ibatis.logging.LogFactory，支持多种日志框架自动发现与集成。合理配置日志框架是排查 SQL 执行问题的第一步。

MyBatis 日志架构

MyBatis 按照优先级自动探测日志实现，顺序如下：

注意：MyBatis 3.5.x 推荐使用 SLF4J + Logback 组合，生态成熟、配置灵活。

Maven 依赖配置

SLF4J + Logback 组合（推荐）

<dependencies>
    <!-- SLF4J API -->
    <dependency>
        <groupId>org.slf4j</groupId>
        <artifactId>slf4j-api</artifactId>
        <version>2.0.9</version>
    </dependency>

    <!-- Logback 实现 -->
    <dependency>
        <groupId>ch.qos.logback</groupId>
        <artifactId>logback-classic</artifactId>
        <version>1.4.14</version>
    </dependency>
</dependencies>

SLF4J + Log4j2 组合

<dependencies>
    <!-- SLF4J API -->
    <dependency>
        <groupId>org.slf4j</groupId>
        <artifactId>slf4j-api</artifactId>
        <version>2.0.9</version>
    </dependency>

    <!-- Log4j2 SLF4J 桥接 -->
    <dependency>
        <groupId>org.apache.logging.log4j</groupId>
        <artifactId>log4j-slf4j2-impl</artifactId>
        <version>2.22.0</version>
    </dependency>

    <!-- Log4j2 核心 -->
    <dependency>
        <groupId>org.apache.logging.log4j</groupId>
        <artifactId>log4j-core</artifactId>
        <version>2.22.0</version>
    </dependency>
</dependencies>

注意：不要同时引入多个日志实现，否则 MyBatis 会按优先级选择第一个，可能导致预期外的日志行为。

Logback 配置文件

在 src/main/resources/ 下创建 logback.xml：

<?xml version="1.0" encoding="UTF-8"?>
<configuration>

    <!-- 控制台输出 -->
    <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>
        </encoder>
    </appender>

    <!-- 文件输出 -->
    <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>logs/mybatis.log</file>
        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <fileNamePattern>logs/mybatis.%d{yyyy-MM-dd}.log</fileNamePattern>
            <maxHistory>30</maxHistory>
        </rollingPolicy>
        <encoder>
            <pattern>%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{50} - %msg%n</pattern>
        </encoder>
    </appender>

    <!-- MyBatis 日志级别设置 -->
    <logger name="com.example.mapper" level="DEBUG" additivity="false">
        <appender-ref ref="CONSOLE"/>
        <appender-ref ref="FILE"/>
    </logger>

    <!-- 根日志级别 -->
    <root level="INFO">
        <appender-ref ref="CONSOLE"/>
    </root>

</configuration>

配置说明

强制指定日志实现

如果自动探测不符合预期，可在 MyBatis 配置文件中强制指定：

<!-- mybatis-config.xml -->
<configuration>
    <settings>
        <!-- 强制使用 SLF4J -->
        <setting name="logImpl" value="SLF4J"/>
    </settings>
</configuration>

支持的 logImpl 值包括：SLF4J、LOG4J、LOG4J2、JDK_LOGGING、COMMONS_LOGGING、STDOUT_LOGGING、NO_LOGGING。

Spring Boot 集成

Spring Boot 项目默认已集成 SLF4J + Logback，只需在 application.yml 中配置：

logging:
  level:
    root: INFO
    com.example.mapper: DEBUG  # Mapper 接口包设为 DEBUG
    org.mybatis: DEBUG         # MyBatis 内部日志

无需额外添加 logback.xml，Spring Boot 自动加载默认配置。

要点总结

• MyBatis 按优先级自动探测日志框架，推荐 SLF4J + Logback
• 避免同时引入多个日志实现，防止行为不可预期
• logback.xml 中通过 <logger> 控制特定包的日志级别
• Spring Boot 项目可直接在 application.yml 中配置日志级别
• 通过 logImpl 设置可强制指定日志实现

文章存放路径：articles/MYBATIS/入门/日志配置与调试/日志框架集成.md