快速定位问题：查看 MyBatis 执行的完整 SQL – wiki基地

作者： /

快速定位问题：深度解析如何查看MyBatis执行的完整SQL

在复杂的企业级应用开发中，数据库操作是核心环节。作为Java领域流行的持久层框架，MyBatis以其灵活的SQL映射能力受到广大开发者的喜爱。然而，当业务逻辑变得复杂，或者数据库出现异常时，如何快速定位问题就成为了一个巨大的挑战。其中一个最常见、也是最有效的方法，就是查看MyBatis实际执行到数据库的完整SQL语句。

很多时候，MyBatis的动态SQL（如<if>、<where>、<foreach>等）或者参数绑定机制（#{}、${}）会在运行时生成最终的SQL。我们在Mapper文件中编写的SQL模板，可能与最终执行的SQL存在差异。例如，一个 <where> 标签可能会根据条件添加或移除子句；一个 <foreach> 可能会生成不同数量的 OR 或 AND 条件。如果最终执行的SQL有问题——无论是语法错误、条件错误、参数绑定问题，还是性能瓶颈——我们都需要看到这个“真相”，才能对症下药。

本文将详细探讨多种查看MyBatis完整SQL的方法，包括基于日志框架的配置、使用特定的数据库代理工具等，并分析它们的优缺点，帮助开发者在不同场景下选择最合适的方式，从而实现问题的快速定位和解决。

为什么需要查看完整SQL？

在深入具体方法之前，我们先明确一下查看完整SQL的必要性：

  1. 调试动态SQL生成： MyBatis强大的动态SQL特性非常方便，但也可能隐藏问题。一个复杂的 <if> 嵌套或者 <foreach> 循环可能生成非预期的SQL。查看完整SQL是验证动态SQL是否按照预期生成的最直接方式。
  2. 参数绑定验证： #{} 和 ${} 是MyBatis处理参数的两种方式。#{} 使用预编译（PreparedStatement），${} 进行字符串替换。如果参数绑定错误（例如，#{} 用于表名/列名，${} 用于用户输入且未做处理导致SQL注入，或者参数类型不匹配），查看带参数的完整SQL能立刻揭示问题。
  3. SQL语法或逻辑错误： 数据库抛出的错误信息有时比较晦涩。直接看到执行失败的SQL，可以方便地在数据库客户端中重放，隔离环境进行测试，快速确认是SQL本身的问题还是应用层的问题。
  4. 性能调优： 慢查询是常见的性能瓶颈。要分析一个查询的性能（例如使用数据库的 EXPLAIN 命令），你需要准确的、带参数的完整SQL。MyBatis日志或代理工具提供的SQL正是你所需要的。
  5. 理解框架行为： 对于MyBatis初学者或者需要深入理解框架的开发者来说，观察MyBatis如何解析Mapper文件、如何处理参数、如何与JDBC驱动交互并生成最终SQL，是学习和掌握框架非常有益的过程。

简而言之，查看完整SQL是将“黑盒”变成“白盒”的关键一步，能够极大地提高问题诊断的效率。

方法一：利用日志框架（最常用且推荐）

MyBatis本身提供了日志功能，可以输出SQL执行的详细信息。它并不直接实现日志记录，而是委托给底层的日志框架，如Log4j2、Logback、Java Util Logging (JUL) 等。这是最常用、最推荐的方式，因为它侵入性最小，只需修改配置文件即可。

MyBatis会输出以下几个关键维度的日志：

  • mybatis.executor.Executor: 负责SQL的执行过程，包括缓存命中、查询准备、参数设置、结果映射等。当日志级别设置为TRACE时，它会输出执行的SQL语句。
  • mybatis.sql.Statement: 在执行SQL前，会输出PreparedStatement或者Statement对象的创建。在低版本的MyBatis或者某些配置下，它也可能输出SQL。
  • mybatis.mapping.Statement: 与Mapper文件中的<select>, <insert>, <update>, <delete>等标签对应。日志级别设置为TRACE时，它会输出解析后的SQL语句模板（可能不包含最终替换的参数）。
  • java.sql.Connection, java.sql.PreparedStatement, java.sql.Statement, java.sql.ResultSet: 这些是JDBC相关的日志，由具体的JDBC驱动和MyBatis内部调用产生。高级别的日志（如TRACE/DEBUG/FINE/FINER）会输出很多底层信息，包括完整的SQL（通常是预编译前的模板）和设置的参数。

