Mybatis插件机制(拦截器)和缓存机制示例详解

public interface executor {

  resulthandler no_result_handler = null;
	/**
	 * 执行更新操作（insert、update、delete）
	 * <p><b>执行流程：</b></p>
	 * <ol>
	 *   <li>创建 statementhandler</li>
	 *   <li>调用 parameterhandler 设置参数</li>
	 *   <li>执行 sql 更新</li>
	 *   <li>清理相关缓存</li>
	 * </ol>
	 * @param ms mappedstatement 对象，包含 sql 映射信息
	 * @param parameter 参数对象，可以是 map 或 pojo
	 * @return 影响的行数
	 * @throws sqlexception 如果数据库操作失败
	 */
  int update(mappedstatement ms, object parameter) throws sqlexception;
  /**
   * 执行查询操作（完整参数版本）
   * 这是查询操作的底层实现，包含所有必要的参数。通常由另一个重载的 query 方法调用。
   * @param <e> 返回结果的类型
   * @param ms mappedstatement 对象
   * @param parameter 参数对象
   * @param rowbounds 分页参数，包含 offset 和 limit
   * @param resulthandler 结果处理器，用于自定义结果处理
   * @param cachekey 缓存键，用于一级缓存
   * @param boundsql 绑定的 sql 信息
   * @return 查询结果列表
   * @throws sqlexception 如果数据库操作失败
   *
   * @see #query(mappedstatement, object, rowbounds, resulthandler)
   */
  <e> list<e> query(mappedstatement ms, object parameter, rowbounds rowbounds, resulthandler resulthandler,
      cachekey cachekey, boundsql boundsql) throws sqlexception;
   /**
    * 执行查询操作（常用版本）
    *
    * <p><b>执行流程：</b></p>
    * <ol>
    *   <li>检查一级缓存</li>
    *   <li>缓存未命中时查询数据库</li>
    *   <li>创建 statementhandler 和 resultsethandler</li>
    *   <li>执行查询并映射结果</li>
    *   <li>将结果存入一级缓存</li>
    * </ol>
    * @param <e> 返回结果的类型
    * @param ms mappedstatement 对象
    * @param parameter 参数对象
    * @param rowbounds 分页参数
    * @param resulthandler 结果处理器，如果为 null 则使用默认处理器
    * @return 查询结果列表
    * @throws sqlexception 如果数据库操作失败
    */
  <e> list<e> query(mappedstatement ms, object parameter, rowbounds rowbounds, resulthandler resulthandler)
      throws sqlexception;
  /**
   * 执行查询操作，返回游标（用于大数据量流式处理）
   * <p>与普通查询不同，游标查询不会一次性加载所有数据到内存，
   * 而是逐条处理，适合处理大数据集。</p>
   * @param <e> 返回结果的类型
   * @param ms mappedstatement 对象
   * @param parameter 参数对象
   * @param rowbounds 分页参数
   * @return 查询结果游标
   * @throws sqlexception 如果数据库操作失败
   */
  <e> cursor<e> querycursor(mappedstatement ms, object parameter, rowbounds rowbounds) throws sqlexception;
   /**
    * 刷新批处理语句
    *
    * <p>执行所有缓存的批处理语句，通常在 batchexecutor 中使用。
    * 调用此方法会执行所有已添加但未执行的批处理操作。</p>
    * @return 批处理结果列表
    * @throws sqlexception 如果数据库操作失败
    * @see org.apache.ibatis.executor.batchresult
    *
    * @example
    * <pre>
    * // 批处理操作示例
    * for (user user : users) {
    *     sqlsession.insert("insertuser", user);
    * }
    * list<batchresult> results = sqlsession.flushstatements();
    * </pre>
    */
  list<batchresult> flushstatements() throws sqlexception;
  /**
   * 提交事务
   * <p>如果 required 为 true，则强制提交事务；
   * 如果为 false，则根据事务状态决定是否提交。</p>
   * @param required 是否强制提交
   */
  void commit(boolean required) throws sqlexception;
  /**
   * 回滚事务
   * <p>如果 required 为 true，则强制回滚事务；
   * 如果为 false，则根据事务状态决定是否回滚。</p>
   * @param required 是否强制回滚
   */
  void rollback(boolean required) throws sqlexception;
  /**
   * 创建缓存键
   *
   * <p>根据 sql 语句、参数和分页信息生成唯一的缓存键，
   * 用于一级缓存的键值对存储。</p>
   *
   * @param ms mappedstatement 对象
   * @param parameterobject 参数对象
   * @param rowbounds 分页信息
   * @param boundsql 绑定的 sql
   * @return 缓存键对象
   */
  cachekey createcachekey(mappedstatement ms, object parameterobject, rowbounds rowbounds, boundsql boundsql);
  /**
   * 检查指定缓存键是否已缓存
   *
   * <p>查询一级缓存中是否存在指定 mappedstatement 和缓存键对应的结果。</p>
   *
   * @param ms mappedstatement 对象
   * @param key 缓存键
   * @return 如果已缓存返回 true，否则返回 false
   */
  boolean iscached(mappedstatement ms, cachekey key);
  /**
   * 清理本地缓存（一级缓存）
   *
   * <p>清除当前 executor 实例的所有一级缓存。
   * 在更新操作后会自动调用，也可以手动调用。</p>
   */
  void clearlocalcache();
  /**
   * 延迟加载
   *
   * <p>用于处理关联对象的延迟加载。当访问懒加载属性时，
   * mybatis 会调用此方法从数据库加载关联数据。</p>
   *
   * @param ms 关联对象的 mappedstatement
   * @param resultobject 结果对象（主对象）
   * @param property 要加载的属性名
   * @param key 缓存键
   * @param targettype 目标类型
   */
  void deferload(mappedstatement ms, metaobject resultobject, string property, cachekey key, class<?> targettype);

