Protocol Buffers — Defining and Generating Java Code

Protocol Buffers are gRPC's schema and serialization format — the wire format that makes gRPC payloads 5–10× smaller than JSON. The workflow has three parts: writing the schema, generating code, and implementing the service.

The `.proto` schema:

• Define message types (data shapes) and a service contract (RPC methods) in a .proto file under src/main/proto
• The key insight is that field numbers — not field names — identify data on the wire; you can rename fields freely without breaking backward compatibility because the binary encoding uses numbers, not names
• Never reuse deleted field numbers — mark them with reserved to prevent accidental reuse that would silently misinterpret old binary data from clients still on the previous schema

Code generation:

• Configure the protobuf-maven-plugin with the protoc-gen-grpc-java extension so mvn compile automatically runs protoc and drops generated stubs into target/generated-sources
• No separate protoc installation needed — the plugin downloads the right binary for the current OS, keeping CI reproducible across developer machines

Service implementation:

• Extend the generated ImplBase class, override your RPC methods, and drive responses through StreamObserver — call onNext to send data and onCompleted to close the stream

Version alignment — the most dangerous footgun:

• The protoc compiler version, protobuf-java runtime, and grpc-java stubs all need to be compatible with each other; a mismatch between the protoc version that generated stubs and the runtime library causes subtle serialization bugs that are hard to trace
• Pin all three versions in the parent POM as a single discipline to prevent hours of debugging that nobody expects from a code generator

I recommend java_multiple_files = true in your .proto files so each message generates a separate Java file — without it, all messages nest inside one outer class, making imports verbose and IDE navigation painful in large schemas.