为了看到带参数的完整SQL（或至少是预编译SQL模板和参数列表），我们需要配置日志框架，将与SQL执行相关的logger的日志级别设置为足够低，通常是TRACE或DEBUG。

下面以最常用的Log4j2和Logback为例，详细说明配置方法。

1. 使用 Log4j2

Log4j2 是一个功能强大、高性能的日志框架。

步骤：

a) 添加 Log4j2 依赖： 如果项目未使用Log4j2，需要添加相关依赖。如果使用Maven：

“`xml

org.apache.logging.log4j
log4j-api
${log4j2.version}


org.apache.logging.log4j
log4j-core
${log4j2.version}


org.apache.logging.log4j
log4j-slf4j-impl
${log4j2.version}

``
确保${log4j2.version}`是合适的版本号。

b) 配置 Log4j2： 在类路径下创建 log4j2.xml 或 log4j2.yaml/log4j2.json 配置文件。以下是log4j2.xml的示例，将MyBatis相关logger的级别设置为TRACE：

“`xml





















    <!-- 可以根据需要，只针对某个特定的Mapper接口设置TRACE级别 -->
    <!-- 例如：
    <Logger name="com.yourcompany.mapper.UserMapper" level="TRACE" additivity="false">
        <AppenderRef ref="Console"/>
    </Logger>
    -->

    <!-- 其他应用的Logger -->
    <Root level="INFO">
        <AppenderRef ref="Console"/>
        <!-- <AppenderRef ref="File"/> -->
    </Root>
</Loggers>


``
**解释：**
*: Log4j2自身的内部状态日志级别。
*: 定义日志的输出目的地，例如控制台 (Console) 或文件 (File).
*: 定义具体的Logger配置。
*: 这是关键！将负责SQL执行的logger级别设置为TRACE。additivity=”false”表示这个logger的日志不会再传递给Root logger，避免重复输出。
*: 另一个重要的logger，尤其在某些配置或JDBC驱动下更有效。
* 通过指定Logger name为特定的Mapper接口全限定名（如com.yourcompany.mapper.UserMapper），可以只输出该Mapper的SQL日志，方便调试特定模块。
*`: 定义全局的根Logger，未被特定配置覆盖的logger会继承其级别。

c) 运行应用： 启动应用并执行涉及数据库操作的代码。在控制台或指定的日志文件中，你将看到类似以下的输出：

... [main] TRACE mybatis.executor.Executor - ==&gt; Preparing: SELECT id, name, age FROM user WHERE id = ?
... [main] TRACE mybatis.executor.Executor - ==&gt; Parameters: 1 (Integer)
... [main] TRACE mybatis.executor.Executor - &lt;== Total: 1

输出解读：
* Preparing: 后跟着的是MyBatis生成的预编译SQL模板。请注意，这里的参数位置用 ? 占位符表示。
* Parameters: 后跟着的是依次绑定的参数值及其类型。
* Total: 表示影响的行数（对于SELECT是返回的行数，对于INSERT/UPDATE/DELETE是影响的行数）。

要获取完整的SQL，你需要手动将Parameters:中的值，根据顺序替换掉Preparing:中的?。这在参数较多或类型复杂时可能会比较麻烦。

2. 使用 Logback

Logback 是SLF4J的另一个常用实现，通常与Spring Boot集成紧密。

步骤：

a) 添加 Logback 依赖： 如果项目未使用Logback，需要添加相关依赖。如果使用Maven：

“`xml

ch.qos.logback
logback-core
${logback.version}


ch.qos.logback
logback-classic
${logback.version}


``
确保${logback.version}和${slf4j.version}`是合适的版本号。Spring Boot Starter通常会包含logback和slf4j。

