Redis bitmap计算位图偏移并避免越界的实现方法

Redis Bitmap 的偏移量本质上是 String 中从 0 开始计算的 bit offset，不是字节下标。要避免越界，先把业务位置换算成非负的位偏移，再检查乘法结果是否超过 2^32 - 1；如果还要用 BITFIELD 存定宽整数，则要分清普通绝对 offset 和带 # 的槽位 offset。

官方地址：https://redis.io/docs/latest/develop/data-types/strings/bitfields/

实用规则是：业务下标只负责定位，Redis offset 只负责表达位位置；任何“槽位 × 位宽”的计算都在客户端完成边界检查，不能把 Redis 自动补零误认为输入合法。

把业务下标换算成 Redis bit offset

假设签到日、功能开关或用户序号在业务侧从 0 开始，直接把这个整数传给 SETBIT key offset value 即可。如果业务侧从 1 开始，先减一；如果业务下标代表第几个定宽槽位，则还要乘以每个字段的位宽。不要把“第 3 个字节”直接当成 offset 3，那只会改到第 4 个 bit。

# 用第 10 个业务位置，对应零基 bit offset 9
redis-cli SETBIT user:features 9 1

# 读取同一位；返回 0 或 1，不代表 key 一定已经存在
redis-cli GETBIT user:features 9

Redis Bitmap 由 String 承载。offset 0 到 7 属于第一个字节，8 到 15 属于第二个字节。用公式表达就是：byteIndex = offset / 8，bitIndex = offset % 8。这两个值适合在客户端解析 GET key 返回的二进制字符串时使用。

按 Redis 的高位优先规则解释字节

如果只是调用 GETBIT，不需要自己处理掩码；但把 Bitmap 读成 String 后在 Go 中解析，就必须注意一个字节内的顺序。offset 对应的掩码不是简单的 1 ，而是从最高位开始计数：

func bytePosition(offset int64) (int64, byte, error) {
    // Redis offset 必须是非负位偏移，先拦截错误输入。
    if offset = 1

例如 offset 9 的 byteIndex 是 1，字节内位置是 1，掩码为二进制 00000010。这只是客户端解释规则；直接用 GETBIT 时，Redis 已经替你完成了定位。

在 SETBIT 前拦截偏移越界

SETBIT 的 offset 要求大于等于 0 且小于 2^32，字符串会扩展到能容纳该位，扩展区域补 0。极大的首次偏移还可能触发大段内存分配，因此不能只依赖命令本身处理边界。

const maxBitmapOffset = (uint64(1)  maxBitmapOffset/width {
        return 0, fmt.Errorf("slot offset overflow")
    }
    offset := slot * width
    // 这里的上限是可用的最大 bit offset，而不是字符串字节数。
    if offset > maxBitmapOffset {
        return 0, fmt.Errorf("bitmap offset exceeds Redis limit")
    }
    return int64(offset), nil
}

边界检查至少包括：业务下标不能为负；位宽不能为 0；乘法前确认结果不会回绕；最终 offset 不超过 Redis 限制；对稀疏位图评估远端扩容成本。读一个尚未写过但在当前长度之外的位会返回 0，这是 Redis 的读取语义，不是“业务数据确实为否”的证明。

BITFIELD 的绝对 offset 和 # 槽位写法

存储多个定宽整数时，BITFIELD 可以直接使用绝对 bit offset，也可以给 offset 加 # 前缀，让 Redis 用字段位宽自动计算位置。例如 u8 #0 从位 0 开始，u8 #1 从位 8 开始，u8 #3 从位 24 开始。

# #0 和 #1 按 u8 的位宽排布，不需要客户端手算 0 和 8
redis-cli BITFIELD user:stats SET u8 '#0' 12 SET u8 '#1' 99

# 普通数字是绝对 bit offset；这里从第 16 位开始读一个 u8
redis-cli BITFIELD user:stats GET u8 16

# 对增量字段设置饱和溢出，避免无符号计数回绕
redis-cli BITFIELD user:stats OVERFLOW SAT INCRBY u8 '#1' 1

无前缀 offset 与 # 槽位的区别，是排查“读到相邻字段”问题的关键。GET 访问当前字符串之外的位会按 0 处理，SET 或 INCRBY 则会按最远触及的位扩展并补零；而定宽整数溢出则由 WRAP、SAT 或 FAIL 决定，默认是 WRAP。

上线前的偏移复核清单

相关问题

GETBIT 读取超出当前字符串的 offset 会报错吗？

不会。官方语义是把缺失部分视为 0；但业务代码仍要区分“未初始化”与“明确写入了 0”。

为什么 offset 9 对应第二个字节的第二位？

因为每 8 个 bit 占一个字节，9 / 8 = 1，而 9 % 8 = 1；Redis 在该字节内从高位向低位解释位置。

BITFIELD 的 #1 能避免所有越界吗？

不能。它只负责按字段位宽计算槽位起点，业务仍需控制槽位数量、总位数和远端扩容成本；定宽整数自身还要选择合适的溢出策略。