Redis BITFIELD 怎样更新多个位字段

如果一个 Redis 字符串里要紧凑地保存多个小整数，BITFIELD 比把每个数字拆成独立键更适合做位级布局。它允许一次命令串联多个 GET、SET、INCRBY，并按子命令顺序返回结果。真正容易出错的地方不是命令长度，而是位宽、偏移和溢出策略没有一起设计。

官方地址：https://redis.io/docs/latest/commands/bitfield/

实用做法是先把每个字段的位宽和起始位置列成表，再用 uN 或 iN 固定解释方式；需要计数时显式写出 OVERFLOW SAT 或 OVERFLOW FAIL，不要依赖默认的 WRAP。

问题现场：同一个键里为什么会有多个返回值

BITFIELD key 操作的是一个 Redis 字符串，但字符串被当作连续的位空间。一次调用可以包含多段操作，返回数组的第一个元素对应第一个子命令，第二个元素对应第二个子命令，以此类推。官方文档还明确说明，每个子命令的时间复杂度是 O(1)，但访问很远的位会触发字符串扩容。

因此，下面这条命令不是“执行两次后只返回最后一次”，而是同时递增一个有符号字段，再读取一个无符号字段：

# 第一个字段是从第 100 位开始的 5 位有符号整数；第二个字段读取前 4 位
redis-cli BITFIELD metrics INCRBY i5 100 1 GET u4 0

返回结果要按照命令里的顺序解释。SET 返回写入前的旧值，INCRBY 返回更新后的新值，GET 返回当前读到的值。

初步判断：先把编码和偏移写清楚

编码由两部分组成：i 表示有符号整数，u 表示无符号整数，后面的数字是位宽。例如 u8 能表达 8 位无符号字段，i16 表示 16 位有符号字段。Redis 官方文档当前支持有符号最多 64 位、无符号最多 63 位。

偏移不带前缀时，是从字符串开头计算的零基位偏移；偏移带 # 时，会按当前编码的位宽进行槽位换算。要把同宽字段当成数组使用，# 更不容易手算错：

# 两个连续的 i8 字段分别落在第 0 和第 8 位
redis-cli BITFIELD profile SET i8 #0 100 SET i8 #1 200

# 读取同一组字段，返回值按 GET 子命令顺序排列
redis-cli BITFIELD profile GET i8 #0 GET i8 #1

如果不同字段需要不同位宽，就改用普通位偏移，并把字段表保存到代码或配置中。不要只在命令里留下几个“神秘的 37、52、91”，否则后续修改一个字段时很难判断是否覆盖了邻接位。

动手验证：一次命令读写多个位字段

下面用一个简化的画像键保存三个逻辑字段：状态 2 位、等级 6 位、计数 10 位。示例把连续字段放在固定位置，重点是展示返回值顺序和一次调用中的组合方式。

# 先设置状态、等级和计数；SET 返回每个字段被覆盖前的旧值
redis-cli BITFIELD user:42 SET u2 0 1 SET u6 2 12 SET u10 8 30

# 一次读取三个字段；返回数组顺序与三个 GET 的顺序一致
redis-cli BITFIELD user:42 GET u2 0 GET u6 2 GET u10 8

# 只增加计数，同时读取状态；INCRBY 返回新计数，GET 返回当前状态
redis-cli BITFIELD user:42 INCRBY u10 8 1 GET u2 0

这里的 0、2、8 是位偏移，第二个字段紧接着第一个字段，第三个字段从第 8 位开始。如果写入的最远位超过当前字符串长度，Redis 会补零并扩展字符串到所需的最小长度；这在偶尔访问很远偏移时可能带来额外分配。

业务代码接收返回数组时，应当按固定 schema 解包，而不是根据返回值猜字段。字段表至少记录名称、编码、偏移、取值范围和是否允许溢出。

定位原因：默认 WRAP 可能让计数回到小值

INCRBY 和 SET 遇到边界时，默认溢出策略是 WRAP。例如 2 位无符号字段的值域是 0 到 3，继续加 1 会绕回 0。对环形序号这是合理的，对库存、额度或重试次数通常就是错误的。

OVERFLOW 只影响它后面、直到下一个 OVERFLOW 之前的 SET 和 INCRBY。三种策略可以这样理解：

修复方案：对业务计数显式选择 SAT 或 FAIL

如果字段代表不会无限回绕的业务计数，可以选择饱和策略：

# u2 的最大值是 3；SAT 会把继续增加的结果保持在 3
redis-cli BITFIELD quota OVERFLOW SAT INCRBY u2 0 1

# 需要业务感知越界时使用 FAIL；返回 nil 后由调用方决定是否告警或拒绝
redis-cli BITFIELD quota OVERFLOW FAIL INCRBY u2 0 1

注意同一条命令里可以切换策略，但策略只对后面的写操作生效。若使用 FAIL，不要只判断命令是否执行成功，还要检查返回数组里对应位置是否为空；在 RESP2 中表现为 nil，在 RESP3 中表现为 null。

对于固定数组式字段，推荐把策略和字段声明放在同一处。例如“等级允许饱和，订单序号允许回绕，额度超界必须失败”，不要让三个字段都继承默认值。

验证结果：用四个检查点确认布局没有漂移

1. 检查编码：确认有符号字段没有误写成 uN，无符号字段也没有超出 63 位限制。
2. 检查偏移：连续字段优先使用 #，非连续字段记录明确的位偏移，避免互相覆盖。
3. 检查返回值：按子命令顺序解包，区分 SET 的旧值、INCRBY 的新值和 GET 的当前值。
4. 检查边界：给每个字段做一次最大值、最小值和越界路径，确认 WRAP、SAT、FAIL 符合业务预期。

还要留意一个容易忽略的成本：访问距离当前字符串很远的位会造成扩容，BITFIELD 本身很快并不意味着任意偏移都没有内存代价。字段布局应尽量紧凑，并把可能跳到远端的场景单独评估。

常见问题

BITFIELD 的 SET 返回新值还是旧值？

SET 返回该位字段被覆盖前的旧值；INCRBY 返回更新后的新值，二者不要混用。

没有这个 Redis 字符串键时 GET 会报错吗？

不会。GET 会把超出当前字符串长度的缺失位按 0 处理；但 SET 或 INCRBY 写到远端位时会扩展字符串。

为什么一次 BITFIELD 返回多个数字？

因为一次调用可以串联多个子命令，返回数组中的每一项对应一个子命令。调用方必须按固定顺序解包。

OVERFLOW FAIL 失败后会写入部分结果吗？

越界的那个 SET 或 INCRBY 不执行，并返回 nil/null；如果同一条命令包含多个子命令，仍应按每一项的返回值分别处理。

总结一下：先用字段表固定编码和偏移，再组合 GET、SET、INCRBY，最后为每类业务字段显式指定 OVERFLOW。这样既能享受 BITFIELD 把多个小整数收进一个字符串的紧凑性，也能避免默认回绕把边界错误悄悄变成正常数据。