MyBatis Plus SQL日志配置与调试全指南

1. 为什么需要关注MyBatis Plus的SQL日志

在Java后端开发中，MyBatis Plus作为MyBatis的增强工具，因其简洁的API和丰富的功能被广泛使用。但很多开发者在使用过程中经常遇到一个共同的问题：当SQL执行结果不符合预期时，却无法快速定位问题所在。这时候，SQL日志输出就成了排查问题的生命线。

我经历过一个典型的生产环境事故：某个查询接口突然返回空数据，但数据库明明有记录。当时由于没有配置SQL日志输出，团队花了2个小时才定位到是MyBatis Plus的QueryWrapper条件拼接错误。如果有完整的SQL日志输出，这个问题可能在5分钟内就能解决。

SQL日志不仅能帮助调试，还能：

• 发现潜在的性能问题（如N+1查询）
• 验证动态SQL是否正确生成
• 审计系统执行的SQL语句
• 分析ORM框架与实际SQL的映射关系

2. MyBatis Plus日志配置全解析

2.1 基础日志配置

MyBatis Plus的日志输出依赖于底层的MyBatis日志实现。最基础的配置方式是在application.yml中：

yaml复制mybatis-plus:
  configuration:
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl

这种配置会将SQL日志输出到控制台，适合本地开发环境。但生产环境通常需要更灵活的日志管理，这时应该使用SLF4J配合Logback或Log4j2。

2.2 生产环境推荐配置

对于Spring Boot项目，推荐以下Logback配置：

xml复制<logger name="com.baomidou.mybatisplus" level="DEBUG"/>
<logger name="java.sql" level="DEBUG"/>
<logger name="java.sql.Statement" level="DEBUG"/>
<logger name="java.sql.PreparedStatement" level="DEBUG"/>
<logger name="java.sql.ResultSet" level="DEBUG"/>

这种分层配置的好处是：

1. 可以单独控制MyBatis Plus核心包的日志级别
2. 能捕获JDBC层面的SQL执行细节
3. 方便通过日志框架的Appender将SQL日志输出到特定文件

2.3 日志内容定制

默认的SQL日志输出可能包含过多信息，可以通过MyBatis Plus的配置进行精简：

yaml复制mybatis-plus:
  configuration:
    log-prefix: "[MP-SQL]"
    log-sql: true
    log-params: true
    log-result: false

这样配置后，日志会以"[MP-SQL]"为前缀，包含参数值但不包含结果集，既保持了可读性又避免了日志膨胀。

3. 高级日志调试技巧

3.1 动态调整日志级别

在生产环境，我们可能只需要在特定情况下开启SQL日志。Spring Boot Actuator提供了动态调整日志级别的能力：

bash复制curl -X POST http://localhost:8080/actuator/loggers/com.baomidou.mybatisplus \
-H "Content-Type: application/json" \
-d '{"configuredLevel":"DEBUG"}'

记得在安全配置中保护好Actuator端点，避免未授权访问。

3.2 SQL美化打印

默认的SQL日志是单行显示，复杂SQL难以阅读。可以通过以下配置实现SQL美化：

java复制@Bean
public PerformanceInterceptor performanceInterceptor() {
    PerformanceInterceptor interceptor = new PerformanceInterceptor();
    interceptor.setFormat(true); // 格式化SQL
    interceptor.setMaxTime(1000); // 超过1秒的SQL会打印警告
    return interceptor;
}

注意：性能拦截器会影响系统性能，建议只在调试时开启

3.3 敏感数据脱敏

日志中的SQL可能包含敏感数据，可以通过自定义日志插件实现脱敏：

java复制public class SensitiveDataLoggerProxy implements InvocationHandler {
    private final Object target;
    
    @Override
    public Object invoke(Object proxy, Method method, Object[] args) {
        if ("debug".equals(method.getName())) {
            args[0] = maskSensitiveData(args[0].toString());
        }
        return method.invoke(target, args);
    }
    
    private String maskSensitiveData(String sql) {
        // 实现手机号、身份证等敏感信息的脱敏逻辑
    }
}

4. 常见问题排查指南

4.1 日志不输出问题

