Python typing.Annotated 的元数据怎么在运行时读取

如果你在运行时读取 Python 的类型注解，直接调用 get_type_hints() 往往只能看到 int、str 这样的基础类型。原因不是 Annotated 丢了，而是这个函数默认会移除额外元数据。把调用改成 get_type_hints(target, include_extras=True)，再从返回的 Annotated 对象读取 __metadata__，即可拿到原始标记。

官方文档：https://docs.python.org/3/library/typing.html

先复现：默认读取为什么只剩基础类型

先定义一个带业务标记的函数。这里的字符串和字典只是示例元数据，真正的解释规则仍由你的框架或工具决定。

from typing import Annotated, get_type_hints

def create_user(user_id: Annotated[int, "主键", {"positive": True}],
               email: Annotated[str, "邮箱格式"]) -> None:
    # 函数体不负责校验；本例只观察注解在运行时的形态。
    pass

plain = get_type_hints(create_user)
full = get_type_hints(create_user, include_extras=True)

print(plain["user_id"])              # 
print(full["user_id"])               # typing.Annotated[int, '主键', {'positive': True}]
print(full["user_id"].__metadata__)  # ('主键', {'positive': True})

plain 适合只关心类型检查的场景；反射式参数校验、接口文档或依赖注入工具则必须使用 full。注意，Annotated 里的元数据不会自动触发校验，工具需要自己约定如何解释它。

用 include_extras 让元数据留在运行时

get_type_hints() 会返回一个以参数名为键的字典。对函数、方法或类读取时，先开启 include_extras=True，再判断某个值的外层是否为 Annotated。

from typing import Annotated, get_args, get_origin, get_type_hints

def read_annotated(target: object) -> list[dict[str, object]]:
    # 返回每个 Annotated 参数的基础类型和元数据，便于后续工具消费。
    hints = get_type_hints(target, include_extras=True)
    found = []
    for name, annotation in hints.items():
        if get_origin(annotation) is not Annotated:
            continue
        base, *metadata = get_args(annotation)
        found.append({
            "name": name,
            "base": base,
            "metadata": tuple(metadata),
        })
    return found

for item in read_annotated(create_user):
    # 业务层可以按元数据类型分派，而不是依赖字符串格式猜测。
    print(item["name"], item["base"], item["metadata"])

这里用 get_args() 拆分更适合通用代码：第一个参数是被注解的类型，后面的参数按原顺序组成元数据。若只需要快速读取，也可以直接访问 annotation.__metadata__。

区分原始类型、容器和嵌套元数据

最容易混淆的是 get_origin() 和 __origin__：对 Annotated[int, ...] 来说，前者返回 Annotated，后者返回 int。不要用 get_origin(annotation) is int 判断基础类型。

当注解是 list[Annotated[int, "编号"]] 时，最外层是 list，不能在第一层直接取 __metadata__。应先用 get_args() 取得列表元素，再递归检查元素注解：

from typing import Any, Annotated, get_args, get_origin

def collect_metadata(annotation: Any) -> list[tuple[Any, tuple[Any, ...]]]:
    # 递归穿过 list、dict 等容器，只收集实际出现的 Annotated 层。
    if get_origin(annotation) is Annotated:
        args = get_args(annotation)
        return [(args[0], tuple(args[1:]))]
    result = []
    for child in get_args(annotation):
        result.extend(collect_metadata(child))
    return result

嵌套的 Annotated 会被 Python 展平，元数据顺序从内层开始；重复的元数据不会自动去重。业务代码不要假设元数据一定是字符串，也不要擅自改变其顺序。

把读取逻辑封装起来，再处理真实项目边界

项目里建议把反射集中在一个小函数中：统一开启 include_extras，统一返回结构，并对前向引用解析失败保留清晰异常。get_type_hints() 可能执行注解中的表达式，因此不要对不可信对象随意反射。

from typing import Annotated, get_origin, get_type_hints

def describe_target(target: object) -> list[dict[str, object]]:
    # 集中处理反射，调用方只消费稳定的数据结构。
    hints = get_type_hints(target, include_extras=True)
    result = []
    for name, annotation in hints.items():
        if get_origin(annotation) is Annotated:
            result.append({
                "name": name,
                "annotation": annotation,
                "base_type": annotation.__origin__,
                "metadata": annotation.__metadata__,
            })
    return result

如果代码使用 from __future__ import annotations 或字符串形式的前向引用，确保相关名称在可解析的全局或局部命名空间中。读取类时还要记住，get_type_hints() 会合并继承链上的类注解；如果只想看当前类的原始字典，应另行读取 __annotations__，但那样不会替你解析前向引用。

相关问题

Annotated 会自动检查值是否符合元数据吗？

不会。它只把额外信息附着到类型上，校验规则需要由你或使用它的库实现。

为什么 get_origin(Annotated[int, "id"]) 不是 int？

因为 get_origin() 返回的是最外层构造 Annotated；要取被包裹的 int，使用 __origin__ 或 get_args() 的第一个元素。

元数据只有一个字符串吗？

不是。Annotated 支持多个元数据项，__metadata__ 返回按声明顺序排列的元组，工具应自行决定哪些项有意义。

实际排查时可以记成一句话：先用 include_extras=True 保留信息，再用 get_origin() 判断包装层，最后用 get_args() 或属性读取基础类型与元数据。这样既不会把注解当成运行时校验器，也能给反射工具留下稳定入口。