SpringBoot集成MyBatis实现SQL拦截器的实战指南

谭谷易

一、为什么需要SQL拦截器？

先看几个真实场景：

• 慢查询监控：生产环境突然出现接口超时，需要快速定位执行时间过长的SQL
• 数据脱敏：用户表查询结果中的手机号、身份证号需要自动替换为****
• 权限控制：多租户系统中，自动给SQL添加tenant_id = ?条件，防止数据越权访问
• SQL审计：记录所有执行的SQL语句、执行人、执行时间，满足合规要求

如果没有拦截器，这些需求可能需要修改每一个Mapper接口或Service方法，工作量巨大。

而MyBatis的SQL拦截器能在SQL执行的各个阶段进行拦截处理，实现"无侵入式"增强。

二、MyBatis拦截器基础

2.1 核心接口：Interceptor

MyBatis的拦截器机制基于JDK动态代理，所有自定义拦截器都要实现Interceptor接口：

1. public interface Interceptor {
2. // 拦截逻辑的核心方法
3. Object intercept(Invocation invocation) throws Throwable;
5. // 生成代理对象（通常直接用Plugin.wrap()）
6. Object plugin(Object target);
8. // 读取配置参数（如从mybatis-config.xml中获取）
9. void setProperties(Properties properties);
10. }

复制代码

2.2 拦截目标与签名配置

MyBatis允许拦截4个核心组件的方法，通过@Intercepts和@Signature注解指定拦截目标：

举个栗子：拦截StatementHandler的prepare方法（SQL预编译阶段）：

1. @Intercepts({
2. @Signature(
3. type = StatementHandler.class, // 拦截哪个接口
4. method = "prepare", // 拦截接口的哪个方法
5. args = {Connection.class, Integer.class} // 方法参数类型（用于确定重载方法）
6. )
7. })
8. public class MySqlInterceptor implements Interceptor {
9. // 实现接口方法...
10. }

复制代码

注意：args参数必须严格匹配方法的参数类型，否则拦截不到！比如prepare方法有两个重载，这里指定(Connection, Integer)类型的参数。

三、实战一：慢查询监控拦截器

3.1 需求说明

监控所有SQL执行时间，超过阈值（如500ms）则打印警告日志，包含：

• SQL执行时间
• 完整SQL语句（带参数占位符）
• 参数值（防止SQL注入排查）

3.2 完整实现代码

（1）拦截器类

1. import lombok.extern.slf4j.Slf4j;
2. import org.apache.ibatis.executor.statement.StatementHandler;
3. import org.apache.ibatis.plugin.*;
4. import org.apache.ibatis.session.ResultHandler;
5. import java.sql.Connection;
6. import java.sql.Statement;
7. import java.util.Properties;
9. @Slf4j
10. @Intercepts({
11. // 拦截查询方法
12. @Signature(
13. type = StatementHandler.class,
14. method = "query",
15. args = {Statement.class, ResultHandler.class}
16. ),
17. // 拦截更新方法（insert/update/delete）
18. @Signature(
19. type = StatementHandler.class,
20. method = "update",
21. args = {Statement.class}
22. )
23. })
24. public class SlowSqlInterceptor implements Interceptor {
26. // 慢查询阈值（毫秒），可通过配置文件注入
27. private long slowThreshold = 500;
29. @Override
30. public Object intercept(Invocation invocation) throws Throwable {
31. // 1. 记录开始时间
32. long startTime = System.currentTimeMillis();
34. try {
35. // 2. 执行原方法（继续SQL执行流程）
36. return invocation.proceed();
37. } finally {
38. // 3. 计算执行耗时（无论成功失败都记录）
39. long costTime = System.currentTimeMillis() - startTime;
41. // 4. 获取SQL语句和参数
42. StatementHandler statementHandler = (StatementHandler) invocation.getTarget();
43. String sql = statementHandler.getBoundSql().getSql(); // 获取SQL语句（带?占位符）
44. Object parameterObject = statementHandler.getBoundSql().getParameterObject(); // 获取参数
46. // 5. 判断是否慢查询
47. if (costTime > slowThreshold) {
48. log.warn("[慢查询警告] 执行时间: {}ms, SQL: {}, 参数: {}",
49. costTime, sql, parameterObject);
50. } else {
51. log.info("[SQL监控] 执行时间: {}ms, SQL: {}", costTime, sql);
52. }
53. }
54. }
56. @Override
57. public Object plugin(Object target) {
58. // 生成代理对象（MyBatis提供的工具方法，避免自己写代理逻辑）
59. return Plugin.wrap(target, this);
60. }
62. @Override
63. public void setProperties(Properties properties) {
64. // 从配置文件读取阈值（如application.yml中配置）
65. String threshold = properties.getProperty("slowThreshold");
66. if (threshold != null) {
67. slowThreshold = Long.parseLong(threshold);
68. }
69. }
70. }

复制代码

（2）SpringBoot注册拦截器

