Redis BITFIELD 怎样在字符串中读写小整数

当一个 Redis String 里需要同时保存状态位、小计数器和短范围数值时，BITFIELD 比手工拆字节更直接：用 i 或 u 指定有符号/无符号和位宽，用偏移定位字段，再用 GET、SET、INCRBY 完成读写。官方地址：https://redis.io/docs/latest/commands/bitfield/

BITFIELD 的关键不是“把数字变成二进制”这么简单，而是先固定每个字段的位宽和偏移，再明确溢出时是回绕、饱和还是失败。只要这三个约定不变，一个 String 就能稳定承载多个小整数。

• 字段类型：u4 表示 4 位无符号整数，i8 表示 8 位有符号整数。
• 字段位置：普通偏移是从 0 开始的 bit offset，带 # 的偏移会按当前位宽换算。
• 结果判断：一个 BITFIELD 命令可以串联多个操作，返回数组顺序与操作顺序一致。

先看懂 BITFIELD 的编码和偏移

BITFIELD 把 String 当作连续的 bit 数组。编码前缀 u 表示无符号，i 表示有符号，后面的数字就是位宽，例如 u4 的范围是 0 到 15，i8 的范围是 -128 到 127。官方文档支持的有符号编码最高为 64 位，无符号编码最高为 63 位。

偏移直接写数字时，它就是零基 bit offset；如果写成 #0、#1，Redis 会把编号乘以当前编码的位宽，适合排列一组等宽字段。等宽数组优先使用 #，字段宽度不同或需要跨字段精确定位时，再使用普通 bit offset。

用三种子命令完成最小读写

GET 只读取指定字段，SET 写入并返回旧值，INCRBY 则按字段的编码做增减并返回新值。下面把一个 4 位状态计数器放在编号 0，再读取它；命令块中的注释只说明参数意图，不改变 Redis 命令语法。

# 读取编号为 0 的 4 位无符号字段；#0 会按 u4 的宽度换算位置
BITFIELD user:flags GET u4 #0

# 写入字段并返回旧值；新值 9 需要落在 u4 的范围内
BITFIELD user:flags SET u4 #0 9

# 原子增加 1，并返回增加后的字段值
BITFIELD user:flags INCRBY u4 #0 1

一个调用可以继续追加操作，返回值会按出现顺序组成数组。例如先递增一个位于 100 的有符号 5 位字段，再读取 offset 0 的无符号 4 位字段，第二个返回值不会因为第一个操作而被改写。这个顺序很适合把“更新计数器”和“读取状态”放进同一次请求里。

溢出策略决定结果是否回绕

INCRBY 和 SET 的结果是否越界，由它们前面的 OVERFLOW 决定。默认是 WRAP：无符号整数按范围回绕，有符号整数从最大值越过后回到最小值。SAT 会把结果卡在最小值或最大值；FAIL 检测到越界时不执行该操作，并在对应返回位置给出 NULL。

# 让后面的增加在越界时保持 i8 最大值，而不是回绕到负数
BITFIELD metrics INCRBY i8 #0 120 OVERFLOW SAT INCRBY i8 #0 10

# 用 FAIL 让调用方从 NULL 发现越界；失败操作不会写入新值
BITFIELD metrics OVERFLOW FAIL INCRBY u4 #1 20

注意 OVERFLOW 只影响它后面的 SET 和 INCRBY，直到下一次 OVERFLOW 出现。生产代码不要只判断命令是否返回数组，还要按操作顺序检查某个位置是否为 NULL；否则 FAIL 策略的保护会被误当成普通的空结果。

常见问题

BITFIELD 适合保存什么数据？

适合范围明确、位宽较小且需要高密度存储的状态值或计数器。字段协议需要由应用双方共同维护，频繁改变位宽会让旧数据解释变得困难。

GET 读取不存在的字段会报错吗？

不会。读取超出当前 String 长度的区域时，Redis 会按缺失部分全为 0 来解释；而 SET 或 INCRBY 写到更远位置时，会按需要扩展 String 并补零。

为什么 u64 不作为常规编码使用？

官方文档说明无符号编码最高支持 63 位，这是因为 Redis 协议当前不能把 64 位无符号整数作为回复返回。需要完整 64 位范围时，应重新设计字段或结果表达。

什么时候应该选择 FAIL？

当越界意味着业务数据不能继续累加时选择 FAIL，并把 NULL 当成明确的业务分支；如果自然需要封顶，选择 SAT；只有计数器允许模运算时才使用默认的 WRAP。