go-grpc-patterns

gRPC Patterns (Go)

Upstream: https://pkg.go.dev/google.golang.org/grpc · https://grpc.io/docs/languages/go/

Service Definition

Proto-first. Generate with protoc-gen-go + protoc-gen-go-grpc.

syntax = "proto3";
package user.v1;
option go_package = "example.com/gen/user/v1;userv1";

service UserService {
    rpc GetUser (GetUserRequest) returns (User);                  // unary
    rpc ListUsers (ListUsersRequest) returns (stream User);       // server streaming
    rpc UploadUsers (stream User) returns (UploadUsersResponse);  // client streaming
    rpc Chat (stream Message) returns (stream Message);           // bidi
}

Version packages (user.v1, user.v2) — never break a shipped proto. Add fields; never renumber.

Server Setup

lis, _ := net.Listen("tcp", ":9090")
srv := grpc.NewServer(
    grpc.UnaryInterceptor(loggingInterceptor),
    grpc.StreamInterceptor(streamLoggingInterceptor),
)
userv1.RegisterUserServiceServer(srv, &userServer{repo: repo})
reflection.Register(srv) // dev only
srv.Serve(lis)

Graceful shutdown: srv.GracefulStop() on SIGTERM.

Four Stream Types

Unary

func (s *userServer) GetUser(ctx context.Context, req *userv1.GetUserRequest) (*userv1.User, error) {
    u, err := s.repo.FindByID(ctx, req.Id)
    if err != nil {
        if errors.Is(err, domain.ErrNotFound) {
            return nil, status.Errorf(codes.NotFound, "user %d not found", req.Id)
        }
        return nil, status.Errorf(codes.Internal, "find user: %v", err)
    }
    return &userv1.User{Id: u.ID, Email: u.Email}, nil
}

Server Streaming

func (s *userServer) ListUsers(req *userv1.ListUsersRequest, stream userv1.UserService_ListUsersServer) error {
    users, err := s.repo.List(stream.Context(), req.PageSize)
    if err != nil { return status.Errorf(codes.Internal, "list: %v", err) }
    for _, u := range users {
        if err := stream.Send(&userv1.User{Id: u.ID, Email: u.Email}); err != nil {
            return err
        }
    }
    return nil
}