Redis BITFIELD 怎么批量读写位字段：OVERFLOW、偏移量与结果核对

把 Redis 当计数器用时，很多人会把几十个小状态拆成几十个 key。若这些值都能落在固定的位宽里，BITFIELD 可以把它们放进一个字符串，并在一次命令里完成读取、写入和递增。真正容易出错的地方不是语法，而是偏移量、返回值顺序和溢出策略。

BITFIELD 适合存什么，先看一条最小命令

例如设备上报两个 0 到 255 的小计数：第一个槽记录温度告警次数，第二个槽记录断线次数。可以把它们分别放入一个字符串的两个 u8 字段：

redis-cli
DEL device:42:stats
BITFIELD device:42:stats SET u8 #0 7 SET u8 #1 2 GET u8 #0 GET u8 #1
GET device:42:stats

这条命令返回四个整数，前两个是两次 SET 读回的旧值，后两个才是最后的读取结果。新 key 的旧值通常是 0，所以不要把第一项当作写入后的值。

u8、i8 和普通 offset 到底差在哪里

编码中的 u 表示无符号，i 表示有符号；数字是字段宽度。例如 u8 能表达 0 到 255，i8 能表达 -128 到 127。offset 默认按 bit 计算，不是按字节计算。

如果字段宽度和位置总是成组排列，带 # 的 offset 更不容易写错：

BITFIELD device:42:stats SET u8 #0 7 SET u8 #1 2 GET u8 #0 GET u8 #1

#1 会把 1 乘以 u8 的宽度，落在第 8 个 bit；改成 #2 就是第 16 个 bit。若你需要把一个 3 bit 标志位和一个 13 bit 数值紧挨着放置，仍然要自己计算普通 bit offset，不能把所有 offset 都当成字节下标。

一次 BITFIELD 的返回数组应该怎样对上

客户端收到的是一个数组，每个产出结果的子操作占单独一个位置。建议写代码时按命令构造顺序逐个做结果断言，不要靠字段名去猜返回值的下标位置：

BITFIELD device:42:stats \
  SET u8 #0 7 \
  INCRBY u8 #1 1 \
  GET u8 #0 \
  GET u8 #1

返回可以理解为：第 1 项是第一个 SET 的旧值，第 2 项是第二个槽递增后的新值，第 3、4 项是两次 GET。如果把 SET 和 INCRBY 的返回语义混在一起，监控很容易把“写入成功”记录成旧值 0。

还有一个容易踩的边界：同一条命令里的子操作会按顺序依次生效。前一项写入的结果会直接影响后一项读取的返回值，所以测试时要先把待操作的 key 清理干净，同时完整记录整条命令的子操作顺序。

OVERFLOW 不写清楚，计数器迟早会回绕

u8 的最大值是 255。默认策略 WRAP 在 255 上再加 1 会回到 0；这对环形序号有用，对告警次数、库存或累计量通常是危险的。

DEL device:42:stats
BITFIELD device:42:stats SET u8 #0 255 OVERFLOW SAT INCRBY u8 #0 1
BITFIELD device:42:stats GET u8 #0

DEL device:42:stats
BITFIELD device:42:stats SET u8 #0 255 OVERFLOW FAIL INCRBY u8 #0 1
BITFIELD device:42:stats GET u8 #0

SAT 会把结果停在 255；FAIL 会让溢出的那次递增返回 nil，并且该字段不被改变。OVERFLOW 的作用范围是后续写入型子操作，生产命令不要依赖默认值，直接把策略写在命令里更容易审查。

上线前用四个检查点收住边界

1. 先确认位宽：业务最大值是否可能超过 u8、u16 或 i16，不要为了省几个字节牺牲可解释性。
2. 再确认 offset：连续槽位优先使用 #，非对齐字段把 bit 起点写进常量或测试用例。
3. 核对返回值：SET 看旧值，INCRBY 看新值，FAIL 还要处理 nil。
4. 观察对应 key 的实际长度：远端偏移量会触发字符串自动扩容，不能把用户可控的超大偏移量直接丢给 Redis 执行。

常见问题

BITFIELD 能代替普通 Redis Hash 吗？

只有业务侧字段数量多、位宽固定、按位置访问且能接受位级编码开销时才适合用 BITFIELD。需要按字段名查询、频繁增删字段或者希望直接读懂存储值的场景，普通 Hash 结构会更合适。

为什么 GET u8 0 和 GET u8 #0 看起来一样？

因为 #0 乘以任何字段宽度仍然是 0。差异会在 #1、#2 这样的连续槽位上体现出来。

OVERFLOW FAIL 返回 nil 时会回滚整条命令吗？

不能把 BITFIELD 当成整条命令自动回滚的原子操作。要按每个子操作单独核对结果，用独立测试验证同一条命令中前后字段的联动变化，业务层还要预先定义 nil 返回的告警或重试策略。

小结

BITFIELD 的价值在于用固定宽度把多个小整数压进一个字符串，同时保持一次命令的原子修改。实际落地时，先画清字段布局，再把返回值顺序和溢出策略写进测试；只要这两处不靠默认猜测，BITFIELD 就不会变成难以维护的位运算黑盒。