gRPC Tutorial: Build a Server and Client
On this page
What you'll build
A Go server implementing OrderService, a client calling it, and the ability to inspect it from the command line. Every snippet here is from the course's lab, built with Go 1.27 and grpc-go 1.84.
Step 1: implement the gRPC server in Go
Embed the generated base type and implement methods:
type server struct {
shopv1.UnimplementedOrderServiceServer
mu sync.Mutex
orders map[string]*shopv1.Order
}
func (s *server) GetOrder(ctx context.Context, req *shopv1.GetOrderRequest) (*shopv1.GetOrderResponse, error) {
s.mu.Lock()
defer s.mu.Unlock()
o, ok := s.orders[req.GetOrderId()]
if !ok {
return nil, status.Errorf(codes.NotFound, "order %q not found", req.GetOrderId())
}
return &shopv1.GetOrderResponse{Order: o}, nil
}Methods can run concurrently on many goroutines, hence the mutex. Generated getters like req.GetOrderId() are nil-safe.
Step 2: start the server with health and reflection
func main() {
lis, err := net.Listen("tcp", "127.0.0.1:50051")
if err != nil {
log.Fatal(err)
}
srv := grpc.NewServer(grpc.UnaryInterceptor(authLog)) // interceptors: Day 16
shopv1.RegisterOrderServiceServer(srv, s)
hs := health.NewServer() // standard health service (Day 20)
healthpb.RegisterHealthServer(srv, hs)
hs.SetServingStatus("shop.v1.OrderService", healthpb.HealthCheckResponse_SERVING)
reflection.Register(srv) // lets tools discover the API
log.Fatal(srv.Serve(lis))
}This development server uses no TLS; Day 17 adds it.
Step 3: explore the API with grpcurl
With reflection on, grpcurl lists and describes services without the .proto file:
grpcurl -plaintext 127.0.0.1:50051 listgrpc.health.v1.Health
grpc.reflection.v1.ServerReflection
grpc.reflection.v1alpha.ServerReflection
shop.v1.OrderServicegrpcurl -plaintext -H 'authorization: Bearer demo-token' \
-d '{"order_id":"ord_42"}' 127.0.0.1:50051 shop.v1.OrderService/GetOrder{
"order": {
"id": "ord_42",
"customerId": "cus_7",
"status": "STATUS_PAID",
"totalCents": "4999",
"createdAt": "2026-10-15T02:53:44.048484Z"
}
}grpcurl converts JSON to protobuf and back. Note "totalCents": "4999": the protobuf JSON mapping writes 64-bit integers as strings, because JavaScript numbers can't represent all of them exactly (Day 21).
Step 4: write a Go client
conn, err := grpc.NewClient("127.0.0.1:50051",
grpc.WithTransportCredentials(insecure.NewCredentials()))
if err != nil {
log.Fatal(err)
}
defer conn.Close()
client := shopv1.NewOrderServiceClient(conn)
ctx := metadata.AppendToOutgoingContext(context.Background(), "authorization", "Bearer demo-token")
resp, err := client.GetOrder(ctx, &shopv1.GetOrderRequest{OrderId: "ord_42"})grpc.NewClient(which replaced the oldergrpc.Dial) doesn't connect immediately; the connection is established on the first call and reconnects automatically.- Create one connection and reuse it for the life of the process. A connection carries many concurrent calls over HTTP/2; opening one per request wastes handshakes.
- Metadata carries headers such as auth tokens.
Common gRPC setup problems
| Symptom | Cause |
|---|---|
Unimplemented: unknown service | Service not registered, or client and server packages differ |
Unavailable: connection refused | Server not running, wrong address or port |
Unavailable ... EOF from a plaintext client | The server expects TLS (Day 17) |
Unauthenticated | Missing or wrong metadata, rejected by an interceptor |
Check yourself
A single connection multiplexes many concurrent calls over HTTP/2 streams. Creating a connection per call adds TCP and TLS handshakes, resolver work and latency to every request for no benefit, and can exhaust ports under load.
Tools like grpcurl and Postman can list services and methods and call them without having the .proto files, because the server describes its own API at runtime. It's very convenient for debugging.
The protobuf JSON mapping encodes 64-bit integers as strings, because JavaScript numbers lose precision above 2^53. The binary value is still a normal int64.
A grpc.health.v1.Health service with Check and Watch methods that load balancers, Kubernetes probes and tools can call to ask whether the server, or a specific service on it, is serving. Every gRPC library ships an implementation.
They send traffic in plain text and don't verify the server's identity, so anyone on the network path can read or alter calls, including auth tokens. Production connections should use TLS, ideally mutual TLS between services.