Modern applications often consist of multiple services that need to communicate quickly and reliably. REST APIs are widely used for this purpose, but they are not the only option.

Another popular technology is gRPC.

gRPC is a high-performance Remote Procedure Call framework commonly used for communication between backend services and microservices. Instead of manually designing JSON endpoints such as /users or /orders, developers define services and messages using Protocol Buffers, commonly called Protobuf.

From that definition, gRPC can generate strongly typed client and server code for multiple programming languages.

Go works particularly well with gRPC because both are widely used in cloud-native systems, microservices, distributed applications, Kubernetes environments, and backend infrastructure.

In this guide, you will learn what gRPC is, how it works, how Protocol Buffers work, how to install the required tools, create your first Go gRPC server and client, understand unary and streaming RPCs, handle errors, deadlines, metadata, authentication, interceptors, TLS, testing, project structure, and production best practices.

What Is gRPC?

gRPC is a framework for Remote Procedure Calls.

RPC stands for:

Remote Procedure Call

The basic idea is simple.

Suppose one application has a function:

GetUser(10)

but the actual user service is running on another server.

With RPC, your application can call a remote service in a way that feels similar to calling a local function.

Conceptually:

Go Client
    |
    | GetUser(10)
    v
Network
    |
    v
Go gRPC Server
    |
    v
GetUser()
    |
    v
Database

gRPC handles much of the communication infrastructure between the client and server.

What Does gRPC Stand For?

The project uses the name:

gRPC

It is commonly described as a modern Remote Procedure Call framework.

For beginners, the important part is understanding RPC: calling functionality provided by another service over a network.

Why Use gRPC with Go?

Go and gRPC are frequently used together for backend and microservice development.

Important benefits include:

Strongly typed APIs
Protocol Buffers
Code generation
HTTP/2-based transport
Streaming support
Deadlines and cancellation
Multiple language support
Efficient binary serialization
Good fit for service-to-service communication

A common architecture is:

Mobile / Web
     |
     | REST / HTTP
     v
API Gateway
     |
     | gRPC
     v
+----+---------+---------+
|              |         |
v              v         v
User         Order     Payment
Service      Service    Service

REST may be exposed publicly while gRPC handles internal service communication.

This is only one architecture; gRPC can also be exposed directly when the client environment supports it.

What Is Protocol Buffers?

Protocol Buffers, or Protobuf, is a language-neutral data serialization format.

With gRPC, you normally define your API in a:

.proto

file.

For example:

syntax = "proto3";

package user;

message UserRequest {
  int64 id = 1;
}

message UserResponse {
  int64 id = 1;
  string name = 2;
  string email = 3;
}

This describes the structure of your messages.

Why Does Protobuf Use Numbers?

Notice:

int64 id = 1;
string name = 2;
string email = 3;

The numbers:

1
2
3

are field numbers.

They identify fields in the binary representation.

Once a field number has been used in a published schema, avoid changing or reusing it for a different meaning.

For example, if you remove:

string email = 3;

do not later reuse field number 3 for an unrelated field.

You can reserve removed fields:

reserved 3;
reserved "email";

This helps prevent accidental schema conflicts.

Protobuf vs JSON

A REST API often sends JSON:

{
  "id": 10,
  "name": "Ankit",
  "email": "user@example.com"
}

gRPC commonly uses Protobuf binary messages.

JSON is human-readable and extremely convenient for public web APIs.

Protobuf is compact, strongly structured, and designed for efficient serialization.

A simplified comparison:

Feature	gRPC + Protobuf	REST + JSON
Data format	Usually Protobuf	Usually JSON
Human readable	No	Yes
API contract	Strong `.proto` schema	Depends on API design
Code generation	Built in workflow	Optional
Streaming	Strong support	Requires other approaches
Browser friendliness	Requires additional considerations	Excellent
Internal microservices	Excellent	Excellent
Public APIs	Possible	Very common

Neither automatically replaces the other.

How Does Go gRPC Work?

The workflow usually looks like:

Create .proto File
       ↓
Define Messages
       ↓
Define Service
       ↓
Run Protobuf Compiler
       ↓
Generate Go Code
       ↓
Implement Server
       ↓
Create Client
       ↓
Call RPC

The .proto file becomes the contract between services.

What Is a gRPC Service?

A service defines operations clients can call.

Example:

service UserService {
  rpc GetUser(UserRequest)
      returns (UserResponse);
}

This defines:

Method:
GetUser

Input:
UserRequest

Output:
UserResponse

The Go gRPC tooling generates the required interfaces and client code.

Types of gRPC Communication

gRPC supports four major RPC patterns:

Unary RPC
Server Streaming
Client Streaming
Bidirectional Streaming

Understanding these four patterns is one of the most important parts of learning gRPC.

1. Unary RPC

Unary RPC is the simplest.

One request produces one response.

Client
  |
  | Request
  v
Server
  |
  | Response
  v
Client

Example:

GetUser
CreateOrder
GetProduct
ValidateToken

Proto:

rpc GetUser(UserRequest)
    returns (UserResponse);

This is conceptually similar to many traditional HTTP request-response APIs.

2. Server Streaming RPC

