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 占位符的情况）：

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

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

简析MyBatis的执行流程

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

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

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

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

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

参数解析异常的根本原因

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

发现了主要区别如下：

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

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

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

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

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

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

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

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

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

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

同样的问题在 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() 的源码）：

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

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

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

针对问题的解决方案

如果选用了 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>