疑难杂症－MyBatis一级缓存引起的分页插件失效

症状：使用自定义MyBatis分页插件，只有分页参数不同的方法在短时间内使用不同分页参数查询出来的结果相同。
病因：自定义MyBatis插件拦截目标为StatementHandler，而在同一个SqlSession中，在StatementHandler.prepare之前，MyBatis的已经命中了一级缓存，所以直接返回了缓存中的内容。
治疗方案：重写自定义MyBatis分页插件使之拦截Executor，或增加新的插件，使之拦截Executor清除一级缓存。

这是我最近在一个项目中排查的一个问题，在这里记录一下以备后查。

首先这个项目并没有使用比较流行的PageHelper插件，而是自己实现了一个，由于不是本人的代码，就不贴出来了。网上搜一下的话也有很多类似的，主要的实现原理是使用MyBatis提供的@Intercepts拦截StatementHandler类的prepare方法，通过反射获取到MappedStatement和BoundSql。如果执行的是约定的分页方法（MappedStatement的id带有Page后缀），那么就把BoundSql中的sql字段更改为带有分页功能的sql。如果要使用分页查询，那么分页方法的参数需要带有分页参数，同时分页方法名需要带有约定的Page后缀。乍一看没有什么问题，但是在真正使用的时候，由于MyBatis一级缓存的存在，同一个SqlSession中后续的分页方法生成了相同的CacheKey，导致直接返回了缓存中的内容。这里主要的问题是拦截的时机，拦截发生在MyBatis决定是否要使用缓存之后！！

关于MyBatis的缓存机制，网上有很多资料讲的很详细，不清楚的可以先了解了解。总的来说，在同一个SqlSession中，执行同一条sql MyBatis会直接返回缓存。不过对于我们碰到的问题，一开始我是带着疑虑的，两次执行的方法明明分页参数是不同的，怎么会命中同一个缓存呢？带着这个疑问我们debug MyBatis的源码，查看其生成CacheKey的逻辑。首先当执行一条sql的时候，会进到4参数CachingExecutor.query,（网上一查，这个类是用来处理二级缓存的，明明没用二级缓存，为何会用到这个类？这里先留个悬念，后面再说）:

  @Override
  public <E> List<E> query(MappedStatement ms, Object parameterObject, RowBounds rowBounds, ResultHandler resultHandler) throws SQLException {
    BoundSql boundSql = ms.getBoundSql(parameterObject);
    CacheKey key = createCacheKey(ms, parameterObject, rowBounds, boundSql);
    return query(ms, parameterObject, rowBounds, resultHandler, key, boundSql);
  }

再看这里缓存key的生成方法，实际上是调用了delegate的createCacheKey方法。（那这个delegate又是个啥？我们待会一起说）：

  @Override
  public CacheKey createCacheKey(MappedStatement ms, Object parameterObject, RowBounds rowBounds, BoundSql boundSql) {
    return delegate.createCacheKey(ms, parameterObject, rowBounds, boundSql);
  }

查看createCacheKey方法的实现类，就只有CachingExecutor和BaseExecutor，所以这里是使用了BaseExecutor.createCacheKey生成缓存key：

@Override
  public CacheKey createCacheKey(MappedStatement ms, Object parameterObject, RowBounds rowBounds, BoundSql boundSql) {
    if (closed) {
      throw new ExecutorException("Executor was closed.");
    }
    CacheKey cacheKey = new CacheKey();
    cacheKey.update(ms.getId());
    cacheKey.update(rowBounds.getOffset());
    cacheKey.update(rowBounds.getLimit());
    cacheKey.update(boundSql.getSql());
    List<ParameterMapping> parameterMappings = boundSql.getParameterMappings();
    TypeHandlerRegistry typeHandlerRegistry = ms.getConfiguration().getTypeHandlerRegistry();
    // mimic DefaultParameterHandler logic
    for (ParameterMapping parameterMapping : parameterMappings) {
      if (parameterMapping.getMode() != ParameterMode.OUT) {
        Object value;
        String propertyName = parameterMapping.getProperty();
        if (boundSql.hasAdditionalParameter(propertyName)) {
          value = boundSql.getAdditionalParameter(propertyName);
        } else if (parameterObject == null) {
          value = null;
        } else if (typeHandlerRegistry.hasTypeHandler(parameterObject.getClass())) {
          value = parameterObject;
        } else {
          MetaObject metaObject = configuration.newMetaObject(parameterObject);
          value = metaObject.getValue(propertyName);
        }
        cacheKey.update(value);
      }
    }
    if (configuration.getEnvironment() != null) {
      // issue #176
      cacheKey.update(configuration.getEnvironment().getId());
    }
    return cacheKey;
  }

