徐术挺-漫思录

02-类型系统进阶

23分钟阅读

第 2 章 类型系统进阶：type hints 是工程契约

这一章解决你最大的心结：Python 没有 var x int 那种编译期绑定，项目一大就怕「传错东西进去还跑得好好的，半夜才炸」。Python 的解法不是改语言，而是用 type hints + mypy 把「这段代码该传什么」写成一份可机器校验的工程契约。

墨叔：老哥，你从 Go 过来，最不习惯的一定是——写 Python 函数，参数啥类型全靠猜，IDE 不给提示，改了签名没人报错。你心里是不是一直犯嘀咕：这玩意儿能写大项目？

老哥：对，我们组有人改了个函数返回值，下游十几个调用点全靠运行时才暴露，太吓人了。

墨叔：慌啥，Python 社区早就被这事儿坑怕了，所以有了 type hints。但先得把一个根子上的误会掰正：类型注解（type hints）在运行时是「聋子的耳朵」——摆设，不强制。这一章我就把这件事讲透：它到底是个啥、怎么写、为什么这么设计、以及 mypy 怎么把这纸契约变成真检查。

一、注解本质：运行时不被强制，只是提示

先给你泼盆清醒的冷水。下面这段代码，Python 全程不拦你：

def add(a: int, b: int) -> int:
    return a + b
 
print(add("1", "2"))   # 输出 "12"，解释器一句废话都没有

a: int、-> int 这些就是 type hints，学名 PEP 484。它们存在哪里？存在函数的 __annotations__ 字典里，纯粹当元数据。解释器执行 add("1", "2") 时，根本不看这个字典。

墨叔：你拿它和 Go 对齐一下——Go 里 func add(a int, b int) int，编译器在编译那一刻就把类型焊死，传字符串直接红。Python 的注解呢？只是个「便签」，贴在代码上给人和工具看，运行时不当真。

那它有什么用？两个实在用处：

  1. 给 IDE 当路标。PyCharm、VS Code 的 Pylance 读你 -> list[User] 这种注解，就能在调用处给你补全、给红线提示，体验直追 Go。
  2. 给静态检查器当证据。mypy、pyright 这些工具「离线」扫描你的代码，对照注解推理类型是否自洽，发现矛盾就报错——而且是在你 git push 之前。

老哥：等等，那这不是脱裤子放屁吗？运行时不管，还得装个额外工具？

墨叔：这恰恰是 Python 的取舍哲学。语言本身保持动态、灵活、零编译摩擦；类型检查降级成可选工具链的一环，你愿意要就装上，不愿意就不装，互不影响。Go 是「编译器替你盯着」，Python 是「你想被盯着就装个 mypy 盯着」。代价是少了一层强制，收益是动态语言的灵活和极快的原型速度都保住了。

Python 3.9+ 起，很多类型可以直接用内置容器，不必从 typing 引：

# Python 3.9+ 推荐写法（运行时就是普通 list/dict，干净）
def parse(raw: dict[str, list[int]]) -> tuple[int, str]:
    ...
 
# 旧写法（3.8 及以前必须这么写，现在仍兼容但啰嗦）
from typing import Dict, List, Tuple
def parse_old(raw: Dict[str, List[int]]) -> Tuple[int, str]:
    ...

老哥：那 x: int = 5 和 Go 的 var x int = 5 看着像，其实完全不同？

墨叔：看穿了。x: int = 5 在 Python 里只是「顺手把注解也标了」，运行时 x 照样能被赋成字符串。注解不创造约束，只是声明意图。

二、typing 模块：把契约写细

基础类型不够用时，typing 模块给你一整套「组合拳」来描述复杂结构。挑项目里最常用、最值得你记牢的几个：

from typing import Optional, Union, Callable, Any, Literal
 
# Optional[int] 等价于 Union[int, None]，即「int 或 None」
def find_user(uid: int) -> Optional[dict]:
    return None if uid < 0 else {"uid": uid}
 
