Redis BITFIELD 做积分计数为什么会溢出：位宽、OVERFLOW 与验收边界

积分服务里有一类数据很适合放进 Redis 的位域：签到次数、等级进度、短周期计数。问题也从这里开始——把一个 8 位字段当成“足够大的整数”，连续加到上限后，结果可能回绕成负数或从 255 变成 0，而业务日志只看到一次正常的数值返回。

先把业务范围换算成位宽，再明确溢出时要回绕、封顶还是拒绝；最后用 GET 和边界值查询验收，不能只看一次 INCRBY 的返回结果。

先复现：8 位积分为什么从 255 变回 0

先准备一个干净的 key。Redis 的位域偏移量从 0 开始，u8 表示从某个字节位置取 8 位无符号整数。

DEL member:42:score
BITFIELD member:42:score SET u8 #0 254
BITFIELD member:42:score INCRBY u8 #0 1
BITFIELD member:42:score INCRBY u8 #0 1
BITFIELD member:42:score GET u8 #0

在默认的 WRAP 策略下，前两次加法会得到 255 和 0。最后一次查询也会得到 0。命令没有报错，所以如果只记录“写入成功”，就很难发现积分已经回到了起点。

位宽先怎么算：u8、i8 不是同一种积分字段

无符号字段 uN 的范围是 0 到 2^N-1；有符号字段 iN 的范围是 -2^(N-1) 到 2^(N-1)-1。积分通常不需要负数，但撤销积分、补偿扣减会让增量出现负值，这时更要先定清楚业务含义。

例如，月度签到最多 31 次，u8 够用；如果把年度积分上限设为 10000，至少要 14 位，因为 13 位只能到 8191。字段不是按“常见整数类型”随手选的，应该按“最大合法值 + 预留空间”推导。

# 无符号 8 位：最大 255
BITFIELD member:42:score SET u8 #0 200
BITFIELD member:42:score GET u8 #0

# 有符号 8 位：最大 127，最小 -128
DEL member:42:delta
BITFIELD member:42:delta SET i8 #0 127
BITFIELD member:42:delta INCRBY i8 #0 1

第二段如果仍使用默认回绕，127 加 1 会得到 -128。这里别急着把字段改成更宽；先确认业务是否真的需要负值，以及数据迁移时旧字段如何解释。

OVERFLOW 三种策略：回绕、封顶和拒绝

BITFIELD 的溢出策略可以放在具体的 INCRBY 前面。它只影响后面的子命令，不会自动改变整个 key 的规则。

DEL score:wrap score:sat score:fail

# WRAP：超过范围后按位宽回绕
BITFIELD score:wrap SET u8 #0 255 INCRBY u8 #0 1

# SAT：超过范围后停在边界
BITFIELD score:sat SET u8 #0 255 OVERFLOW SAT INCRBY u8 #0 1

# FAIL：超过范围时拒绝本次修改
BITFIELD score:fail SET u8 #0 255 OVERFLOW FAIL INCRBY u8 #0 1

三组命令的返回结果分别体现了三种语义：回绕得到 0，封顶仍是 255，拒绝则返回空值。FAIL 的空值不是“积分变成空”，而是本次子命令没有修改字段；应用层必须把它当成明确的业务失败分支。

把命令放进业务代码前，先做四个边界检查

检查一：空 key 和字段初始值

对不存在的 key 做 GET u8 #0 会得到 0。这个默认值适合计数器初始化，但不代表字段已经完成业务登记。若 key 还承担用户状态，建议把“首次创建”和“积分为 0”分开记录，避免误把缺失数据当成有效账户。

检查二：成功返回与最终读取

INCRBY 返回的是修改后的字段值。使用 FAIL 时要检查数组里的空值；批量子命令中，前面的修改可能成功，后面的某个字段可能失败，不要把整条返回数组压缩成一个布尔值。

检查三：负增量和并发扣减

积分补偿常用正增量，撤销则可能是负增量。无符号字段遇到负增量时要单独测试；如果业务要求“低于 0 就拒绝”，位域本身只负责数值边界，跨字段的业务校验应在事务脚本或服务层完成。

检查四：读写类型必须完全一致

写入用 u12，读取却用 u8，得到的只是另一个解释方式。把类型和偏移量放在一个常量表里，代码评审时同时检查写入、增加和读取三处，别让魔法字符串散落在多个函数中。

一套可重复的验收命令

下面的检查不依赖线上业务 key，适合放进发布前脚本。每次先清理测试 key，再验证上限、封顶和拒绝。

DEL qa:bitfield
BITFIELD qa:bitfield SET u8 #0 254
BITFIELD qa:bitfield OVERFLOW FAIL INCRBY u8 #0 1
BITFIELD qa:bitfield OVERFLOW FAIL INCRBY u8 #0 1
BITFIELD qa:bitfield GET u8 #0

DEL qa:bitfield:sat
BITFIELD qa:bitfield:sat SET u8 #0 255
BITFIELD qa:bitfield:sat OVERFLOW SAT INCRBY u8 #0 1
BITFIELD qa:bitfield:sat GET u8 #0

验收重点有三个：第一次增加到 255 是否成功；第二次增加是否返回空且数值仍为 255；封顶策略是否没有把结果回绕到 0。Redis 客户端如果把空值转换成 0，必须在适配层保留“拒绝”状态，否则监控会把失败误报成正常的零值。

常见问题

BITFIELD 适合存所有用户积分吗？

不适合。它适合字段数量固定、范围明确的小整数；需要审计流水、跨用户查询、按时间统计或频繁调整上限时，普通 Hash、关系表或专门的流水表更容易维护。

积分字段应该用 WRAP 还是 SAT？

周期计数如果明确允许回到 0，可以用 WRAP；累计积分通常至少要 SAT 或 FAIL。不能只按存储空间决定，要按超限后的业务动作决定。

FAIL 返回空值后，是否需要再查一次？

需要根据接口契约决定。若应用必须返回当前积分，拒绝后再 GET 一次可以补齐结果；若只是判断是否允许增加，直接把空值映射为“达到上限”即可，但不能静默映射为成功。

换成更宽的位域就不会溢出了吗？

只能推迟溢出，不能消除它。更宽字段仍需要明确上限、负值规则和迁移方式，并继续保留边界测试。

把溢出当成业务状态，而不是偶发异常

Redis 位域节省的是表示空间和访问路径，付出的代价是类型、偏移量和溢出语义都要由应用维护。对积分这类不能悄悄回绕的数据，建议固定字段定义，默认使用 FAIL 或 SAT，在监控中单独统计拒绝次数，并把边界命令纳入发布验收。