Go gRPC (Production) Overview
gRPC provides strongly-typed RPC APIs backed by Protocol Buffers, with first-class streaming support and excellent performance for service-to-service communication. This skill focuses on production defaults: versioned protos, deadlines, error codes, interceptors, health checks, TLS, and testability.
Quick Start 1) Define a versioned protobuf API
✅ Correct: versioned package
// proto/users/v1/users.proto syntax = "proto3";
package users.v1; option go_package = "example.com/myapp/gen/users/v1;usersv1";
service UsersService { rpc GetUser(GetUserRequest) returns (GetUserResponse); rpc ListUsers(ListUsersRequest) returns (stream User); }
message GetUserRequest { string id = 1; } message GetUserResponse { User user = 1; } message ListUsersRequest { int32 page_size = 1; string page_token = 2; }
message User { string id = 1; string email = 2; string display_name = 3; }
❌ Wrong: unversioned package (hard to evolve)
package users;
2) Generate Go code
Install generators:
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
Generate:
protoc -I proto \ --go_out=./gen --go_opt=paths=source_relative \ --go-grpc_out=./gen --go-grpc_opt=paths=source_relative \ proto/users/v1/users.proto
3) Implement server with deadlines and status codes
✅ Correct: validate + map errors to gRPC codes
package usersvc
import ( "context"
"google.golang.org/grpc/codes"
"google.golang.org/grpc/status"
usersv1 "example.com/myapp/gen/users/v1"
)
type Service struct { usersv1.UnimplementedUsersServiceServer Repo Repo }
type Repo interface { GetUser(ctx context.Context, id string) (User, error) }
type User struct { ID, Email, DisplayName string }
func (s Service) GetUser(ctx context.Context, req usersv1.GetUserRequest) (*usersv1.GetUserResponse, error) { if req.GetId() == "" { return nil, status.Error(codes.InvalidArgument, "id is required") }
u, err := s.Repo.GetUser(ctx, req.GetId())
if err != nil {
if err == ErrNotFound {
return nil, status.Error(codes.NotFound, "user not found")
}
return nil, status.Error(codes.Internal, "internal error")
}
return &usersv1.GetUserResponse{
User: &usersv1.User{
Id: u.ID,
Email: u.Email,
DisplayName: u.DisplayName,
},
}, nil
}
❌ Wrong: return raw errors (clients lose code semantics)
return nil, errors.New("user not found")
Core Concepts Deadlines and cancellation
Make every call bounded; enforce server-side timeouts for expensive handlers.
✅ Correct: require deadline
if _, ok := ctx.Deadline(); !ok { return nil, status.Error(codes.InvalidArgument, "deadline required") }
Metadata
Use metadata for auth/session correlation, not for primary request data.
✅ Correct: read auth token from metadata
md, _ := metadata.FromIncomingContext(ctx) auth := "" if vals := md.Get("authorization"); len(vals) > 0 { auth = vals[0] }
Interceptors (Middleware)
Use interceptors for cross-cutting concerns: auth, logging, metrics, tracing, request IDs.
✅ Correct: unary interceptor with request ID
func unaryRequestID() grpc.UnaryServerInterceptor { return func(ctx context.Context, req any, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (any, error) { id := uuid.NewString() ctx = context.WithValue(ctx, requestIDKey{}, id) resp, err := handler(ctx, req) return resp, err } }
Streaming patterns Server streaming (paginate or stream results)
✅ Correct: stop on ctx.Done()
func (s Service) ListUsers(req usersv1.ListUsersRequest, stream usersv1.UsersService_ListUsersServer) error { users, err := s.Repo.ListUsers(stream.Context(), int(req.GetPageSize())) if err != nil { return status.Error(codes.Internal, "internal error") }
for _, u := range users {
select {
case <-stream.Context().Done():
return stream.Context().Err()
default:
}
if err := stream.Send(&usersv1.User{
Id: u.ID,
Email: u.Email,
DisplayName: u.DisplayName,
}); err != nil {
return err
}
}
return nil
}
Unary vs streaming decision Use unary for single request/response and simple retries. Use server streaming for large result sets or continuous updates. Use client streaming for bulk uploads with one final response. Use bidirectional streaming for interactive protocols. Production Hardening Health checks and reflection
Add health service; enable reflection only in non-production environments.
✅ Correct: health + conditional reflection
hs := health.NewServer() grpc_health_v1.RegisterHealthServer(s, hs)
if env != "production" { reflection.Register(s) }
Graceful shutdown
Prefer GracefulStop with a deadline.
✅ Correct: graceful stop
stopped := make(chan struct{}) go func() { grpcServer.GracefulStop() close(stopped) }()
select { case <-stopped: case <-time.After(10 * time.Second): grpcServer.Stop() }
TLS
Use TLS (or mTLS) in production; avoid insecure credentials outside local dev.
✅ Correct: server TLS
creds, err := credentials.NewServerTLSFromFile("server.crt", "server.key") if err != nil { return err }
grpcServer := grpc.NewServer(grpc.Creds(creds))
Testing (bufconn)
Test gRPC handlers without opening real sockets using bufconn.
✅ Correct: in-memory gRPC test server
const bufSize = 1024 * 1024
lis := bufconn.Listen(bufSize) srv := grpc.NewServer() usersv1.RegisterUsersServiceServer(srv, &Service{Repo: repo})
go func() { _ = srv.Serve(lis) }()
ctx := context.Background() conn, err := grpc.DialContext( ctx, "bufnet", grpc.WithContextDialer(func(context.Context, string) (net.Conn, error) { return lis.Dial() }), grpc.WithTransportCredentials(insecure.NewCredentials()), ) if err != nil { t.Fatal(err) } defer conn.Close()
client := usersv1.NewUsersServiceClient(conn) resp, err := client.GetUser(ctx, &usersv1.GetUserRequest{Id: "1"}) _ = resp _ = err
Anti-Patterns
Ignore deadlines: unbounded handlers cause tail latency and resource exhaustion.
Return string errors: map domain errors to codes.* with status.Error or status.Errorf.
Stream without backpressure: stop on ctx.Done() and handle Send errors.
Expose reflection in production: treat reflection as a discovery surface.
Troubleshooting Symptom: clients see UNKNOWN errors
Actions:
Return status.Error(codes.X, "...") instead of raw errors. Wrap domain errors into typed errors, then map to gRPC codes. Symptom: slow/hanging requests
Actions:
Require deadlines and propagate ctx to downstream calls. Add server-side timeouts and bounded concurrency in repositories. Symptom: flaky streaming
Actions:
Stop streaming on ctx.Done() and handle stream.Send errors. Avoid buffering entire result sets before sending. Resources gRPC Go: https://github.com/grpc/grpc-go Protobuf Go: https://pkg.go.dev/google.golang.org/protobuf gRPC error codes: https://grpc.io/docs/guides/error/