跳到主要内容

字符串

2025年01月10日
柏拉文
越努力，越幸运

前言​

Redis 文档

一、set​

1.1 认识​

set <key> <value>: 设置键的值。

1.2 语法​

set(key: RedisKey, value: string | number | Buffer, callback?: Callback<"OK">): Promise<"OK">
set(key: RedisKey, value: string | number | Buffer, get: "GET", callback?: Callback<string>): Promise<string>
set(key: RedisKey, value: string | number | Buffer, nx: "NX", callback?: Callback<"OK">): Promise<"OK">
set(key: RedisKey, value: string | number | Buffer, nx: "NX", get: "GET", callback?: Callback<string>): Promise<string>
set(key: RedisKey, value: string | number | Buffer, xx: "XX", callback?: Callback<"OK">): Promise<"OK">
set(key: RedisKey, value: string | number | Buffer, xx: "XX", get: "GET", callback?: Callback<string>): Promise<string>
set(key: RedisKey, value: string | number | Buffer, secondsToken: "EX", seconds: string | number, callback?: Callback<"OK">): Promise<"OK">
set(key: RedisKey, value: string | number | Buffer, secondsToken: "EX", seconds: string | number, get: "GET", callback?: Callback<string>): Promise<string>
set(key: RedisKey, value: string | number | Buffer, secondsToken: "EX", seconds: string | number, nx: "NX", callback?: Callback<"OK">): Promise<"OK">
set(key: RedisKey, value: string | number | Buffer, secondsToken: "EX", seconds: string | number, nx: "NX", get: "GET", callback?: Callback<string>): Promise<string>
set(key: RedisKey, value: string | number | Buffer, secondsToken: "EX", seconds: string | number, xx: "XX", callback?: Callback<"OK">): Promise<"OK">
set(key: RedisKey, value: string | number | Buffer, secondsToken: "EX", seconds: string | number, xx: "XX", get: "GET", callback?: Callback<string>): Promise<string>
set(key: RedisKey, value: string | number | Buffer, millisecondsToken: "PX", milliseconds: string | number, callback?: Callback<"OK">): Promise<"OK">
set(key: RedisKey, value: string | number | Buffer, millisecondsToken: "PX", milliseconds: string | number, get: "GET", callback?: Callback<string>): Promise<string>
set(key: RedisKey, value: string | number | Buffer, millisecondsToken: "PX", milliseconds: string | number, nx: "NX", callback?: Callback<"OK">): Promise<"OK">
set(key: RedisKey, value: string | number | Buffer, millisecondsToken: "PX", milliseconds: string | number, nx: "NX", get: "GET", callback?: Callback<string>): Promise<string>
set(key: RedisKey, value: string | number | Buffer, millisecondsToken: "PX", milliseconds: string | number, xx: "XX", callback?: Callback<"OK">): Promise<"OK">
set(key: RedisKey, value: string | number | Buffer, millisecondsToken: "PX", milliseconds: string | number, xx: "XX", get: "GET", callback?: Callback<string>): Promise<string>
set(key: RedisKey, value: string | number | Buffer, unixTimeSecondsToken: "EXAT", unixTimeSeconds: string | number, callback?: Callback<"OK">): Promise<"OK">
set(key: RedisKey, value: string | number | Buffer, unixTimeSecondsToken: "EXAT", unixTimeSeconds: string | number, get: "GET", callback?: Callback<string>): Promise<string>
set(key: RedisKey, value: string | number | Buffer, unixTimeSecondsToken: "EXAT", unixTimeSeconds: string | number, nx: "NX", callback?: Callback<"OK">): Promise<"OK">
set(key: RedisKey, value: string | number | Buffer, unixTimeSecondsToken: "EXAT", unixTimeSeconds: string | number, nx: "NX", get: "GET", callback?: Callback<string>): Promise<string>
set(key: RedisKey, value: string | number | Buffer, unixTimeSecondsToken: "EXAT", unixTimeSeconds: string | number, xx: "XX", callback?: Callback<"OK">): Promise<"OK">
set(key: RedisKey, value: string | number | Buffer, unixTimeSecondsToken: "EXAT", unixTimeSeconds: string | number, xx: "XX", get: "GET", callback?: Callback<string>): Promise<string>
set(key: RedisKey, value: string | number | Buffer, unixTimeMillisecondsToken: "PXAT", unixTimeMilliseconds: string | number, callback?: Callback<"OK">): Promise<"OK">
set(key: RedisKey, value: string | number | Buffer, unixTimeMillisecondsToken: "PXAT", unixTimeMilliseconds: string | number, get: "GET", callback?: Callback<string>): Promise<string>
set(key: RedisKey, value: string | number | Buffer, unixTimeMillisecondsToken: "PXAT", unixTimeMilliseconds: string | number, nx: "NX", callback?: Callback<"OK">): Promise<"OK">
set(key: RedisKey, value: string | number | Buffer, unixTimeMillisecondsToken: "PXAT", unixTimeMilliseconds: string | number, nx: "NX", get: "GET", callback?: Callback<string>): Promise<string>
set(key: RedisKey, value: string | number | Buffer, unixTimeMillisecondsToken: "PXAT", unixTimeMilliseconds: string | number, xx: "XX", callback?: Callback<"OK">): Promise<"OK">
set(key: RedisKey, value: string | number | Buffer, unixTimeMillisecondsToken: "PXAT", unixTimeMilliseconds: string | number, xx: "XX", get: "GET", callback?: Callback<string>): Promise<string>
set(key: RedisKey, value: string | number | Buffer, keepttl: "KEEPTTL", callback?: Callback<"OK">): Promise<"OK">
set(key: RedisKey, value: string | number | Buffer, keepttl: "KEEPTTL", get: "GET", callback?: Callback<string>): Promise<string>
set(key: RedisKey, value: string | number | Buffer, keepttl: "KEEPTTL", nx: "NX", callback?: Callback<"OK">): Promise<"OK">
set(key: RedisKey, value: string | number | Buffer, keepttl: "KEEPTTL", nx: "NX", get: "GET", callback?: Callback<string>): Promise<string>
set(key: RedisKey, value: string | number | Buffer, keepttl: "KEEPTTL", xx: "XX", callback?: Callback<"OK">): Promise<"OK">
set(key: RedisKey, value: string | number | Buffer, keepttl: "KEEPTTL", xx: "XX", get: "GET", callback?: Callback<string>): Promise<string>

