Python 3.14 annotationlib.get_annotations 怎么读延迟注解：VALUE、FORWARDREF 与安全边界

升级到 Python 3.14 后，类型注解不一定在函数定义那一刻就变成最终对象。做插件注册、参数文档或运行时检查时，直接读取注解字典，可能遇到未定义的前向引用，也可能意外触发注解表达式。annotationlib.get_annotations() 的价值在于把“我要什么形态的注解”明确写出来：要运行时对象就用 VALUE，要尽量保留未解析名称就用 FORWARDREF，只做展示就用 STRING。

先把三种读取结果放在同一个例子里

下面这个函数故意引用一个尚未定义的类型名。它更接近插件系统里的真实场景：先声明接口，具体的实现类型可能由后续加载的模块补充提供。

from __future__ import annotations

def register(payload: "PluginPayload", retries: int) -> "PluginResult":
    return payload

在 Python 3.14 中，读取者可以明确选择格式，而不是猜测 __annotations__ 当前保存的内容：

from annotationlib import Format, get_annotations

values = get_annotations(register, format=Format.VALUE)
refs = get_annotations(register, format=Format.FORWARDREF)
source_like = get_annotations(register, format=Format.STRING)

VALUE 会尝试得到真正的对象；如果 PluginPayload 尚未进入可用命名空间，读取可能抛出名称相关异常。FORWARDREF 则尽可能解析已知对象，把未解析项保留为 ForwardRef。STRING 更像面向文档的展示结果，适合生成参数说明。

插件注册先选 FORWARDREF，再决定是否加载

做插件扫描的场景下，通常只需要确认两个信息：目标对象有没有声明对应接口、接口的名称是否符合记录要求。如果为了拿到完整的类型对象就立刻触发注解求值，反而会因为插件还没加载完全部依赖，误判成插件注册失败。

from annotationlib import Format, ForwardRef, get_annotations

def inspect_plugin(fn):
    annotations = get_annotations(fn, format=Format.FORWARDREF)
    result = {}
    for name, value in annotations.items():
        if isinstance(value, ForwardRef):
            result[name] = {"kind": "unresolved", "name": value.__forward_arg__}
        else:
            result[name] = {"kind": "resolved", "type": value}
    return result

这里的重点不是把 ForwardRef 立刻变成类型，而是把它当作扫描结果的一部分。注册阶段可以保存名称、提示缺少哪个模块；等依赖准备好后，再在受信任的加载路径中做一次明确求值。

为什么不直接调用 get_type_hints

typing.get_type_hints() 更偏向“给我最终可用的类型提示”，适合类型检查辅助和运行时确实需要类型对象的代码。插件发现阶段的目标不同：先盘点声明，再处理依赖。把两个阶段混在一起，日志里就很难区分“插件写错了”和“插件还没加载完”。

文档生成用 STRING，但要保留信任边界

参数文档通常希望展示接近源代码的注解，而不是输出某个运行时类的内部表示。STRING 在这个场景下更顺手：

from annotationlib import Format, get_annotations

def build_parameter_docs(fn):
    annotations = get_annotations(fn, format=Format.STRING)
    return [f"{name}: {value}" for name, value in annotations.items()]

但“返回字符串”不等于“读取过程不会执行任何代码”。注解表达式本身可能包含属性访问、函数调用或其他表达式；官方文档明确提醒，注解内省的大部分能力都可能执行任意代码。文档生成器面对第三方插件时，应该在隔离进程或受控导入环境中工作，不能把 STRING 当成安全沙箱。

把格式选择写进代码的检查点

如果应用兼容 Python 3.13 及更早版本，不要无条件导入 annotationlib。可以把导入放在兼容层，并用 inspect.get_annotations() 或 typing-extensions 的对应能力作为旧版本路径；关键是不要让兼容代码悄悄改变“是否求值”的安全策略。

常见问题：延迟注解的几个边界

FORWARDREF 会保证完全不执行注解表达式吗？

不会。它可以为未定义的名称保留前向引用标识，但复杂的表达式依然有可能在读取阶段触发异常、执行额外逻辑。面对不可信代码，做好运行环境隔离远比单纯选注解格式来得稳妥。

STRING 结果可以直接写入缓存吗？

可以把获取到的注解文本作为展示层缓存使用，但要明确它只是当前代码环境下的描述信息，不要直接拿缓存下来的文本反向执行，也不能依据缓存结果默认所有依赖都已经加载完成。

什么时候应该使用 VALUE？

等后续业务逻辑确实需要调用类型对象、读取它的属性或者做运行时适配的时候再用。提前准备好完整的导入环境，捕获所有解析失败的情况，抛出可定位的错误提示。

最后的落地建议

把注解读取拆成“发现、解析、展示”三个动作，格式选择就会清楚很多：发现阶段保留未知，解析阶段在可信环境中求值，展示阶段只生成面向读者的文本。Python 3.14 的 annotationlib 提供了更细的控制，但它并没有替应用替代权限边界和隔离策略。