插件开发与拦截链——分页、脱敏、多租户实战

概述

衔接前文

在前文《MyBatis 架构全解》中，我们已经分析了 InterceptorChain.pluginAll 如何利用 JDK 动态代理将多个拦截器织入责任链，按序包裹 Executor、StatementHandler、ParameterHandler、ResultSetHandler 四大核心对象。拦截链的门槛并不在于理解代理机制本身，而在于：如何依据业务需求精确选择拦截点？如何安全地改写即将执行的 SQL ？如何保证多个横切关注点在责任链中协调运作？本文将以三个高价值实战场景------分页、数据脱敏、多租户数据隔离------作为切入点，完整展示如何将 MyBatis 拦截链打造为企业级数据中间件的可靠通道。

总结性引言

MyBatis 的插件系统是它可扩展性的基石。与 Spring AOP 的 Bean 级横切不同，MyBatis 插件直接在数据库交互的最细粒度（Statement 准备、参数设置、结果集封装）施加影响。通过实现 Interceptor 接口并配合 @Intercepts 注解，开发者可以透明地改写 SQL、篡改参数、过滤结果集，而无需侵入任何业务代码。本文将深入分页方言的动态拼接、脱敏策略的模式封装、租户标识的 SQL 注入，揭示如何利用责任链模式"在最后一公里"干净利落地解决横切关注点，同时沉淀出一套可复用的拦截链开发方法论。

核心要点

• 拦截点决策 ：Executor、StatementHandler、ResultSetHandler 拦截时机与应用场景的全景决策树。
• 分页插件 ：在 StatementHandler.prepare 中利用 MetaObject 改写 BoundSql，动态适配多数据库方言，并处理 count 查询与缓存键隔离。
• 脱敏插件 ：通过 @Sensitive 注解与 MaskStrategy 策略接口，在 ResultSetHandler.handleResultSets 后自动对敏感字段进行脱敏。
• 多租户插件 ：基于 ThreadLocal 传递租户上下文，在 StatementHandler.prepare 阶段智能拼接 tenant_id 条件，防止全表泄露。
• 拦截链管理：慢 SQL 监控、多拦截器顺序控制、异常传播与回滚策略。
• 模式对比：MyBatis 拦截链与 Spring AOP 责任链在粒度、实现、适用场景上的本质区别。

文章组织架构图

flowchart TB n1["1. 拦截链回顾与拦截点选择策略"] n2["2. 分页插件实战: SQL重写与方言自动适配"] n3["3. 数据脱敏插件实战: 注解驱动与策略模式"] n4["4. 多租户数据隔离插件实战: SQL注入租户条件"] n5["5. 拦截链监控、顺序与异常处理"] n6["6. MyBatis 拦截链与 Spring AOP 的对比"] n7["7. 生产事故排查专题"] n8["8. 面试高频专题"] n1 --> n2 n1 --> n3 n1 --> n4 n2 --> n5 n3 --> n5 n4 --> n5 n5 --> n6 n6 --> n7 n7 --> n8 classDef topic fill:#f8f9fa,stroke:#333,stroke-width:2px,rx:5,color:#333; class n1,n2,n3,n4,n5,n6,n7,n8 topic;

架构图说明

• 总览说明：本文8个模块以责任链的拦截点选择为起点，依次实现三个经典插件，再升级到拦截链的运营管理、与 Spring 体系的横向对比，最后以生产事故复盘与面试高频题收尾，形成"理论回顾→实战落地→可靠性提升→对比认知→避坑验证"的完整闭环。
• 逐模块说明 ：
  • 模块1 是决策基础，帮助开发者根据需求选择最合适的拦截对象。
  • 模块2-4 是核心战例，分别演示如何在 SQL 重写、结果过滤、条件注入三个维度运用拦截链。
  • 模块5 将拦截链从"能跑"提升到"可靠"，覆盖监控与异常处理。
  • 模块6 在两个生态间做责任链模式对比，加深架构理解。
  • 模块7-8 落地排查与面试，保证知识的实战转化。
• 关键结论 ：MyBatis 插件是责任链模式的绝佳战场，掌握其对核心对象的拦截时机与改写技巧，是构建企业级数据中间件的必备技能。

---

1. 拦截链回顾与拦截点选择策略

1.1 责任链结构速览