必填参数:

  • key: RedisKey: 这是 Redis 中存储数据的键。它是一个标识符，用于唯一确定一个存储位置。可以使用 user:id:123 这样的键来存储用户 ID 为 123 的用户信息，其中 user:id 是一个命名空间，123 是具体的用户标识

  • value: string | number | Buffer: 表示要存储在 Redis 中的值。可以是字符串、数字或 Buffer 类型。这提供了灵活性，允许存储各种类型的数据。

    await redis.set("username", "Alice");

可选参数:

  • secondsToken: "EX": 以秒为单位设置键的过期时间。

    await redis.set("session", "data", "EX", 3600);

  • millisecondsToken: "PX": 以毫秒为单位设置键的过期时间。

    await redis.set("cache", "value", "PX", 10000);

  • nx: "NX": 仅当键不存在时才设置值（防止覆盖）。代表 Not eXists。使用这个参数时，只有当键不存在时，set 操作才会成功。这对于实现锁机制或确保某些数据的唯一性非常有用。例如，在实现分布式锁时，可以使用 nx: "NX" 来确保只有一个客户端能够成功设置锁，如果键已经存在，意味着锁已经被其他客户端持有，当前客户端的 set 操作将失败，从而避免多个客户端同时操作同一个资源。

    await redis.set("counter", 1, "NX");

  • xx: "XX": 仅当键存在时才设置值（避免新增键）。代表 eXists。与 nx 相反，只有当键已经存在时，set 操作才会成功。这可以用于更新操作，确保只对已存在的数据进行更新，而不会创建新的数据。示例：如果你想更新用户的信息，但前提是该用户信息已经存在于 Redis 中，可以使用 xx: "XX"，避免创建一个新的用户记录。

    await redis.set("counter", 2, "XX");

  • get: "GET": 使用 GET 选项，会返回设置前的旧值。当设置此参数时，set 操作会同时返回之前存储在该键上的值。这在需要更新一个键的值但又要先查看其旧值的情况下很有用，它提供了一种原子操作的方式，避免了先 get 再 set 可能导致的数据不一致问题。示例：假设你想更新一个用户的余额，你可能需要先获取旧的余额，进行计算，然后设置新的余额。使用 get: "GET" 可以在一次操作中完成这两个步骤，确保数据的一致性。

    const oldValue = await redis.set("username", "Bob", "GET");
    console.log(oldValue);  // Alice

  • unixTimeSecondsToken: "EXAT": 以 Unix 时间戳（秒）设置过期时间。

    await redis.set("event", "data", "EXAT", 1700000000);

  • unixTimeMillisecondsToken: "PXAT": 以 Unix 时间戳（毫秒）设置过期时间。

    await redis.set("token", "data", "PXAT", 1700000000000);

  • keepttl: "KEEPTTL": 保留当前键的 TTL（不覆盖过期时间）。当设置此参数时，在修改键的值时会保留原有的过期时间。这对于更新键的值但不想影响其过期时间的情况很有用，确保数据的更新不会影响其生命周期管理。示例：假设你存储了一个带有 30 分钟过期时间的缓存项，在更新其内容时，使用 keepttl: "KEEPTTL" 可以保持 30 分钟的过期时间不变，避免重新设置过期时间可能导致的不一致或错误。

    await redis.set("session", "newValue", "KEEPTTL");

  • seconds: string | number: 过期时间，字符串或数字。

  • milliseconds: string | number: 是具体的毫秒数。这在需要更精确的时间控制时使用。

  • unixTimeSeconds: string | number: 是 Unix 时间戳的秒数。这允许你精确地设置键在某个具体的未来时间点过期。

  • unixTimeMilliseconds: string | number: 使用的是 Unix 时间戳的毫秒数，提供了更精确的时间控制。

  • callback?: Callback<"OK">: 这是一个可选的回调函数，当 set 操作完成后会调用。它的类型是 Callback<"OK">，通常表示操作成功时的回调，一般会接收到 OK 作为结果。在异步编程中，这个回调函数可以用来处理操作完成后的后续逻辑，比如确认数据是否成功存储，或者根据存储结果进行下一步操作。

    function handleSetResult(result) {
        if (result === 'OK') {
            console.log('数据存储成功');
        } else {
            console.error('数据存储失败');
        }
    }
    client.set('key', 'value', handleSetResult);

