Redis 序列化协议规范

Redis 序列化协议 （RESP） 是客户端实现的有线协议

为了与 Redis 服务器通信，Redis 客户端使用一种称为 Redis 序列化协议 （RESP） 的协议。 虽然该协议是专门为 Redis 设计的，但您可以将其用于其他客户端-服务器软件项目。

RESP 是以下考虑因素之间的折衷方案：

• 易于实施。
• 快速解析。
• 人类可读。

RESP 可以序列化不同的数据类型，包括整数、字符串和数组。 它还具有特定于错误的类型。 客户端以字符串数组的形式向 Redis 服务器发送请求。 数组的内容是服务器应执行的命令及其参数。 服务器的回复类型是特定于命令的。

RESP 是二进制安全的，并使用前缀长度来传输批量数据，因此它不需要处理从一个进程传输到另一个进程的批量数据。

RESP 是您应该在 Redis 客户端中实施的协议。

RESP 版本

Redis 1.2 中引入了对 RESP 协议第一个版本的支持。 将 RESP 与 Redis 1.2 一起使用是可选的，主要目的是解决协议中的问题。

在 Redis 2.0 中，该协议的下一个版本（又名 RESP2）成为客户端与 Redis 服务器的标准通信方法。

RESP3 是 RESP2 的超集，主要目的是让客户作者的生活更轻松一些。 Redis 6.0 引入了对 RESP3 功能的实验性选择加入支持（不包括流式字符串和流式聚合）。 此外，引入了HELLOcommand 允许客户端握手并升级连接的协议版本（请参阅客户端握手）。

直到 Redis 7（包括 Redis 7），RESP2 和 RESP3 客户端都可以调用所有核心命令。 但是，对于不同的协议版本，命令可能会返回不同类型的回复。

Redis 的未来版本可能会更改默认协议版本，但 RESP2 不太可能完全弃用。 但是，即将推出的版本中的新功能可能需要使用 RESP3。

网络层

客户端通过创建到其端口的 TCP 连接（默认值为 6379）来连接到 Redis 服务器。

虽然 RESP 在技术上不是特定于 TCP 的，但该协议专门用于 Redis 上下文中的 TCP 连接（或等效的面向流的连接，如 Unix 套接字）。

请求-响应模型

Redis 服务器接受由不同参数组成的命令。 然后，服务器处理命令并将回复发送回客户端。

这是最简单的模型;但是，也有一些例外：

• Redis 请求可以流水线化。 Pipelining 使客户端能够一次发送多个命令并等待稍后的回复。
• 当 RESP2 连接订阅 Pub/Sub 频道时，该协议会更改语义并成为推送协议。 客户端不再需要发送命令，因为服务器将在收到新消息后立即自动向客户端发送新消息（对于客户端订阅的通道）。
• 这MONITOR命令。 调用MONITOR命令将连接切换到 ad-hoc 推送模式。 此模式的协议未指定，但很明显易于解析。
• 保护模式。 在保护模式下，从非环回地址打开到 Redis 的连接将被拒绝并被服务器终止。 在终止连接之前，Redis 会无条件地发送-DENIED回复，无论客户端是否写入套接字。
• RESP3 Push 类型。 顾名思义，推送类型允许服务器将带外数据发送到连接。 服务器可以随时推送数据，数据不一定与客户端执行的特定命令相关。

排除这些例外情况，Redis 协议是一个简单的请求-响应协议。

RESP 协议说明

RESP 本质上是一种支持多种数据类型的序列化协议。 在 RESP 中，data 的第一个字节确定其类型。

Redis 通常使用 RESP 作为请求-响应协议，具体如下：

• 客户端将命令作为批量字符串数组发送到 Redis 服务器。 数组中的第一个（有时也是第二个）批量字符串是命令的名称。 数组的后续元素是命令的参数。
• 服务器使用 RESP 类型进行回复。 回复的类型由命令的实现决定，也可能由客户端的协议版本决定。

