# guide-rpc-framework: a Netty, Kryo and Zookeeper RPC framework built for reading

> guide-rpc-framework is a Java RPC framework with an example server and client, built on Netty, Kryo and Zookeeper. Its real value is as a study project, not as production middleware.

**Snailclimb/guide-rpc-framework** — A custom RPC framework implemented by Netty+Kyro+Zookeeper.（一款基于 Netty+Kyro+Zookeeper 实现的自定义 RPC 框架-附详细实现过程和相关教程。）

- Repository: https://github.com/Snailclimb/guide-rpc-framework
- Website: https://gitee.com/SnailClimb/guide-rpc-framework
- Stars: 4,432 · Forks: 2,149
- Language: Java
- License: NOASSERTION
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/snailclimb-guide-rpc-framework

## What guide-rpc-framework solves, and who it is written for

The README is explicit about the audience. It describes the project as a way to learn how RPC works underneath, and it suggests the repository as a graduation project or a portfolio entry, on the argument that building a framework yourself stands out more than another business system. That framing should shape how you read everything else. This is a teaching codebase with a working server, a working client and a runnable example, not a framework you drop into an existing service mesh.

The problem it addresses is concrete: calling a method on a remote JVM should look like calling a local one. The README draws the line at HTTP. Feign-style clients that parse and wrap HTTP requests are, in its words, not RPC frameworks. What guide-rpc-framework implements instead is the classic shape: a provider registers its address with a registry, a consumer looks that address up and then speaks a binary protocol over a persistent connection. The modules follow the same split, with rpc-framework-simple holding the core, rpc-framework-common holding utilities and constants, and hello-service-api, example-server and example-client forming a runnable demonstration.

## The request path: Zookeeper, a custom frame, a proxy and a CompletableFuture

Start at the registry. The server publishes its service name plus ip and port to Zookeeper when it starts. The client resolves the service name to a list of addresses. The README states that service discovery defaults to consistent hashing, and that random load balancing is also implemented. Both live behind the same selection step, so the choice is a configuration concern rather than a code change.

On the wire, the project does not reuse JDK serialization. The README rejects it on two grounds: poor efficiency and known security weaknesses. Kryo is the default in the description, with Protostuff and Hessian supported through a pluggable serialization component. The frame itself is custom. It carries a magic number to reject packets that do not belong to this protocol, a serializer identifier, and a message body length computed at runtime, with the RpcRequest and RpcResponse objects as the body. That magic-number check is a small but real design decision: an unrecognised packet can be dropped before any deserialization happens.

The client side wraps the call in a dynamic proxy, so application code invokes an interface method and the proxy handles encoding and transport. Results come back through CompletableFuture rather than an AttributeMap bound to the channel, which the README lists as a completed migration. There is a synchronous proxy that preserves the local-call feel and an asynchronous one that returns CompletableFuture<T> directly. Failures are typed: RpcStatusCode, a requestId and typed exceptions separate business errors from timeout, cancellation, transport and protocol failures, and unknown server-side exception details are hidden from the caller.

## Running the example: Zookeeper, Maven, then a provider and a consumer

The README lists JDK 25 or newer, Maven 3.9 or newer and Zookeeper 3.9.5 or newer as the environment requirements. Start the registry with the Docker command the README gives, which publishes port 2181:

```bash
docker pull zookeeper:3.9.5
docker run -d --name zookeeper -p 2181:2181 zookeeper:3.9.5
```

Then clone and build the whole reactor. The install step matters because the example modules depend on the API and core modules being in the local Maven repository.

```bash
git clone https://github.com/Snailclimb/guide-rpc-framework.git
cd guide-rpc-framework
mvn clean install
```

The service contract lives in hello-service-api. The README's example is a HelloService with a single hello(Hello) method, and a Hello data transfer object carrying a message and a description.

```java
public interface HelloService {
    String hello(Hello hello);
}
```

On the provider side, an implementation is annotated with @RpcService and given a group and a version, which is how the framework disambiguates multiple implementations of one interface. The server is bootstrapped with @RpcScan over the base package, and the README's NettyServerMain creates an AnnotationConfigApplicationContext, pulls NettyRpcServer from it, and calls the service locally as a sanity check. The client half of the example follows the mirror image of this, consuming the same interface through the proxy. You should see the provider log the incoming message and the client receive the returned description string.

## Where guide-rpc-framework stops: the unfinished list is the honest part

The README keeps an explicit checklist, and the unchecked boxes are the limitation section you would otherwise have to write yourself. Support for further registries, load balancing and per-service or per-method configuration is still open. A monitoring console comparable to dubbo admin is not built. Concurrent request tests, disconnect-and-retry tests, malformed frame tests and end-to-end failure tests are listed as still to be added, even though configuration, codec, proxy, exception response and registry discovery already have automated tests.

