grpc
/
grpc.io
mirror of https://github.com/grpc/grpc.io.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Small improvements to tutorials/basic/go.md (#178) 

- Fix line wrapping
- Standardize references to .proto files (no code formatting)
- Add missing punctuation
This commit is contained in:
Waldir Pimenta 2020-04-08 19:24:41 +01:00 committed by GitHub
parent bbd3c83c4f
commit d30fd6adb2
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 30 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

60
content/docs/tutorials/basic/go.md
View File

@ -13,13 +13,12 @@ By walking through this example you'll learn how to:
- Generate server and client code using the protocol buffer compiler.
- Use the Go gRPC API to write a simple client and server for your service.
It assumes that you have read the [Overview](/docs/) and are familiar
with [protocol buffers](https://developers.google.com/protocol-buffers/docs/overview). Note that the
example in this tutorial uses the proto3 version of the protocol buffers
language: you can find out more in the
[proto3 language
guide](https://developers.google.com/protocol-buffers/docs/proto3) and the [Go
generated code
It assumes that you have read the [Overview](/docs/) and are familiar with
[protocol buffers](https://developers.google.com/protocol-buffers/docs/overview).
Note that the example in this tutorial uses the proto3 version of the protocol
buffers language: you can find out more in the [proto3 language
guide](https://developers.google.com/protocol-buffers/docs/proto3) and the
[Go generated code
guide](https://developers.google.com/protocol-buffers/docs/reference/go-generated).
### Why use gRPC?
@ -54,15 +53,16 @@ Then change your current directory to `grpc-go/examples/route_guide`:
$ cd $GOPATH/src/google.golang.org/grpc/examples/route_guide
```
You also should have the relevant tools installed to generate the server and client interface code - if you don't already, follow the setup instructions in [the Go quick start guide](/docs/quickstart/go/).
You also should have the relevant tools installed to generate the server and
client interface code - if you don't already, follow the setup instructions in
[the Go quick start guide](/docs/quickstart/go/).
### Defining the service
Our first step (as you'll know from the [Overview](/docs/)) is to
define the gRPC *service* and the method *request* and *response* types using
[protocol buffers](https://developers.google.com/protocol-buffers/docs/overview). You can see the
complete .proto file in
[protocol buffers](https://developers.google.com/protocol-buffers/docs/overview).
You can see the complete .proto file in
[`examples/route_guide/routeguide/route_guide.proto`](https://github.com/grpc/grpc-go/blob/master/examples/route_guide/routeguide/route_guide.proto).
To define a service, you specify a named `service` in your .proto file:
@ -126,7 +126,7 @@ all of which are used in the `RouteGuide` service:
rpc RouteChat(stream RouteNote) returns (stream RouteNote) {}
```
Our `.proto` file also contains protocol buffer message type definitions for all
Our .proto file also contains protocol buffer message type definitions for all
the request and response types used in our service methods - for example, here's
the `Point` message type:
@ -146,9 +146,9 @@ message Point {
Next we need to generate the gRPC client and server interfaces from our .proto
service definition. We do this using the protocol buffer compiler `protoc` with
a special gRPC Go plugin.
This is similar to what we did in the [quickstart guide](/docs/quickstart/go/)
This is similar to what we did in the [quickstart guide](/docs/quickstart/go/).
From the `route_guide` example directory run:
From the `route_guide` example directory, run:
```sh
protoc -I routeguide/ routeguide/route_guide.proto --go_out=plugins=grpc:routeguide
@ -188,7 +188,8 @@ Let's take a closer look at how it works.
#### Implementing RouteGuide
As you can see, our server has a `routeGuideServer` struct type that implements the generated `RouteGuideServer` interface:
As you can see, our server has a `routeGuideServer` struct type that implements
the generated `RouteGuideServer` interface:
```go
type routeGuideServer struct {
@ -273,14 +274,13 @@ to be sent on the wire.
##### Client-side streaming RPC
Now let's look at something a little more complicated: the client-side
streaming method `RecordRoute`, where we get a stream of `Point`s from the
client and return a single `RouteSummary` with information about their trip. As
you can see, this time the method doesn't have a request parameter at all.
Instead, it gets a `RouteGuide_RecordRouteServer` stream, which the server can
use to both read *and* write messages - it can receive client messages using
its `Recv()` method and return its single response using its `SendAndClose()`
method.
Now let's look at something a little more complicated: the client-side streaming
method `RecordRoute`, where we get a stream of `Point`s from the client and
return a single `RouteSummary` with information about their trip. As you can
see, this time the method doesn't have a request parameter at all. Instead, it
gets a `RouteGuide_RecordRouteServer` stream, which the server can use to both
read *and* write messages - it can receive client messages using its `Recv()`
method and return its single response using its `SendAndClose()` method.
```go
func (s *routeGuideServer) RecordRoute(stream pb.RouteGuide_RecordRouteServer) error {
@ -315,13 +315,13 @@ func (s *routeGuideServer) RecordRoute(stream pb.RouteGuide_RecordRouteServer) e
}
```
In the method body we use the `RouteGuide_RecordRouteServer`'s `Recv()` method to
repeatedly read in our client's requests to a request object (in this case a
`Point`) until there are no more messages: the server needs to check the
error returned from `Read()` after each call. If this is `nil`, the stream is
still good and it can continue reading; if it's `io.EOF` the message stream has
ended and the server can return its `RouteSummary`. If it has any other value,
we return the error "as is" so that it'll be translated to an RPC status by the
In the method body we use the `RouteGuide_RecordRouteServer`'s `Recv()` method
to repeatedly read in our client's requests to a request object (in this case a
`Point`) until there are no more messages: the server needs to check the error
returned from `Read()` after each call. If this is `nil`, the stream is still
good and it can continue reading; if it's `io.EOF` the message stream has ended
and the server can return its `RouteSummary`. If it has any other value, we
return the error "as is" so that it'll be translated to an RPC status by the
gRPC layer.
##### Bidirectional streaming RPC