深入理解Python __annotations__属性（小白也能掌握的类型注解与元数据编程指南）

什么是 __annotations__ 属性？

简单来说，__annotations__ 是一个字典（dict），它存储了函数、类或模块中定义的类型注解（Type Annotations）。这些注解不会影响程序的运行逻辑，但可以被工具（如IDE、类型检查器 mypy 等）用来进行静态分析。

例如，当你给函数参数或返回值添加类型提示时，Python 会自动将这些信息保存到该函数的 __annotations__ 属性中。

基本用法示例

下面是一个简单的函数，带有参数和返回值的类型注解：

def greet(name: str, age: int) -> str:    return f"Hello {name}, you are {age} years old."# 查看 __annotations__ 属性print(greet.__annotations__)

运行结果如下：

{'name': <class 'str'>, 'age': <class 'int'>, 'return': <class 'str'>}

可以看到，__annotations__ 是一个字典，键是参数名（包括特殊的 'return' 表示返回值类型），值是对应的类型对象。

在类中使用 __annotations__

不仅函数可以使用类型注解，类中的变量也可以：

class Person:    name: str    age: int    def __init__(self, name: str, age: int) -> None:        self.name = name        self.age = ageprint(Person.__annotations__)

输出：

{'name': <class 'str'>, 'age': <class 'int'>}

注意：这里的 __annotations__ 是属于 类本身 的，而不是实例。

__annotations__ 的实际用途

虽然 __annotations__ 不影响程序执行，但它在以下场景非常有用：

• IDE 智能提示：如 PyCharm、VS Code 可根据注解提供更准确的自动补全。
• 类型检查工具：如 mypy 可静态分析代码是否符合类型规范。
• 自定义框架开发：例如 FastAPI 利用注解来自动生成 API 文档和请求验证逻辑。
• 元数据编程：通过读取 __annotations__ 实现动态行为，比如 ORM 字段映射。

注意事项

• 如果函数没有定义任何注解，__annotations__ 默认是一个空字典 {}，而不是 None。
• 注解可以是任意表达式，不一定是类型。例如：x: "some string" 也是合法的（尽管不推荐）。
• 从 Python 3.7 开始，可以使用 from __future__ import annotations 来启用“延迟求值”，避免前向引用问题。

总结

通过本文，你已经掌握了 Python __annotations__属性 的基本概念、使用方法和实际价值。无论是为了写出更清晰的代码，还是为了参与现代 Python 项目开发，理解类型注解和 __annotations__ 都是必不可少的技能。

记住，Python类型注解 不是为了限制你，而是为了帮助你和你的团队写出更健壮、更易维护的代码。而 __annotations__ 正是这一切背后的“元数据引擎”。

希望这篇教程能让你对 Python函数注解 和 Python元数据编程 有更深的理解！快去试试在你的项目中使用类型注解吧！