MyBatis Log 使用指南

在开发中用 MyBatis 操作数据库时，我们常遇到一个问题：写的 XML 映射语句到底会不会被正确解析？参数有没有传对？最终执行的 SQL 是什么样的？

原生 MyBatis 日志只会输出带 ? 的“占位符 SQL”（比如 SELECT * FROM user WHERE id = ?），看不到真实参数，调试起来很麻烦。而 MyBatis Log 的核心作用就是：把“占位符 SQL”自动替换成带真实参数的“完整 SQL”，直接复制就能在数据库工具（Navicat、DBeaver）里执行，调试效率翻倍！
MyBatis Log及激活码仅供学习使用

一、两种常用使用方式（推荐优先用插件）

MyBatis Log 有两种主流用法：「IDE 插件（一键生成，最方便）」和「手动配置日志框架（灵活可控）」。下面分别详细说明，全程配“图文描述”，跟着做就能成！

二、方式一：IDE 插件（推荐！5分钟搞定）

这里以最常用的 IDEA 为例，用「MyBatis Log Plugin」插件（目前最稳定的是「MyBatis Log Free」或「MyBatis Log Plugin Pro」，免费且无广告）。

步骤1：安装插件

1. 打开 IDEA → 点击顶部菜单栏「File」→「Settings」（Windows 快捷键 Ctrl+Alt+S，Mac Cmd+,）；

2. 在左侧找到「Plugins」→ 顶部搜索框输入「MyBatis Log」→ 选择任意一个高评分插件（比如「MyBatis Log Free」）→ 点击「Install」安装（图1）；

3. 安装完成后，点击「Restart IDEA」重启 IDE，插件生效。

（关键元素：左侧「Plugins」→ 顶部搜索框 → 插件列表「MyBatis Log Free」→ 蓝色「Install」按钮 → 底部「Restart IDEA」按钮）

步骤2：配置 MyBatis 日志输出（关键！）

插件需要依赖 MyBatis 的“原始日志”才能解析，所以要先告诉 MyBatis：“把 SQL 相关日志输出出来”。有两种配置方式，选一种即可：

配置方式A：在 mybatis-config.xml 中设置

如果项目里有 mybatis-config.xml（MyBatis 核心配置文件），直接添加 <settings> 标签：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE configuration PUBLIC "-//mybatis.org//DTD Config 3.0//EN"
        "http://mybatis.org/dtd/mybatis-3-config.dtd">
<configuration>
    <!-- 其他配置（如环境、映射器） -->
    
    <!-- 开启 MyBatis 日志，指定日志实现类 -->
    <settings>
        <!-- 可选值：SLF4J（推荐）、LOG4J2、STDOUT_LOGGING（控制台直接输出，无需额外依赖） -->
        <setting name="logImpl" value="SLF4J"/>
    </settings>
</configuration>

配置方式B：在 application.yml（Spring Boot 项目）中设置

如果是 Spring Boot 项目，更简单，直接在 application.yml 里加配置：

mybatis:
  configuration:
    log-impl: org.apache.ibatis.logging.slf4j.Slf4jImpl  # 开启 SLF4J 日志

注意：如果选 STDOUT_LOGGING，无需额外加依赖；如果选 SLF4J 或 LOG4J2，需要项目里有对应的日志框架依赖（Spring Boot 项目默认自带 SLF4J+Logback，无需手动加）。

步骤3：打开插件面板，查看格式化 SQL

1. 重启 IDEA 后，点击顶部菜单栏「View」→「Tool Windows」→「MyBatis Log」（或直接在 IDEA 右侧找到「MyBatis Log」标签，图2）；

2. 运行你的项目（比如执行一个查询接口），此时控制台会输出 MyBatis 的原始日志（带 ? 的 SQL）；

3. 插件会自动解析原始日志，在「MyBatis Log」面板中生成 带真实参数的完整 SQL（图3）！

（关键元素：顶部「View」→ 下拉「Tool Windows」→ 子菜单「MyBatis Log」→ 右侧弹出插件面板）

（关键元素：左侧是原始日志（含 ?），右侧是格式化后的 SQL，比如 SELECT * FROM user WHERE id = 1001 AND name = '张三'，可以直接复制到数据库工具执行）

插件用法小结

• 优点：零代码、一键生成、无需懂日志框架，新手首选；