b) 配置 Logback： 在类路径下创建 logback.xml 或 logback-spring.xml (Spring Boot推荐) 配置文件。以下是logback.xml的示例：

“`xml



%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} – %msg%n 

<!-- 重要的MyBatis SQL相关的Logger -->
<logger name="mybatis.executor.Executor" level="DEBUG"/>
<!-- 另一个可能输出SQL的Logger -->
<logger name="mybatis.sql.Statement" level="DEBUG"/>

<!-- 或者只针对某个特定的Mapper接口 -->
<!-- <logger name="com.yourcompany.mapper.UserMapper" level="DEBUG"/> -->

<!-- Logback通常使用DEBUG或TRACE级别输出SQL -->
<!-- 在Spring Boot中，可能需要将级别设置为 TRACE -->
<!-- <logger name="mybatis.executor.Executor" level="TRACE"/> -->
<!-- <logger name="mybatis.sql.Statement" level="TRACE"/> -->


<root level="INFO">
    <appender-ref ref="STDOUT"/>
</root>


``
**解释：**
*: 根元素。
*: 定义控制台输出。
*: 将MyBatis SQL执行Logger级别设置为DEBUG。对于MyBatis 3.x系列，通常DEBUG级别就足够看到SQL和参数。但在某些环境下（尤其是配合Spring Boot），可能需要TRACE级别才能看到最详细的信息。
*additivity属性默认为true，如果想避免重复输出，可以设置为false，但通常通过控制Root logger级别来管理。
*`: 全局根Logger，将日志输出到STDOUT appender。

c) 运行应用： 启动应用。输出格式与Log4j2类似，同样包含Preparing和Parameters信息。

在 Spring Boot 中的简化配置：

Spring Boot对日志框架进行了简化配置。你通常只需要在 application.properties 或 application.yml 文件中设置相应的日志级别即可，无需创建完整的logback.xml或log4j2.xml文件（除非需要更复杂的配置）。

  • application.properties:

    “`properties

    设置MyBatis相关的Logger级别

    logging.level.mybatis.executor.Executor=DEBUG
    logging.level.mybatis.sql.Statement=DEBUG

    如果需要更详细的JDBC驱动日志，可以尝试

    logging.level.java.sql=DEBUG

    logging.level.jdbc=DEBUG

    logging.level.org.springframework.jdbc.core=DEBUG

    或者只针对特定Mapper

    logging.level.com.yourcompany.mapper.UserMapper=DEBUG

    “`

  • application.yml:

    “`yaml
    logging:
    level:
    mybatis.executor.Executor: DEBUG
    mybatis.sql.Statement: DEBUG
    # java.sql: DEBUG # 可选
    # jdbc: DEBUG # 可选
    # org.springframework.jdbc.core: DEBUG # 可选

    # 或者只针对特定Mapper
# com.yourcompany.mapper.UserMapper: DEBUG

    “`
    使用Spring Boot的这种方式最为便捷。

日志方法的优缺点：

  • 优点：
    • 侵入性最小，只需修改日志配置即可。
    • 易于启用和禁用，可以根据需要快速切换日志级别。
    • 适用于任何Java项目，不依赖特定的框架（除了MyBatis本身）。
    • 提供了详细的日志上下文信息（线程、时间戳、Logger名等）。
  • 缺点：
    • 参数与SQL分离： 需要手动将参数拼接到SQL中，尤其对于大量参数或复杂类型（如二进制、日期格式）时非常不便且容易出错。
    • 日志量大： 当有大量数据库操作时，特别是在TRACE级别下，日志会非常庞大，影响性能并难以查找关键信息。
    • 不直观： SQL和参数分开显示，不如直接看到完整SQL直观。

尽管存在缺点，但由于其便捷性，基于日志框架的方法是开发者最常用的快速查看SQL的方式，尤其适合简单的调试场景。

方法二：使用数据库代理工具

数据库代理工具（也称为JDBC Loggers 或 DataSource Wrappers）工作在应用程序和JDBC驱动之间。它们拦截JDBC调用，记录或修改SQL语句、参数、执行结果等，然后将调用转发给真正的JDBC驱动。这类工具的最大优势在于，它们能够捕获到MyBatis处理完参数后、将要发送给数据库的几乎是完整的、带参数替换的SQL语句（或者至少是预编译SQL和其绑定的参数列表，并以更友好的方式呈现）。

