MyBatis 如何映射 Enum（使用 EnumTypeHandler、自定义 TypeHandler）

前置博客：Java中枚举是什么？枚举（Enumeration, 简称 Enum）是 Java 中一种特殊的数据类型，用于定义一组常量。它提供了一种更具语义的方式来表示和处理固定集合的值，避免了魔法数字或字符串。

1. MyBatis 中的 Enum 映射概述

Enum 的概念

在 Java 中，Enum 是一种特殊的类，用于定义常量集合。每个 Enum 实例都是该类的一个常量，具备固定的值和方法。

public enum Status {
    ACTIVE, INACTIVE, DELETED;
}

为什么需要在 MyBatis 中处理 Enum

ORM（对象关系映射）框架的核心目标是将数据库中的关系模型映射到 Java 对象。然而，数据库中的字段通常使用整数或字符串类型来表示状态或类型，而在 Java 代码中，我们常常使用 Enum 来提高代码的可读性和可维护性。因此，如何将 Enum 与数据库字段映射，是 MyBatis 中不可避免的问题。

Enum 映射在数据库设计中的意义

枚举类型通常用于表示有限集合的状态或分类。例如，数据库中一个状态字段可能以整数 1 表示“激活”，0 表示“禁用”。而在 Java 代码中，我们更希望通过 Enum（如 Status.ACTIVE 或 Status.INACTIVE）来处理这些状态。

2. 使用 EnumTypeHandler

MyBatis 自带了 EnumTypeHandler，用于将 Java 枚举类型映射到数据库字段。这个处理器可以自动将 Enum 类型与数据库字段进行映射，无需开发者编写额外的处理逻辑。

EnumTypeHandler 映射整数与字符串

EnumTypeHandler 支持两种映射方式：

• 将 Enum 的 name() 方法返回的字符串值映射到数据库的 VARCHAR 字段。
• 将 Enum 的 ordinal() 值（枚举项的顺序，从 0 开始）映射到数据库的整数字段。

2.1 代码示例：将 Enum 映射为字符串

以下是将 Status 枚举映射为数据库中 VARCHAR 字段的例子：

public enum Status {
    ACTIVE, INACTIVE, DELETED;
}

在 MyBatis 的映射文件中，我们可以这样配置：

<select id="selectStatusById" resultType="Status">
    SELECT status FROM users WHERE id = #{id}
</select>

当数据库中存储的值为 "ACTIVE" 时，MyBatis 会将其映射为 Status.ACTIVE。

2.2 代码示例：将 Enum 映射为整数

如果数据库中存储的 status 是整数类型（例如：0 表示 ACTIVE，1 表示 INACTIVE），则 MyBatis 通过 ordinal() 方法实现：

<select id="selectStatusById" resultType="Status">
    SELECT status FROM users WHERE id = #{id}
</select>

需要注意的是，使用 ordinal() 存在风险，如果 Enum 发生改动（如插入新常量），可能导致映射出错。因此，更推荐使用字符串映射。

2.3 如何配置 EnumTypeHandler

EnumTypeHandler 是 MyBatis 的默认处理器，因此我们不需要额外配置。当需要自定义映射行为时，可以在 mybatis-config.xml 中显式声明：

<typeHandlers>
    <typeHandler handler="org.apache.ibatis.type.EnumTypeHandler" javaType="com.example.Status"/>
</typeHandlers>

也可以通过注解方式：

@Result(property = "status", column = "status", typeHandler = EnumTypeHandler.class)

3. 自定义 TypeHandler

3.1 为什么需要自定义 TypeHandler

有时，MyBatis 默认的 EnumTypeHandler 无法满足项目中的特定需求。例如，数据库中的枚举字段可能需要映射为更复杂的类型，或者 Enum 映射的逻辑需要根据业务规则进行调整。在这种情况下，自定义 TypeHandler 是更灵活的选择。

3.2 自定义 TypeHandler 的实现

假设我们需要将 Status 枚举映射为数据库中的自定义值，如：

• ACTIVE 映射为 "A"
• INACTIVE 映射为 "I"
• DELETED 映射为 "D"

我们可以创建自定义的 TypeHandler 来实现该映射逻辑：

