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