Skip to content

约 5 分钟阅读

MyBatis 插件的拦截边界 ​

订单查询偶尔变慢,可以先观察哪个 Mapper statement 耗时长,再到数据库核对执行计划、锁和连接等待。MyBatis 插件能在执行器、语句准备、参数绑定或结果映射等位置加入观测逻辑,但这些位置看到的时间和调用次数不同。先确定观测对象,才能解释日志。

本页以 MyBatis 3.5.19 为练习版本,沿用 映射、会话与事务 的 H2 订单例子。示例只记录调用标识、成功标志和经过时间,不修改 SQL,也不承担支付重试。

四类扩展点如何经过缓存 ​

MyBatis插件与缓存的拦截边界

Interceptor 通过 @Intercepts、@Signature 声明接口、方法名和参数类型,框架用 JDK 动态代理包装匹配的目标。常见扩展点是 Executor、StatementHandler、ParameterHandler 和 ResultSetHandler。签名必须精确匹配;只写同名方法不表示拦截了所有重载。

位置适合观察什么不能直接推出什么
Executor.query一次执行器查询调用的总耗时,包含所经过的缓存和映射不能当成数据库服务端执行耗时
Executor.update一次更新调用是否返回、执行器耗时不能证明事务最终提交;BATCH 模式还可能尚未发送到数据库
StatementHandler.prepare实际准备 JDBC Statement 的路径缓存命中、Statement 复用时不一定进入
ParameterHandler.setParameters参数向 JDBC 语句绑定的过程不等于可以把敏感参数原值写日志
ResultSetHandler.handleResultSets结果集读取和对象映射不能独立覆盖连接等待、执行和提交

图画的是普通查询主路径,其他执行器模式、游标、嵌套查询和插件组合需要分别验证。代理只拦截经过它的调用;目标对象内部自调用不会自动再经过同一代理。例如只拦截四参数 query,不能据此宣称覆盖了所有六参数调用或内部嵌套查询。

可编译的耗时观测插件 ​

以下是完整 MapperTimingPlugin.java,与上一页的 MyBatisOrder.java 放在同一练习目录。每次拦截只有一处 invocation.proceed()。目标失败时记录失败标志并把原异常继续向外传递,不再执行原 SQL。

java
import java.util.concurrent.TimeUnit;
import org.apache.ibatis.executor.Executor;
import org.apache.ibatis.mapping.MappedStatement;
import org.apache.ibatis.plugin.Interceptor;
import org.apache.ibatis.plugin.Intercepts;
import org.apache.ibatis.plugin.Invocation;
import org.apache.ibatis.plugin.Signature;
import org.apache.ibatis.session.ResultHandler;
import org.apache.ibatis.session.RowBounds;

@Intercepts({
    @Signature(type = Executor.class, method = "query",
        args = {MappedStatement.class, Object.class,
                RowBounds.class, ResultHandler.class}),
    @Signature(type = Executor.class, method = "update",
        args = {MappedStatement.class, Object.class})
})
public final class MapperTimingPlugin implements Interceptor {
    @Override
    public Object intercept(Invocation invocation) throws Throwable {
        MappedStatement statement = (MappedStatement) invocation.getArgs()[0];
        long started = System.nanoTime();
        boolean success = false;
        try {
            Object result = invocation.proceed();
            success = true;
            return result;
        } finally {
            long micros = TimeUnit.NANOSECONDS.toMicros(System.nanoTime() - started);
            try {
                System.err.printf("statement=%s success=%s elapsedMicros=%d%n",
                        statement.getId(), success, micros);
            } catch (RuntimeException loggingFailure) {
                // 观测写出失败不能覆盖数据库调用的结果或原始异常。
            }
        }
    }
}

nanoTime 用于测量同一 JVM 内的经过时间,不是日志事件的墙上时钟。success=true 只表示这个被拦截调用正常返回;外层业务仍可能失败或回滚。不要把它显示成“订单支付成功”。示例的标准错误输出适合练习,生产应接入有容量上限的指标或日志通道,避免同步输出阻塞请求。

