Mybatis源码之美:2.14.解析Mybatis的typeHandlers元素，配置Mybatis的类型转换器

解析Mybatis的typeHandlers元素，配置Mybatis的类型转换器

在学习本章内容之前，可以通过类型转换器（typeHandlers）来了解关于TypeHandler的用法。

示例

为了更好的理解mybatis的TypeHandler对象，我们在测试包org.apache.learning下，新建一个typehandler包，该包下的所有数据，均用于演示TypeHandler对象的用法。

首先我们在包下新建一个CreateDB.sql的脚本文件：

drop table users if exists;
create table users
(
    id     varchar(36),
    name   varchar(20),
    gender varchar(6)

);

insert into users (id, name,gender) values ('38400000-8cf0-11bd-b23e-10b96e4ef00d', 'Panda', '男');

该脚本用于创建一个users表，并插入一条数据以供使用。

之后我们新建一个mybatis-config.xml文件，该文件用于为mybatis提供一个基本的数据源环境配置：

然后创建一个名为EUserGender的枚举对象：

/**
 * 用户性别
 *
 * @author HanQi [[email protected]]
 * @version 1.0
 * @since 2020/3/14 10:47
 */
@Getter
@AllArgsConstructor
public enum EUserGender {
    MALE("男"), FEMALE("女");
    private String name;
}

并为EUserGender创建一个专属的TypeHandler——EUserGenderTypeHandler:

public class EUserGenderTypeHandler extends BaseTypeHandler {

    @Override
    public void setNonNullParameter(PreparedStatement ps, int i, EUserGender parameter, JdbcType jdbcType) throws SQLException {
        ps.setString(i, parameter.getName());
    }

    @Override
    public EUserGender getNullableResult(ResultSet rs, String columnName) throws SQLException {
        String columnValue = rs.getString(columnName);

        return findEUserGender(columnValue);
    }

    @Override
    public EUserGender getNullableResult(ResultSet rs, int columnIndex) throws SQLException {
        String columnValue = rs.getString(columnIndex);
        return findEUserGender(columnValue);
    }

    @Override
    public EUserGender getNullableResult(CallableStatement cs, int columnIndex) throws SQLException {
        String columnValue = cs.getString(columnIndex);
        return findEUserGender(columnValue);
    }

    private EUserGender findEUserGender(String dbName) {
        return Stream.of(EUserGender.values())
                .filter(g -> g.getName().equals(dbName))
                .findFirst()
                .orElse(null);
    }
}

再新建一个名为User的实体对象,对象中的属性定义和创建的users表中的列保持一致：

@Getter
@Setter
@NoArgsConstructor
public class User {
    private String id;
    private String name;
    private EUserGender gender;
}

紧接着新建一个Mapper接口，该接口定义了操作User对象的两个方法：

public interface Mapper {
    List selectByGender(EUserGender gender);

    List selectByGenderWithoutSpecify(EUserGender gender);
}

以及Mapper对应的xml文件——Mapper.xml：

    
        
        
        
        
    

    
    
        select *
        from users
        where gender = #{gender, typeHandler=org.apache.learning.typehandler.EUserGenderTypeHandler}
    

    
    
        select *
        from users
        where gender = #{gender}
    

其中selectByGender()的方法针对gender属性明确指定了EUserGenderTypeHandler作为类型转换器，selectByGenderWithoutSpecify()方法只是一个普通的方法定义。

完成上述的基础数据的准备之后，新建一个名为typeHanlderTest的单元测试类,测试常见的三种场景：

/**
 * 类型转换器测试类
 *
 * @author HanQi [[email protected]]
 * @version 1.0
 * @since 2020/3/14 10:45
 */
public class TypeHandlerTest {
    private static SqlSessionFactory sqlSessionFactory;

    @BeforeEach
    @SneakyThrows
    public void setup() {
        @Cleanup
        Reader reader = Resources.getResourceAsReader("org/apache/learning/typehandler/mybatis-config.xml");
        sqlSessionFactory = new SqlSessionFactoryBuilder().build(reader);
        sqlSessionFactory.getConfiguration().addMapper(Mapper.class);
        BaseDataTest.runScript(sqlSessionFactory.getConfiguration().getEnvironment().getDataSource(), "org/apache/learning/typehandler/CreateDB.sql");
    }

    /**
     * 声明语句时，指定类型转换器
     */
    @Test
    public void testForCustomTypeHandler() {
        // 执行准备工作
        @Cleanup
        SqlSession sqlSession = sqlSessionFactory.openSession();
        // 执行
        Mapper mapper = sqlSession.getMapper(Mapper.class);
        List users = mapper.selectByGender(EUserGender.MALE);
        Assertions.assertEquals("Panda", users.get(0).getName());


    }