二、get​

2.1 认识​

get <key>: 获取键的值。

2.2 语法​

get(key: RedisKey, callback?: Callback<string>): Promise<string>

三、mset​

3.1 认识​

mset 是 Redis 提供的一个命令，用于一次性设置多个键值对。它的主要优势是原子性，即所有键值对要么同时设置成功，要么都不会设置，从而避免部分数据更新的问题。mset 适用于需要一次性初始化或更新多个键值对时，可以使用 mset, 保证一致性：确保多个键值对同时更新，避免单独设置每个键时可能发生的中途失败。mset 如果某些键已经存在，mset 将直接覆盖它们的值。如果键不存在，mset 会创建新的键值对。使用 mset 减少与 Redis 的交互次数 (网络请求次数 + 命令次数)，提升应用响应速度。

3.2 语法​

mset(object: object, callback?: Callback<"OK">): Promise<"OK">
mset(map: Map<string | number | Buffer, string | number | Buffer>, callback?: Callback<"OK">): Promise<"OK">
mset(...args: [...keyValues: (number | RedisKey)[], callback: Callback<"OK">]): Promise<"OK">
mset(...args: (number | RedisKey)[]): Promise<"OK">

  • object: 对象形式, 传入一个对象，键为 Redis key，值为对应的 value。

    await redis.mset({ key1: "value1", key2: "value2" });

  • map: Map 形式, 传入一个 Map 类型，允许键值对以更灵活的方式存储。适合键值可能包含 Buffer 数据的情况。

    const data = new Map();
    data.set("user:1", "Alice");
    data.set("user:2", "Bob");
    await redis.mset(data);

  • ...args: [...keyValues: (number | RedisKey)[], callback?: Callback<"OK">]: 扁平化参数, 传入一系列的键和值作为参数，每两个元素组成一对。适合直接写明具体键值的情况。

    await redis.mset("key1", "value1", "key2", "value2", "key3", "value3");

  • callback?: Callback<"OK">: 可选回调, 采用 Node.js 的回调风格，处理异步结果。如果不提供回调，返回 Promise<"OK">。

    redis.mset("key1", "value1", "key2", "value2", (err, result) => {
        if (err) console.error("发生错误:", err);
        else console.log("操作成功:", result);
    });

  • 返回值: 返回一个 Promise<string>，如果操作成功，解析值为 "OK"。

3.3 用法​

四、mget​

4.1 认识​

mget 方法用于批量获取多个键的值，对应于 Redis 的 MGET 命令。该方法允许一次性从 Redis 读取多个键的值，而不必单独执行多个 get 操作，提高了读取效率。使用 mget 减少与 Redis 的交互次数 (网络请求次数 + 命令次数)，提升应用响应速度。

4.2 语法​

