Master MyBatis TypeHandler: Elegant Enum Mapping and Custom Handlers

1. Scenario

In everyday Java development, numeric codes such as 0 or 1 are often used to represent statuses (e.g., 0 for female, 1 for male). To improve readability and eliminate magic numbers, developers typically define an enum and store its value in the database.

Typical enum definition and database mapping are illustrated below:

Insertion (pseudo‑code) and retrieval often involve additional conditional logic, which is not elegant.

Reading the value may require reverse processing or a SQL CASE WHEN clause.

2. MyBatis TypeHandler

If you use MyBatis as your ORM, the TypeHandler<T> interface can solve this problem. It converts between JDBC types and Java types.

2.1 TypeHandler

setParameter : Write data to the database using a PreparedStatement based on the provided Java type.

getResult(ResultSet rs, String columnName) : Read from the database by column name and convert to the Java type.

getResult(ResultSet rs, int columnIndex) : Read by column index.

getResult(CallableStatement cs, int columnIndex) : Retrieve results from stored procedures.

2.2 EnumOrdinalTypeHandler

This built‑in handler stores the enum’s ordinal (starting from 0). For example, GenderType.FEMALE → 0, GenderType.MALE → 1, and GenderType.UNKNOWN → 2. Retrieval reverses the process to the corresponding enum constant.

2.3 EnumTypeHandler

This handler stores the enum’s name() string. Using the same example, GenderType.FEMALE → "FEMALE", GenderType.MALE → "MALE", and GenderType.UNKNOWN → "UNKNOWN". Retrieval uses Enum.valueOf.

2.4 Custom TypeHandler

When built‑in handlers do not meet your needs, you can create a custom handler by extending BaseTypeHandler and implementing its three abstract methods.

Implementation skeleton:

2.5 Core Points of TypeHandler

A TypeHandler converts between a Java type and a JDBC type, so you must explicitly declare both when registering a handler. MyBatis does not infer the JDBC type from metadata; you need to specify @MappedJdbcTypes and @MappedTypes or use XML typeHandler elements. Avoid overriding built‑in handlers unintentionally.

2.6 No‑Registration TypeHandler (XML)

Common XML configurations allow you to use a TypeHandler without explicit registration.

Insert example:

2.7 Registration TypeHandler

For XML configuration, declare the handler inside <typeHandlers>. For Java configuration, register via SqlSessionFactory.getConfiguration().addTypeHandler or use Spring Boot’s mybatis.typeHandlersPackage property.

3. Summary

We have learned how to use MyBatis TypeHandler for enum conversion, how to choose between built‑in handlers, and how to implement and register custom handlers. The full source code is available at https://gitee.com/felord/mybatis-test.git .