【微服务】mybatis typehandler使用详解

一、前言

二、TypeHandler简介

2.1 什么是TypeHandler

2.1.1 TypeHandler特点

2.2 TypeHandler原理

2.3 mybatis自带的TypeHandler

三、环境准备

3.1 准备一张数据表

3.2 搭建一个springboot工程

3.2.1 基础依赖如下

3.2.2 核心配置文件

3.2.3 测试接口

四、TypeHandler在项目中的使用

4.1 时间类型转换问题

4.1.1 添加自定义TypeHandler

4.1.2 添加扫描

4.1.3 xml配置字段引用自定义TypeHandler

4.1.4 接口效果测试

4.1.5 新增数据

4.2 常用的TypeHandler

4.2.1 List类型的处理

4.2.2 枚举类型的处理

4.2.3 json类型的处理

4.3 注意事项

4.3.1 自定义TypeHandler步骤

4.3.2 自定义TypeHandler使用注意事项

五、写在文末

一、前言

在springboot为基础框架的微服务开发中，经常要涉及到数据库的操作，此时mybatis或mybatis-plus便成为技术选型中必不可少的组件。基本上来说，springboot+mybatis成为很多公司微服务项目的基础选型。使用mybatis的好处很多，这里不再赘述了，接下来要探讨的是在业务代码中，如何使用mybtais完成一些字段的类型转换。

二、TypeHandler简介

2.1 什么是TypeHandler

TypeHandler，即：类型转换器，在mybatis中用于实现 java类型和 JDBC类型的相互转换，在 Java 与mybatis的整合开发中，TypeHandler 是 MyBatis 框架的一个核心组件，用于实现数据库表字段类型与和Java 数据类型之间的相互转换。这个组件的存在，它允许开发人员自定义类型处理器，以满足特定场景下的业务需求。

TypeHandler 作用是在 MyBatis 执行数据查询或更新操作时，将数据库中的列值转换为 Java 对象，并在将 Java 对象写入数据库时执行相反的转换。它提供了一种灵活且可扩展的方式，用于处理数据库类型与 Java 类型之间的映射关系。

2.1.1 TypeHandler特点

TypeHandler在实际项目中该如何使用呢？需要搞清它的特点才能更好的掌握其使用场景，以下列举了TypeHandler 一些特点和使用方式；

类型转换，TypeHandler 负责将数据库表中的字段值转换为 Java 对象，并将 Java 对象转换为数据库表中可被接受的类型；
映射规则，TypeHandler 是基于映射规则的（在下文的表中详细给出了常用的映射规则），即在 MyBatis 映射文件中，需要指定表字段和对象属性之间的映射关系，这样TypeHandler才能正确进行类型转换；
支持自定义类型转换器，MyBatis 提供了一些默认的类型处理器，例如整数、字符串、日期等常见的数据类型，同时，开发人员可根据业务需要自定义类型处理器，实现特定类型的转换逻辑，比如你可以在自定义处理器中处理字段加密的逻辑；
注册类型处理器，自定义类型处理器需要在 MyBatis 配置文件中进行注册，这样MyBatis 在执行数据库操作时才能找到并使用它们；
支持复杂的类型，TypeHandler 不仅可以处理基本数据类型，还可以处理复杂类型，例如枚举、自定义对象等；

2.2 TypeHandler原理

还记得在使用jdbc操作数据库的时候，我们是如何设置一个查询的sql语句中的字段参数值的吗，没错，就是使用PrepareStatement对象中的set方法。

对mybatis原理有所了解的同学应该不陌生，其实mybatis框架就是对jdbc的完美封装。所以，mybatis使用 prepareStatement 进行参数设置的时候，需要通过 TypeHandler 将传入的java参数设置成合适的jdbc类型参数，这个过程实际上是通过调用 PrepareStatement 不同的set方法实现的。

