SpringBoot3+MyBatis-Plus SQL可视化调试实战

1. 项目概述

作为一名长期奋战在业务开发一线的Java工程师，我深知排查SQL问题的痛苦。每次看到MyBatis日志里那一串串问号占位符，都忍不住想摔键盘。手动拼接SQL参数不仅耗时耗力，还容易出错；想统计SQL执行耗时更是要各种加日志、查监控，效率极其低下。

最近在SpringBoot3项目中实践了一套SQL可视化调试方案，完美解决了这些问题。这套方案的核心优势在于：

• 零侵入：无需修改任何业务代码
• 即插即用：添加依赖后立即生效
• 完整SQL展示：直接输出带真实参数的SQL语句
• 执行耗时统计：自动计算每条SQL的执行时间

2. 环境准备

2.1 基础环境要求

在开始配置前，请确保你的开发环境满足以下要求：

• SpringBoot版本：3.2.5（最低要求3.0+）
• ORM框架：MyBatis-Plus 3.5.3+
• 数据库：MySQL 8.0（其他数据库也支持，配置略有不同）
• JDK版本：17+

提示：虽然方案主要针对SpringBoot3设计，但经过测试在SpringBoot2.7+版本也能正常工作，只是部分配置项可能需要调整。

2.2 开发工具建议

为了获得最佳调试体验，推荐使用以下工具组合：

1. IDE：IntelliJ IDEA（社区版即可）
2. 数据库客户端：DBeaver或Navicat
3. 项目构建工具：Maven 3.8+
4. 终端工具：支持ANSI颜色的终端（如Windows Terminal）

3. 核心依赖配置

3.1 Maven依赖引入

方案的核心是p6spy组件，它通过代理模式拦截JDBC操作。推荐使用starter简化配置：

<!-- SQL可视化调试核心starter --> <dependency> <groupId>com.github.gavlyukovskiy</groupId> <artifactId>p6spy-spring-boot-starter</artifactId> <version>2.0.0</version> </dependency> <!-- 以下是项目原有依赖，检查是否已存在 --> <dependency> <groupId>com.mysql</groupId> <artifactId>mysql-connector-j</artifactId> <scope>runtime</scope> </dependency> <dependency> <groupId>com.baomidou</groupId> <artifactId>mybatis-plus-boot-starter</artifactId> <version>3.5.3.1</version> </dependency>

3.2 依赖选择建议

在实际项目中，可能会遇到以下两种场景：

1. 全新项目：直接使用上述starter方案最省心
2. 已有项目改造：
   • 如果原项目使用了复杂的数据源配置（如多数据源），可能需要手动配置
   • 对于Spring Cloud项目，注意检查是否与其他数据源组件冲突

踩坑记录：曾经在一个多数据源项目中直接引入starter导致启动失败，后来发现需要排除自动配置类。解决方案是在@SpringBootApplication中添加exclude = {P6SpyAutoConfiguration.class}，然后手动配置。

4. 详细配置指南

4.1 基础配置（application.yml）

spring: datasource: url: jdbc:mysql://localhost:3306/your_db?useUnicode=true&characterEncoding=utf-8&serverTimezone=Asia/Shanghai&useSSL=false username: root password: your_password driver-class-name: com.mysql.cj.jdbc.Driver type: com.zaxxer.hikari.HikariDataSource # 关闭MyBatis-Plus原生日志避免重复 mybatis-plus: configuration: log-impl: org.apache.ibatis.logging.nologging.NoLoggingImpl # SQL调试配置 decorator: datasource: p6spy: logging: sysout log-format: "SQL执行耗时: %(executionTime)ms | 执行时间: %(currentTime) | 完整SQL: %(sql)"

4.2 高级配置（spy.properties）

在resources目录下创建spy.properties文件：

# 日志格式化（适配MyBatis-Plus） logMessageFormat=com.baomidou.mybatisplus.extension.p6spy.P6SpyLogger # 日志输出到控制台 appender=com.p6spy.engine.spy.appender.StdoutLogger # 启用前缀标识 useprefix=true # 排除无用日志类别 excludecategories=info,debug,result,commit,resultset # 时间格式化 dateformat=yyyy-MM-dd HH:mm:ss # 真实数据库驱动 driverlist=com.mysql.cj.jdbc.Driver # 慢SQL检测（单位：秒） outagedetection=true outagedetectioninterval=2

