枚举值怎么存进数据库:@Enumerated、Postgres 原生枚举类型与查找表

几乎每个领域模型都有一个只能取有限几个值的字段。一笔订单是 PENDING、PAID、SHIPPED、 DELIVERED 或 CANCELLED。一笔付款要么已授权要么已扣款。一份订阅处于四个套餐之一。 在 Java 里你会不假思索地伸手去拿 enum。有意思的问题在边界上——这组有限的值到底怎么 在数据库里安身,以及六个月后这组值发生变化时,每种方案各自要你付出什么。

本文按你实际会遇到的顺序,过一遍用 Hibernate 持久化枚举的每种常见方式:@Enumerated 的 两种模式、真正的 Postgres ENUM 类型、AttributeConverter,最后是让枚举自成一表的查找表 方案。我会用一个例子——订单状态——贯穿全程,最后给出我自己实际会做的选择。

技术栈:Java、Spring Boot、Hibernate、PostgreSQL。

TL;DR

  • @Enumerated(ORDINAL) 存的是枚举的位置——紧凑,但在中间插入值会悄悄污染之后的所有行。如果非用不可,用单元测试钉死序号。
  • @Enumerated(STRING) 存的是常量名——自描述、可调试、对重排序免疫。这是最理智的默认选择。
  • 别满足于裸 varchar——定义真正的 Postgres ENUM 类型,让数据库亲自拒绝非法值。
  • AttributeConverter 持久化一个与 Java 名称解耦的稳定代码,于是重命名不再是数据库问题。
  • 查找表只有在值携带可编辑业务数据时才值得——而不是作为应付重命名的权宜之计。

业务场景

我们在做订单管理。一笔订单沿着固定的生命周期流转:

stateDiagram-v2
    [*] --> PENDING
    PENDING --> PAID
    PENDING --> CANCELLED
    PAID --> SHIPPED
    SHIPPED --> DELIVERED
    PAID --> CANCELLED

在 Java 里这就是个显而易见的枚举:

public enum OrderStatus {
    PENDING,
    PAID,
    SHIPPED,
    DELIVERED,
    CANCELLED
}

订单实体上有个 status 字段。唯一的问题是 Hibernate 怎么把它映射到列——而这一注解选择 带来的后果,会比今天写下的代码活得更久。


第 1 部分 — @Enumerated(ORDINAL):按整数存

JPA 对枚举的默认值就是 ORDINAL。每个常量按声明时的位置存储:PENDING → 0, PAID → 1,SHIPPED → 2,依此类推。

@Entity
@Table(name = "orders_ordinal")
public class OrderOrdinal {

    @Id
    @GeneratedValue(strategy = GenerationType.UUID)
    private UUID id;

    @Enumerated(EnumType.ORDINAL)   // this is also the default if you omit @Enumerated
    @Column(nullable = false)
    private OrderStatus status;
}
CREATE TABLE orders_ordinal (
    id     UUID     PRIMARY KEY DEFAULT gen_random_uuid(),
    status SMALLINT NOT NULL
);

保存一笔状态为 PAID 的订单,列里存的是 1。紧凑,纸面上也说得过去。

❌ 陷阱:在中间插入一个值

序号存的不是标签,而是位置,而位置由源码顺序定义。某天有人在 PAID 和 SHIPPED 之间加入了一个打包环节:

public enum OrderStatus {
    PENDING,
    PAID,
    PACKED,      // <-- inserted here
    SHIPPED,
    DELIVERED,
    CANCELLED
}

……PAID 之后的每个常量都下移一位:

常量 插入前序号 插入后序号
PENDING 0 0
PAID 1 1
PACKED — 2
SHIPPED 2 3
DELIVERED 3 4
CANCELLED 4 5

数据库里什么都没变。每一条已存在的 SHIPPED 订单仍然存着整数 2——但 2 现在解码为 PACKED。已发货的订单悄悄变成已打包。已送达变成已发货。没有报错,没有失败的迁移, 没有日志行。数据没动,动的是你对它的解释。当客户来问为什么已送达的订单显示「打包中」 时,你才会发现。

防线:钉死序号

如果你有理由继续用 ORDINAL——遗留 schema、一张真正热点且巨大的表、字节差异确实重要—— 那就把「顺序不能动」这条约束显式化:写一个测试,一旦有人重排枚举,它立刻变红:

class OrdinalPinTest {

    @Test
    void ordinalsAreFrozen() {
        // If this test fails, you reordered OrderStatus. Existing ORDINAL-mapped rows now mean
        // something different. Revert the reorder, or append the new value at the end.
        assertThat(OrderStatus.PENDING.ordinal()).isZero();
        assertThat(OrderStatus.PAID.ordinal()).isEqualTo(1);
        assertThat(OrderStatus.SHIPPED.ordinal()).isEqualTo(2);
        assertThat(OrderStatus.DELIVERED.ordinal()).isEqualTo(3);
        assertThat(OrderStatus.CANCELLED.ordinal()).isEqualTo(4);
        assertThat(OrderStatus.values()).hasSize(5);
    }
}

