本文详解 Go 语言中 sqlmock 报错“ExpectedBegin => expecting database transaction Begin”的根本原因与解决方案，帮助开发者正确配置事务预期、避免未初始化事务或语句顺序错误导致的测试失败。
本文详解 go 语言中 sqlmock 报错“expectedbegin => expecting database transaction begin”的根本原因与解决方案，帮助开发者正确配置事务预期、避免未初始化事务或语句顺序错误导致的测试失败。
在使用 sqlmock 进行 Go 应用数据库层单元测试时，若测试中涉及事务（如 db.Begin()），而 mock 未按实际执行顺序设置对应期望，则极易触发如下错误：
Params: [call to query, was not expected, next expectation is: ExpectedBegin => expecting database transaction Begin]
该错误明确指出：sqlmock 当前期望收到 BEGIN 事务启动调用，但实际代码却直接执行了 Query / Exec 等非事务内操作。本质是期望序列（expectation order）与真实 SQL 调用顺序不匹配。
✅ 正确使用模式：显式声明事务流程
假设被测函数如下：
func CreateUserTx(db *sql.DB, name string) error {
tx, err := db.Begin()
if err != nil {
return err
}
defer tx.Rollback() // 注意：生产中需结合 commit 判断
_, err = tx.Exec("INSERT INTO users(name) VALUES(?)", name)
if err != nil {
return err
}
return tx.Commit()
}对应测试必须严格遵循「Begin → Exec → Commit/Rollback」链路设置期望：
func TestCreateUserTx(t *testing.T) {
db, mock, err := sqlmock.New()
if err != nil {
t.Fatal(err)
}
defer db.Close()
// ✅ 关键：先期望 BEGIN
mock.ExpectBegin()
// ✅ 再期望 INSERT 语句（在事务内执行）
mock.ExpectExec("INSERT INTO users\(name\) VALUES\(\?\)").
WithArgs("alice").
WillReturnResult(sqlmock.NewResult(1, 1))
// ✅ 最后期望 COMMIT
mock.ExpectCommit()
// 执行被测函数
err = CreateUserTx(db, "alice")
if err != nil {
t.Fatal(err)
}
// ✅ 验证所有期望均已满足
if err := mock.ExpectationsWereMet(); err != nil {
t.Error(err)
}
}⚠️ 常见错误与规避要点
错误 1：忘记 ExpectBegin()
若业务逻辑含 db.Begin()，测试中必须以 mock.ExpectBegin() 开头，否则后续任何操作都会因“期望未匹配”而失败。错误 2：事务内用了 db.Query() 而非 tx.Query()
db.Query() 属于非事务直连，会绕过事务上下文。务必确保所有操作均通过 *sql.Tx 对象调用（如 tx.Exec, tx.QueryRow）。-
错误 3：defer tx.Rollback() 干扰期望
即使最终调用 tx.Commit()，defer tx.Rollback() 仍可能在 panic 时触发——若未显式 ExpectRollback()，且测试未 panic，则该 defer 不执行，不影响；但若误写成 tx.Rollback() 无条件执行，则需 ExpectRollback()。建议采用如下安全模式：func CreateUserTxSafe(db *sql.DB, name string) error { tx, err := db.Begin() if err != nil { return err } // 不 defer Rollback —— 仅在出错时显式回滚 defer func() { if err != nil { tx.Rollback() } }() _, err = tx.Exec("INSERT INTO users(name) VALUES(?)", name) if err != nil { return err } return tx.Commit() } 错误 4：并发或多次事务混用同一 mock 实例
sqlmock 默认不支持并发期望。每个测试应使用独立 sqlmock.New() 实例，避免跨测试污染。
✅ 总结
sqlmock 的核心设计是基于调用顺序的确定性断言。只要确保三点，即可彻底规避 ExpectedBegin 类错误：
- 顺序一致：mock.ExpectBegin() → ExpectExec/Query → ExpectCommit|Rollback；
- 对象一致：事务内操作全部通过 *sql.Tx，而非原始 *sql.DB；
- 清理到位：每个测试后调用 mock.ExpectationsWereMet() 验证完整性。
掌握这一契约式模拟逻辑，你将能高效、可靠地为 Go 数据库逻辑编写可维护的单元测试。