The client sends one request.

The server sends multiple responses.

Client
  |
  | Request
  v
Server
  |
  | Response 1
  | Response 2
  | Response 3
  v
Client

Proto:

rpc ListUsers(UserListRequest)
    returns (stream UserResponse);

Potential uses include:

Large result streams
Live updates
Logs
Progress updates
Data feeds

3. Client Streaming RPC

The client sends multiple messages.

The server eventually returns one response.

Client
  |
  | Message 1
  | Message 2
  | Message 3
  v
Server
  |
  | Final Response
  v
Client

Proto:

rpc UploadData(stream DataChunk)
    returns (UploadResponse);

Potential uses include sending a sequence of chunks or events to a service.

4. Bidirectional Streaming RPC

Both client and server can send streams of messages.

Client <------> Server
Client <------> Server
Client <------> Server

Proto:

rpc Chat(stream ChatMessage)
    returns (stream ChatMessage);

Potential use cases include:

Real-time communication
Interactive services
Streaming systems
Live event exchange

Install Go

Verify Go:

go version

If Go is installed correctly, you should see your installed version.

Install Protocol Buffer Compiler

gRPC code generation requires the Protocol Buffer compiler:

protoc

Check:

protoc --version

On macOS with Homebrew:

brew install protobuf

On Linux, use your distribution’s supported package installation method or the official Protobuf installation instructions.

Windows users can install the official Protobuf compiler and add its executable directory to PATH.

Always verify:

protoc --version

Install Go Protobuf Plugins

Install the Go message generator:

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

Install the Go gRPC generator:

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

The resulting binaries need to be available through your shell’s PATH.

Check:

which protoc-gen-go

and:

which protoc-gen-go-grpc

On Windows, use the equivalent command for locating executables.

Create a Go gRPC Project

Create:

mkdir go-grpc-example
cd go-grpc-example

Initialize:

go mod init example.com/go-grpc-example

Create folders:

go-grpc-example/
│
├── proto/
├── server/
├── client/
└── go.mod

Install gRPC Dependencies

Run:

go get google.golang.org/grpc

Also add Protobuf support:

go get google.golang.org/protobuf

Then:

go mod tidy

Create Your First `.proto` File

Create:

proto/user.proto

Add:

syntax = "proto3";

package user;

option go_package =
  "example.com/go-grpc-example/proto;userpb";

message UserRequest {
  int64 id = 1;
}

message UserResponse {
  int64 id = 1;
  string name = 2;
  string email = 3;
}

service UserService {
  rpc GetUser(UserRequest)
      returns (UserResponse);
}

Understanding `go_package`

This line:

option go_package =
  "example.com/go-grpc-example/proto;userpb";

helps the generator understand the Go import path and package name.

Here:

example.com/go-grpc-example/proto

is the Go import path.

And:

userpb

is the generated Go package name.

For real projects, make the import path match your actual Go module.

Generate Go Code from Protobuf

From the project root, run:

protoc \
  --go_out=. \
  --go_opt=paths=source_relative \
  --go-grpc_out=. \
  --go-grpc_opt=paths=source_relative \
  proto/user.proto

This generates files similar to:

proto/
├── user.proto
├── user.pb.go
└── user_grpc.pb.go

Do not manually edit generated files.

Change the .proto definition and regenerate instead.

What Is Generated?

user.pb.go contains generated Go types for your Protobuf messages.

For example, conceptually:

type UserRequest struct {
	Id int64
}

user_grpc.pb.go contains gRPC client and server definitions.

The generated code handles much of the low-level RPC plumbing.

Create a Go gRPC Server

Create:

server/main.go

Add:

package main

import (
	"context"
	"log"
	"net"

	userpb "example.com/go-grpc-example/proto"

	"google.golang.org/grpc"
)

type userServer struct {
	userpb.UnimplementedUserServiceServer
}

func (s *userServer) GetUser(
	ctx context.Context,
	req *userpb.UserRequest,
) (*userpb.UserResponse, error) {

	log.Printf(
		"GetUser called with ID: %d",
		req.GetId(),
	)

	return &userpb.UserResponse{
		Id:    req.GetId(),
		Name:  "Ankit",
		Email: "user@example.com",
	}, nil
}

func main() {
	listener, err :=
		net.Listen(
			"tcp",
			":50051",
		)

	if err != nil {
		log.Fatalf(
			"failed to listen: %v",
			err,
		)
	}

	grpcServer :=
		grpc.NewServer()

	userpb.RegisterUserServiceServer(
		grpcServer,
		&userServer{},
	)

	log.Println(
		"gRPC server running on :50051",
	)

	if err :=
		grpcServer.Serve(
			listener,
		);
		err != nil {

		log.Fatalf(
			"server failed: %v",
			err,
		)
	}
}

Why Embed `UnimplementedUserServiceServer`?

The generated package provides:

userpb.UnimplementedUserServiceServer

Embedding it is the recommended forward-compatible pattern for implementing generated gRPC server interfaces.

Your struct becomes:

type userServer struct {
	userpb.UnimplementedUserServiceServer
}

Then you implement the RPC methods you need.

Start the gRPC Server

Run:

go run ./server

