Redis BITFIELD 溢出策略 WRAP SAT FAIL 怎么选

Redis BITFIELD 的三种溢出策略可以直接按业务语义选择：计数到边界后允许从另一端继续，就用 WRAP；只能停在最大值或最小值，就用 SAT；越界必须保持原值并交给业务层处理，就用 FAIL。如果没有显式写 OVERFLOW，默认策略是 WRAP。

官方命令文档：https://redis.io/docs/latest/commands/bitfield/

BITFIELD 把 Redis 字符串看成连续比特，并用 iN 或 uN 读写指定宽度的整数。溢出策略不是“性能档位”，而是数据越过位宽边界时的业务规则。选错后，命令仍可能成功执行，但数值含义已经不符合业务预期。

先按业务负载做选择

选择时先问一个问题：越界是合法状态、可接受的截断，还是必须暴露给调用方的异常？这比先看命令写法更可靠。WRAP 适合“循环”，SAT 适合“封顶”，FAIL 适合“拒绝”。

位宽先决定可表示范围

iN 表示有符号整数，uN 表示无符号整数。官方文档说明，BITFIELD 支持最多 64 位的有符号整数和最多 63 位的无符号整数。比如 i8 的范围是 -128 到 127，u8 的范围是 0 到 255。只有当 SET 或 INCRBY 的结果越过这个范围，溢出策略才会产生差异。

# 把 key 中从偏移 0 开始的 8 位解释为有符号整数，并写入 127
redis-cli BITFIELD demo:counter SET i8 0 127

# 读取同一位字段，确认当前值仍处于 i8 的上边界
redis-cli BITFIELD demo:counter GET i8 0

位宽越小，越容易触发边界。将业务上可能持续增长的累计量塞进很窄的字段之前，应先估算生命周期内的最大值；否则即使策略选对，也可能只是把数据建模问题隐藏起来。

三种策略放在一起看

下面都从 i8=127 开始再加 1。为了让每种策略互不干扰，示例使用三个不同的 key。

# WRAP：i8 的 127 再加 1，会回绕到 -128
redis-cli BITFIELD demo:wrap SET i8 0 127 OVERFLOW WRAP INCRBY i8 0 1

# SAT：达到上边界后保持 127，不再继续增大
redis-cli BITFIELD demo:sat SET i8 0 127 OVERFLOW SAT INCRBY i8 0 1

# FAIL：越界的 INCRBY 不写入，返回数组中的对应位置为空
redis-cli BITFIELD demo:fail SET i8 0 127 OVERFLOW FAIL INCRBY i8 0 1

# 再次读取，确认 FAIL 场景下原值仍是 127
redis-cli BITFIELD demo:fail GET i8 0

SET 返回写入前的旧值，INCRBY 返回更新后的值，因此一条包含多个子操作的 BITFIELD 命令会返回一个结果数组。判断 FAIL 时，不要只观察整个命令是否有响应，而要检查对应子操作位置是不是 nil/Null。

推荐方案取决于数据语义

循环编号选择 WRAP

如果数值本来就是有限状态环，例如 0、1、2、3 后回到 0，WRAP 能直接表达这种语义。无符号字段回绕可理解为在该位宽容量上取模；有符号字段上溢会回到最小负值，下溢会回到最大正值。普通访问次数、订单数量和余额通常不应使用这种策略，因为回绕会让累计含义失真。

展示上限选择 SAT

如果产品只关心“最多显示到某个等级”，SAT 更直观。它使用饱和算术：上溢停在最大值，下溢停在最小值。SAT 不会告诉你真实值已经超出多少，所以需要审计精确累计量时，应把完整值放在更宽字段或其他数据结构中。

强约束选择 FAIL

额度、库存和不可跨越的状态边界更适合 FAIL。它在检测到上溢或下溢时不执行对应操作，并在对应返回位置给出 nil/Null，让客户端明确进入拒绝、重试或补偿分支。FAIL 只是位宽边界控制，不会代替余额校验、库存预占或权限判断等完整业务规则。

