用 Rust 从零实现 Redis 协议服务:让 redis-cli 直接连上来
想验证自己对协议的理解?最好的方式是"让现成的客户端连上来"。
写一个 Redis 协议(RESP)服务端是最合适的练手题:协议只有 5 种前缀,redis-cli 就是现成的测试工具。等它真能 PING、SET、GET 了,你会对"协议"这两个字有实感。
RESP 只有 5 种类型
RESP(REdis Serialization Protocol)的设计目标很明确:简单、人类可读、二进制安全。
每种类型用一个首字节标记:
| 前缀 | 类型 | 格式 | 例子 |
|---|---|---|---|
+ |
简单字符串 | +OK\r\n |
状态回复 |
- |
错误 | -ERR xxx\r\n |
错误回复 |
: |
整数 | :1000\r\n |
计数、长度 |
$ |
批量字符串 | $5\r\nhello\r\n |
二进制安全 |
* |
数组 | *2\r\n$3\r\nfoo\r\n... |
多元素 |
关键点:所有行都以 \r\n 结尾,长度是字节数(不是字符数)。
客户端发来的命令长什么样
redis-cli SET name king 发出去的其实是数组:
*3\r\n
$3\r\nSET\r\n
$4\r\nname\r\n
$4\r\nking\r\n也就是"3 个元素的数组:SET、name、king"。
统一用数组传输,是为了让参数里包含空格或二进制数据时也能正确处理。 如果用空格分隔的行协议,SET key "a b" 就没法区分了。
第一步:定义值类型
服务端内部的表示:
#[derive(Debug, Clone, PartialEq)]
pub enum RespValue {
Simple(String),
Error(String),
Integer(i64),
Bulk(Vec<u8>), // 注意是 Vec<u8>,不是 String
Array(Vec<RespValue>),
Null,
}Bulk 用 Vec<u8> 是"二进制安全"的体现。 Redis 可以存任意字节的 value,包括 \0。如果用 String,就存不了非 UTF-8 数据——这是自研实现最常见的错误。
第二步:编码
编码比解码简单,从最外层类型开始写:
pub fn encode(value: &RespValue, out: &mut Vec<u8>) {
match value {
RespValue::Simple(s) => {
out.push(b'+');
out.extend_from_slice(s.as_bytes());
out.extend_from_slice(b"\r\n");
}
RespValue::Error(s) => {
out.push(b'-');
out.extend_from_slice(s.as_bytes());
out.extend_from_slice(b"\r\n");
}
RespValue::Integer(n) => {
out.push(b':');
out.extend_from_slice(n.to_string().as_bytes());
out.extend_from_slice(b"\r\n");
}
RespValue::Bulk(data) => {
out.push(b'$');
out.extend_from_slice(data.len().to_string().as_bytes());
out.extend_from_slice(b"\r\n");
out.extend_from_slice(data);
out.extend_from_slice(b"\r\n");
}
RespValue::Null => {
// Redis 用 $-1 表示不存在的 key
out.extend_from_slice(b"$-1\r\n");
}
RespValue::Array(items) => {
out.push(b'*');
out.extend_from_slice(items.len().to_string().as_bytes());
out.extend_from_slice(b"\r\n");
for item in items {
encode(item, out);
}
}
}
}有个细节:Null 编码成 $-1 而不是 *-1。这是历史约定,客户端(redis-cli、各种 SDK)都按这个解析。写错的话,GET 一个不存在的 key 会让客户端行为异常。
第三步:解码
解码要处理"读一行"和"读 N 字节"两种动作。
use std::io::{BufRead, Read};
pub struct Decoder<R> {
reader: R,
}
impl<R: BufRead> Decoder<R> {
/// 读一行(到 \r\n 为止),返回不含行尾的内容
fn read_line(&mut self) -> std::io::Result<Vec<u8>> {
let mut buf = Vec::new();
self.reader.read_until(b'\n', &mut buf)?;
// 去掉结尾的 \r\n
if buf.ends_with(b"\n") { buf.pop(); }
if buf.ends_with(b"\r") { buf.pop(); }
Ok(buf)
}
pub fn decode(&mut self) -> std::io::Result<Option<RespValue>> {
let mut prefix = [0u8; 1];
match self.reader.read_exact(&mut prefix) {
Ok(()) => {}
Err(e) if e.kind() == std::io::ErrorKind::UnexpectedEof => return Ok(None),
Err(e) => return Err(e),
}
match prefix[0] {
b'+' => Ok(Some(RespValue::Simple(self.line_as_string()?))),
b'-' => Ok(Some(RespValue::Error(self.line_as_string()?))),
b':' => Ok(Some(RespValue::Integer(self.line_as_int()?))),
b'$' => self.decode_bulk().map(Some),
b'*' => self.decode_array().map(Some),
other => Err(std::io::Error::new(
std::io::ErrorKind::InvalidData,
format!("未知的 RESP 前缀: {}", other as char),
)),
}
}
}批量字符串:先读长度,再精确读 N 字节。
fn decode_bulk(&mut self) -> std::io::Result<RespValue> {
let len_line = self.read_line()?;
let len: i64 = std::str::from_utf8(&len_line)
.ok()
.and_then(|s| s.parse().ok())
.ok_or_else(|| std::io::Error::new(std::io::ErrorKind::InvalidData, "bad bulk len"))?;
if len < 0 {
return Ok(RespValue::Null); // $-1 = null
}
let mut data = vec![0u8; len as usize];
self.reader.read_exact(&mut data)?;
// 吃掉数据后面的 \r\n
let mut crlf = [0u8; 2];
self.reader.read_exact(&mut crlf)?;
Ok(RespValue::Bulk(data))
}这一步是整个协议的关键:长度是字节数,读完必须精确吃掉结尾的 \r\n。少读或多读都会导致后续解析错位——症状是"前几个命令正常,然后突然全乱"。
数组:递归解码。
fn decode_array(&mut self) -> std::io::Result<RespValue> {
let len_line = self.read_line()?;
let len: i64 = std::str::from_utf8(&len_line)
.ok()
.and_then(|s| s.parse().ok())
.ok_or_else(|| std::io::Error::new(std::io::ErrorKind::InvalidData, "bad array len"))?;
if len < 0 {
return Ok(RespValue::Null);
}
let mut items = Vec::with_capacity(len as usize);
for _ in 0..len {
match self.decode()? {
Some(v) => items.push(v),
None => return Err(std::io::Error::new(std::io::ErrorKind::UnexpectedEof, "eof")),
}
}
Ok(RespValue::Array(items))
}递归解码数组是合法的,因为 RESP 支持嵌套:*2\r\n*1\r\n:1\r\n$3\r\nfoo\r\n。不过实际命令的数组一般不嵌套。
协议解码器必须是"可恢复的":解析失败时,连接的状态要明确——是关掉重来,还是继续尝试。RESP 的答案是直接关连接,因为错位之后无法定位。
一个必须处理的兼容性坑:内联命令
redis-cli 在某些情况下会发内联命令——不是数组,而是纯文本行:
PING\r\n这是给 telnet 调试留的兼容路径。如果你的解码器只认 + - : $ * 五种前缀,收到 PING 会直接报错。
处理方式是:首字节不是已知前缀时,当作内联命令解析。
b'*' => self.decode_array().map(Some),
// 不是已知前缀,按内联命令处理
_ => {
// 把已读的那个字节放回,加上剩余这一行
let mut line = vec![prefix[0]];
let rest = self.read_line()?;
line.extend_from_slice(&rest);
let parts: Vec<RespValue> = line
.split(|b| *b == b' ')
.filter(|s| !s.is_empty())
.map(|s| RespValue::Bulk(s.to_vec()))
.collect();
Ok(Some(RespValue::Array(parts)))
}这样 PING、SET key value(不带引号)这种调试输入也能工作。很多自研 Redis 兼容服务在 telnet 下不能调试,就是漏了这段。
第四步:命令处理
收到 Array 后,第一个元素是命令名,后面是参数。
pub struct Server {
store: std::collections::HashMap<Vec<u8>, Vec<u8>>,
}
impl Server {
pub fn dispatch(&mut self, value: RespValue) -> RespValue {
let RespValue::Array(parts) = value else {
return RespValue::Error("ERR protocol error: expected array".into());
};
if parts.is_empty() {
return RespValue::Error("ERR empty command".into());
}
// 命令名大小写不敏感,转大写
let cmd = match &parts[0] {
RespValue::Bulk(b) => String::from_utf8_lossy(b).to_uppercase(),
_ => return RespValue::Error("ERR invalid command type".into()),
};
let args = &parts[1..];
match cmd.as_str() {
"PING" => RespValue::Simple("PONG".into()),
"ECHO" => args.first().cloned().unwrap_or(RespValue::Null),
"SET" => self.cmd_set(args),
"GET" => self.cmd_get(args),
"DEL" => self.cmd_del(args),
"EXISTS" => self.cmd_exists(args),
"COMMAND" => RespValue::Array(vec![]), // 让 redis-cli 不报错
_ => RespValue::Error(format!("ERR unknown command '{}'", cmd)),
}
}
}COMMAND 这个命令值得单说:redis-cli 连上来时默认会先发 COMMAND DOCS 来获取命令补全信息。 如果不处理它,redis-cli 会在连接初期打印一个错误,虽然不影响使用,但看起来很不专业。
返回空数组是最简单的兼容方式。
然后是 SET / GET:
fn cmd_set(&mut self, args: &[RespValue]) -> RespValue {
if args.len() < 2 {
return RespValue::Error("ERR wrong number of arguments for 'set' command".into());
}
let key = match &args[0] { RespValue::Bulk(b) => b.clone(), _ => return RespValue::Error("ERR invalid key".into()) };
let val = match &args[1] { RespValue::Bulk(b) => b.clone(), _ => return RespValue::Error("ERR invalid value".into()) };
self.store.insert(key, val);
RespValue::Simple("OK".into())
}
fn cmd_get(&self, args: &[RespValue]) -> RespValue {
if args.len() != 1 {
return RespValue::Error("ERR wrong number of arguments for 'get' command".into());
}
match &args[0] {
RespValue::Bulk(key) => match self.store.get(key) {
Some(v) => RespValue::Bulk(v.clone()),
None => RespValue::Null, // 不存在的 key 返回 $-1
},
_ => RespValue::Error("ERR invalid key".into()),
}
}
fn cmd_del(&mut self, args: &[RespValue]) -> RespValue {
let mut removed = 0;
for arg in args {
if let RespValue::Bulk(key) = arg {
if self.store.remove(key).is_some() {
removed += 1;
}
}
}
RespValue::Integer(removed)
}错误信息的格式和 Redis 保持一致。比对自己的实现和真 Redis 的输出,是低成本高收益的对照测试:
ERR unknown command 'FOO'
ERR wrong number of arguments for 'get' command客户端和 SDK 有时会按错误前缀解析(比如 WRONGTYPE、MOVED、ASK)。错误格式不对,某些客户端行为就会偏离。
第五步:连接循环
pub fn serve(listener: std::net::TcpListener) -> std::io::Result<()> {
let store = std::sync::Arc::new(std::sync::Mutex::new(Server::default()));
for stream in listener.incoming() {
let stream = stream?;
let store = store.clone();
std::thread::spawn(move || {
let _ = handle_client(stream, store);
});
}
Ok(())
}
fn handle_client(stream: std::net::TcpStream, store: std::sync::Arc<std::sync::Mutex<Server>>) -> std::io::Result<()> {
let mut decoder = Decoder { reader: std::io::BufReader::new(stream.try_clone()?) };
let mut out = stream;
while let Some(value) = decoder.decode()? {
// 先算回复,再拿锁(缩短临界区)
let reply = {
let mut server = store.lock().unwrap();
server.dispatch(value)
};
let mut buf = Vec::new();
encode(&reply, &mut buf);
std::io::Write::write_all(&mut out, &buf)?;
out.flush()?;
}
Ok(())
}注意这里先 dispatch 再编码,锁的范围很小。如果把编码也放进临界区,所有连接都会在锁上排队。
真 Redis 是单线程事件循环模型(6.0 之后 IO 多线程但命令执行仍单线程),所以不存在锁竞争。但用锁保护共享状态、把临界区缩到最小,是自研实现最直接的路径。
测试:直接用 redis-cli
cargo run &
redis-cli -p 6379
127.0.0.1:6379> PING
PONG
127.0.0.1:6379> SET name king
OK
127.0.0.1:6379> GET name
"king"
127.0.0.1:6379> GET missing
(nil)
127.0.0.1:6379> EXISTS name
(integer) 1"能被现成客户端正常使用"是协议实现最好的验收标准。 它自动帮你覆盖了编码、空值、错误格式、内联命令这一大堆细节。
值得继续做的三件事
真要做到"能当缓存用",还差:
- 过期时间(TTL):
SET key value EX 60、EXPIRE、惰性删除 + 定期删除 - 数据结构:
LPUSH/LRANGE(链表)、HSET/HGETALL(哈希表)、ZADD(跳表) - 持久化:RDB 快照(前面写过序列化,正好用上)、AOF 追加日志
这三个每一条都能单独成一篇。而你现在已经有的,是它们共同的底座:RESP 编解码 + 命令分发。
结论
RESP 协议的价值在于它把"协议设计"压缩到了最小可理解的范围:
5 种前缀,长度前缀式编码保证二进制安全;数组传命令避免空格歧义;
$-1表示空值;别忘了内联命令这个兼容路径。
写完之后你会明白为什么 Redis 能被各种语言几百行实现一个客户端——协议简单,就是它最大的竞争力。