You should see:

gRPC server running on :50051

Your server is ready.

Create the Go gRPC Client

Create:

client/main.go

Add:

package main

import (
	"context"
	"log"
	"time"

	userpb "example.com/go-grpc-example/proto"

	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials/insecure"
)

func main() {
	conn, err :=
		grpc.NewClient(
			"localhost:50051",
			grpc.WithTransportCredentials(
				insecure.NewCredentials(),
			),
		)

	if err != nil {
		log.Fatalf(
			"failed to create client: %v",
			err,
		)
	}

	defer conn.Close()

	client :=
		userpb.NewUserServiceClient(
			conn,
		)

	ctx, cancel :=
		context.WithTimeout(
			context.Background(),
			5*time.Second,
		)

	defer cancel()

	response, err :=
		client.GetUser(
			ctx,
			&userpb.UserRequest{
				Id: 10,
			},
		)

	if err != nil {
		log.Fatalf(
			"GetUser failed: %v",
			err,
		)
	}

	log.Printf(
		"User: %d %s %s",
		response.GetId(),
		response.GetName(),
		response.GetEmail(),
	)
}

Run the Client

Keep the server running.

In another terminal:

go run ./client

You should receive a response containing the user information.

The communication flow is:

Go Client
   |
   | UserRequest
   v
gRPC
   |
   v
Go Server
   |
   | UserResponse
   v
Go Client

Congratulations—you have built your first Go gRPC application.

Why Use Context in gRPC?

Most generated Go gRPC client calls accept:

context.Context

Context is important for:

Deadlines
Timeouts
Cancellation
Metadata propagation
Tracing
Request lifecycle management

Avoid using unlimited request durations for production RPC calls.

gRPC Deadlines

Suppose Service A calls Service B.

Without a deadline:

Service A
   |
   v
Service B
   |
   v
Wait indefinitely

This can cause resource exhaustion during failures.

Use:

ctx, cancel :=
	context.WithTimeout(
		context.Background(),
		2*time.Second,
	)

defer cancel()

Then:

response, err :=
	client.GetUser(
		ctx,
		request,
	)

If the operation exceeds the deadline, it fails rather than waiting forever.

Deadline Propagation

Imagine:

API
 |
 v
Order Service
 |
 v
Payment Service
 |
 v
Fraud Service

Each downstream operation should respect the request’s remaining time budget.

Passing context through service layers helps propagate cancellation and deadlines.

gRPC Status Codes

gRPC has its own standard status codes.

Common examples include:

OK
InvalidArgument
NotFound
AlreadyExists
PermissionDenied
Unauthenticated
ResourceExhausted
FailedPrecondition
Unavailable
Internal
DeadlineExceeded

Instead of returning generic errors everywhere, use appropriate gRPC status codes.

Return a `NotFound` Error

Example:

return nil,
	status.Error(
		codes.NotFound,
		"user not found",
	)

Imports:

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

Invalid Argument Example

if req.GetId() <= 0 {
	return nil,
		status.Error(
			codes.InvalidArgument,
			"user ID must be greater than zero",
		)
}

This allows clients to distinguish invalid input from server failures.

Handle gRPC Errors on the Client

Example:

response, err :=
	client.GetUser(
		ctx,
		request,
	)

if err != nil {
	st, ok :=
		status.FromError(err)

	if ok {
		log.Printf(
			"gRPC error: code=%s message=%s",
			st.Code(),
			st.Message(),
		)
	}

	return
}

Clients can make decisions based on status codes.

gRPC Metadata

Metadata allows clients and servers to exchange additional request information.

Examples include:

Authentication token
Request ID
Trace information
Client version
Locale

Metadata is conceptually similar to HTTP headers.

Send Metadata from Client

Example:

md :=
	metadata.Pairs(
		"authorization",
		"Bearer TOKEN",
	)

ctx :=
	metadata.NewOutgoingContext(
		context.Background(),
		md,
	)

Then use that context when making the RPC.

Read Metadata on Server

Example:

md, ok :=
	metadata.FromIncomingContext(
		ctx,
	)

if !ok {
	return nil,
		status.Error(
			codes.Unauthenticated,
			"metadata missing",
		)
}

Then retrieve values:

values :=
	md.Get(
		"authorization",
	)

Never log access tokens.

Authentication with gRPC

A common authentication flow is:

Client
   |
   | Token in Metadata
   v
gRPC Server
   |
   v
Authentication Interceptor
   |
   +---- Invalid → Unauthenticated
   |
   v
RPC Handler

Rather than repeating authentication code inside every RPC, interceptors can handle common logic.

What Are gRPC Interceptors?

Interceptors are middleware-like components.

For unary RPCs:

Request
  |
  v
Logging Interceptor
  |
  v
Authentication Interceptor
  |
  v
RPC Handler

They can be used for:

Authentication
Authorization
Logging
Metrics
Tracing
Rate limiting
Error handling
Request IDs

Unary Server Interceptor

Example:

func loggingInterceptor(
	ctx context.Context,
	req any,
	info *grpc.UnaryServerInfo,
	handler grpc.UnaryHandler,
) (any, error) {

	log.Printf(
		"gRPC method: %s",
		info.FullMethod,
	)

	return handler(
		ctx,
		req,
	)
}

