Python中的@enum.EnumUnique装饰器用于确保枚举类中的成员值唯一，避免重复值引发的潜在问题，当枚举成员的值（而非名称）必须唯一时，该装饰器会强制检查所有值，并在发现重复时抛出ValueError异常，在定义状态码或标志位时，值的唯一性至关重要，使用方式为在枚举类定义前添加@enum.EnumUnique，结合enum.Enum基类，若未启用此装饰器，默认允许不同成员共享相同值（如别名场景），该功能需Python 3.11+版本支持，适用于需要严格值唯一性的场景，但可能牺牲部分灵活性（如无法定义别名），开发者应在明确需求后选择是否启用此装饰器。

在Python中，enum模块提供了一种方便的方式来定义枚举类型，使得代码更具可读性和可维护性，在某些情况下，我们可能需要确保枚举成员的值是唯一的，以避免潜在的逻辑错误，为此，Python 3.11引入了@enum.EnumUnique装饰器，它可以帮助我们强制检查枚举值的唯一性，本文将详细介绍@enum.EnumUnique的用法、应用场景及其实现原理。

---

什么是@enum.EnumUnique？

@enum.EnumUnique是Python 3.11新增的一个装饰器，用于确保枚举类中的每个成员都具有唯一的值，如果枚举类中的多个成员具有相同的值，Python会抛出ValueError异常，这个装饰器可以帮助我们在定义枚举时避免重复值的问题,从而提高代码的健壮性。

基本语法

from enum import Enum, EnumUnique
@EnumUnique
class Color(Enum):
    RED = 1
    GREEN = 2
    BLUE = 3  # 如果重复值，如 BLUE = 1，会抛出 ValueError

---

为什么需要@enum.EnumUnique？

在标准的Enum类中,Python允许枚举成员具有相同的值，

from enum import Enum
class Status(Enum):
    PENDING = 1
    PROCESSING = 1  # 允许重复值
    COMPLETED = 2

虽然Python不会报错,但这样的设计可能会导致逻辑上的混淆。

print(Status.PENDING is Status.PROCESSING)  # 输出 True

这意味着PENDING和PROCESSING实际上是同一个枚举成员，这可能不符合我们的预期，使用@enum.EnumUnique可以避免这种情况,确保每个枚举成员的值都是唯一的。

---

如何使用@enum.EnumUnique？

（1）基本用法

from enum import Enum, EnumUnique
@EnumUnique
class HTTPStatus(Enum):
    OK = 200
    CREATED = 201
    ACCEPTED = 202
    BAD_REQUEST = 400
    UNAUTHORIZED = 401
    FORBIDDEN = 403
    NOT_FOUND = 404

如果尝试定义重复值：

@EnumUnique
class HTTPStatus(Enum):
    OK = 200
    DUPLICATE_OK = 200  # 抛出 ValueError: duplicate values found in <enum 'HTTPStatus'>: DUPLICATE_OK -> OK

（2）结合auto()使用

auto()可以自动分配递增的值，结合@EnumUnique可以确保唯一性：

from enum import Enum, EnumUnique, auto
@EnumUnique
class Priority(Enum):
    LOW = auto()
    MEDIUM = auto()
    HIGH = auto()

（3）处理字符串枚举

@EnumUnique同样适用于字符串枚举：

@EnumUnique
class Direction(Enum):
    NORTH = "north"
    SOUTH = "south"
    EAST = "east"
    WEST = "west"

---

与@enum.verify的比较

Python 3.11还引入了@enum.verify装饰器,它可以用于更广泛的枚举验证，

• @enum.verify(EnumUnique)：确保值唯一（等同于@EnumUnique）。
• @enum.verify(EnumContinuous)：确保值是连续的（如1, 2, 3，而不是1, 3, 4）。
• @enum.verify(EnumNamedTuple)：确保枚举成员是namedtuple类型。

@EnumUnique实际上是@enum.verify(EnumUnique)的简化写法。

---

实现原理

@EnumUnique的工作原理是在枚举类创建时检查所有成员的值，如果发现重复值，则抛出ValueError,其底层实现类似于：

def check_unique(enum_cls):
    seen = set()
    for member in enum_cls:
        if member.value in seen:
            raise ValueError(f"duplicate values found in {enum_cls.__name__}")
        seen.add(member.value)
    return enum_cls

@EnumUnique在enum模块中的实现更加高效,并且与Python的枚举机制深度集成。

---

适用场景

@EnumUnique适用于以下情况：

1. HTTP状态码：确保每个状态码唯一。
2. 错误码：避免重复的错误码导致混淆。
3. 配置选项：如日志级别（DEBUG, INFO, WARNING, ERROR）。
4. 游戏状态：如MENU, PLAYING, PAUSED, GAME_OVER。

---

@enum.EnumUnique是Python 3.11引入的一个实用装饰器，用于强制枚举值的唯一性，它可以帮助开发者避免因重复值导致的逻辑错误，提高代码的可靠性，结合auto()和字符串枚举，可以更灵活地定义枚举类型，如果你正在使用Python 3.11或更高版本，建议在需要唯一枚举值的场景中使用@EnumUnique,以确保代码的健壮性。

# 示例：完整使用场景
from enum import Enum, EnumUnique, auto
@EnumUnique
class LogLevel(Enum):
    DEBUG = auto()
    INFO = auto()
    WARNING = auto()
    ERROR = auto()
    CRITICAL = auto()
# 测试
print(list(LogLevel))  # 输出所有唯一枚举成员

希望本文能帮助你更好地理解和使用@enum.EnumUnique！