当配置正确但SQL日志仍然不输出时，可以按以下步骤排查：

1. 检查是否有多个日志框架冲突（如同时存在Logback和Log4j2）
2. 确认没有其他配置覆盖了日志级别（如@SpringBootApplication的exclude）
3. 检查是否有AOP切面拦截了SQL执行
4. 尝试在启动参数中添加-Dlogging.level.com.baomidou.mybatisplus=DEBUG

4.2 日志输出过多问题

如果日志量过大，可以考虑：

1. 使用正则过滤只关注特定表的SQL
2. 为慢SQL单独配置日志文件
3. 使用SamplingLogger实现采样输出

4.3 性能监控集成

将SQL日志与监控系统集成可以更好地发现问题：

java复制@Aspect
@Component
public class SqlMonitorAspect {
    @Around("execution(* org.apache.ibatis.session.SqlSession.*(..))")
    public Object monitorSql(ProceedingJoinPoint joinPoint) throws Throwable {
        long start = System.currentTimeMillis();
        try {
            return joinPoint.proceed();
        } finally {
            long cost = System.currentTimeMillis() - start;
            Metrics.counter("sql.execute.count").increment();
            Metrics.timer("sql.execute.time").record(cost, TimeUnit.MILLISECONDS);
            if (cost > 500) {
                LOG.warn("Slow SQL detected: {}ms", cost);
            }
        }
    }
}

5. 生产环境最佳实践

5.1 日志分级策略

建议采用分级的日志策略：

• DEBUG：开发环境全量SQL日志
• INFO：生产环境只记录慢SQL和错误SQL
• WARN：记录执行超过1秒的SQL
• ERROR：记录执行失败的SQL

5.2 日志文件分离

将SQL日志单独输出到文件便于分析：

xml复制<appender name="SQL-FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
    <file>logs/sql.log</file>
    <filter class="ch.qos.logback.classic.filter.ThresholdFilter">
        <level>DEBUG</level>
    </filter>
    <encoder>
        <pattern>[%d{yyyy-MM-dd HH:mm:ss}] [%thread] %-5level %logger{36} - %msg%n</pattern>
    </encoder>
</appender>

5.3 日志分析工具链

构建完整的SQL日志分析体系：

1. 使用Filebeat收集SQL日志
2. 通过Logstash解析SQL执行时间、参数等字段
3. 在Elasticsearch中建立索引
4. 通过Kibana可视化分析慢SQL趋势

6. 性能优化与日志的平衡

开启SQL日志必然会带来一定的性能开销，特别是在高并发场景下。以下是一些优化建议：

6.1 异步日志输出

使用异步Appender可以显著降低日志对主流程的影响：

xml复制<appender name="ASYNC-SQL" class="ch.qos.logback.classic.AsyncAppender">
    <queueSize>1024</queueSize>
    <discardingThreshold>0</discardingThreshold>
    <appender-ref ref="SQL-FILE"/>
</appender>

6.2 采样率控制

对于高频SQL，可以设置采样率避免日志爆炸：

java复制@Configuration
public class SqlLogConfig {
    @Bean
    public LoggerListener loggerListener() {
        return new LoggerListener() {
            private final AtomicLong counter = new AtomicLong();
            private final int sampleRate = 10; // 10%采样率
            
            @Override
            public void onLogger(Logger logger) {
                if (logger.getName().contains("sql") && 
                    counter.incrementAndGet() % sampleRate != 0) {
                    logger.setLevel(Level.OFF);
                }
            }
        };
    }
}

6.3 条件化日志输出

只在特定条件下输出日志可以平衡可观察性和性能：

java复制public class ConditionalLogger {
    private static final ThreadLocal<Boolean> DEBUG_ENABLED = ThreadLocal.withInitial(() -> false);
    
    public static void enableForCurrentRequest() {
        DEBUG_ENABLED.set(true);
    }
    
    public static void logSql(String sql) {
        if (DEBUG_ENABLED.get()) {
            LOG.debug(sql);
        }
    }
}

通过合理配置和使用这些技巧，可以在获得足够调试信息的同时，将日志对系统性能的影响降到最低。