Python StrEnum 怎样与 JSON 字符串互转

如果接口字段本来就是字符串，Python 3.11 引入的 StrEnum 可以把“可读的枚举成员”和“稳定的线上值”放在同一个类型里。最小闭环是：枚举成员用 value 作为协议值，出站时交给 json.dumps()，入站后先用 json.loads() 得到字符串，再调用 Status(raw) 恢复成员。不要把 name 当成接口值，也不要在未知值时静默改写字符串。

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

稳定做法可以概括为：name 是 Python 代码里的符号名，value 才是需要长期兼容的 JSON 字符串。序列化保存 value，反序列化用枚举类按 value 查找；查不到时显式进入错误或兼容分支。

先判断：接口字段应该保存 name 还是 value

StrEnum 的成员同时具有 name 和 value。例如 Status.READY.name 是 READY，而 Status.READY.value 可以明确写成 ready。前者适合代码内部定位成员，后者适合接口、消息队列或配置文件，因为它可以独立于 Python 命名风格演进。

建议把协议值显式写出。只有在值确实等于小写成员名时，才使用 auto()；官方文档说明，StrEnum 使用 auto() 时默认取成员名的小写形式。

from enum import StrEnum

class Status(StrEnum):
    # 显式固定线上协议值，成员名只服务于 Python 代码可读性
    READY = "ready"
    PAUSED = "paused"
    FAILED = "failed"

print(Status.READY.name)   # READY：代码中的符号名
print(Status.READY.value)  # ready：接口中传输的字符串值

如果后端将成员改名为 AVAILABLE，但仍保留 value = "ready"，外部 JSON 就不会因为内部重命名而改变。这是字符串枚举适合接口模型的关键。

序列化：用 json.dumps 把成员写成 JSON 字符串

在标准库的常见用法中，StrEnum 可以放进待编码的字典，json.dumps() 会把它作为字符串处理。调用方拿到的是 JSON 文本，而不是 Python 枚举对象。

import json
from enum import StrEnum

class Status(StrEnum):
    # value 是接口稳定值，避免直接暴露成员名
    READY = "ready"
    FAILED = "failed"

payload = {
    "job_id": "job-42",
    "status": Status.READY,
}

# ensure_ascii=False 让非 ASCII 文本保持可读，不改变枚举的序列化规则
wire_text = json.dumps(payload, ensure_ascii=False)
print(wire_text)
# {"job_id": "job-42", "status": "ready"}

值为 READY 还是 ready，取决于枚举定义中的 value，不是 name。如果接入的编码器先做严格的 type(x) == str 判断，不能依赖字符串子类的兼容行为，可以在交给编码器前显式使用 str(Status.READY)。

反序列化：用枚举类调用把字符串恢复为成员

收到 JSON 后，先解析出普通 Python 字典，再用 Status(raw_status) 根据 value 查找成员。查找成功得到的是 Status.READY，不是一条失去类型信息的字符串；查找失败则抛出 ValueError，这正好可以作为请求拒绝或兼容处理的入口。

import json
from enum import StrEnum

class Status(StrEnum):
    # 只接受约定中的线上值，未知字符串不自动猜测
    READY = "ready"
    FAILED = "failed"

def parse_status(wire_text: str) -> Status:
    # 先解 JSON，再取出协议字段，避免把整段 JSON 直接传给枚举
    data = json.loads(wire_text)
    raw_status = data["status"]
    try:
        # 枚举类调用按 value 查找成员
        return Status(raw_status)
    except (KeyError, TypeError, ValueError) as exc:
        # 保留原始异常作为原因，交给上层返回明确的输入错误
        raise ValueError("status 必须是 ready 或 failed") from exc

status = parse_status('{"status": "ready"}')
print(status is Status.READY)  # True

运维判断：未知值、严格编码器和回滚怎么处理

值班时可以把问题分成三类。第一类是入站字符串拼写错误，Status(raw) 直接抛出 ValueError，应该记录字段名并返回输入错误。第二类是上游已经发布了新值，此时不要把它默认为旧状态；若业务需要前向兼容，可以增加一个明确的 UNKNOWN 成员或在边界层保存原始字符串，但要把这项决定写进协议。

第三类是编码器或框架只接受精确的内置 str。官方文档也提醒，标准库中存在检查 type(x) == str 而不是 isinstance(x, str) 的位置，这类场景要显式调用 str(member)。这不是把 name 改成字符串，而是把同一个 value 以普通字符串形式交给严格边界。

from enum import StrEnum

class Status(StrEnum):
    # 回滚时保留旧协议值，内部成员名可以另行调整
    READY = "ready"
    FAILED = "failed"

def wire_status(status: Status) -> str:
    # 严格边界只接收内置 str，显式转换仍然使用 value
    return str(status)

def recover_status(raw: object) -> Status | None:
    # 未知值不静默映射到 READY，调用方可选择告警或拒绝
    if not isinstance(raw, str):
        return None
    try:
        return Status(raw)
    except ValueError:
        return None

回滚时先保证旧的 value 仍然可读，再切换内部代码；不要先删除旧 value 后再观察调用方。发布确认可以只看四项：JSON 出站字段是否为 value、入站是否经过枚举类查找、未知值是否有明确分支、严格编码器边界是否使用了 str(member)。

常见问题

StrEnum 的 name 和 value 有什么区别？ name 是成员名，例如 READY；value 是成员值，例如 ready。接口协议应优先使用 value。

为什么 Status("ready") 能得到枚举成员？ 枚举类的调用语法用于按 value 查找已有成员，查不到时会抛出 ValueError。

可以直接把 StrEnum 当普通字符串吗？ 大多数字符串场景可以，但遇到精确类型判断的边界时应显式写 str(member)，并保留未知值处理逻辑。