3分钟搞定数据质量监控：MyBatis-Plus拦截器方案让异常无所遁形

数据异常导致的业务故障往往源于"亡羊补牢"式的被动响应。传统开发中，SQL注入、全表扫描、关联查询缺失索引等问题常常潜伏到生产环境才被发现。本文将详解如何利用MyBatis-Plus的拦截器（Interceptor）机制，构建轻量级数据质量监控体系，实时拦截异常SQL并预警，将数据治理防线前移到开发阶段。

拦截器原理：MyBatis-Plus的SQL防火墙

MyBatis-Plus通过插件（Plugin）机制提供了SQL执行全生命周期的拦截能力。核心实现类MybatisPlusInterceptor允许开发者注册多个InnerInterceptor，在SQL解析、参数处理、结果返回等环节植入自定义逻辑。这种设计类似过滤器链模式，每个拦截器专注于特定的数据质量规则校验。

关键实现类位于mybatis-plus-extension/src/main/java/com/baomidou/mybatisplus/extension/plugins/目录，其中IllegalSQLInnerInterceptor是数据质量监控的核心组件，通过JSqlParser解析SQL抽象语法树（AST），实现对SQL语义的深度分析。

实战配置：3步搭建监控体系

1. 引入拦截器依赖

在Spring Boot项目中，通过配置类注册拦截器链。以下代码演示如何同时启用分页插件和非法SQL拦截器：

@Configuration
public class MyBatisConfig {
    @Bean
    public MybatisPlusInterceptor mybatisPlusInterceptor() {
        MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
        // 添加分页拦截器
        interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL));
        // 添加SQL质量监控拦截器
        interceptor.addInnerInterceptor(new IllegalSQLInnerInterceptor()
                .setDbType(DbType.MYSQL)
                .setProhibitFullTableScan(true)
                .setProhibitWithoutWhere(true));
        return interceptor;
    }
}

配置类完整路径参考spring-boot-starter/mybatis-plus-spring-boot-autoconfigure/src/main/java/com/baomidou/mybatisplus/autoconfigure/

2. 核心规则配置

IllegalSQLInnerInterceptor提供了丰富的可配置规则，通过单元测试用例可以清晰了解其校验能力：

监控规则	配置方法	风险等级
禁止全表扫描	setProhibitFullTableScan(true)	高
禁止无WHERE条件更新删除	setProhibitWithoutWhere(true)	高
检测索引缺失	setCheckIndex(true)	中
限制单表关联数量	setMaxJoinTableNum(3)	中
禁止SELECT *查询	setProhibitSelectAll(true)	低

测试用例mybatis-plus-jsqlparser-support/mybatis-plus-jsqlparser-4.9/src/test/java/com/baomidou/mybatisplus/test/extension/plugins/inner/IllegalSQLInnerInterceptorTest.java展示了28种SQL场景的拦截效果，包括：

// 允许带索引的查询
Assertions.assertDoesNotThrow(() -> interceptor.parserSingle(
    "select * from T_DEMO where a = 1 and `b` = 2", 
    dataSource.getConnection()
));

// 拦截无索引条件的查询
Assertions.assertThrows(MybatisPlusException.class, () -> interceptor.parserSingle(
    "select * from T_DEMO where c = 3", 
    dataSource.getConnection()
));

3. 异常处理与告警集成

拦截到异常SQL时，默认抛出MybatisPlusException中断执行。生产环境中可扩展为：

public class AlertIllegalSQLInterceptor extends IllegalSQLInnerInterceptor {
    @Override
    protected void handleIllegalSql(String sql, String message) {
        // 1. 记录详细日志到ELK
        log.error("SQL质量异常: {}, SQL: {}", message, sql);
        // 2. 推送告警到企业微信/钉钉
        alertService.send("数据质量监控", message + "\n" + sql);
        // 3. 开发环境直接抛出异常，生产环境可降级处理
        if (environment.acceptsProfiles(Profiles.of("dev"))) {
            throw new MybatisPlusException(message);
        }
    }
}

高级应用：自定义监控规则

索引有效性校验

通过重写checkIndex方法，实现业务特异性的索引规则校验。例如强制要求订单表查询必须包含user_id条件：

@Override
protected boolean checkIndex(Connection connection, Table table, List<Expression> whereExpressions) {
    if ("t_order".equalsIgnoreCase(table.getName())) {
        return whereExpressions.stream()
            .anyMatch(expr -> expr.toString().contains("user_id"));
    }
    return super.checkIndex(connection, table, whereExpressions);
}

分表场景适配

对于Sharding-JDBC等分表中间件，可通过setSchema方法指定逻辑表对应的物理表元数据：

illegalSQLInterceptor.setSchemaProvider((sql, tableName) -> {
    if (tableName.startsWith("t_log_")) {
        return "t_log_202306"; // 动态获取当前分表
    }
    return tableName;
});

监控效果可视化

结合项目中的监控图表，可直观展示SQL质量趋势。下图显示某系统集成拦截器后，全表扫描SQL数量的周环比下降趋势：

通过mybatis-plus-core/src/main/java/com/baomidou/mybatisplus/core/toolkit/中的SqlUtils工具类，可实现SQL格式化、执行耗时统计等辅助功能，进一步丰富监控维度。

最佳实践与性能优化

1. 环境隔离：开发/测试环境启用严格模式，生产环境仅记录不中断
2. 规则分级：区分阻断性规则（如无WHERE更新）和警告性规则（如SELECT *）
3. 性能调优：通过setParseTimeout限制SQL解析超时时间，默认3秒
4. 白名单机制：对历史遗留SQL添加全类名+方法名的白名单豁免

illegalSQLInterceptor.setWhiteList(Arrays.asList(
    "com.legacy.service.OrderService.queryAll",
    "com.legacy.mapper.UserMapper.exportAll"
));

总结与扩展

MyBatis-Plus拦截器方案相比传统数据质量监控工具，具有侵入性低、响应实时、开发友好等优势。通过本文介绍的IllegalSQLInnerInterceptor组件，配合自定义规则扩展，可构建覆盖SQL编写、测试、上线全流程的质量防线。

官方文档README-zh.md提供了更多拦截器实现细节，建议结合mybatis-plus-core/src/test/java/com/baomidou/mybatisplus/core/plugins/目录下的测试用例深入学习。后续可进一步集成Prometheus metrics，构建数据质量大屏，实现从被动拦截到主动预防的治理升级。

本文配套示例代码已同步至项目仓库mybatis-plus-samples/quality-monitor，包含完整的规则配置与告警集成方案。