Python 3.14 deferred annotation 如何迁移：annotationlib、类型检查时机与运行时兼容

升级到 Python 3.14 后，最容易被忽略的变化不是某个新语法，而是注解的读取时机变了：函数定义时不再急着把类型表达式算完，真正访问注解时才会求值。只要项目里有路由注册、数据校验、文档生成或插件扫描，直接读取 __annotations__ 就可能把版本差异带进运行时。

Python 3.14 到底改了什么

Python 3.13 及更早版本里，普通注解通常在定义函数或类时就完成求值；如果名字尚未定义，函数定义阶段可能直接抛出 NameError。Python 3.14 默认改为延迟求值，注解先保存在编译器生成的注解函数中，访问时才取值。

这解决了前向引用和导入时开销问题，但也改变了一个常见假设：func.__annotations__ 不再只是“拿一个已经准备好的字典”。它可能触发求值，也可能因为注解中的名字、属性或表达式失败而抛异常。

# Python 3.14
def load_user(user: User) -> None:
    pass

class User:
    pass

print(load_user.__annotations__)
# {'user': , 'return': None}

为什么要用 annotationlib 而不是直接读 __annotations__

annotationlib 把“我要什么形式的注解”明确写进调用点。VALUE 适合已经准备好运行时类型对象的场景；FORWARDREF 允许未解析的名字以代理形式留下；STRING 适合文档、代码生成和不希望立刻解析类型的工具。

from annotationlib import Format, get_annotations

def parse_event(event: Event) -> Result:
    pass

print(get_annotations(parse_event, format=Format.FORWARDREF))
print(get_annotations(parse_event, format=Format.STRING))

# 只有确认名字和执行环境都可靠时，才取运行时值
print(get_annotations(parse_event, format=Format.VALUE))

这里的选择逻辑很直白：文档生成工具通常不需要把每个前向引用都解析成真实对象；插件扫描器也更适合先拿到完整结构，再判断哪些类型可以进入后续处理流程。

旧代码会在哪些地方出现兼容差异

第一类风险是模块导入时机问题。旧代码可能在导入阶段就读取注解，还默认所有依赖都已经加载完成，3.14的延迟机制会让这类错误推迟到扫描或注册阶段才暴露。第二类风险是把注解字典当成永久缓存，修改之后又期望Python继续按旧规则生成结果。第三类风险是直接从类的命名空间字典里取注解，这属于不能依赖的内部实现细节。

如果开发的库需要同时兼容Python 3.10到3.13版本，可以把读取注解的入口收拢到一个小型工具函数里：

try:
    from annotationlib import Format, get_annotations
except ImportError:
    from inspect import get_annotations as _get_annotations

    def get_annotations(obj, *, format=None):
        # 旧版本没有三格式接口，保留值格式的最小兼容面
        return _get_annotations(obj)

def annotations_for_runtime(obj, *, runtime=False):
    if runtime:
        return get_annotations(obj, format=Format.VALUE)
    return get_annotations(obj)

上面的兼容层只负责统一入口，不要把 Python 3.14 的 Format.FORWARDREF 假装成旧版本也支持。调用方如果依赖未解析引用，就应该在旧版本走明确的降级策略，例如保留字符串并记录待解析名称。

迁移时建议固定的三个检查点

先查访问点，不要只搜注解声明

在代码库里同时搜索 __annotations__、get_type_hints、inspect.get_annotations 以及框架的自动注册钩子。真正需要改的，往往是扫描器而不是业务函数签名。

再区分“展示”与“运行”

展示类工具优先使用 STRING，允许未知类型原样显示；运行时校验才使用 VALUE，并在测试中覆盖名称缺失、循环引用和导入顺序变化。

最后把异常延迟纳入回归测试

至少准备一个前向引用用例、一个故意缺失的类型名用例，以及一个带潜在副作用风险的注解用例。测试不光要断言返回值是否正确，还要确认异常出现在预期的扫描阶段，而不是悄悄在模块导入阶段就抛出。

最小验证：用一个脚本确认三种读取结果

from annotationlib import Format, get_annotations

def show(value: MissingType) -> None:
    pass

for fmt in (Format.FORWARDREF, Format.STRING):
    print(fmt.name, get_annotations(show, format=fmt))

try:
    get_annotations(show, format=Format.VALUE)
except NameError as exc:
    print("VALUE failed as expected:", exc)

运行结果的重点不是某个对象的 repr 长什么样，而是：FORWARDREF 和 STRING 能在名字未就绪时完成扫描，VALUE 会把未解析名字暴露为可处理的异常。把这段脚本放进升级分支的 CI，通常比只跑业务主流程更容易发现兼容问题。

常见问题

Python 3.14 还需要写字符串形式的前向引用吗？

默认延迟求值后，很多场景不再需要手写引号；但项目若仍使用 from __future__ import annotations，字符串注解语义依然存在，不能只因为升级解释器就直接删除。

annotationlib 能完全替代 typing.get_type_hints 吗？

不能简单画等号。annotationlib 主要解决注解读取格式与延迟求值，类型提示归一化、继承合并等需求仍要根据库的实际语义选择接口。

读取注解为什么要做安全审查？

注解求值过程可能访问属性、调用注解函数或者解析前向引用。对于外部提交的字符串或者人工编辑的元数据，不要直接交给运行时解析接口处理。

把迁移范围收窄，验收反而更稳

这次改动的核心不是把所有涉及注解的代码全部重写一遍，而是把读取行为显式化：需要拿到运行时对象就选 VALUE，需要容忍未解析的名字就选 FORWARDREF，只做展示用途就选 STRING；跨版本兼容的库则把读取入口统一放到兼容层。做完这三步，再用前向引用和缺失名称的场景做一轮回归测试，基本就能覆盖最容易踩中的边界情况。