Python 3.14延迟求值注解解决循环引用

我在整理领域模型时，最容易被打断的地方不是类本身，而是类型注解：User 里想写订单列表，Order 又想引用用户。Python 3.14 默认延迟求值注解后，这类互相引用可以直接写，不必为了“后面的类还没定义”把每个名字都包成字符串。

官方地址：https://docs.python.org/3.14/

结论：Python 3.14 会把注解的求值推迟到真正读取时；定义阶段可以先保留类型表达式，运行时再用 annotationlib.get_annotations() 选择实际值、前向引用或字符串格式。

先用直接注解解决互相引用

最小场景是两个类型互相指向。Python 3.14 不会在类体创建的那一刻立刻计算 list[Order]，因此 Order 可以出现在它真正定义之前：

class User:
    # Order 尚未定义；Python 3.14 会把这条注解留到之后再求值
    orders: list[Order]


class Order:
    # User 已经位于模块命名空间中，表示订单的买家类型
    buyer: User

这里的关键不是“循环引用被忽略”，而是注解从定义时机移到了读取时机。模块加载完成后，User 和 Order 都已经进入命名空间，注解才有机会解析成真实类型。这个语义也适合跨模块的模型关系，但模块导入环本身仍然要单独设计，延迟注解不会替你消除导入环。

运行时读取要先选格式

真正需要注解的地方通常是文档生成器、序列化器或框架注册逻辑。Python 3.14 新增的 annotationlib 把“我要什么结果”写进调用参数，而不是让所有调用都强制执行求值：

from annotationlib import Format, get_annotations

# VALUE 会尝试把名称解析成真实类型；适合模块已经完成加载的场景
user_value = get_annotations(User, format=Format.VALUE)

# FORWARDREF 对暂时解析不了的名字保留 ForwardRef 对象
class Report:
    # MissingOwner 故意未定义，用来展示未解析名称的边界
    owner: MissingOwner

report_refs = get_annotations(Report, format=Format.FORWARDREF)

# STRING 只返回注解表达式的字符串形式，适合展示或延迟处理
user_source = get_annotations(User, format=Format.STRING)

可以按下面的方式选择：

要注意，Format.VALUE 不是“更正确”的格式，它只是更积极地求值。如果注解中仍有未定义名字，读取可能抛出异常；这时可改用 Format.FORWARDREF 或 Format.STRING，把解析责任交给后续阶段。

循环引用解决了，求值边界仍然存在

延迟只改变时间，不改变名称解析规则。模块完成导入后，类名、别名和局部作用域是否仍然可用，决定了 VALUE 能否成功。注解中也不应放入来自不可信输入的表达式：官方文档提醒，读取和求值注解可能执行其中的代码，因此库接口最好由调用者明确选择是否求值。

如果只是显示类型，不要为了得到漂亮字符串而先调用会执行求值的接口；优先使用 Format.STRING。如果需要知道某个名字暂时缺失但不想让整个扫描失败，使用 Format.FORWARDREF，再在依赖准备好后决定是否调用它的求值能力。

旧版本项目怎么兼容

Python 3.13 及更早版本没有 Python 3.14 的默认延迟语义。常见兼容写法有两种：在模块顶部使用 from __future__ import annotations，或只给确实需要后置定义的类型加引号。前者更适合整套模型统一迁移，后者对老框架和局部改动更保守。

如果代码还要支持多个 Python 版本，可以把读取入口包在兼容层里：3.14+ 使用 annotationlib.get_annotations，旧版本继续使用 inspect.get_annotations 或现有框架接口，并确保求值时传入正确的全局/局部命名空间。不要直接依赖类字典里注解缓存的私有形态，Python 3.14 的官方建议已经转向公开读取函数。

几个容易混淆的问题

Python 3.14 还需要给前向引用加引号吗？通常不需要，直接写类型表达式即可；如果项目要兼容旧解释器，仍应保留兼容写法。

用了延迟注解就不会有循环导入了吗？不会。它解决的是注解表达式过早求值，不能替代模块依赖拆分、局部导入或共享协议模块。

什么时候使用 Format.FORWARDREF？当扫描器希望先收集结构、但允许部分名称尚未准备好时使用；如果业务逻辑必须拿到真实类型，则应在依赖就绪后再选择 Format.VALUE。

把“定义注解”和“读取注解”分成两个决策点，基本就能把 Python 3.14 的循环引用问题控制在清晰范围内：模型定义保持直接，运行时工具按需要选择求值强度。