InterceptorChain.pluginAll 遍历所有注册的拦截器，依次调用 Plugin.wrap(target, interceptor)，利用 JDK 动态代理为目标对象生成代理。若目标对象实现了多个接口（如 Executor 同时实现了 Executor 及其父接口），则 Plugin 会为所有接口创建代理，拦截所有匹配的方法。该过程本质是一个静态责任链 ：多个拦截器层层包裹同一个真实对象，形成一个"洋葱"结构；调用时从最外层代理进入，沿 interceptor.intercept(Invocation) 链式传递，最终抵达真实对象。

关键类与核心代码重温：

• org.apache.ibatis.plugin.Plugin.wrap(Object target, Interceptor interceptor) ：根据 @Intercepts 注解判断是否包装目标，使用 Proxy.newProxyInstance 创建代理。
• org.apache.ibatis.plugin.InterceptorChain.pluginAll(Object target) ：循环调用 plugin.wrap，逐层叠加。

// org.apache.ibatis.plugin.InterceptorChain
public Object pluginAll(Object target) {
  for (Interceptor interceptor : interceptors) {
    target = Plugin.wrap(target, interceptor);
  }
  return target;
}

该循环产生嵌套代理：proxy_n( ... proxy_2( proxy_1( target ) ) )，从而构成责任链。

责任链模式体现 ：每个 Interceptor 的 intercept 方法中可通过 invocation.proceed() 显式调用下一个拦截器或目标方法，形成完整的链式处理逻辑。与经典责任链不同，MyBatis 的链节点由动态代理自动串联，开发者只需关注业务逻辑，无须手动组装 next 指针。

1.2 拦截点决策表

MyBatis 可拦截的四大对象及其关键方法如下：

拦截对象	方法（常用）	参数特征	典型应用
Executor	query(MappedStatement, Object, RowBounds, ResultHandler, CacheKey, BoundSql)	包含完整的执行上下文、分页参数 RowBounds	慢 SQL 监控、分页拦截（早期思路）、缓存键定制
Executor	update(MappedStatement, Object)	更新操作，可获取 SQL 命令类型	租户条件注入（update 场景）、审计日志
StatementHandler	prepare(Connection, Integer)	此时 BoundSql 已生成，但尚未创建 Statement	分页方言改写、租户条件注入（改写 SQL）
StatementHandler	parameterize(Statement)	参数预编译之后，可获取 ParameterHandler	参数加密/掩码
ResultSetHandler	handleResultSets(Statement)	结果集已从数据库返回，尚未映射为 Java 对象	数据脱敏、结果过滤
ParameterHandler	setParameters(PreparedStatement)	参数设置阶段	参数脱敏（入库前）

1.3 拦截点选择原则

• 最小影响原则 ：优先选择离目标横切逻辑最近的拦截点。例如分页方言改写应在 SQL 构建完成后、预编译之前，因此 StatementHandler.prepare 是理想切入点；若选 Executor.query，则需额外解析 MappedStatement，且可能干扰一、二级缓存键。
• 避免拦截过广 ：仅对匹配的方法签名进行拦截，并在 intercept 中快速过滤无关操作（如只处理 SELECT 语句）。
• 性能考量：拦截器处于热路径上，应避免在拦截方法内执行重操作（如同步远程调用、复杂正则解析）。慢 SQL 监控应使用异步或轻量计时。
• 副作用隔离 ：改写 BoundSql 时需保留原始 SQL，便于日志审计；为结果对象脱敏时建议生成新对象或就地修改，避免影响缓存中的原值。

---

2. 分页插件实战：SQL 重写与方言自动适配

2.1 拦截点选择与设计思路

最常用的分页插件（如 PageHelper）早期曾拦截 Executor.query，通过改写 BoundSql 来实现。但该方式需要处理 RowBounds 参数与 CacheKey 的联动，且 SQL 改写时机偏晚。更优雅的做法是拦截 StatementHandler.prepare，此时 BoundSql 已生成且尚未传到 PreparedStatement，我们可以安全地修改其 SQL 字符串和参数映射，实现物理分页。

核心流程：

1. 从 ThreadLocal 获取分页参数（pageNum、pageSize）。
2. 在 prepare 拦截中，通过 MetaObject 取出 delegate.boundSql。
3. 依据数据库方言，将原始 SQL 包装成分页 SQL（如 MySQL LIMIT offset, size）。
4. 重新设置分页参数，剔除已消费的分页上下文，避免污染后续查询。
5. 可选：在 Executor.query 拦截点生成 count 查询，以支持总条数返回。

