Go Squirrel 怎样用 Expr 把表达式与绑定参数组合起来

我在把一段“固定 SQL + 可选条件”交给 Squirrel 时，最容易踩的坑不是语法，而是把表达式文本和参数值混在一起。sq.Expr(sql, args...)适合把这两部分装进一个可组合的 Sqlizer：表达式保留在 SQL 中，动态值继续留在 args 里，最后交给数据库驱动绑定。

官方地址：https://github.com/Masterminds/squirrel

记住一个判断：Expr 负责描述 SQL 片段和参数位置，不负责把参数值拼接进 SQL。先用问号写清结构，再通过 ToSql 看 SQL 与 args 是否一一对应。

我先把 Expr 看成一层参数边界

Squirrel 官方源码里，Expr 接收一个 SQL 字符串和可变参数，返回 Sqlizer。最小用法是把带条件的片段交给 Where，而不是手动拼接用户输入：

since := time.Now().Add(-24 * time.Hour)

// SQL 结构写在字符串里，时间和值仍作为绑定参数传入。
filter := sq.Expr(
    "created_at >= ? AND status = ?",
    since,
    "paid",
)

query := sq.Select("id", "amount").
    From("orders").
    Where(filter)

sqlText, args, err := query.ToSql()
if err != nil {
    // 生成阶段的错误先返回，避免把不完整 SQL 交给驱动。
    return err
}
_ = sqlText
_ = args

这里的两个问号对应两个参数，顺序就是 since、"paid"。字段名、运算符和函数名属于 SQL 结构，不能把它们当成普通参数；用户输入只能进入参数列表，不能借由 Expr 逃过边界。

嵌套 Expr 时，先看问号和 args 的对应关系

Expr 的价值在于它本身也是 Sqlizer。当参数里出现另一个 Sqlizer，Squirrel 会把内层 SQL 展开，并把内层参数按出现位置并入外层 args。下面这个例子把聚合表达式作为外层条件的一部分：

totalExpr := sq.Expr("COALESCE(SUM(?), 0)", sq.Expr("amount"))

// 外层问号对应折扣阈值，内层 Expr 只描述列表达式。
condition := sq.Expr("? >= ?", totalExpr, 1000)

sqlText, args, err := sq.Select("customer_id").
    From("orders").
    Where(condition).
    GroupBy("customer_id").
    ToSql()
if err != nil {
    // 保留原始错误，便于定位嵌套表达式的构造问题。
    return err
}
// sqlText 的结构和 args 的顺序应一起查看。
_, _ = sqlText, args

排查时不要只盯着 SQL 文本。外层第一个问号被内层 Sqlizer 占用后，内层参数会先展开；外层剩余的 1000 再按顺序进入 args。若你把一个本应是 SQL 结构的值当成普通参数，通常会看到语义不对，而不是 Go 编译错误。

ToSql 之后再转换数据库占位符

我更倾向于让表达式统一使用问号，最后由 builder 的 PlaceholderFormat 处理数据库差异。这样写表达式时只需要维护一套参数顺序：

query := sq.StatementBuilder.
    PlaceholderFormat(sq.Dollar).
    Select("id").
    From("orders").
    Where(sq.Expr("status = ? AND amount > ?", "paid", 1000))

sqlText, args, err := query.ToSql()
if err != nil {
    // 占位符转换也属于生成阶段，失败时不要继续执行。
    return err
}
// PostgreSQL 形式会使用 $1、$2，args 顺序保持不变。
_, _ = sqlText, args

这一步只改占位符表示，不改变参数语义。真正执行时仍应把 sqlText 和 args... 交给 database/sql，不要把格式化后的值重新拼成字符串。

出现错位时按运行手册排查

触发信号：SQL 看起来完整，但驱动提示参数数量不符，或条件值落到了错误位置。

快速判断：先打印或记录 ToSql 返回的 SQL 模板和参数个数；再从左到右数普通问号，单独标出嵌套 Sqlizer。不要把参数值写进日志或文章示例中的真实凭据。

处理步骤：把动态值恢复为 ? 参数；把列名、函数和运算符留在受控 SQL 片段中；嵌套表达式先单独命名；最后再应用 PlaceholderFormat。

回滚路径：如果嵌套结构让人难以判断，就拆成一个普通 Where 片段和一个独立的 Expr，先保证参数顺序清楚，再逐步组合。

告警确认：?? 用于保留字面问号，例如某些 JSON 操作符场景；它不是“跳过一个参数”的写法。每增加一个普通 ?，都要确认对应 args 是否随之增加。

复盘项：记录表达式的 SQL 结构、参数顺序、目标数据库占位符格式，以及是否存在嵌套 Sqlizer。这样下一次遇到相同症状，可以先复核边界，而不是重新改写整段查询。

相关问题

Expr 能不能替代字段名参数？不能。参数通常表示值，不表示标识符；字段名应来自受控映射，不能直接接收未信任输入。

为什么要先看 ToSql？因为它同时给出 SQL 模板和 args，最适合在执行前发现问号数量、嵌套展开和占位符格式的问题。