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. - 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. - 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 It assumes that you have read the [Overview](/docs/) and are familiar with
with [protocol buffers](https://developers.google.com/protocol-buffers/docs/overview). Note that the [protocol buffers](https://developers.google.com/protocol-buffers/docs/overview).
example in this tutorial uses the proto3 version of the protocol buffers Note that the example in this tutorial uses the proto3 version of the protocol
language: you can find out more in the buffers language: you can find out more in the [proto3 language
[proto3 language guide](https://developers.google.com/protocol-buffers/docs/proto3) and the
guide](https://developers.google.com/protocol-buffers/docs/proto3) and the [Go [Go generated code
generated code
guide](https://developers.google.com/protocol-buffers/docs/reference/go-generated). guide](https://developers.google.com/protocol-buffers/docs/reference/go-generated).
### Why use gRPC? ### 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 $ 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 ### Defining the service
Our first step (as you'll know from the [Overview](/docs/)) is to 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 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 [protocol buffers](https://developers.google.com/protocol-buffers/docs/overview).
complete .proto file in 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). [`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: 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) {} 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 request and response types used in our service methods - for example, here's
the `Point` message type: the `Point` message type:
@ -146,9 +146,9 @@ message Point {
Next we need to generate the gRPC client and server interfaces from our .proto 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 service definition. We do this using the protocol buffer compiler `protoc` with
a special gRPC Go plugin. 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 ```sh
protoc -I routeguide/ routeguide/route_guide.proto --go_out=plugins=grpc:routeguide 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 #### 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 ```go
type routeGuideServer struct { type routeGuideServer struct {
@ -273,14 +274,13 @@ to be sent on the wire.
##### Client-side streaming RPC ##### Client-side streaming RPC
Now let's look at something a little more complicated: the client-side Now let's look at something a little more complicated: the client-side streaming
streaming method `RecordRoute`, where we get a stream of `Point`s from the method `RecordRoute`, where we get a stream of `Point`s from the client and
client and return a single `RouteSummary` with information about their trip. As return a single `RouteSummary` with information about their trip. As you can
you can see, this time the method doesn't have a request parameter at all. see, this time the method doesn't have a request parameter at all. Instead, it
Instead, it gets a `RouteGuide_RecordRouteServer` stream, which the server can gets a `RouteGuide_RecordRouteServer` stream, which the server can use to both
use to both read *and* write messages - it can receive client messages using read *and* write messages - it can receive client messages using its `Recv()`
its `Recv()` method and return its single response using its `SendAndClose()` method and return its single response using its `SendAndClose()` method.
method.
```go ```go
func (s *routeGuideServer) RecordRoute(stream pb.RouteGuide_RecordRouteServer) error { 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 In the method body we use the `RouteGuide_RecordRouteServer`'s `Recv()` method
repeatedly read in our client's requests to a request object (in this case a 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 `Point`) until there are no more messages: the server needs to check the error
error returned from `Read()` after each call. If this is `nil`, the stream is returned from `Read()` after each call. If this is `nil`, the stream is still
still good and it can continue reading; if it's `io.EOF` the message stream has good and it can continue reading; if it's `io.EOF` the message stream has ended
ended and the server can return its `RouteSummary`. If it has any other value, and the server can return its `RouteSummary`. If it has any other value, we
we return the error "as is" so that it'll be translated to an RPC status by the return the error "as is" so that it'll be translated to an RPC status by the
gRPC layer. gRPC layer.
##### Bidirectional streaming RPC ##### Bidirectional streaming RPC