MyBatis使用教程 - 目录

4. 类型处理器（typeHandlers）

MyBatis使用教程

MyBatis 在设置预处理语句（PreparedStatement）中的参数或从结果集中取出一个值时， 都会用类型处理器将获取到的值以合适的方式转换成 Java 类型。下表描述了一些默认的类型处理器。

从 3.4.5 开始，MyBatis 默认支持 JSR-310（日期和时间 API）。

BooleanTypeHandler

  • 类型处理器: BooleanTypeHandler
  • Java 类型: java.lang.Boolean, boolean
  • JDBC 类型: 数据库兼容的 BOOLEAN

ByteTypeHandler

  • 类型处理器: ByteTypeHandler
  • Java 类型: java.lang.Byte, byte
  • JDBC 类型: 数据库兼容的 NUMERIC 或 BYTE

ShortTypeHandler

  • 类型处理器: ShortTypeHandler
  • Java 类型: java.lang.Short, short
  • JDBC 类型: 数据库兼容的 NUMERIC 或 SMALLINT

IntegerTypeHandler

  • 类型处理器: IntegerTypeHandler
  • Java 类型: java.lang.Integer, int
  • JDBC 类型: 数据库兼容的 NUMERIC 或 INTEGER

LongTypeHandler

  • 类型处理器: LongTypeHandler
  • Java 类型: java.lang.Long, long
  • JDBC 类型: 数据库兼容的 NUMERIC 或 BIGINT

FloatTypeHandler

  • 类型处理器: FloatTypeHandler
  • Java 类型: java.lang.Float, float
  • JDBC 类型: 数据库兼容的 NUMERIC 或 FLOAT

DoubleTypeHandler

  • 类型处理器: DoubleTypeHandler
  • Java 类型: java.lang.Double, double
  • JDBC 类型: 数据库兼容的 NUMERIC 或 DOUBLE

BigDecimalTypeHandler

  • 类型处理器: BigDecimalTypeHandler
  • Java 类型: java.math.BigDecimal
  • JDBC 类型: 数据库兼容的 NUMERIC 或 DECIMAL

StringTypeHandler

  • 类型处理器: StringTypeHandler
  • Java 类型: java.lang.String
  • JDBC 类型: CHAR, VARCHAR

ClobReaderTypeHandler

  • 类型处理器: ClobReaderTypeHandler
  • Java 类型: java.io.Reader
  • JDBC 类型: -

ClobTypeHandler

  • 类型处理器: ClobTypeHandler
  • Java 类型: java.lang.String
  • JDBC 类型: CLOB, LONGVARCHAR

NStringTypeHandler

  • 类型处理器: NStringTypeHandler
  • Java 类型: java.lang.String
  • JDBC 类型: NVARCHAR, NCHAR

NClobTypeHandler

  • 类型处理器: NClobTypeHandler
  • Java 类型: java.lang.String
  • JDBC 类型: NCLOB

BlobInputStreamTypeHandler

  • 类型处理器: BlobInputStreamTypeHandler
  • Java 类型: java.io.InputStream
  • JDBC 类型: -

ByteArrayTypeHandler

  • 类型处理器: ByteArrayTypeHandler
  • Java 类型: byte[]
  • JDBC 类型: 数据库兼容的字节流类型

BlobTypeHandler

  • 类型处理器: BlobTypeHandler
  • Java 类型: byte[]
  • JDBC 类型: BLOB, LONGVARBINARY

DateTypeHandler

  • 类型处理器: DateTypeHandler
  • Java 类型: java.util.Date
  • JDBC 类型: TIMESTAMP

DateOnlyTypeHandler

  • 类型处理器: DateOnlyTypeHandler
  • Java 类型: java.util.Date
  • JDBC 类型: DATE

TimeOnlyTypeHandler

  • 类型处理器: TimeOnlyTypeHandler
  • Java 类型: java.util.Date
  • JDBC 类型: TIME

SqlTimestampTypeHandler

  • 类型处理器: SqlTimestampTypeHandler
  • Java 类型: java.sql.Timestamp
  • JDBC 类型: TIMESTAMP

SqlDateTypeHandler

  • 类型处理器: SqlDateTypeHandler
  • Java 类型: java.sql.Date
  • JDBC 类型: DATE

SqlTimeTypeHandler

  • 类型处理器: SqlTimeTypeHandler
  • Java 类型: java.sql.Time
  • JDBC 类型: TIME

ObjectTypeHandler

  • 类型处理器: ObjectTypeHandler
  • Java 类型: Any
  • JDBC 类型: OTHER 或未指定类型

EnumTypeHandler

  • 类型处理器: EnumTypeHandler
  • Java 类型: Enumeration Type
  • JDBC 类型: VARCHAR 或任何兼容的字符串类型，用来存储枚举的名称（而不是索引序数值）

EnumOrdinalTypeHandler

  • 类型处理器: EnumOrdinalTypeHandler
  • Java 类型: Enumeration Type
  • JDBC 类型: 任何兼容的 NUMERIC 或 DOUBLE 类型，用来存储枚举的序数值（而不是名称）。

SqlxmlTypeHandler

  • 类型处理器: SqlxmlTypeHandler
  • Java 类型: java.lang.String
  • JDBC 类型: SQLXML

InstantTypeHandler

  • 类型处理器: InstantTypeHandler
  • Java 类型: java.time.Instant
  • JDBC 类型: TIMESTAMP

LocalDateTimeTypeHandler

  • 类型处理器: LocalDateTimeTypeHandler
  • Java 类型: java.time.LocalDateTime
  • JDBC 类型: TIMESTAMP

