当前位置：首页 > 文章列表 > 数据库 > Redis > Redis BITFIELD 怎样在字符串中读写小整数

Redis BITFIELD 怎样在字符串中读写小整数

来源：17golang原创 2026-10-26 21:07:27 0浏览收藏

当一个 Redis String 里需要同时保存状态位、小计数器和短范围数值时，BITFIELD 比手工拆字节更直接：用 i 或 u 指定有符号/无符号和位宽，用偏移定位字段，再用 GET、SET、INCRBY 完成读写。官方地址：https://redis.io/docs/latest/commands/bitfield/

BITFIELD 的关键不是“把数字变成二进制”这么简单，而是先固定每个字段的位宽和偏移，再明确溢出时是回绕、饱和还是失败。只要这三个约定不变，一个 String 就能稳定承载多个小整数。

字段类型：u4 表示 4 位无符号整数，i8 表示 8 位有符号整数。
字段位置：普通偏移是从 0 开始的 bit offset，带 # 的偏移会按当前位宽换算。
结果判断：一个 BITFIELD 命令可以串联多个操作，返回数组顺序与操作顺序一致。

先看懂 BITFIELD 的编码和偏移

BITFIELD 把 String 当作连续的 bit 数组。编码前缀 u 表示无符号，i 表示有符号，后面的数字就是位宽，例如 u4 的范围是 0 到 15，i8 的范围是 -128 到 127。官方文档支持的有符号编码最高为 64 位，无符号编码最高为 63 位。

Redis String 中 u4 与 i8 位字段和偏移关系的结构说明图 — 图1：BITFIELD 字段布局说明图，展示同一个 String 中的位宽与偏移关系，不是运行截图。

偏移直接写数字时，它就是零基 bit offset；如果写成 #0、#1，Redis 会把编号乘以当前编码的位宽，适合排列一组等宽字段。等宽数组优先使用 #，字段宽度不同或需要跨字段精确定位时，再使用普通 bit offset。

用三种子命令完成最小读写

GET 只读取指定字段，SET 写入并返回旧值，INCRBY 则按字段的编码做增减并返回新值。下面把一个 4 位状态计数器放在编号 0，再读取它；命令块中的注释只说明参数意图，不改变 Redis 命令语法。

# 读取编号为 0 的 4 位无符号字段；#0 会按 u4 的宽度换算位置
BITFIELD user:flags GET u4 #0

# 写入字段并返回旧值；新值 9 需要落在 u4 的范围内
BITFIELD user:flags SET u4 #0 9

# 原子增加 1，并返回增加后的字段值
BITFIELD user:flags INCRBY u4 #0 1

一个调用可以继续追加操作，返回值会按出现顺序组成数组。例如先递增一个位于 100 的有符号 5 位字段，再读取 offset 0 的无符号 4 位字段，第二个返回值不会因为第一个操作而被改写。这个顺序很适合把“更新计数器”和“读取状态”放进同一次请求里。

溢出策略决定结果是否回绕

INCRBY 和 SET 的结果是否越界，由它们前面的 OVERFLOW 决定。默认是 WRAP：无符号整数按范围回绕，有符号整数从最大值越过后回到最小值。SAT 会把结果卡在最小值或最大值；FAIL 检测到越界时不执行该操作，并在对应返回位置给出 NULL。

Redis BITFIELD 的 WRAP SAT FAIL 溢出策略结构说明图 — 图2：BITFIELD 溢出策略结构图，对比 WRAP、SAT、FAIL 的结果边界，不是运行截图。

# 让后面的增加在越界时保持 i8 最大值，而不是回绕到负数
BITFIELD metrics INCRBY i8 #0 120 OVERFLOW SAT INCRBY i8 #0 10

# 用 FAIL 让调用方从 NULL 发现越界；失败操作不会写入新值
BITFIELD metrics OVERFLOW FAIL INCRBY u4 #1 20

注意 OVERFLOW 只影响它后面的 SET 和 INCRBY，直到下一次 OVERFLOW 出现。生产代码不要只判断命令是否返回数组，还要按操作顺序检查某个位置是否为 NULL；否则 FAIL 策略的保护会被误当成普通的空结果。