1. package com.example.config;
3. import com.example.interceptor.SensitiveInterceptor;
4. import com.example.interceptor.SlowSqlInterceptor;
5. import org.apache.ibatis.session.SqlSessionFactory;
6. import org.mybatis.spring.SqlSessionFactoryBean;
7. import org.mybatis.spring.annotation.MapperScan;
8. import org.springframework.context.annotation.Bean;
9. import org.springframework.context.annotation.Configuration;
10. import org.springframework.core.io.support.PathMatchingResourcePatternResolver;
11. import javax.sql.DataSource;
12. import java.util.Properties;
14. @Configuration
15. @MapperScan("com.example.mapper") // Mapper接口所在包
16. public class MyBatisConfig {
18. // 注册慢查询拦截器
19. @Bean
20. public SlowSqlInterceptor slowSqlInterceptor() {
21. SlowSqlInterceptor interceptor = new SlowSqlInterceptor();
23. // 设置属性（也可通过application.yml配置）
24. Properties properties = new Properties();
25. properties.setProperty("slowThreshold", "500"); // 慢查询阈值500ms
26. interceptor.setProperties(properties);
28. return interceptor;
29. }
31. @Bean
32. public SensitiveInterceptor sensitiveInterceptor() {
33. return new SensitiveInterceptor();
34. }
36. // 将拦截器添加到SqlSessionFactory
37. @Bean
38. public SqlSessionFactory sqlSessionFactory(DataSource dataSource, SlowSqlInterceptor slowSqlInterceptor) throws Exception {
39. SqlSessionFactoryBean sessionFactory = new SqlSessionFactoryBean();
40. sessionFactory.setDataSource(dataSource);
42. // 设置Mapper.xml路径（如果需要）
43. /*sessionFactory.setMapperLocations(
44. new PathMatchingResourcePatternResolver()
45. .getResources("classpath:mapper/*.xml")
46. );*/
48. // 添加拦截器
49. sessionFactory.setPlugins(slowSqlInterceptor);
51. return sessionFactory.getObject();
52. }
53. }
54. （3）测试效果
55. 写个简单的查询接口：
57. @Service
58. public class UserService {
59. @Autowired
60. private UserMapper userMapper;
62. public User getUserById(Long id) {
63. return userMapper.selectById(id);
64. }
65. }

复制代码

执行后控制台输出：

1. [SQL监控] 执行时间: 30ms, SQL: SELECT id,username,phone FROM user WHERE id = ?如果SQL执行时间超过500ms（比如查询大数据量表）：[慢查询警告] 执行时间: 1430ms, SQL: SELECT * FROM user WHERE id = ?, 参数: {id=1, param1=1}踩坑提示：如果拦截不到SQL，检查@Signature注解的args参数是否与方法参数类型完全匹配！

复制代码

四、实战二：数据脱敏拦截器（敏感信息保护）

4.1 需求说明

查询用户信息时，自动将敏感字段脱敏：

• 手机号：13812345678 → 138****5678
• 身份证号：110101199001011234 → ****************34

4.2 完整实现代码

（1）自定义脱敏注解

1. import java.lang.annotation.*;
3. // 作用在字段上
4. @Target(ElementType.FIELD)
5. // 运行时生效
6. @Retention(RetentionPolicy.RUNTIME)
7. public @interface Sensitive {
8. // 脱敏类型（手机号、身份证号等）
9. SensitiveType type();
10. }
12. // 脱敏类型枚举
13. public enum SensitiveType {
14. PHONE, // 手机号
15. ID_CARD // 身份证号
16. }

复制代码

（2）实体类添加注解

1. import lombok.Data;
3. @Data
4. public class User {
5. private Long id;
6. private String username;
8. @Sensitive(type = SensitiveType.PHONE) // 手机号脱敏
9. private String phone;
11. @Sensitive(type = SensitiveType.ID_CARD) // 身份证号脱敏
12. private String idCard;
13. }

复制代码

（3）脱敏工具类

1. public class SensitiveUtils {
2. // 手机号脱敏：保留前3位和后4位
3. public static String maskPhone(String phone) {
4. if (phone == null || phone.length() != 11) {
5. return phone; // 非手机号格式不处理
6. }
7. return phone.replaceAll("(\d{3})\d{4}(\d{4})", "$1****$2");
8. }
10. // 身份证号脱敏：保留最后2位
11. public static String maskIdCard(String idCard) {
12. if (idCard == null || idCard.length() < 18) {
13. return idCard; // 非身份证格式不处理
14. }
15. return idCard.replaceAll("\d{16}(\d{2})", "****************$1");
16. }
17. }

复制代码

（4）结果集拦截器

