grpc.io/content/docs/languages/go/quickstart.md

title	description	weight
Quick Start	This guide gets you started with gRPC in Go with a simple working example.	10

Prerequisites

• [Go][], any one of the three latest major [releases of Go][].

  For installation instructions, see Go's [Getting Started][] guide.

• [Protocol buffer][pb] compiler, protoc, [version 3][proto3].

  For installation instructions, see [Protocol Buffer Compiler Installation][pbc-install].

• Go plugin for the protocol compiler:

  1. Install the protocol compiler plugin for Go (protoc-gen-go) using the following command:

     $ export GO111MODULE=on  # Enable module mode
     $ go get github.com/golang/protobuf/protoc-gen-go
     

  2. Update your PATH so that the protoc compiler can find the plugin:

     $ export PATH="$PATH:$(go env GOPATH)/bin"
     

Get the example code

The example code is part of the [grpc-go][] repo.

1. [Download the repo as a zip file][download] and unzip it, or clone the repo:

   $ git clone -b {{< param grpc_go_release_tag >}} https://github.com/grpc/grpc-go
   

2. Change to the quick start example directory:

   $ cd grpc-go/examples/helloworld
   

Run the example

From the examples/helloworld directory:

1. Compile and execute the server code:

   $ go run greeter_server/main.go
   

2. From a different terminal, compile and execute the client code to see the client output:

   $ go run greeter_client/main.go
   Greeting: Hello world
   

Congratulations! You've just run a client-server application with gRPC.

Update a gRPC service

In this section you'll update the application with an extra server method. The gRPC service is defined using [protocol buffers][pb]. To learn more about how to define a service in a .proto file see gRPC Basics: Go. For now, all you need to know is that both the server and the client stub have a SayHello() RPC method that takes a HelloRequest parameter from the client and returns a HelloReply from the server, and that the method is defined like this:

// The greeting service definition.
service Greeter {
  // Sends a greeting
  rpc SayHello (HelloRequest) returns (HelloReply) {}
}

// The request message containing the user's name.
message HelloRequest {
  string name = 1;
}

// The response message containing the greetings
message HelloReply {
  string message = 1;
}

Open helloworld/helloworld.proto and add a new SayHelloAgain() method, with the same request and response types:

// The greeting service definition.
service Greeter {
  // Sends a greeting
  rpc SayHello (HelloRequest) returns (HelloReply) {}
  // Sends another greeting
  rpc SayHelloAgain (HelloRequest) returns (HelloReply) {}
}

// The request message containing the user's name.
message HelloRequest {
  string name = 1;
}

// The response message containing the greetings
message HelloReply {
  string message = 1;
}

Remember to save the file!

Regenerate gRPC code

Before you can use the new service method, you need to recompile the updated .proto file.

While still in the examples/helloworld directory, run the following commands:

$ ( cd ../../cmd/protoc-gen-go-grpc && go install . )
$ protoc \
  --go_out=Mgrpc/service_config/service_config.proto=/internal/proto/grpc_service_config:. \
  --go-grpc_out=Mgrpc/service_config/service_config.proto=/internal/proto/grpc_service_config:. \
  --go_opt=paths=source_relative \
  --go-grpc_opt=paths=source_relative \
  helloworld/helloworld.proto

This will regenerate the helloworld/helloworld.pb.go and helloworld/helloworld_grpc.pb.go files, which contain:

• Code for populating, serializing, and retrieving HelloRequest and HelloReply message types.
• Generated client and server code.

{{< note >}} We are in the process of transitioning to a new Go protoc plugin. Until the transition is complete, you need to install grpc-go/cmd/protoc-gen-go-grpc manually before regenerating .pb.go files. To track progress on this issue, see Update Go quick start #298.

{{< /note >}}

Update and run the application

You have regenerated server and client code, but you still need to implement and call the new method in the human-written parts of the example application.

Update the server

Open greeter_server/main.go and add the following function to it:

func (s *server) SayHelloAgain(ctx context.Context, in *pb.HelloRequest) (*pb.HelloReply, error) {
        return &pb.HelloReply{Message: "Hello again " + in.GetName()}, nil
}

Update the client

Open greeter_client/main.go to add the following code to the end of the main() function body:

r, err = c.SayHelloAgain(ctx, &pb.HelloRequest{Name: name})
if err != nil {
        log.Fatalf("could not greet: %v", err)
}
log.Printf("Greeting: %s", r.GetMessage())

Remember to save your changes.

Run!

Run the client and server like you did before. Execute the following commands from the examples/helloworld directory:

1. Run the server:

   $ go run greeter_server/main.go
   

2. From another terminal, run the client. This time, add a name as a command-line argument:

   $ go run greeter_client/main.go Alice
   

   You'll see the following output:

   Greeting: Hello Alice
   Greeting: Hello again Alice
   

What's next

• Learn how gRPC works in Introduction to gRPC and Core concepts.
• Work through the Basics Tutorial.
• Explore the API reference.

[download]: https://github.com/grpc/grpc-go/archive/{{< param grpc_go_release_tag >}}.zip [Getting Started]: https://golang.org/doc/install [Go]: https://golang.org [grpc-go]: https://github.com/grpc/grpc-go [pb]: https://developers.google.com/protocol-buffers [proto3]: https://developers.google.com/protocol-buffers/docs/proto3 [pbc-install]: /docs/protoc-installation [releases of Go]: https://golang.org/doc/devel/release.html