mget(...args: [...keys: RedisKey[], callback: Callback<string[]>]): Promise<string[]>
mget(...args: [keys: RedisKey[], callback: Callback<string[]>]): Promise<string[]>
mget(...args: RedisKey[]): Promise<string[]>
mget(...args: [keys: RedisKey[]]): Promise<string[]>

  • ...keys: RedisKey[]: 扁平化参数, 传入多个 Redis 键作为参数，直接获取对应的值。适用于简单、少量的键值查询。

    await redis.mget("key1", "key2", "key3");

  • [keys: RedisKey[]]: 数组形式, 传入一个字符串数组，数组中的每个元素是 Redis 的键。适合动态构造键的情况，比如从数据库、接口动态获取键

    const keys = ["key1", "key2", "key3"];
    await redis.mget(keys);

  • callback?: Callback<string[]>: 可选回调, 采用回调函数来异步获取结果，遵循 Node.js 风格的 (err, result)。适用于传统回调处理方式，而非 Promise。

    redis.mget(["key1", "key2"], (err, result) => {
        if (err) console.error("发生错误:", err);
        else console.log("获取的值:", result);
    });

  • 返回值: 返回一个 Promise<string[]>，解析结果为包含所有请求键的值的数组。如果某个键不存在，其对应值将为 null。

五、incr​

5.1 认识​

incr <key> 增加键的值（值必须为整数）。incr 方法用于 对指定键的值执行自增操作，类似于 Redis 的 INCR 命令。它会将存储在键（key）中的 值加 1，并返回更新后的值。

5.2 语法​

incr(key: RedisKey, callback?: Callback<number>): Promise<number>

  • key: RedisKey（必填）: 要执行自增操作的键名（字符串类型）。如果键不存在，Redis 会自动创建并初始化为 0，然后执行 +1 操作。如果该键存储的不是一个数字，则会返回错误。

  • callback?: Callback<number>（可选）: 可选的回调函数，遵循 Node.js 经典回调模式 (err, result) => {}。如果提供回调函数，方法将以异步方式运行，并将结果传递给回调函数。

  • 返回值: 返回一个 Promise<number>，解析为自增后的值。

六、decr​

6.1 认识​

decr <key> 减少键的值（值必须为整数）。decr 方法用于对指定键的值执行自减操作，类似于 Redis 的 DECR 命令。它会将存储在键（key）中的 值减 1，并返回更新后的值。

6.2 语法​

decr(key: RedisKey, callback?: Callback<number>): Promise<number>

  • key: RedisKey（必填）: 要执行自减操作的键名（字符串类型）。如果键不存在，Redis 会自动创建并初始化为 0，然后执行 -1 操作。如果该键存储的不是一个数字，则会返回错误。

  • callback?: Callback<number>（可选）: 可选的回调函数，遵循 Node.js 经典回调模式 (err, result) => {}。如果提供回调函数，方法将以异步方式运行，并将结果传递给回调函数。

  • 返回值: 返回一个 Promise<number>，解析为自减后的值。

七、incrby​

7.1 认识​

incrby 方法用于对指定键的值按给定增量执行自增操作，类似于 Redis 的 INCRBY 命令。它会将存储在键（key）中的数值增加指定的步长，并返回更新后的值。

7.2 语法​

incrby(key: RedisKey, increment: string | number, callback?: Callback<number>): Promise<number>

  • key: RedisKey（必填）: 需要执行自增操作的键名（字符串类型）。 如果键不存在，Redis 会自动创建并初始化为 0，然后执行增量操作。如果键的值不是数值类型，则会报错。

  • increment: string | number（必填）: 要增加的数值（可以是字符串形式的数字或数字类型）。支持正负整数。

  • callback?: Callback<number>（可选）: 可选的回调函数，遵循 Node.js 经典回调模式 (err, result) => {}。如果提供了回调，则以异步方式运行，并将结果传递给回调函数。

  • 返回值: 返回一个 Promise<number>，解析为增加后的值。

八、decrby​

8.1 认识​

decrby 方法用于 对指定键的值按给定减量执行自减操作，类似于 Redis 的 DECRBY 命令。它会将存储在键（key）中的数值减少指定的步长，并返回更新后的值。

8.2 语法​

decrby(key: RedisKey, decrement: string | number, callback?: Callback<number>): Promise<number>

  • key: RedisKey（必填）: 需要执行自减操作的键名（字符串类型）。如果键不存在，Redis 会自动创建并初始化为 0，然后执行递减操作。如果键的值不是数值类型，则会报错。

  • decrement: string | number（必填）: 要减少的数值（可以是字符串形式的数字或数字类型）。必须是正整数，等效于 key = key - decrement。

  • callback?: Callback<number>（可选）: 可选的回调函数，遵循 Node.js 经典回调模式 (err, result) => {}。如果提供了回调，则以异步方式运行，并将结果传递给回调函数。

  • 返回值: 返回一个 Promise<number>，解析为减少后的值。

九、getset​

9.1 认识​

