手写 RPC 框架教程：Netty + ZooKeeper + SPI 实战

Guide约 3250 字大约 11 分钟

面试官顺着一个 RPC 项目继续问，问题很快就会落到具体实现上：

TCP 只有字节流，粘包、半包怎么处理？
同一条长连接发出多个请求，响应回来后怎么找到对应的调用方？
服务实例上下线以后，客户端怎样及时拿到新地址？
请求超时后，CompletableFuture 和在途请求 Map 怎么清理，复用的 Channel 要不要关闭？
新增一种序列化方式，为什么不应该继续往 switch 里加分支？

只记住“RPC 让远程调用像本地调用一样简单”，遇到这些追问很难往下讲。《手写 RPC 框架》围绕一个可以运行的 Java 项目，把动态代理、网络通信、自定义协议、序列化、注册中心、负载均衡、异步调用和异常处理串在一起。

如果你还不熟悉 RPC 的概念和调用流程，可以先阅读 JavaGuide 的免费文章：RPC 远程过程调用详解。

项目介绍

guide-rpc-framework 是一个面向学习和工程实践的轻量级 RPC 框架。项目保留了早期 Socket 版本，也提供了基于 Netty 的实现，方便对照 BIO 与 NIO 在连接、线程和请求处理方式上的差异。

项目地址（欢迎 Star）：

GitHub：https://github.com/Snailclimb/guide-rpc-framework
Gitee：https://gitee.com/SnailClimb/guide-rpc-framework

项目代码完全开源。配套教程是 JavaGuide 知识星球内部小册，当前包含 15 篇正文，以及一篇简历写法和面试常见问题解答。

一次 RPC 调用经过了什么

Guide RPC Framework 整体架构

以 @RpcReference 注入的服务接口为例，一次调用会经过这些环节：

本地接口调用
    ↓
JDK 动态代理组装 RpcRequest
    ↓
ZooKeeper 服务发现
    ↓
一致性哈希选择服务实例
    ↓
建立或复用 Netty Channel
    ↓
协议编码、序列化与压缩
    ↓
服务端拆帧、解码并执行目标方法
    ↓
响应按 requestId 完成对应 CompletableFuture

教程不会停在“客户端发送请求、服务端返回结果”这一层。协议字段怎样排列、服务端为什么不能在 I/O 线程里执行耗时方法、请求从排队到收到响应如何共用一个超时预算，这些问题都会结合当前代码说明。

当前项目实现了哪些能力

模块	当前实现
网络通信	Socket 与 Netty 两种传输实现，Netty 支持 Channel 复用和心跳检测
通信协议	16 字节固定头部，包含魔数、版本、完整长度、消息类型、编解码编号和请求编号
消息边界	基于长度字段拆帧，并限制帧及解压后消息体最大为 8 MiB
序列化与压缩	支持 Hessian、Kryo、Protostuff 和 Gzip，默认序列化方式为 Hessian
服务注册发现	使用 ZooKeeper 临时节点和 CuratorCache，支持本地地址缓存与会话恢复
负载均衡	默认使用一致性哈希，每个物理节点对应 160 个虚拟节点
请求响应关联	使用 `requestId -> CompletableFuture` 管理并发请求，处理超时、取消、断连和关闭清理
调用方式	提供同步代理和返回 `CompletableFuture` 的异步镜像接口
扩展机制	自定义命名 SPI，覆盖序列化、压缩、负载均衡、注册中心、服务发现和传输层
Spring 集成	使用 `@RpcScan`、`@RpcService`、`@RpcReference` 完成扫描、服务发布与代理注入
错误处理	使用 0～16 的稳定状态码区分参数错误、超时、资源耗尽、服务不可用和内部错误
自动化测试	共 82 项测试，覆盖配置、SPI、编解码、代理、传输、服务处理和 ZooKeeper 会话恢复

这仍然是一个教学和工程实践项目。自动重试、熔断、限流、TLS、调用方鉴权、远程取消、监控中心以及服务端有界任务队列尚未实现。教程会直接标出这些限制，避免把成熟 RPC 框架的能力套到当前代码上。

