Python typing Protocol 怎么为第三方对象定义最小接口

接入第三方 SDK 时，最稳妥的做法通常不是让它继承项目里的基类，而是先写出业务真正用到的最小接口。Python 的 typing.Protocol 正好适合这个场景：静态类型检查器会按方法和属性判断对象是否兼容，第三方类无需修改，也无需显式继承本地协议。

把 Protocol 当作静态协作约定；只有确实需要在运行时用 isinstance() 分流时才加 @runtime_checkable，并记住它只看成员是否存在，不会验证签名和返回值。

先从调用方抽出最小 Protocol

假设订单服务只需要一个对象提供 put 和 get。不要把第三方客户端的连接池、重试、监控方法一起塞进接口，否则每次换实现都要承担无关约束。

from typing import Protocol

class CachePort(Protocol):
    def put(self, key: str, value: bytes, ttl: int) -> None:
        # 协议只描述业务真正调用的方法
        ...

    def get(self, key: str) -> bytes | None:
        # 返回值约束交给静态检查器和实现测试
        ...

def remember(cache: CachePort, order_id: str, payload: bytes) -> bytes | None:
    # 调用方依赖最小接口，而不是某个 SDK 基类
    cache.put(order_id, payload, ttl=300)
    return cache.get(order_id)

这里的 CachePort 不是必须实例化的父类。它表达的是“只要对象拥有这两个兼容成员，就可以传给 remember”。协议方法中的类型签名仍然重要，因为静态检查器会用它判断参数和返回值是否能安全传递。

第三方对象为什么可以直接接入

下面用一个不继承 CachePort 的对象模拟外部 SDK。它只实现协议要求的两个方法，因此在支持 Protocol 的类型检查器中可以作为 CachePort 使用。

class VendorCache:
    def __init__(self) -> None:
        # 用普通字典模拟第三方客户端的内部存储
        self._data: dict[str, bytes] = {}

    def put(self, key: str, value: bytes, ttl: int) -> None:
        # 示例不实现过期，只保留与协议匹配的参数
        self._data[key] = value

    def get(self, key: str) -> bytes | None:
        # 缺失键返回 None，与协议保持一致
        return self._data.get(key)

cache = VendorCache()
result = remember(cache, "order-17", b"paid")

结构化子类型的关键是“形状兼容”，不是继承关系。如果第三方方法把 ttl 写成必填字符串，或者 get 返回类型与调用方假设冲突，静态检查器应当提示问题；这比运行到线上才发现适配错误更早。

什么时候需要 runtime_checkable

如果程序需要根据对象能力选择路径，例如插件加载器要先判断是否提供 close，可以把协议标记为运行时可检查：

from typing import Protocol, runtime_checkable

@runtime_checkable
class ClosablePort(Protocol):
    def close(self) -> None:
        # 这里只声明关闭能力
        ...

def shutdown(resource: object) -> None:
    # 运行时只做能力分流，不假设完整业务行为
    if isinstance(resource, ClosablePort):
        resource.close()

没有这个装饰器时，对协议调用 isinstance(resource, ClosablePort) 会抛出 TypeError。加上之后，检查也只是成员存在性检查：一个名为 close 的属性可能不是可调用方法，签名是否接受正确参数也不会由该判断保证。Python 3.12 起运行时协议成员创建后会冻结，动态给协议追加成员不会改变已有的判断；因此不要把它当成动态校验器。

用行为测试补上接口边界

接入第三方对象前，至少测试协议声明的每个动作：写入后能否读回、缺失键是否返回 None、关闭方法是否真的可调用。不要因为 isinstance() 返回 True 就直接放行。

def test_cache_port(cache: CachePort) -> None:
    # 测试协议承诺的核心行为，而不是只测类名
    cache.put("missing", b"value", ttl=60)
    assert cache.get("missing") == b"value"
    assert cache.get("unknown") is None

生产代码中可以让适配层把第三方 SDK 的参数、异常和生命周期收敛到 CachePort，业务层只依赖协议。这样既保留了静态检查的早期反馈，也避免把 SDK 的复杂 API 扩散到每个调用点。

常见问题

Protocol 和抽象基类应该怎么选？

需要强制继承、共享实现或注册机制时选抽象基类；只想约束调用方所需的成员，并兼容不受控的第三方类时优先 Protocol。

runtime_checkable 会检查方法参数吗？

不会。它主要检查成员是否存在，不能证明参数类型、返回值类型或业务行为正确。

为什么协议写得越小越好？

因为调用方只依赖少量能力时，更多第三方实现可以自然兼容，适配层也更容易测试和替换。

实际落地时，可以把协议放在业务边界，把第三方 SDK 留在适配模块；静态检查负责发现形状错误，行为测试负责确认真实协作，运行时检查只承担有限的能力分流。相关语义可继续查阅 Python typing 官方文档中的 Protocol。