Redis BITPOS 怎样按 BIT 范围定位首个置位点

Redis 的 bitmap 实际存放在 String 值里。要按“位”而不是“字节”查找首个置位点，关键是给 BITPOS 的范围参数加上 BIT：BITPOS key 1 start end BIT。这里的 start 和 end 是包含端点的位编号范围，返回值始终是从整段字符串开头计算的绝对位索引；范围内没有目标位时返回 -1。

官方地址：https://redis.io/

如果你的业务已经用 GETBIT、SETBIT 按位编号维护状态，就显式写 BIT。不写单位时，Redis 会把范围按字节解释，最容易出现“结果差了 8 倍”的误判。

先分清 BYTE 与 BIT

BITPOS 的语法是 BITPOS key bit [start [end [BYTE | BIT]]]。其中 bit 只能是 0 或 1；start、end 是可选的范围端点，end 也是包含在内的。

下面的命令只用 SETBIT 建立示例状态，不需要把二进制字节手工写进命令行：

# 设置第 0 位和第 9 位，模拟两个已启用的功能开关
redis-cli SETBIT demo:flags 0 1
redis-cli SETBIT demo:flags 9 1

# 只查看第 0 到第 15 位中的首个 1，范围单位必须写 BIT
redis-cli BITPOS demo:flags 1 0 15 BIT

这里的查询目标是“前 16 个位中的第一个 1”。如果第 0 位未设置而第 9 位仍为 1，返回应当是 9；这个数是位编号，不是字节下标。

用 BITPOS 查询首个置位点

当目标是找首个“已启用”位时，把 bit 设为 1；如果要找首个“未启用”位，则把它设为 0。范围可以缩小扫描边界，但不会改变返回值的全局坐标。

# 查找第 8 到第 15 位中的首个 1，端点都包含
redis-cli BITPOS demo:flags 1 8 15 BIT

# 查询同一范围中的首个 0，用于寻找第一个可分配槽位
redis-cli BITPOS demo:flags 0 8 15 BIT

上面两次查询使用同一组范围，但寻找的位不同。第二条命令的返回值仍然是绝对位索引，例如第 12 位是范围内首个 0，就返回 12，不会返回它在范围内的相对序号 4。

范围比较可以这样记：BYTE 适合按原始字节片段定位，BIT 适合和 GETBIT、SETBIT 共用位编号。只要业务字段是“第几个开关”或“第几个槽位”，就应优先使用 BIT。

读取绝对位置并处理空结果

BITPOS 的返回值是一个整数位置。不要把它直接当成字节偏移，也不要在客户端再次乘以 8。只有在需要访问原始字节数组时，才根据业务明确地做 byteIndex = bitIndex / 8 和 bitOffset = bitIndex % 8 转换。

最常见的三个边界如下：

• 范围内找到目标位：返回从整个 String 第 0 位开始计算的绝对编号。
• 范围内没有目标位：返回 -1，这不是 Redis 错误，而是“没有匹配位置”。
• 键不存在：Redis 把不存在的键当作空字符串处理，因此查找 1 通常也会得到 -1。

Redis 官方文档还说明，start 和 end 可以使用负数从末尾定位；在 BIT 模式下，负数按最后一个位倒数计算。若业务需要稳定的分页或槽位编号，建议在应用层把负数范围转换为明确的正向边界后再记录。

在 Go 客户端中固定 BIT 参数

以 github.com/redis/go-redis/v9 为例，可以通过通用命令接口传入 BIT，这样不会误用只接受字节范围的封装。示例只负责读取位置，连接配置和重试策略由应用统一管理：

package main

import (
    "context"
    "fmt"

    "github.com/redis/go-redis/v9"
)

func firstSetBit(ctx context.Context, rdb *redis.Client, key string, start, end int64) (int64, error) {
    // 显式传入 BIT，让 start/end 与 SETBIT 使用同一套位编号。
    value, err := rdb.Do(ctx, "BITPOS", key, 1, start, end, "BIT").Int64()
    if err != nil {
        // 协议错误、连接错误和类型错误都交给调用方决定是否重试。
        return -1, fmt.Errorf("读取 BITPOS 失败: %w", err)
    }
    // -1 是“没有匹配位”的正常结果，不应当当作网络故障。
    return value, nil
}

调用方拿到 -1 时，可以把它映射成“没有可用槽位”或“没有启用功能”；拿到非负整数时，直接把它当作全局位编号。若后续还要用 GETBIT 读取同一位置，应该把这个整数原样传回去。

小结与常见问题

记住三点即可：第一，按位范围必须显式写 BIT；第二，end 包含在范围内；第三，返回值是绝对位索引，-1 表示没有匹配位。这样就能把“查找首个置位点”和 bitmap 中已有的位编号约定保持一致。

BITPOS 为什么返回 9 而不是 1？

因为返回的是整个 String 中的绝对位编号。若查询范围从第 8 位开始，第 9 位是首个目标位，返回仍是 9，而不是范围内相对位置 1。

省略 BIT 会发生什么？

Redis 会按 BYTE 解释 start/end。例如 0 到 1 表示两个字节，不是两个位。和 SETBIT 配合时，这通常就是偏移理解错误的来源。