这套教程怎么讲

教程先用 Socket 和 JDK 动态代理搭出最小调用链，再逐步换成 Netty、自定义协议、可插拔序列化和 ZooKeeper。读者可以看到每次改造解决了哪个问题，而非直接面对一套已经组装好的代码。

源码分析部分按真实调用顺序展开。客户端怎样生成请求、服务发现怎样选择地址、编解码器怎样处理消息、服务端怎样执行方法、响应怎样完成 Future，都能在文章和代码之间对应起来。

后面的 SPI、负载均衡和测试章节继续处理扩展与失败场景。除了正常调用，也会讨论重复 requestId、响应晚到、请求超时、连接提前关闭、非法协议帧和 ZooKeeper 会话失效。

运行项目所需的环境、启动顺序和第一次 RPC 调用继续放在项目 README 的“快速开始”中维护，不再单独拆一篇重复文章。

配套教程内容安排

RPC 基础与框架设计

01 什么是 RPC？原理是什么？：从本地调用与远程调用的差异出发，说明 RPC 的组成和一次调用的基本过程。
02 常见 RPC 框架介绍：对比 Dubbo、gRPC、Thrift、Motan 等常见方案，理解框架选型关注的因素。
03 如何自己实现一个 RPC 框架？：确定代理、传输、序列化、注册中心和负载均衡等模块的职责。
04 序列化介绍以及序列化协议选择：比较 JDK 序列化、Hessian、Kryo、Protostuff 等方案，并说明当前项目的接入方式。

网络通信、动态代理与 ZooKeeper

05 Socket 网络通信实战：用最少的组件跑通远程请求，理解阻塞 I/O 版本的线程和连接模型。
06 Netty 网络通信实战：学习 EventLoop、Channel、Pipeline、Handler 以及长度字段拆帧。
07 静态代理、JDK 与 CGLIB 动态代理实战：理解代理对象怎样屏蔽请求组装和网络传输细节。
08 ZooKeeper 常用命令与 Curator 使用详解：掌握节点模型、临时节点、监听机制和 Curator 的基本用法。

RPC 框架源码分析

09 网络传输模块：沿着客户端发送、协议编解码、Channel 复用、心跳和服务端处理器阅读代码。
10 注册中心模块：分析服务标识、服务发布、地址缓存、节点监听和会话恢复。
11 其他模块：继续说明代理、服务提供、本地服务容器、Spring 注解集成和异常处理。

异步调用、扩展机制与可靠性

12 使用 CompletableFuture 优化接收服务端返回结果：实现并发请求与响应关联，并说明超时、取消和资源清理。
13 RPC 框架的 SPI 扩展机制是如何实现的？：从硬编码工厂切换到命名 SPI，分析扩展发现、校验和三级缓存。
14 随机负载均衡与一致性哈希实战：理解两种算法的适用场景，重点分析项目当前使用的一致性哈希实现。
15 如何测试一个 RPC 框架？：使用 JUnit、Netty EmbeddedChannel 和 Curator TestingServer 验证并发、超时、断连、非法帧与会话恢复。

简历写法与面试准备

项目能运行只是第一步。写进简历以后，默认序列化方式、协议头长度、线程模型、超时范围和当前缺少的治理能力都可能被追问。

配套的《简历写法和面试常见问题解答》包含：

9 条后端项目经历推荐写法，以及适合一页简历的 6 条精简版。
当前可以直接核对的指标，例如 16 字节协议头、8 MiB 报文上限、160 个虚拟节点和 82 项测试。
一分钟项目介绍和 18 个常见追问。
容易写错的项目能力说明，例如默认 Hessian、随机负载均衡尚未接入当前 SPI 配置、没有 Spring Boot Starter，也没有完整的重试和熔断机制。

这部分不会教你凭空包装数据。没有压测报告，就不写“十万 QPS”；没有实现 Spring Boot Starter，也不会把 Spring 注解集成换个名字放进简历。