# Union：多种可能类型，比 Go 的 interface{} 精准
def to_str(v: Union[int, float, str]) -> str:
    return str(v)
 
# Literal：只能是这几个字面量之一，Go 里常用 const + iota 枚举
def set_level(level: Literal["debug", "info", "error"]) -> None:
    print(level)
 
# Callable：函数类型，像 Go 的 func 参数
def retry(times: int, fn: Callable[[int], bool]) -> bool:
    for i in range(times):
        if fn(i):
            return True
    return False

Any 是「我放弃标注、放你一马」的逃生舱——尽量少用，用了就等于告诉 mypy「这块别查了」。Literal 特别适合替代 Go 里那种 const LevelDebug = "debug" 的枚举场景，配合第 9 章的 Enum 用更香。

老哥：这跟 Go 的 interface{} / any 比呢？

墨叔：方向正相反。Go 的 any 是「什么都能装，但进去就丢类型信息，取出要断言」。Python 的 Union[str, int] 是「明说就这俩，mypy 还能继续查里面」。你写 Any 越多，越退化成 Go 里滥用 any 然后一路 .(type) 断言的烂代码。所以纪律是：能用具体类型/Union 就别用 Any。

三、泛型：TypeVar 与 Generic

来个你肯定会遇到的场景。你要写一个「栈」结构，元素可能是 int、可能是 str、可能是你的业务对象。Go 里你直接 type Stack[T any] struct{...} 上泛型。Python 怎么做？用 TypeVar + Generic：

from typing import TypeVar, Generic
 
T = TypeVar("T")   # 一个「类型变量」，占位用
 
class Stack(Generic[T]):
    def __init__(self) -> None:
        self._items: list[T] = []
 
    def push(self, item: T) -> None:
        self._items.append(item)
 
    def pop(self) -> T:
        if not self._items:
            raise IndexError("pop from empty stack")
        return self._items.pop()
 
s = Stack[int]()
s.push(1)
s.push("x")   # mypy 报错：Argument 1 to "push" has incompatible type "str"; expected "int"

TypeVar("T") 声明一个类型占位符，Stack[int] 表示「这是个装 int 的栈」。mypy 就能在 push("x") 时抓出「类型不对」。

还能加约束，等价于 Go 的「泛型约束」：

from typing import TypeVar, Sequence
 
# 约束 T 必须是 Number 的子类
Num = TypeVar("Num", int, float)
 
def total(nums: Sequence[Num]) -> Num:
    acc: Num = nums[0]   # 注意这里类型还是 Num，mypy 跟踪得住
    for n in nums[1:]:
        acc = acc + n     # int+int 或 float+float，自洽
    return acc

Sequence 是 typing 里的「只读序列协议」，比直接写 list[Num] 更宽（tuple 也能接受），这正是「接受最宽接口、返回最窄类型」的工程好习惯，和你 Go 里「参数用 interface 收口」一个道理。

四、Protocol：鸭子类型的静态契约（重点对照 Go）

这是你从 Go 过来最该兴奋的一块，因为它把第 1 章说的「鸭子类型」变成了可检查的东西。回忆一下：第 1 章我们说 Python 里「只要有 quack 方法就能当鸭子用」，但问题是运行时才验身，大项目心虚。

Python 3.8+ 的 typing.Protocol 就是解药——它描述「结构子类型（structural subtyping）」：只要一个类长着该协议要求的方法，mypy 就认定它实现了协议，不用显式声明。

from typing import Protocol
 
class Quacker(Protocol):
    def quack(self) -> str: ...
 
class Duck:
    def quack(self) -> str:
        return "嘎"
 
class Person:
    def quack(self) -> str:
        return "我模仿鸭子：嘎"
 
def make_it_quack(thing: Quacker) -> str:
    return thing.quack()
 
make_it_quack(Duck())    # OK
make_it_quack(Person())  # OK，mypy 看结构就够了

老哥：这跟 Go 的 interface 有啥区别？Go 也是「不写 implements，有方法就算实现」啊。