Read that as a boundary, not a defect. A framework without a retry path will surface a dropped connection as a failure to the caller, and that is the correct behaviour for a teaching implementation but the wrong behaviour for a payment service. The same applies to the single-registry assumption: Zookeeper is the only registry the README describes, and if your organisation runs etcd or Nacos, the lookup step is code you would have to write. Version control is present, and the README gives the reason, that incompatible interface changes such as removing a method or a field need a version bump, but versioning is a manual discipline here, not something the framework enforces for you. If you need a supported, monitored RPC stack with a console and a retry policy, this is the wrong tool.

## How it differs from Dubbo and from HTTP-based clients

The README compares its own architecture diagram with Dubbo's and concludes that the shapes are broadly the same: registry, provider, consumer, network transport. The difference is everything around that shape. Dubbo ships the operational surface, including the admin console that guide-rpc-framework lists as an open task, and it has had years of production hardening that a study project cannot claim. Choosing Dubbo means inheriting that surface and its configuration model. Choosing guide-rpc-framework means you can read the whole request path in an afternoon, because the modules are small and the comments are, per the README, detailed.

The comparison with Feign-style clients is a different axis. Those clients speak HTTP, which means they interoperate with anything that understands HTTP and can be debugged with curl. guide-rpc-framework speaks a binary frame over Netty with Kryo serialization, which is faster in principle but opaque to generic tooling: you cannot inspect a request with a text editor, and a non-Java consumer is not a realistic target. The README's own framing is that such HTTP clients are not RPC frameworks at all, which is a defensible position for a project whose goal is to show what a binary RPC protocol looks like when you build one.

## Maintenance, licence and the cost of upgrading

The repository is not archived, and the last push was on 2026-08-08. There are no releases, so there is no versioned artifact to pin and no changelog to read before an upgrade; you track master. That is a real cost. If you fork the project, as the README invites, you own the merge burden for every change to the wire protocol, because the magic number, the serializer identifier and the body length are shared between client and server. A protocol change is a coordinated upgrade on both sides, not a rolling one.

The licence is the other thing to check before you copy anything. GitHub reports the licence as NOASSERTION, which means the file in the repository root does not match a standard SPDX identifier that the platform recognises. The README does not discuss licence terms. Read LICENSE yourself and decide whether the terms fit your use, particularly if you intend to reuse the core module in a commercial product. Nothing here is legal advice, and the file is short enough to read in full.

## Conclusion

Adopt guide-rpc-framework if you want to read a working Java RPC stack end to end, or if you need a course project with a real registry, wire protocol and proxy layer. Do not adopt it for production traffic: the README still lists a monitoring console and further registry, load-balancing and per-service configuration as unfinished, and the licence file in the repository root is not a standard SPDX identifier, so check the LICENSE text before you copy code into anything you ship. Verify first that JDK 25, Maven 3.9 and Zookeeper 3.9.5 are what your environment actually runs, then bring up the example server and client before reading the core module.

## FAQ

### What is guide-rpc-framework?

It is a custom Java RPC framework built on Netty for network transport, Kryo and other pluggable serializers, and Zookeeper as the registry. The README presents it primarily as a learning project with a runnable example server and client.

### Is guide-rpc-framework still relevant today?

As a study of how an RPC stack fits together, yes: the modules are small and the README keeps a checklist of what is done and what is not. As production middleware, the README itself lists monitoring, retry testing and further registry support as unfinished work, and the last push was on 2026-08-08 with no releases.

### Can you explain guide-rpc-framework in a simple way?

A provider registers its address in Zookeeper, a consumer looks the address up, and a dynamic proxy turns a method call on an interface into a binary request sent over Netty. The result comes back through a CompletableFuture, so the caller sees a normal method return value.

### Why use guide-rpc-framework instead of REST?

The README argues that frameworks which parse and wrap HTTP requests are not RPC frameworks, and it rejects JDK serialization for being slow and having security weaknesses, so it uses a binary frame with Kryo instead. The trade-off is that you cannot inspect a request with ordinary HTTP tooling.

## Sources

- [Issues](https://github.com/Snailclimb/guide-rpc-framework/issues)
- [Project website](https://gitee.com/SnailClimb/guide-rpc-framework)
- [README](https://github.com/Snailclimb/guide-rpc-framework/blob/master/README.md)
- [Snailclimb/guide-rpc-framework on GitHub](https://github.com/Snailclimb/guide-rpc-framework)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/snailclimb-guide-rpc-framework