  /**
   * 获取事务对象
   * @return 当前的事务对象
   * @see org.apache.ibatis.transaction.transaction
   */
  transaction gettransaction();
  /**
   * 关闭执行器
   *
   * <p>如果 forcerollback 为 true，则在关闭前强制回滚所有未提交的事务；
   * 如果为 false，则根据事务状态决定。</p>
   *
   * @param forcerollback 是否强制回滚
   */
  void close(boolean forcerollback);
  /**
   * 检查执行器是否已关闭
   * @return 如果已关闭返回 true，否则返回 false
   */
  boolean isclosed();
  /**
   * 设置执行器包装器
   * <p>用于插件机制，允许在现有 executor 外包装额外的逻辑。
   * 这个方法通常由 mybatis 内部使用。</p>
   * @param executor 包装器执行器
   */
  void setexecutorwrapper(executor executor);
}

/**
 * mybatis 结果集处理器核心接口
 * <p><b>核心映射流程：</b></p>
 * <ol>
 *   <li>遍历 resultset 的每一行</li>
 *   <li>根据 resultmap 创建目标对象实例</li>
 *   <li>将列值映射到对象属性</li>
 *   <li>处理嵌套查询和延迟加载</li>
 *   <li>返回映射后的对象集合</li>
 * </ol>
 */
public interface resultsethandler {

  /**
   * 处理结果集并将其转换为 java 对象列表，默认方法
   * 
   * <p><b>执行流程：</b></p>
   * <ol>
   *   <li>获取 resultset 元数据（列信息）</li>
   *   <li>遍历 resultset 的每一行数据</li>
   *   <li>根据 resultmap 创建目标对象实例</li>
   *   <li>将列值设置到对象属性中（支持自动映射和显式映射）</li>
   *   <li>处理关联对象（association）和集合对象（collection）</li>
   *   <li>返回完整映射的对象列表</li>
   * </ol>
   *
   * @param <e> 返回结果的类型
   * @param stmt jdbc statement 对象，包含执行后的 resultset
   * @return 映射后的 java 对象列表，如果没有结果返回空列表（非 null）
   */
  <e> list<e> handleresultsets(statement stmt) throws sqlexception;

