A gRPC Service Checklist

Questions to ask

Are proto files linted, versioned by package and checked for breaking changes? Does every RPC have its own request and response messages? Do clients set deadlines and servers propagate them? Are status codes specific, with rich details for validation errors? Are retries limited to idempotent calls? Is all traffic encrypted, with authentication and per-method authorisation in interceptors? Is load balancing per request? Are health checks, metrics and tracing in place, and are streams handling cancellation and reconnects?

The checklist

Use it in reviews.

[ ] proto: versioned package, buf lint + buf breaking in CI, reserved removed fields
[ ] dedicated request/response messages; enums with *_UNSPECIFIED = 0
[ ] deadlines on every client call; propagated downstream
[ ] precise status codes; rich error details for validation
[ ] retries only for idempotent methods or with idempotency keys
[ ] TLS/mTLS everywhere; auth + authorisation interceptors (unary AND stream)
[ ] per-request load balancing (L7 proxy or client-side round robin)
[ ] health service + Kubernetes gRPC probes; reflection off in prod if public
[ ] per-method metrics and OpenTelemetry tracing
[ ] streams: cancellation checks, keepalive, reconnect with backoff

Share a service template

A template repository with interceptors, health checks, metrics and CI checks makes every new service production-ready from day one.

Quick check: Which item belongs on a gRPC checklist?

• Retry PlaceOrder on every error
• Reuse deleted field numbers
• Every client call sets a deadline
• Use insecure channels in production