Go SQLX 怎样把命名参数与 IN 列表展开组合起来

我第一次把列表筛选接到 sqlx 查询里时，最容易混在一起的是三件事：结构体或 map 里的命名参数、SQL 中的 IN (?)，以及 PostgreSQL 这类驱动自己的占位符。稳定的组合顺序是：先用 sqlx.Named 把 :name 变成问号查询，再用 sqlx.In 展开切片，最后调用 db.Rebind 适配驱动。这样既能保留命名参数的可读性，也能让 IN 列表拥有数量匹配的参数。

记住一句话：Named → In → Rebind。不要直接把切片交给命名查询，也不要在 In 之前把问号改成 PostgreSQL 的 $1。

• 命名层：:tenant_id、:ids 先被解析成问号和参数列表。
• 展开层：sqlx.In 把一个切片参数展开为多个问号，并扁平化参数。
• 驱动层：Rebind 按数据库驱动把问号转换成目标占位符。

先把命名参数变成可展开的问号参数

sqlx 的命名查询适合表达业务含义，例如 :tenant_id 和 :ids 比位置参数更容易读。但对 sqlx.In 来说，输入查询必须使用问号占位符。因此先调用 sqlx.Named，拿到新的 SQL 和按出现顺序排列的参数。

下面的 map 里，ids 仍然是一个切片值。此时 Named 只负责找到名字并生成参数列表，不负责把切片拆成多个参数。

package main

import (
    "fmt"
    "log"

    "github.com/jmoiron/sqlx"
)

func namedQuery() (string, []interface{}, error) {
    // 用命名键表达筛选条件，ids 在这一阶段仍是一个整体切片。
    query := `SELECT id, name FROM users
        WHERE tenant_id = :tenant_id AND id IN (:ids)
        ORDER BY id`
    args := map[string]interface{}{
        "tenant_id": 7,
        "ids":       []int{101, 203, 305},
    }

    // Named 只把 :name 绑定成 ?，并按命名参数出现顺序返回参数。
    boundQuery, boundArgs, err := sqlx.Named(query, args)
    if err != nil {
        return "", nil, fmt.Errorf("命名参数绑定失败: %w", err)
    }
    return boundQuery, boundArgs, nil
}

func main() {
    query, args, err := namedQuery()
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(query)
    fmt.Printf("参数数量: %d\n", len(args))
}

这一步的关键不是立即执行，而是把参数表达从“名字”转换为 sqlx.In 能处理的问号形式。若这里漏掉字段名，Named 会返回绑定错误，应该保留错误而不是继续拼接。

让 IN 列表展开，再交给驱动适配

完成命名绑定后，boundArgs 中的 []int{101, 203, 305} 还是一个参数。把它和问号 SQL 一起传给 sqlx.In，它会将 IN (?) 展成 IN (?, ?, ?)，同时返回扁平化的参数列表。空切片不是“查不到结果”的快捷写法，sqlx 会返回 empty slice passed to 'in' query，调用方应提前决定是否直接返回空结果。

In 完成后，再调用 Rebind。例如 PostgreSQL 会把问号转换成 $1、$2、$3；MySQL 的问号形式则可以原样保留。顺序反过来时，In 就无法按自己的问号规则识别列表。

package main

import (
    "context"
    "fmt"

    "github.com/jmoiron/sqlx"
)

type User struct {
    ID   int    `db:"id"`
    Name string `db:"name"`
}

func findUsers(ctx context.Context, db *sqlx.DB, tenantID int, ids []int) ([]User, error) {
    // 空列表没有可绑定的 IN 值，按业务约定直接返回空结果，避免把错误带到数据库层。
    if len(ids) == 0 {
        return []User{}, nil
    }

    namedSQL := `SELECT id, name FROM users
        WHERE tenant_id = :tenant_id AND id IN (:ids)
        ORDER BY id`
    namedArgs := map[string]interface{}{
        "tenant_id": tenantID,
        "ids":       ids,
    }

    // 第一步：命名参数转为问号 SQL，ids 此时仍是一个切片参数。
    query, args, err := sqlx.Named(namedSQL, namedArgs)
    if err != nil {
        return nil, fmt.Errorf("sqlx.Named: %w", err)
    }

    // 第二步：展开 IN 列表，并得到与问号数量一致的扁平参数。
    query, args, err = sqlx.In(query, args...)
    if err != nil {
        return nil, fmt.Errorf("sqlx.In: %w", err)
    }

    // 第三步：按当前驱动转换占位符；MySQL 通常保持 ?，PostgreSQL 会使用 $n。
    query = db.Rebind(query)

    var users []User
    // SelectContext 负责查询并把列映射到 User 的 db 标签。
    if err := db.SelectContext(ctx, &users, query, args...); err != nil {
        return nil, fmt.Errorf("查询用户: %w", err)
    }
    return users, nil
}

这个函数把三层职责分开：输入层决定是否允许空列表，sqlx 层负责命名绑定和切片展开，数据库连接层负责驱动占位符。后续更换 MySQL、PostgreSQL 或其他已注册驱动时，查询主体不用重新手写占位符。

几个容易让组合失效的细节

第一，不要直接对 :ids 调用 sqlx.In；它只识别问号占位符。第二，不要把 ids 预先转成字符串拼到 SQL 中，这会让参数绑定失去边界，也容易把输入误当成 SQL 片段。第三，Named 产生的参数顺序要和返回 SQL 一起传递，不能自行重排 map。第四，空切片必须由业务层定义语义：返回空集合、跳过查询，或者改用明确的恒假条件，而不是期待数据库替你解释空的 IN 列表。

常见问题

为什么不能直接使用 NamedQuery 处理 IN 切片？

命名查询会把切片作为一个参数传递，而数据库通常需要为列表中的每个值准备一个占位符。要展开切片，应先得到问号 SQL，再调用 sqlx.In。

sqlx.In 为什么要求问号占位符？

它的展开逻辑以问号为定位点，按切片长度插入更多问号。驱动专用的 $1 或 @p1 应由最后的 Rebind 统一转换。

ids 为空时可以继续执行查询吗？

不建议直接继续。sqlx.In 对空切片返回错误，业务函数更适合在进入绑定流程前决定是否返回空结果或采用另一条明确的查询分支。

换成 PostgreSQL 后代码要改哪里？

保留 Named → In 的顺序，使用当前 *sqlx.DB 的 Rebind 处理最终查询即可。连接使用的驱动名称和数据库配置仍应按项目实际情况设置。

对我来说，这个组合最值得保留的不是某一段固定 SQL，而是清晰的参数生命周期：命名参数负责可读性，In 负责列表形状，Rebind 负责驱动差异。三步分开后，查询函数更容易迁移、排错和复用。