Add it:

grpcServer :=
	grpc.NewServer(
		grpc.UnaryInterceptor(
			loggingInterceptor,
		),
	)

Stream Interceptors

Streaming RPCs have separate interceptors.

Use:

grpc.StreamInterceptor(...)

for streaming operations.

If your application uses both unary and streaming RPCs, you may need both interceptor types.

Multiple Interceptors

Production applications often require several interceptors.

For example:

Recovery
Authentication
Logging
Metrics
Tracing

gRPC provides interceptor chaining support, or you can use suitable middleware libraries.

Keep the order intentional because interceptor ordering can affect behavior.

Server Streaming Example

Update your proto:

message UserListRequest {}

service UserService {
  rpc GetUser(UserRequest)
      returns (UserResponse);

  rpc ListUsers(UserListRequest)
      returns (stream UserResponse);
}

Regenerate the Go files after changing the .proto file.

Server Streaming Implementation

The exact generated method signature depends on your installed gRPC-Go code-generation version.

Conceptually, the implementation sends multiple messages:

func (s *userServer) ListUsers(
	req *userpb.UserListRequest,
	stream userpb.UserService_ListUsersServer,
) error {

	users := []*userpb.UserResponse{
		{
			Id:   1,
			Name: "User One",
		},
		{
			Id:   2,
			Name: "User Two",
		},
	}

	for _, user :=
		range users {

		if err :=
			stream.Send(user);
			err != nil {

			return err
		}
	}

	return nil
}

With newer generated APIs, the signature may use a generic server-streaming type. Follow the generated interface in your project.

Receive Server Stream on Client

Conceptually:

stream, err :=
	client.ListUsers(
		ctx,
		&userpb.UserListRequest{},
	)

if err != nil {
	return
}

for {
	user, err :=
		stream.Recv()

	if errors.Is(
		err,
		io.EOF,
	) {
		break
	}

	if err != nil {
		return
	}

	fmt.Println(
		user.GetName(),
	)
}

The client continues receiving messages until the stream ends.

Client Streaming

Define:

message DataChunk {
  bytes data = 1;
}

message UploadResponse {
  int64 bytes_received = 1;
}

service UploadService {
  rpc Upload(stream DataChunk)
      returns (UploadResponse);
}

The client can send multiple chunks:

Chunk 1
Chunk 2
Chunk 3
Chunk 4
   |
   v
Server
   |
   v
UploadResponse

This can be useful for streaming sequences of data.

Bidirectional Streaming

Define:

service ChatService {
  rpc Chat(stream ChatMessage)
      returns (stream ChatMessage);
}

Now both sides can send messages independently.

Conceptually:

Client --------> Server
Client <-------- Server
Client --------> Server
Client <-------- Server

Bidirectional streaming requires careful handling of:

Concurrency
Cancellation
Errors
Backpressure
Connection lifecycle

gRPC Uses HTTP/2

gRPC commonly uses HTTP/2 as its transport.

HTTP/2 provides capabilities useful to gRPC, including multiplexed streams.

Multiple RPCs can share a connection efficiently.

However, developers should not assume that HTTP/2 alone automatically makes every application faster. Database queries, network topology, message sizes, code quality, and architecture also affect performance.

Connection Reuse

Do not create a new gRPC client connection for every request unless there is a specific reason.

Prefer long-lived client connections that can be reused.

Bad pattern:

Request
  ↓
Create Connection
  ↓
RPC
  ↓
Close Connection

Better:

Application Starts
       ↓
Create gRPC Client
       ↓
Reuse Client
       ↓
Many RPC Calls
       ↓
Application Stops

gRPC and Microservices

Consider an e-commerce system:

API Gateway
     |
     +------> User Service
     |
     +------> Product Service
     |
     +------> Order Service
                    |
                    +------> Payment Service
                    |
                    +------> Inventory Service

Internal services can communicate through gRPC.

For example:

Order Service
     |
     | CheckInventory()
     v
Inventory Service

and:

Order Service
     |
     | CreatePayment()
     v
Payment Service

Strong contracts make service boundaries explicit.

gRPC vs REST

This is one of the most common questions.

REST commonly looks like:

GET /users/10

Response:

{
  "id": 10,
  "name": "Ankit"
}

gRPC might define:

rpc GetUser(UserRequest)
    returns (UserResponse);

Then call:

client.GetUser(
	ctx,
	&userpb.UserRequest{
		Id: 10,
	},
)

When Should You Use REST?

REST is often a strong choice when:

You need a public HTTP API
Browser compatibility is important
Human-readable JSON is useful
External integrations expect REST
Simple HTTP tooling matters

When Should You Use gRPC?

gRPC is often a strong choice when:

Services communicate internally
Strong API contracts are important
Multiple languages share the API
Streaming is required
Efficient binary serialization matters
You have many service-to-service calls

Can REST and gRPC Be Used Together?

Absolutely.

A common architecture is:

Web / Mobile
     |
     | HTTPS + JSON
     v
API Gateway
     |
     | gRPC
     v
Backend Services

