Go Squirrel 复用查询构造器时为什么需要接收链式返回值

用 Squirrel 写可复用查询时，最容易忽略的一点是：SelectBuilder 的链式方法不会把原变量原地改掉。Where、From、OrderBy 等方法都会返回一个新的 builder，所以需要把返回值重新赋给变量，或者直接继续链式调用。

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

如果一个查询要作为多个分支的基础模板，请把每次追加条件后的返回值保存成新的查询变量；只调用方法而丢弃返回值，原来的查询不会得到这次条件。

先看一个“条件没有生效”的例子

下面的代码看起来像是给基础查询加了状态条件，但 Where 的返回值没有被接住：

package main

import (
    "fmt"

    sq "github.com/Masterminds/squirrel"
)

func main() {
    // 先建立所有分支都会使用的查询骨架。
    base := sq.Select("id", "name").From("users")

    // Where 返回新的 SelectBuilder；丢掉返回值不会修改 base。
    base.Where("status = ?", "active")

    sqlText, args, err := base.ToSql()
    if err != nil {
        // 生成 SQL 失败时立即处理，避免把不完整查询交给数据库。
        panic(err)
    }
    fmt.Println(sqlText, args)
}

这里真正交给 ToSql 的仍是只有 id、name 和 users 的基础查询。正确写法是：

// 接住返回值，activeQuery 才包含状态条件。
activeQuery := base.Where("status = ?", "active")

sqlText, args, err := activeQuery.ToSql()
if err != nil {
    // 保留错误返回，调用方可以记录或转换成业务错误。
    return err
}
_ = sqlText
_ = args

为什么 Squirrel 要返回新的 builder

Squirrel 的 SelectBuilder 是一个 builder 类型，源码中的格式、连接、列、条件和输出方法都以值接收者形式返回 SelectBuilder。例如 Where 最终调用底层 builder 的追加操作，再把结果转换回新的 SelectBuilder。

底层 lann/builder 文档把 builder 定义为不可变对象：Set、Append 等函数返回给定 builder 的副本。这样做的价值在于，一份基础查询可以安全地派生出多个不同条件，分支之间不会因为后续追加条件而互相污染。

这也是链式写法能成立的原因：

// 每个方法都把新的 builder 交给下一个方法，最后由 ToSql 读取。
query := sq.Select("id", "name").
    From("users").
    Where("status = ?", "active").
    OrderBy("created_at DESC").
    Limit(20)

sqlText, args, err := query.ToSql()
if err != nil {
    // ToSql 负责把构造结果转换成 SQL 和绑定参数。
    return err
}
_ = sqlText
_ = args

复用查询模板时怎样拆分变量

我在需要同时支持“只看启用用户”和“按创建时间取最近一页”的场景里，会保留一个不带分支条件的 base，再分别保存派生值。这样每个分支的意图清楚，后续新增条件也不会误加到另一个分支。

// base 只保存共同的查询骨架，作为可复用起点。
base := sq.Select("id", "name", "created_at").From("users")

// 接住 Where 的返回值，形成独立的状态分支。
activeQuery := base.Where(sq.Eq{"status": "active"})

// 接住 OrderBy 和 Limit 的返回值，形成独立的分页分支。
recentQuery := base.OrderBy("created_at DESC").Limit(20)

activeSQL, activeArgs, err := activeQuery.ToSql()
if err != nil {
    // 第一个分支失败时不要继续执行第二个分支。
    return err
}
recentSQL, recentArgs, err := recentQuery.ToSql()
if err != nil {
    // 第二个分支单独处理自己的构造错误。
    return err
}
_, _, _, _ = activeSQL, activeArgs, recentSQL, recentArgs

几个容易误判的边界

• 空条件：如果条件可能为空，先在 Go 代码中判断，再决定是否接收 Where 返回值；不要把“没有调用”误认为“调用后会原地修改”。
• 分支共享：可以共享 base，但不要把某个已经带有业务条件的派生查询继续当成所有分支的公共模板。
• 参数绑定：把值作为占位符参数传给 Where，让 Squirrel 同时生成 SQL 和参数列表；不要为了检查链式返回值而拼接用户输入。
• 最终检查：在执行前调用 ToSql 并处理错误，重点看生成的条件是否落在预期的那个分支上。

相关问题

为什么不能直接修改 base？因为 Squirrel 采用不可变 builder 语义，修改方法通过返回新值表达结果。

链式写法和拆变量写法有区别吗？语义一致，拆变量更适合复用基础查询和管理多个分支。

ToSql 会执行数据库查询吗？不会，它只把构造器转换成 SQL 字符串、参数和错误；执行需要配合数据库 runner 或标准库调用。