    /**
     * 普通方法且无类型转换器
     */
    @Test
    public void testForCustomTypeHandlerWithoutSpecify() {
        // 执行准备工作
        @Cleanup
        SqlSession sqlSession = sqlSessionFactory.openSession();

        // 执行
        Mapper mapper = sqlSession.getMapper(Mapper.class);
        List users = mapper.selectByGenderWithoutSpecify(EUserGender.MALE);
        Assertions.assertTrue(users.isEmpty());
    }

    /**
     * 测试普通方法触发全局类型转换器
     */
    @Test
    public void testForCustomTypeHandlerWithoutSpecifyNeedSuccess() {
        // 注册全局的类型转换器
        sqlSessionFactory.getConfiguration().getTypeHandlerRegistry().register(EUserGenderTypeHandler.class);

        // 执行准备工作
        @Cleanup
        SqlSession sqlSession = sqlSessionFactory.openSession();

        // 执行
        Mapper mapper = sqlSession.getMapper(Mapper.class);
        List users = mapper.selectByGenderWithoutSpecify(EUserGender.MALE);
        Assertions.assertEquals("Panda", users.get(0).getName());
    }
}

毫无疑问，上面的单元测试都能正常运行，这也就意味着我们自定义的TypeHandler生效了,那么TypeHandler到底是一个怎样的东西呢？

类型转换器——TypeHandler

TypeHandler是myabtis中定义的负责jdbc类型和java类型互相转换的策略接口，我称之为类型转换器。

TypeHandler接口有一个泛型参数定义，这个泛型参数就是要处理的java类型，该定义还约束了标准的类型转换器需要提供下列四种方法：