This provides a familiar public interface while allowing internal services to use gRPC.

gRPC and Browsers

Traditional browser clients cannot always consume a standard native gRPC service in exactly the same way as a Go backend client.

Solutions include browser-compatible gRPC approaches and gateway/proxy layers.

Therefore, REST/JSON is still common for browser-facing APIs.

Design based on your client requirements rather than automatically choosing one protocol everywhere.

gRPC Gateway

Some Go architectures use a gateway that exposes REST/JSON while forwarding requests to gRPC services.

Conceptually:

REST Client
    |
    v
HTTP/JSON Gateway
    |
    v
gRPC Service

This can reduce duplication when you need both REST and gRPC interfaces.

Database Integration

Your gRPC handler can call a database just like an HTTP handler.

Architecture:

gRPC Client
    |
    v
gRPC Handler
    |
    v
Service Layer
    |
    v
Repository
    |
    v
PostgreSQL

Do not put all database logic directly inside generated service handlers.

Recommended Layered Architecture

For larger applications:

Transport
   |
   v
Service
   |
   v
Repository
   |
   v
Database

The transport may be:

gRPC

today and possibly:

REST

later.

Your core business logic should not depend unnecessarily on transport details.

Example Service Layer

type UserService struct {
	repository UserRepository
}

func (
	s *UserService,
) GetUser(
	ctx context.Context,
	id int64,
) (*User, error) {

	return s.repository.FindByID(
		ctx,
		id,
	)
}

Then the gRPC handler converts between:

Protobuf Message
      ↕
Domain Model

This keeps responsibilities clean.

Validation

Never trust client input.

Example:

if req.GetId() <= 0 {
	return nil,
		status.Error(
			codes.InvalidArgument,
			"invalid user ID",
		)
}

Validate:

Required values
Ranges
String lengths
Formats
Business rules

before performing sensitive operations.

Protobuf Schema Evolution

One major benefit of Protobuf is that schemas can evolve when compatibility rules are followed.

Suppose version 1 contains:

message User {
  int64 id = 1;
  string name = 2;
}

Later you add:

string email = 3;

Older clients can generally continue working because they simply do not know about the new field.

Do Not Renumber Existing Fields

Bad:

string name = 2;

changed to:

string name = 5;

Changing field numbers can break compatibility.

Once published, treat field numbers as stable identifiers.

Reserve Removed Fields

If:

string username = 3;

is removed, use:

reserved 3;
reserved "username";

This prevents future developers from accidentally reusing it.

Avoid Huge Messages

Do not send enormous messages merely because Protobuf supports structured binary data.

Large messages can increase:

Memory usage
Latency
Network usage
Processing time

For large datasets, consider pagination or streaming.

For large files, dedicated object storage may be a better architecture than transporting everything through an RPC.

gRPC Message Size Limits

gRPC implementations have message size limits.

If your application genuinely needs large messages, limits can be configured, but increasing them without understanding memory and network implications can create problems.

Prefer appropriate architecture over simply making every limit larger.

TLS with Go gRPC

The earlier local example used:

insecure.NewCredentials()

That is appropriate for a simple local learning environment.

Do not use plaintext transport across untrusted production networks.

Production systems should use TLS when required by their architecture.

Server TLS Concept

Load a certificate:

creds, err :=
	credentials.NewServerTLSFromFile(
		"server.crt",
		"server.key",
	)

if err != nil {
	log.Fatal(err)
}

Create server:

grpcServer :=
	grpc.NewServer(
		grpc.Creds(creds),
	)

Now the gRPC server uses TLS.

Client TLS Concept

The client must trust the server certificate.

Example:

creds, err :=
	credentials.NewClientTLSFromFile(
		"ca.crt",
		"",
	)

if err != nil {
	log.Fatal(err)
}

Then:

conn, err :=
	grpc.NewClient(
		"service.example.com:443",
		grpc.WithTransportCredentials(
			creds,
		),
	)

Certificate configuration depends on your infrastructure and PKI.

What Is mTLS?

mTLS means:

Mutual TLS

With normal TLS:

Client verifies Server

With mTLS:

Client verifies Server
AND
Server verifies Client

mTLS can be useful for service-to-service identity in certain production architectures.

Authentication vs TLS

TLS protects communication and can authenticate endpoints.

Application authentication answers questions such as:

Which user is making this request?
What permissions does the user have?

Do not assume TLS alone replaces authorization.

A system may use:

TLS/mTLS
+
JWT/OAuth/service identity
+
Authorization policies

depending on its security model.

Graceful Shutdown

Production gRPC servers should shut down gracefully.

Listen for termination signals:

ctx, stop :=
	signal.NotifyContext(
		context.Background(),
		os.Interrupt,
		syscall.SIGTERM,
	)

defer stop()

<-ctx.Done()

Then:

grpcServer.GracefulStop()

This allows active RPCs to finish where possible.

`Stop()` vs `GracefulStop()`

GracefulStop() attempts to finish existing RPCs before shutting down.

Stop() stops the server immediately.

A production application may use graceful shutdown with an overall timeout strategy so shutdown cannot hang forever.

Health Checks

Cloud platforms and load balancers need to know whether a gRPC service is healthy.

