Python runtime_checkable Protocol 为什么只检查属性存在

我曾经把 @runtime_checkable 当成了一个轻量运行时类型检查器：既然 isinstance(obj, Parser) 返回 True，方法签名和返回值总该匹配吧？实际并不是。runtime-checkable Protocol 只做简单的结构检查：确认协议要求的方法或属性名称存在，不检查它们的类型，也不比较方法参数与返回值签名。它适合做粗筛，不适合单独承担插件安全、输入校验或业务契约验证。

Python 官方文档：https://docs.python.org/3/library/typing.html#typing.runtime_checkable

触发信号：isinstance 通过，真正调用却失败

最典型的现场是插件加载器。协议声明 parse(raw: bytes) -> dict[str, str]，候选对象也有一个名为 parse 的成员，于是运行时检查通过；但这个成员可能接收错误参数、返回错误类型，甚至根本不可调用。

from typing import Protocol, runtime_checkable

@runtime_checkable
class Parser(Protocol):
    def parse(self, raw: bytes) -> dict[str, str]:
        ...  # 协议为静态检查器描述期望签名

class WrongSignature:
    def parse(self, raw: int) -> list[int]:
        return [raw]  # 名称存在，但参数和返回类型都不匹配

class NotCallable:
    parse = "disabled"  # 属性存在，却不是可调用方法

assert isinstance(WrongSignature(), Parser)
assert isinstance(NotCallable(), Parser)

这两次断言通过并不表示对象可正确解析 bytes，只表示运行时找到了协议要求的 parse 名称。看到“检查通过但调用异常”时，优先确认自己是否把存在性检查误当成了完整类型验证。

快速判断：它解决的是运行时结构筛选

Protocol 的主要价值是结构化子类型：对象不必显式继承协议，只要静态类型上拥有兼容成员，就能被类型检查器接受。@runtime_checkable 只是额外允许该协议出现在 isinstance 和部分 issubclass 检查中。

官方文档直接把这种检查称为简单的运行时协议，并明确说明它忽略类型签名。这个取舍让协议保持接近 Python 的鸭子类型：运行时只问“像不像拥有这些能力”，详细的类型兼容留给静态工具。

为什么运行时不按注解逐项验签

类型注解在 Python 运行时默认不会自动强制执行。若 isinstance 要完整解释所有注解，它还要处理泛型、前向引用、装饰器改写、描述符、动态属性以及众多无法仅凭签名判断的语义。即使签名形状相同，也无法证明方法真的返回承诺的数据。

PEP 544 把运行时协议定位成显式选择的有限能力，并指出实例检查不可能做到百分之百静态可靠。换句话说，@runtime_checkable 没有承诺成为运行时版 mypy 或 pyright，它只提供与部分 collections.abc 类似的结构入口。

Python 3.12 起还有两个实现细节值得运维排查时记住：协议检查改用 inspect.getattr_static() 查找属性；协议成员在类创建后对运行时检查视为冻结。给协议类后续动态补成员，不会改变既有 isinstance 的成员集合。

处理手册：把存在性、可调用性和业务契约拆开

我现在会按接入风险选择检查层，而不是要求一个 isinstance 回答所有问题。

第一层：只需要粗筛时使用 runtime_checkable

def looks_like_parser(candidate: object) -> bool:
    # 这里只承诺协议成员存在，不宣称签名或行为正确
    return isinstance(candidate, Parser)

适合低风险分派、测试替身发现或快速过滤。若后面仍有受控调用和异常处理，这层可以减少明显不匹配的对象。

第二层：进入调用前至少确认成员可调用

from typing import Any

def has_callable_parse(candidate: object) -> bool:
    # getattr 提供默认值，避免成员缺失时抛出 AttributeError
    parse: Any = getattr(candidate, "parse", None)
    return callable(parse)

callable 能排除“同名字符串或数据属性”，但依旧不会验证参数和返回值。它是存在性检查的补充，不是类型系统替代品。

第三层：边界严格时使用显式适配器与受控试调用