这里可以看到，CacheKey由四组参数组成，简单说就是待执行的

1. SQL代码的ID（ms.getId()），
2. MyBatis自带的内存分页边界（rowBounds.getOffset()与rowBounds.getLimit()），
3. xml中的sql语句（boundSql.getSql()），
4. 实际执行的参数（通过获取boundSql.getParameterMappings()并将parameterObject映射获得）。

虽然由于分页参数不同，我们这里每次传入的parameterObject不同，但是由于分页sql是在StatementHandler中进行拼装，xml中的sql并没有写相应的参数去接受分页参数，所以boundSql.getParameterMappings()并没有包含我们的分页参数，不同的parameterObject也就并没有造成不同的CacheKey。

搞明白了问题的原因，接下来我们要来解决这个问题。思路有四条，A：参考网上比较流行的PageHelper，将我们的分页插件改写成拦截Executor，在生成CacheKey前就拼装好SQL；B：执行分页方法时disable一级缓存；C：直接使用PageHelper替换；D：将分页参数写入xml中，如where #{pageNum} = #{pageNum} and #{pageSize} = #{pageSize}。这样不会影响执行结果，也能保证每次CacheKey值不同，实际上我们发现问题后的临时解决方案就是这个。最终评估改造成本后，决定使用B方案。

要disable缓存，我们得知道缓存再何时被使用。那我们继续debug，发现4参数数的CachingExecutor.query中生成CacheKey后调用了内部6参数的query方法：

  @Override
  public <E> List<E> query(MappedStatement ms, Object parameterObject, RowBounds rowBounds, ResultHandler resultHandler, CacheKey key, BoundSql boundSql)
      throws SQLException {
    Cache cache = ms.getCache();
    if (cache != null) {
      flushCacheIfRequired(ms);
      if (ms.isUseCache() && resultHandler == null) {
        ensureNoOutParams(ms, parameterObject, boundSql);
        @SuppressWarnings("unchecked")
        List<E> list = (List<E>) tcm.getObject(cache, key);
        if (list == null) {
          list = delegate.<E> query(ms, parameterObject, rowBounds, resultHandler, key, boundSql);
          tcm.putObject(cache, key, list); // issue #578 and #116
        }
        return list;
      }
    }
    return delegate.<E> query(ms, parameterObject, rowBounds, resultHandler, key, boundSql);
  }

这里有段if (cache != null)的判断逻辑，一开始还以为这里就是缓存起效的逻辑，但debug后发现并不是，每次进来这边cache取到的都是null，排除这里使用cache的可能。（那这里的cache是个啥？别急，待会和前面两个问题一块说。）这边最后调用了delegate.query，也就是BaseExecutor.query：