String sql = "SELECT * tb_user where usernmae=? and pwd=?";
PreparedStatement pstmt = connection.prepareStatement(sql);
pstmt.setString(1, "jerry");
pstmt.setString(1, "root@321");
ResultSet rs = pstmt.executeQuery();

在获取到返回结果之后，也需要将返回的结果转换成需要的java数据类型，这时候是通过调用 ResultSet 对象不同类型的get方法实现的。比如我们在得到jdbc的结果集之后，会通过下面的方式获得某个字段的结果：

String id=rs.getString("id");
int number=rs.getInt("number");

所以不同类型的 TypeHandler 其实就是调用 PrepareStatement 和 ResultSet 的不同方法来进行类型的转换，有些时候会在调用 PrepareStatement 和 ResultSet 的相关方法之前，可以对传入的参数进行一定的处理.。

而当我们没有指定 TypeHandler 时，mybatis 会根据入参类型和返回值类型调用默认的 TypeHandler 进行处理。

对于一个 TypeHandler来说，需要配置 java类型(javaType) 和 JDBC类型(jdbcType)，TypeHandler 作用就是实现这两种类型的转换，在传入参数为指定的Java类型时，通过TypeHandler ，将其转换为指定的JDBC类型，当返回值为指定JDBC类型时，TypeHandler 再将其转换为配置的Java类型。

2.3 mybatis自带的TypeHandler

MyBatis 默认已经内置了一些常用的TypeHandler，大部分场景下无须显式声明 jdbcType 和 javaType，或者用 TypeHandler 去指定对应的字段来实现数据类型转换，因为 mybatis会自动探测待映射的数据类型，从而自动选择合适的 TypeHandler。下面列举了mybatis常用的TypeHandler

类型处理器	Java类型	JDBC类型
BooleanTypeHandler	java.lang.Boolean,boolean	数据库兼容的 BOOLEAN
ByteTypeHandler	java.lang.Byte, byte	数据库兼容的 NUMERIC 或 BYTE
ShortTypeHandler	java.lang.Short, short	数据库兼容的 NUMERIC 或 SHORT INTEGER
IntegerTypeHandler	java.lang.Integer, int	数据库兼容的 NUMERIC 或 INTEGER
LongTypeHandler	java.lang.Long, long	数据库兼容的 NUMERIC 或 LONG INTEGER
FloatTypeHandler	java.lang.Float, float	数据库兼容的 NUMERIC 或 FLOAT
DoubleTypeHandler	java.lang.Double,double	数据库兼容的 NUMERIC 或 DOUBLE
BigDecimalTypeHandler	java.math.BigDecimal	数据库兼容的 NUMERIC 或 DECIMAL
StringTypeHandler	java.lang.String	CHAR, VARCHAR
ClobReaderTypeHandler	java.io.Reader	-
ClobTypeHandler	java.lang.String	CLOB, LONGVARCHAR
NStringTypeHandler	java.lang.String	NVARCHAR, NCHAR
NClobTypeHandler	java.lang.String	NCLOB
BlobInputStreamTypeHandler	java.io.InputStream	-
ByteArrayTypeHandler	byte[]	数据库兼容的字节流类型
BlobTypeHandler	byte[]	BLOB, LONGVARBINARY
DateTypeHandler	java.util.Date	TIMESTAMP
DateOnlyTypeHandler	java.util.Date	DATE
TimeOnlyTypeHandler	java.util.Date	TIME
SqlTimestampTypeHandler	java.sql.Timestamp	TIMESTAMP
SqlDateTypeHandler	java.sql.Date	DATE
SqlTimeTypeHandler	java.sql.Time	TIME
ObjectTypeHandler	Any	OTHER 或未指定类型
EnumTypeHandler	Enumeration Type	VARCHAR-任何兼容的字符串类型，存储枚举的名称(而不是索引)
EnumOrdinalTypeHandler	Enumeration Type	任何兼容的 NUMERIC 或 DOUBLE 类型，存储枚举的索引(而不是名称)

三、环境准备

3.1 准备一张数据表

