背景

最近有一個數據統計服務需要升級 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 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 ）的執行流程大致如下：

當然，因為問題出現在參數解析部分，只需要關注 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.OffsetDateTimeTypeHandlerpublic 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

到此這篇關于MyBatis版本升級導致OffsetDateTime入參解析異常問題復盤的文章就介紹到這了,更多相關MyBatis OffsetDateTime入參異常內容請搜索好吧啦網以前的文章或繼續瀏覽下面的相關文章希望大家以后多多支持好吧啦網！