• 根据参数索引和jdbc类型设置PreparedStatement语句中的值,即将?替换为实际值的setParameter(PreparedStatement,int,T,JdbcType).
• 获取指定ResultSet中指定名称的列对应的值，并转换为相应的JAVA类型的getResult(ResultSet,String)。
• 获取指定ResultSet中指定索引下面的列对应的值，并转换为相应的JAVA类型的getResult(ResultSet,int)。
• 获取指定存储过程(CallableStatement)中指定索引下标对应的值，并转换为相应的JAVA类型的getResult(CallableStatement,int。

/**
 * 类型转换处理器
 *
 * @author Clinton Begin
 */
public interface TypeHandler {

    /**
     *  根据参数索引和jdbc类型设置PreparedStatement语句中的值,即将? 替换为实际值。
     *
     * @param ps        PreparedStatement 语句
     * @param i         参数索引
     * @param parameter 参数
     * @param jdbcType  jdbc类型
     * @throws SQLException SQL异常
     */
    void setParameter(PreparedStatement ps, int i, T parameter, JdbcType jdbcType) throws SQLException;

    /**
     * 获取指定ResultSet中指定名称的列对应的值，并转换为相应的JAVA类型
     *
     * @param rs         ResultSet
     * @param columnName 列名称
     * @return 值
     * @throws SQLException SQL异常
     */
    T getResult(ResultSet rs, String columnName) throws SQLException;

    /**
     * 获取指定ResultSet中指定索引下面的列对应的值，并转换为相应的JAVA类型
     *
     * @param rs          ResultSet
     * @param columnIndex 列索引
     * @return 值
     * @throws SQLException SQL异常
     */
    T getResult(ResultSet rs, int columnIndex) throws SQLException;

    /**
     * 获取指定存储过程(CallableStatement)中指定索引下标对应的值，并转换为相应的JAVA类型
     *
     * @param cs          存储过程
     * @param columnIndex 列索引
     * @return 值
     * @throws SQLException SQL异常
     */
    T getResult(CallableStatement cs, int columnIndex) throws SQLException;

}

为了简化我们的操作，Mybatis定义了一个名为BaseTypeHandler的抽象类，实现了TypeHandler接口，他是Mybatis提供的一个默认的类型转换器的基类。

public abstract class BaseTypeHandler extends TypeReference implements TypeHandler {

    /**
     * Mybatis配置
     *
     * @deprecated Since 3.5.0 - See https://github.com/mybatis/mybatis-3/issues/1203. This field will remove future.
     */
    @Deprecated
    protected Configuration configuration;

    /**
     * @deprecated Since 3.5.0 - See https://github.com/mybatis/mybatis-3/issues/1203. This property will remove future.
     */
    @Deprecated
    public void setConfiguration(Configuration c) {
        this.configuration = c;
    }

    /**
     * @param ps        PreparedStatement
     * @param i         参数索引
     * @param parameter 参数值
     * @param jdbcType  jdbc类型
     */
    @Override
    public void setParameter(PreparedStatement ps, int i, T parameter, JdbcType jdbcType) throws SQLException {
        if (parameter == null) {
            if (jdbcType == null) {
                throw new TypeException("JDBC requires that the JdbcType must be specified for all nullable parameters.");
            }
            try {
                ps.setNull(i, jdbcType.TYPE_CODE);
            } catch (SQLException e) {
                throw new TypeException("Error setting null for parameter #" + i + " with JdbcType " + jdbcType + " . " +
                        "Try setting a different JdbcType for this parameter or a different jdbcTypeForNull configuration property. " +
                        "Cause: " + e, e);
            }
        } else {
            try {
                setNonNullParameter(ps, i, parameter, jdbcType);
            } catch (Exception e) {
                throw new TypeException("Error setting non null for parameter #" + i + " with JdbcType " + jdbcType + " . " +
                        "Try setting a different JdbcType for this parameter or a different configuration property. " +
                        "Cause: " + e, e);
            }
        }
    }

    @Override
    public T getResult(ResultSet rs, String columnName) throws SQLException {
        try {
            return getNullableResult(rs, columnName);
        } catch (Exception e) {
            throw new ResultMapException("Error attempting to get column '" + columnName + "' from result set.  Cause: " + e, e);
        }
    }

    @Override
    public T getResult(ResultSet rs, int columnIndex) throws SQLException {
        try {
            return getNullableResult(rs, columnIndex);
        } catch (Exception e) {
            throw new ResultMapException("Error attempting to get column #" + columnIndex + " from result set.  Cause: " + e, e);
        }
    }

    @Override
    public T getResult(CallableStatement cs, int columnIndex) throws SQLException {
        try {
            return getNullableResult(cs, columnIndex);
        } catch (Exception e) {
            throw new ResultMapException("Error attempting to get column #" + columnIndex + " from callable statement.  Cause: " + e, e);
        }
    }

    public abstract void setNonNullParameter(PreparedStatement ps, int i, T parameter, JdbcType jdbcType) throws SQLException;

    public abstract T getNullableResult(ResultSet rs, String columnName) throws SQLException;

    public abstract T getNullableResult(ResultSet rs, int columnIndex) throws SQLException;

    public abstract T getNullableResult(CallableStatement cs, int columnIndex) throws SQLException;
}

BaseTypeHandler实现了TypeHandler接口定义的默认方法，添加了基本的数据校验，并暴露出了新的抽象方法供子类实现。

虽然他还添加了对Mybatis配置类Configuration的引用，并提供了对应的设值方法，但是这一功能已被弃用，所以这里就不在讨论。

获取泛型定义原始类型——TypeReference

除此之外,BaseTypeHandler还继承了TypeReference抽象类，提供了获取泛型定义原始类型的能力。

public abstract class TypeReference {

    /**
     * TypeReference 中T的泛型类型
     */
    private final Type rawType;

    protected TypeReference() {
        // 获取当前类的泛型类型
        rawType = getSuperclassTypeParameter(getClass());
    }
    // ... 省略 getSuperclassTypeParameter() 方法
}

TypeReference抽象类中提供了一个Type类型的rawType属性，并对外了暴露了该属性的getter方法，该属性的作用是保存类上泛型定义的类型，他的初始化工作是在TypeReference的构造方法中完成的。

有关于泛型解析相关的知识，我们在介绍TypeParameterResolver时已经做了很完整的分析，这里就不在赘述。

我们自己定义的EUserGenderTypeHandler就继承了BaseTypeHandler基类，并通过泛型参数指定了要处理的java类型是EUserGender。

存储类型转换器的注册表——TypeHandlerRegistry

在简单的了解了TypeHandler之后，我们回过头来继续看TypeHandlerRegistry。

Tips:
我想换一种方式来描述对象的功能和实现，之前描述一个类的源码时，都是站在程序员的角度去想，去写，按照方法调用栈来解析源代码。现在我想站在产品的角度来解析代码，
先给出实例存在的目的和宗旨，并围绕着这个目的和宗旨，逐步的扩展出代码。

TypeHandlerRegistry的作用

TypeHandlerRegistry作为存储类型转换器的注册表，他存在的目的就是为了保存所有类型转换器，并提供相应的注册和获取类型转换器的功能。

编程是一件开放性很高的事情，一千个人眼中就有一千个哈姆雷特，一千个程序员对于同一个功能可能有不止一万种实现方案。

所以在接下来我们会根据需求去梳理TypeHandlerRegistry的实现，而不是去重新实现一个新的TypeHandlerRegistry。

TypeHandlerRegistry的属性定义

首先我们看一下TypeHandlerRegistry中的属性定义:

/**
 * jdbc类型和处理器的映射关系
 */
private final Map> JDBC_TYPE_HANDLER_MAP = new EnumMap<>(JdbcType.class);
/**
 * java类型和映射处理器的关系
 */
private final Map>> TYPE_HANDLER_MAP = new ConcurrentHashMap<>();
/**
 * 未知类型的对应的默认处理器
 */
private final TypeHandler