类型注解Type Annotation和运行时反射Runtime Reflection是现代 Python 工程的两块基石。前者让代码会说话后者让程序在运行时照镜子。两者结合催生了 Pydantic、FastAPI、dataclasses 这类改变 Python 生态的框架。理解它们是从能写 Python到会设计 Python 系统的关键一跃。一、类型注解代码的说明书它到底是什么Python 本质上是动态类型语言——变量没有固定类型。但从 Python 3.5 起PEP 484 引入了类型注解语法允许开发者在代码里标注变量、参数、返回值的期望类型def greet(name: str, times: int 1) - str: return (fHello, {name}! * times).strip()这里的: str、: int、- str就是类型注解。关键点Python 解释器本身不强制执行这些注解它们只是元数据存储在对象的__annotations__属性里。真正的类型检查由 mypy、pyright 等静态分析工具或 Pydantic 这类运行时库来完成。__annotations__的本质每个函数、类都有一个__annotations__字典def add(x: int, y: int) - int: return x y print(add.__annotations__) # {x: class int, y: class int, return: class int}类也一样class Point: x: float y: float label: str origin print(Point.__annotations__) # {x: class float, y: class float, label: class str}这个字典是运行时反射的入口——所有框架魔法的起点。二、typing模块构建复杂类型的工具箱typing模块提供了远超内置类型的表达能力核心概念如下泛型容器from typing import List, Dict, Tuple, Set def process(items: List[int]) - Dict[str, int]: return {str(i): i for i in items}Python 3.9 可以直接用内置类型list[int]、dict[str, int]不再需要从typing导入。联合类型与可选类型from typing import Union, Optional # Union可以是 int 或 str def parse(value: Union[int, str]) - str: return str(value) # Optional[X] 等价于 Union[X, None] def find_user(user_id: Optional[int] None) - Optional[str]: ...Python 3.10 引入了更优雅的写法int | str、int | None。TypeVar泛型函数from typing import TypeVar, List T TypeVar(T) def first(items: List[T]) - T: return items[0]TypeVar让函数能保留类型信息——输入List[int]返回值也知道是int而不是模糊的Any。Literal、Final、TypedDictfrom typing import Literal, Final, TypedDict # Literal限定为特定值 Mode Literal[read, write, append] # Final声明常量 MAX_RETRY: Final 3 # TypedDict带类型的字典结构 class UserInfo(TypedDict): name: str age: int email: strProtocol结构子类型鸭子类型的类型化from typing import Protocol class Drawable(Protocol): def draw(self) - None: ... class Circle: def draw(self) - None: print(Drawing circle) def render(shape: Drawable) - None: shape.draw() render(Circle()) # ✅ 无需继承 Drawable只要有 draw 方法即可Protocol是 Python 类型系统里最优雅的设计之一完美契合 Python 的鸭子类型哲学。三、运行时反射程序的自我审视typing.get_type_hints()正确读取注解的方式直接读__annotations__有个大坑——前向引用Forward Referenceclass Node: next: Node # 用字符串避免循环引用 print(Node.__annotations__) # {next: Node} ← 只是字符串不是真正的类型get_type_hints()会自动解析这些字符串引用返回真实的类型对象from typing import get_type_hints hints get_type_hints(Node) # {next: class __main__.Node} ← 真正的类型这正是 Pydantic 等框架在底层做的事情。inspect模块深度解剖对象inspect是 Python 自省Introspection的瑞士军刀核心 API 一览import inspect # 1. 获取函数签名 def create_user(name: str, age: int, admin: bool False) - dict: ... sig inspect.signature(create_user) for param_name, param in sig.parameters.items(): print(f{param_name}: 注解{param.annotation}, 默认值{param.default}) # 输出 # name: 注解class str, 默认值class inspect._empty # age: 注解class int, 默认值class inspect._empty # admin: 注解class bool, 默认值False# 2. 获取类的成员 class MyClass: class_var: int 0 def method(self): ... staticmethod def static_method(): ... # 过滤出所有方法 methods inspect.getmembers(MyClass, predicateinspect.isfunction) # 3. 判断对象类型 inspect.isclass(MyClass) # True inspect.isfunction(create_user) # True inspect.ismethod(obj.method) # True绑定方法 # 4. 获取源码 print(inspect.getsource(create_user)) # 5. 获取调用栈 frame inspect.currentframe() print(inspect.getframeinfo(frame))四、两者结合框架魔法的底层逻辑理解了注解和反射很多魔法框架就不再神秘。下面用一个简化的依赖注入容器演示import inspect from typing import get_type_hints, Callable, Any, Dict, Type class Container: 极简依赖注入容器 _registry: Dict[type, Any] {} classmethod def register(cls, service_type: type, instance: Any): cls._registry[service_type] instance classmethod def resolve(cls, func: Callable) - Any: hints get_type_hints(func) sig inspect.signature(func) kwargs {} for param_name, param in sig.parameters.items(): if param_name return: continue param_type hints.get(param_name) if param_type and param_type in cls._registry: kwargs[param_name] cls._registry[param_type] return func(**kwargs) # 使用 class Database: def query(self): return data class UserService: def __init__(self, db: Database): self.db db Container.register(Database, Database()) # 框架自动识别 UserService.__init__ 需要 Database并注入FastAPI 的路由参数解析、Pydantic 的模型验证本质上都是这套机制的工业级实现。五、核心概念关系图六、工程实践该怎么用怎么避坑✅ 该做的渐进式引入注解不必一次全加从公共 API、核心数据结构开始标注收益最大。用get_type_hints()而非直接读__annotations__前者能正确处理from __future__ import annotationsPython 3.10 的延迟求值模式带来的字符串化注解问题。善用inspect.signature()做参数校验写工具函数、装饰器时用签名反射来动态适配不同函数比硬编码参数名健壮得多。Protocol优于抽象基类当你只关心对象能做什么而非对象是什么时Protocol更灵活也更 Pythonic。⚠️ 要注意的注解不等于运行时约束def f(x: int)传入字符串不会报错需要 Pydantic 或手动校验才能在运行时强制类型。from __future__ import annotations的副作用开启后所有注解变成字符串__annotations__里看不到真实类型必须用get_type_hints()解析且解析时需要正确的命名空间。inspect有性能开销getmembers、getsource等操作涉及文件 I/O 或大量遍历不要在热路径高频调用的代码里使用适合初始化阶段或调试工具。循环引用问题类互相引用时get_type_hints()可能抛出NameError需要传入正确的localns/globalns参数hints get_type_hints(MyClass, globalnsglobals(), localnslocals())七、一张表总结核心 API工具核心 API典型用途typingList,Dict,Optional,Union标注容器与可选类型typingTypeVar,Generic编写泛型函数/类typingProtocol定义结构化接口typingget_type_hints()运行时安全读取注解inspectsignature()获取函数参数及默认值inspectgetmembers()枚举类/模块的所有成员inspectisclass()/isfunction()判断对象类型inspectgetsource()获取源码文本调试用类型注解和运行时反射本质上是 Python 在动态灵活与工程可靠之间找到的平衡点。注解让意图可见反射让框架智能两者叠加才有了今天 Python 生态里那些写起来像魔法、用起来很踏实的工具。掌握这套机制你就掌握了读懂 FastAPI、Pydantic、SQLModel 等现代框架源码的钥匙。