这是一个纯单元测试——不需要 Spring 上下文,不需要数据库。一旦有人碰了枚举的顺序,它就 把一个不可见的数据污染 bug 立刻变成红色的构建。新值仍然可以加,只是必须加在末尾—— 追加在那里是安全的。这就是 ORDINAL 悄悄依赖的全部规则,把它写下来而已。


第 2 部分 — @Enumerated(STRING):按字符串存

对绝大多数人来说,解药只有一个词:

@Enumerated(EnumType.STRING)
@Column(nullable = false)
private OrderStatus status;

现在列里存的是常量名:

CREATE TABLE orders_string (
    id     UUID    PRIMARY KEY DEFAULT gen_random_uuid(),
    status VARCHAR NOT NULL
);

状态为 PAID 的订单存的是字面字符串 'PAID'。三件事立刻变好:

  • 重排无害。值就是它自己的名字;位置不再重要。PACKED 想加哪儿加哪儿。
  • 可调试。SELECT * FROM orders_string WHERE status = 'PAID' 一眼就能读懂。不需要解码环, 不需要在脑子里跟你的 Java 源码做 join。
  • 导出和日志自描述。CSV 导出里的一行数据自己就能说明问题。

是的,'DELIVERED' 比 3 多花几个字节。对绝大多数表来说这个差异是噪音——而且索引随时 可加。存名字才是正确的默认,「紧凑」几乎从来不值得「悄悄出错」。

仅剩的陷阱:重命名

STRING 消灭了顺序陷阱,但引入了一个更小的。存储的值就是 Java 标识符,所以重命名常量 会让已有行变成孤儿:

PENDING  →  AWAITING_PAYMENT

每一条老的 'PENDING' 行不再匹配任何常量,Hibernate 读到它们时会抛异常。存储的数据和 代码悄悄漂移了。你可以用一次数据迁移来修复 (UPDATE … SET status = 'AWAITING_PAYMENT' WHERE status = 'PENDING')——这是完全正当的 答案。第 4 部分还会看到一种让重命名彻底变成「无事发生」的办法。


第 3 部分 — 更进一步:真正的 Postgres 枚举类型

上面两种方案都是把值存进一个数据库并不真正理解的列——一个 smallint 或一个碰巧装着 枚举值的 varchar。Postgres 可以做得更好。它有一等公民的枚举类型:

CREATE TYPE order_status AS ENUM ('PENDING', 'PAID', 'SHIPPED', 'DELIVERED', 'CANCELLED');

CREATE TABLE orders_pgenum (
    id     UUID         PRIMARY KEY DEFAULT gen_random_uuid(),
    status order_status NOT NULL
);

现在由数据库来执行领域约束。一条 INSERT … VALUES ('SHPPED')——一个手误、一次糟糕的 迁移、一个失控的脚本——会在源头直接失败,报 invalid input value for enum order_status。 用裸 varchar 的话,这些垃圾会落进表里,你之后才会发现。枚举类型既是文档也是约束: 列的类型本身就列出了它的合法值。

在 Hibernate 里映射它和之前一样是 @Enumerated(STRING)——Hibernate 把常量名作为字符串 绑定,Postgres 把它存进枚举:

@Enumerated(EnumType.STRING)
@Column(nullable = false, columnDefinition = "order_status")
private OrderStatus status;

只有一处管道需要处理。默认情况下 PostgreSQL JDBC 驱动把 Java String 按 varchar 类型 发送,而 Postgres 不会隐式地把 varchar 强转成 order_status,于是你会得到 column "status" is of type order_status but expression is of type character varying。 在 JDBC URL 上加 stringtype=unspecified,驱动就会以 unknown 发送该值,让 Postgres 把它 强转成枚举:

spring:
  datasource:
    url: jdbc:postgresql://localhost:5434/mydatabase?stringtype=unspecified

(Hibernate 6 还提供 @JdbcTypeCode(SqlTypes.NAMED_ENUM) 来直接指向具名枚举类型;上面 @Enumerated(STRING) + stringtype=unspecified 的组合最常见,也是我自己会用的。)

唯一要知道的注意事项:ALTER TYPE order_status ADD VALUE 'PACKED' 只能追加。你可以 增加值(PostgreSQL 12 起甚至可以加在某个特定值的前面或后面),但不重建类型就无法删除或 重排已有值。这听起来像限制,直到你意识到它和序号测试强制执行的是同一条规则——永不 重排,只做追加——只不过这里由数据库来保证,而不是单元测试。约束本身就是特性。