The gRPC ecosystem provides a standard health checking protocol.

Conceptually:

Load Balancer
     |
     | Health Check
     v
gRPC Service
     |
     v
SERVING

This is preferable to inventing a different health protocol for every gRPC service.

Reflection

gRPC reflection allows supported tools to discover services at runtime.

It can be enabled in Go:

import (
	"google.golang.org/grpc/reflection"
)

Then:

reflection.Register(
	grpcServer,
)

Reflection is extremely useful during development.

Consider your security requirements before exposing it in sensitive production environments.

Testing with grpcurl

grpcurl is a useful command-line tool for interacting with gRPC servers.

If reflection is enabled, you can inspect services.

For a local plaintext server, conceptually:

grpcurl \
  -plaintext \
  localhost:50051 \
  list

Then inspect a service or invoke an RPC.

This is similar to how developers use curl when working with REST APIs.

Testing Go gRPC Services

Go’s testing package can test service logic.

Example:

func TestGetUser(
	t *testing.T,
) {
	server :=
		&userServer{}

	response, err :=
		server.GetUser(
			context.Background(),
			&userpb.UserRequest{
				Id: 1,
			},
		)

	if err != nil {
		t.Fatal(err)
	}

	if response.GetId() != 1 {
		t.Fatalf(
			"expected ID 1, got %d",
			response.GetId(),
		)
	}
}

For more realistic tests, test the service through an actual in-memory or local gRPC transport.

In-Memory Testing

Go’s networking/testing ecosystem allows you to test gRPC clients and servers without opening normal external network ports.

This can make integration tests:

Fast
Repeatable
Isolated
CI-friendly

Keep business logic testable independently from transport code as well.

Mocking gRPC Clients

Suppose your Order Service depends on Payment Service.

Instead of requiring the real Payment Service for every unit test, define a small interface around the operations your code needs.

Example:

type PaymentClient interface {
	CreatePayment(
		ctx context.Context,
		request *CreatePaymentRequest,
	) (*PaymentResponse, error)
}

Then tests can provide a fake implementation.

This keeps tests focused and fast.

Logging

Do not print random messages throughout a production service.

Use structured logging.

Go provides:

log/slog

Example:

slog.Info(
	"gRPC request completed",
	"method",
	"GetUser",
	"user_id",
	req.GetId(),
)

Never log:

Passwords
Access tokens
Private keys
Sensitive personal data
Full payment information

Metrics

Useful gRPC metrics include:

RPC request count
RPC error count
Request duration
Active streams
Message count
Deadline exceeded count
Retry count

Infrastructure metrics may include:

CPU
Memory
Network
Container restarts

Distributed Tracing

In microservices:

Gateway
   |
   v
Order Service
   |
   v
Payment Service
   |
   v
Fraud Service

it can be difficult to determine where a request became slow.

Distributed tracing can show:

Gateway          20ms
Order Service    40ms
Payment Service  80ms
Fraud Service   300ms

This makes performance problems easier to investigate.

OpenTelemetry

OpenTelemetry is commonly used to instrument distributed systems.

A Go gRPC service can use OpenTelemetry-compatible instrumentation for:

Tracing
Metrics
Context propagation

Interceptors are a natural place to add observability.

Retries

gRPC applications may encounter temporary errors such as:

Unavailable
Temporary network failure
Service restart

Retries can help, but they must be used carefully.

Use:

Limited retries
Backoff
Jitter
Deadlines
Retryable status codes

Do not retry every operation automatically.

Why Retries Can Be Dangerous

Suppose:

CreatePayment()

succeeds on the server, but the response is lost.

The client retries.

Without idempotency:

Payment 1 created
Payment 2 created

Critical write operations should therefore be designed with idempotency in mind.

Load Balancing

A service may run multiple instances:

             Client
                |
                v
          Load Balancer
                |
       +--------+--------+
       |        |        |
       v        v        v
    User 1   User 2   User 3

In Kubernetes or cloud environments, service discovery and load balancing can route traffic among healthy instances.

gRPC’s use of long-lived HTTP/2 connections means load-balancing behavior should be considered carefully rather than assuming HTTP/1-style request distribution.

gRPC with Kubernetes

Go gRPC services work well in Kubernetes.

Example:

Kubernetes Service
       |
       v
+------+------+------+
|      |      |      |
v      v      v      v
Pod    Pod    Pod    Pod

Important considerations include:

Health checks
Readiness
Graceful shutdown
TLS
Service discovery
Load balancing
Resource limits
Observability

gRPC with Docker

A Go gRPC application can be containerized like any other Go service.

Example:

FROM golang:1.25 AS builder

WORKDIR /app

COPY go.mod go.sum ./
RUN go mod download

COPY . .

RUN CGO_ENABLED=0 \
    GOOS=linux \
    go build \
    -o /server \
    ./server

FROM gcr.io/distroless/static-debian12:nonroot

COPY --from=builder \
    /server \
    /server

EXPOSE 50051

ENTRYPOINT ["/server"]

Use a Go version compatible with your project.

Recommended Project Structure

A larger project might use:

