Python enum.Flag 怎样组合权限标记并判断成员

当一个字段不是“只能选一个值”，而是“可以同时拥有读、写、导出中的几项能力”时，Python 的 enum.Flag 比手写整数常量更容易维护。它让每个基础标记有清晰的名字，再用按位运算组合多个标记。判断权限时，优先把“某个成员是否包含在组合值中”封装成小函数，避免业务代码到处出现难读的数字比较。

官方地址：https://docs.python.org/3/library/enum.html

最小答案是：用 Flag 定义独立成员，用 | 组合，用 required in granted 或 (granted & required) == required 判断是否拥有所需标记；空值用 Access(0) 表示，不要把任意整数直接当成合法权限。

先把单个权限定义成 Flag 成员

权限标记需要满足一个前提：每个基础成员占用不同的位。这样 READ、WRITE 和 EXPORT 才能叠加而不互相覆盖。使用 auto() 时，Flag 会为基础成员生成适合组合的值；如果协议要求固定值，也可以显式写成 1、2、4 这样的独立位。

from enum import Flag, auto


class Access(Flag):
    # 每个成员代表一种可以独立开关的能力。
    READ = auto()
    WRITE = auto()
    EXPORT = auto()


# 组合值表达“同时拥有读和写”，而不是新增一个互斥状态。
EDITOR_ACCESS = Access.READ | Access.WRITE

这里的 EDITOR_ACCESS 仍然是 Access 类型的组合值。它的含义由组成它的成员决定，业务代码不必记住底层整数。图1展示了枚举定义、基础成员与组合对象之间的静态关系。

用按位或组合多个标记

| 是组合权限最直接的写法。组合是幂等的：同一个成员重复加入不会产生第二份权限；组合顺序也不改变最终的集合语义。需要注意的是，Flag 适合表达可拆分的集合，不适合拿来表达“状态只能处于其中一个”的互斥选项，后者通常应使用普通 Enum。

from enum import Flag, auto


class Access(Flag):
    # 使用独立标记位，组合后仍能拆出每一项能力。
    READ = auto()
    WRITE = auto()
    EXPORT = auto()


granted = Access.READ | Access.EXPORT

# 按位或继续添加成员；重复添加不会改变集合含义。
granted = granted | Access.READ

# 可以迭代出组合中的非别名成员，用于展示或记录。
members = list(granted)

如果需要把组合值输出给日志或接口，建议在边界处明确格式：内部继续使用 Access，外部再转换成成员名称列表或协议规定的整数。不要让业务层依赖 repr() 的展示文本。

用 in 或按位与判断成员

在支持实例包含判断的 Python 版本中，required in granted 读起来最接近业务语义。官方文档也给出了组合成员之间的包含关系。若代码需要兼容较早的运行环境，使用按位与表达式更明确：只有当交集完整覆盖所需标记时，才算拥有权限。

def has_permission(granted: Access, required: Access) -> bool:
    # required 可能是一个组合值，所以要检查整组标记是否都存在。
    return (granted & required) == required


granted = Access.READ | Access.EXPORT

# 单个成员和组合成员都可以作为 required。
can_read = has_permission(granted, Access.READ)
can_edit = has_permission(granted, Access.READ | Access.WRITE)

# Python 3.11 及更新版本也可以写成：
can_export = Access.EXPORT in granted

常见错误是只判断结果是否非零：bool(granted & required) 只能说明两者有交集，不能说明 required 的每一项都具备。例如已有 READ，需求是 READ | WRITE 时，交集非零但权限仍然不完整。

处理零值、未知值和输入转换

没有任何权限时可以使用 Access(0)。它与“没有设置字段”相比更明确，也便于统一走权限检查函数。零值在布尔上下文中表示没有成员，因此不能把它当成默认拥有某项能力。

empty = Access(0)

# 空集合不包含任何权限，检查函数会返回 False。
assert not has_permission(empty, Access.READ)


def parse_access(raw: int) -> Access:
    # 外部整数必须经过枚举转换，非法位交给调用方处理。
    try:
        return Access(raw)
    except ValueError as exc:
        raise ValueError(f"未知的权限组合: {raw}") from exc

这里没有把任何外部整数默认为合法权限。接口、配置文件或数据库里读到的值可能来自旧版本或错误输入，转换失败时应当明确记录并拒绝继续使用，而不是静默放大权限。若协议确实允许未来新增位，应先定义兼容策略，再决定是否保留原始整数。

把权限边界收敛到可维护的检查

企业代码里，权限判断最好只保留一处语义入口：调用方传入当前授权集合和所需集合，函数负责完整匹配。这样后续增加 DELETE 或调整权限来源时，业务分支不用重新理解位运算。

def require_access(granted: Access, required: Access) -> None:
    # 统一检查所有 required 标记，缺少任意一项就拒绝继续。
    if not has_permission(granted, required):
        raise PermissionError(
            f"缺少权限: required={required!r}, granted={granted!r}"
        )


def export_report(granted: Access) -> str:
    # 导出动作需要同时具备读取和导出能力。
    require_access(granted, Access.READ | Access.EXPORT)
    return "report-ready"

测试时至少覆盖四类情况：单个成员、完整组合、只具备部分组合、零值。尤其要覆盖“交集非零但组合不完整”的情况，它最容易让宽松的布尔判断漏掉权限边界。

几个容易混淆的选择

常见问题

bool(granted & required) 能判断完整权限吗？

不能。它只判断有没有交集。完整判断应使用 (granted & required) == required，或者在支持的 Python 版本中使用 required in granted。

为什么不直接保存一个普通整数？

普通整数更难阅读，也容易把位含义散落在业务代码里。Flag 把成员名、组合关系和转换边界集中到一个类型中，日志与代码评审更容易看出意图。

Flag 和 IntFlag 怎么选？

如果权限只在 Python 类型内部流转，优先使用 Flag。如果必须和已有整数协议、位掩码或数组索引边界交互，再评估 IntFlag，并在边界处明确说明整数运算可能让结果失去枚举类型。

总结一下：基础能力用独立 Flag 成员定义，多个能力用 | 合并，完整权限用 in 或“按位与后等于需求集合”判断；零值与外部未知值要单独处理。把判断集中到一个小函数，权限组合才不会随着业务分支增长而失控。