MyBatis版本升级导致OffsetDateTime入参解析异常问题复盘

背景

最近有一个数据统计服务需要升级 SpringBoot 的版本，由 1.5.x.RELEASE 直接升级到 2.3.0.RELEASE ，考虑到没有用到 SpringBoot 的内建 SPI ，升级过程算是顺利。但是出于代码洁癖和版本洁癖，看到项目中依赖的 MyBatis 的版本是 3.4.5 ，相比当时的最新版本 3.5.5 大有落后，于是顺便把它升级到 3.5.5 。升级完毕之后，执行所有现存的集成测试，发现有部分 OffsetDateTime 类型入参的查询方法出现异常，于是进行源码层面的 DEBUG 找到最终的问题并且解决。

问题复现

项目中有一个查询方法类似下面的演示例子：

public interface OrderMapper {

    List<Order> selectByCreateTime(@Param("startCreateTime") OffsetDateTime startCreateTime,
                                   @Param("endCreateTime") OffsetDateTime endCreateTime);
}

对应的 XML 文件中的 SQL 代码段如下：

<select id="selectByCreateTime" resultMap="BaseResultMap">
    SELECT *
    FROM t_order
    WHERE deleted = 0 
        AND create_time <![CDATA[>=]]> #{startCreateTime}
        AND create_time <![CDATA[<=]]> #{e ndCreateTime}
</select>

上面的 OrderMapper#selectByCreateTime() 方法在 MyBatis 版本为 3.4.5 的前提下执行没有任何异常，当 MyBatis 版本升级为 3.5.5 后再次执行，在 SQL 执行日志输出正确的前提下返回了一个空集合，具体的内容如下：

查询订单列表：[]

虽然上帝视角是确认了入参解析有问题，但是基于第一次发生异常的日志，其实定位不到具体发生问题的位置，当时条件反射认为有几处地方会出现这类异常（ SQL 比较简单，可以排除人为写错 SQL 占位符的情况）：

1. MyBatis 解析 OffsetDateTime 类型方法参数的方法有版本兼容问题。
2. MySQL 驱动包解析 OffsetDateTime 类型的参数有版本兼容问题。
3. 前面两种情况混合相互影响导致的，其实这里也可以理解为同一种情况，因为 MyBatis 归根到底是对 MySQL 驱动包进行了封装。

当时项目中使用的 mysql-connector-java 版本为 8.0.18 ，并未升级为当前的最新版本 8.0.21 ，所以当时也有怀疑是低版本 MySQL 驱动包没有兼容解析 OffsetDateTime 类型的参数。

简析MyBatis的执行流程

MyBatis 的源码并不复杂，如果省去分析它的配置和映射文件解析模块，一个查询 SQL （ SelectList ）的执行流程大致如下：

当然，因为问题出现在参数解析部分，只需要关注 StatementHandler 的处理逻辑即可。 StatementHandler 的父类 BaseStatementHandler 构造函数中，初始化了 ParameterHandler 和 ResultSetHandler 实例，提交到 SimpleExecutor 中的 doQuery() 方法中执行，使用了占位符参数的查询会经由 doQuery() 方法中的 prepareStatement() 方法然后调用 PreparedStatementHandler#parameterize() ，最终委托到 DefaultParameterHandler#setParameters() 方法进行参数设置，这个 setParameters() 方法会用到 ParameterMapping 和 TypeHandler 。

如果用到了内建的 TypeHandler 或者自定义的 TypeHandler 实现，同时出现了参数解析异常，那么很大几率异常就是从 DefaultParameterHandler#setParameters() 方法中出现，这样就能顺藤摸瓜找到出现异常的 TypeHandler 。

参数解析异常的根本原因

本文前面提到的解析 OffsetDateTime 类型异常，实际上执行查询的时候代码会步入 OffsetDateTimeTypeHandler ，这里对比一下 3.4.5 和 3.5.5 版本中 MyBatis 对应的 OffsetDateTimeTypeHandler 实现：

发现了主要区别如下：

• 3.4.5 版本中，会把 OffsetDateTime 参数类型转换为 Timestamp 类型，再委托到 PreparedStatement#setTimestamp() 进行参数设置。

• 3.5.5 版本中，直接调用 PreparedStatement#setObject() 进行参数设置。

PreparedStatement#setTimestamp() 是很早期的产物，这个方法是没有任何问题的， 3.4.5 版本 MyBatis 把 OffsetDateTime 类型兼容为 Timestamp 类型处理 。那么基本可以确定问题出现在 PreparedStatement#setObject() 方法上，对于 MySQL8.x 的驱动， PreparedStatement 选用的实现类是 com.mysql.cj.jdbc.ClientPreparedStatement ，通过层层 DEBUG 最终到达 AbstractQueryBindings#setObject() 方法：

由于驱动中没有任何解析 OffsetDateTime 类型的片段，所以最终会使用 AbstractQueryBindings#setSerializableObject() 方法（也就是 else 分支的代码）兜底，直接转化为一个 byte[] 传输到 MySQL 服务端， 问题就出在这里，直接把 OffsetDateTime 类型序列化疑似在 MySQL 服务端拿到的不是预期的参数，导致查询条件出现失效（这里笔者没有花时间去阅读 MySQL 的协议，也没有花大量时间去抓包，所以这里还只是猜测） 。然而， 这个问题在 2020-7-12 最新发布的 mysql:mysql-connector-java:8.0.21 依然没有解决 。但是看到这里又出现一个疑惑， MyBatis 的开发者应该不可能在这种关键而不复杂的问题上出现纰漏，于是花时间去看看这里的代码提交记录：

