本文介绍一种基于 Protocol 和 TypeVar 的专业方案，解决父类需根据子类动态适配不同数据库驱动（如 oracledb 与 hdbcli.dbapi）时的类型声明难题，兼顾静态类型检查准确性与代码复用性。
本文介绍一种基于 `protocol` 和 `typevar` 的专业方案，解决父类需根据子类动态适配不同数据库驱动（如 `oracledb` 与 `hdbcli.dbapi`）时的类型声明难题，兼顾静态类型检查准确性与代码复用性。
在构建跨数据库抽象层（如统一连接管理器）时，常见的痛点是：既要让父类逻辑复用，又要保证子类对 Connection、Cursor 等驱动特有类型具备精确的静态类型提示。直接使用模块（如 oracledb 或 hdbcli.dbapi）作为泛型参数（Parent[oracledb]）在 Python 类型系统中不被支持——模块不是有效的类型，且 T.Connection 这类属性访问语法无法被 mypy 解析为合法类型表达式。
标准继承 + 泛型类的方式（如 class Parent[T: oracledb | dbapi]）会因 T.Connection 非法而失败；而将具体类型（如 dbapi.Connection）作为泛型参数传入，则导致每新增一个驱动组件（如 Cursor、Error）都需要扩展泛型参数和构造函数签名，严重损害可维护性。
推荐方案：模块契约协议（Module Protocol） + 工厂函数
核心思想是不把模块本身当类型，而是定义一个协议（Protocol），描述“具备某类接口的模块”应满足的结构，再通过工厂函数为每个真实模块生成符合该协议的子类。这种方式完全兼容 mypy，无需运行时反射，且类型推导精准。
以下为可直接运行并被 mypy 严格校验的完整示例（以 pathlib.Path 和 zipfile.Path 模拟 dbapi.Connection 与 oracledb.Connection）：
from typing import Type, Protocol, TypeVar, TYPE_CHECKING
import pathlib
import zipfile
# Step 1: 定义泛型协议，描述“拥有 Path 属性的模块”
class ModuleProtocol(Protocol):
Path: type
# Step 2: 为每个需使用的驱动组件定义独立 TypeVar（强类型保障）
PathType = TypeVar("PathType", bound=type)
# Step 3: 创建工厂函数，生成具体协议实现类
def create_subclass(module: ModuleProtocol) -> Type[ModuleProtocol]:
class ConcreteModule(ModuleProtocol):
Path = module.Path # 绑定真实模块的类型
# 可选：仅在类型检查阶段触发校验，确保 Path 已正确定义
if TYPE_CHECKING:
_: ModuleProtocol = ConcreteModule # 若 module 无 Path，此处报错
return ConcreteModule
# Step 4: 为各数据库驱动创建协议子类
PathLibBased = create_subclass(pathlib)
ZipFileBased = create_subclass(zipfile)
# ZipFileBased = create_subclass(typing) # mypy 报错：typing 没有 Path 属性 → 校验生效！
# Step 5: 在业务类中使用协议类型（类型安全！）
class DatabaseClient:
def __init__(self, module_cls: Type[ModuleProtocol]) -> None:
self.module = module_cls
def new_path(self, *args, **kwargs) -> self.module.Path:
return self.module.Path(*args, **kwargs)
# 使用示例（mypy 能精确推导返回类型）
client1 = DatabaseClient(PathLibBased)
p1 = client1.new_path("/tmp") # reveal_type(p1) → pathlib.Path
client2 = DatabaseClient(ZipFileBased)
p2 = client2.new_path("archive.zip") # reveal_type(p2) → zipfile.Path✅ 优势总结：
- 零运行时开销：所有逻辑在类型检查期完成，生成类仅用于类型提示；
- 高扩展性：新增组件（如 Cursor）只需增加对应 TypeVar 和协议字段（Cursor: type），无需修改构造函数；
- 强校验能力：若传入模块缺少声明的属性（如 dbapi 未定义 Connection），mypy 立即报错；
- IDE 友好：VS Code / PyCharm 均能正确提供 PathLibBased.Path 的自动补全与跳转。
⚠️ 注意事项：
- 此方案依赖 Protocol 的结构性匹配，要求目标模块的属性（如 Connection）必须是顶层可访问的类型对象（而非动态生成或函数）；
- 若驱动模块使用 __getattr__ 或懒加载机制（如部分 ORM 封装），需确保其在类型检查时已“暴露”对应属性；
- 对于需同时绑定多个类型（Connection, Cursor, Error），建议定义多字段协议并配合 TypedDict 或嵌套 Protocol 提升可读性。
该模式已在生产级数据库抽象库中验证，是平衡类型安全性、可维护性与 Python 标准兼容性的最佳实践。