RESP 是一种二进制协议，它使用以标准 ASCII 编码的控制序列。 这A字符，例如，使用值 65 的二进制字节进行编码。 同样，字符 CR （\r）、LF （\n） 和 SP （） 的二进制字节值分别为 13、10 和 32。

这\r\n（CRLF） 是协议的终止符，它始终将其部分分开。

RESP 序列化负载中的第一个字节始终标识其类型。 后续字节构成类型的内容。

我们将每种 RESP 数据类型分为简单、批量或聚合。

简单类型类似于编程语言中表示纯文本值的标量。布尔值和整数就是这样的例子。

RESP 字符串可以是 simple 或 bulk。 简单字符串从不包含回车 （\r） 或换行符 （\n） 字符。 批量字符串可以包含任何二进制数据，也可以称为 binary 或 blob。 请注意，批量字符串可以由客户端进一步编码和解码，例如使用广泛的多字节编码。

聚合（如 Arrays 和 Map）可以具有不同数量的子元素和嵌套级别。

下表总结了 Redis 支持的 RESP 数据类型：

简单字符串

简单字符串编码为加号 （） 字符，后跟字符串。 字符串不得包含 CR （+\r） 或 LF （\n） 字符终止，并由 CRLF 终止（即\r\n).

简单字符串以最小的开销传输短的非二进制字符串。 例如，许多 Redis 命令在成功时只回复 “OK”。 此 Simple String 的编码为以下 5 个字节：

+OK\r\n

当 Redis 使用简单字符串进行回复时，客户端库应向调用方返回一个字符串值，该值由字符串末尾之后的第一个字符组成，不包括最终的 CRLF 字节。+

要发送二进制字符串，请改用批量字符串。

简单错误

RESP 具有特定的错误数据类型。 简单错误，或简称为错误，类似于简单字符串，但它们的第一个字符是减号 （） 字符。 RESP 中简单字符串和错误之间的区别在于，客户端应将错误视为异常，而以错误类型编码的字符串是错误消息本身。-

基本格式为：

-Error message\r\n

Redis 仅在出现问题时才会回复错误，例如，当您尝试对错误的数据类型进行作时，或者当命令不存在时。 客户端在收到 Error 回复时应引发异常。

以下是错误回复的示例：

-ERR unknown command 'asdf'
-WRONGTYPE Operation against a key holding the wrong kind of value

， 后面的第一个大写单词（直到第一个空格或换行符）表示返回的错误类型。 此词称为错误前缀。 请注意，错误前缀是 Redis 使用的约定，而不是 RESP 错误类型的一部分。-

例如，在 Redis 中，ERR是一般错误，而WRONGTYPE是一个更具体的错误，表示客户端尝试对错误的数据类型执行作。 错误前缀允许客户端了解服务器返回的错误类型，而无需检查确切的错误消息。

客户端实现可以为各种错误返回不同类型的异常，或者通过直接将错误名称作为字符串提供给调用方来提供捕获错误的通用方法。

但是，不应将此类功能视为重要功能，因为它很少有用。 此外，更简单的 Client 端实现可以返回一个通用的 error 值，例如false.

整数

此类型是以 CRLF 结尾的字符串，表示带符号的 10 基数 64 位整数。

RESP 按以下方式对整数进行编码：

:[<+|->]<value>\r\n

• 冒号 （:） 作为第一个字节。
• 可选的加号 （） 或减号 （）。+-
• 一个或多个十进制数字 （0..9） 指定为整数的无符号 10 基数值。
• CRLF 终止符。

例如:0\r\n和:1000\r\n是整数回复（分别为 0 和 1 1000）。

许多 Redis 命令返回 RESP 整数，包括INCR,LLEN和LASTSAVE. 整数本身除了在返回它的命令的上下文中之外，没有其他特殊含义。 例如，它是INCR、LASTSAVE等。 但是，返回的整数保证在有符号 64 位整数的范围内。

在某些情况下，整数可以表示 true 和 false 布尔值。 例如SISMEMBER返回 1 表示 true，返回 0 表示 false。

其他命令，包括SADD,SREM和SETNX，当数据发生变化时返回 1，否则返回 0。

批量字符串

