Python 类型注解：从能跑到优雅

更新: 1/28/2026字数: 0 字 时长: 0 分钟

Python 是动态语言，但这并不意味着你只能“随缘写代码”。

从 Python 3.5 开始，类型注解（Type Hints） 正式进入语言核心。 它不影响运行时，却能极大提升：

• 可读性
• IDE 智能提示
• 静态检查能力
• 大型项目的可维护性

一、什么是 Python 类型注解？

最直观的理解：

给变量、函数参数、返回值“贴标签”，告诉人和工具：这是什么类型

def add(a: int, b: int) -> int:
    return a + b

• a: int：参数类型
• -> int：返回值类型

⚠️ 重要：类型注解不会影响运行

add("1", "2")  # 运行时不会报错

Python 解释器不会检查类型，检查的是工具（IDE / mypy / pyright）。

二、为什么要写类型注解？

1️⃣ IDE 智能提示直接起飞 🚀

def get_name(user: dict) -> str:
    return user["name"]

IDE 能帮你：

• 自动补全
• 参数提示
• 重构安全

2️⃣ 提前发现 bug（静态检查）

def sum_list(nums: list[int]) -> int:
    return sum(nums)

sum_list(["1", "2"])  # ❌ 静态检查直接报错

运行前就能发现问题，而不是等到线上炸。

3️⃣ 大型项目必备（尤其是多人协作）

• 不用翻实现
• 看签名就知道怎么用
• 类似 TypeScript 对 JavaScript 的价值

三、基础类型注解

1️⃣ 内置基础类型

name: str = "Alice"
age: int = 18
height: float = 1.72
is_admin: bool = False

2️⃣ 容器类型（Python 3.9+ 推荐写法）

numbers: list[int] = [1, 2, 3]
user: dict[str, str] = {"name": "Tom"}
tags: set[str] = {"python", "typing"}
point: tuple[int, int] = (10, 20)

👉 Python 3.9 之前写法

from typing import List, Dict, Tuple

numbers: List[int]

四、函数类型注解（重点）

1️⃣ 参数 + 返回值

def greet(name: str) -> str:
    return f"Hello {name}"

2️⃣ 没有返回值

def log(msg: str) -> None:
    print(msg)

None ≠ 没写返回值 👉 表示“明确不返回任何东西”

3️⃣ 可选参数（Optional）

from typing import Optional

def get_user(id: int) -> Optional[str]:
    if id == 0:
        return None
    return "Tom"

等价写法（Python 3.10+）👇

def get_user(id: int) -> str | None:
    ...

五、Union / Literal / Any

1️⃣ Union（多种类型之一）

from typing import Union

def parse_id(id: Union[int, str]) -> int:
    return int(id)

Python 3.10+：

def parse_id(id: int | str) -> int:
    return int(id)

2️⃣ Literal（字面量类型）

from typing import Literal

def set_theme(theme: Literal["light", "dark"]) -> None:
    ...

👉 适合 配置项 / 状态值

3️⃣ Any（慎用）

from typing import Any

def parse(data: Any) -> Any:
    return data

⚠️ Any = 放弃类型检查 👉 不到万不得已别用

六、类型别名（让类型更可读）

User = dict[str, str]

def get_user() -> User:
    return {"name": "Tom"}

复杂类型尤其有用：

Response = dict[str, int | str | bool]

七、TypedDict（字典结构约束）

普通 dict 太宽松？

from typing import TypedDict

class User(TypedDict):
    id: int
    name: str
    active: bool

def get_user() -> User:
    return {
        "id": 1,
        "name": "Tom",
        "active": True
    }

👉 非常适合：

• JSON
• API 返回值
• 配置对象

八、Class & 方法类型注解

class UserService:
    def __init__(self, name: str):
        self.name: str = name

    def get_name(self) -> str:
        return self.name

九、泛型（进阶但很香）

from typing import TypeVar, Generic

T = TypeVar("T")

class Box(Generic[T]):
    def __init__(self, value: T):
        self.value = value

    def get(self) -> T:
        return self.value

使用：

box = Box
box.get()  # 推断为 int

👉 类似 TypeScript 泛型

---

扩展资源：

• Python 官方 typing 模块文档
• mypy 文档
• Python 类型提示指南
• Real Python 类型提示教程