Go sqlmock SQL 中的问号和括号为什么导致预期匹配失败

如果 Go sqlmock 的预期 SQL 里出现 ?、( 或 )，测试报“无法匹配实际 SQL”，通常不是数据库驱动改写了语句，而是默认匹配器把预期文本当成了正则表达式。最小修复是对预期字符串使用 regexp.QuoteMeta；如果测试只需要比较规范化后的整条 SQL，也可以在创建 mock 时切换到 sqlmock.QueryMatcherEqual。

官方地址：https://github.com/DATA-DOG/go-sqlmock

下面只排查 SQL 文本中的正则元字符问题，不把 WithArgs 参数不一致、预期调用顺序错误或真实数据库语法错误混在一起。

先确认默认匹配器为什么会误解问号和括号

sqlmock 默认使用 QueryMatcherRegexp。它会先把 ExpectQuery 或 ExpectExec 收到的预期字符串编译成正则表达式，再拿实际 SQL 去匹配。因此，预期中的 ? 不再只是占位符字符，括号也可能被解释成分组；如果表达式本身不完整，还会在匹配前直接编译失败。

例如，业务代码实际发送的是带问号的 SQL：

package querytest

import (
    "database/sql"
    "testing"

    "github.com/DATA-DOG/go-sqlmock"
)

func loadUser(db *sql.DB, id int64) error {
    // 参数值由 database/sql 单独绑定，SQL 文本仍保留问号占位符。
    _, err := db.Exec("UPDATE users SET enabled = ? WHERE id = ?", true, id)
    return err
}

func TestLoadUser(t *testing.T) {
    db, mock, err := sqlmock.New()
    if err != nil {
        t.Fatalf("创建 mock 数据库失败: %v", err)
    }
    defer db.Close()

    // 这里的问号会先进入默认正则匹配器，而不是直接按普通字符比较。
    mock.ExpectExec("UPDATE users SET enabled = ? WHERE id = ?").
        WithArgs(true, int64(7)).
        WillReturnResult(sqlmock.NewResult(0, 1))

    if err := loadUser(db, 7); err != nil {
        t.Fatalf("执行更新失败: %v", err)
    }
    // 该检查能区分“预期未消费”和业务函数本身返回错误。
    if err := mock.ExpectationsWereMet(); err != nil {
        t.Fatalf("预期未满足: %v", err)
    }
}

排查时先看错误文本：出现正则编译错误，说明预期字符串本身没有形成合法表达式；出现“无法匹配实际 SQL”，则可能是元字符改变了语义，也可能是空白、大小写或调用的 SQL 真有差异。

保留默认匹配器时，用 QuoteMeta 把 SQL 当字面量

如果项目中已经大量使用正则预期，只想修复这一条包含问号或括号的 SQL，可以只转义预期文本。regexp.QuoteMeta 会为正则有特殊含义的字符添加转义，实际 SQL 无需改变。

package querytest

import (
    "regexp"
    "testing"

    "github.com/DATA-DOG/go-sqlmock"
)

func TestLiteralSQL(t *testing.T) {
    db, mock, err := sqlmock.New()
    if err != nil {
        t.Fatalf("创建 mock 数据库失败: %v", err)
    }
    defer db.Close()

    actualSQL := "UPDATE users SET enabled = ? WHERE id = ?"
    // QuoteMeta 只处理预期表达式，保留数据库驱动使用的问号占位符。
    expectedSQL := regexp.QuoteMeta(actualSQL)
    mock.ExpectExec(expectedSQL).
        WithArgs(true, int64(7)).
        WillReturnResult(sqlmock.NewResult(0, 1))

    // 这里替换成被测函数；参数校验仍由 WithArgs 负责。
    if _, err := db.Exec(actualSQL, true, int64(7)); err != nil {
        t.Fatalf("执行更新失败: %v", err)
    }
    if err := mock.ExpectationsWereMet(); err != nil {
        t.Fatalf("预期未满足: %v", err)
    }
}

这种写法仍然保留了 QueryMatcherRegexp 的能力：你可以只对固定片段转义，再自行留下少量确实需要的正则部分。但如果整条 SQL 只要求按文本匹配，就不要一边转义一边维护复杂表达式，直接使用等值匹配更容易读。

整条 SQL 只做文本比较时，切换 QueryMatcherEqual

sqlmock 提供 QueryMatcherOption，可以在 sqlmock.New 时选择 QueryMatcherEqual。它会在去掉空白差异后做区分大小写的整条 SQL 比较，问号和括号就只是普通字符，不再需要手动转义。

package querytest

import (
    "testing"

    "github.com/DATA-DOG/go-sqlmock"
)

func TestEqualMatcher(t *testing.T) {
    // 选择等值匹配后，预期 SQL 中的问号和括号不再被解释为正则。
    db, mock, err := sqlmock.New(sqlmock.QueryMatcherOption(sqlmock.QueryMatcherEqual))
    if err != nil {
        t.Fatalf("创建等值匹配器失败: %v", err)
    }
    defer db.Close()

    expected := "SELECT id, (name) FROM users WHERE id = ?"
    mock.ExpectQuery(expected).
        WithArgs(int64(7)).
        WillReturnRows(sqlmock.NewRows([]string{"id", "name"}).AddRow(7, "Ada"))

    rows, err := db.Query(expected, int64(7))
    if err != nil {
        t.Fatalf("查询失败: %v", err)
    }
    // 及时关闭结果集，避免把资源问题误判成 SQL 匹配问题。
    defer rows.Close()
    if err := mock.ExpectationsWereMet(); err != nil {
        t.Fatalf("预期未满足: %v", err)
    }
}

等值匹配的边界也很明确：大小写差异仍然会失败，非空白字符的拼写差异也会失败。它适合由同一处常量生成预期和实际 SQL，或测试明确要求完整文本一致的场景；如果 SQL 会由格式化器改变、只想关注关键片段，默认正则匹配反而更灵活。

用三项检查区分真正的失败原因

修复后不要只看到测试不再报错就结束，可以按下面的顺序缩小问题：

• 先看 SQL 文本：问号、括号、加号、星号等字符是否只是字面量；是的话优先 QuoteMeta 或 QueryMatcherEqual。
• 再看参数：WithArgs 校验的是绑定值，不负责修复 SQL 正则。参数类型、数量不一致时，应单独处理。
• 最后看预期消费：调用结束后执行 ExpectationsWereMet，确认预期确实被消费，而不是只绕开了某个错误分支。

选择可以压缩成一句话：只修一条正则预期就用 regexp.QuoteMeta；整套测试都按完整 SQL 文本比较就配置 QueryMatcherEqual；确实需要通配符或片段匹配时才保留正则表达式。

常见问题

问号是 database/sql 的占位符，为什么还要转义？

占位符是数据库驱动解释 SQL 时的语义；sqlmock 默认先处理“预期字符串是否匹配实际字符串”，这一步使用的是正则表达式。两个层次不同，所以问号可能在匹配层先改变含义。

用了 QueryMatcherEqual 还失败怎么办？

检查实际调用是否真的使用了同一条 SQL、大小写是否一致、非空白字符是否相同，以及 WithArgs 的参数数量和类型。不要继续修改正则，因为等值匹配已经不走正则解释。