Rust / 系统课时

使用 Codec 组织协议

使用 Codec 组织协议

手写读取循环能完成分帧,但协议解析、缓冲管理和业务处理容易纠缠在一起。本节把字节到消息的转换封装为 Decoder/Encoder,再交给 Framed 驱动,让同一个 Codec 能复用于客户端、服务端和测试。

学习目标

  • 区分 Decoder、Encoder 与 Framed 的职责边界
  • 实现一个可复用的换行消息 Codec,并正确处理不完整输入
  • 使用 Stream 和 Sink 接口收发应用层消息

Framed 如何连接 I/O 与消息

Decoder 负责从读缓冲区尝试取出一条消息;字节不足时返回 Ok(None),并保留未消费的数据。Encoder 做相反工作,把一条应用消息追加到写缓冲区。Framed 持有异步 I/O、Codec 和内部缓冲区,把读取侧暴露为 Stream,把写入侧暴露为 Sink。

Framed 与 Codec 双向数据流

这个边界很重要:业务层应该处理 String、结构体或枚举等消息,不再关心“这次 socket 读到了多少字节”。而 Codec 只处理协议格式,不承担认证、数据库写入或业务状态迁移。

实现可复用 Codec

下面实现一个简单的换行协议:每条 UTF-8 消息以 \n 结束,正文最多 64 字节。Decoder 搜索完整分隔符;没有换行时返回 None,让 Framed 继续读取。Encoder 则把消息和结尾换行写入输出缓冲区。

项目依赖如下:

toml
[package]
name = "codec-demo"
version = "0.1.0"
edition = "2024"

[dependencies]
bytes = "1"
futures = "0.3"
tokio = { version = "1", features = ["macros", "rt-multi-thread", "io-util"] }
tokio-util = { version = "0.7", features = ["codec"] }

主程序使用 tokio::io::duplex 模拟一对双向连接,并让客户端与服务端复用同一个 MessageCodec:

rust
use bytes::{BufMut, BytesMut};
use futures::{SinkExt, StreamExt};
use std::io;
use tokio_util::codec::{Decoder, Encoder, Framed};

struct MessageCodec {
    max_len: usize,
}

impl MessageCodec {
    fn new(max_len: usize) -> Self {
        Self { max_len }
    }
}

impl Decoder for MessageCodec {
    type Item = String;
    type Error = io::Error;

    fn decode(&mut self, src: &mut BytesMut) -> io::Result<Option<String>> {
        let newline = src.iter().position(|byte| *byte == b'\n');

        match newline {
            Some(pos) if pos > self.max_len => Err(io::Error::new(
                io::ErrorKind::InvalidData,
                "message is too long",
            )),
            Some(pos) => {
                // split_to 只消费当前帧,连续到达的下一帧仍保留在 src 中。
                let mut line = src.split_to(pos + 1);
                line.truncate(pos);
                String::from_utf8(line.to_vec())
                    .map(Some)
                    .map_err(|_| io::Error::new(io::ErrorKind::InvalidData, "invalid utf-8"))
            }
            None if src.len() > self.max_len => Err(io::Error::new(
                io::ErrorKind::InvalidData,
                "message is too long",
            )),
            None => Ok(None),
        }
    }
}

impl Encoder<String> for MessageCodec {
    type Error = io::Error;

    fn encode(&mut self, item: String, dst: &mut BytesMut) -> io::Result<()> {
        if item.len() > self.max_len || item.as_bytes().contains(&b'\n') {
            return Err(io::Error::new(
                io::ErrorKind::InvalidInput,
                "invalid outbound message",
            ));
        }

        dst.reserve(item.len() + 1);
        dst.put_slice(item.as_bytes());
        dst.put_u8(b'\n');
        Ok(())
    }
}

#[tokio::main]
async fn main() -> io::Result<()> {
    let (client_io, server_io) = tokio::io::duplex(128);

    let server = tokio::spawn(async move {
        let mut framed = Framed::new(server_io, MessageCodec::new(64));

        while let Some(message) = framed.next().await {
            let message = message?;
            framed.send(format!("ack:{message}")).await?;
        }

        Ok::<_, io::Error>(())
    });

    let mut client = Framed::new(client_io, MessageCodec::new(64));
    client.send("ping".to_owned()).await?;

    if let Some(reply) = client.next().await {
        println!("{}", reply?);
    }

    drop(client);
    server.await.unwrap()?;
    Ok(())
}

预期输出

text
ack:ping

这里客户端和服务端复用了同一个 MessageCodec。Framed 会在读取到新字节后调用 decode,也可能在缓冲区仍有剩余数据时再次调用,所以 decode 必须只消费已经确认属于当前消息的字节;输入不完整时不能提前删除前缀。

Decoder 与 Encoder 的实现边界

实现 Decoder 时,Ok(Some(item)) 表示已经消费并产出一帧,Ok(None) 表示暂时没有完整帧,Err 表示协议层无法继续正常解码。一个输入缓冲区可能同时包含多帧,因此成功产出一帧后应把其余字节留给后续调用。

实现 Encoder 时,应只负责验证并编码单条出站消息。示例禁止消息自身包含换行,否则接收方会把一条业务消息误拆成两帧。二进制协议则可以改用长度前缀 Codec,让消息正文无需避让分隔符。

把业务逻辑留在 Codec 之外

Codec 最适合保持确定性:给定相同字节,应得到相同消息或相同协议错误。认证、限流、数据库访问等业务操作放在 framed.next() 之后处理,这样协议层可以独立单元测试,也能在不同连接类型上复用。

当协议从简单字符串演进为命令枚举或结构体时,只需要改变 Decoder::Item 与 Encoder 接受的消息类型,业务层仍通过 Stream/Sink 面向消息工作。这样就把“TCP 是字节流”的复杂性限制在 Codec 边界内,而不是扩散到每个请求处理函数。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

使用 Codec 组织协议

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通