@Override
  public <E> List<E> query(MappedStatement ms, Object parameter, RowBounds rowBounds, ResultHandler resultHandler, CacheKey key, BoundSql boundSql) throws SQLException {
    ErrorContext.instance().resource(ms.getResource()).activity("executing a query").object(ms.getId());
    if (closed) {
      throw new ExecutorException("Executor was closed.");
    }
    if (queryStack == 0 && ms.isFlushCacheRequired()) {
      clearLocalCache();
    }
    List<E> list;
    try {
      queryStack++;
      list = resultHandler == null ? (List<E>) localCache.getObject(key) : null;
      if (list != null) {
        handleLocallyCachedOutputParameters(ms, key, parameter, boundSql);
      } else {
        list = queryFromDatabase(ms, parameter, rowBounds, resultHandler, key, boundSql);
      }
    } finally {
      queryStack--;
    }
    if (queryStack == 0) {
      for (DeferredLoad deferredLoad : deferredLoads) {
        deferredLoad.load();
      }
      // issue #601
      deferredLoads.clear();
      if (configuration.getLocalCacheScope() == LocalCacheScope.STATEMENT) {
        // issue #482
        clearLocalCache();
      }
    }
    return list;
  }

终于我们找到了我们要找的方法，我们看到这里通过localCache.getObject(key)获取缓存，如果存在直接返回，否则执行去数据库查询结果queryFromDatabase，再看queryFromDatabase：

private <E> List<E> queryFromDatabase(MappedStatement ms, Object parameter, RowBounds rowBounds, ResultHandler resultHandler, CacheKey key, BoundSql boundSql) throws SQLException {
    List<E> list;
    localCache.putObject(key, EXECUTION_PLACEHOLDER);
    try {
      list = doQuery(ms, parameter, rowBounds, resultHandler, boundSql);
    } finally {
      localCache.removeObject(key);
    }
    localCache.putObject(key, list);
    if (ms.getStatementType() == StatementType.CALLABLE) {
      localOutputParameterCache.putObject(key, parameter);
    }
    return list;
  }

这里通过localCache.putObject存放一级缓存。

由于我们每次调用CacheKey都相同，所以在BaseExecutor.query中就直接使用了缓存返回。那我们的拦截器是在哪里生效的？我们可以继续往下看，这里的doQuery方法调用了具体子类的doQuery方法，如SimpleExecutor.doQuery：

  @Override
  public <E> List<E> doQuery(MappedStatement ms, Object parameter, RowBounds rowBounds, ResultHandler resultHandler, BoundSql boundSql) throws SQLException {
    Statement stmt = null;
    try {
      Configuration configuration = ms.getConfiguration();
      StatementHandler handler = configuration.newStatementHandler(wrapper, ms, parameter, rowBounds, resultHandler, boundSql);
      stmt = prepareStatement(handler, ms.getStatementLog());
      return handler.<E>query(stmt, resultHandler);
    } finally {
      closeStatement(stmt);
    }
  }

  private Statement prepareStatement(StatementHandler handler, Log statementLog) throws SQLException {
    Statement stmt;
    Connection connection = getConnection(statementLog);
    stmt = handler.prepare(connection, transaction.getTimeout());
    handler.parameterize(stmt);
    return stmt;
  }

而这里的handler.prepare才是真正被我们的分页拦截器拦截到的方法，而这个时候缓存的使用早就被决定了。

那么我们如何disable缓存呢？我们回过头去看BaseExecutor.query方法，这里有一个关键的判断：

    if (queryStack == 0 && ms.isFlushCacheRequired()) {
      clearLocalCache();
    }

显然，我们可以通过将ms的flushCacheRequired设置为true来强行清除缓存。增加一个拦截器拦截Executor.query，利用反射强改flushCacheRequired属性。注意，这里只能拦截4参数的query方法而不能拦截到6参数的，由于6参数的query方法是通过内部调用的，无法被动态代理。具体代码如下供大家参考：

@Intercepts({@Signature(type = Executor.class, method = "query", args = {MappedStatement.class, Object.class,
        RowBounds.class, ResultHandler.class})})
public class PageLocalCacheDisableInterceptor implements Interceptor {

    private static final String DEFAULT_PAGE_SQLID = ".*Page$";