• 缺点：依赖 IDE 插件，换 IDE 后需要重新安装。

三、方式二：手动配置日志框架（Logback 为例）

如果不想用插件，或者需要自定义日志输出格式（比如输出到文件），可以手动配置日志框架。这里用 Spring Boot 默认的「Logback」（轻量、无需额外依赖）。

步骤1：确认依赖（Spring Boot 项目可跳过）

如果是普通 Maven 项目，需要在 pom.xml 中添加 Logback 和 SLF4J 依赖（Spring Boot 已内置，无需手动加）：

<!-- SLF4J 核心（日志接口） -->
<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-api</artifactId>
    <version>1.7.36</version>
</dependency>
<!-- Logback 实现（日志具体实现） -->
<dependency>
    <groupId>ch.qos.logback</groupId>
    <artifactId>logback-classic</artifactId>
    <version>1.2.11</version>
</dependency>

步骤2：创建 Logback 配置文件

在项目 src/main/resources 目录下，新建文件 logback.xml（文件名固定），添加以下配置：

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <!-- 1. 控制台输出配置 -->
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <!-- 日志输出格式：时间 + 日志级别 + 类名 + 完整 SQL -->
            <pattern>%d{yyyy-MM-dd HH:mm:ss} [%level] %logger{50} - %msg%n</pattern>
            <charset>UTF-8</charset>
        </encoder>
    </appender>

    <!-- 2. 关键：设置 MyBatis 映射器接口的日志级别为 DEBUG -->
    <!-- 注意：把 com.yourpackage.mapper 改成你自己的 Mapper 接口所在包名！ -->
    <logger name="com.yourpackage.mapper" level="DEBUG" additivity="false">
        <appender-ref ref="CONSOLE"/>
    </logger>

    <!-- 3. 全局日志级别（默认 INFO，不影响其他代码） -->
    <root level="INFO">
        <appender-ref ref="CONSOLE"/>
    </root>
</configuration>

关键说明：

• name="com.yourpackage.mapper"：必须改成你项目中 Mapper 接口的实际包名（比如你的 UserMapper 放在 com.example.demo.mapper，就填这个路径）；

• level="DEBUG"：只有设为 DEBUG 级别，MyBatis 才会输出 SQL 相关日志；

• 无需再配置 MyBatis 的 logImpl（Spring Boot 会自动关联 SLF4J）。

步骤3：运行项目，查看控制台日志

执行你的数据库操作代码（比如调用 userMapper.selectById(1001)），此时控制台会直接输出 带真实参数的完整 SQL（图4）：

手动配置小结

• 优点：不依赖插件，可自定义日志输出（比如输出到文件、按日期分割日志），适合生产环境调试；

• 缺点：需要写配置文件，对新手稍复杂。

四、常见问题&注意事项

1. 插件看不到 SQL？

   1. 检查 MyBatis 的 logImpl 是否配置正确（必须是 SLF4J/LOG4J2，不能留空）；

   2. 检查 Mapper 接口的包名是否和日志配置一致；

   3. 重启 IDEA 和项目，确保插件生效。

2. 控制台输出乱码？

   1. 在 Logback 配置文件的 <encoder> 中添加 <charset>UTF-8</charset>（参考步骤2的配置）；

   2. IDEA 中设置控制台编码：「Settings」→「Editor」→「File Encodings」→ 全部设为 UTF-8。

3. 生产环境别开 DEBUG！

   1. DEBUG 级别会输出大量 SQL 日志，影响系统性能，还可能泄露敏感数据（比如密码、手机号）；

   2. 生产环境把日志级别改成 INFO 或 WARN。

4. 参数是字符串但没加引号？

   1. 插件或日志框架会自动处理：字符串参数会加单引号（'张三'），数字/布尔值不加，直接复制到数据库工具就能执行。

五、总结

• 新手/快速调试：用「IDEA 插件」（MyBatis Log Free），5分钟搞定，直接看完整 SQL；

• 自定义需求/生产环境：用「Logback 手动配置」，灵活控制日志输出；

• 核心目的：把 ? 替换成真实参数，让 SQL 调试从“猜”变成“直接验证”，效率翻倍！

按照上面的步骤操作，你再也不用为 MyBatis 的 SQL 调试发愁啦～

MyBatis Log及激活码仅供学习使用