2.2 分页插件实现：拦截 StatementHandler.prepare

序列图：分页插件改写 BoundSql

sequenceDiagram participant Business as 业务代码 participant SqlSession as SqlSession participant Executor as Executor participant SH as StatementHandler participant PagePlugin as PageInterceptor participant DB as 数据库 Business->>SqlSession: selectList("findUser", params) SqlSession->>Executor: query(ms, params, RowBounds.DEFAULT) Executor->>SH: prepare(connection, txTimeout) Note over SH: 原始BoundSql已生成
包含SQL: SELECT * FROM user SH-->>PagePlugin: 拦截prepare方法 PagePlugin->>PagePlugin: 从ThreadLocal获取
pageNum=2, pageSize=10 PagePlugin->>PagePlugin: 通过MetaObject获取BoundSql PagePlugin->>PagePlugin: 根据方言生成分页SQL
SELECT * FROM user LIMIT 10,10 PagePlugin->>SH: 将改写后的SQL设置回BoundSql SH->>DB: 执行预处理与查询 DB-->>Business: 返回分页结果

图表主旨概括 ：展示分页插件如何在 StatementHandler.prepare 阶段截获 SQL，利用 MetaObject 动态改写为分页语句。 逐层/逐元素分解 ：业务调用的正常路径为 SqlSession -> Executor -> StatementHandler.prepare；动态代理在 StatementHandler 外包裹了 PageInterceptor，拦截 prepare 调用。插件从 ThreadLocal 获取分页上下文，通过 MyBatis 的 MetaObject 反射机制修改 BoundSql.getSql 返回的 SQL 字符串。 设计原理映射 ：这里使用代理模式 织入横切逻辑，策略模式 （方言适配）封装不同数据库的分页语法。ThreadLocal 用于解决参数传递的跨层问题，保证线程安全。 工程联系与关键结论 ：分页插件的本质是在 SQL 执行"最后一公里"对语句进行无侵入改写，拦截 StatementHandler.prepare 可以获得未预编译的纯净 SQL，避免了缓存键和参数映射的复杂处理，是生产级插件的最佳实践。

自行实现的 PageInterceptor 代码

// com.deepspring.mybatis.plugin.PageInterceptor
@Intercepts({
    @Signature(type = StatementHandler.class, method = "prepare", args = {Connection.class, Integer.class})
})
public class PageInterceptor implements Interceptor {

    // 分页参数上下文
    private static final ThreadLocal<PageInfo> PAGE_HOLDER = new ThreadLocal<>();

    // 方言策略映射
    private final Map<String, Dialect> dialectMap = new HashMap<>();

    public PageInterceptor() {
        dialectMap.put("MySQL", new MySqlDialect());
        dialectMap.put("PostgreSQL", new PostgreSqlDialect());
        // 可扩展 OracleDialect 等
    }

    /**
     * 业务侧调用此方法设置分页参数
     */
    public static void startPage(int pageNum, int pageSize) {
        PAGE_HOLDER.set(new PageInfo(pageNum, pageSize));
    }

    public static void clearPage() {
        PAGE_HOLDER.remove();
    }

    @Override
    public Object intercept(Invocation invocation) throws Throwable {
        PageInfo pageInfo = PAGE_HOLDER.get();
        if (pageInfo == null) {
            return invocation.proceed(); // 未设置分页，直接通过
        }

        try {
            StatementHandler handler = (StatementHandler) invocation.getTarget();
            MetaObject meta = MetaObject.forObject(handler,
                    SystemMetaObject.DEFAULT_OBJECT_FACTORY,
                    SystemMetaObject.DEFAULT_OBJECT_WRAPPER_FACTORY,
                    new DefaultReflectorFactory());
            // 获取原始 BoundSql
            BoundSql boundSql = (BoundSql) meta.getValue("delegate.boundSql");
            String originalSql = boundSql.getSql();
            // 根据数据库方言生成分页SQL
            String dialectKey = getDialectKey(handler);
            Dialect dialect = dialectMap.getOrDefault(dialectKey, new MySqlDialect());
            String pageSql = dialect.getPageSql(originalSql, pageInfo.getOffset(), pageInfo.getPageSize());
            // 设置改写后的SQL
            meta.setValue("delegate.boundSql.sql", pageSql);
            return invocation.proceed();
        } finally {
            clearPage(); // 务必清除，防止污染
        }
    }

