Redis Bitmap 位偏移映射用户状态的设计要点

我在做“用户是否完成某项权益”的状态存储时，最容易踩的坑不是 SETBIT 命令本身，而是把业务用户 ID 直接当成 offset。用户 ID 可能从 1001 跳到 900000000，这会让 Bitmap 的地址空间被稀疏 ID 拉大。更稳妥的做法是：先把业务 ID 映射到稳定、连续的内部 offset，再把这个 offset 写入属于明确租户和状态集合的 Redis key。

官方资料：https://redis.io/docs/latest/develop/data-types/bitmaps/

Bitmap 只保存“某个位置是 0 还是 1”。用户身份、offset 的分配规则和 key 的生命周期必须由业务层明确维护；Redis 不会替你解释一个 offset 对应哪个用户。

本文结论：连续 offset 控制空间，作用域 key 控制数据隔离，SETBIT/GETBIT 控制单状态读写，BITCOUNT 控制集合统计；映射表变化时要用版本或不可复用策略保护历史数据。

先把用户 ID 和 offset 分成两层

我会把这件事拆成“身份映射”和“位状态”两层。身份映射可以放在业务数据库或专门的映射表里，记录 user_id -> offset；Bitmap 只接收 offset。这样无论用户 ID 是整数、字符串还是外部系统编号，位图都只面对紧凑的整数空间。

key 先定作用域，再决定是否按天拆分

一个可读的 key 可以写成 tenant:{tenant_id}:state:{state_name}:v{mapping_version}:{date}。如果状态是当前快照，就不必强行加入日期；如果要统计每日完成率或保留历史，日期应成为明确的分区维度。重点是不要让“全站用户”“某租户用户”“某天用户”共用同一个字符串。

位图是 Redis String 的二进制视图，offset 越大，字符串可能被扩展到对应位置。若直接把稀疏业务 ID 当 offset，即使只有少量用户，也可能付出远大于实际用户数的空间成本。连续 offset 还方便估算上界：大致只需关注最大 offset 对应的字节位置，而不是外部 ID 的数值含义。

单用户读写要保留命令的真实语义

SETBIT 设置或清除目标位，并返回该位修改前的值；GETBIT 读取目标位，超出当前字符串长度的位置按 0 处理。下面的命令只展示静态用法，注释说明每个返回值在业务代码中的用途。

# 为连续 offset=42 的用户标记“已完成”
redis-cli SETBIT 'tenant:7:state:completed:v1' 42 1

# 读取同一个 offset 的当前状态，返回 0 或 1
redis-cli GETBIT 'tenant:7:state:completed:v1' 42

# 清除状态；返回清除前的值，可用于判断是否发生了状态变化
redis-cli SETBIT 'tenant:7:state:completed:v1' 42 0

业务层可以利用第一次返回的旧值做增量统计：旧值为 0、新值为 1 时增加一次，旧值为 1、新值为 0 时减少一次。这个判断只适用于同一个 Bitmap 位；如果还要同时写审计记录、更新时间或映射表，就不能把多个命令的组合误认为单条命令的原子性。

统计时区分单个位、位范围和字节范围

BITCOUNT 适合回答“这个集合里有多少个 1”，也可以指定范围；默认范围参数按字节解释，使用 BIT 修饰符后才按位解释。BITPOS 则用于查找第一个 0 或 1 的位置。两者都可能扫描较大范围，不能把它们当成无成本的单用户查询。

# 统计整个 Bitmap 中已完成的用户数
redis-cli BITCOUNT 'tenant:7:state:completed:v1'

# 只统计 offset 0 到 999，明确告诉 Redis 这是 bit 范围
redis-cli BITCOUNT 'tenant:7:state:completed:v1' 0 999 BIT

# 找到第一个仍为 0 的 offset，结果仍是从 bit 0 开始的绝对位置
redis-cli BITPOS 'tenant:7:state:completed:v1' 0

如果业务只需要某一小段用户集合，优先让映射分配规则和 key 分区共同缩小扫描范围；不要在查询层临时猜测“用户 ID 大概对应哪一段”。

四个容易被忽略的边界

• 删除用户：不要因为用户注销就立刻复用 offset。复用会让历史位看起来属于新用户；可以保留 tombstone，或使用新的映射版本。
• 多租户：同一个 offset 只在一个租户和一个映射版本内有意义，不能跨租户共享而不加前缀。
• 复合写入：Bitmap 单命令写入很清楚，但状态位、映射表和审计记录需要一起变化时，应采用事务或服务端脚本，并设计失败重试语义。
• 生命周期：按天或按活动周期拆 key 时，给过期策略和离线统计留出窗口，别让 TTL 把仍需复盘的状态提前删除。

结语：先维护映射，再维护位图

这类设计的核心不是把更多字段塞进一个 Bitmap，而是让每个 bit 的含义长期稳定。先为用户身份建立不可歧义的连续 offset，再按租户、状态和时间窗口划分 key，最后根据读取目标选择 GETBIT、BITCOUNT 或 BITPOS。当映射要重建、用户要删除或多个对象要一起变更时，优先切版本或明确事务边界。

相关问题

Bitmap 能直接保存用户 ID 吗？不能。它只保存位位置和值，用户 ID 到 offset 的解释必须由业务层维护。

为什么 BITCOUNT 结果和用户数量不一致？通常是映射重复、旧 offset 未清理、key 作用域混用，或把字节范围误当成位范围。先核对 key、映射版本和范围单位。