Redis BITFIELD_RO 怎样只读提取打包整数

需要从一个 Redis String 里读出多个打包整数，又不希望查询动作修改数据时，可以使用 BITFIELD_RO。它只接受 GET encoding offset，同一次调用可以读取多个字段，返回数组的顺序与 GET 的书写顺序一致。要点是先固定位布局，再分别确认 i/u 编码和 offset，不能把它当成普通字符串切片。

最小形式是 BITFIELD_RO packed:stats GET u3 0 GET i5 3 GET u8 8。它从同一个 key 的第 0、3、8 位读取三个字段，结果可按顺序得到 5、-7、200。BITFIELD_RO 只读，适合把写入和查询职责分开，也适合只读副本上的读取路径。

一、先把打包整数的布局写清楚

Redis 位字段建立在 String 上，字段不要求按字节对齐。为了让示例容易核对，先把 3 位无符号、5 位有符号和 8 位无符号字段放在同一个 key 中：第一个字段从 bit 0 开始，第二个从 bit 3 开始，第三个从 bit 8 开始。生产代码通常由写入侧负责维护这份布局契约，读取侧只需要遵守它。

# 先写入示例布局：u3 占 bit 0-2，i5 占 bit 3-7，u8 占 bit 8-15
redis-cli BITFIELD packed:stats \
  SET u3 0 5 \
  SET i5 3 -7 \
  SET u8 8 200

# 只读提取三个字段，GET 的顺序就是返回数组的顺序
redis-cli BITFIELD_RO packed:stats \
  GET u3 0 \
  GET i5 3 \
  GET u8 8
# 预期返回：5、-7、200

这条读取命令不会使用 SET、INCRBY 或 OVERFLOW。如果客户端把结果映射到对象，建议按命令中的同一顺序解包，例如将三个位置分别命名为 level、delta 和 score，不要只依赖数组下标的记忆。

二、encoding 和 offset 决定读出的整数

encoding 由字母和位数构成。u5 表示 5 位无符号整数，范围是 0 到 31；i5 表示 5 位有符号整数，范围是 -16 到 15。位数越小，节省的空间越多，但可表达的范围也越窄。官方参考支持有符号整数最多 64 位、无符号整数最多 63 位。

不带前缀的 offset 是零基 bit 偏移，不是字节下标。需要读取非等宽布局时，直接写真实偏移，例如上面的 0、3、8；这样能清楚表达字段边界。若所有字段使用相同宽度，可以用 #n 省掉乘法：

# 等宽 u8 槽位：#0、#1、#2 分别对应 bit 0、8、16
redis-cli BITFIELD_RO counters GET u8 "#0" GET u8 "#1" GET u8 "#2"
# 返回数组的三个位置依次对应三个槽位

# i/u 只改变解释方式，不会把已有字段自动转换成另一种布局
redis-cli BITFIELD_RO packed:stats GET i5 3 GET u5 3
# 同一组 bit 用 i5 和 u5 读取，数值解释可能不同

#n 是按当前 encoding 的宽度计算的槽位表达式。因此，混合 u3、i5、u8 时不要把 #0 #1 #2 想成统一的 8 位数组；非等宽字段应在协议中保存明确的 bit offset。

三、一次读多个字段时检查返回顺序和边界

命令可以重复追加 GET，每个子命令的读取复杂度为 O(1)，整条命令的结果是一个数组。应用层最容易出错的地方不是命令拼写，而是字段定义和返回位置不一致。可以用下面的清单设计接口：

读取超出当前字符串长度的位时，Redis 会把缺失部分视为 0；这意味着不存在的 key 也可能得到一组 0，而不是天然报错。这个行为适合稀疏初始化，但不适合用来判断业务数据是否真的写入过。若要区分“全 0 的有效记录”和“key 不存在”，应额外用 EXISTS 或明确的版本字段做状态判断。

四、只读并不等于没有部署边界

BITFIELD_RO 的只读属性解决的是命令本身不会修改 key，不能替代连接路由和权限设计。使用 Redis Cluster 的只读副本时，先确认服务端和客户端都支持该命令，并让只读连接按集群规则访问正确的副本；权限上也要允许 bitmap 读取。对于需要写入、递增或设置溢出策略的场景，应回到 BITFIELD，不要把 BITFIELD_RO 当成写命令的缩写。

工程上建议把位布局写成版本化契约：字段名、位宽、起始 offset、符号类型和默认值都记录在代码或配置中。这样后续新增字段时，可以选择追加到未占用区域，避免在不知情的情况下移动旧字段，导致历史数据被另一种 encoding 解释。

相关问题

BITFIELD_RO 能执行 SET 或 INCRBY 吗？

不能。它只接受 GET encoding offset；需要写入或递增时使用 BITFIELD，并单独设计溢出策略。

为什么同一个字段用 i5 和 u5 读出不同结果？

两者使用相同的 bit，但解释范围不同。最高位在有符号编码中参与负数表示，在无符号编码中仍表示正数权重。

读取不存在的 key 为什么没有报错？

GET 对超出当前 String 的位按 0 处理，所以空 key 可能返回 0。需要判断数据是否存在时，再结合 EXISTS 或业务版本字段。

把位布局、encoding、offset 和返回顺序一起写进协议，BITFIELD_RO 就适合承担高密度计数器或状态字段的批量读取；如果这些约束没有固定，节省的字节很容易换来难以排查的数值解释错误。