本文介绍如何通过 __metadata__ 属性安全、标准地提取 typing.annotated 类型注解中携带的自定义元数据（如文档对象、校验规则或配置实例），避免字符串化陷阱，实现运行时类型增强功能。
在 Python 3.9+ 中，typing.Annotated 提供了一种标准化方式，为类型添加任意元数据（metadata），而这些元数据在运行时并非被丢弃或转为字符串，而是以元组形式完整保留在类型对象的 __metadata__ 属性中。这使得你可以在反射（reflection）场景下（如自动生成 API 文档、参数校验、序列化配置等）可靠地访问它们。
以下是一个完整示例，展示如何从 Annotated[str, B(x="foo")] 中提取并使用 B 实例：
from typing import Annotated, get_args
import inspect
from dataclasses import dataclass
@dataclass
class B:
x: str
@dataclass
class A:
y: Annotated[str, B(x="foo"), "This is a user-facing description"]
# 获取运行时解析后的注解字典（推荐：使用 get_type_hints 或 inspect.get_annotations）
annotations = inspect.get_annotations(A, eval_str=True)
annotated_type = annotations["y"]
# ✅ 正确方式：访问 __metadata__ 属性（标准、稳定、无需解析字符串）
if hasattr(annotated_type, "__metadata__"):
metadata = annotated_type.__metadata__ # 类型：tuple
print("Metadata tuple:", metadata) # 输出: (B(x='foo'), 'This is a user-facing description')
# 提取第一个元数据项（即 B 实例）
if metadata and isinstance(metadata[0], B):
b_instance = metadata[0]
print("B.x =", b_instance.x) # 输出: B.x = foo
# 可遍历所有元数据（支持多个标签）
for i, item in enumerate(metadata):
print(f"Metadata[{i}]: {type(item).__name__} = {item}")⚠️ 重要注意事项：
- ❌ 不要尝试用 str()、正则或 eval() 解析 repr(annotated_type) —— 这是脆弱且不安全的；
- ✅ __metadata__ 是官方定义的公有协议属性（见 Python 官方文档），保证在所有兼容实现中可用；
- ? 若需获取原始 Annotated 的所有参数（包括基础类型），可使用 get_args(annotated_type)，它返回 (str, B(x="foo"), "description")；但 __metadata__ 更语义明确，专用于元数据；
- ? inspect.get_annotations(..., eval_str=True) 是推荐方式，确保字符串化注解（如 "str"）被正确求值，避免 ForwardRef 问题。
总结来说，Annotated[T, meta1, meta2] 的设计初衷就是支持运行时元编程——__metadata__ 就是你通往类型“附加信息”的标准接口。善用它，即可构建类型驱动的文档生成器、验证框架或配置绑定系统，真正实现「类型即配置」。
立即学习“Python免费学习笔记（深入）”；
