Redis BITFIELD 如何读取紧凑计数器：位偏移、溢出策略与原子返回值

当一组状态计数都只有几个字节，却被拆成几十个 Redis key 时，真正浪费的往往不是读取时间，而是 key 和字符串对象本身的管理成本。Redis BITFIELD 可以把多个小整数放进同一个字符串，并在一次调用中读取、设置或递增它们。

紧凑计数器的关键不是“把数字塞进位图”这么简单，而是固定编码宽度、用 # 偏移表达数组位置，并在递增前明确选择 WRAP、SAT 或 FAIL。

BITFIELD 适合管理哪类小整数

它操作的是 Redis String，不是独立的 Hash 字段。每个子操作都指定一个整数编码，例如 u8 表示无符号 8 位整数，i16 表示有符号 16 位整数。一个 key 可以连续承载多个宽度相同或不同的字段。

这很适合按日保存一组小计数、把一批开关状态压进一个值，或在高频写入时减少 key 数量。它不适合需要按字段单独过期、单独查询或频繁改变字段宽度的记录。

用 #0 和 #1 固定多个计数器的位置

下面的布局把 redis:daily:counter 的第一个和第二个槽都定义成 u8。#0 与 #1 会按编码宽度自动换算为位偏移，因此不需要手写 0 和 8。

BITFIELD redis:daily:counter SET u8 #0 12 SET u8 #1 7 GET u8 #0 GET u8 #1

返回值按子操作顺序排列：第一个 SET 返回旧值，第二个 SET 返回旧值，最后两个 GET 返回当前值。第一次使用时，未分配的区域按零读取；写入较远的位会让字符串扩展，所以槽位规划不能随意跳到很大的偏移。

读取时不要把返回数组当成字段名映射

BITFIELD 返回的是有序列表，不会带回 day 或 retry 这样的字段名。客户端应按请求顺序接收结果，或者在代码里把操作列表与返回列表一起封装，避免后来插入一个 GET 后造成下标错位。

BITFIELD redis:daily:counter GET u8 #0 GET u8 #1

如果只需要读而不希望客户端获得写权限，可以使用只读的 BITFIELD_RO。它只接受 GET，更适合把读取连接放进只读权限边界。

INCRBY 递增前先决定越界怎么处理

以 u8 为例，能够表示的范围是 0 到 255。默认的 WRAP 会回绕：255 再加 1 会得到 0。这个结果对环形序号可能合理，但对订单量、失败次数通常是危险的。

BITFIELD redis:daily:counter OVERFLOW SAT INCRBY u8 #0 1
BITFIELD redis:daily:counter OVERFLOW FAIL INCRBY u8 #1 1

OVERFLOW SAT 会把结果压在边界上，超过 255 时仍返回 255；OVERFLOW FAIL 在无法表示时返回空值，并且不写入新值。一个 OVERFLOW 只影响后面紧邻的写入类子操作，读取操作不会改变这个策略。

和普通 INCR key 相比，取舍在哪里

普通 INCR 的语义直观，一个计数一个 key，也方便独立设置过期时间和按名称排查。BITFIELD 的优势是把多个小整数集中在一个字符串里，并让一次调用按顺序完成多个子操作；代价是布局成为协议，后续修改宽度或偏移必须兼容旧数据。

如果计数器需要单独删除、单独过期，或者运维人员经常直接用命令行查看某一个名字，Hash 或普通 String 往往更容易维护。只有当字段数量稳定、宽度可预估、访问模式确实适合批量读取时，紧凑布局才值得引入。

上线前的三项核对

第一，给每个槽位写一份编码表，记录编码、逻辑名称和偏移，不要只把 #0 留在代码里。第二，对会自然增长的值显式指定 OVERFLOW SAT 或 OVERFLOW FAIL，并分别测试边界返回值。第三，检查客户端对空值的处理，因为 FAIL 的越界结果不是普通整数。

还要关注远位写入导致的字符串扩展。Redis 官方文档把每个子操作的复杂度列为 O(1)，但访问当前短字符串之外的很远位置仍可能触发分配；这类布局应在测试环境用真实槽位范围核对内存变化。

常见问题

BITFIELD 的 # 偏移是不是字节下标

不是。它会把槽号乘以整数编码宽度；u8 #1 表示从第 8 个 bit 开始。若使用非整字节宽度，必须额外理解 bit 顺序。

为什么 INCRBY 返回空值

先检查前面是否设置了 OVERFLOW FAIL。当新值超出编码范围时，Redis 会返回空值而不写入；这和网络错误或 key 不存在不是一回事。

把编码布局、返回顺序和越界策略一起固定下来，BITFIELD 才是可维护的紧凑计数器，而不是一段只有作者自己看得懂的位运算。