墨叔：问到骨头上了，区别在这：Go 的 interface 是编译期强制校验。var q Quacker = Duck{} 那一刻，编译器确认 Duck 真有 Quack()，才让你编译过；少一个方法，编译都红。Python 的 Protocol 是让 mypy 在静态分析阶段模拟出同样效果，但解释器运行时依然不强制——make_it_quack(随便一个对象) 运行时只要真有 quack 就过，没有才抛 AttributeError。

也就是说，Protocol 把「Go 的接口安全」搬到了 Python 的检查器里，却没动 Python 的运行模型。这是个非常 Python 的解法：不动运行时，只在工具链补一层。

真实项目里，你常拿它描述「外部依赖的契约」，比如一个缓存后端：

from typing import Protocol
 
class CacheBackend(Protocol):
    def get(self, key: str) -> bytes | None: ...
    def set(self, key: str, value: bytes, ttl: int) -> None: ...
 
class RedisCache:
    def get(self, key: str) -> bytes | None: ...      # 结构契合，无需声明
    def set(self, key: str, value: bytes, ttl: int) -> None: ...
 
class MemoryCache:
    def get(self, key: str) -> bytes | None: ...
    def set(self, key: str, value: bytes, ttl: int) -> None: ...
 
def handler(cache: CacheBackend, key: str) -> bytes:
    return cache.get(key) or b""

handler 只认 CacheBackend 这个协议，传 RedisCache 或 MemoryCache 都行。测试时你甚至能随手写一个 FakeCache 满足协议就注入进去，不用为了测试去 mock 框架——这正是 Go 里 interface 解耦依赖、方便测试那套思路，在 Python 里用 Protocol 复刻。

五、mypy 接入：把契约变成真检查

空有注解不跑检查，等于合同签了不执行。mypy 是把纸面契约变铁律的工具。

安装与最小配置（项目根目录 pyproject.toml）：

[tool.mypy]
python_version = "3.11"
strict = true            # 严格模式：连未注解的函数都报错
warn_unused_ignores = true
disallow_any_generics = true

跑：mypy your_package/。它会遍历代码，对照注解推理每个变量的类型，发现矛盾就报。比如你前面 Stack[int] 里 push("x")，mypy 直接红。

接入工程化要在 CI 里卡住：

# .github/workflows/ci.yml 片段
- name: Type check
  run: mypy src/

老哥：strict 模式会不会太狠？我一堆老代码没注解，一开全红。

墨叔：会，所以渐进式才是正道。先不开 strict，从核心模块开始标注解，跑通后再逐步收紧。mypy 支持按文件/按函数忽略（# type: ignore），但这是债务，别滥用。还有个关键收益你得知道：重构时 mypy 替你当免费测试。你改了 get_user 的返回类型，所有调用点立刻被 mypy 扫出来，不用靠人肉 grep 或等运行时炸——这正是你从 Go 最怀念的「编译器帮你查所有调用点」的安全感，mypy 还你大半。

注意一个边界：mypy 只做离线静态分析，运行时该炸还是炸。它不提升运行速度（类型注解在运行时通常被忽略，CPython 甚至有个 assert 似的 __annotations__ 但没人强制）。所以它的收益纯粹在「开发期拦截 bug + 文档化意图」，不是性能。

六、贴近项目的一个例子

把上面几样缝到一个真实的「配置加载器」里，你每天写业务都会碰到：

from typing import Protocol, TypeVar, Generic, Optional
 
T = TypeVar("T")
 
class Loader(Protocol):
    def load(self, path: str) -> dict[str, object]: ...
 
class FileLoader:
    def load(self, path: str) -> dict[str, object]:
        import json
        with open(path, encoding="utf-8") as f:
            return json.load(f)     # 注意真实项目要 try；这里聚焦类型
 
class Config(Generic[T]):
    def __init__(self, loader: Loader, path: str) -> None:
        self._raw = loader.load(path)
 
    def get(self, key: str) -> Optional[T]:
        return self._raw.get(key)   # type: ignore[return-value]
 
