Redis BITFIELD 怎样存储多个小整数并读取指定范围

如果一组数值的取值范围很小，却要在 Redis 中高频读取或更新，可以把它们压缩到同一个 String 的位流里。BITFIELD 的关键不是“把数字转成字符串”，而是先给每个字段分配位宽，再用偏移找到它。

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

本文只讨论三件事：位宽怎样决定范围、偏移怎样定位字段、越界时怎样选择策略。示例使用 Redis CLI 语法，图片是原创静态说明图，不是运行截图。

先把位宽和偏移设计清楚

BITFIELD 把 Redis String 当作从 0 开始编号的位数组。编码以 u 或 i 开头：u4 表示 4 位无符号整数，范围是 0 到 15；i8 表示 8 位有符号整数，范围是 -128 到 127。

字段不要求落在字节边界上。例如先放一个 4 位状态，再放一个 8 位温度，第二个字段可以从第 4 位开始。这样节省空间，但也意味着读取时必须复用完全相同的编码和偏移。

两种 offset 写法分别适合什么场景

最直接的 offset 是从 0 开始计算的 bit offset。下面的布局把 u4 放在 0，i8 放在 4，u3 放在 12：

# 用直接位偏移，把三个不同宽度的字段连续写入同一个 String
redis-cli BITFIELD device:state SET u4 0 9 SET i8 4 -12 SET u3 12 5

# 用同样的编码和偏移读取，返回值顺序对应三个 GET 子命令
redis-cli BITFIELD device:state GET u4 0 GET i8 4 GET u3 12

SET 返回被覆盖前的旧值，GET 返回当前位置按指定编码解释后的整数。一个命令可以串联多个子命令，返回数组的顺序就是子命令的顺序。

如果字段是等宽数组，可以使用带 # 的 offset。#0 表示第 0 个槽位，#1 表示第 1 个槽位，Redis 会把槽位编号乘以当前编码的位宽：

# 每个槽位都是 u4，#0、#1、#2 自动对应 bit 0、4、8
redis-cli BITFIELD sensor:levels SET u4 #0 3 SET u4 #1 7 SET u4 #2 12

# 仍然用 u4 读取三个等宽槽位，避免手算 bit offset
redis-cli BITFIELD sensor:levels GET u4 #0 GET u4 #1 GET u4 #2

这里的 # 只适合等宽字段。若一个 String 同时包含 u4、i8、u3 这种混合布局，就应该明确写出实际 bit offset；否则换了编码，槽位间距也会跟着变化。

用 SET、GET 和 INCRBY 组合一次完成读写

BITFIELD 的一个实用模式是：用固定宽度保存一组小计数器，再在同一条命令里增加它们。每个子命令独立返回结果，复杂度按子命令计为 O(1)。

# 用两个 u8 槽位保存成功数和失败数，并同时递增
redis-cli BITFIELD job:daily INCRBY u8 #0 1 INCRBY u8 #1 2

# 读取时显式列出每个槽位，返回 [成功数, 失败数]
redis-cli BITFIELD job:daily GET u8 #0 GET u8 #1

这个模式适合计数器、状态码、等级和有限枚举。它的前提是业务能接受固定的位宽上限，并且所有读写方都共享同一份字段布局。字段定义最好写进代码常量或数据字典，避免某个调用方把 u8 误读成 i8。

用 OVERFLOW 处理小整数越界

如果没有显式设置，INCRBY 和后续写操作默认使用 WRAP。对计数器来说，这通常不是安全的默认业务语义：u3 的最大值是 7，继续加 1 后可能回到 0。

三种策略的差异可以先用一个范围很小的 u3 字段理解：

# SAT 会把超过 u3 最大值 7 的结果保持在 7
redis-cli BITFIELD quota SET u3 #0 7 OVERFLOW SAT INCRBY u3 #0 1

# FAIL 会返回 nil；调用方应把 nil 当作“未写入”处理
redis-cli BITFIELD quota OVERFLOW FAIL INCRBY u3 #0 1

OVERFLOW 会影响它后面出现的 SET 和 INCRBY，直到同一条 BITFIELD 命令里的下一次 OVERFLOW。它不是全局配置，也不会改变其他命令的行为，因此在一条复杂命令里最好把策略放在紧邻的更新操作前面。

这套位段模式的反例

把许多字段塞进一个 String 并不意味着所有数字都适合 BITFIELD。字段经常扩容、需要按名称查询、需要保存完整时间戳，或者读写方无法稳定共享布局时，位段压缩会把数据结构的隐含约定变成维护成本。

还要注意访问很远的 bit offset 会让 String 扩容到被触碰的最远位置，可能产生比操作已有位更高的分配成本。不要为了“预留一个很大的 offset”而把稀疏字段放得过远。

上线前的判断清单

1. 每个字段的最大值、最小值是否能被选定的 i/u 位宽覆盖？
2. 混合宽度布局是否记录了明确的 bit offset，等宽数组是否统一使用 # offset？
3. 计数器越界时，业务到底需要回绕、封顶还是拒绝写入？
4. 所有读写方是否使用同样的编码、offset 和字段顺序？
5. 是否避免了过远的 bit offset 和不可读的隐式布局？

总结：BITFIELD 的核心是“位宽决定范围，offset 决定位置，OVERFLOW 决定越界后果”。固定宽度的多个小整数可以用 #0、#1 简化定位；混合宽度字段则应显式管理 bit offset。只要把布局和溢出策略写成稳定契约，压缩存储才不会变成难以排查的隐患。

常见问题

u8 和 i8 能互相读取吗？

不应这样做。它们占用相同的 8 位，但解释范围不同：u8 是 0 到 255，i8 是 -128 到 127。读取编码必须和写入契约一致。

#1 是第一个字节吗？

不是。#1 是按当前整数编码宽度计算的第一个槽位，不是固定的字节偏移。例如 u4 下 #1 从第 4 个 bit 开始，u8 下才从第 8 个 bit 开始。

FAIL 返回 nil 后字段会被清零吗？

不会。检测到上溢或下溢时，FAIL 对应的操作不执行，并用 nil 表示没有完成这次更新。调用方应把它当成一次明确的失败结果。