Python 是一门动态类型语言，这让它足够灵活，但也让大型项目维护起来容易踩坑。类型注解（Type Hints）就是 Python 提供给我们的"安全带"——它不会改变代码的运行方式，但能显著提升代码的可读性和健壮性。

1. 基础语法

Python 3.5+ 引入了类型注解语法。最基本的用法就是给变量和函数参数标注类型：

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

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

这里 name: str 表示参数 name 应该是字符串，-> str 表示返回值是字符串。运行时不强制检查，但 IDE 和类型检查工具（如 mypy、pyright）会据此给出智能提示和错误警告。

2. 常用集合类型

列表、字典等集合类型的标注需要从 typing 模块导入：

from typing import List, Dict, Tuple, Optional

def process_items(items: List[int]) -> Dict[str, int]:
    return {str(x): x for x in items}

def find_user(uid: int) -> Optional[dict]:
    if uid in db:
        return db[uid]
    return None

Python 3.9+ 允许直接使用内置泛型，写法更简洁：list[int]、dict[str, int] 等，不再需要从 typing 导入。3.10+ 还引入了 X | Y 语法来替代 Union[X, Y]。

3. 实战场景：处理 API 响应

类型注解在解析外部数据时特别有用。比如处理一个 JSON API 响应：

from typing import TypedDict, List

class User(TypedDict):
    id: int
    name: str
    email: str
    is_active: bool

def fetch_users(url: str) -> List[User]:
    response = requests.get(url)
    data = response.json()
    return [User(**item) for item in data]

有了 TypedDict，IDE 就能自动补全 User 的字段名，拼写错误也能在编码阶段被发现。

4. 进阶用法：Protocol 与泛型

如果你习惯写鸭子类型风格的代码，Protocol 是更好的选择。它定义了"如果有这个行为就是这种类型"的接口：

from typing import Protocol

class Drawable(Protocol):
    def draw(self) -> None: ...

def render(obj: Drawable) -> None:
    obj.draw()

任何有 draw() 方法的对象都可以传给 render()，不需要显式继承。这让代码既有静态类型检查的安全性，又保留了 Python 的灵活风格。

泛型可以让函数适配多种类型而不失安全：

from typing import TypeVar

T = TypeVar('T')

def first(items: list[T]) -> T | None:
    return items[0] if items else None

调用 first([1, 2, 3]) 时，类型检查器能推断出返回值类型是 int | None，而不是笼统的 Any。

5. 团队协作建议

如果你所在的项目还没有引入类型注解，不要一口气加上全部。推荐渐进式引入：

先从公共 API 的函数签名开始（参数和返回值），然后在核心数据模型上用 TypedDict 或者 dataclass 加注解，最后配置 mypy/pyright 开启增量检查。大多数 CI 流程里加一个 mypy 检查步骤也就几行配置的事。

我在实际项目中遇到过几次因为类型不匹配导致的线上 bug，比如上游接口改了字段类型，下游还在用字符串拼接——如果有类型注解，这类问题在 CI 阶段就会被 mypy 拦截，根本不会进入生产环境。

以上就是我对 Python 类型注解的一些实践心得。从简单标注开始，慢慢扩展到协议和泛型，每次新增的注解都是在为项目的长期健康做投资。希望对你有帮助！