gRPC Service Design — Protocol Buffers and Production Patterns

Protocol Buffers basics

syntax = "proto3";
package orders.v1;

service OrderService {
  rpc GetOrder (GetOrderRequest) returns (Order);
  rpc ListOrders (ListOrdersRequest) returns (stream Order); // server streaming
  rpc CreateOrder (CreateOrderRequest) returns (Order);
}

message Order {
  int64  id          = 1;
  string customer_id = 2;
  double amount      = 3;
  OrderStatus status = 4;
}

enum OrderStatus {
  ORDER_STATUS_UNSPECIFIED = 0;
  ORDER_STATUS_PENDING     = 1;
  ORDER_STATUS_SHIPPED     = 2;
}

Always set deadlines

Every gRPC call must have a deadline. Without one, a slow downstream can hold goroutines/threads indefinitely. Pass the deadline through the context on every hop.

Interceptors

Use interceptors for cross-cutting concerns: logging, metrics, authentication, and retry logic. Equivalent to middleware in HTTP frameworks.

Error model

Use Google's rich error model (google.rpc.Status) with error details. Map gRPC status codes to HTTP status codes at the gateway for REST clients.