  /**
   * 处理游标结果集，支持流式读取大数据集
   * 
   * <p>与 {@link #handleresultsets(statement)} 不同，此方法返回 cursor 对象，
   * 允许逐条处理结果，避免一次性加载所有数据到内存。</p>
   * 
   * <p><b>适用场景：</b></p>
   * <ul>
   *   <li>处理大量数据（避免内存溢出）</li>
   *   <li>需要逐条处理的业务逻辑</li>
   *   <li>数据导出或批量处理</li>
   * </ul>
   *
   * @param <e> 返回结果的类型
   * @param stmt jdbc statement 对象
   * @return 游标对象，用于迭代访问结果
   */
  <e> cursor<e> handlecursorresultsets(statement stmt) throws sqlexception;

  /**
   * 处理存储过程的输出参数
   * <p>专门用于处理 callablestatement 中的输出参数（out/inout 参数）。
   * 在执行存储过程后，从此方法中获取输出参数的值。</p>
   * <p><b>处理流程：</b></p>
   * <ol>
   *   <li>从 callablestatement 中获取输出参数元数据</li>
   *   <li>根据 parametermap 配置定位输出参数</li>
   *   <li>使用 typehandler 将 jdbc 类型转换为 java 类型</li>
   *   <li>将输出参数值设置到参数对象中</li>
   * </ol>
   *
   * @param cs 调用存储过程后的 callablestatement 对象
   */
  void handleoutputparameters(callablestatement cs) throws sqlexception;
}

/**
 * mybatis 参数处理器核心接口
 * <p><b>参数处理流程：</b></p>
 * <ol>
 *   <li>获取 mapper 方法的参数对象</li>
 *   <li>解析参数类型和值</li>
 *   <li>使用 typehandler 进行类型转换</li>
 *   <li>将参数设置到 preparedstatement 的对应位置</li>
 * </ol>
 */
public interface parameterhandler {

  /**
   * 获取原始参数对象
   * 
   * <p>返回 mapper 方法调用时传入的原始参数对象。
   * 参数可能是单个对象、map、或者被 @param 注解标注的多参数包装对象。</p>
   *
   * @return 原始参数对象，如果没有参数则返回 null
   * @example
   * // mapper 方法定义：user selectuser(@param("id") long id, @param("name") string name);
   * // 调用时，getparameterobject() 返回的可能是：
   * // 1. map 对象：{id=1, name="张三", param1=1, param2="张三"}
   * // 2. 或者经过包装的参数对象
   */
  object getparameterobject();

  /**
   * 设置参数到 preparedstatement
   * 
   * <p><b>核心执行流程：</b></p>
   * <ol>
   *   <li>获取 boundsql 中的参数映射信息</li>
   *   <li>遍历所有参数映射（parametermapping）</li>
   *   <li>根据参数名称从参数对象中获取值</li>
   *   <li>使用对应的 typehandler 将 java 类型转换为 jdbc 类型</li>
   *   <li>调用 preparedstatement.setxxx() 方法设置参数</li>
   * </ol>
   *
   * @param ps jdbc preparedstatement 对象
   * @throws sqlexception 如果数据库操作失败或参数设置错误
   */
  void setparameters(preparedstatement ps) throws sqlexception;
}

/**
 * mybatis 语句处理器核心接口
 */
public interface statementhandler {

  /**
   * 准备 sql 语句，创建 jdbc statement 对象
   * 
   * <p><b>执行流程：</b></p>
   * <ol>
   *   <li>根据 sql 类型创建对应的 statement（preparedstatement/callablestatement）</li>
   *   <li>设置查询超时时间</li>
   *   <li>设置获取大小（fetch size）等优化参数</li>
   *   <li>返回准备好的 statement 对象</li>
   * </ol>
   *
   * @param connection 数据库连接
   * @param transactiontimeout 事务超时时间（秒），可为 null
   * @return 准备好的 jdbc statement 对象
   * @throws sqlexception 如果数据库操作失败
   */
  statement prepare(connection connection, integer transactiontimeout) throws sqlexception;