常用的数据库代理工具有：

  1. P6Spy: 一个开源的数据库代理框架，功能强大，支持多种输出方式（日志文件、控制台等），可以格式化SQL，甚至捕获堆栈信息。
  2. DataSource-Proxy: 另一个开源的JDBC代理库，由阿里开源，也提供了SQL拦截、慢查询日志等功能。

这里我们以P6Spy为例进行详细说明。

1. 使用 P6Spy

P6Spy 通过在JDBC URL前加上spy:前缀来工作，或者通过配置文件指定要代理的真实JDBC驱动和URL。

步骤：

a) 添加 P6Spy 依赖：

xml
<dependency>
<groupId>p6spy</groupId>
<artifactId>p6spy</artifactId>
<version>${p6spy.version}</version>
</dependency>
确保${p6spy.version}是合适的版本号。

b) 配置 P6Spy：

  • 方式一：修改 JDBC URL (简单场景)

    在数据库连接URL前加上spy:前缀。例如，如果你的数据库URL是 jdbc:mysql://localhost:3306/mydatabase，修改为 jdbc:spy:mysql://localhost:3306/mydatabase。同时，需要将JDBC驱动类名修改为P6Spy的驱动类：com.p6spy.engine.spy.P6SpyDriver。

    “`properties

    application.properties 或其他连接池配置

    spring.datasource.url=jdbc:spy:mysql://localhost:3306/mydatabase?useUnicode=true&characterEncoding=utf8
    spring.datasource.driver-class-name=com.p6spy.engine.spy.P6SpyDriver
    spring.datasource.username=your_user
    spring.datasource.password=your_password
    “`

  • 方式二：通过配置文件指定真实驱动和URL (推荐)

    这种方式更灵活，特别是当你使用连接池并且不方便直接修改连接池配置时。
    在类路径下创建 spy.properties 文件。

    “`properties

    指定真实的JDBC驱动类名

    realdriver=com.mysql.cj.jdbc.Driver

    指定真实的数据库连接URL (去除spy:前缀)

    realurl=jdbc:mysql://localhost:3306/mydatabase?useUnicode=true&characterEncoding=utf8

    指定输出方式 (logging, stdout, file, slf4j等)

    这里设置为 logging，P6Spy将通过SLF4J输出日志，需要结合日志框架配置

    appender=com.p6spy.engine.spy.appender.Slf4jLogger

    或者直接输出到控制台 (stdout)

    appender=com.p6spy.engine.spy.appender.StdoutLogger

    或者输出到文件

    appender=com.p6spy.engine.spy.appender.FileLogger

    logfile=spy.log

    append=true

    是否开启日志

    enablelog=true

    是否美化SQL输出

    includecategories=info,error,batch,commit,rollback,statement

    指定要日志的类别

    logMessageFormat=com.p6spy.engine.spy.appender.CustomLineFormat

    自定义日志格式，{0}:当前时间 {1}:执行时间(ms) {2}:分类 {3}:连接id {4}:语句/批量语句编号 {5}:SQL

    customLogMessageFormat=P6Spy – %2$s ms | %5$s

    是否美化SQL格式

    sqlexpression=

    sqlformat.factory=com.p6spy.engine.spy.format.BasicSQLFormatter

    sqlformat.factory=com.p6spy.engine.spy.format.InlineCommonsTextFormatter # 使用更高级的格式化器，将参数值嵌入SQL中

    如果使用 InlineCommonsTextFormatter，需要添加commons-text依赖

    org.apache.commons

    commons-text

    1.9

    过滤规则 (可选，例如只记录慢查询，或排除某些SQL)

    excludecategories=info

    excludeconnectionids=

    excludecommondataprefix=

    executethreshold=100 # 只记录执行时间超过100ms的SQL

    ``
    在配置连接池（如HikariCP, Druid, C3P0等）时，将DataSource的类型设置为    com.p6spy.engine.spy.SpyDataSource，或者如果连接池支持wrapperDataSource`属性，可以将其设置为真实的DataSource，并将连接池的DataSource类设为P6Spy的DataSourceWrapper。

    在 Spring Boot 中配置 P6Spy (推荐方式二)：

    Spring Boot 2.0+ 提供了对P6Spy的自动配置支持。只需要添加P6Spy依赖，然后在application.properties或application.yml中配置即可。

    “`properties

    application.properties

    spring.datasource.driver-class-name=com.p6spy.engine.spy.P6SpyDriver

    真实的URL和驱动在spy.properties中配置

    spring.datasource.url=jdbc:spy:mysql://localhost:3306/mydatabase?useUnicode=true&characterEncoding=utf8 # 或者直接在spy.properties中配置realurl和realdriver

    如果希望P6Spy日志通过标准的Spring Boot日志系统输出

    在spy.properties中设置 appender=com.p6spy.engine.spy.appender.Slf4jLogger

    然后在application.properties中设置日志级别

    logging.level.p6spy=INFO # 或者 DEBUG/TRACE，取决于logMessageFormat的类别
    ``
    Spring Boot会自动检测到    com.p6spy.engine.spy.P6SpyDriver并应用P6Spy的配置。确保spy.properties`文件位于classpath下。