cfg = Config[dict](FileLoader(), "app.json")
# cfg.get("db") 被推断为 Optional[dict]，IDE 补全、mypy 可查

Loader 协议让 Config 不依赖具体文件实现（测试可注入假 loader）；Config[T] 泛型让「取出来是什么类型」被标注清楚。这份契约写下来，三个月后的你或新同事，看签名就知道怎么用，mypy 还能在你用错时立刻拦。

七、NewType 与类型收窄：让契约更细

注解还有两个你写业务时马上用得上的进阶招，别漏掉。

第一招 NewType，专治「两个本质不同的 int 被混用」。比如 user_id 和 order_id 都是 int，但语义不同，传错就是 bug，而普通 int 注解拦不住：

from typing import NewType
 
UserId = NewType("UserId", int)
OrderId = NewType("OrderId", int)
 
def get_user(uid: UserId) -> dict: ...
 
uid = UserId(42)
get_user(uid)          # OK
get_user(OrderId(42))  # mypy 报错：类型不兼容
get_user(42)           # mypy 报错：裸 int 不能当 UserId 用

NewType 运行时零成本（就是个返回原值的函数），但 mypy 视 UserId 和 int 为不同类型，跨语义赋值直接红。这比 Go 里「用 type UserId int 做强类型区分」还轻——Go 那边你还得做类型转换，Python 这边运行时无开销。

第二招「类型收窄（narrowing）」：mypy 能顺着 if isinstance 把类型收敛。这和你 Go 里 switch v := x.(type) 后 v 变成具体类型一个道理：

from typing import Union
 
def handle(v: Union[str, int]) -> str:
    if isinstance(v, str):
        return v.upper()      # 此处 mypy 知道 v 是 str，能调 upper
    return str(v)             # 此处 mypy 知道 v 是 int

老哥：这收窄是 mypy 自己推理的，不用我标？

墨叔：对，它看 isinstance 分支自动收窄，不用手写断言。但提醒一句：收窄只在「静态可判定」时生效。你若用动态手段（比如 type() 比较、或字典查表），mypy 收窄不了，得显式 assert isinstance(v, str) 帮它一把。另外 typing.cast 是「告诉 mypy 我比它懂」的逃生舱：

from typing import cast
v = cast(str, some_any)   # 仅 mypy 层面断言 v 是 str，运行时什么都不做

cast 和 NewType 一样运行时零成本，但它不做任何检查，纯属给检查器喂信息。滥用 cast 等于骗 mypy，等于你 Go 里强行 .(*Concrete) 但明知可能断言失败——能不用就不用，真要用就确保那行确实安全。

八、TYPE_CHECKING：躲开注解引发的循环导入

注解还有个实在的工程坑：为了标注类型，你 import 了一个模块，结果两个模块互相 import，炸了循环导入。解法是用 TYPE_CHECKING 守卫——这是个只在 mypy 跑时才为 True 的常量，运行时是 False，所以运行时不会真 import，却能让 mypy 看到类型：

from typing import TYPE_CHECKING
 
if TYPE_CHECKING:
    from models import User      # 仅 mypy 可见，运行时跳过，避免循环导入
 
def get(uid: int) -> "User":     # 或用 from __future__ import annotations 后直接写 User
    ...

配合 from __future__ import annotations（文件顶部加一行），所有注解会被当成字符串延迟求值，运行时完全不碰类型名，循环导入问题基本消失。这是中大型 Python 项目里几乎必开的开关，和你 Go 里「用接口打破包依赖环」是同一个意图——只是 Python 用「类型信息只在检查期存在」绕开了运行时的环。

九、收益与代价的总账

最后给你把账算清，别光听我吹：

  • 收益：IDE 补全/跳转直追 Go；重构有 mypy 兜底；代码即文档，签名读得懂；新人上手快；Protocol 让鸭子类型可检查，测试解耦更顺。
  • 代价：要写额外注解（有体力成本）；mypy 有误报需偶尔 type: ignore（债务）；只能静态查、运行时该炸还炸，不能替代单测；strict 模式对老项目侵入大，要渐进。
  • 设计意图：Python 故意让注解运行时无效，保住动态灵活性；把「强制」让位给「可选工具链」。你愿意为安全付工具成本，就装 mypy；要极限灵活的原型，就裸奔。掌控权在你。

