junhong_cmp_fiber/openspec/changes/archive/2026-01-22-optimize-test-db-connection/design.md

Design: 优化测试数据库连接管理

Context

当前测试架构在每个测试用例中独立创建数据库和 Redis 连接,导致严重的性能问题和资源浪费。随着测试用例数量增长(已达 200+),测试套件运行时间从最初的 10 秒增长到 70+ 秒,严重影响开发效率。

现状:

• 每个测试调用 SetupTestDB(t) 创建新连接
• 每次连接都执行 AutoMigrate(检查 8 张表结构)
• 连接配置硬编码在 testutils/setup.go 中
• Redis 连接在每个测试中独立创建和关闭

约束:

• 必须保持远程测试数据库(开发机器资源有限)
• 必须保持测试间完全隔离(事务回滚)
• 必须支持向后兼容(渐进迁移)
• 必须确保资源自动清理(防止泄漏)

Goals / Non-Goals

Goals

1. 性能提升: 测试套件运行速度提升 ≥ 5 倍
2. 资源节省: 内存占用降低 ≥ 70%,网络连接数降低到 1
3. 简洁 API: 测试代码行数减少,意图更清晰
4. 自动清理: 使用 t.Cleanup() 确保资源自动释放
5. 向后兼容: 新旧方案共存,支持渐进迁移
6. 规范化: 建立测试连接管理的标准规范

Non-Goals

1. ❌ 本地数据库支持(开发机器资源有限)
2. ❌ Mock 数据库方案(需要真实数据库验证业务逻辑)
3. ❌ 并发测试优化(GORM 事务非线程安全)
4. ❌ 一次性强制迁移所有测试(渐进式迁移更安全)

Decisions

Decision 1: 全局单例连接池

决策: 使用 sync.Once 实现全局单例数据库和 Redis 连接,整个测试套件共享。

理由:

• ✅ 性能: 只创建一次连接,消除重复开销
• ✅ 简单: Go 标准库支持,无需引入依赖
• ✅ 安全: sync.Once 保证线程安全
• ✅ 兼容: 不影响现有测试

实现:

var (
    testDBOnce    sync.Once
    testDB        *gorm.DB
    testRedisOnce sync.Once
    testRedis     *redis.Client
)

func GetTestDB(t *testing.T) *gorm.DB {
    testDBOnce.Do(func() {
        // 创建连接和 AutoMigrate (只执行一次)
    })
    return testDB
}

替代方案:

• ❌ 每个测试独立连接: 现状,性能差
• ❌ TestMain 初始化: 不灵活,无法在子包中使用
• ❌ 依赖注入框架: 过度设计,增加复杂度

---

Decision 2: 基于 t.Cleanup() 的自动清理

决策: 使用 Go 1.14+ 的 t.Cleanup() 机制替代 defer,确保资源自动释放。

理由:

• ✅ 可靠: 即使测试 panic 也能执行清理
• ✅ 简洁: 无需手动 defer,API 更直观
• ✅ 灵活: 支持注册多个清理函数
• ✅ 标准: Go 官方推荐的测试清理模式

实现:

func NewTestTransaction(t *testing.T) *gorm.DB {
    tx := GetTestDB(t).Begin()
    t.Cleanup(func() {
        tx.Rollback()
    })
    return tx
}

替代方案:

• ❌ 手动 defer: 需要开发者记住,容易遗漏
• ❌ TeardownTestDB: 需要配对调用,样板代码多
• ❌ TestMain 清理: 无法针对单个测试清理

---

Decision 3: 测试名称作为 Redis 键前缀

决策: 自动使用 t.Name() 作为 Redis 键前缀,格式: test:{TestName}:*

理由:

• ✅ 隔离: 不同测试的键自动隔离
• ✅ 自动化: 无需手动指定前缀
• ✅ 可追溯: 键名包含测试名称,方便调试
• ✅ 支持嵌套: 子测试继承父测试前缀

实现:

func CleanTestRedisKeys(t *testing.T) {
    testPrefix := fmt.Sprintf("test:%s:", t.Name())
    // 清理已有键
    keys, _ := rdb.Keys(ctx, testPrefix+"*").Result()
    if len(keys) > 0 {
        rdb.Del(ctx, keys...)
    }
    // 注册清理函数
    t.Cleanup(func() {
        keys, _ := rdb.Keys(ctx, testPrefix+"*").Result()
        if len(keys) > 0 {
            rdb.Del(ctx, keys...)
        }
    })
}

替代方案:

• ❌ 手动指定前缀: 容易冲突,样板代码多
• ❌ UUID 前缀: 不可读,调试困难
• ❌ 全局清理: 可能误删其他测试的数据

---

Decision 4: 向后兼容策略

决策: 保留旧的 SetupTestDB/TeardownTestDB,标记为 Deprecated,支持渐进迁移。

理由:

• ✅ 风险低: 现有测试继续正常运行
• ✅ 灵活: 可以逐个文件迁移,不强制一次性完成
• ✅ 可观察: 可以对比迁移前后的性能
• ✅ 可回退: 如果新方案有问题,可以快速回退

实现:

// Deprecated: 使用 NewTestTransaction 和 CleanTestRedisKeys 代替
// 迁移示例:
//   旧: db, rdb := SetupTestDB(t); defer TeardownTestDB(t, db, rdb)
//   新: tx := NewTestTransaction(t); CleanTestRedisKeys(t)
func SetupTestDB(t *testing.T) (*gorm.DB, *redis.Client) {
    // 保留现有实现
}

替代方案:

• ❌ 直接删除旧函数: 破坏所有现有测试,风险极高
• ❌ 立即迁移所有测试: 工作量大,容易引入 bug
• ❌ 维护两套独立实现: 增加维护成本

---

Decision 5: 事务隔离级别

决策: 使用数据库默认事务隔离级别(PostgreSQL: READ COMMITTED),不强制指定。

理由:

• ✅ 简单: 无需额外配置
• ✅ 足够: 测试隔离只需回滚,不需要特殊隔离级别
• ✅ 兼容: 与生产环境保持一致
• ✅ 性能: READ COMMITTED 性能较好

实现:

tx := db.Begin()  // 使用默认隔离级别

替代方案:

• ❌ SERIALIZABLE: 性能差,测试不需要
• ❌ READ UNCOMMITTED: 可能读到脏数据
• ❌ REPEATABLE READ: 可能死锁,测试不需要

Risks / Trade-offs

Risk 1: 连接池耗尽

风险: 如果测试并发运行,单个连接池可能成为瓶颈。

影响: 测试可能等待连接,耗时增加。

缓解措施:

• 监控连接池使用情况
• 如有需要,调整 max_open_conns 配置
• 测试默认串行运行,并发风险较低

---

Risk 2: 事务长时间持有

风险: 如果单个测试运行时间过长,事务长时间持有可能影响其他测试。

影响: 数据库锁等待,测试变慢。

缓解措施:

• 优化慢测试,确保单个测试 < 1 秒
• 避免在测试中执行耗时操作(如 HTTP 请求)
• 使用 t.Parallel() 需要每个测试独立事务

---

Risk 3: Redis 键命名冲突

风险: 如果测试名称包含特殊字符,可能导致键名冲突。

影响: 测试间数据污染。

缓解措施:

• 使用 t.Name() 自动生成前缀,降低冲突风险
• 文档说明 Redis 键命名规范
• 提供手动指定前缀的选项(如有需要)

---

Trade-off 1: 连接创建延迟 vs 内存占用

选择: 全局单例连接,首次创建耗时 ~300ms,之后复用。

权衡:

• ✅ 优点: 后续测试几乎零开销,总耗时大幅降低
• ⚠️ 缺点: 首个测试需要承担初始化时间
• ✅ 决策: 接受首次延迟,换取整体性能提升

---

Trade-off 2: 向后兼容 vs 代码简洁

选择: 保留旧函数,标记为 Deprecated,而非直接删除。

权衡:

• ✅ 优点: 现有测试无需修改,渐进迁移
• ⚠️ 缺点: 维护两套 API,增加维护成本
• ✅ 决策: 接受短期维护成本,换取迁移灵活性

Migration Plan

Phase 1: 创建新工具(不影响现有测试)

时间: 1 天

步骤:

1. 创建 tests/testutils/db.go
2. 实现全局单例连接管理函数
3. 添加完整的文档注释

验证:

• 运行现有测试,确保无影响
• 手动测试新 API 功能正确性

---

Phase 2: 小规模验证(选择 2-3 个测试)

时间: 1 天

步骤:

1. 选择 2-3 个简单的单元测试
2. 迁移到新的连接管理方式
3. 对比迁移前后的性能

验证:

• 功能正确性: 测试通过,结果一致
• 性能提升: 单测耗时降低 > 80%
• 资源清理: 无连接泄漏

---

Phase 3: 批量迁移(渐进式)

时间: 3-5 天

步骤:

1. 迁移所有 unit 测试(约 20 个文件)
2. 迁移所有 integration 测试(约 13 个文件)
3. 每迁移一批,运行测试验证

优先级:

• 高: 高频测试(每次 PR 都运行)
• 中: 功能测试
• 低: 边缘 case 测试

回退策略:

• 如果新方案有问题,保留旧代码可立即回退
• 每批迁移前创建 git commit,方便回滚

---

Phase 4: 标记旧 API 为 Deprecated

时间: 1 天

步骤:

1. 在 SetupTestDB/TeardownTestDB 添加 Deprecated 注释
2. 提供迁移指引
3. 更新文档和 AGENTS.md

验证:

• IDE 显示 Deprecated 警告
• 文档包含迁移示例

---

Phase 5: 观察期(可选)

时间: 1-2 周

步骤:

1. 监控测试套件运行时间
2. 收集开发者反馈
3. 优化文档和常见问题

决策点:

• 如果稳定运行 2 周,可以移除旧 API
• 如果发现问题,继续优化新方案

---

Rollback Plan

触发条件:

• 新方案导致测试不稳定
• 发现关键 bug 无法快速修复
• 性能提升不如预期

回滚步骤:

1. 恢复使用 SetupTestDB/TeardownTestDB
2. 将已迁移的测试回退到旧方案
3. 分析问题,优化新方案后再尝试

Open Questions

Q1: 是否需要支持本地数据库?

背景: 当前只支持远程数据库,开发机器资源有限。

选项:

• A: 保持现状,只支持远程数据库
• B: 提供 Docker Compose 支持本地数据库(可选)

决策: 待定,暂时保持 A,未来可扩展 B

---

Q2: 是否需要支持并发测试?

背景: 当前方案使用事务隔离,不支持 t.Parallel()。

选项:

• A: 不支持,文档说明限制
• B: 每个并发测试开启独立事务

决策: B,但文档说明需要手动处理

---

Q3: 旧 API 何时移除?

背景: 保留 Deprecated API 增加维护成本。

选项:

• A: 永久保留(向后兼容)
• B: 迁移完成后立即删除
• C: 观察 1-2 个月后删除

决策: C,观察期后删除,确保稳定性