LocalDateTypeHandler

  • 类型处理器: LocalDateTypeHandler
  • Java 类型: java.time.LocalDate
  • JDBC 类型: DATE

LocalTimeTypeHandler

  • 类型处理器: LocalTimeTypeHandler
  • Java 类型: java.time.LocalTime
  • JDBC 类型: TIME

OffsetDateTimeTypeHandler

  • 类型处理器: OffsetDateTimeTypeHandler
  • Java 类型: java.time.OffsetDateTime
  • JDBC 类型: TIMESTAMP

OffsetTimeTypeHandler

  • 类型处理器: OffsetTimeTypeHandler
  • Java 类型: java.time.OffsetTime
  • JDBC 类型: TIME

ZonedDateTimeTypeHandler

  • 类型处理器: ZonedDateTimeTypeHandler
  • Java 类型: java.time.ZonedDateTime
  • JDBC 类型: TIMESTAMP

YearTypeHandler

  • 类型处理器: YearTypeHandler
  • Java 类型: java.time.Year
  • JDBC 类型: INTEGER

MonthTypeHandler

  • 类型处理器: MonthTypeHandler
  • Java 类型: java.time.Month
  • JDBC 类型: INTEGER

YearMonthTypeHandler

  • 类型处理器: YearMonthTypeHandler
  • Java 类型: java.time.YearMonth
  • JDBC 类型: VARCHAR 或 LONGVARCHAR

JapaneseDateTypeHandler

  • 类型处理器: JapaneseDateTypeHandler
  • Java 类型: java.time.chrono.JapaneseDate
  • JDBC 类型: DATE

你可以重写已有的类型处理器或创建你自己的类型处理器来处理不支持的或非标准的类型。 具体做法为：实现 org.apache.ibatis.type.TypeHandler 接口， 或继承一个很便利的类 org.apache.ibatis.type.BaseTypeHandler， 并且可以（可选地）将它映射到一个 JDBC 类型。比如：

// ExampleTypeHandler.java
@MappedJdbcTypes(JdbcType.VARCHAR)
public class ExampleTypeHandler extends BaseTypeHandler<String> {

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

  @Override
  public String getNullableResult(ResultSet rs, String columnName) throws SQLException {
    return rs.getString(columnName);
  }

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

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

<!-- mybatis-config.xml -->
<typeHandlers>
  <typeHandler handler="org.mybatis.example.ExampleTypeHandler"/>
</typeHandlers>

使用上述的类型处理器将会覆盖已有的处理 Java String 类型的属性以及 VARCHAR 类型的参数和结果的类型处理器。 要注意 MyBatis 不会通过检测数据库元信息来决定使用哪种类型，所以你必须在参数和结果映射中指明字段是 VARCHAR 类型， 以使其能够绑定到正确的类型处理器上。这是因为 MyBatis 直到语句被执行时才清楚数据类型。

通过类型处理器的泛型，MyBatis 可以得知该类型处理器处理的 Java 类型，不过这种行为可以通过两种方法改变：

  • 在类型处理器的配置元素（typeHandler 元素）上增加一个 javaType 属性（比如：javaType="String"）；
  • 在类型处理器的类上增加一个 @MappedTypes 注解指定与其关联的 Java 类型列表。 如果在 javaType 属性中也同时指定，则注解上的配置将被忽略。

可以通过两种方式来指定关联的 JDBC 类型：

  • 在类型处理器的配置元素上增加一个 jdbcType 属性（比如：jdbcType="VARCHAR"）；
  • 在类型处理器的类上增加一个 @MappedJdbcTypes 注解指定与其关联的 JDBC 类型列表。 如果在 jdbcType 属性中也同时指定，则注解上的配置将被忽略。

当在 ResultMap 中决定使用哪种类型处理器时，此时 Java 类型是已知的（从结果类型中获得），但是 JDBC 类型是未知的。 因此 Mybatis 使用 javaType=[Java 类型], jdbcType=null 的组合来选择一个类型处理器。 这意味着使用 @MappedJdbcTypes 注解可以限制类型处理器的作用范围，并且可以确保，除非显式地设置，否则类型处理器在 ResultMap 中将不会生效。 如果希望能在 ResultMap 中隐式地使用类型处理器，那么设置 @MappedJdbcTypes 注解的 includeNullJdbcType=true 即可。 然而从 Mybatis 3.4.0 开始，如果某个 Java 类型只有一个注册的类型处理器，即使没有设置 includeNullJdbcType=true，那么这个类型处理器也会是 ResultMap 使用 Java 类型时的默认处理器。

最后，可以让 MyBatis 帮你查找类型处理器：

<!-- mybatis-config.xml -->
<typeHandlers>
  <package name="org.mybatis.example"/>
</typeHandlers>

注意在使用自动发现功能的时候，只能通过注解方式来指定 JDBC 的类型。

你可以创建能够处理多个类的泛型类型处理器。为了使用泛型类型处理器， 需要增加一个接受该类的 class 作为参数的构造器，这样 MyBatis 会在构造一个类型处理器实例的时候传入一个具体的类。

//GenericTypeHandler.java
public class GenericTypeHandler<E extends MyObject> extends BaseTypeHandler<E> {

  private Class<E> type;

  public GenericTypeHandler(Class<E> type) {
    if (type == null) throw new IllegalArgumentException("Type argument cannot be null");
    this.type = type;
  }
  ...

EnumTypeHandler 和 EnumOrdinalTypeHandler 都是泛型类型处理器，我们将会在接下来的部分详细探讨。

章节目录