Golang测试模拟数据库连接实战教程

本文深入剖析了使用 sqlmock 进行 Golang 数据库测试时最常见、最易踩坑的四大核心问题：驱动重复注册导致 panic、SQL 语句匹配失败、RowsAre 与 WillReturnRows 使用错位引发静默失效，以及 mock 实例非并发安全造成的并行测试崩溃；通过真实报错场景、底层原理（如 database/sql 全局驱动注册机制）和可落地的最佳实践（如禁用 init() 初始化、统一占位符风格、每测试独立创建 mock、开启调试日志比对实际 SQL），手把手教你构建稳定、可靠、可维护的数据库单元测试，彻底告别“mock 总是不生效”的抓狂时刻。

sqlmock.New() 初始化失败：panic: sql: Register called twice for driver mock

这是用 sqlmock 时最常遇到的崩溃，不是你代码写错了，而是重复调用了 sql.Open("mock", ...) 或不小心多次执行了 sqlmock.New()。Go 的 database/sql 驱动注册是全局单例，sqlmock 内部也调用了 sql.Register("mock", ...)，第二次就会 panic。

• 确保整个测试包里只调用一次 sqlmock.New()，通常放在 TestMain 或每个测试函数开头（但别在子测试或 helper 函数里再调）
• 不要在 init() 函数中初始化 mock，它可能被多个测试文件触发
• 如果用了 testify/suite，在 SetupTest 里创建 mock 实例，但记得把 *sql.DB 和 sqlmock.Sqlmock 都作为字段存下来，别每次重 New
• 检查是否误把 sqlmock.New() 放在循环或条件分支里 —— 即使没执行到，go test 也会静态扫描并可能触发注册逻辑

ExpectQuery() 匹配不到 SQL：实际执行的语句和 Expect 不一致

sqlmock 默认对 SQL 字符串做**完全匹配**，空格、换行、参数占位符类型（$1 vs ? vs :name）全算在内。你在代码里用 db.Query("SELECT * FROM users WHERE id = ?", id)，但 Expect 写的是 mock.ExpectQuery("SELECT * FROM users WHERE id = $1")，那就永远不命中。

• 用 mock.ExpectQuery(`SELECT \* FROM users`).WillReturnRows(...) 这种正则式写法（注意反引号和转义星号），避开具体 WHERE 条件的差异
• 或者统一你的 ORM/查询构造方式：如果底层用 github.com/lib/pq，就全用 $1；用 mysql 驱动就坚持 ?；别混用
• 开启调试模式看真实执行语句：mock.ExpectQuery("").WillReturnRows(...).RowsAre(...) 然后跑测试，从 panic 信息里抄出实际 SQL
• 注意 Go 的 fmt.Sprintf 拼接 SQL 是高危操作 —— mock 能看到拼完的字符串，但你 Expect 的可能是带变量的模板，根本对不上

RowsAre() 和 WillReturnRows() 的行为差异：为什么返回空结果却没报错

WillReturnRows() 只负责返回一个 *sqlmock.Rows，它不校验你给的数据结构是否和 Query 的 Scan 目标匹配；而 RowsAre() 是断言层，会在测试结束时检查“是否所有 Expect 都被触发 + 返回数据是否符合预期”。很多人只用 WillReturnRows() 却忘了加 mock.ExpectQuery(...).WillReturnRows(...) 的链式调用，导致 mock 认为该 Query 根本没被 expect，直接走 fallback 行为（比如返回 error 或空 rows）。

• 必须成对使用：mock.ExpectQuery(...).WillReturnRows(rows)，不能只写后者
• 构造 rows 时列名和类型要跟真实数据库一致，否则 Scan() 会 panic：sqlmock.NewRows([]string{"id", "name"}).AddRow(1, "foo")
• 如果 Query 返回多行，用 AddRow() 多次；如果想模拟无结果，用 sqlmock.NewRows(...) 后不调 AddRow() 即可
• 别依赖 WillReturnError() 来测试错误路径 —— 它不会阻止后续逻辑执行，只是让 Query() 返回 error；真正要测 error 分支，得确保你的业务代码正确处理了 err != nil

TestMain 中复用 mock 导致并发失败：t.Parallel() 下 panic

sqlmock 实例**不是并发安全的**。当你在多个并行测试中共享同一个 mock 对象（比如在 TestMain 里初始化一次），Expect 和实际执行就会乱序竞争，出现 “expected query, not executed” 或 “there is a remaining expectation which was not matched”。

• 放弃 TestMain 全局 mock，改用每个测试函数独立初始化：db, mock, err := sqlmock.New()
• 用 defer mock.ExpectationsWereMet() 放在每个测试末尾，确保该测试自己的 Expect 全部兑现
• 如果真要复用（比如初始化开销大），至少用 sync.Once + map[*testing.T]*sqlmock.Sqlmock 做 per-test 缓存，但收益极小，还容易引入 bug
• 注意 t.Parallel() 必须在 db/mock 创建之后调用，否则 setup 阶段就被并发干扰

测试里最难绷的其实是 SQL 字符串的“隐形契约”：它看起来是文本，实则是协议。空格、换行、参数风格、甚至注释位置，都可能让 mock 失效。别指望靠肉眼比对，把 mock.MatchExpectationsInOrder(false) 和日志打印打开，先看清程序到底发了什么，再决定怎么 Expect。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《Golang测试模拟数据库连接实战教程》文章吧，也可关注golang学习网公众号了解相关技术文章。