第 4 部分 — AttributeConverter:把名称和存储值解耦

第 2 部分的重命名陷阱之所以存在,是因为我们让存储值和 Java 标识符成了同一个字符串。 JPA 的 AttributeConverter 打破这种耦合:你持久化的是一个与常量名毫无关系的稳定代码。

给每个常量一个显式、永久的代码:

public enum OrderStatus {

    PENDING("PND"),
    PAID("PAID"),
    SHIPPED("SHP"),
    DELIVERED("DLV"),
    CANCELLED("CNC");

    private final String code;

    OrderStatus(String code) {
        this.code = code;
    }

    public String getCode() {
        return code;
    }

    public static OrderStatus fromCode(String code) {
        return Arrays.stream(values())
                .filter(s -> s.code.equals(code))
                .findFirst()
                .orElseThrow(() -> new IllegalArgumentException("Unknown OrderStatus code: " + code));
    }
}

然后是一个在枚举 ↔ 代码之间互转的转换器:

@Converter
public class OrderStatusConverter implements AttributeConverter<OrderStatus, String> {

    @Override
    public String convertToDatabaseColumn(OrderStatus status) {
        return status == null ? null : status.getCode();
    }

    @Override
    public OrderStatus convertToEntityAttribute(String code) {
        return code == null ? null : OrderStatus.fromCode(code);
    }
}

再用 @Convert(而不是 @Enumerated)挂到字段上:

@Convert(converter = OrderStatusConverter.class)
@Column(nullable = false)
private OrderStatus status;

现在数据库把 'PAID' 当作代码存储,而不是标识符。把 Java 常量 PENDING 重命名为 AWAITING_PAYMENT,存储的代码 'PND' 纹丝不动——重命名变成一次零数据库影响的纯重构。 你把「数据库知道什么」和「你在代码里怎么称呼它」解耦了,而这恰恰是人们求助于查找表想要 得到的性质。带着这个结论进入下一部分。


第 5 部分 — 查找表方案

最后一种方案干脆不再把状态当作枚举。状态集合自成一表,订单通过外键引用其中一行:

CREATE TABLE order_statuses (
    id       INTEGER PRIMARY KEY,
    code     VARCHAR NOT NULL UNIQUE,
    label    VARCHAR NOT NULL,
    terminal BOOLEAN NOT NULL DEFAULT FALSE
);

INSERT INTO order_statuses (id, code, label, terminal) VALUES
    (1, 'PND',  'Pending',   FALSE),
    (2, 'PAID', 'Paid',      FALSE),
    (3, 'SHP',  'Shipped',   FALSE),
    (4, 'DLV',  'Delivered', TRUE),
    (5, 'CNC',  'Cancelled', TRUE);

CREATE TABLE orders_lookup (
    id        UUID    PRIMARY KEY DEFAULT gen_random_uuid(),
    status_id INTEGER NOT NULL REFERENCES order_statuses (id)
);

在 JPA 里,状态变成一个关联关系,而不是枚举值:

@Entity
@Table(name = "orders_lookup")
public class OrderLookup {

    @Id
    @GeneratedValue(strategy = GenerationType.UUID)
    private UUID id;

    @ManyToOne(fetch = FetchType.EAGER, optional = false)
    @JoinColumn(name = "status_id", nullable = false)
    private OrderStatusDefinition status;
}

想知道一笔订单的状态——它的人类可读标签、它是不是终态——你需要 join:

SELECT o.id, s.code, s.label
FROM   orders_lookup o
JOIN   order_statuses s ON s.id = o.status_id
WHERE  o.id = ?;

✅ 什么时候它才物有所值

查找表真正买到的东西只有一件:值的集合以及挂在每个值上的元数据,从代码搬进了 数据。这在以下情况是真有价值:

  • 每个值携带可编辑的业务数据——展示标签、排序、颜色、功能开关、SLA。状态不只是一个 身份,它是一条小记录。
  • 由非开发人员管理这些值,或者按租户配置,或者在运行时随改随生效、不需要发版。
  • 你确实有大规模变更——重命名一个出现在数百万行里的标签,只需要更新 order_statuses 里的某一行,而不是每一笔订单。

最后一点是最有力的论据:改一处,而不是改所有处。如果你的「枚举」其实是一份被持续维护的 目录(catalog),那这才是正确的模型。


我的取舍

对于一个朴素的枚举——像订单生命周期这种固定的代码级状态集合——我不用查找表,并且在 code review 里会推回这种方案。

我常听到的理由是「万一以后要重命名某个值呢?」但我们刚刚看到,不用表也能解决: AttributeConverter 把存储代码和 Java 名称解耦,一个要改的标签就是一行迁移。为了活过一次 重命名,你不需要在每个查询上都背上外键和 join。

