Spring Boot整合MyBatis如何开启SQL日志输出？

Question

在Spring Boot整合MyBatis的项目中，开发者常遇到SQL语句未输出到控制台的问题，导致调试困难。尽管已配置`mybatis.configuration.log-impl=org.apache.ibatis.logging.stdout.StdOutImpl`，但依然看不到执行的SQL日志。可能原因包括：配置文件未正确加载、Mapper接口未使用注解或XML绑定、日志级别未设置为DEBUG等。如何正确开启MyBatis的SQL日志输出，确保DAO层执行的每一条SQL都能在控制台清晰显示？

Answer 1

一、问题背景与现象描述

在Spring Boot整合MyBatis的项目开发过程中，SQL语句未输出到控制台是一个高频且影响调试效率的问题。开发者通常会通过配置mybatis.configuration.log-impl=org.apache.ibatis.logging.stdout.StdOutImpl来尝试开启SQL日志输出，但即便如此，仍可能无法看到任何执行的SQL语句。

这一现象背后涉及多个层面的技术细节，包括但不限于：配置加载机制、日志系统集成、MyBatis执行流程以及Spring容器管理等。若不能深入理解这些机制，仅靠表面配置很难彻底解决问题。

二、常见原因分析（由浅入深）

1. 日志级别未设置为DEBUG：MyBatis默认只在DEBUG及以上级别输出SQL，若日志框架（如Logback、Log4j2）未将相关包的日志级别设为DEBUG，则不会输出。
2. 配置文件未正确加载：application.yml或application.properties中的MyBatis配置项可能因命名错误、路径问题或Profile激活失败而未生效。
3. Mapper接口未正确绑定SQL映射：使用XML方式时，Mapper XML文件未被正确扫描或namespace不匹配；使用注解方式时，@Select等注解未正确书写。
4. MyBatis配置项作用域错误：mybatis.configuration.log-impl仅对MyBatis核心配置起作用，若存在SqlSessionFactory手动配置，则需在Java Config中显式设置日志实现。
5. 第三方插件干扰日志输出：例如PageHelper分页插件、MyBatis Plus等可能会覆盖或拦截执行过程，导致标准日志无法输出。
6. 日志实现类冲突：项目中存在多个日志适配器（如SLF4J、Commons Logging），可能导致StdOutImpl未被正确识别。

三、解决方案详解

排查步骤	检查内容	推荐配置/代码
1. 检查日志级别	确保mybatis及mapper所在包的日志级别为DEBUG	logging.level.com.example.mapper=DEBUG logging.level.org.mybatis=DEBUG
2. 验证MyBatis日志实现配置	确认配置项已正确写入application.yml	mybatis: configuration: log-impl: org.apache.ibatis.logging.stdout.StdOutImpl
3. 手动配置SqlSessionFactory（高级场景）	当使用自定义SqlSessionFactoryBean时，需编程设置	@Bean public SqlSessionFactory sqlSessionFactory(DataSource dataSource) throws Exception { SqlSessionFactoryBean factory = new SqlSessionFactoryBean(); factory.setDataSource(dataSource); org.apache.ibatis.session.Configuration configuration = new org.apache.ibatis.session.Configuration(); configuration.setLogImpl(StdOutImpl.class); factory.setConfiguration(configuration); return factory.getObject(); }
4. 确保Mapper被Spring管理	Mapper接口应使用@Mapper或@MapperScan	@MapperScan("com.example.mapper")

四、典型配置示例与验证流程

以下是一个完整的application.yml配置片段，用于确保SQL日志可被输出：

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/testdb
    username: root
    password: root
    driver-class-name: com.mysql.cj.jdbc.Driver

mybatis:
  configuration:
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl
    map-underscore-to-camel-case: true

logging:
  level:
    com.example.mapper: DEBUG
    org.mybatis: DEBUG
    org.springframework: WARN

启动应用后，执行一次数据库查询操作，观察控制台是否输出类似如下内容：

==>  Preparing: SELECT * FROM user WHERE id = ? 
==> Parameters: 1(Integer)
<==    Columns: id, name, email
<==        Row: 1, zhangsan, [e-mail]
<==      Total: 1

五、可视化诊断流程图

graph TD
            A[开始诊断SQL日志未输出] --> B{日志级别是否为DEBUG?}
            B -- 否 --> C[调整logging.level.*为DEBUG]
            B -- 是 --> D{mybatis.configuration.log-impl是否设置?}
            D -- 否 --> E[添加StdOutImpl配置]
            D -- 是 --> F{是否存在自定义SqlSessionFactory?}
            F -- 是 --> G[在Java Config中设置configuration.setLogImpl()]
            F -- 否 --> H{Mapper是否被扫描?}
            H -- 否 --> I[使用@MapperScan或@Mapper注解]
            H -- 是 --> J[检查XML映射文件路径与namespace]
            J --> K[验证SQL执行并查看控制台输出]

六、进阶建议与最佳实践

• 在开发环境中，推荐结合MyBatis Log Plugin（IDEA插件）将SQL格式化输出，提升可读性。
• 避免在生产环境开启StdOutImpl，应切换为SLF4J实现并通过AOP或拦截器统一记录SQL性能日志。
• 对于复杂项目，建议使用MyBatis Generator生成Mapper并配合PageHelper进行分页，同时注意插件间的兼容性。
• 可通过实现org.apache.ibatis.logging.Log接口来自定义日志行为，例如添加执行耗时监控。
• 使用Spring Boot Actuator结合Metrics可进一步追踪DAO层调用频率与响应时间。
• 若使用Kotlin开发，需注意编译后的类名与反射机制是否影响Mapper扫描。
• 多数据源环境下，每个SqlSessionFactory都需独立配置logImpl，否则仅主数据源生效。