c) 运行应用： 启动应用并执行数据库操作。如果配置正确，你将在控制台或指定的日志文件中看到P6Spy输出的SQL日志。使用 InlineCommonsTextFormatter 时，输出会非常直观：

P6Spy - 3 ms | SELECT id, name, age FROM user WHERE id = 1
或者更详细的格式（取决于 customLogMessageFormat）：
... [main] INFO p6spy - P6Spy - 3 ms | SELECT id, name, age FROM user WHERE id = 1

P6Spy方法的优缺点：

  • 优点：
    • SQL与参数合并： 能够将参数值直接嵌入到SQL语句中输出，非常直观，无需手动拼接。
    • 功能强大： 支持多种输出方式、SQL格式化、慢查询日志、过滤等高级功能。
    • 侵入性相对较低： 主要修改连接配置或添加配置文件，对业务代码无影响。
  • 缺点：
    • 需要额外依赖和配置： 比简单的日志配置稍微复杂一些。
    • 轻微性能开销： 拦截所有JDBC调用会带来一定的性能开销，不适合在生产环境长期开启所有日志。
    • 参数类型信息可能丢失： 虽然能看到参数值，但不如MyBatis日志那样明确标注参数类型。

P6Spy是调试复杂SQL、分析性能问题时的利器，尤其是其直接显示带参数SQL的能力，极大地提高了问题排查效率。DataSource-Proxy也有类似的功能，选择哪个取决于个人喜好和项目已有技术栈。

方法三：数据库服务器日志

大多数关系型数据库（如MySQL, PostgreSQL, Oracle）都有自己的查询日志功能。开启数据库服务器的查询日志，可以直接在数据库端看到所有客户端连接执行的SQL语句。

以MySQL为例，可以通过修改 my.cnf (或 my.ini) 文件并重启MySQL服务来开启慢查询日志和通用查询日志：

“`ini

my.cnf

[mysqld]
slow_query_log = 1 # 开启慢查询日志
slow_query_log_file = /var/log/mysql/mysql-slow.log # 慢查询日志文件路径
long_query_time = 1 # 记录执行时间超过1秒的查询
log_output = FILE # 日志输出方式

general_log = 1 # 开启通用查询日志 (会记录所有查询，慎用！)
general_log_file = /var/log/mysql/mysql.log # 通用查询日志文件路径
``
开启general_log` 后，所有连接执行的所有语句都会被记录下来，包括MyBatis发送的SQL。