OVERFLOW 的作用域别理解错

OVERFLOW 不是某个 key 的永久配置。它只影响同一条 BITFIELD 命令中位于它后面的 SET 和 INCRBY，直到遇到下一个 OVERFLOW。GET 只是读取，不需要溢出策略。下一条 BITFIELD 命令若没有再次指定，会回到默认 WRAP。

# 第一个 INCRBY 使用 SAT；下一个 OVERFLOW 把后续 INCRBY 切换为 FAIL
redis-cli BITFIELD demo:mixed \
  SET i8 0 120 \
  OVERFLOW SAT INCRBY i8 0 10 \
  OVERFLOW FAIL INCRBY i8 0 1 \
  GET i8 0

# 不要假设上一条命令的 FAIL 会保留；这里未声明时仍采用默认 WRAP
redis-cli BITFIELD demo:mixed INCRBY i8 0 1

混合多个策略可以减少往返，但也会提高阅读成本。生产代码若确实需要这样做，建议让每段 OVERFLOW 紧挨它控制的子操作，并在客户端按固定下标解析结果。

客户端必须区分空返回和数字 0

FAIL 的关键不是抛出普通命令错误，而是对应数组元素为空。数字 0 可能是完全合法的更新结果，nil/Null 才表示该子操作因溢出或下溢未执行。客户端封装应返回“值 + 是否成功”或显式错误，不要把空值自动转成 0。

# redis-py 返回列表；None 表示 FAIL 策略拒绝了对应子操作
result = redis_client.execute_command(
    "BITFIELD", "quota:user:42",
    "OVERFLOW", "FAIL",
    "INCRBY", "u8", 0, 1,
)

# 必须检查数组位置的 None，不能用 result[0] or 0 吞掉拒绝信号
if result[0] is None:
    raise ValueError("位字段已到上限，本次增量未写入")

new_value = result[0]  # 合法的 0 也会被原样保留

如果一条命令包含多个写子操作，FAIL 只表示发生溢出的对应子操作没有执行，不能把它当成整条命令的事务回滚信号。需要全有或全无的复杂业务约束时，应重新设计字段布局，或使用能完整表达条件判断与原子更新的服务端逻辑。

上线前用这份清单收尾

• 先定范围：根据生命周期最大值选择 iN 或 uN，不要只追求节省几个比特。
• 再定语义：循环用 WRAP，封顶用 SAT，必须拒绝越界用 FAIL。
• 显式声明：即使准备使用默认 WRAP，关键业务代码也可显式写出，减少维护者猜测。
• 检查返回：按子操作位置解析数组，严格区分 nil/Null 与数字 0。
• 监控边界：SAT 长期停在极值、FAIL 频繁返回空值，都应成为容量或模型调整信号。
• 控制复杂度：一条命令混用多种策略时，让策略与受控操作紧邻，并固定返回数组的解析契约。

常见问题

不写 OVERFLOW 时是哪一种？

默认使用 WRAP。对不允许回绕的累计量，最好显式选择 SAT 或 FAIL。

OVERFLOW 会影响 GET 吗？

不会。它控制后续 SET 和 INCRBY 的越界处理，GET 只按指定编码和偏移读取数值。

FAIL 会删除或清空原来的值吗？

不会。发生溢出或下溢时，对应操作不执行，返回位置为 nil/Null，原位字段保持原值。

SAT 适合精确累计吗？

如果达到边界后仍需要知道真实累计量，就不适合只靠 SAT。SAT 更适合“达到上限即可”的展示或状态语义。

最终可以把选择压缩成一句话：WRAP 接受回绕，SAT 接受丢失超出边界的增量，FAIL 要求调用方正面处理越界。先确定业务能接受哪种结果，再决定命令中的策略。