go-grpc-app/
│
├── api/
│   └── proto/
│       └── user.proto
│
├── cmd/
│   ├── server/
│   │   └── main.go
│   └── client/
│       └── main.go
│
├── internal/
│   ├── grpcserver/
│   ├── service/
│   ├── repository/
│   ├── database/
│   ├── auth/
│   └── config/
│
├── gen/
│   └── user/
│
├── go.mod
└── go.sum

Exact structure depends on project size.

Do not create dozens of packages for a tiny learning project.

Separate Generated Code

Keeping generated Protobuf code separate from handwritten business logic makes projects easier to maintain.

For example:

api/proto/
   |
   v
Code Generation
   |
   v
gen/

Your service implementation remains inside:

internal/

This prevents generated code from becoming mixed with application logic.

Automate Protobuf Generation

Instead of manually typing a long protoc command every time, create a repeatable workflow.

For example, use:

Makefile
Task runner
go generate
Build script
CI pipeline

The important goal is reproducibility.

Every developer and CI environment should generate compatible code in the same way.

Pin Tool Versions

Production teams should avoid relying blindly on whatever latest generator happens to be installed on a developer machine.

Pin or document versions for:

protoc
protoc-gen-go
protoc-gen-go-grpc

This helps keep generated code reproducible across machines and CI.

API Versioning

You may organize Protobuf APIs using versioned packages.

Example:

package user.v1;

Later:

package user.v2;

Do not create a new API version for every small additive change.

Protobuf supports many backward-compatible schema changes without requiring a completely new version.

gRPC Security Checklist

For production services, consider:

TLS for sensitive/untrusted networks
Authentication
Authorization
Input validation
Request deadlines
Message size limits
Rate limiting where needed
Secret management
Least privilege
Safe logging
Dependency updates
Certificate rotation
Monitoring
Audit requirements

Security should exist at multiple layers.

Common Go gRPC Mistakes

Avoid:

Using insecure credentials in production
No deadlines
Creating a connection for every RPC
Ignoring gRPC status codes
Returning generic Internal errors everywhere
Changing Protobuf field numbers
Reusing removed field numbers
Putting business logic directly in handlers
Sending huge messages unnecessarily
No authentication
No authorization
Logging tokens
Unlimited retries
No idempotency for critical writes
No graceful shutdown
No health checking
No observability
Ignoring streaming cancellation
Manually editing generated code

When Not to Use gRPC

gRPC is powerful, but it is not automatically the best choice.

You may prefer a traditional REST API when:

Your API is primarily public
Browser clients are the main consumers
Human-readable requests are valuable
Third-party developers expect JSON
The application is simple
Your infrastructure does not need streaming

Adding gRPC to a simple application can create unnecessary complexity.

When gRPC Is a Strong Choice

Consider gRPC when:

You have multiple backend services
Internal communication is frequent
Strong contracts matter
Streaming is required
Multiple programming languages are involved
Efficient serialization is valuable
You are building cloud-native distributed systems

Beginner Go gRPC Project

Build a User Service.

Methods:

CreateUser
GetUser
UpdateUser
DeleteUser
ListUsers

Architecture:

Go Client
    |
    v
User gRPC Service
    |
    v
Service Layer
    |
    v
Repository
    |
    v
PostgreSQL

Start with unary RPCs.

Then add:

Validation
Status codes
Deadlines
Logging
Authentication
Tests
Docker

Intermediate Project

Build an e-commerce backend:

API Gateway
     |
+----+----------+----------+
|               |          |
v               v          v
User          Product     Order
Service       Service     Service
                           |
                    +------+------+
                    |             |
                    v             v
                 Payment       Inventory
                 Service       Service

Use gRPC for internal service communication.

Add:

JWT authentication
PostgreSQL
Redis
Docker
Metrics
Tracing
Health checks

Advanced Project

Build a real-time distributed system using streaming:

Client
   |
   v
Gateway
   |
   v
Streaming Service
   |
+--+-----------+
|              |
v              v
Worker 1     Worker 2

Use:

Bidirectional streaming
Authentication
Backpressure handling
Cancellation
Retries
Observability
Kubernetes
Load balancing
TLS/mTLS

This gives you practical experience with advanced gRPC concepts.

Go gRPC Learning Roadmap

A good learning order is:

Go Fundamentals
       ↓
net/http Basics
       ↓
Context
       ↓
Protocol Buffers
       ↓
protoc
       ↓
Unary gRPC
       ↓
Status Codes
       ↓
Metadata
       ↓
Interceptors
       ↓
Authentication
       ↓
Server Streaming
       ↓
Client Streaming
       ↓
Bidirectional Streaming
       ↓
TLS
       ↓
Testing
       ↓
Database Integration
       ↓
Docker
       ↓
Microservices
       ↓
Observability
       ↓
Kubernetes

Frequently Asked Questions

What is gRPC in Go?

gRPC is an RPC framework that allows Go applications to communicate with local or remote services using strongly defined service contracts, commonly with Protocol Buffers.

Is gRPC better than REST?

Not universally.

gRPC is especially strong for internal service communication, streaming, strongly typed contracts, and efficient binary serialization.

REST remains extremely useful for public and browser-friendly APIs.