批量字符串表示单个二进制字符串。 字符串可以是任意大小，但默认情况下，Redis 将其限制为 512 MB（请参阅proto-max-bulk-lenconfiguration 指令）。

RESP 按以下方式对批量字符串进行编码：

$<length>\r\n<data>\r\n

• 美元符号 （） 作为第一个字节。$
• 一个或多个十进制数字 （0..9） 作为字符串的长度（以字节为单位），作为无符号的 base-10 值。
• CRLF 终止符。
• 数据。
• 最终的 CRLF。

因此，字符串 “hello” 的编码方式如下：

$5\r\nhello\r\n

空字符串的编码为：

$0\r\n\r\n

Null 批量字符串

RESP3 具有 null 值的专用数据类型，而 RESP2 没有此类类型。 相反，由于历史原因，RESP2 中 null 值的表示是通过批量字符串和数组类型的预定形式。

null 批量字符串表示不存在的值。 这GETcommand 在目标键不存在时返回 Null Bulk String。

它被编码为长度为负数 1 （-1） 的批量字符串，如下所示：

$-1\r\n

当服务器使用 null 批量字符串而不是空字符串进行回复时，Redis 客户端应返回 nil 对象。 例如，Ruby 库应返回nil而 C 库应返回NULL（或在 reply 对象中设置特殊标志）。

阵 列

客户端将命令作为 RESP 数组发送到 Redis 服务器。 同样，一些返回元素集合的 Redis 命令使用数组作为其回复。 一个例子是LRANGE返回列表元素的命令。

RESP 数组的编码使用以下格式：

*<number-of-elements>\r\n<element-1>...<element-n>

• 星号 （） 作为第一个字节。*
• 一个或多个十进制数字 （0..9） 作为数组中的元素数，作为无符号的 base-10 值。
• CRLF 终止符。
• 数组的每个元素的附加 RESP 类型。

所以空 Array 就是这样：

*0\r\n

而由两个批量字符串 “hello” 和 “world” 组成的数组的编码为：

*2\r\n$5\r\nhello\r\n$5\r\nworld\r\n

如您所见，在*<count>CRLFpart 的数组前缀，则组成数组的其他数据类型将一个接一个地连接起来。 例如，一个包含三个整数的 Array 的编码如下：

*3\r\n:1\r\n:2\r\n:3\r\n

数组可以包含混合数据类型。 例如，以下编码是四个整数和一个批量字符串的列表：

*5\r\n
:1\r\n
:2\r\n
:3\r\n
:4\r\n
$5\r\n
hello\r\n

（为了便于阅读，原始 RESP 编码被分成多行）。

服务器发送的第一行是*5\r\n. 此数值告诉客户端将有五种回复类型紧随其后。 然后，每个连续的回复都构成数组中的一个元素。

所有聚合 RESP 类型都支持嵌套。 例如，包含两个数组的嵌套数组的编码如下：

*2\r\n
*3\r\n
:1\r\n
:2\r\n
:3\r\n
*2\r\n
+Hello\r\n
-World\r\n

（为了便于阅读，原始 RESP 编码被分成多行）。

上面对一个双元素数组进行编码。 第一个元素是一个数组，而该数组又包含三个整数 （1， 2， 3）。 第二个元素是另一个包含简单字符串和错误的数组。

Null 数组

RESP3 具有 null 值的专用数据类型，而 RESP2 没有此类类型。相反，由于历史原因，RESP2 中 null 值的表示是通过 Bulk Strings 和 arrays 类型的预定形式。

Null 数组是表示 Null 值的另一种方式。 例如，当BLPOP命令超时时，返回 null 数组。

空数组的编码是长度为 -1 的数组的编码，即：

*-1\r\n

当 Redis 使用 null 数组进行回复时，客户端应返回 null 对象而不是空数组。 这对于区分空列表和不同条件（例如，BLPOP命令）。

数组中的 Null 元素

数组的单个元素可以是 null 批量字符串。 这在 Redis 回复中用于表示这些元素缺失，而不是空字符串。例如，在SORT命令与GET pattern选择 如果缺少指定的键。

