Python typing.Protocol 运行时检查为什么不等于接口完整性：runtime_checkable、属性访问与静态类型边界

代码评审场景里，大家经常会碰到一个看似稳妥的判断逻辑：先定义 typing.Protocol，再用 isinstance(value, ServiceLike) 拦下不符合要求的对象。但这个判断实际上只能确认“对象身上存在对应名称的属性/方法”，根本没法验证“方法签名能不能按约定正常调用”。

Protocol 解决的是哪一层接口问题

假设你写的订单导出器，只要求传入对象具备 write 方法。如果用继承抽象基类的方案，调用方和实现方必须绑定到同一棵类继承树上，而 Protocol 可以实现“只要对象结构匹配就能直接被接收”的结构化类型写法：

from typing import Protocol

class Writer(Protocol):
    def write(self, text: str) -> int:
        ...

class CsvWriter:
    def write(self, text: str) -> int:
        return len(text)

def export_row(writer: Writer, row: str) -> int:
    return writer.write(row)

export_row(CsvWriter(), "id,name")

这段代码的核心价值体现在静态分析阶段：类型检查器可以提前发现 CsvWriter.write 的参数或者返回值不符合 Writer 定义的问题。Python 解释器本身不会因为你加了这个注解，就自动替你完成全量接口验证。

为什么普通 Protocol 不能直接传给 isinstance

如果你把 Writer 直接传给 isinstance，解释器会直接抛出异常拒绝执行。因为协议定义里包含了参数、返回值、属性类型这类纯静态的信息，运行时没有一套低成本、全兼容的机制可以完整复现类型检查器的所有校验逻辑。

from typing import Protocol

class Writer(Protocol):
    def write(self, text: str) -> int: ...

isinstance(CsvWriter(), Writer)
# TypeError: Instance and class checks can only be used with @runtime_checkable protocols

这不是 Python 的设计缺陷，而是明确的边界提示：静态契约校验交给静态工具完成，运行时能力探测就要明确定义规则，只检查“成员是否真实存在”。

runtime_checkable 只看名字，不看签名

给协议加上 @runtime_checkable 装饰之后，isinstance 可以正常执行了，但它的检查粒度非常粗。下面这个示例对象把 write 写成了接收整数、返回字符串的方法，运行时依然可以顺利通过校验：

from typing import Protocol, runtime_checkable

@runtime_checkable
class Writer(Protocol):
    def write(self, text: str) -> int: ...

class WrongWriter:
    def write(self, number: int) -> str:
        return str(number)

print(isinstance(WrongWriter(), Writer))  # True
print(WrongWriter().write(7))             # 7

这个 True 为真，仅代表 WrongWriter 身上存在一个名为 write 的成员。它不会自动帮你核对 int、str，也没法提前保证后续调用一定能正常执行。

属性协议的陷阱：存在不等于值正确

方法成员的检查宽松还只是第一层问题，属性协议同样只会做最简单的存在性判断：

@runtime_checkable
class HasTimeout(Protocol):
    timeout: float

class Config:
    timeout = "30s"

print(isinstance(Config(), HasTimeout))  # True
print(Config().timeout + 1)              # TypeError

所以涉及边界字段的校验，通常都需要手动显式编写校验逻辑。校验代码要尽量贴近真正使用这个字段的代码位置，不要把 isinstance 的结果当成完整的数据校验结论：

def read_timeout(value: object) -> float:
    if not isinstance(value, HasTimeout):
        raise TypeError("对象缺少 timeout")
    timeout = value.timeout
    if not isinstance(timeout, (int, float)) or timeout 

Python 3.12+ 还改变了哪两个运行时细节

官方文档明确说明，Python 3.12 开始，运行时协议检查使用 inspect.getattr_static() 查找属性，和之前偏向动态访问的实现方式不一样。这会导致依赖 __getattr__ 临时动态生成成员的对象，校验结果和旧版本表现不同。同时协议成员会在协议类创建完成后直接冻结，后续给协议类动态新增字段，也不会改变 isinstance 的检查集合。

这类版本差异的行为不适合直接用来承载业务核心逻辑。如果插件系统必须支持动态代理能力，建议单独写一个显式的适配器，把动态查找、签名转换和错误提示逻辑统一收拢到这一处维护。

落地时怎么选检查方式

有个很简单的判断原则：调用前你只想确认“对象有没有这个能力”，可以用 hasattr 或者轻量的运行时协议；你要保证调用参数和返回结果都符合约定，就要用静态检查搭配运行时数据校验；如果对接的是第三方插件，还要额外补上适配器和错误隔离机制。

• 不要在每次请求的热路径里反复对大型协议做 isinstance，最好提前缓存适配结果，或者在模块加载阶段就完成检查。
• 不要把 runtime_checkable 当成反序列化器使用，它不会验证 JSON 字段的类型和值域是否合法。
• 对必须返回特定结构的函数，用显式转换、TypedDict 搭配自定义校验函数，或是让领域对象的构造逻辑自行承担校验职责。

相关问题

Protocol 和抽象基类必须二选一吗？

没必要强行二选一。内部稳定的继承体系适合用抽象基类，跨包协作或者插件边界场景更适合用 Protocol；两者完全可以在同一个项目里分层使用，各自服务不同的需求。

runtime_checkable 会检查方法参数吗？

不会。它的核心作用是检查协议要求的成员能不能被正常找到，方法签名和返回值的校验依然要交给静态类型检查器，或是手动编写的显式运行时校验逻辑来完成。

为什么 hasattr 有时比 isinstance 更合适？

当你只需要校验单个能力，而且代码运行在高频路径里时，hasattr(obj, "write") 的执行逻辑更直接；如果要同时校验的协议成员有好几个，再考虑用运行时协议统一表达这一组能力要求。

把边界写进团队约定

最基础的规则可以简化成一句话：Protocol 用来描述“对象应该长什么样”，静态检查器负责“签名是否完全匹配”，运行时校验负责“当前拿到的数据能不能直接用”。把三件事分开处理，isinstance(..., runtime_checkable_protocol) 对应的那个 True 结果，就不会被误读成接口已经完整实现了。