Python typing.ReadOnly 怎样标记 TypedDict 中不可修改字段

如果一个接口返回的字典里有 id、name 和 created_at，调用方可以读取这些字段，却不应该在业务层重新改写 id。Python 3.13 提供的 typing.ReadOnly，就是给 TypedDict 字段补上这层静态约束。

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

结论先说：把字段写成 ReadOnly[T] 后，支持该特性的静态类型检查器会提示对它重新赋值；但 Python 运行时拿到的仍是普通字典，ReadOnly 不会自动把字典变成不可变对象。

ReadOnly 到底限制了什么

TypedDict 解决的是“字典应该有哪些键、每个键是什么类型”，而 ReadOnly 进一步表达“这个键的值由上游建立，当前代码只读”。它属于类型标注语义，主要服务于 mypy、pyright 等静态检查工具。

因此需要把两个问题分开：

• 类型检查阶段：对只读字段重新赋值，应当被检查器报告。
• 程序执行阶段：底层对象仍可能是 dict，直接下标赋值并不会因为注解存在而自动抛错。

最小迁移写法

先把只读字段包在 ReadOnly 中，普通字段保持原来的写法：

from typing import ReadOnly, TypedDict


class UserView(TypedDict):
    # id 由上游生成，业务层只读取它
    id: ReadOnly[int]
    # display_name 允许当前组装逻辑继续调整
    display_name: str


user: UserView = {
    "id": 1001,
    "display_name": "未命名用户",
}

# 普通字段可以被重新赋值
user["display_name"] = "林木"

# 支持 ReadOnly 的检查器会在这里提示类型错误
user["id"] = 1002

这段声明表达的是“字段级别”的只读，而不是整个 UserView 都不可修改。读取 user["id"] 仍然是正常操作，display_name 也仍然可以更新。

先确认检查器真的启用了这个语义

注解本身不会执行检查，项目需要使用支持 PEP 705 的类型检查器版本。最小验证可以同时放入一条合法读取、一条普通字段修改和一条只读字段修改：

from typing import ReadOnly, TypedDict


class Config(TypedDict):
    # 发布后由配置中心确定，调用方不应改写
    revision: ReadOnly[int]
    # 本地展示名称允许调整
    label: str


config: Config = {"revision": 7, "label": "灰度"}

current_revision = config["revision"]  # 合法：只读字段可以读取
config["label"] = "正式"  # 合法：普通字段仍可写
config["revision"] = 8  # 检查器应提示：ReadOnly 字段不能重新赋值

如果最后一行没有提示，先不要急着修改代码。常见原因是检查器版本太旧、项目没有加载正确配置，或者文件没有被纳入检查范围。运行时是否能赋值，不能用来判断静态检查是否生效。

为什么运行时仍然能改

TypedDict 在运行时不会创建一个带字段描述的专用容器，它的值通常就是普通 dict。ReadOnly 也不会替你插入代理对象、属性拦截器或冻结逻辑，所以以下代码可能正常执行：

from typing import ReadOnly, TypedDict


class Snapshot(TypedDict):
    # 这个约束给静态检查器使用
    checksum: ReadOnly[str]


snapshot: Snapshot = {"checksum": "abc"}

# 运行时只是普通 dict；注解不会自动抛出异常
snapshot["checksum"] = "changed"
print(snapshot["checksum"])

如果业务要求“运行时也绝对不能修改”，应该选用真正的不可变设计，例如只暴露读取接口、构造不可变数据对象，或在边界层复制后封装。不要把类型检查提示当作安全边界。

旧代码怎么逐步迁移

1. 先找出由服务端、配置中心或数据库生成、下游只应读取的字段。
2. 只给这些字段加 ReadOnly，不要把整张 TypedDict 盲目改成全部只读。
3. 运行静态检查，区分真实的错误写入和测试夹具、反序列化代码中的合法构造。
4. 需要运行时防篡改时，另行设计对象边界，不依赖 ReadOnly。

构造字典时给只读字段赋初值并不等于“修改已存在的只读字段”。读者可以把“创建快照”和“拿到快照后改写”分开看：前者是填充结构，后者才是检查器要阻止的更新动作。

一张表记住边界

常见问题

ReadOnly 会让 dict 变成只读吗？

不会。它是 TypedDict 字段的静态类型限定，运行时仍然可能拿到普通字典。

只读字段还能在创建时赋值吗？

可以。创建一个符合 TypedDict 形状的初始值，与对已经存在的只读字段再次改写，是两个不同动作。

项目暂时不能升级检查器怎么办？

先保留现有 TypedDict 声明，并把只读约定写入接口文档和代码评审规则；等工具链支持后再加入 ReadOnly，不要伪造运行时保护。

把 ReadOnly 看成“给数据流加一条静态契约”就够了：它帮助团队更早发现错误写入，但真正的运行时不可变性仍需要单独设计。