在上一页 factory 方法中,放在 build 之前注册插件:

java
configuration.addInterceptor(new MapperTimingPlugin());
return new SqlSessionFactoryBuilder().build(configuration);
bash
javac --release 17 -encoding UTF-8 -cp 'lib/*' MyBatisOrder.java MapperTimingPlugin.java
java -cp '.:lib/*' MyBatisOrder

Windows 的运行 classpath 改为 .;lib/*。输出仍应保持订单 102 已支付、103 金额 3000 分、总额 8000 分;额外日志按调用记录 statement 标识。插件没有记录 SQL 参数、连接 URL、密码或异常消息,避免把业务数据带到观测系统。真实日志还需要访问控制、保留周期和请求关联标识。

注册顺序与共享状态 ​

同一目标先注册 A,再注册 B,后注册的代理位于外层。正常调用的顺序为 B进入 → A进入 → 目标 → A退出 → B退出;发生异常时则按各层的 catch/finally 逻辑退出。这条规则只适用于都匹配该对象和签名的插件,不代表所有 MyBatis 扩展点形成一条全局线性链。

原生 MyBatis 可在构建前 configuration.addInterceptor(...),也可在配置文件的 <plugins> 中注册。Spring Boot 集成应使用所选 starter 支持的插件 Bean 或配置定制入口;先检查实际配置中的拦截器列表,避免自动扫描与手动注册各加一次。org.apache.ibatis.session.Configuration 与 Spring 的 @Configuration 不是同一个类型。

插件实例可被多个会话和请求共享。当前示例把开始时间和成功标志放在局部变量里,没有用实例字段保存“当前订单”“当前连接方言”或“当前分页参数”。配置值应在启动阶段固定,不能在首次请求时猜出数据库方言后让所有数据源共用它。

分页改写为什么需要更多合同 ​

分页不是给任意 SQL 末尾添加 LIMIT 就结束。原 SQL 可能有 CTE、子查询、已有分页、锁语句、末尾分号或数据库特有语法;SQL Server 等方言还要求相应排序规则。查询结果由 SQL、绑定参数、分页条件和缓存键共同决定,若在生成缓存键后只改 SQL,可能把不同页混进同一缓存身份。

需要通用分页时,应评估项目已有、维护中的分页组件及其具体版本兼容范围;只有少数固定查询时,明确数据库方言的 SQL 通常更容易验证。两者都应检查页码/页大小边界、偏移量溢出、稳定唯一排序、空页、总数统计语义、缓存和其他插件顺序。不要通过反射写入 BoundSql 私有字段来绕过这些合同。

ThreadLocal 的清理范围也必须覆盖业务调用的完整生命周期。在 prepare 的 finally 中清理,无法覆盖缓存命中或进入 prepare 前已经抛错的路径;线程池复用时可能污染下一个请求。优先显式传递分页参数;必须使用线程上下文时,应由建立上下文的边界负责 try/finally 清理,嵌套调用还要有恢复策略。

验收与排错 ​

验证场景应看到什么失败意味着什么
同一会话连续执行相同查询执行器观测可能两次,数据库准备次数更少不应把日志条数直接当 SQL 请求数
更新违反数据库约束原异常向外传播,一次调用不自动再写捕获后重调 proceed 会形成隐式重试
更新正常返回后业务回滚观测可为 success=true,新会话仍读到旧值需要区分调用成功和事务提交
A、B 都匹配同一方法B进入、A进入、A退出、B退出检查注册顺序、重复注册和实际代理链
并发请求使用不同参数每次观测只关联自身调用检查共享字段与线程上下文泄漏

插件没生效时,先核对最终配置里是否已注册,再核对接口方法签名和本次路径是否真的经过该位置。慢查询排查应把执行器耗时、连接池等待、数据库执行计划与锁等待放在同一请求上下文中分析;单个插件不能代替这些证据。

别急,先让缓存热一下。