Python 自 3.5 引入 类型注解（Type Hints），让开发者在动态语言中也能写出带类型提示的代码。许多人知道 def foo(x: int) -> str: 这种写法，但往往忽略了背后的 __annotations__ 属性，它不仅能记录类型信息，还能做很多有趣的事情。本文将带你从基础理解到高级妙用。

一、什么是 __annotations__？

每个函数、类甚至模块在定义类型注解后，Python 会自动把这些信息存储在 __annotations__ 属性中。

示例

输出：

解释：__annotations__ 是一个字典，记录了参数名和返回值对应的类型。

二、类型注解的基本作用

提升可读性：让别人一眼就知道函数期望的参数类型和返回类型。静态类型检查：配合 mypy、pyright 等工具进行静态分析，提前发现类型错误。IDE 支持：让 PyCharm、VSCode 等智能提示更精准。

但很多人不知道，__annotations__ 可以在运行时被访问和使用，这才是妙用所在。

三、__annotations__ 的实战妙用

1. 自动参数校验

利用 __annotations__ 可以在函数运行时做类型检查，避免手动写大量 if-else 判断。

小结：通过 __annotations__，你可以动态获取类型信息并在运行时做验证，实现“轻量型类型检查”。

2. 动态生成 API 文档

如果函数都有类型注解，可以自动生成文档，而无需手动维护。

输出：

这样在大型项目里，文档可以自动从类型注解生成，减少人工维护成本。

3. 数据校验与自动化工具

在构建 Web API、数据处理管道 时，__annotations__ 可以作为动态校验的基础：

经验分享：在 FastAPI、Pydantic 等现代框架里，类型注解配合运行时校验几乎是标配，而 __annotations__ 就是底层原理之一。

4. 元编程与动态函数生成

__annotations__ 还可以与 装饰器 或 工厂函数 结合，实现动态代码生成或参数注入。

输出：

这样可以在运行时自动记录参数类型信息，非常适合做调试、日志或者监控。

四、类型注解 + __annotations__ 的拓展使用场景

自动表单生成：根据函数或类的类型注解生成前端表单字段类型。自动序列化/反序列化：结合 dataclasses 或 pydantic，可以根据注解动态生成 JSON 序列化规则。插件系统：在大型框架中，根据类型注解动态注册处理函数或策略。

五、经验总结

__annotations__ 不只是文档或 IDE 提示，它是 运行时可访问的元信息。动态类型检查、自动文档生成、API 校验、元编程等，都可以依赖它。在实际项目中，合理利用 __annotations__ 可以 提升代码可靠性、减少重复工作、增强自动化能力。

六、结语

Python 的动态特性很强，但同时也容易出现类型混乱。类型注解结合 __annotations__，既保留了 Python 灵活性，又带来了可读性、可检查性和自动化能力。

小结一句话：类型注解是静态世界的提示，__annotations__ 是动态世界的利器。合理使用它，你的代码将更安全、更可维护、更智能。