Python enum.FlagBoundary 怎样处理未知标志位

Python 的 Flag 和 IntFlag 从整数构造成员时，最容易被忽略的是“输入里多了一位没有声明的标志”。这时不要只盯着最终数字，真正需要先决定的是：未知位应该让输入失败、被裁剪、退回普通整数，还是原样保留。

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

这个决策由 enum.FlagBoundary 控制。STRICT 适合不允许未知位的严格协议，CONFORM 会删除未知位，EJECT 会让结果失去 Flag 类型，KEEP 则保留未知位和 Flag 身份。下面用同一个输入把差异拆开。

先准备一个带未知位的输入

假设当前版本只声明了 READ、WRITE、EXECUTE 三个位，它们的掩码是 1 | 2 | 4。外部系统传来 20，二进制表示为 10100，其中 4 是已知的 EXECUTE，16 是当前枚举没有声明的未知位。

from enum import Flag, IntFlag, auto

# 用三个独立的二进制位描述权限；auto() 会生成 1、2、4
class Permission(Flag):
    READ = auto()
    WRITE = auto()
    EXECUTE = auto()

# 20 同时包含已知位 EXECUTE 和未知位 16
raw_value = 20
known_mask = Permission.READ.value | Permission.WRITE.value | Permission.EXECUTE.value
print(bin(raw_value), bin(known_mask))

这里的未知位并不一定是脏数据。它也可能代表新版本新增的权限、跨版本传输的扩展字段，或者调用方传错了值。因此，边界策略必须和输入契约一起设计。

STRICT：未知位直接抛出 ValueError

STRICT 是普通 Flag 的默认边界。构造值包含未声明位时，Python 抛出 ValueError，不会返回一个看似正常但语义不完整的权限对象。

from enum import Flag, STRICT, auto

# STRICT 把未知位视为输入契约错误
class StrictPermission(Flag, boundary=STRICT):
    READ = auto()
    WRITE = auto()
    EXECUTE = auto()

try:
    # 20 的 16 位没有声明，因此构造会失败
    value = StrictPermission(20)
except ValueError as exc:
    # 在边界层记录原始值，交给上层决定是否拒绝请求
    print(type(exc).__name__, exc)

适用场景是协议字段、权限校验或配置文件：未知位说明生产者和消费者的版本或约定不一致，继续执行比拒绝更危险。注意，捕获异常后不要把原始整数静默转换成普通权限集合，否则严格策略就失去了意义。

CONFORM：删掉未知位，留下合法 Flag

CONFORM 会移除输入中未声明的位，只保留能够映射到当前枚举的部分。对于 20，结果相当于只留下 EXECUTE，返回值仍然是 Flag 成员。

from enum import Flag, CONFORM, auto

# CONFORM 适合允许向前兼容、但当前版本只消费已知权限的场景
class ConformPermission(Flag, boundary=CONFORM):
    READ = auto()
    WRITE = auto()
    EXECUTE = auto()

value = ConformPermission(20)
print(value)                 # ConformPermission.EXECUTE
print(value.value)           # 4，未知的 16 已被移除
print(isinstance(value, Flag))  # True

它的代价是信息丢失：如果未知位代表必须执行的未来能力，CONFORM 会让调用方误以为整个输入已经被完整处理。使用前要确认业务允许“只处理当前认识的部分”。

EJECT：未知位让结果退回 int

EJECT 的特点不是抛错，也不是裁剪，而是让包含未知位的结果失去 Flag 成员身份，直接返回普通 int。这样可以保留原始数值，但下游不能再假设它具备 Flag 的成员和位运算语义。

from enum import Flag, EJECT, auto

# EJECT 保留原始数字，适合需要把未知位交给旧式整数逻辑的边界
class EjectPermission(Flag, boundary=EJECT):
    READ = auto()
    WRITE = auto()
    EXECUTE = auto()

value = EjectPermission(20)
print(value, type(value).__name__)  # 20 int
print(isinstance(value, Flag))      # False

代码接收 EJECT 的结果时必须显式判断类型。如果下游继续访问 value.name 或把它当成枚举成员，就会在真正处理数据时才失败。它的优势是不会伪装成“已知权限集合”，同时保留原始位图。

