BITFIELD 溢出策略怎么配置或排查

Redis 的 BITFIELD 溢出策略不是全局配置，而是写在一条命令里的局部规则。默认使用 WRAP；需要“到上限就停”时用 SAT，需要把溢出当成失败并阻止写入时用 FAIL。排查时先核对 iN/uN 的位宽，再看 OVERFLOW 放在了哪个 SET 或 INCRBY 前面。

先把 BITFIELD 的合法范围算清楚

uN 是无符号整数，范围为 0 到 2^N-1；iN 是有符号整数，范围为 -2^(N-1) 到 2^(N-1)-1。例如 u3 最大只能保存 7，i8 最大为 127。很多“策略没生效”的问题，其实是把 u3 当成了普通整数，或者把 #1 误当成了第 1 个 bit。

不带井号的 offset 是绝对 bit 偏移；带 # 时，Redis 会用当前 encoding 的宽度相乘。因此 SET u3 #1 6 指向第二个 3-bit 槽位，而不是偏移 1 bit。先固定 encoding 和 offset，再讨论溢出，排查才不会把两个问题混在一起。

WRAP、SAT、FAIL 分别解决什么问题

三种策略的差别只在越过位宽上下限时显现。以 u3 当前值 7 再加 1 为例：

可以用一条命令表达“先按默认规则写，再对下一次写入启用饱和”：

redis-cli
# 第一项使用默认 WRAP；第二项遇到上限时保持在 7
BITFIELD score:demo INCRBY u3 #0 1 OVERFLOW SAT INCRBY u3 #0 1

返回值数组按子命令顺序排列。若改用 FAIL，对应位置会出现 nil；不要只看客户端打印的整行结果，要把每个返回值和它前面的操作一一对齐。

OVERFLOW 的作用范围是排查关键

OVERFLOW 是命令序列中的状态切换，不是 key 的持久化属性。它只影响后面的 SET 与 INCRBY，直到遇到下一条 OVERFLOW。这意味着同一条命令可以让不同字段采用不同策略，但下一条独立的 BITFIELD 命令仍会回到默认 WRAP，除非再次写出策略。

redis-cli
# 先把槽位设为 7；再用 FAIL 检查是否允许继续增加
BITFIELD score:demo SET u3 #0 7 OVERFLOW FAIL INCRBY u3 #0 1

这里最后一次 INCRBY 越界时，返回 nil，位字段不会被改成 0。若你看到返回 nil 但回读仍是旧值，这通常正是 FAIL 的正确表现，不是 Redis 丢写。

一张清单定位“策略不生效”

1. 核对 encoding：确认是 iN 还是 uN，并算出上下限。
2. 核对 offset：确认裸数字和 #N 是否被混用，尤其是多槽位字段。
3. 核对顺序：确认 OVERFLOW 出现在目标 SET/INCRBY 之前，而不是之后。
4. 核对返回值：多操作返回数组中，nil 只对应某个越界子命令。
5. 用 GET 回读：GET 不改变数据，也不需要依赖前面的溢出策略。

生产上，环形序号可以接受 WRAP；余额、配额、库存这类不可越界的数值更适合 SAT 或 FAIL。如果业务需要知道“本次没有增加”，优先用 FAIL 并在客户端把 nil 转成明确的业务分支；如果只需要保证不超过上限，SAT 更省处理代码。

常见问题

BITFIELD 的默认溢出策略是什么？

默认是 WRAP。不要把一次命令里的 OVERFLOW SAT 理解成 key 级别的永久设置。

FAIL 溢出后会把字段清零吗？

不会。越界的 SET 或 INCRBY 不执行，对应结果返回 nil，原值保持不变。

GET 也会受到 OVERFLOW 影响吗？

不会。GET 只按指定 encoding 解释位字段；排查时可用它确认写入是否真的发生。

Redis 官方命令文档明确列出 WRAP、SAT 和 FAIL 的语义。实际接入时，把位宽范围、策略选择和 nil 分支写进回归用例，BITFIELD 的边界行为就不会只靠口头约定。