一、类型注解学习笔记

type

Post

status

Published

date

Feb 21, 2026

slug

python-type-annotations-study-notes-1

summary

有些情况下,没有报错,能够运行但是拿到的数据是不对的.搞不清变量是什么类型，传参时就会经常传错。用了类型注解后，IDE 能自动提示，错误能提前发现，代码可读性也大大提高了！

1. 什么是类型注解？

类型注解是给变量、函数参数、返回值添加类型说明的语法。

📝 我的理解：类型注解就像是给变量贴标签——虽然 Python 不会强制检查，但 IDE 和类型检查工具能看懂，帮你提前发现错误。

2. 基本类型注解

2.1 常用内置类型

📝 我的理解：基本类型就像是基础积木——str、int、float、bool 是最常用的，list、dict、set、tuple 是容器积木。

2.2 可选类型（Optional）

📝 我的理解：Optional[str] 就像是二选一——要么是有值的字符串，要么是空（None）。

2.3 联合类型（Union）

📝 我的理解：Union[int, str] 就像是多选一——变量可以是整数，也可以是字符串，甚至可以是更多类型之一。

3. 函数类型注解

3.1 参数和返回值注解

📝 我的理解：函数类型注解就像是函数签名——看一眼就知道要传什么参数，会返回什么结果。

3.2 返回 None 的函数

📝 我的理解：-> None 明确表示这个函数不返回有用的值，只是执行操作（如打印、保存等）。

3.3 返回复杂类型的函数

📝 我的理解：复杂返回类型就像是快递单——清楚地标明包裹里装的是什么，方便接收方处理。

4. 高级类型注解

4.1 类型别名（Type Alias）

📝 我的理解：类型别名就像是起外号——dict[str, str | int] 太长，就叫它 Student，既简洁又表意。

4.2 泛型函数

📝 我的理解：泛型就像是万能模板——写一次代码，可以处理任意类型，不用为每种类型都写一遍。

4.3 Callable 类型（函数作为参数）

📝 我的理解：Callable[[int, int], int] 就像是函数说明书——说明这个参数是一个函数，它接收什么参数，返回什么值。

5. 类类型注解

5.1 类属性注解

📝 我的理解：类类型注解就像是班级花名册——每个同学（属性）都标明了类型，一目了然。

5.2 自引用类型

📝 我的理解：自引用类型就像是套娃——类里可以引用自己，比如链表、树结构都需要这样定义。

6. 类型检查工具

6.1 mypy 类型检查器

6.2 常见类型错误

⚠️ 注意：Python 运行时不会检查类型注解，需要用 mypy 等工具进行静态检查！

7. 踩坑记录

7.1 忘记导入类型

⚠️ 踩坑：使用 Optional、Union、Callable 等类型时，记得从 typing 模块导入！

7.2 循环导入问题

⚠️ 踩坑：两个模块互相引用时，用 from __future__ import annotations 启用延迟求值，类型注解用字符串形式。

7.3 可变类型默认值

⚠️ 踩坑：带类型注解的函数也要注意可变类型不能作为默认值！

8. 核心知识点整理

8.1 类型注解速查表

类型	注解	示例
字符串	`str`	`name: str = "张三"`
整数	`int`	`age: int = 18`
浮点数	`float`	`height: float = 175.5`
布尔	`bool`	`is_ok: bool = True`
列表	`list[T]`	`scores: list[int] = [1, 2, 3]`
字典	`dict[K, V]`	`info: dict[str, str] = {}`
元组	`tuple[T, ...]`	`point: tuple[int, int] = (0, 0)`
集合	`set[T]`	`ids: set[int] = {1, 2}`
可选	`T \\| None`	`name: str \\| None = None`
联合	`T1 \\| T2`	`data: int \\| str = 1`

8.2 函数注解模板

8.3 需要注意下

从简单开始：先给函数参数和返回值加注解

渐进式添加：不需要一次性给所有代码加注解

配合工具使用：用 mypy 检查类型错误

不要过度：简单的脚本可以不写类型注解