不能直接封装“批量Set”函数，因其隐去返回值、错误检查和执行时机控制，且内部调用Exec()导致调用方无法感知命令是否发出；正确封装应只构造pipeline并返回Cmd实例，由业务层显式调用Exec()并逐个检查错误。
为什么不能直接封装成“批量Set”函数
很多人想写一个 BatchSet(ctx, map[string]interface{}) 一把塞进 pipeline，看似干净，实则埋雷：它隐去了命令返回值、错误检查入口和执行时机控制。最致命的是——Exec() 被藏在函数内部，调用方完全感知不到是否真的发出去了；一旦漏掉或重复调用，就是静默失败或 panic。
封装必须暴露 pipe.Exec() 和 cmd 结果检查点
真正可维护的封装，不是消灭复杂性，而是把关键控制权交还给调用方。核心原则就三条：
- 封装函数只负责「构造 pipeline 并排队命令」，不调
Exec() - 必须返回
*redis.Pipeline和所有*redis.Cmd实例（如[]*redis.StatusCmd） - 调用方自己决定何时
pipe.Exec(ctx)，并自行遍历检查每个cmd.Err()
示例（批量 Set 字符串）：
func BuildBatchSet(pipe *redis.Pipeline, kv map[string]interface{}, expiration time.Duration) []*redis.StatusCmd {
cmds := make([]*redis.StatusCmd, 0, len(kv))
for k, v := range kv {
cmd := pipe.Set(context.TODO(), k, v, expiration)
cmds = append(cmds, cmd)
}
return cmds
}
// 使用：
pipe := client.Pipeline()
cmds := BuildBatchSet(pipe, data, time.Hour)
_, err := pipe.Exec(ctx) // ← 这步必须由业务层显式写
if err != nil {
// 处理网络级错误
}
for i, cmd := range cmds {
if cmd.Err() != nil {
// 处理第 i 条命令的具体错误，比如 key 类型冲突
}
}
带错误聚合的封装要谨慎使用
有些封装试图在函数内完成 Exec() 并返回所有错误列表，比如 BatchSetWithErrs(ctx, ...)。这看似省事，但会带来三个实际问题：
立即学习“go语言免费学习笔记（深入）”；
- ctx 超时被绑定到整批，无法按子命令差异化设超时
- 无法在
Exec()前插入其他逻辑（如 DB 查询、HTTP 调用），导致 pipeline 的 RTT 优势被抵消 - 错误聚合后丢失上下文——你只知道“第7条错了”，但不知道它对应的是哪个 key，除非额外传入 key 切片并做索引映射，代码陡增
真要聚合，推荐用结构体封装结果：
type BatchSetResult struct {
Key string
Value interface{}
Err error
}
func ExecBatchSet(ctx context.Context, client *redis.Client, kv map[string]interface{}, exp time.Duration) []BatchSetResult {
pipe := client.Pipeline()
cmds := make(map[string]*redis.StatusCmd)
var keys []string
for k, v := range kv {
cmds[k] = pipe.Set(ctx, k, v, exp)
keys = append(keys, k)
}
_, _ = pipe.Exec(ctx) // 注意：此处仍需处理网络错误，简化示例略
results := make([]BatchSetResult, 0, len(keys))
for _, k := range keys {
results = append(results, BatchSetResult{
Key: k,
Value: kv[k],
Err: cmds[k].Err(),
})
}
return results
}
集群环境下封装必须先分 slot 再建 pipe
在 redis.ClusterClient 上直接调 client.Pipeline() 会 panic。正确路径是：先算 slot → 找节点 → 在该节点的 *redis.Client 上建 pipe。封装时不能假设单机，必须接受 clusterClient 或 client 两种输入，并做运行时判断：
- 如果是
*redis.ClusterClient，用clusterClient.KeySlot(key)和clusterClient.NodeForKey(slot)获取目标节点 - 如果是
*redis.Client，直接用它建 pipe - 别试图在封装里自动拆分跨 slot 的 key 列表——这属于业务逻辑，应由调用方按前缀/业务域预分组
最容易被忽略的一点：封装函数返回的 *redis.Pipeline 对象，其生命周期绑定于底层 *redis.Client。如果封装里偷偷 new 了一个临时 client，那这个 pipe 就成了孤儿，Exec() 时会 panic 或连接复用失败。