    @Override
    public Object intercept(Invocation invocation) throws Throwable {
        Object[] args = invocation.getArgs();
        MappedStatement ms = (MappedStatement) args[0];
        if (ms.getId().matches(DEFAULT_PAGE_SQLID)) {
            Class<?> clazz = ms.getClass();
            Field flushLocalCache = clazz.getDeclaredField("flushCacheRequired");
            flushLocalCache.setAccessible(true);
            flushLocalCache.set(ms, true);
        }
        return invocation.proceed();
    }

    @Override
    public Object plugin(Object target) {
        return Plugin.wrap(target, this);
    }

    @Override
    public void setProperties(Properties properties) {
        //do nothing
    }

}

说完了解决方案，我们解决下之前留下的三个疑问：

1. 为什么会用到CachingExecutor？
2. CachingExecutor中的delegate是什么？
3. CachingExecutor中的cache是什么？

MyBatis的二级缓存

实际上要弄明白这些问题，只需要搞明白MyBatis的二级缓存是什么就好了。我们继续看源码：

  public CachingExecutor(Executor delegate) {
    this.delegate = delegate;
    delegate.setExecutorWrapper(this);
  }

发现delegate就是个Executor，并且在CachingExecutor构造函数中传入，由于CachingExecutor本身也实现了Executor，那其实就是设计模式中的装饰者模式了。这时候我们就可以顺着这条线继续调查为啥MyBatis要用CachingExecutor装饰Executor，查看构造函数的调用方，发现只有一处调用，即Configuration.newExecutor：

 public Executor newExecutor(Transaction transaction, ExecutorType executorType) {
    executorType = executorType == null ? defaultExecutorType : executorType;
    executorType = executorType == null ? ExecutorType.SIMPLE : executorType;
    Executor executor;
    if (ExecutorType.BATCH == executorType) {
      executor = new BatchExecutor(this, transaction);
    } else if (ExecutorType.REUSE == executorType) {
      executor = new ReuseExecutor(this, transaction);
    } else {
      executor = new SimpleExecutor(this, transaction);
    }
    if (cacheEnabled) {
      executor = new CachingExecutor(executor);
    }
    executor = (Executor) interceptorChain.pluginAll(executor);
    return executor;
  }

这里首先会根据executorType为executor实例化一个对应的实现类，同时根据cacheEnabled是否为true来决定是否要用CachingExecutor装饰。而我们看到这个cacheEnabled是有初始值true的，并且在XMLConfigBuilder构造配置相的时候会设置true为缺省值，所以默认就会带上CachingExecutor：

  protected boolean cacheEnabled = true;

  configuration.setCacheEnabled(booleanValueOf(props.getProperty("cacheEnabled"), true));

那如果我们确定不用二级缓存，其实可以通过设置参数来关闭这个修饰器，这样原本执行的CachingExecutor.query就不会被执行，取而代之的是本身BaseExecutor.query方法，这样可以简化调用链路。设置如下：

<configuration>
    <settings>
        <!-- 打印查询语句 -->
        <setting name="logImpl" value="STDOUT_LOGGING"/>
        <!-- 二级缓存关闭-->
        <setting name="cacheEnabled" value="false"/>
    </settings>

    <typeAliases>
    </typeAliases>
    <!--plugins插件之 分页拦截器-->
    <plugins>
        <plugin interceptor="com.nfsq.member.coupon.common.PaginationInterceptor"></plugin>
        <plugin interceptor="com.nfsq.member.coupon.common.PageLocalCacheDisableInterceptor"></plugin>
    </plugins>
</configuration>

现在可以来解答一下之前留下的三个疑问了：

1. 由于默认二级缓存是开启的，就算我们没有使用二级缓存，MyBatis每次创建Executor的时候也都会用CachingExecutor装饰实际的Executor对象。
2. CachingExecutor中的delegate即被装饰的Executor对象。
3. CachingExecutor中的cache是二级缓存，MyBatis会优先使用二级缓存，如果没有二级缓存，再使用一级缓存，如果连一级缓存也没有，那就连接数据库查询。虽然二级缓存默认开启，但是是需要人为配置才能使用的，我们没有配置，所以每次都是null。