  /**
   * 参数化 statement，设置 sql 参数
   * <p>调用 parameterhandler 将 java 参数设置到 preparedstatement 中。
   * 这是参数绑定的核心步骤。</p>
   *
   * @param statement jdbc statement 对象（通常是 preparedstatement）
   * @throws sqlexception 如果参数设置失败
   */
  void parameterize(statement statement) throws sqlexception;

  /**
   * 执行批量操作
   * 
   * <p>将多个 sql 语句添加到批处理中，但不立即执行。
   * 实际的执行由 {@link org.apache.ibatis.executor.batchexecutor} 控制。</p>
   *
   * @param statement jdbc statement 对象
   * @throws sqlexception 如果批处理操作失败
   */
  void batch(statement statement) throws sqlexception;

  /**
   * 执行更新操作（insert、update、delete）
   * 
   * <p><b>执行流程：</b></p>
   * <ol>
   *   <li>调用 parameterize() 方法设置参数</li>
   *   <li>执行 statement.executeupdate()</li>
   *   <li>返回影响的行数</li>
   * </ol>
   *
   * @param statement jdbc statement 对象
   * @return 影响的行数
   * @throws sqlexception 如果数据库操作失败
   */
  int update(statement statement) throws sqlexception;

  /**
   * 执行查询操作，返回结果列表
   * 
   * <p><b>执行流程：</b></p>
   * <ol>
   *   <li>调用 parameterize() 方法设置参数</li>
   *   <li>执行 statement.executequery()</li>
   *   <li>调用 resultsethandler 处理结果集</li>
   *   <li>返回映射后的对象列表</li>
   * </ol>
   *
   * @param <e> 返回结果的类型
   * @param statement jdbc statement 对象
   * @param resulthandler 结果处理器
   * @return 查询结果列表
   * @throws sqlexception 如果数据库操作失败

   */
  <e> list<e> query(statement statement, resulthandler resulthandler) throws sqlexception;

  /**
   * 执行查询操作，返回游标（用于流式处理大数据集）
   * 
   * <p>与 {@link #query(statement, resulthandler)} 不同，此方法返回 cursor 对象，
   * 允许逐条读取结果，避免一次性加载所有数据到内存。</p>
   *
   * @param <e> 返回结果的类型
   * @param statement jdbc statement 对象
   * @return 查询结果游标
   * @throws sqlexception 如果数据库操作失败
   */
  <e> cursor<e> querycursor(statement statement) throws sqlexception;

  /**
   * 获取绑定的 sql 信息
   * <p>boundsql 包含最终要执行的 sql 语句、参数映射信息和参数对象。</p>
   * @return boundsql 对象，包含 sql 语句和参数信息
   */
  boundsql getboundsql();

  /**
   * 获取参数处理器
   * <p>parameterhandler 负责将 java 参数转换为 jdbc 参数。</p>
   * @return parameterhandler 对象
   */
  parameterhandler getparameterhandler();
}

public interface interceptor {
	// 核心拦截方法
  object intercept(invocation invocation) throws throwable;
	// 生成代理对象，将该插件加入到过滤器链中。底层是代理技术。
  default object plugin(object target) {
    return plugin.wrap(target, this);
  }
	// 设置属性值，接收xml传递来的参数信息
  default void setproperties(properties properties) {
    // nop
  }
}

public class testmybatisinterceptor implements interceptor {
    /**
     * 核心方法
     * @param invocation
     * @return
     * @throws throwable
     */
    @override
    public object intercept(invocation invocation) throws throwable {
        // 核心方法,确保mybatis方法可以正常运行
        object proceed = invocation.proceed();
        
        return proceed;
    }
}

