Python enum.verify 怎样在定义时检查枚举约束

如果一个枚举的值不能重复、整数不能跳号，或者一个 Flag 组合必须由已经命名的位组成，可以把约束写在类定义旁边：使用 enum.verify 装饰器包住 UNIQUE、CONTINUOUS 或 NAMED_FLAGS。约束不满足时，枚举类在定义阶段就会抛出 ValueError，问题会在模块加载阶段暴露，而不是等到业务请求才发现。

官方文档：https://docs.python.org/3/library/enum.html#enum.verify

这套机制适合表达“枚举结构本身不应该违反什么规则”，不负责校验用户输入、数据库字段或接口业务状态。本文只讨论标准库 enum 中的定义期检查。

用 verify 把约束放在枚举定义边界

verify 接收一个或多个检查项，返回一个装饰器。装饰器应用于枚举类后，标准库会根据检查项审视已经创建的成员。最小写法如下：

from enum import Enum, verify, UNIQUE

# 约束和枚举放在同一个定义边界，重复值会在类创建阶段被拒绝。
@verify(UNIQUE)
class JobState(Enum):
    PENDING = 1
    RUNNING = 2
    FINISHED = 3

这里的重点不是给成员增加运行时方法，而是给类创建过程增加一个明确的不变量。若后来有人把 FAILED = 3 写进去，模块在加载这个类时就会收到 ValueError。错误距离定义位置很近，代码审查也能直接看到“这个枚举要求值唯一”。

三种检查项分别解决什么问题

Python 官方文档把 UNIQUE、CONTINUOUS 和 NAMED_FLAGS 放在 EnumCheck 中。选择时不要按名字猜，应该先看枚举值的业务形状：

CONTINUOUS 与 NAMED_FLAGS 面向整数值。字符串枚举可以使用 UNIQUE 检查别名，但不能把“字符串排序连续”理解成 CONTINUOUS 的目标。

UNIQUE：禁止无意的别名

Enum 原生允许不同名字绑定相同值，并把后一个名字视为别名。这在兼容旧常量时可能是有意设计，但在状态、权限或协议码中，重复值往往意味着输入映射不完整。

from enum import Enum, UNIQUE, verify

# 业务要求每个外部状态码只有一个枚举名字。
@verify(UNIQUE)
class PaymentState(Enum):
    CREATED = 10
    PAID = 20
    # REFUNDED = 20  # 取消注释会因别名而在定义期抛出 ValueError。

如果重复值本来就是兼容协议的别名，就不要机械添加 UNIQUE；此时应在文档或测试中明确别名关系。

CONTINUOUS：保证整数区间没有断点

当枚举代表顺序编号、等级或连续的错误码区间时，可以使用 CONTINUOUS。它检查最低成员值和最高成员值之间是否存在缺口，不是检查成员声明顺序，也不是要求从 1 开始。

from enum import Enum, CONTINUOUS, verify

# 这里的编号从 10 开始，但 12 不应被跳过。
@verify(CONTINUOUS)
class Severity(Enum):
    LOW = 10
    MEDIUM = 11
    HIGH = 12
    # CRITICAL = 14  # 如果没有 13，定义期会报告缺失值。

因此，值为 10、11、12 是连续的，值为 10、12 则不连续。若编号本来是稀疏协议码，跳号是设计的一部分，就不应套用这个约束。

NAMED_FLAGS：检查组合位是否可解释

Flag 的成员通常是 1、2、4 这样的单独位，多个位可以按位或组成组合值。NAMED_FLAGS 关注的是已经写出的组合值能否完全由已命名的标志位解释，特别适合手写掩码而不是全部使用 auto() 的场景。

from enum import Flag, NAMED_FLAGS, verify

# 组合权限只能由已经声明的基本权限组成。
@verify(NAMED_FLAGS)
class Permission(Flag):
    READ = 1
    WRITE = 2
    EXECUTE = 4
    READ_WRITE = READ | WRITE
    # BROKEN = 8 | READ  # 8 没有对应的命名基本位，会被拒绝。