1. import lombok.extern.slf4j.Slf4j;
2. import org.apache.ibatis.executor.resultset.ResultSetHandler;
3. import org.apache.ibatis.plugin.*;
4. import java.lang.reflect.Field;
5. import java.sql.Statement;
6. import java.util.List;
7. import java.util.Properties;
9. @Slf4j
10. @Intercepts({
11. @Signature(
12. type = ResultSetHandler.class,
13. method = "handleResultSets",
14. args = {Statement.class}
15. )
16. })
17. public class SensitiveInterceptor implements Interceptor {
19. @Override
20. public Object intercept(Invocation invocation) throws Throwable {
21. // 1. 执行原方法，获取查询结果
22. Object result = invocation.proceed();
24. // 2. 如果结果是List，遍历处理每个元素
25. if (result instanceof List<?>) {
26. List<?> resultList = (List<?>) result;
27. for (Object obj : resultList) {
28. // 3. 对有@Sensitive注解的字段进行脱敏
29. desensitize(obj);
30. }
31. }
32. return result;
33. }
35. // 反射处理对象中的敏感字段
36. private void desensitize(Object obj) throws IllegalAccessException {
37. if (obj == null) {
38. return;
39. }
40. Class<?> clazz = obj.getClass();
41. Field[] fields = clazz.getDeclaredFields(); // 获取所有字段（包括私有）
43. for (Field field : fields) {
44. // 4. 检查字段是否有@Sensitive注解
45. if (field.isAnnotationPresent(Sensitive.class)) {
46. Sensitive annotation = field.getAnnotation(Sensitive.class);
47. field.setAccessible(true); // 开启私有字段访问权限
48. Object value = field.get(obj); // 获取字段值
50. if (value instanceof String) {
51. String strValue = (String) value;
52. // 5. 根据脱敏类型处理
53. switch (annotation.type()) {
54. case PHONE:
55. field.set(obj, SensitiveUtils.maskPhone(strValue));
56. break;
57. case ID_CARD:
58. field.set(obj, SensitiveUtils.maskIdCard(strValue));
59. break;
60. default:
61. break;
62. }
63. }
64. }
65. }
66. }
68. @Override
69. public Object plugin(Object target) {
70. return Plugin.wrap(target, this);
71. }
73. @Override
74. public void setProperties(Properties properties) {
75. // 可配置更多脱敏规则，此处省略
76. }
77. }

复制代码

（5）注册多个拦截器

修改MyBatisConfig，添加脱敏拦截器：

1. @Configuration
2. @MapperScan("com.example.mapper")
3. public class MyBatisConfig {
4. // ... 慢查询拦截器配置 ...
6. @Bean
7. public SensitiveInterceptor sensitiveInterceptor() {
8. return new SensitiveInterceptor();
9. }
11. @Bean
12. public SqlSessionFactory sqlSessionFactory(DataSource dataSource,
13. SlowSqlInterceptor slowSqlInterceptor,
14. SensitiveInterceptor sensitiveInterceptor) throws Exception {
15. SqlSessionFactoryBean sessionFactory = new SqlSessionFactoryBean();
16. sessionFactory.setDataSource(dataSource);
17. sessionFactory.setMapperLocations(
18. new PathMatchingResourcePatternResolver().getResources("classpath:mapper/*.xml")
19. );
21. // 注册多个拦截器（注意顺序！先执行的拦截器先注册）
22. sessionFactory.setPlugins(slowSqlInterceptor, sensitiveInterceptor);
24. return sessionFactory.getObject();
25. }
26. }

复制代码

（6）测试效果

查询用户信息：

1. User user = userService.getUserById(1L);
2. System.out.println(user);
3. // 输出：User(id=1, username=张三, phone=138****5678, idCard=****************34)

复制代码

五、实战踩坑指南

5.1 拦截器顺序问题

坑：多个拦截器时，注册顺序就是执行顺序。比如先注册慢查询拦截器，再注册脱敏拦截器：

SQL执行 → 慢查询拦截器（记录时间） → 脱敏拦截器（处理结果）
如果顺序反了，脱敏拦截器会先处理结果，慢查询拦截器记录的SQL就看不到原始参数了。

解决：按"执行SQL前→执行SQL后→处理结果"的顺序注册。

5.2 拦截器签名配置错误

坑：@Signature的args参数类型写错，导致拦截不到方法。比如StatementHandler.prepare方法有两个重载：

1. // 正确的参数类型
2. prepare(Connection connection, Integer transactionTimeout)
3. // 错误示例：写成了(int)
4. @Signature(args = {Connection.class, int.class}) // 出现下面的异常！

复制代码

java.lang.NoSuchMethodException: org.apache.ibatis.executor.statement.StatementHandler.prepare(java.sql.Connection,int)

解决：通过IDE查看方法参数类型，确保完全一致。

5.3 性能问题

坑：在拦截器中做复杂操作（如反射遍历所有字段）会影响性能。

解决：

• 反射操作缓存Class信息
• 非必要不拦截（如只拦截查询方法）
• 敏感字段脱敏可考虑在DTO层处理

到此这篇关于SpringBoot集成MyBatis实现SQL拦截器的实战指南的文章就介绍到这了,更多相关SpringBoot MyBatis拦截SQL内容请搜索晓枫资讯以前的文章或继续浏览下面的相关文章希望大家以后多多支持晓枫资讯！

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！