Python 类型注解核心用法指南_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__ 字典，实现属性校验、自动生成方法等功能。

四、常用类型简写

类型场景	注解写法（3.10+）	说明
基础类型	int/str/bool/float/none	最常用、最基础的类型
联合类型	str \| int、str \| none	多类型二选一（3.10+ 语法）
容器类型	list[int]、dict[str, int]	列表（整数元素）、字典（字符串键+整数值）
任意类型	any（需导入 from typing import any）	不限制类型，尽量少用，避免失去注解意义
元组类型	tuple[int, str]	固定长度、固定元素类型的元组（如 (1, “a”)）