getset 方法用于 设置键的值，并返回该键的旧值，对应于 Redis 的 GETSET 命令。如果键已存在，getset 会返回旧值，并将其替换为新值；如果键不存在，返回 null，并将新值存入键中。该命令常用于实现原子性的计数器重置、缓存刷新等功能。

9.2 语法​

getset(key: RedisKey, value: string | number | Buffer, callback?: Callback<string>): Promise<string>

  • key: RedisKey: 需要操作的 Redis 键。类型：string | Buffer。

  • value: string | number | Buffer: 新的值，将存储到该键中。类型：可以是 string、number 或 Buffer，非字符串的值会自动转换为字符串。

  • callback?: Callback<string | null>:（可选回调）, 采用 Node.js 风格的 (err, result) 回调函数。如果不提供回调，则返回 Promise<string | null>。

  • 返回值: Promise<string | null>, 如果键存在，返回键的旧值（字符串格式）。如果键不存在，返回 null。当使用回调方式时，返回的旧值通过回调的 result 参数返回。

十、strlen​

10.1 认识​

strlen <key>: 获取值的长度。

10.2 语法​

strlen(key: RedisKey, callback?: Callback<number>): Promise<number>

十一、append​

11.1 认识​

append <key> <value>: 向键值后追加数据。append 方法用于 将给定值追加到指定键的现有值之后，对应于 Redis 的 APPEND 命令。如果键已经存在，append 将把新值附加到现有值的末尾；如果键不存在，则会创建该键并将值存入其中。

11.2 语法​

append(key: RedisKey, value: string | number | Buffer, callback?: Callback<number>): Promise<number>

  • key: RedisKey: 需要追加内容的 Redis 键。类型：string | Buffer。

  • value: string | number | Buffer: 要追加的新值，可以是字符串、数字或二进制数据（Buffer），非字符串的值会自动转换为字符串并追加。

  • callback?: Callback<number>:（可选回调）, 采用 Node.js 风格的回调 (err, result)，其中 result 是追加后字符串的总长度。如果不提供回调，则返回 Promise<number>。

  • 返回值: Promise<number>, 返回追加操作后字符串的新长度。使用回调方式时，长度作为回调参数返回。

十二、setrange​

12.1 认识​

setrange 方法用于 设置 Redis 键值的子字符串，并在指定的偏移量位置开始写入内容，类似于 Redis 的 SETRANGE 命令。这个命令允许你通过指定一个偏移量，将新内容写入现有值的某个位置，覆盖该位置后的内容。如果偏移量大于现有字符串的长度，Redis 会用空字符填充并追加新内容。

12.2 语法​

setrange(key: RedisKey, offset: string | number, value: string | number | Buffer, callback?: Callback<number>): Promise<number>

  • key: RedisKey: 要操作的 Redis 键。类型：string | Buffer。

  • offset: string | number: 偏移量，指定从键值的哪个位置开始设置新值。这个值是一个非负整数，表示从字符串的起始位置或负数（从字符串的末尾倒数）。

  • value: string | number | Buffer: 要写入的新值，可以是字符串、数字或二进制数据（Buffer）。该值会从指定的偏移量开始写入并覆盖现有的内容。

  • callback?: Callback<number>:（可选回调） 采用 Node.js 风格的回调 (err, result)，其中 result 是新的字符串长度。如果不提供回调，则返回 Promise<number>。

  • Promise<number>: 返回设置操作后字符串的新长度。使用回调方式时，返回的新字符串长度通过回调参数返回。

十三、getrange​

13.1 认识​

getrange 方法用于 获取 Redis 键值的子字符串，对应于 Redis 的 GETRANGE 命令。你可以通过 start 和 end 索引来指定子字符串的范围，Redis 会返回该范围内的字符。

13.2 语法​

getrange(key: RedisKey, start: string | number, end: string | number, callback?: Callback<string>): Promise<string>

  • key: RedisKey: 需要获取子字符串的 Redis 键。类型：string | Buffer。

  • start: string | number: 子字符串的起始索引，可以是正整数（从字符串的开始位置开始计算）或负整数（从字符串的末尾反向计算）。

  • end: string | number: 子字符串的结束索引。类似于 start，可以是正整数或负整数。注意，Redis 将返回从 start 到 end 之间的字符（包括起始和结束位置）。

  • callback?: Callback<string>:（可选回调）采用 Node.js 风格的回调 (err, result)，其中 result 是获取的子字符串。如果不提供回调，则返回 Promise<string>。

  • 返回值: Promise<string>, 返回获取的子字符串。使用回调方式时，返回的子字符串通过回调的 result 参数返回。