SETRANGE 是什么
SETRANGE 从指定字节偏移开始覆写字符串内容，写入超出当前长度时自动用零字节补齐中间空缺，并返回修改后的总字节长度。它把字符串当成可随机寻址的字节数组，适合定长记录的原位字段更新和紧凑编码，改一个字段不必把整条记录重新写回；读片段用 GETRANGE，取长度用 STRLEN。
基本信息
| 语法 | SETRANGE key offset value |
|---|---|
| 返回值 | 修改后字符串的总字节长度 |
| 扩展行为 | offset 超出当前长度时，中间空隙补 0x00 |
| 容量上限 | 单个字符串最大 512MB |
| 权限要求 | 普通用户即可，属于写操作 |
| 配套命令 | GETRANGE 读片段，STRLEN 取总长，APPEND 追加 |
典型使用场景
- 定长记录更新：记录按固定偏移布局，改昵称只覆写对应字节区间
- 紧凑编码：多个小字段编码进一个 value，减少键数量与元数据开销
- 报文改写：解析到的二进制帧按偏移修正头部字段后原样落回
- 最小改动试验：只动一个字段、其余字节保持原样，便于二分定位问题
- 局部回填：对已存在的长 value 替换片段，避免整键重写的带宽浪费
常用写法
常用写法
redis-cli SETRANGE record:1001 0 ACME # 从 0 偏移写入 4 字节
redis-cli GETRANGE record:1001 0 3 # 读回这 4 字节核对
redis-cli SETRANGE record:1001 20 VIP # 从 20 偏移覆写状态字段
redis-cli GETRANGE record:1001 0 -1 # 取出全部内容查看布局
redis-cli STRLEN record:1001 # 校验总长度是否越界膨胀
redis-cli SETRANGE record:1001 0 '' # 空值写入，长度保持不变返回值与边界读法
| 情况 | 返回值 | 说明 |
|---|---|---|
| 正常覆写 | 修改后总长度 | 可用来校验偏移布局是否符合约定 |
| offset 超长 | offset 加 value 字节数 | 中间空隙被零字节填满，长度被动变大 |
| value 为空串 | 当前长度不变 | 相当于只探测了一次长度 |
| 键不存在 | value 的字节数 | 按空字符串起步再写入 |
SETRANGE 按字节而不是按字符操作：写 UTF-8 中文时 offset 指的是字节位置，字段边界要按字节布局算，否则会把多字节字符切开。
补位用的零字节不可见，越界写入后 GET 整个键会看到一长串不可打印内容。别用「长度等于预期」当唯一校验，越界时要修正偏移计算并回收异常键。