Go Squirrel Eq 的空切片为什么不能按普通等号理解

Squirrel 的 Eq 不是把每个值都机械拼成 字段 = ?。当值是非空切片时，它会生成 IN；当值是空切片时，则生成恒假条件 1=0（NotEq 对应恒真条件 1=1）。所以，空切片表达的是“这个集合没有任何可匹配值”，不是“把切片本身拿去做一次普通等号比较”。

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

这个区别很重要：如果业务希望空筛选列表代表“不要加这个过滤条件”，就应该在调用 Eq 前跳过条件；如果业务希望空列表代表“明确查不到任何记录”，保留空切片才是合适的写法。

先把普通值、非空切片和空切片分开

Eq 的输入类型是 map[string]interface{}。Squirrel 会根据值的动态类型选择 SQL 形态，而不是只看键名。下面的示例只展示预期的 SQL 结构，代码可复制到读者自己的项目中验证。

package main

import (
	"fmt"

	sq "github.com/Masterminds/squirrel"
)

func main() {
	// 普通值使用等号，并把值放进参数列表。
	show("普通值", sq.Eq{"status": "ready"})

	// 非空切片转换成 IN，每个元素对应一个占位符。
	show("非空切片", sq.Eq{"id": []int64{7, 9}})

	// 空切片不生成 IN ()，而是生成恒假条件。
	show("空切片", sq.Eq{"id": []int64{}})
}

func show(label string, predicate sq.Sqlizer) {
	// ToSql 只负责构造 SQL 和参数，不会连接数据库。
	sqlText, args, err := predicate.ToSql()
	if err != nil {
		fmt.Printf("%s: 构造失败: %v\n", label, err)
		return
	}
	fmt.Printf("%s: %s; args=%v\n", label, sqlText, args)
}

对应关系可以概括为：普通字符串得到 status = ?；非空切片得到 id IN (?,?)；空切片得到 1=0 且没有参数。它不会把空切片作为一个数组参数交给数据库，也不会生成许多数据库不接受的 IN ()。

为什么空切片会变成 1=0

在 Squirrel 的 Eq 实现里，值被识别为数组或切片后会继续查看长度。长度大于零时，代码为每个元素追加参数并拼出 IN；长度为零时，使用内部的恒假 SQL 表达式。这个分支既保留了 SQL 的合法性，也让“集合为空”保持了集合筛选的自然逻辑：没有元素能满足“属于这个集合”。

因此，空切片和 nil 也不能混为一谈。未类型化的 nil 表示空值，通常对应 字段 IS NULL；而一个长度为零的切片仍然是切片，表达的是空集合。尤其要留意 var ids []int64 = nil：它的动态类型仍是切片，长度为零，不能按 SQL NULL 过滤来理解。

// 该函数只演示输入契约，不执行真实查询。
func predicate(ids []int64, useNull bool) sq.Eq {
	if useNull {
		// nil 是 SQL NULL 语义，适合表达“字段没有值”。
		return sq.Eq{"owner_id": nil}
	}
	// nil 切片的长度仍为 0；在 Eq 中它属于空集合语义。
	return sq.Eq{"id": ids}
}

另一个容易误判的边界是 []byte。Squirrel 需要兼容 database/sql 对字节切片参数的特殊处理，因此不能仅凭“它是切片”就把所有 []byte 当成 IN 列表。不要把字符串数组、整数切片和二进制参数混成同一种输入契约。

放进 Where、Or 和 NotEq 后，逻辑结果会变化吗

空切片本身的结果是恒假，但组合器会决定它对整条条件的影响。直接作为 Where 条件时，查询会保留 WHERE 1=0，结果是没有记录；它不会悄悄删除整个 WHERE。

// 查询构造只表达逻辑关系；数据库执行仍由调用方负责。
func byIDs(ids []int64) sq.SelectBuilder {
	return sq.Select("id", "name").
		From("users").
		Where(sq.Eq{"id": ids})
}

func byIDsOrVisible(ids []int64) sq.SelectBuilder {
	// 空 ids 会成为 1=0；在 OR 中它不等于“忽略这一支”。
	return sq.Select("id", "name").
		From("users").
		Where(sq.Or{
			sq.Eq{"id": ids},
			sq.Eq{"visible": true},
		})
}

在 1=0 OR visible = ? 中，恒假分支不会影响另一支；在 1=0 AND tenant_id = ? 中，整条条件仍然恒假。NotEq 使用相反逻辑：空切片对应 1=1，因为“不是空集合中的任意元素”对所有值都成立。但这不代表应该把空集合当作无限制条件，它只说明了 NOT IN 的空集合语义。

先决定业务语义，再决定是否传空切片

实际排查时最常见的错误不是 Squirrel 生成错了，而是调用方没有定义空列表的业务含义。可以在构造条件前明确写出策略：

// buildUsersQuery 用 allowEmpty 表达空筛选集合的业务约定。
func buildUsersQuery(ids []int64, allowEmpty bool) (sq.SelectBuilder, error) {
	query := sq.Select("id", "name").From("users")
	if len(ids) == 0 {
		if allowEmpty {
			// 空列表表示“不筛选”，因此不追加 Eq。
			return query, nil
		}
		// 空列表表示“没有合法目标”，显式返回无结果查询。
		return query.Where(sq.Expr("1=0")), nil
	}
	// 非空时才交给 Eq 生成 IN (?, ...)。
	return query.Where(sq.Eq{"id": ids}), nil
}

如果统一使用 Eq，也可以让“空集合即无结果”自然落到 WHERE 1=0，但要在接口文档和测试中写清楚。不要为了让 SQL 看起来像“没有条件”而把恒假条件从组合树中删除，那会把权限范围、租户过滤或数据导出边界改变成另一种查询。

排查 Eq 空切片的最小清单

遇到“传了 ID 列表却查不到数据”时，按下面顺序看，通常比先改占位符或清理缓存更快：

• 确认动态类型确实是整数、字符串等列表，而不是把 JSON 文本或逗号字符串当成切片传入。
• 打印或记录 len(ids)，区分空切片、非空切片和未传值；不要只看变量名。
• 查看 ToSql() 生成的是 IN 还是 1=0，并同时查看参数数量。
• 检查它位于 AND 还是 OR，确认组合逻辑是否符合权限、租户和可见性约束。
• 为“空集合无结果”和“空集合跳过过滤”分别写测试，避免用一个布尔开关隐含两种语义。

最后记住：Squirrel 的 Eq 是 SQL 条件构造器，空切片是它对空集合的明确编码，不是 Go 等号比较，也不是数据库 NULL。先决定空集合要代表“无结果”还是“不筛选”，再决定是否把它传给 Eq，问题就不会被误归因于占位符或数据库驱动。

源码参考：https://github.com/Masterminds/squirrel/blob/master/expr.go