Redis BITFIELD 怎么在一个键里保存多个整数位段

我在做设备状态缓存时，最先想到的是把每个状态拆成多个 Redis key。这样直观，但字段一多，读取和更新就会变成一串往返。Redis BITFIELD 提供了另一种组织方式：把一个 String 当作按位寻址的容器，在同一个键里放下不同宽度的有符号或无符号整数。

这类设计适合固定范围的状态码、短计数器、压缩后的标志集合。关键不是把数字“转成二进制字符串”，而是先画好字段边界，再用相同的编码和偏移读回它们。

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

混合宽度的字段使用明确的 bit offset 最容易维护；同一宽度的连续整数数组可以使用 #n 让 Redis 按字段宽度计算位置。一次 BITFIELD 调用可以串联多个 GET、SET、INCRBY，并按参数顺序返回结果数组。

先把业务状态拆成固定宽度的位段

先不要急着写命令。我通常会先列一张小表：字段含义、编码、宽度、起始位。比如设备状态用 3 位无符号整数，计数器用 5 位无符号整数，温度用 8 位有符号整数。如果要让它们紧挨着排列，起始位就是 0、3、8。

u 表示无符号，i 表示有符号，数字就是字段宽度。Redis 文档说明，字段可以从任意 bit offset 开始，并不要求每个字段都落在整字节边界上。

用 SET 和 GET 读写指定字段

混合宽度布局建议直接写原始 bit offset。下面的命令把状态、计数和温度放进同一个 device:state 键，再按同样的编码和偏移读回来。命令中的注释解释了布局意图，便于以后修改字段表。

# 用显式 bit offset 避免混合宽度字段互相重叠
redis-cli BITFIELD device:state \
  SET u3 0 5 \
  SET u5 3 17 \
  SET i8 8 -2

# 读取时必须复用写入时的编码和起始位
redis-cli BITFIELD device:state \
  GET u3 0 \
  GET u5 3 \
  GET i8 8

SET 会返回被覆盖前的旧值，GET 返回当前位段的解释值。第一次访问不存在的键时，读取超出当前字符串长度的部分按零处理；写入远端位则会按需要扩展 String，并补零到被触及的最远位置。

这里有一个容易踩到的偏移区别：3 是绝对 bit offset，而 #1 是“当前编码宽度乘以 1”的字段内位置。混合宽度时，使用绝对偏移更容易在代码审查中看出字段是否重叠。

让一次 BITFIELD 调用完成多项操作

BITFIELD 的实用之处还在于一次调用可以串联多个子操作。Redis 会为每个子操作放入一个返回项，返回数组的顺序与参数中的操作顺序一致。这样既能减少往返，也能让一次更新和一次读取共享同一个布局。

# 同一请求里依次写入、读取，再更新一个字段
redis-cli BITFIELD device:state \
  SET u3 0 5 \
  SET u5 3 17 \
  GET u3 0 \
  INCRBY u5 3 1

上面会得到四个结果位置：第一个是第一次 SET 覆盖前的旧值，第二个是第二次 SET 覆盖前的旧值，第三个是 GET 读到的状态值，第四个是 INCRBY 完成后的新计数。实际旧值取决于键在调用前的内容，因此不要把示例返回数组硬编码成业务判断。

如果使用连续的同宽字段，#n 会更方便。例如两个连续的 8 位整数可以这样写：

# 对同一个 u8 数组使用字段相对位置，#1 会落在第二个 u8 字段
redis-cli BITFIELD metrics SET u8 '#0' 12 SET u8 '#1' 34

# 用相同的相对位置读取两个元素
redis-cli BITFIELD metrics GET u8 '#0' GET u8 '#1'

用 INCRBY 更新小型计数器

当某个位段代表重试次数、采样数量或短周期计数时，不必先 GET 整个字段、在客户端计算，再 SET 回去。INCRBY 直接在指定编码和偏移上完成增量，并把新值放进当前操作的返回项。

# 只递增位于 bit offset 3 的 u5 计数器
redis-cli BITFIELD device:state INCRBY u5 3 1

# 同一个字段也可以传入负增量，表示递减
redis-cli BITFIELD device:state INCRBY u5 3 -1

字段宽度是数据模型的一部分。写入前要确认业务计数是否真的能放进这个宽度；如果计数会长期增长，应把它单独放到普通 INCR 计数器，而不是为了省一个 key 把它压进过窄的位段。本文不展开 OVERFLOW 的策略差异，但生产设计必须单独决定如何处理边界。

把偏移、扩容和维护边界写进设计

我会把下面几条和字段表一起提交到代码仓库，避免过几个月只剩下一串难以解释的数字：

• 每个字段记录编码、位宽、起始 bit offset 和取值范围。
• 混合宽度布局优先用绝对 offset；#n 只用于读者能清楚理解的同宽数组。
• 不要随意把新字段放到很远的 bit 位置，因为写入远端位会让 String 扩展到更长。
• 同一次调用的返回项按操作顺序解释，调用方不要只读取数组最后一项。
• 字段一旦进入持久化数据模型，移动起始位就等同于迁移，不能只改常量。

最后可以用一条读取命令做人工冒烟检查，但它只是针对当前键值的业务检查，不是本文位图的运行截图：

# 按字段表读取全部值，检查编码和偏移是否保持一致
redis-cli BITFIELD device:state GET u3 0 GET u5 3 GET i8 8

几个容易混淆的问题

BITFIELD 保存的是多个 Redis key 吗？

不是。它只操作一个 String key，只是把这个 String 看成由多个 bit field 组成的容器。

不同宽度字段能不能都用 #0、#1？

可以分别解释，但它们的相对位置按各自编码宽度计算，不代表“上一个字段之后”。如果要拼接不同宽度字段，直接记录绝对 bit offset。

为什么远端字段会让键变大？

因为 SET 或 INCRBY 触及当前长度之外的位时，Redis 需要把 String 扩展到能够容纳最远位的位置，中间区域按零补齐。

什么时候不适合 BITFIELD？

字段需要频繁变更布局、取值范围不断增长，或者团队难以维护位宽表时，普通 Hash、独立 String 计数器通常更容易理解和迁移。