外观
用 Protocol 与分层接口隔离业务和外部依赖
摘要
查询只改一行,测试却必须连数据库。本文面向有开发经验的 Python 初学者,用内存和 SQLite 实现讲清 Protocol、类型收窄与可替换契约。
资料核验日期为 2026-10-29;mypy 官网使用滚动文档,本文不把该页面称为固定版本源码。实际工具版本和运行证据以工程实践与验收手册为准。
本篇静态检查实测使用 Windows x64、CPython 3.13.7、mypy 2.4.1(纯 Python wheel,compiled: no)。严格检查通过;返回类型不兼容的副本检查失败,SQL 降序副本则类型检查通过、契约运行失败。
1. 场景:业务测试为什么离不开数据库
这是教学场景:日志查询函数接收一个 SQLite 连接,自己拼 SQL、取行、校验分页,再包装输出。后来团队想先在内存里运行单元测试,发现业务函数处处调用 execute。有人写了一个假的连接,让它返回预先准备的行,测试变绿;真正的 SQL 少写了排序,线上分页仍重复和遗漏。
判断能否替换仓储,分三步:调用方能否使用相同方法与签名,得到的顺序和错误是否相同,资源最终是否仍由正确的拥有者释放。第一步是结构,第二步是语义,第三步是生命周期。Protocol用所需成员与签名描述结构接口,主要帮助检查第一步;把这三步分开,就不会因为假的连接返回了一份正确列表而推导出真实SQL也正确。
本篇保持query不变,只替换MemoryRepository与SQLiteRepository。业务决定合法分页,仓储兑现数据契约,入口组装并关闭资源。后面用同一组反序写入、分页与重复键追踪两个实现:方法名相同只是起点,结果与失败后的状态才说明替换是否成立。
Repository,仓储,是为业务提供数据存取接口的对象。本篇不把它当成某个框架的特殊基类,只把它定义为两项能力:写入事件,按游标读取一页。Protocol 是 Python 类型系统表达结构接口的方式:检查对象是否具备所需成员与兼容签名,而不要求它显式继承接口。已有其他语言经验的读者可从接口想到它,但必须注意静态检查与运行行为的区别。
先读类与方法绑定和类型注解,再看本篇会更顺。类告诉我们方法如何接到实例;类型系统告诉我们希望对象提供什么;本篇进一步规定这些方法应具有怎样的业务语义。
2. 结构类型回答“具备什么”,名义类型回答“属于谁”
Nominal typing,名义类型,依靠声明的继承关系判断类型归属;structural typing,结构类型,依靠所提供的成员结构。示例中的 MemoryRepository 和 SQLiteRepository 都没有继承 EventRepository,只要方法签名满足 Protocol,就能作为参数传入 query。静态工具可在调用处发现参数不兼容,而 Python 运行时仍按普通方法调用执行。
鸭子类型常被概括成“能做某事就当成某物”。Protocol 把原先只存在于口头约定的能力表达为静态可检查的接口,但不自动执行数据校验。给 page 标注返回 list[Event],不会阻止错误实现返回字典;未经静态检查的程序仍可能运行到使用返回值时才失败。注解在此是分析工具的输入,不是数据库行到业务对象的运行时转换器,见typing Protocol。
@runtime_checkable 允许某些 Protocol 用于 isinstance,但运行检查主要检查成员存在,并不验证完整签名与业务语义。一个 page 方法接收参数不对、永远抛异常,仍可能通过成员存在检查。因此不能用运行时 Protocol 检查替代请求校验,也不能说“isinstance 为真,所以这个插件满足分页约定”。本例刻意不依赖 runtime_checkable,替换能力由静态检查和契约测试共同验证。
还应避免把所有实现细节塞进接口。业务 query 不需要 connection、commit 或 SQLite 的游标对象,因此 Protocol 不声明它们。如果接口直接返回 sqlite3.Row 或连接,业务依然会绑定存储技术,只是多了一层名为接口的包装。返回独立 Event 值对象,使 SQL 行的解释留在存储层。
Event 是 dataclass,即自动生成常见数据类方法的标准库装饰器;frozen=True 限制字段赋值,便于把事件视为已确定的值。它不递归冻结嵌套对象,当前字段都是整数与字符串,才使这个值对象没有额外的可变子图。需要嵌套列表时,必须重新评估对象引用里的所有权边界。
3. 接口签名之外,必须写出语义契约
示例 page 的约定是:按 id 升序;只返回 id 大于 after 的事件;最多 limit 条;没有数据返回空列表。add 的约定是重复 id 抛 ValueError,且不能覆盖原记录。query 负责拒绝负游标和范围外的页大小;允许页大小一到一百。这些并非类型签名能够表达的全部属性。
先把实现名称遮住,预测这组操作:写入id二,再写入id一,执行query(0,1)。按契约,第一条必须是id一;继续query(1,2),只应得到id二。追踪的是按id排序后的边界,而非写入次序。MemoryRepository的字典保存顺序不能直接兑现这个约定,所以page显式sorted;SQLiteRepository则通过ORDER BY兑现同一约定。
接着仅改变一次写入:再次写id一。它应抛ValueError,记录总数仍为二。主例先检查重复错误,再查询总数,避免“异常类型正确,但已经多写数据”的假成功;原记录内容保持不变则是后续加深验收的任务。对两个实现使用同一组输入,使差异落在存取机制,业务query与验收目标都不改变。
SQLite 的 IntegrityError 在仓储边界转换为契约里的重复错误,并保留 from exc 异常链。这里表结构只有一个主键约束,所以映射有明确前提;真实表存在外键、非空和其他唯一约束时,不能把所有 IntegrityError 都叫“重复事件”。先识别约束或建立更细的领域错误,再决定 API 映射。
游标分页相对按偏移分页有不同边界。本例用唯一递增 id 作为游标,避免已返回记录再次进入下一页,但并没有提供一次查询期间的快照一致性。新插入较小 id 的记录可能落在过去游标之前,删除可能改变总体条数。需要稳定快照、复合排序或迟到日志时,必须扩大契约,不能用“采用游标”四个字保证全部行为。
图表将在阅读到此处时加载…
图中入口负责选实现;业务只依赖自己需要的能力。具体数据库依赖位于外层,领域对象没有反向导入数据库。这里的“反转”指代码依赖方向,不意味着执行时数据库在业务之前主动调用业务。
4. 类型收窄把不确定输入变成确定能力
Narrowing,类型收窄,是控制流检查后将一个较宽类型缩小到已知类型。例如从 JSON 得到未知字段,可先以 object 表示它,经过 isinstance(raw, str) 才调用 strip。object 可以容纳任意对象,但使用前需要证明能力;Any 则允许工具跳过许多检查,容易把未知边界带到整个调用链。
静态收窄与运行时验证相互配合:isinstance 本身真的在执行时检查,工具又可以据此知道后续分支 raw 是字符串。检查完之后,字符串是否为空、长度是否超限、内容是否允许,还需要额外规则。类型为 str 并不证明它是合法日志路径。
不要把 assert 用作外部数据验证;优化运行可能移除断言。示例 raw 的显式异常是输入政策,contract 中断言则是教学验收。也不要用 cast 掩盖工具报错:cast 只告诉静态工具接受你声称的类型,不会把字典变成 Event 或把字符串变成整数。要找出数据来源与运行时转换边界,而不是让编辑器红线消失。
签名还涉及可替换性:业务可能传入 Protocol 允许的任意参数,实现不能私自只接受一半。返回值则应满足调用方可用的能力。如果实现的 limit 参数改名,在调用方使用关键字时可能失败,静态签名分析也可能发现不兼容。接口稳定性包括参数用法、异常语义与生命周期,不能只比较方法名称。
5. 完整实验与静态检查
完整程序 26_protocol.py 无第三方运行依赖。它对两个实现执行同一 contract,检查反序输入、两页结果、重复写入和最终条数;数据库连接在 finally 关闭。内存替换是在真实业务 query 上发生,不是另外写一个绕过业务的测试函数。
python
"""同一查询业务契约运行在内存与 SQLite 仓储上;可直接 mypy 检查。"""
from dataclasses import dataclass
import sqlite3
from typing import Protocol
@dataclass(frozen=True)
class Event:
id: int
path: str
status: int
class EventRepository(Protocol):
def add(self, event: Event) -> None: ...
def page(self, after: int, limit: int) -> list[Event]: ...
class MemoryRepository:
def __init__(self) -> None:
self._events: dict[int, Event] = {}
def add(self, event: Event) -> None:
if event.id in self._events:
raise ValueError("duplicate id")
self._events[event.id] = event
def page(self, after: int, limit: int) -> list[Event]:
return [self._events[key] for key in sorted(self._events) if key > after][:limit]
class SQLiteRepository:
def __init__(self) -> None:
self.connection = sqlite3.connect(":memory:")
self.connection.execute("CREATE TABLE events(id INTEGER PRIMARY KEY, path TEXT, status INTEGER)")
def add(self, event: Event) -> None:
try:
with self.connection:
self.connection.execute("INSERT INTO events VALUES(?,?,?)", (event.id, event.path, event.status))
except sqlite3.IntegrityError as exc:
raise ValueError("duplicate id") from exc
def page(self, after: int, limit: int) -> list[Event]:
rows = self.connection.execute("SELECT id,path,status FROM events WHERE id>? ORDER BY id LIMIT ?",
(after, limit)).fetchall()
return [Event(int(row[0]), str(row[1]), int(row[2])) for row in rows]
def close(self) -> None:
self.connection.close()
def query(repository: EventRepository, after: int, limit: int) -> list[Event]:
# 业务边界负责合法性,仓储契约规定顺序、游标、重复键行为。
if after < 0 or not 1 <= limit <= 100:
raise ValueError("invalid page")
return repository.page(after, limit)
def contract(repository: EventRepository) -> None:
repository.add(Event(2, "/orders", 500))
repository.add(Event(1, "/health", 200))
assert query(repository, 0, 1) == [Event(1, "/health", 200)]
assert query(repository, 1, 2) == [Event(2, "/orders", 500)]
try:
repository.add(Event(1, "/duplicate", 200))
except ValueError as exc:
assert str(exc) == "duplicate id"
else:
raise AssertionError("duplicate contract broken")
assert len(query(repository, 0, 100)) == 2
def main() -> None:
contract(MemoryRepository())
database = SQLiteRepository()
try:
contract(database)
finally:
database.close()
# object 表示未知类型;isinstance 收窄后才允许字符串方法。
raw: object = " /orders "
if not isinstance(raw, str):
raise ValueError("path must be str")
assert raw.strip() == "/orders"
print("26 checks: memory/sqlite same contract; duplicate rejected; narrowing")
if __name__ == "__main__":
main()运行 python docs/python/examples/26_protocol.py,预期 26 checks: memory/sqlite same contract; duplicate rejected; narrowing。这证明这几条具体契约在两个实现成立,不证明生产连接池、真实 PostgreSQL 并发或跨事务快照。
在配套环境运行 python -m mypy --strict docs/python/examples/26_protocol.py。严格模式检查缺少注解等问题;最终具体工具版本和结果记录在专题验收记录。静态成功只表明当前被分析代码符合工具可表达的类型规则,不能当成分页测试成功。若把 page 的返回注解改为 list[str],应看到接口不兼容;若把 SQLite 排序改为降序,类型仍可能通过,必须由契约测试捕获。
静态工具需额外安装。统一环境使用锁定依赖,在完整 CPython 中运行 python -m pip install -r docs/python/examples/capstone/requirements.lock.txt,再使用同一解释器执行 mypy。标准库示例本身不需要这一步;不能把未安装工具时的报错当成类型不兼容。
把两种坏改动放在同一个分页问题里看,证据边界就清楚了。返回注解改成list[str]时,调用方需要Event的能力已经不匹配,静态检查失败;只把SQL改为降序时,返回值仍是list[Event],类型可以通过,但query(0,1)取到id二,契约断言失败。一个检查结构,一个检查顺序,二者没有相互替代。
这也是迁移到第三种存储的步骤:先让结构检查接得上,再复用同一行为序列,最后添加该存储特有的持久化与恢复证据。恢复故意改动后两项都应通过,不能把失败副本留在正式主线影响后续章节。
6. 生命周期不是接口设计的附录
第三步检查拥有者。主例的入口创建SQLiteRepository,让contract连续查询和写入,最后在finally调用close;query只是借用page能力。沿这条生命线预测第二次查询:第一次query结束并不应关闭仓储,所以第二页仍可读。若把close搬进query,接口签名和首次结果都可能不变,第二次调用却会失败,这正是语义之外的生命周期破坏。
把仓储接到Web应用时,这条拥有者关系仍可保留,只把创建与释放的位置迁移到应用lifespan;请求路由不能因为用过一次就关闭应用级资源。不同连接策略可能要求请求级或事务级拥有者,但必须重新画清边界,不能只换一个框架装配函数。
大型项目可以让仓储实现上下文管理器,或由应用 lifespan 在启动时创建、退出时释放。接口不必一次声明所有资源动作,但必须有可追踪的拥有者。容器或依赖注入框架不会自动知道业务上的正确作用域;连接可以是应用级、请求级或事务级,选择取决于线程安全、事务边界和池化策略。 可进一步阅读SpringAOP代理创建流程:显式注入与框架动态代理有不同绑定机制。
同步与异步仓储也不能随意互换。把 async page 放进同步 Protocol,不会因为它最终返回 list 就兼容;调用得到的是 awaitable,即需要等待的对象。业务若需要异步能力,应在接口上明确 async,并沿调用链等待;不要在每个方法里偷偷 asyncio.run,那会与已运行的事件循环冲突。事件循环篇解释取消与生命周期,数据库篇解释提交与关闭为何不同。
7. 踩坑、独立练习与验收
常见坑是只测试 MemoryRepository,然后宣称所有仓储实现都正确。内存实现不会证明 SQL 的参数绑定、排序或回滚。另一种坑是所有接口返回 Any,让 Protocol 看起来存在,实际每一层都失去检查。还有一种坑是业务捕获 Exception 返回空列表,使数据库故障伪装成“没有记录”;这会破坏 empty 与 failure 的契约区分。
独立练习:新增文件仓储,复用同一个 query 和 contract,不修改业务函数;要求重新启动后已写入记录仍存在,重复 id 拒绝且原记录保持不变。文件存储是否需要原子写入、文件锁与崩溃恢复必须写出范围,不能说通过内存契约就已生产可用。
验收提交接口定义、依赖图、三种实现的相同契约结果、静态检查命令与错误反例、生命周期负责人说明。额外测试 after 恰等于已存在 id、空结果、非法页大小、重复写入后的内容。下一篇测试分层把这类验收分为单元、集成和端到端;后续真实数据库篇会补充本例故意没有证明的并发与持久化边界。
面试若问“Protocol 与抽象基类怎么选”,可先说明约束来源:是否要求显式继承、是否共享默认实现、是否需要静态结构能力、是否要求运行时实例关系。再说明类型系统无法描述的排序、错误与资源语义由测试和文档补足。只回答“Protocol 更灵活”没有解释为什么它适合这里。
一个替换声明应包含哪些反证
替换不仅要展示两个实现都成功,还应寻找它们可能不同的边界。内存字典持有 Event 对象,SQLite 重新构建 Event;当前 frozen 标量字段使结果值相等,但对象身份可以不同。业务契约若只需要值相等,就不应断言返回的是同一个对象;如果业务依赖 identity map,即同一实体重复查询得到同一内存对象,则必须把它加入接口和缓存设计。本例没有该承诺。
异常也是替换的一部分。仓储抛重复错误后是否还能继续查询,重复写入是否覆盖已有数据,失败是否留下一半状态,都应观察。contract 在重复失败之后再次查询并确认总数,避免只证明异常类型正确。进一步可以检查 id 一的 path 仍是 health,防止实现先覆盖内容再抛异常。签名与异常消息一致,却破坏原数据,仍然不满足接口。
SQL 驱动的 fetchall 返回值在类型存根里可能带宽泛类型,显式构建 Event 并不自动保证数据库里的字段有效。本例自己创建并插入受控表,表中不会出现未知结构;正式导入外部数据库应考虑列约束、空值、域范围和迁移兼容。边界出现 Any 时,要尽快通过实际检查转成确定领域值,而不是把 Any 扩散到服务与 API。
接口颗粒度也有取舍。如果某个业务只需要读取,不必强迫它依赖 add,可以再拆只读 Protocol;这减少权限能力和替身负担。若把每个方法都拆成一个接口,也可能让装配变得难以追踪。应依据调用方实际能力集合和独立变动原因划分,而不是照着数据库表机械生成几十个仓储类。
进阶练习可先定义 Reader Protocol,再让 EventRepository 扩展写入能力,query 改为只接收 Reader。验收:一个只有 page 的对象能通过 query 静态检查并正确运行,写入业务仍要求 add;故意把返回类型改为 list[str] 时检查失败。图中业务依赖更窄,具体存储无需改变。这能证明拆接口减少的是实际依赖,而非文件数量。
一句话总结:分层接口让业务依赖稳定能力,替换实现的可信度来自结构检查与相同行为契约。
Protocol表达静态结构,不能自动验证数据或业务语义。- 排序、游标、错误、所有权需要显式契约,并在每个实现上验证。
- 入口负责装配与资源释放,业务服务无需理解具体数据库对象。
参考:typing、dataclasses、sqlite3、mypy Protocol。实际核验范围见工程实践与验收手册。