下面是一个包含 null 元素的数组 reply 的示例：

*3\r\n
$5\r\n
hello\r\n
$-1\r\n
$5\r\n
world\r\n

在上面，第二个元素为 null。 客户端库应向其调用方返回如下内容：

["hello",nil,"world"]

Null 值

null 数据类型表示不存在的值。

Null 的编码是下划线 （） 字符，后跟 CRLF 终止符 （_\r\n). 以下是 Null 的原始 RESP 编码：

_\r\n

#<t|f>\r\n

双打

Double RESP 类型对双精度浮点值进行编码。 双精度的编码如下：

,[<+|->]<integral>[.<fractional>][<E|e>[sign]<exponent>]\r\n

• 逗号字符 （,） 作为第一个字节。
• 可选的加号 （） 或减号 （）。+-
• 一个或多个十进制数字 （0..9） 指定为无符号的 base-10 整数值。
• 可选点 （.），后跟一个或多个十进制数字 （0..9） 指定为无符号的 10 进制小数值。
• 可选的大写或小写字母 E （E或e），后跟可选的加号 （） 或减号 （） 作为指数符号，以一个或多个十进制数字 （+-0..9） 指定为无符号的 base-10 指数值。
• CRLF 终止符。

以下是数字 1.23 的编码：

,1.23\r\n

由于小数部分是可选的，因此整数值十 （10） 可以同时作为整数和双精度进行 RESP 编码：

:10\r\n
,10\r\n

在这种情况下，Redis 客户端应分别返回本机 integer 和 double 值，前提是其实现语言支持这些类型。

正无穷大、负无穷大和 NaN 值的编码方式如下：

,inf\r\n
,-inf\r\n
,nan\r\n

大数字

此类型可以对有符号 64 位整数范围之外的整数值进行编码。

大数字使用以下编码：

