本文介绍如何通过 `__metadata__` 属性安全、准确地访问 `typing.annotated` 类型注解中嵌入的自定义对象（如文档类、验证器或配置实例），避免字符串化陷阱，实现运行时元数据读取与使用。
在 Python 3.9+ 中，typing.Annotated 提供了一种为类型添加任意元数据的标准化方式。它不仅支持类型检查器识别基础类型（第一个参数），还将后续所有参数统一存储在 __metadata__ 元组中——这正是提取自定义对象（如文档类、校验规则或配置实例）的关键入口。
以下是一个完整示例，展示如何从 Annotated 注解中获取并使用元数据：
from typing import Annotated, get_args
import inspect
from dataclasses import dataclass
@dataclass
class Doc:
description: str
required: bool = True
@dataclass
class A:
name: Annotated[str, Doc("用户姓名", required=True)]
age: Annotated[int, Doc("用户年龄", required=False), "unit: years"]
# 获取运行时注解（自动求值字符串化注解）
annotations = inspect.get_annotations(A, eval_str=True)
# 提取 'name' 字段的 Annotated 类型
annotated_type = annotations["name"]
# ✅ 正确方式：访问 __metadata__ 属性（返回 tuple）
metadata = annotated_type.__metadata__
print(metadata) # (Doc(description='用户姓名', required=True),)
# 获取第一个元数据对象（通常为文档类）
doc_obj = metadata[0]
print(doc_obj.description) # 输出：用户姓名
# 同样适用于多参数场景（如 age 字段）
age_annotated = annotations["age"]
print(age_annotated.__metadata__) # (Doc(description='用户年龄', required=False), 'unit: years')⚠️ 注意事项：
- __metadata__ 是 Annotated 的只读公有属性，由标准库保证存在，无需导入额外模块；
- inspect.get_annotations(..., eval_str=True) 是关键：若注解以字符串形式存在（如 Annotated["str", ...]），必须启用 eval_str=True 才能获得真实类型对象，否则 __metadata__ 不可用；
- 不要尝试用 getattr(annotated_type, '__args__', []) 或 get_args() 替代 __metadata__——get_args(Annotated[T, x, y]) 返回 (T, x, y)，会混入基础类型，而 __metadata__ 精确排除第一个参数，语义更清晰、更安全；
- 元数据对象本身需支持序列化/持久化（如 dataclass 或 NamedTuple），若含不可序列化状态（如 lambda、文件句柄），将影响调试与文档生成。
总结：Annotated[T, meta1, meta2].__metadata__ 是官方推荐、稳定可靠的元数据访问机制，适用于构建类型驱动的文档生成器、参数校验框架或 API 描述工具。掌握它，即可将类型注解真正转化为可执行的程序逻辑与用户友好的上下文信息。
立即学习“Python免费学习笔记（深入）”；
