Redis SETRANGE 怎样按偏移更新字符串片段

如果你需要更新 Redis 字符串中间的一段内容，SETRANGE key offset value 就是针对这个任务的命令。它从零基偏移开始覆盖指定长度的字符串；key 不存在时按空字符串处理，offset 超过当前长度时会用零字节补齐，返回值是修改后的字符串长度。

官方地址：https://redis.io/docs/latest/commands/setrange/

实际使用时先确认 offset 是字节偏移而不是“第几个中文字符”，再根据返回长度判断写入是否越过了原字符串尾部。

本文只讲固定偏移写入、补零和客户端处理，不把 SETRANGE 当作位图命令，也不展开业务分片设计。

SETRANGE 先看清三个参数

命令的语法是 SETRANGE key offset value。offset 从 0 开始，value 会覆盖从该位置开始的连续字节；覆盖不会额外插入一段内容，所以原字符串的后续字节仍按位置保留。

# 先准备一个 11 字节的字符串，从偏移 6 开始覆盖
redis-cli SET key1 "Hello World"
redis-cli SETRANGE key1 6 "Redis"

# 返回 11，表示修改后的字符串总长度
redis-cli GET key1

上面的覆盖结果是 Hello Redis。如果把 offset 看成插入位置，就会误以为原内容会整体后移；SETRANGE 的语义是原地覆盖，不是插入。

偏移超过长度时为什么会出现零字节

当 offset 大于当前字符串长度，Redis 会先把中间缺口补成零字节，再写入 value。例如空 key 上执行 SETRANGE key2 6 "Redis"，返回长度是 11，前 6 个位置不是可见字符，而是 \x00。

# key2 不存在时按空字符串处理，offset 6 会留下 6 个零字节
redis-cli SETRANGE key2 6 "Redis"

# STRLEN 只返回长度；GET 可能把零字节显示成转义形式
redis-cli STRLEN key2
redis-cli GET key2

因此返回长度可按 max(原长度, offset + value长度) 来理解。offset 越大，首次扩容需要分配的中间空间越多；不要用超大偏移把 SETRANGE 当作廉价的稀疏存储。

旧代码迁移时要改正两个判断

第一，offset 是字节位置。Redis 字符串可以保存二进制数据，中文在 UTF-8 中通常占多个字节，所以不要把 Go 的 rune 下标直接传给 SETRANGE。要按协议字段写入时，先明确字段长度单位。

第二，客户端要读取返回长度并处理错误。下面的 go-redis 示例只展示调用关系，不代表本机已经执行；重点是把返回值保留下来，便于记录最终长度和排查偏移计算错误。

package main

import (
    "context"
    "fmt"

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

func updateSegment(ctx context.Context, rdb *redis.Client) error {
    // offset 按字节计数；写入后返回修改后的字符串总长度。
    length, err := rdb.SetRange(ctx, "profile:slot", 6, "Redis").Result()
    if err != nil {
        // 网络错误或 key 类型不匹配都要交给调用方处理。
        return fmt.Errorf("setrange profile:slot: %w", err)
    }

    // 这里的 length 可用于记录结果或与预期边界比较。
    fmt.Printf("updated string length: %d\\n", length)
    return nil
}

Redis 文档还限制了可设置的最大 offset；字符串本身有大小上限。对大块写入，先估算最终长度并观察首次分配是否会阻塞服务，必要时拆分 key，而不是只看命令复杂度的 O(1) 表述。

最小复查：只核对长度和目标片段

迁移完成后可以用 STRLEN 检查总长度，用 GETRANGE 读取目标区间。若数据可能含零字节，不要依赖终端显示来判断内容，改用应用层的字节序列或十六进制表示。

# 复查总长度，再读取覆盖区域附近的字节
redis-cli STRLEN profile:slot
redis-cli GETRANGE profile:slot 0 16

结论可以压缩成三点：offset 在范围内是覆盖，超出范围会补零；返回值是最终长度；offset 和长度都按字节理解。只要这三点与调用方的索引单位一致，SETRANGE 就适合做定长字符串或二进制片段的局部更新。

相关问题

SETRANGE 会插入内容吗？不会，它覆盖从 offset 开始的已有字节，value 结束后的原内容不会因为这次调用整体后移。

key 不存在能直接使用吗？可以，Redis 把不存在的 key 当作空字符串，再按 offset 写入；如果 offset 大于 0，中间会出现零字节。

为什么中文 offset 容易算错？Redis 按字节定位，而不是按 Unicode 字符定位；应先确定编码和字节长度，再计算偏移。