数据库服务器日志方法的优缺点：

  • 优点：
    • 最真实的SQL： 记录的是数据库服务器实际接收到的SQL，不受客户端或驱动程序的影响。
    • 无需修改应用： 完全在数据库端配置。
    • 集中管理： 可以在数据库服务器上统一查看所有客户端的查询。
  • 缺点：
    • 日志量巨大： 特别是通用查询日志，会迅速撑满磁盘空间，对数据库性能影响很大，绝不建议在生产环境长期开启通用查询日志。
    • 定位困难： 日志中混合了所有客户端、所有应用的查询，需要根据时间、客户端IP/端口等信息进行过滤，查找特定应用、特定请求的SQL比较麻烦。
    • 需要数据库管理权限： 通常需要DBA或具备服务器管理权限才能配置。
    • 可能缺乏应用上下文： 日志中只有SQL本身和执行时间等信息，没有应用程序的线程、方法调用栈等上下文信息，不利于从应用层面定位问题。

数据库服务器日志更适合DBA或用于全局监控、发现问题，对于开发者快速定位应用中的某个特定问题，不如前两种方法便捷直观。在紧急情况下，如果前两种方法设置有困难，可以临时开启数据库通用查询日志，获取问题SQL后立即关闭。

方法四：利用集成开发环境(IDE)的调试功能

虽然IDE的调试功能不能直接“查看”MyBatis最终执行的SQL，但可以通过设置断点来观察MyBatis内部处理过程中的SQL和参数。

步骤：

在MyBatis的核心执行类或Mapper接口方法上设置断点。例如，在 org.apache.ibatis.executor.BaseExecutor 类的 query() 或 update() 方法中设置断点。当代码执行到此处时，你可以检查当前对象的成员变量，例如 boundSql 对象，它通常包含了预编译的SQL和运行时绑定的参数信息。

IDE调试方法的优缺点：

  • 优点：
    • 提供了最详细的运行时上下文信息，包括完整的调用栈、变量值等。
    • 无需修改代码或配置文件。
  • 缺点：
    • 效率低下： 需要中断程序执行，手动单步调试或检查变量，不适合批量查看或快速浏览。
    • 需要理解MyBatis内部源码： 需要知道在哪里设置断点以及如何找到相关的SQL/参数信息。
    • 不直观： SQL和参数信息分散在不同的变量中，不如日志或代理工具直接。

IDE调试更适合深入分析MyBatis执行过程中的某个特定细节或复杂场景，而不是作为常规的SQL查看手段。

最佳实践与总结

  1. 首选日志框架方法： 对于日常开发调试，特别是Spring Boot项目，通过配置application.properties或application.yml来开启MyBatis的SQL日志（通常设置为DEBUG或TRACE级别）是最便捷、最常用的方法。它能快速提供SQL模板和参数信息，帮助你验证大部分问题。用完后记得关闭或调高日志级别，避免日志泛滥。
  2. 掌握P6Spy/DataSource-Proxy： 对于需要直观查看带参数完整SQL、分析性能问题（结合慢查询日志）或调试复杂动态SQL生成的场景，数据库代理工具是更强大的选择。特别是P6Spy，其SQL格式化能力非常出色，能让你一眼看出问题所在。可以考虑在开发或测试环境长期开启（或者配置慢查询阈值）。
  3. 谨慎使用数据库服务器日志： 通用查询日志是最后的手段，仅在紧急情况或无法通过前两种方法获取信息时临时开启，并且务必快速关闭。慢查询日志则是一个很好的持续监控工具，但更多是用于发现问题而非定位某个具体请求的SQL。
  4. 结合使用： 在排查复杂问题时，可以将日志框架、数据库代理工具甚至IDE调试结合起来使用，从不同维度获取信息。
  5. 日志级别管理： 务必理解不同日志级别（TRACE, DEBUG, INFO等）的含义以及它们对性能和日志量的影响。在生产环境，通常只开启INFO或WARN级别，SQL日志应谨慎开启或通过慢查询日志来捕获。

查看MyBatis执行的完整SQL是开发者必备的技能之一。通过掌握上述方法，你可以更高效地诊断SQL相关的问题，无论是动态SQL生成错误、参数绑定问题，还是性能瓶颈。选择合适的方法取决于你的具体需求、项目环境以及对不同工具的熟悉程度。熟练运用这些技巧，将使你在MyBatis开发中事半功倍。

发表评论

您的邮箱地址不会被公开。 必填项已用 * 标注

滚动至顶部