4.3 配置项详解

1. logMessageFormat：

   • 默认格式较简单，使用MyBatis-Plus专用格式器输出更清晰
   • 支持自定义实现，可继承com.p6spy.engine.spy.appender.FormattedLogger

2. excludecategories：

   • 过滤掉不关心的日志类型，使输出更简洁
   • 常见值：info,debug,result,commit,resultset,batch

3. outagedetection：

   • 慢SQL检测功能，超过阈值的SQL会特别标注
   • 生产环境建议关闭，避免性能开销

5. 实战效果演示

5.1 控制台输出示例

SQL执行耗时: 32ms | 执行时间: 2026-03-21 15:30:22 | 完整SQL: SELECT id,username,phone FROM t_user WHERE id = 1 AND status = 0; SQL执行耗时: 45ms | 执行时间: 2026-03-21 15:30:30 | 完整SQL: INSERT INTO t_user(username,phone,create_time) VALUES ('张三','13800138000','2026-03-21 15:30:30');

5.2 功能亮点

1. 参数可视化：

   • 所有?占位符都被替换为实际值
   • 字符串类型自动添加引号
   • NULL值明确显示

2. 执行耗时：

   • 精确到毫秒级
   • 包含网络往返时间
   • 可用于性能分析

3. 直接复制执行：

   • 输出的SQL可直接粘贴到客户端工具执行
   • 特别适合复杂查询调试

6. 生产环境管理

6.1 安全注意事项

绝对禁止在生产环境开启此功能，原因包括：

1. 日志会暴露真实数据
2. 增加性能开销
3. 可能泄露敏感信息

6.2 环境隔离方案

方案一：Maven Profile

<profiles> <profile> <id>dev</id> <activation> <activeByDefault>true</activeByDefault> </activation> <dependencies> <dependency> <groupId>com.github.gavlyukovskiy</groupId> <artifactId>p6spy-spring-boot-starter</artifactId> <version>2.0.0</version> </dependency> </dependencies> </profile> </profiles>

方案二：配置开关

spring: profiles: active: dev --- spring: config: activate: on-profile: prod decorator: datasource: p6spy: enable: false

7. 常见问题排查

7.1 驱动加载失败

现象：启动时报"Driver not found"

解决方案：

1. 检查driver-class-name是否正确
2. 如果手动配置，确保url以jdbc:p6spy:开头
3. 推荐使用starter自动配置

7.2 日志重复输出

现象：同一条SQL被打印多次

解决方案：

1. 确认关闭了MyBatis原生日志
2. 检查是否有多个数据源被代理
3. 在spy.properties中设置excludecategories

7.3 性能下降明显

现象：启用后请求响应变慢

解决方案：

1. 检查是否在生产环境误开启
2. 降低日志级别
3. 考虑使用文件输出代替控制台

8. 进阶使用技巧

8.1 日志文件输出

# 输出到文件 appender=com.p6spy.engine.spy.appender.FileLogger # 日志文件路径 logfile=spy.log # 每日滚动 appender.properties=log.dateformat=yyyy-MM-dd

8.2 自定义日志格式

logMessageFormat=com.yourpackage.CustomLogger

需要实现自定义类：

public class CustomLogger extends FormattedLogger { @Override public String formatMessage(int connectionId, String now, long elapsed, String category, String prepared, String sql) { // 自定义格式逻辑 } }

8.3 敏感数据脱敏

通过自定义过滤器实现：

public class SensitiveFilter implements P6LogQueryFilter { @Override public boolean logQuery(String query) { // 实现脱敏逻辑 return true; } }

在spy.properties中注册：

filter=com.yourpackage.SensitiveFilter

这套方案在我负责的多个项目中已经稳定运行超过半年，极大提升了开发调试效率。特别是在处理复杂业务逻辑时，能够快速定位SQL问题，平均每个需求节省约2小时的调试时间。