跳到主要内容

列表

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

前言​

Redis 文档

一、llen​

1.1 认识​

llen 方法用于获取 Redis list 类型的 key 的长度，对应 Redis 的 LLEN 命令。

1.2 语法​

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

  • key: RedisKey —— 要查询的 Redis 列表 key。

  • callback?: Callback<number> —— 可选的回调函数，如果提供了，则会以 回调风格 (err, result) 方式返回结果，否则返回一个 Promise<number>。

  • 返回值:

    • Promise<number>：如果不使用回调，则返回一个 Promise，解析为 list 的长度。

    • callback 方式: 如果传入 callback，则在回调函数中接收 (err, result)。

二、lset​

2.1 认识​

lset key index newValue 对应 Redis 的 LSET 命令，用于设置 Redis list 中指定索引位置的值。

2.2 语法​

lset(key: RedisKey, index: string | number, element: string | number | Buffer, callback?: Callback<"OK">): Promise<"OK">

  • key: RedisKey —— 目标 list 类型的 Redis key。

  • index: string | number —— 列表的索引（从 0 开始，支持负数，-1 代表最后一个元素）。

  • element: string d| number | Buffer —— 要替换的新值，必须是字符串、数字或 Buffer。

  • callback?: Callback<"OK"> —— 可选回调函数 (err, result) => void，如果提供了，则会以回调风格返回 OK，否则返回 Promise<"OK">。

  • 返回值:

    • Promise<"OK">: 如果不使用回调，则返回一个 Promise，解析后值为 OK。

    • callback 方式: 如果传入 callback，则在回调函数中接收 (err, result)，成功时 result 为 OK。

三、lpop​

3.1 认识​

lpop <key>: 用于从 Redis list 的左侧弹出一个或多个元素。

3.2 语法​

// 弹出一个元素
lpop(key: RedisKey, callback?: Callback<string>): Promise<string>

// 弹出多个元素（Redis 6.2+）
lpop(key: RedisKey, count: string | number, callback?: Callback<string[]>): Promise<string[]>

  • key: RedisKey —— 目标 list 类型的 Redis key。

  • count?: string | number（可选，Redis 6.2+ 支持）—— 需要弹出的元素数量：

    • 如果不传 count，默认弹出 1 个元素。

    • 如果传 count，最多弹出 count 个元素（返回数组）。

  • callback? —— 可选的回调函数 (err, result) => void：

    • 当 count 未提供时，result 是一个 string（弹出的单个元素）。

    • 当 count 提供时，result 是一个 string[]（弹出的多个元素）。

  • 返回值:

    • Promise<string>,（当 count 未提供时）：返回被弹出的单个元素，如果 key 不存在 或 list 为空，返回 null。

    • Promise<string[]>, （当 count 提供时）：返回一个 数组，如果 key 不存在 或 list 为空，返回 []。

    • callback 方式：如果传入 callback，返回值会作为 result 传入回调。

四、rpop​

4.1 认识​

rpop 是 ioredis 提供的一个方法，对应 Redis 的 RPOP 命令。用于从 Redis list 的右侧（末尾）弹出一个或多个元素。

4.2 语法​

// 弹出一个元素
rpop(key: RedisKey, callback?: Callback<string>): Promise<string>

// 弹出多个元素（Redis 6.2+）
rpop(key: RedisKey, count: string | number, callback?: Callback<string[]>): Promise<string[]>

  • key: RedisKey: —— 目标 list 类型的 Redis key。

  • count?: string | number（可选，Redis 6.2+ 支持）

    • 如果不传 count，默认弹出 1 个元素，返回 string。

    • 如果传 count，最多弹出 count 个元素，返回 string[]。

  • callback?: —— 可选的回调函数 (err, result) => void

    • 当 count 未提供时，result 是 string（弹出的单个元素）。

    • 当 count 提供时，result 是 string[]（弹出的多个元素）。

  • 返回值:

    • Promise<string>（当 count 未提供时）, 返回被弹出的单个元素，如果 key 不存在 或 list 为空，返回 null。

    • Promise<string[]>（当 count 提供时）, 返回一个 数组，如果 key 不存在 或 list 为空，返回 []。

    • callback 方式：如果传入 callback，返回值会作为 result 传入回调。

五、lrem​

5.1 认识​

lrem key count value 根据 count 值, 从列表中删除所有 value 相等的项

  1. count > 0: 从左到右, 删除最多 count 个 value 相等的项

  2. count < 0: 从右到左, 删除最多 Math.abs(count) 个 value 相等的项

  3. count = 0: 删除所有 value 相等的项

5.2 语法​