最后补一句实操纪律，免得你回去一上来就翻车：注解别追求「全项目一夜 strict」，会直接劝退。正确节奏是从「核心模块、对外 API、数据边界、最容易传错类型的函数」开始标，这些地方 mypy 收益最大；内部纯计算逻辑可暂缓。等团队习惯了，再逐步打开 disallow_untyped_defs、warn_return_any，逼着每个函数都带注解。这是个先松后紧的过程，和你们 Go 项目「编译期一把梭强制」相反，但目标完全一致：让类型从「个人习惯」变成「团队可依赖的工程契约」。

【思考题】

  1. 你团队有个老函数 def get(id): ...，返回有时是 dict，有时是 None，有时是空列表。你想用类型注解「约束」它，但运行时老调用方还是可能传错。只靠 type hints 能彻底杜绝运行时传错类型吗？为什么？要真正安全，你还该补什么？
  2. 用 Go 的 interface 思维看 Python 的 Protocol：两者都支持「隐式实现、不写 implements」。但当你把一个没实现某方法的对象传给 def f(x: Quacker) 时，Go 和 Python(mypy 开启) 分别在什么时机、以什么形式报错？这个差异对「开发体验和线上安全」意味着什么？
  3. 泛型 Stack[T] 和直接写 Stack 然后里面塞 list[Any]，对 mypy 检查能力和你日常维护有什么不同？什么情况下你宁可偷懒用 Any？

【参考答案】

  1. 不能。这是本章反复强调的根：类型注解在 Python 运行时不强制，解释器执行 get("x") 时不看 __annotations__，传错类型只有真正跑到函数体、触发类型相关错误时才在运行时炸。type hints 只能约束「人和 mypy/IDE」，管不了运行时。要真正安全，得叠加：①跑 mypy 在提交前拦截明显误用；②函数体内做运行时校验（如 if not isinstance(v, dict): raise TypeError(...)）或改用 pydantic 在边界做数据校验（第 12 章）；③写单测覆盖异常输入。注解是「声明意图 + 静态辅助」，运行时安全得靠校验和测试兜底，不能本末倒置。
  2. Go：编译期报错。当你写 var q Quacker = SomeType{} 或把 SomeType{} 传给 func f(q Quacker)，若 SomeType 缺 Quack()，编译器直接在编译阶段拒绝，根本生成不了二进制，错误死在出厂前，线上不可能因「没实现接口方法」而炸。Python(mypy 开启)：mypy 在静态分析阶段报 Incompatible types，但前提是你要跑 mypy；若没跑 mypy、或 ignore 了，代码照常运行，直到执行到 thing.quack() 才抛 AttributeError（运行时）。意味着：Go 把接口安全焊进编译产物，开发期+线上双保险但牺牲灵活；Python+Protocol 把同等安全搬进检查器，开发期体验接近，但线上安全仍依赖你「真去跑 mypy + 写好测试」，工具链纪律要求更高。
  3. Stack[T] 让 mypy 能跨函数跟踪具体类型：s: Stack[int] 后 s.pop() 被推断为 int，下游 x: str = s.pop() 会被 mypy 抓出。而 list[Any] 等于告诉 mypy「这里面啥都行，别查了」，类型信息在进入栈那一刻就丢光，取出后下游全退化成 Any，等于自废静态检查武功。维护上，泛型版改了元素类型，所有相关调用点 mypy 会一次性扫出；Any 版改了没人提醒，隐患藏到运行时。宁可偷懒用 Any 的场景：①对接完全无类型信息的第三方动态数据（如解析任意 JSON 后还没 normalize）；②写一次性脚本/原型，确定不会长期维护；③协议边界之外、已经过 pydantic 校验进来的数据再往外传时。原则：边界内尽量精确，逃生舱 Any 是特例不是常态。

反向链接