这个检查项不是禁止所有组合成员，而是要求组合中的每一位都有名字。对于复杂掩码，官方文档还建议结合 show_flag_values() 分解数值，帮助定位缺失的位。

组合多个约束并保留清晰的错误边界

一个枚举可以同时使用多个检查项。把它们放在一次 verify 调用里，意图比连续叠加多个装饰器更集中：

from enum import Enum, CONTINUOUS, UNIQUE, verify

# 状态码既不能重复，也不能在范围中留下缺口。
@verify(UNIQUE, CONTINUOUS)
class ImportStage(Enum):
    READ = 1
    PARSE = 2
    STORE = 3

多个约束并不意味着所有枚举都应该“全选”。判断方式可以压缩成三问：

• 不同名字绑定相同值是否有合法的兼容意义？没有，就考虑 UNIQUE。
• 最小整数和最大整数之间的每个值是否都必须有成员？是，才考虑 CONTINUOUS。
• Flag 的组合掩码是否必须能拆回已命名的基本位？是，才考虑 NAMED_FLAGS。

三种检查失败时都属于定义阶段错误，常见处理方式是让模块加载直接失败，并在发布前通过导入测试发现问题；不要在导入时捕获异常后继续构造一个“半有效”的枚举，这会让后续代码误以为约束已经生效。

不要把 verify 当成运行时输入校验器

verify 检查的是枚举类的静态结构。它不能替代下面这些业务检查：

• 接口传入的整数是否允许出现在当前订单状态转换中；
• 数据库中的旧值是否仍然兼容当前版本；
• 用户提交的字符串能否转换成枚举成员；
• 某个 Flag 组合是否符合当前用户的授权策略。

这些属于输入解析或业务规则，仍然需要显式处理 KeyError、ValueError 或自定义异常。verify 的价值在于把稳定、与类定义绑定的结构规则提前固定下来。

from enum import Enum, UNIQUE, verify

# 定义期约束负责保证类自身没有重复值。
@verify(UNIQUE)
class OrderState(Enum):
    CREATED = "created"
    PAID = "paid"

def parse_state(raw: str) -> OrderState:
    # 运行时输入仍要单独处理，不能假定外部字符串一定有效。
    try:
        return OrderState(raw)
    except ValueError as exc:
        raise ValueError(f"不支持的订单状态: {raw!r}") from exc

一份适合代码审查的判断清单

在提交枚举定义前，可以用下面的清单快速判断：

1. 先确认重复值是缺陷还是兼容别名，再决定是否加入 UNIQUE。
2. 只有整数枚举需要连续编号时才使用 CONTINUOUS，不要把稀疏协议码强行补齐。
3. Flag 手写组合掩码时检查每一位是否有基本成员，必要时添加 NAMED_FLAGS。
4. 把 ValueError 视为定义期反馈，在测试、模块加载或构建阶段暴露，而不是静默吞掉。
5. 对接口输入、数据库兼容和授权判断继续保留独立的运行时校验。

简单说，enum.verify 把“这个枚举应该长什么样”写成了可执行的类定义约束。选对检查项后，重复值、编号断点和不可解释的 Flag 掩码都会在离代码最近的位置暴露，运行时校验则继续负责外部数据和业务状态。

相关问题

UNIQUE 和 unique 装饰器有什么区别？

两者都可以阻止重复值形成别名，但 UNIQUE 是 verify 可组合的检查项；unique 是单独的枚举类装饰器。需要组合多个 EnumCheck 时，使用 verify 更集中。

CONTINUOUS 要求枚举从 1 开始吗？

不要求。它关心最低值到最高值之间是否缺少整数，起始值可以是 0、10 或其他整数。

NAMED_FLAGS 能检查普通 Enum 吗？

它面向 Flag 组合值。普通 Enum 没有按位组合的语义，应根据值唯一性或连续性选择相应检查项。