pgvecto.rs 后端服务模块化设计与 Mock 测试实践

项目背景

pgvecto.rs 是一个基于 Rust 的向量数据库扩展项目，旨在为 PostgreSQL 提供高效的向量搜索能力。随着项目规模的扩大，代码复杂度不断增加，团队决定对后端服务进行模块化拆分，以提升代码的可维护性和可测试性。

模块化设计思路

Worker 模块架构

Worker 作为核心调度单元，采用了分层设计理念：

1. Worker 核心层：负责整体调度和生命周期管理
2. WorkerProtect 保护层：处理启动逻辑和资源保护
3. WorkerView 视图层：提供对外的操作接口

这种设计通过清晰的职责划分，使得各层可以独立演进和测试。特别是将视图层与核心逻辑分离，既保证了接口稳定性，又允许内部实现灵活调整。

Index 模块设计

索引模块采用了类似的模式：

1. Index 核心：管理索引全生命周期
2. IndexProtect：处理底层段(segment)管理和启动流程
3. IndexView：提供外部访问接口

特别值得注意的是索引模块与优化器(Optimizer)的交互设计，将索引构建(Indexing)和密封(Sealing)过程抽象为独立组件，便于针对不同场景定制优化策略。

Mock 测试策略

项目采用了系统化的 Mock 测试方案，针对不同模块特性选择了合适的模拟策略：

Worker 模块 Mock 方案

1. 核心 Worker：作为独立单元不进行 Mock，通过临时目录(tempfile)隔离测试环境
2. WorkerProtect：使用 mockall 自动生成模拟实现
3. WorkerView：作为不透明接口不进行 Mock

这种混合策略既保证了关键路径的真实性，又隔离了外部依赖。特别引入了 mockall_double 来处理需要命名空间切换的场景。

Index 模块 Mock 实现

1. Index 和 IndexProtect：使用 mockall 自动生成
2. IndexView：同样采用 mockall 自动生成
3. 段(Segment)管理：将 SealedSegment 和 GrowingSegment 作为外部依赖抽象

对于需要 Clone 特性的 Instance，采用了手动 Mock 实现(mock!)，解决了派生宏与模拟框架的兼容性问题。

关键技术决策

1. 依赖隔离：通过分层设计将文件系统(std::fs)等平台依赖限制在核心模块
2. 无副作用组件：对 Uuid 和时间戳(std::time::Instant)等无副作用组件不做 Mock
3. 生命周期管理：使用 tempfile 创建临时目录，确保测试隔离性
4. 复杂类型处理：对于包含泛型生命周期的返回类型，采用手动 Mock 实现

架构演进方向

当前设计为后续演进预留了空间：

1. 读写层抽象：计划将数据访问层进一步抽象，支持多种存储后端
2. 库接口标准化：正在设计统一的库级别接口，便于不同场景集成
3. 优化器扩展：优化器接口设计支持未来添加更多优化策略

这种模块化架构不仅提升了当前代码质量，也为项目未来的功能扩展奠定了坚实基础。通过清晰的接口定义和彻底的测试隔离，团队可以更安全地进行迭代开发。