对这种情况,查找表真正添加的是永久成本:每次读取要么 join、要么多一次查询,状态从值变成 了受管理的关联关系,而一个编译期可穷举的 switch 变成了可能落空的运行时查找。你用一个 编译器能理解的值,换来了一个编译器看不懂的行,买来的是固定生命周期永远用不上的灵活性。

所以我的规则针对的是这个值是什么,而不是重命名:

  • 如果这个值只是身份——它就是 SHIPPED,句号——那就保持枚举。用 @Enumerated(STRING) 映射,用 Postgres 枚举类型兜底,想让重命名免费时就上 AttributeConverter。
  • 如果这个值是一条记录——它有需要人在运行时编辑的字段——那它从来就不是真正的枚举。 给它一张表。

重命名不是决定性因素。决定性因素是:这东西有没有属于自己的数据。


决策指南

方案 存储内容 适用场景 主要风险
@Enumerated(ORDINAL) 位置(1) 几乎任何场景都别用 重排悄悄污染已有行
@Enumerated(STRING) 常量名('PAID') 最理智的默认 重命名产生孤儿行
Postgres ENUM 类型 名称,数据库校验 想让数据库拒绝非法值 ADD VALUE 只能追加
AttributeConverter 稳定代码('PAID') 想让重命名零成本 多维护一个小类
查找表 外键指向一行 值携带可编辑数据 每次读取都要 join

对多数项目而言,一个可靠的默认是:在 Postgres 枚举类型之上用 @Enumerated(STRING), 一旦想让存储值与 Java 名称隔离,就升级为 AttributeConverter。


示例代码

本文代码见 github.com/javaAndScriptDeveloper/enums-article—— 同一个 OrderStatus 枚举的全部五种持久化方式、钉序号的测试,以及每种方案一个 round-trip 测试,断言每种方案到底往磁盘上写了什么。Docker 加一条 ./gradlew test 即可全部本地运行。


写在最后

挑选枚举的存储方式感觉像一个五秒钟的决定,而这恰恰是它值得你慢下来的原因。序号深坑、 重命名地雷、缺失的数据库约束——没有一个是写注解当天会出现的。它们出现在值集合发生变化 的那一天,而那一天总会来,通常是在你早已忘记当初的取舍之后很久。

好消息是默认选项很简单:存名字,让数据库校验,需要时把代码和标识符解耦。把查找表留给 那些真的是目录而不是枚举的场景。做对一次,你的状态字段从此安安分分——这是你能给一个列 的最高评价。


欢迎交流

如果你用别的方式存储枚举——或者你曾被这些陷阱中的某一个烧伤过、而我恰好没写到——我想 听听。联系方式见页脚。

常见问题

@Enumerated 应该用 ORDINAL 还是 STRING?

用 STRING。@Enumerated(ORDINAL) 存的是枚举的位置(0、1、2…),只要在非末尾位置插入一个新常量,所有已有行的指向都会被悄悄改掉。@Enumerated(STRING) 存的是常量名(如 ‘PAID’),自描述、可以直接用 SQL 调试,而且对重排序完全免疫。多出的那几个字节存储开销,在安全性面前不值一提。

用 ORDINAL 时在中间插入枚举值会出什么问题?

所有存储顺序在插入点之后的行都会解码成错误的值。如果 SHIPPED 的序号是 2,你在它前面插入 PACKED,SHIPPED 变成 3——但已有行里存的仍是整数 2,现在会被读成 PACKED。数据库没变,变的是你对它的解释。可以用一个钉死每个常量 ordinal() 的单元测试来防御。

怎么把枚举存成 Postgres 的枚举类型?

用 CREATE TYPE order_status AS ENUM ('PENDING', 'PAID', …) 创建类型,把列定义成这个类型,然后在 Hibernate 里用 @Enumerated(EnumType.STRING) 映射。在 JDBC URL 上加 stringtype=unspecified,让驱动以 unknown 类型发送值,Postgres 就能把字符串强转成枚举。此后数据库会拒绝任何枚举之外的值。

如何重命名枚举常量而不破坏已有数据?

把存储值与 Java 标识符解耦。用 JPA 的 AttributeConverter 持久化一个稳定的代码(如 ‘PAID’)而不是常量名,把 PENDING 重命名为 AWAITING_PAYMENT 就变成纯代码改动——不需要数据迁移,也不会产生孤儿行。这正是你很少为了「活过重命名」而需要查找表的原因。

什么时候该用枚举查找表而不是 @Enumerated?

当这些值携带可编辑的业务数据而不只是身份标识——展示给用户的标签、排序、功能开关——或者需要非开发人员在运行时增改它们时。如果枚举只是一组固定的代码级状态,查找表多半只是为一份你永远用不到的灵活性,在每次读取上多付一次 join 和一层间接。