MyBatis 日志机制完全指南Log Factory 实现选择与 SLF4J/Log4j2/Log4j/JDK Logging 配置实战【免费下载链接】mybatis-3MyBatis SQL mapper framework for Java项目地址: https://gitcode.com/gh_mirrors/my/mybatis-3MyBatis 内置一套与具体日志框架解耦的 Log Factory 抽象层会自动探测并使用类路径上第一个可用的日志实现SLF4J、Commons Logging、Log4j 2、Log4j 1.x、JDK Logging并支持通过mybatis-config.xml的logImpl设置或LogFactory静态方法强制指定。本文以 src/site/ja/markdown/logging.md与英文版 src/site/markdown/logging.md 内容一致为主线结合 LogFactory.java 等核心源码完整讲解实现选择机制、配置参数与五种日志框架的实操配置帮助你按需输出 Mapper 语句日志、参数与结果集日志。MyBatis 日志架构内部 Log Factory 与委托机制MyBatis 通过内部的 Log Factory 输出日志信息该工厂会把日志委托给以下实现之一SLF4JApache Commons LoggingLog4j 2Log4j 1.x自 3.5.9 起标记为已弃用对应 LogFactory.java 中useLog4JLogging()方法上的Deprecated注解JDK loggingjava.util.logging实际生效的实现由 MyBatis 内部 Log Factory 在运行时反射探测决定。探测按上述顺序进行使用第一个被发现的实现如果以上实现一个都找不到日志将被禁用回退到NoLoggingImpl位于 nologging/NoLoggingImpl.java。从源码可以确认这个顺序探测 首次命中的机制。在 LogFactory.java 的静态初始化块中static { tryImplementation(LogFactory::useSlf4jLogging); tryImplementation(LogFactory::useCommonsLogging); tryImplementation(LogFactory::useLog4J2Logging); tryImplementation(LogFactory::useLog4JLogging); tryImplementation(LogFactory::useJdkLogging); tryImplementation(LogFactory::useNoLogging); }tryImplementation只在logConstructor仍为空时尝试下一个实现一旦某个实现能成功实例化就固定下来。setImplementation通过implClass.getConstructor(String.class)反射获取构造函数并实例化适配器任何异常都会导致该实现被跳过、继续探测下一个LogFactory.java。这也解释了文档中的规则只有实现类存在于运行时类路径上才会被选中。方式一通过 mybatis-config.xml 的 logImpl 设置指定日志实现如果应用运行在类路径中包含 Commons Logging 的环境中Tomcat、WebSphere 等应用服务器出厂自带的类路径里通常就有 Commons LoggingMyBatis 默认会选用 Commons Logging。例如 WebSphere 提供了自己的专有 Commons Logging 实现这会导致你添加的 Log4j 配置被忽略——表面上看起来MyBatis 无视了我的 Log4j 配置实际上是 MyBatis 优先使用了 Commons Logging。针对这类场景可以在mybatis-config.xml中显式指定日志实现configuration settings ... setting namelogImpl valueLOG4J/ ... /settings /configurationlogImpl的合法取值如下取值含义SLF4J使用 SLF4J 适配器slf4j/Slf4jImpl.javaLOG4J使用 Log4j 1.x已弃用LOG4J2使用 Log4j 2JDK_LOGGING使用 JDK Loggingjava.util.loggingCOMMONS_LOGGING使用 Apache Commons LoggingSTDOUT_LOGGING直接输出到标准输出stdout/StdOutImpl.javaNO_LOGGING完全禁用日志自定义类的全限定名实现org.apache.ibatis.logging.Log接口、且构造函数接收一个String参数的类这条配置的解析链路在源码中有清晰的落点XMLConfigBuilder.loadCustomLogImpl()读取settings中的logImpl属性并解析为Class? extends LogXMLConfigBuilder.java随后Configuration.setLogImpl()调用LogFactory.useCustomLogging()完成切换Configuration.java。因此自定义日志实现时只需实现 Log.java 接口的isDebugEnabled()、isTraceEnabled()、error/debug/trace/warn等方法并提供String类型的构造函数即可。方式二通过 LogFactory 静态方法在代码中指定也可以在业务代码中直接调用以下方法选择日志实现org.apache.ibatis.logging.LogFactory.useSlf4jLogging(); org.apache.ibatis.logging.LogFactory.useLog4JLogging(); org.apache.ibatis.logging.LogFactory.useLog4J2Logging(); org.apache.ibatis.logging.LogFactory.useJdkLogging(); org.apache.ibatis.logging.LogFactory.useCommonsLogging(); org.apache.ibatis.logging.LogFactory.useStdOutLogging();使用这些方法时有两点需要注意必须在调用任何其他 MyBatis 方法之前调用。因为LogFactory的日志实现是在静态初始化块中确定的之后的切换需要尽早完成才有效。只有在请求的实现存在于运行时类路径上时才会真正切换。例如请求切换到 Log4j2 但运行时找不到 Log4j2MyBatis 会忽略该请求继续按默认算法探测日志实现详见 LogFactory.java 中setImplementation的异常处理逻辑。日志输出粒度包、Mapper、命名空间与语句要看到 MyBatis 的日志输出需要针对以下任一对象开启日志一个包package一个Mapper 的全限定类名一个命名空间namespace一个语句的全限定名即namespace . statementId例如org.mybatis.example.BlogMapper.selectBlog具体的配置方式取决于所使用的日志实现。下文以 SLF4JLogback为例给出完整步骤其余框架的配置示例见后文。第 1 步添加 SLF4J Logback 的 JAR 包由于使用 SLF4JLogback需要保证其 JAR 对应用可见Web 或企业级应用将logback-classic.jar、logback-core.jar、slf4j-api.jar放入WEB-INF/lib目录独立应用在 JVM 启动参数-classpath中追加这些 JARMaven 项目在pom.xml中添加依赖dependency groupIdch.qos.logback/groupId artifactIdlogback-classic/artifactId version1.x.x/version /dependency第 2 步配置 Logback假设要为如下 Mapper 开启日志package org.mybatis.example; public interface BlogMapper { Select(SELECT * FROM blog WHERE id #{id}) Blog selectBlog(int id); }创建logback.xml并放到类路径上?xml version1.0 encodingUTF-8? !DOCTYPE configuration configuration appender namestdout classch.qos.logback.core.ConsoleAppender encoder pattern%5level [%thread] - %msg%n/pattern /encoder /appender logger nameorg.mybatis.example.BlogMapper level valuetrace/ /logger root levelerror appender-ref refstdout/ /root /configuration以上配置使 SLF4JLogback对org.mybatis.example.BlogMapper输出详细日志而对应用中其余类只输出错误。更细粒度仅开启单个语句的日志logger nameorg.mybatis.example.BlogMapper.selectBlog level valuetrace/ /logger更粗粒度为一组 Mapper 开启日志如果希望为多个 Mapper 统一开启日志将 logger 指定为 Mapper 所在的根包即可logger nameorg.mybatis.example level valuetrace/ /loggerDEBUG 与 TRACE 的语义区分只看 SQL、不看结果集有些查询会返回海量结果集此时你可能只想看到 SQL 语句而不想看结果。MyBatis 对这两类信息做了级别区分SQL 语句在DEBUG级别输出JDK Logging 中对应FINE结果集在TRACE级别输出JDK Logging 中对应FINER因此只查看语句、不查看结果时将级别设为 DEBUGlogger nameorg.mybatis.example level valuedebug/ /logger这一设计在源码中有直接对应。日志代理基类 BaseJdbcLogger.java 提供debug(text, input)与trace(text, input)两个出口且带查询嵌套深度的/----前缀缩进连接与语句代理分别在 DEBUG 级输出Preparing: ...ConnectionLogger.java和Parameters: ...PreparedStatementLogger.java而ResultSetLogger的结果行输出则走 TRACE 级。所以将级别设为 DEBUG 时只会看到 Preparing/Parameters 这类语句相关信息。使用 XML Mapper 文件时的日志配置如果不使用 Mapper 接口而是使用如下 XML Mapper 文件?xml version1.0 encodingUTF-8 ? !DOCTYPE mapper PUBLIC -//mybatis.org//DTD Mapper 3.0//EN https://mybatis.org/dtd/mybatis-3-mapper.dtd mapper namespaceorg.mybatis.example.BlogMapper select idselectBlog resultTypeBlog select * from Blog where id #{id} /select /mapper为整个 XML 文件开启日志只需把 logger 指向其命名空间logger nameorg.mybatis.example.BlogMapper level valuetrace/ /logger为单个语句开启日志logger nameorg.mybatis.example.BlogMapper.selectBlog level valuetrace/ /logger可以看到无论使用 Mapper 接口还是 XML Mapper 文件日志配置方式没有任何区别——因为 MyBatis 内部统一以命名空间加语句 id 来标识语句。注意如果使用 SLF4J 或 Log4j 2MyBatis 会以MYBATIS作为 Marker 输出日志。对应源码为 LogFactory.java 中的public static final String MARKER MYBATISSLF4J 侧在 Slf4jLocationAwareLoggerImpl.java 中通过MarkerFactory.getMarker(LogFactory.MARKER)构造Log4j 2 侧在 Log4j2AbstractLoggerImpl.java 与 Log4j2LoggerImpl.java 中通过MarkerManager.getMarker(LogFactory.MARKER)构造。你可以利用该 Marker 在过滤器中精准筛选 MyBatis 相关日志。logback.xml中剩余部分是 Appender 的配置本文档不展开讲解可以自行调整配置值观察输出效果。Log4j 2 配置示例pom.xml依赖!-- pom.xml -- dependency groupIdorg.apache.logging.log4j/groupId artifactIdlog4j-core/artifactId version2.x.x/version /dependencylog4j2.xml配置!-- log4j2.xml -- ?xml version1.0 encodingUTF-8? Configuration xmlnshttp://logging.apache.org/log4j/2.0/config Appenders Console namestdout targetSYSTEM_OUT PatternLayout pattern%5level [%t] - %msg%n/ /Console /Appenders Loggers Logger nameorg.mybatis.example.BlogMapper leveltrace/ Root levelerror AppenderRef refstdout/ /Root /Loggers /ConfigurationLog4j 1.x 配置示例pom.xml依赖!-- pom.xml -- dependency groupIdlog4j/groupId artifactIdlog4j/artifactId version1.2.17/version /dependencylog4j.properties配置# log4j.properties log4j.rootLoggerERROR, stdout log4j.logger.org.mybatis.example.BlogMapperTRACE log4j.appender.stdoutorg.apache.log4j.ConsoleAppender log4j.appender.stdout.layoutorg.apache.log4j.PatternLayout log4j.appender.stdout.layout.ConversionPattern%5p [%t] - %m%n需要说明的是Log4j 1.x 适配器自 MyBatis 3.5.9 起已被标记为弃用对应 log4j/Log4jImpl.java新项目建议优先使用 Log4j 2 或 SLF4J。JDK Logging 配置示例logging.properties配置# logging.properties handlersjava.util.logging.ConsoleHandler .levelSEVERE org.mybatis.example.BlogMapperFINER java.util.logging.ConsoleHandler.levelALL java.util.logging.ConsoleHandler.formatterjava.util.logging.SimpleFormatter java.util.logging.SimpleFormatter.format%1$tT.%1$tL %4$s %3$s - %5$s%6$s%n注意JDK Logging 中FINE对应 SQL 语句级别、FINER对应结果集级别需要完整查看语句与结果时使用FINER如上例。结语如何选择与排查日志方案综合文档与源码落地 MyBatis 日志配置时可遵循以下思路先确认探测结果MyBatis 按 SLF4J → Commons Logging → Log4j 2 → Log4j 1.x → JDK Logging 的顺序取第一个可用实现LogFactory.java若全部缺失则日志完全关闭。遇到配置了 Log4j 却不生效的诡异现象优先检查类路径上是否被应用服务器带入了 Commons Logging。需要强制指定实现用mybatis-config.xml的logImpl设置或尽早调用LogFactory.useXxxLogging()。控制输出粒度按 包 / Mapper 全限定类名 / 命名空间 / 语句全限定名 四个层级选择 logger 名称用 DEBUG 看语句、用 TRACE 看结果集。接口与 XML 统一无论 Mapper 接口还是 XML Mapperlogger 名称规则一致无需分别记忆。相关源码可继续在仓库中查阅LogFactory.java、BaseJdbcLogger.java、ConnectionLogger.java、PreparedStatementLogger.java 以及测试 LogFactoryTest.java结合源码与本文示例即可完成从实现选择到细粒度输出的全链路配置。【免费下载链接】mybatis-3MyBatis SQL mapper framework for Java项目地址: https://gitcode.com/gh_mirrors/my/mybatis-3创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考