Python typing.Protocol 怎样描述可替换依赖

typing.Protocol 用结构化子类型描述“依赖应提供哪些成员”。消费者参数标注为协议后，实现类只要具备兼容的方法和属性，通常无需继承协议就能作为该依赖使用。它帮助静态类型检查器发现不兼容的替换，但不会自动创建实现、注入对象或验证业务行为。

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

围绕消费者需要写接口，不围绕实现类画全集

假设一个功能只需要按编号取得展示标题。字典存储与不可变条目集合都能提供查询，消费者不应因为存储方式不同而改变调用代码。需要抽象的是 get(key) 的能力，不是把存储类全部方法复制到协议中。

本文约定：取得标题返回 str，不存在返回 None；空白标题由消费者拒绝。这个约定既包含静态签名，也包含需要实现者遵守的行为规则。类型系统能描述返回值的可能类型，却不能证明实现者没有把“不存在”伪装成任意字符串。

协议越小，替换需要满足的条件越清楚。消费者如果不负责写入、事务或连接关闭，就不应为了统一一个存储类而要求所有依赖实现这些无关方法。

协议支持与示例语法是两项要求

typing.Protocol 在标准库中的支持从 Python 3.8 开始。下面使用 str | None 和内置泛型等写法，完整片段按 Python 3.10 及以上准备，不应因为 Protocol 本身较早可用就把整个片段视为 Python 3.8 代码。

项目还需要配置能读取这些注解的静态类型检查器；普通解释器运行函数时并不会按注解自动阻止传入错误对象。对仍支持旧解释器的项目，应根据目标版本调整联合类型、泛型及相应导入；需要回移的新类型能力时，可查官方文档指向的 typing_extensions，但不必为当前示例增加无用依赖。

小协议、两个实现与显式注入

示例六个节点是render_title、TitleCatalog、MemoryTitles、TupleTitles、字典数据与条目元组。消费者依赖 TitleCatalog 的查询能力；两个具体实现分别保存字典数据和条目元组。结构关系不依赖运行时继承链。

from typing import Protocol

class TitleCatalog(Protocol):
    # 仅允许位置传参，参数名称不作为调用方的关键字契约。
    def get(self, key: str, /) -> str | None:
        ...

class MemoryTitles:
    def __init__(self, data: dict[str, str]) -> None:
        self._data = dict(data)  # 拷贝输入，避免依赖外部字典后续修改。

    def get(self, key: str, /) -> str | None:
        return self._data.get(key)

class TupleTitles:
    def __init__(self, entries: tuple[tuple[str, str], ...]) -> None:
        self._entries = entries

    def get(self, key: str, /) -> str | None:
        # 教学实现：顺序查找，重复编号时采用第一条。
        for entry_key, value in self._entries:
            if entry_key == key:
                return value
        return None

def render_title(key: str, catalog: TitleCatalog) -> str:
    value = catalog.get(key)
    if value is None:
        raise LookupError("没有对应标题")
    cleaned = value.strip()
    if not cleaned:
        raise ValueError("标题不能为空白")
    return f"标题：{cleaned}"

if __name__ == "__main__":
    # 显式标注让类型检查器在赋值处检查结构契约；不是运行时转换。
    memory: TitleCatalog = MemoryTitles({"demo": "演示条目"})
    frozen: TitleCatalog = TupleTitles((("demo", "演示条目"),))
    print(render_title("demo", memory))
    print(render_title("demo", frozen))

两种对象没有继承 TitleCatalog，但都提供所需查询签名。参数注解使消费者不必知道数据存放在哪里，真正的注入仍来自 render_title("demo", memory) 这样的调用。

若读者执行该教学例子，两个调用按逻辑都应形成“标题：演示条目”；本文未运行代码，也没有类型检查通过的实测报告。字典查询与元组遍历的性能和重复键语义不同，它们只在此处需要的读取契约与样本数据上可替换，不能推导出所有场景等价。

方法同名还不够，兼容的是整个调用约定

依赖如果也叫 get，却要求 int 参数，或返回 bytes，就不符合这里的协议。参数数量、位置与关键字规则、默认值及返回类型都应能兼容消费者的调用方式，不能用同名方法判断静态可替换性。

本例的 / 将编号参数设为仅位置参数。如果实际消费者需要 get(key="demo")，协议与实现就要支持对应的关键字参数名，而不能直接套用本例签名。不要为了消除检查提示把所有参数换成 Any，那会丢失这个契约的重要约束。

旧组件方法名或返回形式不同，可以写适配器，把其结果明确转换到 str | None，并处理旧组件的“不存在”情况。适配器不应把网络故障、权限失败等所有异常都吞掉后返回 None，否则消费者无法区分真正缺失与依赖失败。

如果消费者只读取一个属性，协议中可用只读 @property 描述；直接声明可读写属性会赋予消费者写入该属性的能力，类型兼容要求也不同。不要把“我只读取”误写成“我还可以改成任意值”。

运行时成员检查不能证明行为可替换

将静态检查、签名契约归入类型边界，将成员检查、对象成员归入运行时形状，将行为测试、业务语义归入业务边界。静态检查对照签名；运行时成员检查查看成员是否存在；行为测试才针对业务约定。三层不能互相代替。

普通协议不能直接放在 isinstance() 的第二个参数。确实需要简单的运行时结构判断时，可以对协议本身显式使用 @runtime_checkable，但它只检查规定成员的存在，不核对成员的完整类型签名：

from typing import Protocol, runtime_checkable

@runtime_checkable
class HasGet(Protocol):
    def get(self, key: str, /) -> str | None:
        ...

class WrongShape:
    # 参数和返回类型不符合协议，但依然具有名为 get 的方法。
    def get(self, key: int, /) -> int:
        return key + 1

print(isinstance(WrongShape(), HasGet))
# 此检查只问成员是否存在，不能把其结果当成静态签名验证。

这个例子刻意对比成员形状与类型契约，不建议用这段判断给任意插件“认证”。静态检查器还可能提示检查对象与协议之间的兼容问题；具体诊断应以项目工具为准。动态对象、未注解代码和 Any 传播也会影响静态检查覆盖范围。

业务与资源约束仍要明确安排

Protocol 不自动提高运行速度，也不附带重试、超时或资源释放。例子使用内存数据，不涉及连接；真实实现如果持有数据库或 HTTP 客户端，应由创建它的一方明确管理生命周期。不要把 close() 加进协议后就以为消费者一定会调用它。

可在项目行为测试中让两个实现接受同一组样本：存在编号、缺失编号、空白标题，再对各自特有的失败方式补充测试。测试替身要模拟契约，而不是永远返回成功字符串。这样的测试是读者的集成建议，本文不伪造执行结果。

官方协议规范：https://typing.python.org/en/latest/spec/protocol.html
结构化子类型参考：https://typing.python.org/en/latest/reference/protocols.html

两个相关问题

实现类必须写 class Impl(ProtocolName) 吗？不用。兼容结构即可供静态检查；显式继承是另一种选择，但不会自动生成缺失实现。

有 Protocol 就不需要行为测试了吗？仍需要。类型检查不能保证返回值来自正确记录、权限处理正确或错误语义一致。

用 Protocol 描述可替换依赖，关键是定义消费者真正需要的小能力，再将对象明确传入。签名兼容交给类型检查辅助，成员形状与业务行为分别判断，才能避免把“看起来有这个方法”误当成“完整可替换”。