为了方便后面实验演示，这里准备一张数据表，建表sql如下

CREATE TABLE `tb_user` (`id` int(12) NOT NULL,`user_name` varchar(32) DEFAULT NULL,`pwd` varchar(64) DEFAULT NULL,`user_image` blob,`create_time` datetime DEFAULT NULL,PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

3.2 搭建一个springboot工程

技术栈，springboot+mybatis+mysql

3.2.1 基础依赖如下

    <parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>2.5.5</version><relativePath/> <!-- lookup parent from repository --></parent><dependencies><dependency><groupId>com.alibaba.fastjson2</groupId><artifactId>fastjson2</artifactId><version>2.0.23</version></dependency><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-test</artifactId><scope>test</scope></dependency><dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId></dependency><dependency><groupId>org.mybatis.spring.boot</groupId><artifactId>mybatis-spring-boot-starter</artifactId><version>2.2.2</version></dependency><dependency><groupId>com.alibaba</groupId><artifactId>druid-spring-boot-starter</artifactId><version>1.1.17</version></dependency><dependency><groupId>mysql</groupId><artifactId>mysql-connector-java</artifactId></dependency></dependencies><build><finalName>hook-service</finalName><plugins><plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId></plugin></plugins></build>

3.2.2 核心配置文件

主要是配置连接mysql与mybatis的配置

server:port: 8088spring:application:name: user-servicedatasource:url: jdbc:mysql://IP:3306/db-basedriverClassName: com.mysql.jdbc.Driverusername: rootpassword: rootmybatis:mapper-locations: classpath:mapper/*.xml#目的是为了省略resultType里的代码量type-aliases-package: com.congge.entityconfiguration:log-impl: org.apache.ibatis.logging.stdout.StdOutImpl

3.2.3 测试接口

@RestController
@RequestMapping("/user")
public class TbUserController {@Autowiredprivate TbUserService tbUserService;//http:localhost:8088/user/get?id=1@GetMapping("/get")public TbUser getById(@RequestParam int id){return tbUserService.getById(id);}}

业务实现逻辑比较简单就忽略了，最后在mybatis的查询文件中，一般建议配置一resultMap，在这个resultMap中，编写Java实体类属性与数据表的映射关系对应规则，而后面将要说到的自定义TypeHandler也将在这里进行配置，参考如下：

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "http://mybatis.org/dtd/mybatis-3-mapper.dtd" >
<mapper namespace="com.congge.dao.TbUserDao"><resultMap id="baseMap" type="com.congge.entity.TbUser"><id column="id" jdbcType="INTEGER" property="id" /><result column="user_name" jdbcType="VARCHAR" property="userName" /><result column="pwd" jdbcType="VARCHAR" property="pwd" /><result column="user_image" jdbcType="BLOB" property="userImage" /><result column="create_time" jdbcType="TIMESTAMP" property="createTime" /></resultMap><select id="getById" resultMap="baseMap">select * from tb_user where id = #{id}</select>
</mapper>

启动工程后，测试一下接口，可以看到直接报错了

为什么会出现这个问题呢？这该如何处理呢？

四、TypeHandler在项目中的使用

4.1 时间类型转换问题

在上面的接口测试中，发现接口返回的时间类型并不是我们想要的，遇到这个问题，就是数据库的字段类型与java中的时间字段类型不匹配，或者说无法通过默认的TypeHandler进行转换了，该如何解决呢？

4.1.1 添加自定义TypeHandler

自定义一个TypeHandler类，只需要继承BaseTypeHandler类，然后重写里面的setNonNullParameter和getNullableResult方法，在重写的方法里面编写相关的业务逻辑即可。

import org.apache.ibatis.type.*;import java.sql.*;/*** 自定义类型转换：将数据库中的日期类型，转换成long类型的时间戳** 三种注册方式：* 1.直接在 result标签中，指定typeHandler，如@Result(property = "createTime", column = "create_time", jdbcType = JdbcType.TIMESTAMP, typeHandler = Timestamp2LongHandler.class)* 2.在SqlSessionFactory实例中，注册 在SqlSessionFactory实例中.setTypeHandlers(new Timestamp2LongHandler());* 3.mapper 的xml配置，<typeHandler handler="com.congge.handler.Timestamp2LongHandler"/>*/
@MappedTypes(value = Long.class)
@MappedJdbcTypes(value = {JdbcType.DATE, JdbcType.TIME, JdbcType.TIMESTAMP})
public class Timestamp2LongHandler extends BaseTypeHandler<Long> {/*** 将java类型，转换为jdbc类型** @param preparedStatement* @param i* @param aLong             毫秒时间戳* @param jdbcType          db字段类型* @throws SQLException*/@Overridepublic void setNonNullParameter(PreparedStatement preparedStatement, int i, Long aLong, JdbcType jdbcType) throws SQLException {if (jdbcType == JdbcType.DATE) {preparedStatement.setDate(i, new Date(aLong));} else if (jdbcType == JdbcType.TIME) {preparedStatement.setTime(i, new Time(aLong));} else if (jdbcType == JdbcType.TIMESTAMP) {preparedStatement.setTimestamp(i, new Timestamp(aLong));}}@Overridepublic Long getNullableResult(ResultSet resultSet, String s) throws SQLException {return parse2time(resultSet.getObject(s));}@Overridepublic Long getNullableResult(ResultSet resultSet, int i) throws SQLException {return parse2time(resultSet.getObject(i));}@Overridepublic Long getNullableResult(CallableStatement callableStatement, int i) throws SQLException {return parse2time(callableStatement.getObject(i));}private Long parse2time(Object value) {if (value instanceof Date) {return ((Date) value).getTime();} else if (value instanceof Time) {return ((Time) value).getTime();} else if (value instanceof Timestamp) {return ((Timestamp) value).getTime();}return null;}
}

对自定义的TypeHandler类，对类上的两个注解做如下补充说明：

@MappedJdbcTypes，代表对应的数据库中字段的类型；
@MappedTypes，代表要转换后的的JavaBean中的属性（对象）类型；

4.1.2 添加扫描

当一个自定义的TypeHandler编写完成后，如何生效并被使用呢？在上述代码的注释中，其实给出了好几种方式，一般比较常用的像注册到bean中，或者配置到mybatis的全局配置文件中，这里提供另一种方式，就是直接在application.yaml中配置一下扫描路径也可以。（最后一行）

mybatis:mapper-locations: classpath:mapper/*.xml#目的是为了省略resultType里的代码量type-aliases-package: com.congge.entityconfiguration:log-impl: org.apache.ibatis.logging.stdout.StdOutImpltype-handlers-package: com.congge.handler

4.1.3 xml配置字段引用自定义TypeHandler

然后再在上述的UserMapper.xml文件中，在resultMap中的createTime字段映射上引用上述的TypeHandler

<resultMap id="baseMap" type="com.congge.entity.TbUser"><id column="id" jdbcType="INTEGER" property="id" /><result column="user_name" jdbcType="VARCHAR" property="userName" /><result column="pwd" jdbcType="VARCHAR" property="pwd" /><result column="user_image" jdbcType="BLOB" property="userImage" /><result column="create_time" jdbcType="TIMESTAMP" property="createTime" /><result property="createTime" column="create_time" typeHandler="com.congge.handler.Timestamp2LongHandler"/></resultMap>

4.1.4 接口效果测试

以上配置完成后，再次启动工程调用接口，此时可以看到返回的时间可以正确的被转换为Long类型

4.1.5 新增数据

如果是新增数据时，由于在自定义TypeHandler已经对传入数据库的时间字段进行了转换处理，所以按照下面的操作即可。

public int save(TbUser tbUser) {Integer count = tbUserDao.selectCount();Integer id = count+1;tbUser.setId(count+1);tbUser.setCreateTime(System.currentTimeMillis());tbUserDao.save(tbUser);return id;
}

再在xml文件的sql里面，针对createTime字段添加自定义的TypeHandler

<insert id="save">insert into tb_user(id,user_name,pwd,user_image,create_time) values(#{id},#{userName},#{pwd},#{userImage},#{createTime,javaType=Long,jdbcType=TIMESTAMP,typeHandler=com.congge.handler.Timestamp2LongHandler})</insert>

然后调用数据插入接口时，就能正常的被解析为数据库的TIMESTAMP类型

4.2 常用的TypeHandler

在真实的业务场景中，涉及到需要进行转换的字段类型可能非常多，下面总结了一些常用的开发中使用到的数据类型转换的自定义TypeHandler。

4.2.1 List<String>类型的处理

当处理 List 类型时，可使用自定义的TypeHandler 将 List 对象转换为字符串存储，或者从数据库中读取字符串并还原为 List 对象。

比如在一个用户表中，关联了多个角色，这个角色字段relate_roles，存储多个数据时以","分割，而在用户BizUser对象中，包含了一个List<String>类型的属性与relate_roles对应，我们就可以自定义一个handler来实现入库时和查询映射到对象属性时的转换。

mysql建表语句

CREATE TABLE `biz_user` (`id` int(12) NOT NULL,`user_name` varchar(32) DEFAULT NULL,`relate_roles` varchar(132) DEFAULT NULL,PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

自定义以TypeHandler类，代码如下

import org.apache.ibatis.type.BaseTypeHandler;import java.sql.PreparedStatement;
import java.util.Arrays;
import java.util.Collections;
import java.util.List;import org.apache.ibatis.type.*;import java.sql.*;//@MappedTypes(value = Long.class)
//@MappedJdbcTypes(value = {JdbcType.DATE, JdbcType.TIME, JdbcType.TIMESTAMP})public class StringListTypeHandler extends BaseTypeHandler<List<String>> {private static final String DELIMITER = ",";@Overridepublic void setNonNullParameter(PreparedStatement ps, int i, List<String> parameter, JdbcType jdbcType) throws SQLException {// 将 List<String> 转换为以逗号分隔的字符串String rolesString = String.join(DELIMITER, parameter);ps.setString(i, rolesString);}@Overridepublic List<String> getNullableResult(ResultSet rs, String columnName) throws SQLException {// 从 ResultSet 中获取字符串值String rolesString = rs.getString(columnName);// 转换为 List<String>return parseRolesString(rolesString);}@Overridepublic List<String> getNullableResult(ResultSet rs, int columnIndex) throws SQLException {String rolesString = rs.getString(columnIndex);return parseRolesString(rolesString);}@Overridepublic List<String> getNullableResult(CallableStatement cs, int columnIndex) throws SQLException {String rolesString = cs.getString(columnIndex);return parseRolesString(rolesString);}private List<String> parseRolesString(String rolesString) {if (rolesString == null || rolesString.isEmpty()) {return Collections.emptyList();}return Arrays.asList(rolesString.split(DELIMITER));}
}

最后在mybatis的配置文件中做一下配置即可

<resultMap id="baseMap" type="com.congge.entity.BizUser"><id column="id" jdbcType="INTEGER" property="id" /><result column="user_name" jdbcType="VARCHAR" property="userName" /><result column="relate_roles" jdbcType="VARCHAR" property="relateRoles" typeHandler="com.congge.handler.StringListTypeHandler" /></resultMap>

接口测试，提前在数据库中准备一条数据，然后通过接口调用，可以看到下面的效果，说明成功转换

4.2.2 枚举类型的处理

假设我们有一个用户的实体类对象 BizUser，其中包含一个 SexEnum枚举类型的状态字段，在数据库中，我们将状态字段存储为一个字符串类型的列，例如 gender

@Getter
public enum SexEnum {MALE(1, "男"),FEMALE(0, "女");private int id;private String name;SexEnum(int id, String name) {this.id = id;this.name = name;}public static SexEnum getSexById(int id) {for (SexEnum sex : SexEnum.values()) {if (sex.getId() == id) {return sex;}}return null;}}

实体类

@Getter
@Setter
public class BizUser {private int id;private String userName;private List<String>  relateRoles;private SexEnum sex;}

可以使用自定义 TypeHandler 来处理 UserStatus枚举类型与数据库列值之间的转换，参考如下示例的 TypeHandler 实现

public class SexEnumTypeHandler extends BaseTypeHandler<SexEnum> {@Overridepublic SexEnum getNullableResult(ResultSet rs, String columnName) throws SQLException {// 从 ResultSet 中获取列值int data = rs.getInt(columnName);// 将列值转换为枚举对象return SexEnum.getSexById(data);}@Overridepublic SexEnum getNullableResult(ResultSet rs, int columnIndex) throws SQLException {int data = rs.getInt(columnIndex);return SexEnum.getSexById(data);}@Overridepublic SexEnum getNullableResult(CallableStatement callableStatement, int columnIndex) throws SQLException {int data = callableStatement.getInt(columnIndex);return SexEnum.getSexById(data);}@Overridepublic void setNonNullParameter(PreparedStatement preparedStatement, int i, SexEnum status, JdbcType jdbcType) throws SQLException {// 将枚举值的code存储到数据库中preparedStatement.setInt(i, status.getId());}
}

4.2.3 json类型的处理

假如在biz_user表中有一个描述的信息json，是BizUser对象关联的一个对象存储进来的，如下：BizUser对象中持有一个Content的对象引用

@Getter
@Setter
public class BizUser {private int id;private String userName;private List<String>  relateRoles;private SexEnum sex;private Content content;
}

Content对象

@Getter
@Setter
public class Content {private String desc;private String level;private String hit;
}

对应的数据表如下

CREATE TABLE `biz_user` (`id` int(12) NOT NULL,`user_name` varchar(32) DEFAULT NULL,`relate_roles` varchar(132) DEFAULT NULL,`gender` int(1) DEFAULT NULL,`content` json DEFAULT NULL,PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

要完成这样一个场景下字段到实体对象的映射，可以参考下面的做法，自定义一个ObjectJSONTypeHandler

import com.congge.entity.Content;
import com.google.gson.Gson;
import org.apache.ibatis.type.BaseTypeHandler;
import org.apache.ibatis.type.JdbcType;import java.sql.CallableStatement;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;public class ObjectJSONTypeHandler extends BaseTypeHandler<Content> {private Gson gson = new Gson();@Overridepublic void setNonNullParameter(PreparedStatement ps, int i, Content parameter, JdbcType jdbcType) throws SQLException {ps.setString(i, gson.toJson(parameter));}@Overridepublic Content getNullableResult(ResultSet rs, String columnName) throws SQLException {return gson.fromJson(rs.getString(columnName), Content.class);}@Overridepublic Content getNullableResult(ResultSet rs, int columnIndex) throws SQLException {return gson.fromJson(rs.getString(columnIndex), Content.class);}@Overridepublic Content getNullableResult(CallableStatement cs, int columnIndex) throws SQLException {return gson.fromJson(cs.getString(columnIndex), Content.class);}
}

最后再在mybatis的映射文件中将自定义TypeHandler加进去即可

<resultMap id="baseMap" type="com.congge.entity.BizUser"><id column="id" jdbcType="INTEGER" property="id" /><result column="user_name" jdbcType="VARCHAR" property="userName" /><result column="relate_roles" jdbcType="VARCHAR" property="relateRoles" typeHandler="com.congge.handler.StringListTypeHandler" /><result column="gender" jdbcType="INTEGER" property="sex" typeHandler="com.congge.handler.SexEnumTypeHandler" /><result column="content" property="content" typeHandler="com.congge.handler.ObjectJSONTypeHandler" /></resultMap>

测试一下接口可以看到下面的效果