BITFIELD 存储指定宽度和符号性的整数片段(如i8、u16),非完整整数对象;支持位级读写、原子增减及溢出控制,但需注意偏移单位为位、未初始化位返回0、跨字节边界正确处理及客户端解析差异。

BITFIELD 命令能存什么数?不是所有整数都行
BITFIELD 本质是在字符串的二进制位上做读写,它不存“整数对象”,只存“一段连续的比特”。所以你能存的不是 int 或 long,而是指定宽度(如 8、16、32 位)和符号性(i 或 u)的整数片段。
常见误用:以为 BITFIELD key INCRBY i64 0 1 能当原子计数器长期用——其实只要字符串被其他命令(比如 SET、APPEND)覆盖或截断,之前写的位就全丢了。
-
i8表示有符号 8 位,范围是 -128 ~ 127;u8是无符号,0 ~ 255 - 偏移量(offset)单位是“位”,不是字节。写
BITFIELD key SET i16 16 100是从第 16 位开始写一个 16 位有符号整数 - 字符串底层仍是 SDS,位操作不会自动扩容,但 BITFIELD 会按需扩展字符串长度(以字节为单位向上取整)
- 超过当前字符串长度的写操作会触发填充(padding),高位补 0 —— 这点容易被忽略,导致读出意外的 0 值
怎么安全地读写多个字段?别直接链式调用 BITFIELD
BITFIELD 支持一次命令里叠加多个子命令(GET、SET、INCRBY),但要注意:所有子命令共享同一个字符串视图,且执行是原子的。问题在于,如果中间某个 GET 读到了未初始化区域,返回的是 0(不是错误),而你可能误以为这是业务值。
典型场景:用一个字符串存 4 个用户状态位(每状态占 2 位),想一次性读出全部。不能依赖 GET u2 0、GET u2 2 等连写,因为没初始化时全返 0,无法区分“真为 0”和“未设置”。
- 写之前先用
SET初始化整个字符串为全 0(如SET key \x00\x00\x00\x00),尤其当你要用高位时 - 读多字段时,优先用单次 BITFIELD + 多个
GET,避免多次往返;但必须接受“未写过的位置默认为 0”这个事实 - 不要在同一个 BITFIELD 命令里混用
INCRBY和GET去读刚 incr 的结果——它读的是 incr 前的值(命令内子操作顺序是先读再写) - Redis 6.2+ 支持
OVERFLOW控制溢出行为(SAT、FAIL、WRAP),老版本溢出直接回绕,容易出 bug
BITFIELD 和 SETBIT / GETBIT 比起来差在哪?
SETBIT 和 GETBIT 只能操作单个 bit,而 BITFIELD 最小单位是 1 位,最大支持 64 位整数。关键差异不在“能干啥”,而在“怎么解释那串比特”。
比如你想存一个带符号的温度值(-50 ~ +50),用 SETBIT 得自己拆成 7 位二进制再循环设,而 BITFIELD key SET i8 0 -50 一行搞定,Redis 自动处理补码。
-
SETBIT key offset 1写的是第offset个 bit,而BITFIELD key SET u1 offset 1写的是从offset开始的 1 位无符号整数——效果一样,但语义清晰得多 -
BITFIELD支持原子自增(INCRBY),SETBIT不支持;但INCRBY对u1这种宽度只有 1 的类型毫无意义(只能是 0 或 1) - 性能上,单 bit 操作
SETBIT/GETBIT更轻量;批量多宽度整数操作,BITFIELD减少网络和解析开销 - 注意:
GETBIT key offset返回 0/1,而BITFIELD key GET u1 offset返回 0 或 1,但类型是整数响应,客户端解析方式不同
上线前必须验证的三个边界情况
BITFIELD 的坑大多出在位宽、符号性和内存布局交界处,光看文档容易漏掉实际运行时的表现。
- 写
i16到偏移 7:起始位是第 7 位,跨越字节边界(落在第 0 字节后 7 位 + 第 1 字节前 9 位),Redis 能正确处理,但某些客户端 SDK 解析位域时可能出错 - 用
INCRBY i8 0 128:i8 最大是 127,128 会溢出。Redis 6.2 默认WRAP(变成 -128),不报错也不提醒 - 对空 key 执行
BITFIELD key GET u4 0:返回[0],不是空数组也不是 error;但如果你期望“不存在就报错”,得自己加逻辑判断 key 是否存在(比如先EXISTS)
位域操作的复杂性不在命令本身,而在于你得同时脑内维护:字符串字节索引、位偏移、整数符号规则、溢出策略、以及客户端如何把响应还原成业务值。少盯住其中一环,数据就 quietly 错了。