    private String getDialectKey(StatementHandler handler) throws Throwable {
        // 简化：从数据源或配置中识别数据库类型，这里硬编码为 MySQL
        return "MySQL";
    }
}

设计解读：

• @Intercepts 明确拦截 StatementHandler.prepare。
• 参数通过 startPage 放入 ThreadLocal，确保同一线程内后续查询自动分页。
• MetaObject 是 MyBatis 的"万能斧"，通过 delegate.boundSql.sql 路径直达内部属性并修改，避免强耦合 RoutingStatementHandler 结构。
• finally 块中 clearPage() 防止分页参数残留导致其他查询异常。
• Dialect 接口封装方言差异，符合策略模式，新增数据库时仅需添加实现类即可。

Dialect 接口与 MySQL 实现

// com.deepspring.mybatis.plugin.dialect.Dialect
public interface Dialect {
    String getPageSql(String sql, int offset, int limit);
}

// com.deepspring.mybatis.plugin.dialect.MySqlDialect
public class MySqlDialect implements Dialect {
    @Override
    public String getPageSql(String sql, int offset, int limit) {
        return sql + " LIMIT " + offset + ", " + limit;
    }
}

// com.deepspring.mybatis.plugin.dialect.PostgreSqlDialect
public class PostgreSqlDialect implements Dialect {
    @Override
    public String getPageSql(String sql, int offset, int limit) {
        return sql + " LIMIT " + limit + " OFFSET " + offset;
    }
}

2.3 count 查询的实现

为支持分页总数返回，可再增加一个拦截 Executor.query 的拦截器，在执行前判断是否携带分页标记，动态构造 SELECT COUNT(*) FROM (原始SQL) _count 查询。

@Intercepts({
    @Signature(type = Executor.class, method = "query", args = {MappedStatement.class, Object.class, RowBounds.class, ResultHandler.class})
})
public class CountInterceptor implements Interceptor {
    @Override
    public Object intercept(Invocation invocation) throws Throwable {
        // 判断是否需要执行 count，通过 ThreadLocal 标记
        if (PageThreadLocal.needCount()) {
            // 从 MappedStatement 获取 BoundSql 并改写为 count SQL，单独执行
            // 将 count 结果存入 PageThreadLocal，并阻止原查询重复执行
        }
        return invocation.proceed();
    }
}

实际应用时，CountInterceptor 可与 PageInterceptor 配合，通过 ThreadLocal 传递 total 结果。关键点 ：count 查询必须独立于原始查询，不能影响原始 CacheKey，否则缓存将错乱。

2.4 与缓存的冲突及解决

MyBatis 的二级缓存以 CacheKey 作为查询结果标识。CacheKey 由 MappedStatement.id、RowBounds 偏移量、BoundSql 及参数等组合生成。若分页参数未纳入 CacheKey，同一 SQL 的不同页码可能返回相同缓存结果，造成数据错乱。 解决方案：

• 在分页插件改写 SQL 后，BoundSql.getSql 已含有分页方言片段（如 LIMIT 10,10），该片段作为 CacheKey 的一部分自然隔离不同分页结果。但若插件仅通过修改 RowBounds（而不改写物理 SQL）进行逻辑分页，则必须自定义 CacheKey。
• 自行实现的 PageInterceptor 直接改写了 SQL，因此能够天然区分 CacheKey，无需额外处理。但需注意 count 查询应避免生成 CacheKey 或使用独立的缓存区域。

---

3. 数据脱敏插件实战：注解驱动与策略模式

3.1 需求与方案

业务中常需要对手机号、身份证、邮箱等敏感数据在返回前端前自动脱敏。MyBatis 插件可以在结果映射之后、返回调用者之前完成此任务。拦截点选 ResultSetHandler.handleResultSets，此时数据库原始值已经封装到 Java 对象中，插件遍历对象的字段，识别 @Sensitive 注解后调用相应脱敏策略，修改字段值。

核心序列图：脱敏插件处理结果集

sequenceDiagram participant Executor participant RSH as ResultSetHandler(代理) participant MaskPlugin as SensitiveInterceptor participant OriginalRSH as 真实ResultSetHandler participant DB as 数据库结果集 Executor->>RSH: handleResultSets(statement) RSH->>MaskPlugin: inv.intercept() MaskPlugin->>MaskPlugin: invocation.proceed() 先执行原方法 Note over OriginalRSH: 返回 List