本文旨在提供mybatis查询日志记录的专业指南，尤其针对拥有大量xml mapper文件的复杂项目。文章将探讨如何通过配置通用包命名空间进行日志记录，并介绍在无通用命名空间或需求更高级时，如何利用外部jdbc日志工具（如jdbcdslog）实现高效、详细的sql查询日志，以克服传统java.sql日志方式的局限性。
MyBatis查询日志记录概述
在开发和调试基于MyBatis的应用程序时，详细记录SQL查询及其参数是至关重要的。然而，从旧版iBATIS或Spring 1.x迁移到MyBatis和Spring 5.x时，开发者可能会发现传统的java.sql日志配置不再能像以前一样直接输出SQL查询信息。这通常是因为MyBatis在内部处理JDBC操作的方式与直接使用java.sql有所不同，导致需要更精确的日志配置。
当项目包含数百个XML Mapper文件时，为每个Mapper单独配置日志级别显然是不可行的。本教程将提供两种主要策略来有效解决这一挑战。
策略一：利用通用包命名空间进行日志配置
如果您的MyBatis XML Mapper文件（或对应的Mapper接口）的命名空间遵循一定的命名约定，即它们共享一个共同的包前缀，那么您可以利用这个特性在日志配置文件中设置一个全局的日志级别。MyBatis的日志系统会根据Mapper的命名空间来决定其日志输出级别。
例如，如果您的所有Mapper命名空间都以com.example.mapper开头，如com.example.mapper.UserMapper和com.example.mapper.ProductMapper，那么com.example.mapper就是它们的共同包。
以下是针对不同日志框架的配置示例：
1. JDK Logger (java.util.logging)
如果您的项目使用JDK自带的java.util.logging，并且通过logging.properties（或您自定义的logs.properties）进行配置，您可以这样设置：
# 设置共同包的日志级别为FINEST，以输出最详细的SQL信息 com.example.mapper.level = FINEST # 确保控制台或文件处理器也输出FINEST级别的日志 java.util.logging.ConsoleHandler.level = FINEST java.util.logging.FileHandler.level = FINEST
2. Log4j 2
对于Log4j 2，在log4j2.xml中配置如下：
<Configuration status="WARN">
<Loggers>
<Logger name="com.example.mapper" level="trace" additivity="false">
<AppenderRef ref="Console"/>
<AppenderRef ref="File"/>
</Logger>
<!-- 其他Loggers配置 -->
</Loggers>
</Configuration>3. Logback
对于Logback，在logback.xml中配置如下：
<configuration>
<logger name="com.example.mapper" level="TRACE" additivity="false">
<appender-ref ref="CONSOLE" />
<appender-ref ref="FILE" />
</logger>
<!-- 其他logger配置 -->
</configuration>通过这种方式，所有在该通用包下的Mapper都会输出详细的SQL日志，避免了逐一配置的繁琐。
策略二：使用外部JDBC日志工具
当Mapper命名空间没有共同的包前缀，或者您需要更强大、更灵活的JDBC日志功能时，使用外部JDBC日志工具是更优的选择。这些工具通过拦截JDBC驱动层面的操作来记录SQL语句、参数、执行时间等信息，通常对应用程序代码是透明的。
推荐的外部JDBC日志工具包括：
- JdbcDsLog: 轻量级且功能强大的JDBC数据源日志工具。
- P6Spy: 另一个流行的JDBC驱动包装器，提供SQL日志、性能监控等功能。
- Log4jdbc: 同样通过包装JDBC驱动来实现日志记录。
这里以JdbcDsLog为例，说明其集成方式。
1. 引入依赖
首先，在您的项目pom.xml中添加JdbcDsLog的依赖：
<dependency>
<groupId>com.github.adrianshum</groupId>
<artifactId>jdbcdslog</artifactId>
<version>1.0.6.2</version> <!-- 使用最新版本 -->
</dependency>2. 配置数据源
JdbcDsLog通过包装您现有的DataSource来实现日志记录。在Spring框架中，您通常需要修改数据源的配置。
假设您原有的数据源配置如下：
<bean id="dataSource" class="org.apache.commons.dbcp2.BasicDataSource" destroy-method="close">
<property name="driverClassName" value="${jdbc.driverClassName}"/>
<property name="url" value="${jdbc.url}"/>
<property name="username" value="${jdbc.username}"/>
<property name="password" value="${jdbc.password}"/>
</bean>为了集成JdbcDsLog，您可以将其包装起来：
<bean id="actualDataSource" class="org.apache.commons.dbcp2.BasicDataSource" destroy-method="close">
<property name="driverClassName" value="${jdbc.driverClassName}"/>
<property name="url" value="${jdbc.url}"/>
<property name="username" value="${jdbc.username}"/>
<property name="password" value="${jdbc.password}"/>
</bean>
<!-- 使用JdbcDsLogProxyDataSource包装实际的数据源 -->
<bean id="dataSource" class="com.github.adrianshum.jdbcdslog.JdbcDsLogProxyDataSource">
<constructor-arg ref="actualDataSource"/>
<!-- 可选：配置是否打印结果集，默认为false -->
<property name="printResultSet" value="true"/>
<!-- 可选：配置是否打印行数，默认为true -->
<property name="printRowCount" value="true"/>
<!-- 可选：配置SQL日志级别，默认为DEBUG -->
<property name="sqlLogLevel" value="DEBUG"/>
<!-- 可选：配置连接日志级别，默认为DEBUG -->
<property name="connectionLogLevel" value="DEBUG"/>
</bean>3. 配置日志框架
JdbcDsLog会将SQL日志输出到名为jdbcdslog的Logger。因此，您需要在日志配置文件（如log4j2.xml、logback.xml或logging.properties）中为jdbcdslog设置合适的日志级别。
Log4j 2 示例：
<Logger name="jdbcdslog" level="DEBUG" additivity="false">
<AppenderRef ref="Console"/>
<AppenderRef ref="File"/>
</Logger>JDK Logger 示例 (logging.properties)：
jdbcdslog.level = FINEST
通过这种方式，所有经过dataSource的JDBC操作都会被JdbcDsLog拦截并记录，提供详细的SQL语句、参数、执行时间等信息，而无需关心MyBatis Mapper的命名空间结构。
注意事项与最佳实践
- 生产环境日志级别：在生产环境中，详细的SQL日志可能会产生大量的日志文件，并对性能造成一定影响。建议在生产环境将SQL日志级别设置为WARN或ERROR，仅在必要时才临时调高级别进行故障排查。
- 敏感数据：SQL日志中可能包含敏感的用户数据。在配置日志时，请确保遵守数据隐私和安全规范，避免在不安全的日志文件中记录敏感信息。
- 日志框架兼容性：确保您的MyBatis版本与所选的日志框架（如Log4j 2, Logback, JDK Logger）以及外部JDBC日志工具兼容。
- Spring Boot集成：如果使用Spring Boot，集成外部JDBC日志工具通常通过在application.properties或application.yml中配置数据源代理来实现，或者通过Java配置类@Configuration来定义JdbcDsLogProxyDataSource。
总结
有效的MyBatis查询日志是诊断和优化应用程序性能的关键。对于拥有大量XML Mapper的项目，我们可以根据项目结构选择合适的策略：如果Mapper命名空间存在通用前缀，配置通用包日志级别是简洁高效的方法；如果结构复杂或需要更强大的功能，集成JdbcDsLog等外部JDBC日志工具则提供了更灵活、更全面的解决方案。无论选择哪种方式，都应始终关注日志的性能影响和安全合规性。
