本文介绍一种基于 protocol 和泛型工厂函数的 python 类型安全方案，使父类能静态感知子类所绑定的数据库模块（如 oracledb 或 hdbcli.dbapi），从而正确推导 connection、cursor 等类型，避免运行时类型擦除与 mypy 报错。
本文介绍一种基于 protocol 和泛型工厂函数的 python 类型安全方案，使父类能静态感知子类所绑定的数据库模块（如 oracledb 或 hdbcli.dbapi），从而正确推导 connection、cursor 等类型，避免运行时类型擦除与 mypy 报错。
在构建跨数据库抽象层（例如统一封装 HANA 与 Oracle 客户端）时，常见痛点是：既要复用父类逻辑，又要保证子类对各自底层模块（如 oracledb.Connection 或 hdbcli.dbapi.Connection）的类型完全可见。直接使用 TypeVar 约束模块对象（如 T: oracledb | dbapi）会失败——因为模块不是合法类型，且 T.Connection 不是有效的类型表达式。
标准继承 + 泛型类的方式在此场景下受限。Python 的 __orig_bases__ 和 get_args 属于运行时机制，无法被 mypy 在静态检查阶段可靠解析；而将 Connection 类型作为构造参数传入（如 Parent[dbapi.Connection]）虽可行，但扩展性差：一旦还需支持 Cursor、Error、connect() 等多个成员，便需重复声明多个泛型参数与构造参数，违背 DRY 原则。
✅ 推荐方案：Protocol + 模块级类型工厂函数
核心思想是：不把模块本身当类型，而是定义一个协议（Protocol），描述“具备某类接口的模块”应满足的结构；再通过工厂函数，在编译期为每个具体模块生成符合该协议的子类型。这既保留了类型完整性，又无需运行时反射。
以下是一个可直接迁移至数据库场景的最小可行示例（已适配 oracledb 和 hdbcli.dbapi）：
from typing import Type, Protocol, TypeVar, TYPE_CHECKING
import oracledb
from hdbcli import dbapi
# Step 1: 为每个需复用的类定义独立 TypeVar
ConnectionType = TypeVar("ConnectionType", bound=Type[object])
CursorType = TypeVar("CursorType", bound=Type[object])
# Step 2: 定义模块协议 —— 要求模块必须提供 Connection 和 Cursor
class DatabaseModuleProtocol(Protocol[ConnectionType, CursorType]):
Connection: ConnectionType
Cursor: CursorType
# Step 3: 工厂函数 —— 静态验证并生成专用子类型
def make_database_backend(
module: DatabaseModuleProtocol[ConnectionType, CursorType]
) -> Type[DatabaseModuleProtocol[ConnectionType, CursorType]]:
class ConcreteBackend(DatabaseModuleProtocol[ConnectionType, CursorType]):
Connection = module.Connection
Cursor = module.Cursor
# ✅ 关键：TYPE_CHECKING 下强制校验协议实现
if TYPE_CHECKING:
_: DatabaseModuleProtocol[ConnectionType, CursorType] = ConcreteBackend
return ConcreteBackend
# Step 4: 为各数据库创建强类型后端
OracleBackend = make_database_backend(oracledb)
HanaBackend = make_database_backend(dbapi)
# ✅ 静态类型检查通过！
# reveal_type(OracleBackend.Connection) # → oracledb.Connection
# reveal_type(HanaBackend.Cursor) # → hdbcli.dbapi.Cursor基于此，可构建真正类型安全的抽象基类：
class DatabaseClient:
def __init__(self, backend: DatabaseModuleProtocol):
self._backend = backend
def connect(self, **kwargs) -> "backend.Connection":
return self._backend.Connection(**kwargs)
def cursor(self, conn) -> "backend.Cursor":
return conn.cursor()
# 使用示例（类型精准）
oracle_client = DatabaseClient(OracleBackend)
hana_client = DatabaseClient(HanaBackend)
conn = oracle_client.connect(dsn="...") # ✅ 类型为 oracledb.Connection
cursor = oracle_client.cursor(conn) # ✅ 类型为 oracledb.Cursor⚠️ 注意事项与最佳实践：
- TYPE_CHECKING 块中的 _: 赋值是关键技巧：它触发 mypy 对 ConcreteBackend 是否完整实现 DatabaseModuleProtocol 的校验，缺失 Connection 或 Cursor 将立即报错；
- 每个需暴露的模块成员（如 Error, connect, paramstyle）都应在 Protocol 中显式声明，并配以对应 TypeVar，确保类型链完整；
- 此方案兼容标准 mypy（无需 basedmypy），零运行时代价，纯静态类型增强；
- 若模块接口不稳定（如 hdbcli.dbapi 某版本移除了 Cursor），mypy 会在首次构建 HanaBackend 时捕获，实现早期失败。
总结：当需要让父类“感知”子类所选的第三方模块类型时，放弃对模块对象的泛型约束，转而采用 Protocol 描述接口契约 + 工厂函数生成协议实现类，是最符合 PEP 484、兼顾类型精度与工程可维护性的专业解法。
