Python类型注解核心用法指南

一、前言

在Python开发中，类型注解绝对是提升代码可读性、降低维护成本的高性价比手段——它不影响程序运行，却能让IDE实现智能补全、让同事快速理解代码逻辑，更是dataclass、Pydantic等常用框架的核心依赖。

说到底，Python作为动态类型语言，变量、函数参数的类型全靠“猜测”，这会带来三个核心问题：

• 阅读成本高：需要反复追溯变量用途，才能理解代码逻辑；
• 调试成本高：传参类型错误只有在运行时才会暴露，排查起来相当耗时；
• 开发效率低：IDE无法提供精准补全，写代码基本靠记忆。

而类型注解的核心价值，就是给代码“打标签”——仅做类型提示，不强制校验，却能完美解决上述问题。

二、类型注解核心用法

按使用场景可以划分为变量的类型注解、函数类型注解、类的类型注解。

2.1 变量类型注解

先看最基本的用法，覆盖全局变量、函数内局部变量，语法统一且简单。重点在于区分“有无默认值”的差异。

• 无默认值的注解（如 age: int）仅存元数据，不会创建变量，未赋值直接使用会报错；
• 有默认值的注解，同时完成了“类型标记”和“变量赋值”，变量可以正常使用；
• 注解不强制类型匹配（如 age: int = "20" 也能运行），仅起提示作用。

# 无默认值（仅标记类型，不创建变量）
变量名: 类型
# 有默认值（标记类型+赋值，注解与变量共存）
变量名: 类型 = 默认值

age:int = 19
# 合法：只声明类型，不赋值
name: str
# 此时变量还不存在，直接用会报错
# print(name)  # NameError
# 赋值后，变量才真正存在
name = "张三"
print(name)  # 正常运行

2.2 函数类型注解

这部分重点标注「参数类型」和「返回值类型」，让函数用途、输入输出一目了然，大大降低沟通成本。

• 无返回值最好写 -> None，省略会导致IDE提示异常；
• *args 注解标注“元素类型”（如 *args: int 表示所有可变位置参数都是整数）；
• **kwargs 注解标注“值的类型”（如 **kwargs: str 表示所有关键字参数的值为字符串）。

# 仅参数注解
def 函数名(参数1: 类型, 参数2: 类型 = 默认值):
    pass
# 参数+返回值注解（-> 标识返回类型）
def 函数名(参数1: 类型, 参数2: 类型) -> 返回值类型:
    pass

def add(a: int, b: int) -> int:
    return a + b
# 无返回值（必须写 -> None，不可省略）
def log(msg: str) -> None:
    print(f"日志：{msg}")
# 可变参数注解（指定内部元素类型）
def sum_numbers(*args: int, **kwargs: str) -> list[int]:
    return list(args)

2.3 类的类型注解（dataclass 依赖）

这里专门用于标记「实例属性」类型，分三种形态。核心在于区分“注解”与“类属性”的关系，也是dataclass框架的核心依赖。

• 纯注解（如 name: str）不生成类属性，仅存入 __annotations__，用于标记未来实例的属性类型；
• 注解+默认值（如 email: str | None = None），一行完成“类型标记+类属性赋值”；
• dataclass正是通过读取 __annotations__，自动生成 __init__、__repr__ 等方法，无需手动编写；
• 实例化后，注解标记的属性会成为实例属性，优先覆盖同名类属性。

class 类名:
    # 1. 纯注解（仅标记实例属性类型，无类属性）
    属性名1: 类型
    # 2. 注解+默认值（标记类型+创建类属性，供实例继承默认值）
    属性名2: 类型 = 默认值
    # 3. 普通类属性（无注解，不进入__annotations__）
    属性名3 = 默认值

class User:
    # 纯注解：仅标记实例属性类型，无类属性
    name: str
    age: int
    # 注解+默认值：有类型标记，同时创建类属性（默认值）
    email: str | None = None  # 实例可覆盖该默认值
    gender: str = "未知"
    # 普通类属性：无注解，不进入__annotations__，所有实例共享
    address = "北京"
# 验证注解存储（仅包含带注解的属性）
print(User.__annotations__)
# 输出：{'name': str, 'age': int, 'email': str | None, 'gender': str}

三、类型注解元数据的存储机制

Python内部做了这么一件事——它会自动将所有类型注解收集到一个特殊的 __annotations__ 字典中。这个字典的本质就是一个普通字典，键是注解标记的对象名称（变量名、函数参数名、类属性名等），值是对应的类型（如 str、int、list[int] 等），供框架、工具读取使用。

3.1 不同场景下的元数据存储

注解元数据的存储位置，会随着注解场景（变量、函数、类）不同而有所差异。

模块级变量注解存储

全局（模块级）变量的注解，会存储在当前模块对象的 __annotations__ 字典中。

# 模块级变量注解
name: str = "张三"
age: int = 20
score: float | None = 95.5
# 查看模块级注解元数据
print(__annotations__)
# 输出：{'name': str, 'age': int, 'score': float | None}

函数注解存储

函数的注解（参数注解、返回值注解），会存储在函数对象的 __annotations__ 字典中。注意，返回值注解会单独对应键 “return”，参数注解对应各自的参数名。

def add(a: int, b: int) -> int:
    return a + b
# 查看函数注解元数据
print(add.__annotations__)
# 输出：{'a': int, 'b': int, 'return': int}
# 可变参数注解的存储
def sum_numbers(*args: int, **kwargs: str) -> list[int]:
    return list(args)
print(sum_numbers.__annotations__)
# 输出：{'args': int, 'kwargs': str, 'return': list[int]}

类注解存储

类内的属性注解（纯注解、注解+默认值），会存储在类对象的 __annotations__ 字典中（普通类属性无注解，不存入）；实例对象本身没有 __annotations__，其注解信息继承自所属类。

class User:
    name: str  # 纯注解
    age: int   # 纯注解
    email: str | None = None  # 注解+默认值
    gender: str = "未知"       # 注解+默认值
    address = "北京"          # 无注解，不存入
# 查看类的注解元数据
print(User.__annotations__)
# 输出：{'name': str, 'age': int, 'email': str | None, 'gender': str}
# 实例无__annotations__，继承类的注解信息
u = User()
print(hasattr(u, "__annotations__"))  # 输出：False

3.2 关键注意点

• __annotations__ 是动态可变的：可以手动修改该字典，修改后会影响框架、工具对注解的读取（但不推荐手动修改，容易造成混乱）；
• 无默认值的变量注解，仅存入 __annotations__，不创建变量（比如 age: int 仅在 __annotations__ 中有记录，未赋值则变量不存在）；
• 框架依赖：dataclass、Pydantic 等框架，核心就是通过读取 __annotations__ 字典，实现属性校验、自动生成方法等功能。

四、常用类型简写