如何通过Hibernate将数据库ENUM类型正确映射到Spring Data JPA实体

问题根因 #

Hibernate默认会将Java枚举按**序号（Byte类型）**映射到数据库，但你的数据库列是字符串类型的ENUM，导致读取时字符串值无法转成Byte，触发Value 'EQUIPOS' is outside of valid range for type java.lang.Byte错误。

解决方案 #

1. 使用JPA标准注解@Enumerated #

在实体类的枚举字段上添加@Enumerated(EnumType.STRING)，明确告诉JPA用枚举的字符串名称和数据库ENUM映射：

import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;
import javax.persistence.Enumerated;
import javax.persistence.EnumType;

@Entity
public class MyEntity {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    
    @Enumerated(EnumType.STRING)
    private TipoEnum tipo;

    // Getters and setters...
}

2. （可选）Hibernate专属注解@JdbcTypeCode（Hibernate 5.2+） #

如果需要更精细的控制，比如兼容不同数据库的ENUM类型，可以使用Hibernate的@JdbcTypeCode注解，指定SQL类型为Types.VARCHAR：

import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;
import org.hibernate.annotations.JdbcTypeCode;
import java.sql.Types;

@Entity
public class MyEntity {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    
    @JdbcTypeCode(Types.VARCHAR)
    private TipoEnum tipo;

    // Getters and setters...
}

额外注意事项 #

• 确保数据库列的ENUM值和Java枚举的名称完全一致（大小写敏感，比如数据库是EQUIPOS，Java枚举也要是EQUIPOS）
• 如果使用Spring Boot，无需额外配置，Hibernate会自动识别注解并处理映射
• 若已有数据，修改映射后需要确认数据类型兼容，避免数据迁移问题

内容的提问来源于stack exchange，提问作者EZZZ