Pipeline 单条错误怎么配置或排查

Redis Pipeline 报错时，最容易误判的是把整批返回的一个 error 当成“所有命令都失败”。正确做法是保留提交顺序，在 Exec 后逐个检查命令对象的 Err()：它能告诉你哪一条返回了 WRONGTYPE、参数错误或其他 Redis 错误。普通 Pipeline 只解决往返次数，不提供回滚；确实要求全有或全无时，再考虑 TxPipeline。

官方地址：https://redis.io/docs/latest/develop/using-commands/pipelining/

一、先分清批次错误和单条回复错误

Pipeline 把多条请求集中发送，Redis 仍按收到的顺序处理，并按相同顺序返回结果。因此，第三条命令返回错误，不代表第一、第二条没有成功。go-redis 的 Exec 会返回命令列表和一个批次级错误；这个错误适合做“批次是否需要关注”的信号，不能替代逐条检查。

二、用命令下标定位失败项

排查时给每个命令配一个业务标签，并让标签与加入 Pipeline 的顺序保持一致。下面的示例故意先把字符串写入 profile:1，再用列表命令操作它，模拟常见的 WRONGTYPE；最后的 GET 仍然可以返回结果。

ctx := context.Background()
pipe := rdb.Pipeline()

// 标签与入队顺序一一对应，方便把返回的下标映射回业务动作。
labels := []string{"写入 profile:1", "追加 profile:1", "读取 profile:1"}
pipe.Set(ctx, "profile:1", "ready", 0)
pipe.LPush(ctx, "profile:1", "item") // 字符串键不能执行列表命令。
pipe.Get(ctx, "profile:1")

cmds, batchErr := pipe.Exec(ctx)
if batchErr != nil {
	// 批次级错误只说明至少有一项需要关注，不要直接判定全批失败。
	log.Printf("pipeline batch error: %v", batchErr)
}
for i, cmd := range cmds {
	if err := cmd.Err(); err != nil {
		// 输出下标、标签和 Redis 错误，避免只留一条无上下文的日志。
		log.Printf("pipeline index=%d label=%s error=%v", i, labels[i], err)
	}
}

真实项目中还应把批次 ID、命令名和脱敏后的键模式写入结构化日志，不要记录用户值、密码或完整 Token。若客户端在错误时只返回一个总错误，就查看它是否仍暴露了命令列表，或改用能保留逐条命令结果的接口。

三、按错误类型配置重试和修复策略

错误处理可以按“能否通过再次发送同一条命令解决”来分层。WRONGTYPE、错误参数、未知命令通常暴露了代码或数据模型问题，重试只会重复制造日志；先用 TYPE profile:1 或数据迁移记录确认键的实际类型，再修正生产写入路径。

超时、连接断开和连接池耗尽才适合进入有限重试，但要记录这次批次是否已经有部分回复。INCR、LPUSH 等非幂等写入不能因为客户端不知道服务端是否执行过，就无条件整批重放。批量太大时还应拆成合理大小：官方文档提醒，服务端会暂存尚未读取的回复，批次越大，客户端和 Redis 的缓冲压力越高。

建议至少保留四个指标：批次命令数、失败命令数、错误前缀分布、批次耗时。以“100 条命令中 1 条 WRONGTYPE”为例，失败率应是 1%，而不是把整批粗略记成 100% 失败；这会直接影响告警阈值和重试决策。

四、需要全有或全无时改用 TxPipeline

如果业务要求“缓存哈希和过期时间必须一起更新”，普通 Pipeline 不够，因为其他客户端可能在中间状态读取到数据。go-redis 的 TxPipeline 会用 Redis 的 MULTI/EXEC 包住命令，使这组命令以事务方式执行。

但事务也不是“遇到任意单条错误就自动回滚”。Redis 文档说明，执行阶段的错误会作为数组中的某个回复返回，其他命令仍可能完成；只有业务明确需要的原子边界，才值得承担事务语义和排查成本。若 WATCH 导致 EXEC 返回空结果，那是乐观锁条件未满足，应重新读取并按业务策略重试。

最终选择可以很简单：只想减少 RTT，使用 Pipeline；想隔离并保证一组命令连续执行，使用 TxPipeline；想定位问题，无论哪种方式都保存顺序、标签和逐条错误。

相关问题

Pipeline 的一条命令失败会停止后面的命令吗？

普通 Pipeline 不会因为某条回复是错误就自动停止，后续命令仍可能执行，所以写入前要设计幂等性和批次边界。

为什么 GET 返回 redis.Nil 还要单独判断？

redis.Nil 表示键不存在，是缓存未命中的业务结果；它和网络断开、Redis 命令错误不是同一类故障。

只记录 Exec 的 error 可以吗？

不建议。它能提示批次存在错误，但只有遍历命令并读取 Cmd.Err()，才能把失败定位到具体下标和业务标签。