@intercepts({
    @signature(type = 要拦截的类.class, method = "要拦截的方法名", args = {参数类型列表})
})
public class myinterceptor implements interceptor {
    // 实现interceptor接口的方法
}

/**
 * 拦截mybatis执行器的方法query()【执行查询操作（常用版本）】
 */
@intercepts(
        @signature(
                type = executor.class,
                method = "query",
                args = {mappedstatement.class, object.class, rowbounds.class, resulthandler.class}
        )
)
public class testmybatisinterceptor implements interceptor {

    /**
     * 核心拦截方法
     */
    @override
    public object intercept(invocation invocation) throws throwable {
        // 核心方法,确保mybatis方法可以正常运行
        object proceed = invocation.proceed();
        return proceed;
    }
}

invocation.gettarget()：获取被拦截的对象（例如executor实例）。
invocation.getmethod()：获取被拦截的方法（method对象）。
invocation.getargs()：获取被拦截方法的参数数组。
invocation.proceed()：执行原方法。

package com.maven.mybatis.plugins;

import org.apache.ibatis.executor.executor;
import org.apache.ibatis.mapping.boundsql;
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;

import java.lang.reflect.method;

/**
 * 拦截mybatis执行器的方法query()【执行查询操作（常用版本）】
 */
@intercepts(
        @signature(
                type = executor.class,
                method = "query",
                args = {mappedstatement.class, object.class, rowbounds.class, resulthandler.class}
        )
)
public class testmybatisinterceptor implements interceptor {

    /**
     * 核心拦截方法，拦截所有的查询方法，并输出sql语句
     */
    @override
    public object intercept(invocation invocation) throws throwable {
        // cachingexecutor
        object target = invocation.gettarget();
        // 拦截的那个方法：被@signature注解修饰的methdo="query"方法。
        // org.apache.ibatis.executor.executor.query(mappedstatement,object,rowbounds,resulthandler)
        method method = invocation.getmethod();
        // 方法的参数信息
        object[] args = invocation.getargs();
        // 获取sql语句处理器
        mappedstatement ms = (mappedstatement) args[0];
        // args[1]：paramhandler，获取参数处理器
        boundsql boundsql = ms.getboundsql(args[1]);
        // 获取sql语句，xml中定义的sql语句，未进行参数替换
        string sql = boundsql.getsql();
        system.out.println("sql = " + sql);
        // 核心方法,确保mybatis方法可以正常运行
        object proceed = invocation.proceed();
        return proceed;
    }
}

    <plugins>
        <plugin interceptor="com.maven.mybatis.plugins.testmybatisinterceptor">
        </plugin>
    </plugins>

    @test
    public void user() throws exception {
        // 将配置文件转为输入流
        inputstream inputstream = resources.getresourceasstream("mybatis-config.xml");
        // 创建sqlsessionfactorybuilder，作用是根据配置文件，创建sqlsessionfactory工厂
        sqlsessionfactorybuilder sqlsessionfactorybuilder = new sqlsessionfactorybuilder();
        // 根据配置文件，创建工程sqlsessionfactory，全局唯一
        sqlsessionfactory sqlsessionfactory = sqlsessionfactorybuilder.build(inputstream);
        // 工厂创建sqlsession，建立一次会话
        sqlsession sqlsession = sqlsessionfactory.opensession();
        // 使用和指定语句的参数和返回值相匹配的接口,映射器实例
        usermapper usermapper = sqlsession.getmapper(usermapper.class);
        user user = usermapper.selectuserbyid(1);
        system.out.println("user = " + user);
        sqlsession.close();
    }

sql = select
            id ,
            user_name username,
            password
        from user where id = ?

执行查询操作
    ↓
检查二级缓存（如果开启）
    ↓ 命中 → 返回结果
    ↓ 未命中
检查一级缓存（当前sqlsession）
    ↓ 命中 → 返回结果（并存入二级缓存）
    ↓ 未命中
查询数据库
    ↓
结果存入一级缓存
    ↓
sqlsession关闭时 → 一级缓存数据刷入二级缓存