([+|-]<number>\r\n

• 左括号字符 （） 作为第一个字节。(
• 可选的加号 （） 或减号 （）。+-
• 一个或多个十进制数字 （0..9） 指定为无符号的 base-10 值。
• CRLF 终止符。

例：

(3492890328409238509324850943850943825024385\r\n

大数字可以是正数或负数，但不能包含分数。 用具有 big number 类型的语言编写的 Client 端库应该返回一个 big number。 当不支持大数字时，客户端应返回一个字符串，并在可能的情况下向调用方发出信号，表明回复是一个大整数（取决于客户端库使用的 API）。

批量错误

此类型将简单错误的目的与批量字符串的表达能力相结合。

它被编码为：

!<length>\r\n<error>\r\n

• 感叹号 （!） 作为第一个字节。
• 一个或多个十进制数字 （0..9） 作为错误的长度（以字节为单位），作为无符号的 base-10 值。
• CRLF 终止符。
• 错误本身。
• 最终的 CRLF。

按照惯例，错误以传达错误消息的大写 （空格分隔） 单词开头。

例如，错误 “SYNTAX invalid syntax” 由以下协议编码表示：

!21\r\n
SYNTAX invalid syntax\r\n

（为了便于阅读，原始 RESP 编码被分成多行）。

此类型类似于批量字符串，但增加了有关数据编码的提示。

逐字字符串的 RESP 编码如下：

=<length>\r\n<encoding>:<data>\r\n

• 等号 （） 作为第一个字节。=
• 一个或多个十进制数字 （0..9） 作为字符串的总长度（以字节为单位），作为无符号的 base-10 值。
• CRLF 终止符。
• 正好三 （3） 个字节表示数据的编码。
• 冒号 （:） 字符分隔编码和数据。
• 数据。
• 最终的 CRLF。

例：

=15\r\n
txt:Some string\r\n

（为了便于阅读，原始 RESP 编码被分成多行）。

某些客户端库可能会忽略此类型和字符串类型之间的差异，并在这两种情况下返回本机字符串。 但是，交互式客户端，例如命令行界面（例如redis-cli）可以使用此类型，并且知道其输出应按原样呈现给人类用户，并且无需引用字符串。

例如，Redis 命令INFO输出包含 newlines 的报表。 使用 RESP3 时，redis-cli正确显示它，因为它是作为逐字字符串回复发送的（它的三个字节是 “txt”）。 但是，在使用 RESP2 时，redis-cli是硬编码的，以查找INFO命令来确保其正确显示给用户。

地图

RESP 映射对键值元组的集合进行编码，即字典或哈希。

它的编码方式如下：

%<number-of-entries>\r\n<key-1><value-1>...<key-n><value-n>

• 百分比字符 （） 作为第一个字节。%
• 一个或多个十进制数字 （0..9） 作为 Map 中的条目数或键值元组数，作为无符号的 base-10 值。
• CRLF 终止符。
• 映射中的每个键和值有两种额外的 RESP 类型。

例如，以下 JSON 对象：

{
    "first": 1,
    "second": 2
}

可以在 RESP 中编码，如下所示：

%2\r\n
+first\r\n
:1\r\n
+second\r\n
:2\r\n

（为了便于阅读，原始 RESP 编码被分成多行）。

映射键和值都可以是 RESP 的任何类型。

Redis 客户端应返回其语言提供的惯用字典类型。 但是，低级编程语言（例如 C）可能会返回一个数组以及类型信息，这些信息向调用方表明它是一个字典。

属性

属性类型与 Map 类型完全相同，但不是将字符作为第一个字节，%|字符。属性描述字典的方式与 Map 类型完全相同。但是，客户端不应将此类字典视为回复的一部分，而应将其视为增强回复的辅助数据。

注意：在下面的示例中，显示缩进只是为了清楚起见;额外的空格不会是实际回复的一部分。

例如，较新版本的 Redis 可能包括报告每个已执行命令的键的热门程度的功能。对命令的回复MGET a b可能如下：

|1\r\n
    +key-popularity\r\n
    %2\r\n
        $1\r\n
        a\r\n
        ,0.1923\r\n
        $1\r\n
        b\r\n
        ,0.0012\r\n
*2\r\n
    :2039123\r\n
    :9543892\r\n

实际回复MGET只是 2 项数组[2039123, 9543892].返回的属性指定请求的受欢迎程度或频率，以浮点数的形式给出，范围从0.0自1.0，原始命令中提到的键。注意：Redis 中的实际实现可能会有所不同。

当客户端读取回复并遇到属性类型时，它应该读取该属性，并继续读取回复。属性 reply 应该单独累积，并且用户应该有办法访问这些属性。例如，如果我们想象一个高级语言的会话，可能会发生这样的事情：

> r = Redis.new
#<Redis client>
> r.mget("a","b")
#<Redis reply>
> r
[2039123,9543892]
> r.attribs
{:key-popularity => {:a => 0.1923, :b => 0.0012}}

Attributes can appear anywhere before a valid part of the protocol identifying a given type, and supply information only about the part of the reply that immediately follows. For example:

*3\r\n
    :1\r\n
    :2\r\n
    |1\r\n
        +ttl\r\n
        :3600\r\n
    :3\r\n

~<number-of-elements>\r\n<element-1>...<element-n>

><number-of-elements>\r\n<element-1>...<element-n>

HELLO <protocol-version> [optional-arguments]

Client: HELLO 4
Server: -NOPROTO sorry, this protocol version is not supported.

Client: HELLO 3
Server: -ERR unknown command 'HELLO'

Client: HELLO 3 AUTH default mypassword
Server: -ERR invalid password
(the connection remains in RESP2 mode)

C: *2\r\n
C: $4\r\n
C: LLEN\r\n
C: $6\r\n
C: mylist\r\n

S: :48293\r\n

C: PING
S: +PONG

C: EXISTS somekey
S: :0

#include <stdio.h>

int main(void) {
    unsigned char *p = "$123\r\n";
    int len = 0;

    p++;
    while(*p != '\r') {
        len = (len*10)+(*p - '0');
        p++;
    }

    /* Now p points at '\r', and the length is in len. */
    printf("%d\n", len);
    return 0;
}