All posts

Building High-Performance Microservices with gRPC in Go

July 3, 2026
Building High-Performance Microservices with gRPC in Go

gRPC is a high-performance, open-source universal RPC framework initially developed by Google. It leverages HTTP/2 for transport, Protocol Buffers as the interface description language, and provides features such as authentication, load balancing, and bi-directional streaming. In the Go ecosystem, gRPC is a first-class citizen, offering excellent tooling and performance characteristics for building microservices.

Why gRPC over REST?

While RESTful APIs are ubiquitous, they have limitations in terms of performance and type safety. gRPC addresses these by:

  • Binary protocol: Protocol Buffers serialize data into a compact binary format, reducing payload size and parsing overhead compared to JSON.
  • HTTP/2 multiplexing: Multiple requests can be sent concurrently over a single connection, eliminating head-of-line blocking.
  • Strong typing: Service definitions are written in .proto files, generating client and server stubs that ensure compile-time safety.
  • Streaming: gRPC supports client-side, server-side, and bidirectional streaming, enabling real-time data flows.

Defining a Service with Protocol Buffers

The foundation of any gRPC service is the .proto file. Here's a simple example for a user service:

syntax = "proto3";

package user;

service UserService {
  rpc GetUser (GetUserRequest) returns (User);
  rpc ListUsers (ListUsersRequest) returns (stream User);
}

message GetUserRequest {
  string user_id = 1;
}

message ListUsersRequest {
  int32 page_size = 1;
  string page_token = 2;
}

message User {
  string user_id = 1;
  string name = 2;
  string email = 3;
}

This defines a service with two RPCs: a unary call to fetch a single user and a server-streaming call to list users.

Generating Go Code

Install the necessary tools:

go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest

Then generate the Go code:

protoc --go_out=. --go-grpc_out=. user.proto

This produces two files: user.pb.go (message types) and user_grpc.pb.go (client and server interfaces).

Implementing the Server

Here's a server implementation for the UserService:

package main

import (
	"context"
	"log"
	"net"

	"google.golang.org/grpc"
	pb "path/to/your/protobuf/package"
)

type userServer struct {
	pb.UnimplementedUserServiceServer
}

func (s *userServer) GetUser(ctx context.Context, req *pb.GetUserRequest) (*pb.User, error) {
	// Simulate fetching from database
	return &pb.User{
		UserId: req.UserId,
		Name:   "John Doe",
		Email:  "john@example.com",
	}, nil
}

func (s *userServer) ListUsers(req *pb.ListUsersRequest, stream pb.UserService_ListUsersServer) error {
	// Simulate streaming multiple users
	users := []*pb.User{
		{UserId: "1", Name: "Alice", Email: "alice@example.com"},
		{UserId: "2", Name: "Bob", Email: "bob@example.com"},
	}
	for _, user := range users {
		if err := stream.Send(user); err != nil {
			return err
		}
	}
	return nil
}

func main() {
	lis, err := net.Listen("tcp", ":50051")
	if err != nil {
		log.Fatalf("failed to listen: %v", err)
	}
	s := grpc.NewServer()
	pb.RegisterUserServiceServer(s, &userServer{})
	log.Printf("server listening at %v", lis.Addr())
	if err := s.Serve(lis); err != nil {
		log.Fatalf("failed to serve: %v", err)
	}
}

Key points:

  • We embed pb.UnimplementedUserServiceServer to ensure forward compatibility.
  • The ListUsers method receives a stream object to send multiple responses.

Building the Client

The client is equally straightforward:

package main

import (
	"context"
	"log"
	"time"

	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials/insecure"
	pb "path/to/your/protobuf/package"
)

func main() {
	conn, err := grpc.Dial("localhost:50051", grpc.WithTransportCredentials(insecure.NewCredentials()))
	if err != nil {
		log.Fatalf("did not connect: %v", err)
	}
	defer conn.Close()

	client := pb.NewUserServiceClient(conn)

	// Unary call
	ctx, cancel := context.WithTimeout(context.Background(), time.Second)
	defer cancel()
	user, err := client.GetUser(ctx, &pb.GetUserRequest{UserId: "123"})
	if err != nil {
		log.Fatalf("could not get user: %v", err)
	}
	log.Printf("User: %s (%s)", user.Name, user.Email)

	// Server streaming call
	stream, err := client.ListUsers(ctx, &pb.ListUsersRequest{PageSize: 10})
	if err != nil {
		log.Fatalf("could not list users: %v", err)
	}
	for {
		user, err := stream.Recv()
		if err != nil {
			break
		}
		log.Printf("Received user: %s", user.Name)
	}
}

Note: In production, always use TLS. The insecure.NewCredentials() is for development only.

Error Handling and Interceptors

gRPC provides rich error handling via status codes. Use status.Errorf to return detailed errors:

import "google.golang.org/grpc/status"
import "google.golang.org/grpc/codes"

func (s *userServer) GetUser(ctx context.Context, req *pb.GetUserRequest) (*pb.User, error) {
	if req.UserId == "" {
		return nil, status.Errorf(codes.InvalidArgument, "user_id cannot be empty")
	}
	// ...
}

Interceptors are middleware for cross-cutting concerns like logging, authentication, and metrics. Example server-side interceptor:

func loggingInterceptor(ctx context.Context, req interface{}, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (interface{}, error) {
	log.Printf("gRPC call: %s", info.FullMethod)
	resp, err := handler(ctx, req)
	log.Printf("Completed: %s", info.FullMethod)
	return resp, err
}

// In main:
s := grpc.NewServer(grpc.UnaryInterceptor(loggingInterceptor))

Performance Considerations

  • Connection pooling: Use a single long-lived gRPC connection per client; it handles multiplexing.
  • Message size limits: Default is 4 MB; adjust with grpc.MaxRecvMsgSize and grpc.MaxSendMsgSize.
  • Streaming: Prefer streaming for large datasets to avoid memory bloat.
  • Deadlines: Always set a deadline on the client context to prevent resource leaks.

Conclusion

gRPC in Go offers a powerful, type-safe, and high-performance alternative to REST for inter-service communication. With Protocol Buffers, automatic code generation, and built-in streaming, it's an excellent choice for microservices architectures. The Go ecosystem provides robust tooling and a mature gRPC library, making it straightforward to adopt. Start with the official gRPC Go documentation and experiment with the examples provided.

Related posts