Python Protocol 怎样表达结构化接口

当一个函数只需要对象提供 save 和 load，却不想要求实现类继承某个基类时，typing.Protocol 就适合表达这组结构化接口。协议把“调用方依赖什么”写成类型声明；只要具体类具备兼容的成员，静态类型检查器就可以把它当作协议的实现，即使类定义里没有写 Protocol。

官方地址：https://docs.python.org/3/library/typing.html

本文用一个存储适配器场景推进：先拆出接口，再接入两个不同实现，最后说明 @runtime_checkable 为什么不能替代完整的类型检查。

结构化接口的关键不是“有没有继承”，而是调用方依赖的成员是否完整、签名是否兼容。Protocol 主要服务静态检查；只有明确加上 @runtime_checkable 后，才可以用于有限的 isinstance() 判断。

先从调用现场提取最小接口

假设备份函数只关心把字节写入存储，再读回字节。它不需要知道对象是文件、内存缓存还是远端客户端，也不应该把这些实现细节写进参数类型。先把真实依赖收窄成两个方法：

• save(data: bytes) -> None：接受完整字节数据。
• load() -> bytes：返回当前保存的数据。

这一步是结构化接口设计的边界。若调用方还会读取 path、调用 flush 或依赖特定异常，就必须把这些依赖也纳入协议；如果调用方根本不用，就不要为了“看起来完整”加入成员。

用 Protocol 声明方法形状

协议类只描述接口，不负责保存数据。下面的两个实现类都没有继承 Store，但它们提供了同名且兼容的方法，因此可以被静态类型检查器视为 Store。

from typing import Protocol


class Store(Protocol):
    # 协议只声明调用方依赖的成员，不保存具体数据。
    def save(self, data: bytes) -> None:
        ...

    def load(self) -> bytes:
        ...


class MemoryStore:
    def __init__(self) -> None:
        # 内存实现只负责自己的存储细节。
        self._data = b""

    def save(self, data: bytes) -> None:
        self._data = data

    def load(self) -> bytes:
        return self._data


class FileStore:
    def __init__(self, path: str) -> None:
        # 文件实现可以更换为数据库或对象存储，而不改调用方协议。
        self._path = path

    def save(self, data: bytes) -> None:
        with open(self._path, "wb") as target:
            target.write(data)

    def load(self) -> bytes:
        with open(self._path, "rb") as source:
            return source.read()

这里的重点是“成员兼容”，不是类名相同。静态检查器会根据协议要求检查方法是否存在，并检查参数和返回值能否安全地用于协议位置。运行 Python 程序时，解释器不会自动因为注解不匹配就拦截调用；类型检查属于开发期工具链职责。

让业务函数依赖协议而不是实现类

把协议放到函数参数上，调用方的依赖就稳定下来。以后替换存储实现时，只要新类仍然满足 Store，备份逻辑不需要跟着修改。

def round_trip(store: Store, payload: bytes) -> bytes:
    # 业务函数只使用 Store 声明过的成员。
    store.save(payload)
    return store.load()


def make_backup(store: Store, payload: bytes) -> bool:
    # 用返回值表达结果，避免把具体实现的内部字段泄露给调用方。
    stored = round_trip(store, payload)
    return stored == payload


memory = MemoryStore()
ok = make_backup(memory, b"daily-report")
print(ok)

如果把参数写成 MemoryStore，类型系统会把函数和某一种实现绑定；写成 Store 后，函数只承诺使用协议成员。这个变化同时改善了替换实现和测试：测试替身只需实现两个方法，不需要复制真实文件存储的初始化过程。

运行时检查只解决“有这个成员吗”

默认情况下，协议类不能直接作为 isinstance() 的第二个参数。若确实需要在运行时做一个轻量的能力探测，可以显式使用 @runtime_checkable：

from typing import Protocol, runtime_checkable


@runtime_checkable
class Closable(Protocol):
    # 运行时协议用于能力探测，不是完整的参数类型验证器。
    def close(self) -> None:
        ...


def close_if_supported(value: object) -> bool:
    # isinstance 只判断协议成员是否存在，再决定是否调用。
    if not isinstance(value, Closable):
        return False
    value.close()
    return True

这个判断有三个容易被误解的边界：

• @runtime_checkable 检查的是所需方法或属性是否存在，不会验证 close 的参数签名和返回类型。
• 运行时可检查性不会因为继承关系自动传递；需要作为运行时协议使用的子协议，也应明确装饰。
• Python 3.12 起，运行时协议成员创建后会被冻结，并使用静态属性查找；因此不要把运行时动态补丁当作可靠的协议扩展机制。

因此，静态检查负责回答“调用是否按声明安全”，运行时协议负责回答“对象表面上有没有这个能力”。需要确认参数和返回值时，仍应依赖类型检查器、测试或实际调用的错误处理。

把类型检查接入发布前的判断

结构化接口最常见的问题不是 Protocol 写错，而是协议与实际调用逐渐分叉。可以按以下顺序排查：

1. 先列出调用方真正使用的成员，删除没有调用证据的接口字段。
2. 检查每个实现类的方法名、参数类型、返回类型和可选值是否与协议兼容。
3. 让业务函数只接收协议类型，避免在函数内部访问具体实现的私有字段。
4. 用静态类型检查器检查替身和生产实现；不要把程序能运行等同于类型已经通过。
5. 只有在插件探测、可选能力或边界适配场景下，才加入 @runtime_checkable，并把它当作存在性判断。

若新增实现缺少 load，静态检查应该在传入 round_trip 的位置报告问题。若你只在运行时使用 isinstance()，则可能只得到“对象具备某个属性”的粗粒度结论，不能替代对签名的检查。

回滚与复盘：什么时候不该用 Protocol

如果调用方需要共享一段默认实现、依赖显式注册，或者业务必须在运行时确认对象属于某个受控层次，抽象基类可能更合适。Protocol 的优势是降低名义继承要求，但它也可能让过宽的协议悄悄接纳不完整的对象，所以接口应保持小而明确。

如果类型检查噪声变多，先把协议拆成按能力划分的小接口，例如把读写拆成 Readable 和 Writable，而不是给一个协议不断添加与当前调用无关的成员。这样既容易替换实现，也更容易定位哪一项依赖发生变化。

• Protocol 表达的是结构，不是运行时继承身份。
• 未显式继承协议的类，只要成员兼容，也可通过静态检查。
• 函数参数应使用协议类型，避免依赖具体实现。
• @runtime_checkable 只做属性存在性检查，不验证签名。
• Python 3.12+ 的运行时协议成员冻结，动态补丁不能当作协议扩展方案。

Protocol 一定要让实现类继承吗？

不需要。结构化子类型的目标就是让实现类通过成员形状匹配协议；显式继承可以作为文档或约束选择，但不是满足静态协议的必要条件。

为什么 isinstance(store, Store) 会报错？

普通 Protocol 默认只面向静态类型检查，不能直接用于 isinstance() 或 issubclass()。需要有限运行时检查时，才给协议加上 @runtime_checkable，并接受它只检查成员存在性的限制。

runtime_checkable 能检查方法返回类型吗？

不能。它不验证方法签名或类型注解。返回类型、参数类型和调用安全性仍由静态检查器或实际测试负责。

参考：Python typing.Protocol 官方文档、PEP 544：结构化子类型。本文示例与说明图均为原创。