用 Rust 从零实现 RPC 框架:从 IDL 到 stub 生成
用 gRPC 的时候,你只需要写一个
.proto文件,然后build.rs一跑,客户端就能像调本地函数一样调远程服务。这套"魔法"到底是怎么运作的?
答案不复杂:IDL 是契约,代码生成器把契约翻译成两段代码,序列化负责把结构体变成字节,传输层把字节送过去。
这篇把这条链路完整实现一遍。不追求功能完备,只求每一环都清楚。
RPC 的本质:伪装成本地调用
一个远程调用,实际上要完成这些事:
client: fn add(a, b) -> c
↓ 1. 把参数打包成字节(序列化)
↓ 2. 加上方法名,组装成请求
↓ 3. 通过 TCP 发给服务端
server: 4. 收到字节,解析出方法和参数
↓ 5. 找到对应的处理函数,执行
↓ 6. 把返回值打包
↓ 7. 发回客户端
client: 8. 解析返回值,当成"函数返回值"还给调用方第 1、2、8 步在客户端代码里;第 4、5、6 步在服务端;而"生成这些代码"的工作,就是 codegen 要做的。
第一步:设计 IDL
IDL(接口定义语言)的作用是"让代码生成器知道要生成什么"。为了不引入 protobuf 编译器,我们设计一个极简版本:
service UserService {
rpc GetUser(GetUserRequest) -> (GetUserResponse);
rpc ListUsers(ListUsersRequest) -> (ListUsersResponse);
}
message GetUserRequest {
string user_id = 1;
}
message GetUserResponse {
string user_id = 1;
string name = 2;
int32 age = 3;
}为什么要用 IDL,直接写 Rust trait 不行吗?
可以,但有几个问题:
- 跨语言:IDL 能让 Go、Java、Python 的客户端都能对接
- 向后兼容:字段编号(
= 1)让协议可以演进——加了新字段,老客户端不认识就跳过 - 单一事实来源:客户端和服务端的类型定义不会漂移
字段编号是 protobuf 的核心设计,它把"字段名"和"传输标识"解耦了。改名不影响协议兼容性——这是 protobuf 比 JSON 更适合 RPC 的根本原因。
第二步:IDL 解析
解析 IDL 就是前面写过的"词法 + 递归下降":
#[derive(Debug, Clone)]
pub enum Token {
Service, Rpc, Message,
Ident(String),
LParen, RParen, LBrace, RBrace,
Arrow, Semicolon,
Eq,
Number(i32),
Type(String),
Eof,
}
pub struct Lexer<'a> {
chars: std::iter::Peekable<std::str::Chars<'a>>,
}
impl<'a> Lexer<'a> {
fn next_token(&mut self) -> Token {
self.skip_whitespace();
// 跳过注释
// ...
let Some(c) = self.chars.next() else {
return Token::Eof;
};
match c {
'(' => Token::LParen,
')' => Token::RParen,
'{' => Token::LBrace,
'}' => Token::RBrace,
';' => Token::Semicolon,
'=' => Token::Eq,
'-' if self.chars.peek() == Some(&'>') => {
self.chars.next();
Token::Arrow
}
c if c.is_alphabetic() || c == '_' => {
let mut s = String::from(c);
while let Some(&c) = self.chars.peek() {
if c.is_alphanumeric() || c == '_' {
s.push(c);
self.chars.next();
} else {
break;
}
}
match s.as_str() {
"service" => Token::Service,
"rpc" => Token::Rpc,
"message" => Token::Message,
_ => Token::Ident(s),
}
}
c if c.is_ascii_digit() => {
let mut s = String::from(c);
while let Some(&c) = self.chars.peek() {
if c.is_ascii_digit() {
s.push(c);
self.chars.next();
} else {
break;
}
}
Token::Number(s.parse().unwrap())
}
_ => self.next_token(), // 忽略未知字符
}
}
}生成的 AST:
#[derive(Debug)]
pub struct Schema {
pub services: Vec<ServiceDef>,
pub messages: Vec<MessageDef>,
}
#[derive(Debug)]
pub struct ServiceDef {
pub name: String,
pub methods: Vec<MethodDef>,
}
#[derive(Debug)]
pub struct MethodDef {
pub name: String,
pub request: String,
pub response: String,
}
#[derive(Debug)]
pub struct MessageDef {
pub name: String,
pub fields: Vec<FieldDef>,
}
#[derive(Debug)]
pub struct FieldDef {
pub type_name: String, // "string" / "int32" / 其他 message 名
pub name: String,
pub number: i32,
}第三步:代码生成
拿到 AST 之后,为每个 service 生成两个东西:服务端 trait 和客户端 stub。
服务端 trait
fn generate_server_trait(svc: &ServiceDef) -> String {
let mut out = String::new();
out.push_str(&format!("pub trait {} {{\n", svc.name));
for m in &svc.methods {
out.push_str(&format!(
" fn {}(&self, req: {}) -> Result<{}, RpcError>;\n",
to_snake(&m.name),
m.request,
m.response,
));
}
out.push_str("}\n");
out
}生成结果:
pub trait UserService {
fn get_user(&self, req: GetUserRequest) -> Result<GetUserResponse, RpcError>;
fn list_users(&self, req: ListUsersRequest) -> Result<ListUsersResponse, RpcError>;
}客户端 stub
stub 要"把方法名 + 参数发出去,再把响应解回来":
fn generate_client_stub(svc: &ServiceDef) -> String {
let mut out = String::new();
out.push_str(&format!("pub struct {}Client {{\n", svc.name));
out.push_str(" transport: std::sync::Arc<dyn Transport>,\n");
out.push_str("}\n\n");
out.push_str(&format!("impl {}Client {{\n", svc.name));
out.push_str(&format!(
" pub fn new(transport: std::sync::Arc<dyn Transport>) -> Self {{\n Self {{ transport }}\n }}\n\n"
));
for m in &svc.methods {
out.push_str(&format!(
" pub fn {}(&self, req: {}) -> Result<{}, RpcError> {{\n",
to_snake(&m.name),
m.request,
m.response,
));
out.push_str(&format!(
" let path = \"/{}/{}\";\n",
svc.name, m.name
));
out.push_str(" let payload = encode(&req)?;\n");
out.push_str(" let resp = self.transport.call(path, payload)?;\n");
out.push_str(&format!(" decode::<{}>(&resp)\n", m.response));
out.push_str(" }\n\n");
}
out.push_str("}\n");
out
}生成的客户端:
pub struct UserServiceClient {
transport: std::sync::Arc<dyn Transport>,
}
impl UserServiceClient {
pub fn get_user(&self, req: GetUserRequest) -> Result<GetUserResponse, RpcError> {
let path = "/UserService/GetUser";
let payload = encode(&req)?;
let resp = self.transport.call(path, payload)?;
decode::<GetUserResponse>(&resp)
}
}注意这里的关键抽象:Transport 是一个 trait。
pub trait Transport: Send + Sync {
fn call(&self, path: &str, payload: Vec<u8>) -> Result<Vec<u8>, RpcError>;
}把"怎么传"和"传什么"分开,是整个框架最重要的设计决策。 有了它,同一份生成的 stub 代码可以跑在 TCP、HTTP、Unix socket、甚至内存 channel 上——换传输层完全不需要重新生成代码。
RPC 框架可扩展性的关键,在于"方法调用"和"传输方式"之间是否存在一层干净的抽象。
第四步:序列化
不想引入 serde 的话,可以写一个最简单的编码:TLV(Type-Length-Value)。
#[derive(Debug, Clone, Copy, PartialEq)]
pub enum WireType {
Varint = 0,
Len = 2, // 长度前缀(字符串、bytes、嵌套消息)
Fixed32 = 5,
Fixed64 = 1,
}字段头 = (field_number << 3) | wire_type,这就是 protobuf 的做法:
pub fn encode_field_header(out: &mut Vec<u8>, field_number: u32, wire_type: WireType) {
write_varint(out, ((field_number << 3) | wire_type as u32) as u64);
}变长整数编码:
pub fn write_varint(out: &mut Vec<u8>, mut value: u64) {
while value >= 0x80 {
out.push((value as u8) | 0x80); // 最高位 1 = 后续还有
value >>= 7;
}
out.push(value as u8);
}
pub fn read_varint(input: &mut &[u8]) -> Result<u64, RpcError> {
let mut result = 0u64;
let mut shift = 0;
loop {
let byte = *input.first().ok_or(RpcError::Truncated)?;
*input = &input[1..];
result |= ((byte & 0x7F) as u64) << shift;
if byte & 0x80 == 0 {
return Ok(result);
}
shift += 7;
if shift >= 64 {
return Err(RpcError::MalformedVarint);
}
}
}变长整数让"小的数字只占 1 字节"——1 到 127 都是一个字节。这是 protobuf 比 JSON 小的原因之一。
序列化一个 message:
pub fn encode_user(resp: &GetUserResponse) -> Vec<u8> {
let mut out = Vec::new();
// field 1: user_id (string)
encode_field_header(&mut out, 1, WireType::Len);
write_varint(&mut out, resp.user_id.len() as u64);
out.extend_from_slice(resp.user_id.as_bytes());
// field 2: name
encode_field_header(&mut out, 2, WireType::Len);
write_varint(&mut out, resp.name.len() as u64);
out.extend_from_slice(resp.name.as_bytes());
// field 3: age (int32, varint)
encode_field_header(&mut out, 3, WireType::Varint);
write_varint(&mut out, resp.age as u64);
out
}解码要跳过不认识的字段——这是协议演进的关键:
pub fn skip_field(input: &mut &[u8], wire_type: WireType) -> Result<(), RpcError> {
match wire_type {
WireType::Varint => { read_varint(input)?; }
WireType::Len => {
let len = read_varint(input)? as usize;
if input.len() < len {
return Err(RpcError::Truncated);
}
*input = &input[len..];
}
WireType::Fixed32 => *input = input.get(4..).ok_or(RpcError::Truncated)?,
WireType::Fixed64 => *input = input.get(8..).ok_or(RpcError::Truncated)?,
}
Ok(())
}"未知字段必须跳过而不是报错"是向后兼容的基石。 老客户端收到新服务端返回的、带新字段的响应时,跳过未知字段就能正常解析——这是 protobuf 能长期演进的核心机制。
第五步:传输层
一个最简单的 TCP 传输:
pub struct TcpTransport {
addr: String,
pool: ConnectionPool,
}
impl Transport for TcpTransport {
fn call(&self, path: &str, payload: Vec<u8>) -> Result<Vec<u8>, RpcError> {
let mut conn = self.pool.get(&self.addr)?;
// 帧格式:path_len | path | payload_len | payload
let mut frame = Vec::with_capacity(8 + path.len() + payload.len());
frame.extend_from_slice(&(path.len() as u32).to_be_bytes());
frame.extend_from_slice(path.as_bytes());
frame.extend_from_slice(&(payload.len() as u32).to_be_bytes());
frame.extend_from_slice(&payload);
conn.write_all(&frame)?;
// 读响应长度前缀
let mut len_buf = [0u8; 4];
conn.read_exact(&mut len_buf)?;
let resp_len = u32::from_be_bytes(len_buf) as usize;
let mut resp = vec![0u8; resp_len];
conn.read_exact(&mut resp)?;
self.pool.put(conn);
Ok(resp)
}
}长度前缀是必须的(前面 HTTP 那篇讲过原因):TCP 是字节流,没有长度就不知道读到哪算一个完整的响应。
这里还有一个必须处理的细节:连接出错要能从池里剔除。
match conn.write_all(&frame) {
Ok(()) => {}
Err(e) => {
// 连接坏了,直接丢弃,不要放回池里
return Err(RpcError::Transport(e.to_string()));
}
}如果失败的连接被放回池里,下次取出来还会失败——这会让一个坏连接反复造成失败,直到它被自然淘汰。
第六步:服务端分发
服务端要维护一张"路由表":path → 处理函数。
type Handler = Box<dyn Fn(&[u8]) -> Result<Vec<u8>, RpcError> + Send + Sync>;
pub struct RpcServer {
routes: std::collections::HashMap<String, Handler>,
}
impl RpcServer {
pub fn register<S: UserService + 'static>(&mut self, svc: std::sync::Arc<S>) {
let s = svc.clone();
self.routes.insert(
"/UserService/GetUser".into(),
Box::new(move |payload: &[u8]| {
let req: GetUserRequest = decode(payload)?;
let resp = s.get_user(req)?;
Ok(encode_user(&resp))
}),
);
let s = svc.clone();
self.routes.insert(
"/UserService/ListUsers".into(),
Box::new(move |payload| {
let req: ListUsersRequest = decode(payload)?;
let resp = s.list_users(req)?;
Ok(encode_list_users(&resp))
}),
);
}
pub fn handle(&self, path: &str, payload: &[u8]) -> Result<Vec<u8>, RpcError> {
let handler = self.routes.get(path).ok_or(RpcError::UnknownMethod)?;
handler(payload)
}
}注意 register 是手写的。 真实框架里这段代码也是生成出来的——这就要用到泛型 + 宏。这里是手工版本,但逻辑一模一样。
第七步:错误语义——RPC 最容易搞不清楚的地方
本地函数调用只有"成功"和"抛异常"。RPC 有四种失败模式:
1. 客户端根本没发出去 -> 客户端本地错误
2. 发出去了,但服务端没收到 -> 超时 / 网络错误(不知道服务端有没有执行!)
3. 服务端收到了,执行失败 -> 业务错误(明确的)
4. 服务端执行成功,但响应丢了 -> 超时(实际上执行成功了)第 2 和第 4 种情况是"不确定状态"——调用方无法判断操作到底有没有生效。
#[derive(Debug)]
pub enum RpcError {
/// 明确的业务错误,服务端返回的
Status { code: i32, message: String },
/// 网络/传输错误,操作是否生效未知
Transport(String),
/// 超时,操作是否生效未知
Timeout,
/// 编解码错误
Codec(String),
}
impl RpcError {
/// 这次调用是否"确定没生效"
pub fn definitely_not_applied(&self) -> bool {
match self {
// 编解码在发出去之前失败,肯定没生效
RpcError::Codec(_) => true,
// 业务错误:服务端明确返回了,说明请求到了
RpcError::Status { .. } => true,
// 传输错误和超时:不知道
RpcError::Transport(_) | RpcError::Timeout => false,
}
}
}这个区分直接决定了重试策略:
只有"确定没生效"的错误才能安全重试。 传输错误和超时如果无脑重试,可能造成重复扣款、重复下单。
正确的做法是在业务层做幂等——用请求 ID 去重,而不是靠"传输层不重试"。这也是前面微服务系列里反复提到的那个"这件事到底做没做过"的问题。
第八步:客户端负载均衡与超时
一个生产可用的客户端 stub,transport.call 里至少要包含:
pub struct BalancingTransport {
/// 服务发现:拿到当前可用的实例列表
resolver: std::sync::Arc<dyn Resolver>,
/// 负载均衡策略
picker: Box<dyn Picker>,
timeouts: Timeouts,
}
impl Transport for BalancingTransport {
fn call(&self, path: &str, payload: Vec<u8>) -> Result<Vec<u8>, RpcError> {
let instances = self.resolver.resolve()?;
if instances.is_empty() {
return Err(RpcError::Transport("no instances".into()));
}
let start = std::time::Instant::now();
let mut last_err = None;
// 最多试 2 个实例
for attempt in 0..2 {
let inst = self.picker.pick(&instances, attempt);
let remaining = self.timeouts.per_call.saturating_sub(start.elapsed());
if remaining.is_zero() {
return Err(RpcError::Timeout);
}
match self.call_one(inst, path, &payload, remaining) {
Ok(resp) => return Ok(resp),
Err(e) => last_err = Some(e),
}
}
Err(last_err.unwrap())
}
}"整体超时"而不是"每次调用超时" 是这里的关键设计。
如果每个实例都给 1 秒超时,试 3 个实例,最坏情况调用方要等 3 秒。正确做法是预算一个总超时(比如 1 秒),每次重试都从剩余时间里扣。
总预算 1000ms
├─ 实例 A: 最多用 1000ms(实际 400ms 失败)
├─ 实例 B: 剩余 600ms(实际 300ms 失败)
└─ 实例 C: 剩余 300ms这个叫"超时预算传递"(deadline propagation),gRPC 的 grpc-timeout 头就是干这个的。没有它的多实例重试,会把延迟放大到不可接受的程度。
结论
把 RPC 框架拆开,就是一条八段的流水线:
IDL 定义契约;解析器读成 AST;代码生成器产出服务端 trait 和客户端 stub;序列化把结构体变成带字段编号的字节;传输层只负责送字节;服务端用路由表分发;错误要区分"确定失败"和"不确定状态";客户端做负载均衡和超时预算。
其中三个设计决策最值得记住:
Transporttrait 是解耦点——它让"传输方式"可以自由替换- 字段编号是兼容性的基础——未知字段必须跳过而不是报错
- 超时必须从"每次调用"改成"整次调用预算"——否则重试会放大延迟
理解了这些,你再看 gRPC、Thrift、Dubbo 的那些设计,会发现它们是同一套骨架,只是各自在细节上做了不同的取舍。下一篇我们离开协议层,去看一个更"现实"的问题:怎么和一个只提供 HTTP 的云服务打交道。