lrem(key: RedisKey, count: string | number, element: string | number | Buffer, callback?: Callback<number>): Promise<number>

  • key: RedisKey —— 目标 list 类型的 Redis key。

  • count: string | number —— 删除的元素数量：

    • count > 0：从 左到右 删除最多 count 个匹配的 element。

    • count < 0：从 右到左 删除最多 |count| 个匹配的 element。

    • count = 0：删除 所有 匹配的 element。

  • element: string | number | Buffer —— 需要删除的目标元素，必须是字符串、数字或 Buffer。

  • callback?: Callback<number> —— 可选回调 (err, result) => void，result 是删除的元素数量。

  • 返回值:

    • Promise<number>, 返回被删除的元素数量。如果 key 不存在，返回 0（不会报错）。如果 key 存在但没有匹配的 element，返回 0。

    • callback 方式：如果传入 callback，删除的数量作为 result 传入回调。

六、lpush​

6.1 认识​

lpush 是 ioredis 提供的方法，对应 Redis 的 LPUSH 命令，用于将一个或多个元素插入到 Redis list 的左侧（开头）。

6.2 语法​

// 使用回调方式
lpush(
  ...args: [key: RedisKey, ...elements: (string | number | Buffer)[], callback: Callback<number>]
): Promise<number>

// 使用 Promise 方式
lpush(
  ...args: [key: RedisKey, ...elements: (string | number | Buffer)[]]
): Promise<number>

  • key: RedisKey —— 目标 list 类型的 Redis key。

  • ...elements: (string | number | Buffer)[] —— 需要插入的一个或多个元素, 多个元素时，按从右到左的顺序依次插入（最后一个元素最先进入 list）。

  • callback?: Callback<number> —— 可选的回调 (err, result) => void，result 是插入后的 list 长度。

  • 返回值:

    • Promise<number>, 返回插入后的 list 长度。

    • callback 方式, 如果传入 callback，返回值会作为 result 传入回调。

七、rpush​

7.1 认识​

rpush 是 ioredis 提供的方法，对应 Redis 的 RPUSH 命令，用于将一个或多个元素插入到 Redis list 的右侧（末尾）。

7.2 语法​

// 使用回调方式
rpush(
  ...args: [key: RedisKey, ...elements: (string | number | Buffer)[], callback: Callback<number>]
): Promise<number>

// 使用 Promise 方式
rpush(
  ...args: [key: RedisKey, ...elements: (string | number | Buffer)[]]
): Promise<number>

  • key: RedisKey —— 目标 list 类型的 Redis key。

  • ...elements: (string | number | Buffer)[] —— 需要插入的一个或多个 元素, 多个元素时，按 从左到右 的顺序依次插入（第一个元素最先进入 list）。

  • callback?: Callback<number> —— 可选的回调 (err, result) => void，result 是插入后的 list 长度。

  • 返回值:

    • Promise<number>: 返回插入后的 list 长度。

    • callback 方式: 如果传入 callback，返回值会作为 result 传入回调。

八、ltrim​

8.1 认识​

ltrim 是 ioredis 提供的方法，对应 Redis 的 LTRIM 命令，用于对 Redis list 进行裁剪，仅保留指定范围内的元素，删除范围外的元素。

8.2 语法​

ltrim(key: RedisKey, start: string | number, stop: string | number, callback?: Callback<"OK">): Promise<"OK">

  • key: RedisKey —— 目标 list 类型的 Redis key。

  • start: string | number —— 起始索引（包含 start 索引的元素）。

  • stop: string | number —— 结束索引（包含 stop 索引的元素）。

  • callback?: Callback<"OK"> —— 可选的回调 (err, result) => void，result 始终是 OK。

  • 返回值:

    • Promise<"OK"> —— 返回 OK，表示成功裁剪 list。

    • callback 方式：如果传入 callback，返回值 OK 会作为 result 传入回调。

九、lindex​

9.1 认识​

lindex 是 ioredis 提供的方法，对应 Redis 的 LINDEX 命令，用于获取 Redis list 中指定索引的元素。

9.2 语法​

lindex(key: RedisKey, index: string | number, callback?: Callback<string>): Promise<string>

  • key: RedisKey —— 目标 list 类型的 Redis key。

  • index: string | number —— 需要获取的元素索引,

    • 索引从 0 开始，例如：0 表示 第一个元素。1 表示 第二个元素。

    • 支持负索引, -1 表示 最后一个元素。-2 表示 倒数第二个元素。

  • callback?: Callback<string> —— 可选的回调 (err, result) => void，result 是索引对应的值（如果索引超出范围，则返回 null）。

  • 返回值:

    • Promise<string | null>, 如果索引有效，返回该索引对应的元素值。如果索引超出范围，返回 null。

    • callback 方式：如果传入 callback，返回值会作为 result 传入回调。

十、lrange​

10.1 认识​

lrange 是 ioredis 提供的方法，对应 Redis 的 LRANGE 命令，用于获取 Redis list 中指定范围内的元素。

