grpc.io/public/docs/quickstart/go/index.html

325 lines
22 KiB
HTML

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
<link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/css/bootstrap.min.css" integrity="sha384-MCw98/SFnGE8fJT3GXwEOngsV7Zt27NXFoaoApmYm81iuXoPkFOJwJ8ERdknLPMO" crossorigin="anonymous">
<link href="https://fonts.googleapis.com/css?family=Open+Sans:300,400" rel="stylesheet">
<link rel="stylesheet" type="text/css" href="/css/style.css">
<title>
Go Quick Start &ndash; gRPC
</title>
<link rel="apple-touch-icon" href="/favicons/apple-touch-icon.png" sizes="180x180">
<link rel="icon" type="image/png" href="/favicons/android-chrome-192x192.png" sizes="192x192" >
<link rel="icon" type="image/png" href="/favicons/favicon-32x32.png" sizes="32x32">
<link rel="icon" type="image/png" href="/favicons/favicon-16x16.png" sizes="16x16">
<link rel="manifest" href="/favicons/manifest.json">
<link rel="mask-icon" href="/favicons/safari-pinned-tab.svg" color="#2DA6B0">
<meta name="msapplication-TileColor" content="#ffffff">
<meta name="msapplication-TileImage" content="/favicons/mstile-150x150.png">
<script async src="https://www.googletagmanager.com/gtag/js?id=UA-60127042-1"></script>
<script>
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'UA-60127042-1');
</script>
</head>
<body>
<div id="landing-content">
<div class="row">
<div class="topbannersub">
<nav class="navbar navbar-expand-md navbar-dark topnav">
<a class="navbar-brand" href="https://cjyabraham.github.io/">
<img src="https://cjyabraham.github.io/img/grpc-logo.png" width="114" height="50">
</a>
<button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbarSupportedContent" aria-controls="navbarSupportedContent" aria-expanded="false" aria-label="Toggle navigation">
<span class="navbar-toggler-icon"></span>
</button>
<div class="topnav, collapse navbar-collapse" id="navbarSupportedContent" style="float:right !important">
<ul class="navbar-nav ml-auto">
<li class="nav-item ">
<a class="nav-link" href="https://cjyabraham.github.io/about/">About</a>
</li>
<li class="nav-item dropdown active">
<a class="nav-link dropdown-toggle" href="https://cjyabraham.github.io/docs/" id="navbarDropdown" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
Docs
</a>
<div class="dropdown-menu" aria-labelledby="navbarDropdown">
<a class="dropdown-item" href="/docs">
Overview
</a>
<a class="dropdown-item" href="/docs/quickstart/">
Quick Start
</a>
<a class="dropdown-item" href="/docs/guides/">
Guides
</a>
<a class="dropdown-item" href="/docs/tutorials/">
Tutorials
</a>
<a class="dropdown-item" href="/docs/reference/">
Reference
</a>
<a class="dropdown-item" href="/docs/samples/">
Samples
</a>
<a class="dropdown-item" href="/docs/talks">
Presentations
</a>
</div>
</li>
<li class="nav-item ">
<a class="nav-link" href="/blog">
Blog
</a>
</li>
<li class="nav-item ">
<a class="nav-link" href="/community">Community</a>
</li>
<li class="nav-item">
<a class="nav-link" href="https://packages.grpc.io/">
Packages
</a>
</li>
<li class="nav-item ">
<a class="nav-link" href="https://cjyabraham.github.io/faq/">FAQ</a>
</li>
</ul>
</div>
</nav>
<div class="headertext">Documentation</div>
</div>
</div>
</div>
<div class="subnav d-none d-md-block">
<a href="https://cjyabraham.github.io/docs/" >Overview</a>
| <a href="https://cjyabraham.github.io/docs/quickstart/" class="active">Quick Start</a>
| <a href="https://cjyabraham.github.io/docs/guides/" >Guides</a>
| <a href="https://cjyabraham.github.io/docs/tutorials/" >Tutorials</a>
| <a href="https://cjyabraham.github.io/docs/reference/" >Reference</a>
| <a href="https://cjyabraham.github.io/docs/samples/" >Samples</a>
| <a href="https://cjyabraham.github.io/docs/talks/" >Presentations</a>
</div>
<div class="quickstartcols">
<div class="quickstartcol1">
<h8>Quick Start</h8>
<a href="https://cjyabraham.github.io/docs/quickstart/cpp/" >C++</a>
<a href="https://cjyabraham.github.io/docs/quickstart/csharp/" >C#</a>
<a href="https://cjyabraham.github.io/docs/quickstart/dart/" >Dart</a>
<a href="https://cjyabraham.github.io/docs/quickstart/go/" class="active">Go</a>
<a href="https://cjyabraham.github.io/docs/quickstart/java/" >Java</a>
<a href="https://cjyabraham.github.io/docs/quickstart/android/" >Android Java</a>
<a href="https://cjyabraham.github.io/docs/quickstart/node/" >Node.js</a>
<a href="https://cjyabraham.github.io/docs/quickstart/objective-c/" >Objective-C</a>
<a href="https://cjyabraham.github.io/docs/quickstart/php/" >PHP</a>
<a href="https://cjyabraham.github.io/docs/quickstart/python/" >Python</a>
<a href="https://cjyabraham.github.io/docs/quickstart/ruby/" >Ruby</a>
<a href="https://cjyabraham.github.io/docs/quickstart/web/" >Web</a>
</div>
<div class="quickstartcol2" style="margin-top:4%">
<h3 style="margin-top:0px;">Go Quick Start</h3>
<p class="lead">This guide gets you started with gRPC in Go with a simple
working example.</p>
<div id="toc"></div>
<h3 id="prerequisites">Prerequisites</h3>
<h4 id="go-version">Go version</h4>
<p>gRPC requires Go 1.6 or higher.</p>
<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">$ go version</code></pre></div>
<p>For installation instructions, follow this guide: <a href="https://golang.org/doc/install">Getting Started - The Go Programming Language</a></p>
<h4 id="install-grpc">Install gRPC</h4>
<p>Use the following command to install gRPC.</p>
<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">$ go get -u google.golang.org/grpc</code></pre></div>
<h4 id="install-protocol-buffers-v3">Install Protocol Buffers v3</h4>
<p>Install the protoc compiler that is used to generate gRPC service code. The simplest way to do this is to download pre-compiled binaries for your platform(<code>protoc-&lt;version&gt;-&lt;platform&gt;.zip</code>) from here: <a href="https://github.com/google/protobuf/releases">https://github.com/google/protobuf/releases</a></p>
<ul>
<li>Unzip this file.</li>
<li>Update the environment variable <code>PATH</code> to include the path to the protoc binary file.</li>
</ul>
<p>Next, install the protoc plugin for Go</p>
<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">$ go get -u github.com/golang/protobuf/protoc-gen-go</code></pre></div>
<p>The compiler plugin, protoc-gen-go, will be installed in $GOBIN, defaulting to $GOPATH/bin. It must be in your $PATH for the protocol compiler, protoc, to find it.</p>
<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">$ export PATH<span style="color:#f92672">=</span>$PATH:$GOPATH/bin</code></pre></div>
<h3 id="download-the-example">Download the example</h3>
<p>The grpc code that was fetched with <code>go get google.golang.org/grpc</code> also contains the examples. They can be found under the examples dir: <code>$GOPATH/src/google.golang.org/grpc/examples</code>.</p>
<h3 id="build-the-example">Build the example</h3>
<p>Change to the example directory</p>
<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">$ cd $GOPATH/src/google.golang.org/grpc/examples/helloworld</code></pre></div>
<p>gRPC services are defined in a <code>.proto</code> file, which is used to generate a corresponding <code>.pb.go</code> file. The <code>.pb.go</code> file is generated by compiling the <code>.proto</code> file using the protocol compiler: <code>protoc</code>.</p>
<p>For the purpose of this example, the <code>helloworld.pb.go</code> file has already been generated (by compiling <code>helloworld.proto</code>), and can be found in this directory: <code>$GOPATH/src/google.golang.org/grpc/examples/helloworld/helloworld</code></p>
<p>This <code>helloworld.pb.go</code> file contains:</p>
<ul>
<li>Generated client and server code.</li>
<li>Code for populating, serializing, and retrieving our <code>HelloRequest</code> and <code>HelloReply</code> message types.</li>
</ul>
<h3 id="try-it">Try it!</h3>
<p>To compile and run the server and client code, the <code>go run</code> command can be used.
In the examples directory:</p>
<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">$ go run greeter_server/main.go</code></pre></div>
<p>From a different terminal:</p>
<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">$ go run greeter_client/main.go</code></pre></div>
<p>If things go smoothly, you will see the <code>Greeting: Hello world</code> in the client side output.</p>
<p>Congratulations! You&rsquo;ve just run a client-server application with gRPC.</p>
<h3 id="update-a-grpc-service">Update a gRPC service</h3>
<p>Now let&rsquo;s look at how to update the application with an extra method on the
server for the client to call. Our gRPC service is defined using protocol
buffers; you can find out lots more about how to define a service in a <code>.proto</code>
file in <a href="/docs/guides">What is gRPC?</a> and <a href="/docs/tutorials/basic/go/">gRPC Basics:
Go</a>. For now all you need to know is that both the server and the client
&ldquo;stub&rdquo; have a <code>SayHello</code> RPC method that takes a <code>HelloRequest</code> parameter from
the client and returns a <code>HelloReply</code> from the server, and that this method
is defined like this:</p>
<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-protobuf" data-lang="protobuf"><span style="color:#75715e">// The greeting service definition.
</span><span style="color:#75715e"></span><span style="color:#66d9ef">service</span> Greeter {<span style="color:#960050;background-color:#1e0010">
</span><span style="color:#960050;background-color:#1e0010"></span> <span style="color:#75715e">// Sends a greeting
</span><span style="color:#75715e"></span> <span style="color:#66d9ef">rpc</span> SayHello (HelloRequest) <span style="color:#66d9ef">returns</span> (HelloReply) {}<span style="color:#960050;background-color:#1e0010">
</span><span style="color:#960050;background-color:#1e0010"></span>}<span style="color:#960050;background-color:#1e0010">
</span><span style="color:#960050;background-color:#1e0010">
</span><span style="color:#960050;background-color:#1e0010"></span><span style="color:#75715e">// The request message containing the user&#39;s name.
</span><span style="color:#75715e"></span><span style="color:#66d9ef">message</span> <span style="color:#a6e22e">HelloRequest</span> {<span style="color:#960050;background-color:#1e0010">
</span><span style="color:#960050;background-color:#1e0010"></span> <span style="color:#66d9ef">string</span> name <span style="color:#f92672">=</span> <span style="color:#ae81ff">1</span>;<span style="color:#960050;background-color:#1e0010">
</span><span style="color:#960050;background-color:#1e0010"></span>}<span style="color:#960050;background-color:#1e0010">
</span><span style="color:#960050;background-color:#1e0010">
</span><span style="color:#960050;background-color:#1e0010"></span><span style="color:#75715e">// The response message containing the greetings
</span><span style="color:#75715e"></span><span style="color:#66d9ef">message</span> <span style="color:#a6e22e">HelloReply</span> {<span style="color:#960050;background-color:#1e0010">
</span><span style="color:#960050;background-color:#1e0010"></span> <span style="color:#66d9ef">string</span> <span style="color:#66d9ef">message</span> <span style="color:#f92672">=</span> <span style="color:#ae81ff">1</span>;<span style="color:#960050;background-color:#1e0010">
</span><span style="color:#960050;background-color:#1e0010"></span>}</code></pre></div>
<p>Let&rsquo;s update this so that the <code>Greeter</code> service has two methods. Make sure you are in the same examples dir as above (<code>$GOPATH/src/google.golang.org/grpc/examples/helloworld</code>)</p>
<p>Edit <code>helloworld/helloworld.proto</code> and update it with a new <code>SayHelloAgain</code> method, with the same request and response
types:</p>
<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-protobuf" data-lang="protobuf"><span style="color:#75715e">// The greeting service definition.
</span><span style="color:#75715e"></span><span style="color:#66d9ef">service</span> Greeter {<span style="color:#960050;background-color:#1e0010">
</span><span style="color:#960050;background-color:#1e0010"></span> <span style="color:#75715e">// Sends a greeting
</span><span style="color:#75715e"></span> <span style="color:#66d9ef">rpc</span> SayHello (HelloRequest) <span style="color:#66d9ef">returns</span> (HelloReply) {}<span style="color:#960050;background-color:#1e0010">
</span><span style="color:#960050;background-color:#1e0010"></span> <span style="color:#75715e">// Sends another greeting
</span><span style="color:#75715e"></span> <span style="color:#66d9ef">rpc</span> SayHelloAgain (HelloRequest) <span style="color:#66d9ef">returns</span> (HelloReply) {}<span style="color:#960050;background-color:#1e0010">
</span><span style="color:#960050;background-color:#1e0010"></span>}<span style="color:#960050;background-color:#1e0010">
</span><span style="color:#960050;background-color:#1e0010">
</span><span style="color:#960050;background-color:#1e0010"></span><span style="color:#75715e">// The request message containing the user&#39;s name.
</span><span style="color:#75715e"></span><span style="color:#66d9ef">message</span> <span style="color:#a6e22e">HelloRequest</span> {<span style="color:#960050;background-color:#1e0010">
</span><span style="color:#960050;background-color:#1e0010"></span> <span style="color:#66d9ef">string</span> name <span style="color:#f92672">=</span> <span style="color:#ae81ff">1</span>;<span style="color:#960050;background-color:#1e0010">
</span><span style="color:#960050;background-color:#1e0010"></span>}<span style="color:#960050;background-color:#1e0010">
</span><span style="color:#960050;background-color:#1e0010">
</span><span style="color:#960050;background-color:#1e0010"></span><span style="color:#75715e">// The response message containing the greetings
</span><span style="color:#75715e"></span><span style="color:#66d9ef">message</span> <span style="color:#a6e22e">HelloReply</span> {<span style="color:#960050;background-color:#1e0010">
</span><span style="color:#960050;background-color:#1e0010"></span> <span style="color:#66d9ef">string</span> <span style="color:#66d9ef">message</span> <span style="color:#f92672">=</span> <span style="color:#ae81ff">1</span>;<span style="color:#960050;background-color:#1e0010">
</span><span style="color:#960050;background-color:#1e0010"></span>}</code></pre></div>
<h3 id="generate-grpc-code">Generate gRPC code</h3>
<p>Next we need to update the gRPC code used by our application to use the new
service definition. From the same examples dir as above (<code>$GOPATH/src/google.golang.org/grpc/examples/helloworld</code>)</p>
<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">$ protoc -I helloworld/ helloworld/helloworld.proto --go_out<span style="color:#f92672">=</span>plugins<span style="color:#f92672">=</span>grpc:helloworld</code></pre></div>
<p>This regenerates the helloworld.pb.go with our new changes.</p>
<h3 id="update-and-run-the-application">Update and run the application</h3>
<p>We now have new generated server and client code, but we still need to implement
and call the new method in the human-written parts of our example application.</p>
<h4 id="update-the-server">Update the server</h4>
<p>Edit <code>greeter_server/main.go</code> and add the following function to it:</p>
<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-go" data-lang="go"><span style="color:#66d9ef">func</span> (<span style="color:#a6e22e">s</span> <span style="color:#f92672">*</span><span style="color:#a6e22e">server</span>) <span style="color:#a6e22e">SayHelloAgain</span>(<span style="color:#a6e22e">ctx</span> <span style="color:#a6e22e">context</span>.<span style="color:#a6e22e">Context</span>, <span style="color:#a6e22e">in</span> <span style="color:#f92672">*</span><span style="color:#a6e22e">pb</span>.<span style="color:#a6e22e">HelloRequest</span>) (<span style="color:#f92672">*</span><span style="color:#a6e22e">pb</span>.<span style="color:#a6e22e">HelloReply</span>, <span style="color:#66d9ef">error</span>) {
<span style="color:#66d9ef">return</span> <span style="color:#f92672">&amp;</span><span style="color:#a6e22e">pb</span>.<span style="color:#a6e22e">HelloReply</span>{<span style="color:#a6e22e">Message</span>: <span style="color:#e6db74">&#34;Hello again &#34;</span> <span style="color:#f92672">+</span> <span style="color:#a6e22e">in</span>.<span style="color:#a6e22e">Name</span>}, <span style="color:#66d9ef">nil</span>
}</code></pre></div>
<h4 id="update-the-client">Update the client</h4>
<p>Edit <code>greeter_client/main.go</code> to add the following code to the main function.</p>
<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-go" data-lang="go"><span style="color:#a6e22e">r</span>, <span style="color:#a6e22e">err</span> = <span style="color:#a6e22e">c</span>.<span style="color:#a6e22e">SayHelloAgain</span>(<span style="color:#a6e22e">ctx</span>, <span style="color:#f92672">&amp;</span><span style="color:#a6e22e">pb</span>.<span style="color:#a6e22e">HelloRequest</span>{<span style="color:#a6e22e">Name</span>: <span style="color:#a6e22e">name</span>})
<span style="color:#66d9ef">if</span> <span style="color:#a6e22e">err</span> <span style="color:#f92672">!=</span> <span style="color:#66d9ef">nil</span> {
<span style="color:#a6e22e">log</span>.<span style="color:#a6e22e">Fatalf</span>(<span style="color:#e6db74">&#34;could not greet: %v&#34;</span>, <span style="color:#a6e22e">err</span>)
}
<span style="color:#a6e22e">log</span>.<span style="color:#a6e22e">Printf</span>(<span style="color:#e6db74">&#34;Greeting: %s&#34;</span>, <span style="color:#a6e22e">r</span>.<span style="color:#a6e22e">Message</span>)</code></pre></div>
<h4 id="run">Run!</h4>
<p>Run the server</p>
<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">$ go run greeter_server/main.go</code></pre></div>
<p>On a different terminal, run the client</p>
<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">$ go run greeter_client/main.go</code></pre></div>
<p>You should see the updated output:</p>
<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">$ go run greeter_client/main.go
Greeting: Hello world
Greeting: Hello again world</code></pre></div>
<h3 id="what-s-next">What&rsquo;s next</h3>
<ul>
<li>Read a full explanation of how gRPC works in <a href="/docs/guides/">What is gRPC?</a>
and <a href="/docs/guides/concepts/">gRPC Concepts</a></li>
<li>Work through a more detailed tutorial in <a href="/docs/tutorials/basic/go/">gRPC Basics: Go</a></li>
<li>Explore the gRPC Go core API in its <a href="https://godoc.org/google.golang.org/grpc">reference
documentation</a></li>
</ul>
</div>
</div>
</div>
<script src="https://code.jquery.com/jquery-3.3.1.slim.min.js" integrity="sha384-q8i/X+965DzO0rT7abK41JStQIAqVgRVzpbzo5smXKp4YfRvH+8abtTE1Pi6jizo" crossorigin="anonymous"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.14.3/umd/popper.min.js" integrity="sha384-ZMP7rVo3mIykV+2+9J3UJ46jBk0WLaUAdn689aCwoqbBJiSnjAK/l8WvCWPIPm49" crossorigin="anonymous"></script>
<script src="https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/js/bootstrap.min.js" integrity="sha384-ChfqqxuZUCnJSK3+MXmPNIyE6ZbWh2IMqE241rYiqJxyMiZ6OW/JmZQ5stwEULTy" crossorigin="anonymous"></script>
</body>
</html>