public class StatusTypeHandler extends BaseTypeHandler<Status> {

    @Override
    public void setNonNullParameter(PreparedStatement ps, int i, Status parameter, JdbcType jdbcType) throws SQLException {
        ps.setString(i, parameter == Status.ACTIVE ? "A" : parameter == Status.INACTIVE ? "I" : "D");
    }

    @Override
    public Status getNullableResult(ResultSet rs, String columnName) throws SQLException {
        String status = rs.getString(columnName);
        return "A".equals(status) ? Status.ACTIVE : "I".equals(status) ? Status.INACTIVE : Status.DELETED;
    }

    @Override
    public Status getNullableResult(ResultSet rs, int columnIndex) throws SQLException {
        String status = rs.getString(columnIndex);
        return "A".equals(status) ? Status.ACTIVE : "I".equals(status) ? Status.INACTIVE : Status.DELETED;
    }

    @Override
    public Status getNullableResult(CallableStatement cs, int columnIndex) throws SQLException {
        String status = cs.getString(columnIndex);
        return "A".equals(status) ? Status.ACTIVE : "I".equals(status) ? Status.INACTIVE : Status.DELETED;
    }
}

在自定义 TypeHandler 中，getNullableResult 方法被重载了三次，以处理不同的情况。这三种重载方法的主要作用是从数据库中提取枚举值，并根据不同的输入源（列名、列索引或存储过程的输出参数）进行相应的映射。以下是它们各自的用途：

1. getNullableResult(ResultSet rs, String columnName)

   • 这个方法用于从 ResultSet 中通过列名获取枚举值。通常在 SQL 查询返回结果时，我们通过列名来提取数据。
   • 例如：如果查询结果中有一列名为 status，你可以通过 ResultSet 的 getString("status") 获取该列的值，并将其映射为枚举值。

2. getNullableResult(ResultSet rs, int columnIndex)

   • 这个方法用于从 ResultSet 中通过列索引获取枚举值。列索引是指返回的结果集中列的顺序，从 1 开始。
   • 这种方式更高效，尤其当你知道具体列的位置时，避免了列名查找的开销。例如，使用 rs.getString(1) 来获取第一列的值并将其映射为枚举值。

3. getNullableResult(CallableStatement cs, int columnIndex)

   • 这个方法用于处理从存储过程的输出参数中获取枚举值。CallableStatement 是用于调用存储过程的，存储过程有时会返回多个输出参数。该方法根据输出参数的索引获取值，并将其映射为枚举。
   • 例如，存储过程返回的 OUT 参数可以通过 CallableStatement 获取并映射为对应的枚举值。

• 方法重载（overloading）是为了应对不同的数据获取方式：通过列名、列索引或存储过程的输出参数。
• 这三种方式都可能在不同的场景中使用，因此 MyBatis 的 TypeHandler 提供了这些重载，以便开发者能灵活应对不同的数据库访问场景。

3.3 如何注册自定义 TypeHandler

在 MyBatis 配置中注册自定义 TypeHandler，可以通过以下方式：

<typeHandlers>
    <typeHandler handler="com.example.StatusTypeHandler" javaType="com.example.Status"/>
</typeHandlers>

注册完成后，MyBatis 会在映射 Status 类型时自动使用 StatusTypeHandler。

4. 注意事项

设计数据库字段类型

在设计数据库字段时，选择合适的数据类型至关重要。如果你的 Enum 很可能会随着业务需求的变化而增加新值，建议使用字符串存储枚举值，以避免使用整数时出现的顺序问题。

如何处理未知或新增的枚举值

当数据库中出现了 Java 枚举中不存在的值时，应该明确处理此类情况。可以通过在 TypeHandler 中添加默认值或抛出异常来处理不匹配的情况。

5. 总结

MyBatis 提供了多种映射枚举类型的方式，EnumTypeHandler 适合大多数情况，而自定义 TypeHandler 提供了更灵活的选项。开发者应根据项目的具体需求选择合适的映射策略，并确保 Enum 与数据库设计的一致性，以避免常见的问题。

通过代码示例和最佳实践的指导，我们可以更好地掌握如何在 MyBatis 中高效地处理枚举类型。