10.2 语法​

lrange(key: RedisKey, start: string | number, stop: string | number, callback?: Callback<string[]>): Promise<string[]>

  • key: RedisKey —— 目标 list 类型的 Redis key。

  • start: string | number —— 起始索引（包含 start 索引的元素）。

  • stop: string | number —— 结束索引（包含 stop 索引的元素）。

  • callback?: Callback<string[]> —— 可选的回调 (err, result) => void，result 是指定范围内的元素数组。

十一、blpop​

11.1 认识​

blpop 是 ioredis 提供的方法，对应 Redis 的 BLPOP 命令，用于阻塞式弹出（pop）一个 list 中的元素。它会从一个或多个 list 中弹出最左边（即队列头部）的元素，直到其中一个 list 非空，或者超时。

11.2 语法​

// 使用回调方式
blpop(
  ...args: [...keys: RedisKey[], timeout: string | number, callback: Callback<[string, string]>]
): Promise<[string, string]>

// 或者不使用回调
blpop(
  ...args: [keys: RedisKey[], timeout: string | number]
): Promise<[string, string]>

  • keys: RedisKey[] —— 需要监听的 一个或多个 list 的 key。blpop 会从这些 list 中弹出元素，直到有一个 list 有元素可以弹出。

  • timeout: string | number —— 超时时间（秒），表示等待的最长时间。如果超时仍没有元素被弹出，blpop 返回 null。

  • 可选回调方式: callback?: Callback<[string, string]>``：如果传入回调函数，它会在操作完成后执行，result 是一个数组，包含了被弹出元素的 key 和元素值。

  • 返回值:

    • Promise<[string, string]>: 如果有元素被弹出，返回一个包含两个值的数组: 第一个元素是弹出元素所在的 list 的 key, 第二个元素是被弹出的 value。如果超时且没有元素弹出，返回 null。

    • callback 方式: 如果传入 callback，返回值会作为 result 传入回调。

十二、brpop​

12.1 认识​

brpop 是 ioredis 提供的方法，对应 Redis 的 BRPOP 命令，用于阻塞式弹出（pop）一个 list 中的元素，不过与 blpop 不同的是，brpop 是从 list 的右端（即队列尾部）弹出元素。

12.2 语法​

// 使用回调方式
brpop(
  ...args: [...keys: RedisKey[], timeout: string | number, callback: Callback<[string, string]>]
): Promise<[string, string]>

// 或者不使用回调
brpop(
  ...args: [keys: RedisKey[], timeout: string | number]
): Promise<[string, string]>

  • keys: RedisKey[] —— 需要监听的 一个或多个 list 的 key。brpop 会从这些 list 中弹出元素，直到有一个 list 非空，或者超时。

  • timeout: string | number —— 超时时间（秒），表示等待的最长时间。如果超时仍没有元素被弹出，brpop 返回 null。

  • 可选回调方式: callback?: Callback<[string, string]>：如果传入回调函数，它会在操作完成后执行，result 是一个数组，包含了被弹出元素的 key 和元素值。

  • 返回值:

    • Promise<[string, string]>, 如果有元素被弹出，返回一个包含两个值的数组, 第一个元素是弹出元素所在的 list 的 key。第二个元素是被弹出的 value。如果超时且没有元素弹出，返回 null。

    • callback 方式, 如果传入 callback，返回值会作为 result 传入回调。

十三、linsert​

13.1 认识​

linsert 是 ioredis 提供的一个方法，对应 Redis 的 LINSERT 命令，用于在列表中插入一个元素，可以选择将元素插入到指定基准元素的 前面（BEFORE）或者 后面（AFTER）。

13.2 语法​

linsert(key: RedisKey, before: "BEFORE", pivot: string | number | Buffer, element: string | number | Buffer, callback?: Callback<number>): Promise<number>
linsert(key: RedisKey, after: "AFTER", pivot: string | number | Buffer, element: string | number | Buffer, callback?: Callback<number>): Promise<number>

  • key: RedisKey —— 目标 list 的 key。

  • before: BEFORE 或 after, AFTER —— 插入位置的选择：

    • BEFORE：将元素插入到 pivot 元素的前面。

    • AFTER：将元素插入到 pivot 元素的后面。

  • pivot: string | number | Buffer —— 基准元素，插入的目标元素将会相对于该元素的位置进行插入。

  • element: string | number | Buffer —— 要插入的元素，它会被插入到基准元素的前面或后面。

  • 可选回调方式：callback?: Callback<number>：如果传入回调函数，result 是插入后列表的长度。

  • 返回值:

    • Promise<number>：返回插入操作后的 列表长度。

    • callback 方式: 如果传入回调函数，result 会作为 number 类型的列表长度传入回调。