gRPC + Protocol Buffers patterns — proto schema design, code generation, unary and streaming call types, error handling with gRPC status codes, interceptors, reflection, and client usage. For service-to-service communication where REST is insufficient.
gRPC + Protocol Buffers patterns — proto schema design, code generation, unary and streaming call types, error handling with gRPC status codes, interceptors, reflection, and client usage. For service-to-service communication where REST is insufficient.
gRPC Patterns
Binary RPC framework built on HTTP/2. Use when you need: strong typing between services, bi-directional streaming, or high-throughput service-to-service calls.
Need bi-directional streaming (chat, live data feeds, multiplayer)
Performance-critical service calls (gRPC is ~10x smaller than JSON)
Building microservices that need a strongly-typed contract
Replacing REST endpoints between internal services
Versioning a proto schema safely after an already-deployed service has external consumers
Setting up buf lint and buf breaking checks in CI to prevent accidental wire-incompatible changes
Choosing between unary, server-streaming, client-streaming, and bidirectional streaming for a new RPC method
gRPC vs REST — Decision
Factor
gRPC
REST
Contract
.proto file (strict)
OpenAPI (flexible)
Payload
Protocol Buffers (binary)
JSON (text)
Browser support
Needs grpc-web proxy
Native
Streaming
Native (4 modes)
SSE only
Tooling
Generated clients
Manual fetch / OpenAPI codegen
Use case
Internal services
Public APIs, browser clients
Rule: gRPC for internal services; REST+OpenAPI for anything browser-accessible or public.
Proto Schema Design
// proto/order/v1/order.proto
syntax = "proto3";
package order.v1;
option go_package = "github.com/myorg/myapp/gen/order/v1;orderv1";
option java_package = "com.myorg.myapp.order.v1";
import "google/protobuf/timestamp.proto";
// Always version your package: order.v1, order.v2
// Breaking changes → new version, keep old running during transition
service OrderService {
// Unary: one request, one response
rpc CreateOrder(CreateOrderRequest) returns (CreateOrderResponse);
rpc GetOrder(GetOrderRequest) returns (Order);
// Server streaming: one request, many responses (e.g., status updates)
rpc WatchOrder(WatchOrderRequest) returns (stream OrderEvent);
// Client streaming: many requests, one response (e.g., bulk upload)
rpc BulkCreateOrders(stream CreateOrderRequest) returns (BulkCreateOrdersResponse);
// Bidirectional streaming: many requests, many responses
rpc SyncOrders(stream SyncRequest) returns (stream SyncResponse);
}
message Order {
string id = 1;
string user_id = 2;
OrderStatus status = 3;
repeated OrderItem items = 4;
google.protobuf.Timestamp created_at = 5;
// Field numbers NEVER change — adding new fields is safe
// Removing fields → mark reserved, never reuse the number
}
message OrderItem {
string product_id = 1;
int32 quantity = 2;
int64 price_cents = 3; // use int64 for money, never float
}
enum OrderStatus {
ORDER_STATUS_UNSPECIFIED = 0; // always 0 = default/unknown
ORDER_STATUS_PENDING = 1;
ORDER_STATUS_CONFIRMED = 2;
ORDER_STATUS_SHIPPED = 3;
ORDER_STATUS_CANCELLED = 4;
}
message CreateOrderRequest {
string user_id = 1;
repeated OrderItem items = 2;
}
message CreateOrderResponse { Order order = 1; }
message GetOrderRequest { string id = 1; }
message WatchOrderRequest { string id = 1; }
message OrderEvent {
oneof event {
Order updated = 1;
string cancelled_reason = 2;
}
}
message BulkCreateOrdersResponse { int32 created_count = 1; }
message SyncRequest { string last_sync_token = 1; }
message SyncResponse { Order order = 1; string sync_token = 2; }
Proto Field Rules
✅ Field numbers never change (wire compatibility)
✅ Old fields marked reserved if removed: reserved 5, 6; reserved "old_field";
✅ Use google.protobuf.Timestamp for times (not string)
✅ Money as int64 cents (not float/double)
✅ Enum default value = 0 and always UNSPECIFIED
✅ Package versioned: order.v1
❌ Reusing field numbers after deletion
❌ Changing field types
❌ Renaming fields (safe for semantics, breaks JSON interop)
# Lint proto files
buf lint proto/
# Check for breaking changes vs main branch
buf breaking proto/ --against '.git#branch=main'# Breaking changes detected:# proto/order/v1/order.proto:15:3:Field "1" on message "Order" changed type from "string" to "int64".