这是 Raupach 在 2017-08-22 的一个提交，提交的 message 是：测试 OffsetDateTimeHandler 保留了 UTC 的偏移量。单元测试类 OffsetDateTimeTypeHandlerTest 也只是验证了 TypeHandler#setParameter() 和 PreparedStatement#setObject() 参数传递的正确性， 并没有做集成测试去跟踪所有类型数据库的传参问题，估计就是这一步疏忽了，但是这个应该不属于MyBatis的问题，毕竟它只是对数据库驱动包的封装 。其中集成测试 TimestampWithTimezoneTypeHandlerTest 使用了内存数据库，这里可以猜测是 HSQLDB 驱动完善了日期时间的参数解析。

同样的问题在 h2 数据库中不会出现，于是稍微 DEBUG 了一下 h2 数据库驱动进行参数设置的源码，最终定位到 org.h2.value.DataType （驱动包的版本为 com.h2database:h2:1.4.200 ）的第 1333 行有对应 JSR310.OFFSET_DATE_TIME 的解析逻辑，所以 h2 数据库驱动可以支持所有 JSR310 引入的参数类型的参数值设置。下面的截图是 h2 数据库驱动中 PreparedStatement#setObject() 的解析实现（见 org.h2.jdbc.JdbcPreparedStatement 和 DataType#convertToValue() 的源码）：

这里可见， h2 的驱动真的对 JDK8+ 新增的所有日期时间类型都做了解析：

针对问题的解决方案

如果选用了 MySQL ，这个参数解析异常的问题截至 mysql:mysql-connector-java:8.0.21 只有一种解决方案：要把 OffsetDateTime 类型兼容为 Timestamp 类型进行参数设置。其实对于所有非 LocalXX 的日期时间类型都需要进行兼容，兼容表格如下：

序号 类型 兼容类型 调用方法 1 OffsetDateTime Timestamp PreparedStatement#setTimestamp() 2 ZonedDateTime Timestamp PreparedStatement#setTimestamp() 3 OffsetDate java.sql.Date PreparedStatement#setDate() 4 OffsetTime java.sql.Time PreparedStatement#setTime()

以 OffsetDateTime 为例，只需要参考或者直接使用 3.4.5 版本中的 MyBatis 的 OffsetDateTimeTypeHandler ，然后通过配置直接覆盖内置实现即可。

// 假设全类名为club.throwable.OffsetDateTimeTypeHandler
public class OffsetDateTimeTypeHandler extends BaseTypeHandler<OffsetDateTime> {

  @Override
  public void setNonNullParameter(PreparedStatement ps, int i, OffsetDateTime parameter, JdbcType jdbcType)
          throws SQLException {
    ps.setTimestamp(i, Timestamp.from(parameter.toInstant()));
  }

  @Override
  public OffsetDateTime getNullableResult(ResultSet rs, String columnName) throws SQLException {
    Timestamp timestamp = rs.getTimestamp(columnName);
    return getOffsetDateTime(timestamp);
  }

  @Override
  public OffsetDateTime getNullableResult(ResultSet rs, int columnIndex) throws SQLException {
    Timestamp timestamp = rs.getTimestamp(columnIndex);
    return getOffsetDateTime(timestamp);
  }

  @Override
  public OffsetDateTime getNullableResult(CallableStatement cs, int columnIndex) throws SQLException {
    Timestamp timestamp = cs.getTimestamp(columnIndex);
    return getOffsetDateTime(timestamp);
  }

  private static OffsetDateTime getOffsetDateTime(Timestamp timestamp) {
    if (timestamp != null) {
      // 这里可以考虑自定义系统的时区，例如ZoneId.of("Asia/Shanghai")
      return OffsetDateTime.ofInstant(timestamp.toInstant(), ZoneId.systemDefault());
    }
    return null;
  }
}

配置文件中进行 TypeHandler 配置覆盖，下面是类路径下配置文件 mybatis-config.xml 的示例：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE configuration PUBLIC "-//mybatis.org//DTD Config 3.0//EN" "http://mybatis.org/dtd/mybatis-3-config.dtd">
<configuration>
    <settings>
        <!--下划线转驼峰-->
        <setting name="mapUnderscoreToCamelCase" value="true"/>
        <!--未知列映射忽略-->
        <setting name="autoMappingUnknownColumnBehavior" value="NONE"/>
    </settings>
    <typeHandlers>
        <!--覆盖内置OffsetDateTimeTypeHandler-->
        <typeHandler handler="throwable.club.OffsetDateTimeTypeHandler"/>
    </typeHandlers>
</configuration>

其他类型解析异常都可以参照此思路进行兼容。

小结

升级基础框架版本需要谨慎。另外，文中提到的解决方案只是笔者目前通过问题分析和定位得到的一种相对合理的解决方案，也可能有更优解。

本文的 demo 项目仓库：

• Github ： https://github.com/zjcscut/spring-boot-guide/tree/master/ch9-mybatis-mysql

（本文完 c-2-d e-a-20200802 前段时间搬家带宽一直出问题，断更了接近一周）