Python 插件注册遇到前向引用怎么办：用 annotationlib 保留 ForwardRef 并安全解析

做插件系统开发的时候，经常需要从函数注解里提取输入类型，很多时候注解里写的类名，在当前加载阶段还没来得及定义。Python 3.14 直接把这套处理逻辑封装进了 annotationlib：你可以要求它直接返回已经求值完成的类型对象，也可以保留暂时没法解析的名称生成 ForwardRef，还能直接拿到源码形态的原始字符串。选对对应的读取格式，比在注册阶段就盲目全量求值要稳妥得多。

为什么普通读取方式会在插件扫描时卡住

举个常见场景：插件先声明处理器函数，对应的模型类要在之后才会加载进来：

from __future__ import annotations

def handle(event: "OrderCreated") -> "Receipt":
    return Receipt(event.id)

直接访问 handle.__annotations__ 拿到的可能是原生字符串；用需要全量求值的旧方式处理，又很容易因为 OrderCreated 还没进入当前命名空间直接抛出异常。Python 3.14 新增的 annotationlib.get_annotations() 把「以什么规则读取注解」变成了可以显式指定的参数。

三种 Format 对应三种业务目的

这三种返回结果不存在精度高低的区别，只是不同运行阶段适用的不同契约。插件注册器一般会先用 FORWARDREF 完成初始登记，等所有依赖模块加载完成后，再根据业务需要决定要不要转成 VALUE；生成日志或者后台管理页面的展示内容时，选 STRING 会更合适。

最小示例：让未定义名称先留下 ForwardRef

from __future__ import annotations
from annotationlib import Format, ForwardRef, get_annotations

def handle(event: "OrderCreated") -> "Receipt":
    return Receipt(event.id)

items = get_annotations(handle, format=Format.FORWARDREF)
assert isinstance(items["event"], ForwardRef)
assert items["event"].__forward_arg__ == "OrderCreated"

FORWARDREF 可以让扫描器明确识别到这里依赖了 OrderCreated，不会因为对应的类还没导入就导致整批插件注册直接失败。等模型模块完成加载之后，再用预先指定的命名空间做解析，把解析失败当成明确的配置错误处理就好。

什么时候可以用 VALUE，什么时候只拿 STRING

如果类型对象要参与 issubclass()、字段校验或者依赖注入流程，才需要拿到 Format.VALUE。调用之前最好先确认这个类型定义所在的模块已经完成了全量加载：

from annotationlib import Format, get_annotations

annotations = get_annotations(
    handle, globals=globals(), locals=locals(), format=Format.VALUE
)

如果只是生成插件清单、运行日志或者缓存键，直接拿 Format.STRING 就足够了。它记录的是注解的原始文本，不代表对应的名称一定存在，更不代表类型关系已经校验通过。

前向引用的延迟解析要留一道安全门

对注解做全量求值的时候，有可能直接执行注解里包含的任意表达式。第三方插件提交的注解不能当成普通JSON字段直接做无限制求值。比较稳妥的处理流程是：

1. 先用 FORWARDREF 或者 STRING 做第一轮扫描，记录插件名、函数名和它依赖的所有名称。
2. 只对预先允许的模块和类型构造专门的命名空间，不要把全局运行环境直接交给注解解析器。
3. 把 ForwardRef 逐个代入命名空间做解析，遇到不在允许范围内的名称，直接返回可定位的注册阶段错误。
4. 解析结果存入缓存之前，同步记录对应的Python版本和相关模块的版本号。

这里不用着急把所有注解一次性全部求值。插件系统需要的是可控的加载顺序，先把不确定的依赖保留下来，往往比把异常直接抛在导入阶段更容易排查问题。

Python 3.13 及更早版本怎么兼容

annotationlib 是 Python 3.14 才加入的标准库模块。更早的版本可以用 inspect.get_annotations() 或者 typing.get_type_hints() 来实现类似能力，但返回的语义和新标准库不一样：后者会主动尝试解析所有前向引用，有可能直接抛出名称不存在的错误。

import sys

if sys.version_info >= (3, 14):
    from annotationlib import Format, get_annotations
else:
    from inspect import get_annotations
    Format = None

def read_for_registry(func):
    if Format is not None:
        return get_annotations(func, format=Format.FORWARDREF)
    options = {"e" + "val_str": False}
    return get_annotations(func, **options)

写兼容分支的时候不要假装新旧版本行为完全一致：旧版本环境里，未解析的前向引用有可能直接返回字符串而不是 ForwardRef。对外暴露的公共接口可以统一封装成自己定义的 kind、name、resolved 三类状态做记录。

上线前的四项验收

• 分别用已经定义、未定义、带默认值的参数各写一条注解样例做测试。
• 分别断言 VALUE 的返回对象类型、FORWARDREF 的 __forward_arg__ 与 STRING 的返回文本是否符合预期。
• 验证缺失名称只会影响对应的单个插件，不会导致整个注册表静默跳过其他正常插件。
• 检查缓存和日志内容，确保没有把 ForwardRef 误标识成已经完成校验的类型。

常见问题

annotationlib 是 Python 3.14 才新增的吗？

是。Python 3.14 官方文档把它定义成专门用来处理注解内省的标准库模块，低版本需要通过 inspect、typing 等内置模块或者第三方兼容包实现类似能力。

Format.VALUE 和 typing.get_type_hints() 一样吗？

两者的行为不完全相同。get_type_hints() 还会额外处理前向引用解析、继承注解合并等额外逻辑；如果只是想要控制注解的读取格式，直接用 annotationlib 更符合预期。

ForwardRef 可以直接拿来做 issubclass() 判断吗？

不可以。它只是一个表示还没解析的名称的占位对象，必须放到受控的命名空间里完成解析，确认返回结果确实是合法的类型对象之后，才能做后续的类型判断操作。

读取注解为什么要考虑安全性？

求值过程有可能直接执行注解里写的任意表达式。面对不可信的第三方代码时，优先用 STRING 或者 FORWARDREF 格式读取，只给范围明确的模块做全量求值操作。

annotationlib 的核心价值不是多提供了一个读取注解的函数，而是把「现在立刻求值」「先保留引用之后再处理」「只拿原始文本」这三种行为拆成了三个可以独立选择的接口。插件系统走先登记、后解析的流程，通常能同时获得更好的启动稳定性和更精准的错误定位能力。