Python typing.Protocol 运行时检查为何不等于完整实现

把 typing.Protocol 当成“运行时接口验证器”，是 Python 类型标注里很常见的误解。实际边界是：Protocol 首先服务静态类型检查器；只有加上 @runtime_checkable 后，才可以把它传给 isinstance() 或 issubclass()。即便如此，运行时通常也只确认必需成员是否存在，不会替你验证方法签名、参数类型、返回类型，更不会证明业务行为正确。

Protocol 默认解决的是静态兼容

协议采用结构化子类型：实现类不必显式继承协议，只要提供兼容的成员，静态类型检查器就可以把它当成协议类型使用。这正是鸭子类型的类型化版本，重点在调用方获得可靠的参数和返回值提示。

from typing import Protocol


class TextStore(Protocol):
    def read(self, key: str) -> str:
        """中文注释：协议只描述调用方依赖的最小读取能力。"""
        ...


class MemoryStore:
    def __init__(self) -> None:
        # 中文注释：实现类不继承 TextStore，也可以靠结构匹配通过静态检查。
        self.data = {"welcome": "你好"}

    def read(self, key: str) -> str:
        # 中文注释：参数和返回类型与协议一致，调用方可以稳定使用。
        return self.data[key]


def load_message(store: TextStore) -> str:
    # 中文注释：这里依赖的是 read 方法的契约，不依赖具体实现类名。
    return store.read("welcome")

这段代码的关键不是 MemoryStore 有没有写 (TextStore)，而是它的 read 是否满足静态契约。参数名、参数类型、返回类型等细节由类型检查器分析；Python 解释器本身不会因为注解不匹配而自动拦截函数调用。

runtime_checkable 只检查属性是否存在

如果确实需要在运行时做一个粗粒度判断，可以给协议加上 @runtime_checkable。这样做的含义很窄：isinstance(obj, TextStore) 可以检查协议要求的成员名是否出现；它并不读取 read(self, key: str) -> str 的完整签名，也不会调用方法来确认结果。

from typing import Protocol, runtime_checkable


@runtime_checkable
class TextStore(Protocol):
    def read(self, key: str) -> str:
        # 中文注释：这里的注解主要给静态类型工具使用。
        ...


class BrokenStore:
    # 中文注释：成员名字存在，但它不是可调用的方法。
    read = "not a function"


store = BrokenStore()
if isinstance(store, TextStore):
    # 中文注释：运行时通过不等于调用安全，真正调用仍可能抛出 TypeError。
    value = store.read("welcome")

这个例子说明了“存在”和“可用”是两件事。对方法型协议，成员名存在就可能让运行时检查通过，但成员可能是字符串、属性描述器或签名不兼容的函数。Python 官方文档还特别提醒，运行时协议检查不会验证属性或方法的类型签名，并且在性能敏感路径上可能比普通类的 isinstance() 更慢。

为什么通过 isinstance 仍可能在调用时失败

即使成员确实是方法，也只说明名称和粗粒度结构过关。例如下面的实现把参数名和返回语义都改掉了：

class LooseStore:
    def read(self, path: int) -> int:
        # 中文注释：签名和返回类型都偏离 TextStore，但方法名仍然叫 read。
        return path


store = LooseStore()
assert isinstance(store, TextStore)

# 中文注释：运行时协议检查不会替你检查参数类型和返回值类型。
message: str = store.read("welcome")

静态检查器会把 LooseStore 传给 TextStore 视为不兼容；而运行时的协议检查只回答“对象上有没有 read 这个成员”。真正的生产风险还包括：方法虽然能调用，却返回错误业务状态；属性存在，但依赖初始化顺序；或者实现只支持协议的一半语义。协议本身不会替你完成这些验证。

Python 3.12 起，运行时协议检查使用 inspect.getattr_static() 查找成员，协议创建后成员集合也会冻结。依赖运行时给协议动态打补丁的代码，需要重新审视这两个变化；它们让检查边界更稳定，却不会把检查升级成完整实现认证。

按风险补上真正需要的检查

可以把检查分成三层，避免把所有责任压给 isinstance()：

对插件、序列化器或外部适配器，入口可以先做轻量检查，再在隔离测试中调用一个最小用例：

def require_text_store(value: object) -> TextStore:
    # 中文注释：先确认协议成员存在，再确认它确实可调用。
    if not isinstance(value, TextStore):
        raise TypeError("对象缺少 TextStore 的 read 成员")
    if not callable(getattr(value, "read", None)):
        raise TypeError("TextStore.read 必须是可调用成员")
    return value


def check_result(store: TextStore) -> str:
    # 中文注释：最小行为测试用于确认返回值语义，不能由 isinstance() 代替。
    result = store.read("health-check")
    if not isinstance(result, str):
        raise TypeError("TextStore.read 必须返回字符串")
    return result

这里的 isinstance() 只负责第一道门，callable() 负责排除明显的非方法成员，最小行为测试才确认返回值形态。若协议边界涉及权限、事务、幂等或异常语义，还应把这些约定写进专门的测试，而不是继续堆叠反射判断。

相关问题

Protocol 必须显式继承吗？

不必须。对静态类型检查器来说，只要实现类提供兼容成员，就可以按结构匹配协议；显式继承更多用于表达意图和让检查器检查实现。

不加 runtime_checkable 能用 isinstance 吗？

不能把普通 Protocol 直接作为 isinstance() 或 issubclass() 的第二个参数；需要运行时检查时才加这个装饰器。

runtime_checkable 能验证方法参数吗？

不能。它不验证方法签名、参数类型或返回类型；这些应交给静态类型检查和最小行为测试。

什么时候应该不用 Protocol？

如果必须在运行时强制完整契约，可以考虑抽象基类、显式注册机制或专门的验证函数。Protocol 仍可作为静态接口描述，但不要把它当作唯一的运行时安全边界。