Does gRPC use HTTP/2?

Standard gRPC commonly uses HTTP/2 as its transport.

What is Protobuf?

Protocol Buffers is a language-neutral serialization format used to define structured messages and service contracts.

What is a `.proto` file?

A .proto file defines Protobuf messages and gRPC services.

What does `protoc` do?

protoc is the Protocol Buffer compiler. With the appropriate plugins, it generates Go message and gRPC code from .proto files.

Can Go communicate with a Java gRPC service?

Yes.

One major benefit of gRPC is cross-language communication.

For example:

Go
Java
Python
C#
C++
Node.js

can communicate using compatible Protobuf/gRPC definitions and supported libraries.

Is gRPC good for microservices?

Yes. It is commonly used for internal communication between microservices.

Does gRPC support streaming?

Yes.

It supports server streaming, client streaming, and bidirectional streaming.

Can gRPC use JWT authentication?

Yes.

Tokens can be sent through metadata and validated on the server, commonly through interceptors.

Is gRPC secure?

It can be secured using TLS or mTLS along with appropriate authentication, authorization, secret management, and application security practices.

Can I use gRPC with Docker?

Yes.

Go gRPC applications can be packaged and deployed using Docker containers.

Can I use gRPC with Kubernetes?

Yes.

gRPC is commonly used in Kubernetes-based microservice architectures.

Should beginners learn REST before gRPC?

Usually yes.

Understanding HTTP, APIs, request-response communication, JSON, context, and backend fundamentals makes gRPC much easier to understand.

Conclusion

gRPC is a powerful technology for building communication between Go services.

Instead of manually defining loosely connected endpoints and payloads, you can define a clear service contract:

service UserService {
  rpc GetUser(UserRequest)
      returns (UserResponse);
}

Then generate strongly typed Go client and server code from that contract.

The basic workflow is:

.proto Definition
      ↓
protoc
      ↓
Generated Go Code
      ↓
gRPC Server
      ↓
Network
      ↓
gRPC Client

As your application becomes more advanced:

Client
  |
  v
Gateway
  |
  v
gRPC Microservices
  |
  +---- Authentication
  +---- Database
  +---- Streaming
  +---- Logging
  +---- Metrics
  +---- Tracing
  +---- TLS

Start with unary RPCs and learn Protobuf carefully. After that, understand status codes, context, deadlines, metadata, interceptors, authentication, and testing.

Then move into server streaming, client streaming, bidirectional streaming, TLS, Docker, observability, Kubernetes, and microservice architecture.

Most importantly, use gRPC where it provides a real advantage. For many public APIs, REST remains simpler and more accessible. For internal service-to-service communication, strongly typed contracts, streaming, and cloud-native distributed systems, Go and gRPC can be an excellent combination.

Go gRPC: Complete Beginner’s Guide

What Is gRPC?

What Does gRPC Stand For?

Why Use gRPC with Go?

What Is Protocol Buffers?

Why Does Protobuf Use Numbers?

Protobuf vs JSON

How Does Go gRPC Work?

What Is a gRPC Service?

Types of gRPC Communication

1. Unary RPC

2. Server Streaming RPC

3. Client Streaming RPC

4. Bidirectional Streaming RPC

Install Go

Install Protocol Buffer Compiler

Install Go Protobuf Plugins

Create a Go gRPC Project

Install gRPC Dependencies

Create Your First .proto File

Understanding go_package

Generate Go Code from Protobuf

What Is Generated?

Create a Go gRPC Server

Why Embed UnimplementedUserServiceServer?

Start the gRPC Server

Create the Go gRPC Client

Run the Client

Why Use Context in gRPC?

gRPC Deadlines

Deadline Propagation

gRPC Status Codes

Return a NotFound Error

Invalid Argument Example

Handle gRPC Errors on the Client

gRPC Metadata

Send Metadata from Client

Read Metadata on Server

Authentication with gRPC

What Are gRPC Interceptors?

Unary Server Interceptor

Stream Interceptors

Multiple Interceptors

Server Streaming Example

Server Streaming Implementation

Receive Server Stream on Client

Client Streaming

Bidirectional Streaming

gRPC Uses HTTP/2

Connection Reuse

gRPC and Microservices

gRPC vs REST

When Should You Use REST?

When Should You Use gRPC?

Can REST and gRPC Be Used Together?

gRPC and Browsers

gRPC Gateway

Database Integration

Recommended Layered Architecture

Example Service Layer

Validation

Protobuf Schema Evolution

Do Not Renumber Existing Fields

Reserve Removed Fields

Avoid Huge Messages

gRPC Message Size Limits

TLS with Go gRPC

Server TLS Concept

Client TLS Concept

What Is mTLS?

Authentication vs TLS

Graceful Shutdown

Stop() vs GracefulStop()

Health Checks

Reflection

Testing with grpcurl

Testing Go gRPC Services

In-Memory Testing

Mocking gRPC Clients

Logging

Create Your First `.proto` File

Understanding `go_package`

Why Embed `UnimplementedUserServiceServer`?

Return a `NotFound` Error

`Stop()` vs `GracefulStop()`

What is a `.proto` file?

What does `protoc` do?