KEEP：保留未知位和 Flag 身份

KEEP 同时保留未知数字位和 Flag 的类型。结果可以显示为已知成员加上一个未命名数值，例如 EXECUTE|16。这是 IntFlag 的默认边界，适合需要跨版本转发或延迟解释未知位的场景。

from enum import Flag, KEEP, auto

# KEEP 让当前版本保留未来位，稍后仍可按整数转发
class KeepPermission(Flag, boundary=KEEP):
    READ = auto()
    WRITE = auto()
    EXECUTE = auto()

value = KeepPermission(20)
print(value, value.value)       # KeepPermission.EXECUTE|16 20
print(isinstance(value, Flag))  # True

# 显式声明 KEEP 时，行为与 IntFlag 的默认边界一致

保留未知位并不等于当前版本理解了它。展示、存储和转发可以继续进行，但真正授权或执行时仍应只根据已知成员做决定，并把未知位单独记录。

把策略写进枚举定义，而不是散落在调用处

边界策略属于枚举类型的输入契约，优先在类定义中固定。这样每个调用点都能得到一致行为，也避免有人在某个接口里手动按掩码裁剪、另一个接口里直接强转。

from enum import IntFlag, KEEP, auto

# IntFlag 适合需要和旧整数 API 互操作的权限集合
class FeatureBits(IntFlag, boundary=KEEP):
    SEARCH = auto()
    EXPORT = auto()
    AUDIT = auto()

def read_feature_bits(raw_value: int) -> FeatureBits:
    # 构造阶段保留未知位；真正消费时再按已知成员判断
    return FeatureBits(raw_value)

bits = read_feature_bits(8)
if bits & FeatureBits.SEARCH:
    # 只执行当前版本明确认识的能力
    print("允许搜索")
else:
    # 未知位可以继续被保存或转发，但不自动当成已授权能力
    print("没有当前版本可执行的已知能力")

如果业务需要拒绝未知位，可以把 IntFlag 改成普通 Flag 并使用 STRICT，或者在进入枚举构造前先检查掩码。关键是让“是否允许未知位”成为可读的类型设计，而不是隐藏在多个 if 里。

四种策略怎样选

可以用一句话做选择：输入不可信且必须完整匹配时用 STRICT；允许兼容但只关心已知位时用 CONFORM；旧接口只认整数时考虑 EJECT；需要保留未来位时用 KEEP。

最后检查类型和值，不要只打印结果

边界测试至少覆盖一个纯已知值、一个带未知位的值和零值，并同时检查数值与类型。只看字符串表示容易漏掉 EJECT 带来的类型变化。

def assert_boundary_contract(value, expected_type, expected_value=None):
    # 先检查类型，避免 int 与 Flag 的同值结果混淆
    assert isinstance(value, expected_type), type(value).__name__
    if expected_value is not None:
        # 再检查保留或裁剪后的数值是否符合输入契约
        assert value.value == expected_value, value.value

assert_boundary_contract(ConformPermission(20), Flag, 4)
assert_boundary_contract(KeepPermission(20), Flag, 20)
assert_boundary_contract(EjectPermission(20), int, 20)

测试的重点不是把四种策略都用在同一个业务里，而是把“未知位的处理决定”固定成明确契约。这样当生产者升级、权限位扩展或接口从 Flag 改成 IntFlag 时，变化会在边界测试中直接暴露。

常见问题

FlagBoundary 只影响创建时的整数吗？

主要影响从整数创建 Flag 或 IntFlag，以及相关位运算产生超出已声明范围的值。它不替代业务层的权限判断，未知位是否能执行仍需由应用定义。

为什么 IntFlag 默认更倾向于 KEEP？

IntFlag 面向与整数常量和旧 API 的互操作，保留未知位能让数值继续传递；但这也意味着消费端不能把“保留”误当成“理解”。

CONFORM 会不会把数据弄丢？

会。所有未声明位都会从结果中移除。如果未知位对审计、转发或未来升级有价值，应选择 KEEP 或保存原始整数，再决定当前版本如何消费。