from collections.abc import Mapping

def run_parser(candidate: object, raw: bytes) -> dict[str, str]:
    if not isinstance(candidate, Parser):
        raise TypeError("parser 缺少协议要求的成员")

    parse = getattr(candidate, "parse", None)
    if not callable(parse):
        raise TypeError("parser.parse 必须可调用")

    result = parse(raw)  # 在受控边界内调用，让异常落到接入层
    if not isinstance(result, Mapping):
        raise TypeError("parser.parse 必须返回映射")

    # 复制为普通字典，隔离插件返回的自定义映射实现
    normalized = dict(result)
    if not all(isinstance(k, str) and isinstance(v, str) for k, v in normalized.items()):
        raise TypeError("解析结果的键和值都必须是字符串")
    return normalized

这一层检查的是当前业务真正依赖的结果。若插件可能执行 I/O 或有副作用，试调用应使用专门的探针输入、超时和隔离环境，不能拿生产数据随意探测。

签名检查能补多少，什么时候应该回退

inspect.signature() 可以在部分纯 Python 可调用对象上读取签名，用来检查参数名称和数量，但它仍有边界：装饰器可能隐藏原签名，某些内建对象无法提供完整签名，动态调用对象也可能与展示签名不同。更关键的是，签名相同仍不代表行为正确。

import inspect

def inspect_parse_shape(candidate: object) -> inspect.Signature:
    parse = getattr(candidate, "parse", None)
    if not callable(parse):
        raise TypeError("parse 不可调用")

    try:
        return inspect.signature(parse)  # 只读取可见签名，不验证业务语义
    except (TypeError, ValueError) as exc:
        raise TypeError("无法可靠读取 parse 签名") from exc

当接入边界要求强约束时，我更倾向于以下回退方案：

• 同一代码库：保留 Protocol 做静态检查，并把 mypy、pyright 等检查纳入 CI。
• 第三方插件：要求显式继承 ABC 或注册插件元数据，再用适配器统一输入输出。
• 不可信对象：不要把 Protocol 当安全边界；使用隔离、权限限制、超时和结果校验。
• 性能敏感热路径：官方文档提醒运行时协议检查可能比普通类的 isinstance 慢；可在注册阶段检查一次，或直接使用针对性的 hasattr/callable。

告警确认与复盘项

如果线上出现“Protocol 检查通过但调用报错”，应把告警归类为契约分层不足，而不是 typing 失效。确认时记录候选对象类型、缺失或不可调用成员、实际异常、返回值形态和 Python 版本；不要把完整业务载荷或敏感数据写入日志。

• Protocol 是否确实加了 @runtime_checkable，还是误用普通 Protocol 做 isinstance。
• 代码是否错误地把 True 解读为参数与返回类型都匹配。
• 静态检查是否覆盖插件实现，还是插件从动态入口绕开了 CI。
• Python 3.12 前后的属性查找差异是否影响动态代理或描述符对象。
• 协议类是否在创建后被 monkey patch，并误以为运行时成员集合会跟着变化。
• 接入层是否对可调用性、异常、结果结构和副作用设置了独立保护。

相关问题

为什么普通 Protocol 不能直接用于 isinstance？

运行时协议检查是显式选择能力。只有加了 @runtime_checkable 的协议才能作为 isinstance 或允许场景下 issubclass 的第二个参数，否则会抛出 TypeError。

runtime_checkable 会检查属性值类型吗？

不会。协议写了 name: str，运行时检查也只关心 name 是否存在，不保证实际值是字符串。

有了静态类型检查还需要运行时验证吗？

同一受控代码库里，静态检查通常覆盖签名兼容；但外部插件、配置加载、反序列化对象和动态导入绕过了静态边界，仍需要按风险补充运行时业务验证。

结论是：@runtime_checkable 的名字强调“允许在运行时检查”，并不意味着“运行时执行完整类型检查”。把它放在成员存在性这一层，再让静态工具负责签名、让接入适配器负责行为，边界会更清楚，也更符合它原本的设计。