本文针对MyBatis-Spring XML配置环境中SQL查询日志记录的挑战，特别是从iBatis迁移后`java.sql`日志失效的问题，提供了两种高效解决方案。对于具有共同命名空间前缀的Mapper，可通过配置公共包实现集中日志管理；对于Mapper数量庞大或无公共包的复杂场景，推荐集成如JdbcDsLog等外部JDBC日志工具，以确保SQL查询及其参数的完整且可控的记录。
在基于MyBatis和Spring框架的应用程序中，尤其当采用XML配置方式管理Mapper时，有效地记录SQL查询语句及其参数对于调试和性能分析至关重要。然而，在从旧版iBatis或Spring迁移到MyBatis和Spring 5后，开发者可能会发现传统的通过配置java.sql来记录SQL日志的方法不再奏效。面对数百个分散的XML Mapper文件，逐一配置每个Mapper的命名空间进行日志记录显然不切实际。本教程将探讨两种针对此类问题的有效解决方案。
一、利用Mapper命名空间公共包进行日志配置
如果您的MyBatis Mapper命名空间遵循一定的命名约定，即它们共享一个或多个共同的包前缀，那么您可以利用这一特性来集中配置日志级别，而无需为每个Mapper单独设置。这种方法适用于使用JDK Logger或其他支持包级别日志配置的日志框架。
1. 工作原理
MyBatis在内部使用SLF4J（或直接使用JDK Logger，取决于配置）来记录SQL相关信息。当您为某个Mapper配置日志时，实际上是为该Mapper的命名空间（通常对应一个接口或类名）设置了日志级别。如果多个Mapper的命名空间都位于同一个Java包下（例如com.example.mapper.UserMapper和com.example.mapper.ProductMapper），那么我们可以直接为com.example.mapper这个包设置日志级别。
2. 配置示例
假设您的所有MyBatis Mapper命名空间都以com.yourcompany.project.mapper开头，例如：
- com.yourcompany.project.mapper.UserMapper
- com.yourcompany.project.mapper.OrderMapper
- com.yourcompany.project.mapper.ProductMapper
您可以在您的日志配置文件（例如logs.properties或logging.properties，对于JDK Logger）中添加如下配置来开启这些Mapper的SQL日志：
# 开启指定包下所有Mapper的DEBUG级别日志 com.yourcompany.project.mapper=DEBUG
如果您的日志框架是Logback或Log4j2，配置方式类似，例如在logback.xml中：
<configuration>
<!-- 其他配置 -->
<logger name="com.yourcompany.project.mapper" level="DEBUG"/>
<!-- 其他logger或root配置 -->
</configuration>注意事项：
- 日志级别选择： 通常，DEBUG级别会输出SQL语句和参数，TRACE级别可能会输出更详细的信息（例如结果集处理）。根据您的需求选择合适的级别。
- 前缀匹配： 确保您选择的包前缀能够覆盖所有需要记录日志的Mapper。如果Mapper分散在多个不相关的包中，此方法可能需要为每个公共前缀单独配置，或者考虑下一节的外部工具方案。
- 性能影响： 开启大量SQL日志可能会对应用程序性能产生一定影响，尤其是在高并发生产环境中。建议在开发和测试环境中使用，生产环境谨慎开启或仅在必要时开启。
二、集成外部JDBC日志工具
当Mapper命名空间没有明显的公共包前缀，或者Mapper数量极其庞大（如超过500个），以至于手动管理日志配置变得异常复杂时，集成一个外部的JDBC日志工具是更优的选择。这类工具通常通过代理JDBC驱动的方式，在应用程序和数据库之间拦截所有SQL操作，从而实现透明且全面的日志记录。
1. 为什么需要外部工具？
- 透明性： 无需修改任何MyBatis或Mapper配置，工具直接作用于JDBC层。
- 全面性： 能够捕获所有通过JDBC连接执行的SQL，包括预处理语句及其参数、批处理语句等。
- 灵活性： 通常提供比原生日志更丰富的配置选项，例如SQL格式化、执行时间记录、慢查询告警等。
- 隔离性： 将SQL日志逻辑与业务逻辑及MyBatis配置解耦。
2. 推荐工具：JdbcDsLog
JdbcDsLog (https://www.php.cn/link/f8decd07ac3bcdb30bc816319f3287de) 是一个轻量级的JDBC日志工具，它通过提供一个代理JDBC驱动来实现SQL日志功能。它的主要优势在于配置简单，能够清晰地输出SQL语句和绑定的参数，非常适合MyBatis这类使用JDBC的框架。
3. 集成步骤概述
集成JdbcDsLog或其他类似的JDBC日志工具（如P6Spy、DataSource-Proxy等）通常涉及以下几个步骤：
-
添加依赖： 在您的pom.xml（Maven）或build.gradle（Gradle）中添加相应工具的依赖。
<!-- 以JdbcDsLog为例 --> <dependency> <groupId>com.github.adrianshum</groupId> <artifactId>jdbcdslog</artifactId> <version>1.0.6</version> <!-- 请使用最新版本 --> </dependency> -
配置数据源： 修改Spring的数据源配置，将原有的数据库驱动替换为日志工具提供的代理驱动，并指定实际的数据库URL。
示例（Spring XML配置）：
<bean id="dataSource" class="org.apache.commons.dbcp2.BasicDataSource" destroy-method="close"> <!-- 使用JdbcDsLog的代理驱动 --> <property name="driverClassName" value="com.github.adrianshum.jdbcdslog.Driver"/> <!-- 实际的数据库连接URL，JdbcDsLog会解析并连接到此URL --> <property name="url" value="jdbc:log4jdbc:mysql://localhost:3306/your_database?useUnicode=true&characterEncoding=UTF-8"/> <property name="username" value="your_username"/> <property name="password" value="your_password"/> <!-- 其他数据源配置 --> </bean>注意： 上述jdbc:log4jdbc:mysql://...中的log4jdbc是JdbcDsLog内部使用的前缀，它会将其替换为实际的mysql驱动前缀。具体的URL格式请参考JdbcDsLog的官方文档。
-
日志框架配置： 确保您的日志框架（如Logback、Log4j2或JDK Logger）配置了合适的日志级别，以便捕获JdbcDsLog输出的日志。通常，JdbcDsLog会将SQL日志输出到jdbc.sqlonly、jdbc.sqltiming等特定的Logger名称下。
示例（Logback XML配置）：
<configuration> <!-- ... 其他Appender和Logger配置 ... --> <!-- 开启SQL语句日志 --> <logger name="jdbc.sqlonly" level="INFO" /> <!-- 开启SQL语句和执行时间日志 --> <logger name="jdbc.sqltiming" level="DEBUG" /> <!-- 开启连接日志 --> <logger name="jdbc.connection" level="DEBUG" /> <!-- 开启结果集日志 --> <logger name="jdbc.resultset" level="DEBUG" /> <!-- Root Logger --> <root level="INFO"> <appender-ref ref="CONSOLE" /> </root> </configuration>
注意事项：
- 驱动URL格式： 每个JDBC日志工具都有其特定的URL格式来包装实际的数据库连接URL。请务必查阅所选工具的官方文档。
- 生产环境： 在生产环境中，应谨慎配置JDBC日志工具的日志级别，避免产生过多的日志文件或对性能造成不必要的影响。通常建议仅在需要诊断问题时临时开启详细日志。
- 兼容性： 确保所选的JDBC日志工具与您的数据库驱动和Spring版本兼容。
总结
在MyBatis-Spring XML配置环境中记录SQL查询日志，应根据项目规模和Mapper命名空间的组织方式选择合适的策略。对于结构清晰、拥有共同包前缀的Mapper，通过配置包级别的日志是一种简单有效的方案。而面对大量或命名空间分散的Mapper，集成如JdbcDsLog之类的外部JDBC日志工具，则能提供更强大、更透明且更易于管理的SQL日志记录能力，从而大大提升开发和调试效率。无论选择哪种方法，都应注意日志级别对性能的影响，并在不同环境采取不同的配置策略。
