gRPC 的route_guide例子

本文的例子代码在： https://github.com/grpc/grpc-go/tree/master/examples/route_guide

功能就类似目前LBS一样，在每个位置上报一些文字信息，上报方式有多种。

在 .proto 文件中定义服务

在 .proto 文件中定义一个服务很简单，就像如下的代码：

service RouteGuide {
   ...
}

定义rpc的方法，需要指定他们的 request 和response 类型。gRPC 可以定义四种类型的方法，这个 RouteGuide 服务例子中都会出现。

1、就像普通函数调用一样，

客户端带着 stub 发送请求，然后等服务器端返回。

// Points are represented as latitude-longitude pairs in the E7 representation
// (degrees multiplied by 10**7 and rounded to the nearest integer).
// Latitudes should be in the range +/- 90 degrees and longitude should be in
// the range +/- 180 degrees (inclusive).
message Point {
int32 latitude = 1;
int32 longitude = 2;
}

// A feature names something at a given point.
//
// If a feature could not be named, the name is empty.
message Feature {
// The name of the feature.
string name = 1;
// The point where the feature is detected.
Point location = 2;
}

  // A simple RPC.
  //
  // Obtains the feature at a given position.
  //
  // If no feature is found for the given point, a feature with an empty name
  // should be returned.
  rpc GetFeature(Point) returns (Feature) {}

2、服务器端返回的是个RPC的流

客户端发送请求到服务器端，并获得一个流读取消息的序列。客户端从返回的流中读取数据。注意这里用了 stream 这个关键字。

// A latitude-longitude rectangle, represented as two diagonally opposite

// points "lo" and "hi".

message Rectangle {

// One corner of the rectangle.

Point lo = 1;

// The other corner of the rectangle.

Point hi = 2;

}

// A server-to-client streaming RPC.

// Obtains the Features available within the given Rectangle. Results are

// streamed rather than returned at once (e.g. in a response message with a

// repeated field), as the rectangle may cover a large area and contain a

// huge number of features.

rpc ListFeatures(Rectangle) returns (stream Feature) {}

3、客户端用流传输，服务器端正常。

客户端将消息写入流的序列，并将它们发送到服务器。一旦客户端已经写完了消息，客户端等待服务器读取所有这些，返回其响应。

// A RouteSummary is received in response to a RecordRoute rpc.

// It contains the number of individual points received, the number of

// detected features, and the total distance covered as the cumulative sum of

// the distance between each point.

message RouteSummary {

// The number of points received.

int32 point_count = 1;

// The number of known features passed while traversing the route.

int32 feature_count = 2;

// The distance covered in metres.

int32 distance = 3;

// The duration of the traversal in seconds.

int32 elapsed_time = 4;

}

// A client-to-server streaming RPC.

// Accepts a stream of Points on a route being traversed, returning a

// RouteSummary when traversal is completed.

rpc RecordRoute(stream Point) returns (RouteSummary) {}

4、服务器和客户端都用流来处理，即双向流

两个流独立运行，所以客户端和服务器端都可以读取和写入任何他们喜欢的东西。

// A RouteNote is a message sent while at a given point.

message RouteNote {

// The location from which the message is sent.

Point location = 1;

// The message to be sent.

string message = 2;

}

// A Bidirectional streaming RPC.

// Accepts a stream of RouteNotes sent while a route is being traversed,

// while receiving other RouteNotes (e.g. from other users).

rpc RouteChat(stream RouteNote) returns (stream RouteNote) {}

产生客户端和服务器端代码

有一个封装好的 shell 脚本在 https://github.com/grpc/grpc-go/blob/master/codegen.sh

这个工具各种依赖的安装方法请参考： http://www.cnblogs.com/ghj1976/p/4564133.html

我们这里执行的命令是： ./codegen.sh ./examples/route_guide/proto/route_guide.proto

这时候我们产生的文件是：

https://github.com/grpc/grpc-go/blob/master/examples/route_guide/proto/route_guide.pb.go

这个产生的文件中，既有公共类的相关信息，也有客户端和服务器端的代码。

服务器端我们要做这些事情：

实现上面 proto 文件产生的服务器端接口
服务器端运行 rpc 服务器去监听来自客户端的请求，并将它们路由到正确的服务上。

实现 RouteGuideServer 接口

我们在 route_guide.pb.go 中可以看到我们需要实现的接口：

// Server API for RouteGuide service

type RouteGuideServer interface {
    // A simple RPC.
    //
    // Obtains the feature at a given position.
    //
    // If no feature is found for the given point, a feature with an empty name
    // should be returned.
    GetFeature(context.Context, *Point) (*Feature, error)

    // A server-to-client streaming RPC.
    //
    // Obtains the Features available within the given Rectangle. Results are
    // streamed rather than returned at once (e.g. in a response message with a
    // repeated field), as the rectangle may cover a large area and contain a
    // huge number of features.
    ListFeatures(*Rectangle, RouteGuide_ListFeaturesServer) error

    // A client-to-server streaming RPC.
    //
    // Accepts a stream of Points on a route being traversed, returning a
    // RouteSummary when traversal is completed.
    RecordRoute(RouteGuide_RecordRouteServer) error

    // A Bidirectional streaming RPC.
    //
    // Accepts a stream of RouteNotes sent while a route is being traversed,
    // while receiving other RouteNotes (e.g. from other users).
    RouteChat(RouteGuide_RouteChatServer) error
}

simple RPC.

GetFeature 需要根据客户端传入的一个点, 返回数据库中对应的 Feature.

Server-side streaming RPC

返回所有在这个区域的 Feature。

注意，我们这里用到 stream.Send 方法发送的结果数据。在发送完成或者发送除了错误时，才return 结束这个函数。

Client-side streaming RPC

客户端上通过 stream 上传一批点，服务器端记录点的个数、已知的feature数、总行驶距离、总时间消耗。

$)V44Z8BC%)$GPZJT_5{2WOC$

注意，这里通过 stream.Recv 接收数据，通过 stream.SendAndClose 关闭返回流。

Bidirectional streaming RPC

服务器端接收客户端上报的位置信息流，针对当前一个位置，回应这个位置的已有位置信息流。

这里用的 stream.Recv() 接收， stream.Send 发送。

开始服务

开启服务我们做了下面步骤：

1、制定服务的监控端口, lis, err := net.Listen("tcp", fmt.Sprintf(":%d", *port))

2、创建一个 gRPC 服务实例 grpc.NewServer().

3、在gRPC 服务实例上注册我们的服务实现 pb.RegisterRouteGuideServer(grpcServer, &routeGuideServer{})

4、调用 grpcServer.Serve(lis) 开启服务，我们监控的端口做阻塞等待，知道该进程被杀死或者 Stop() 方法被调用。

编译服务器端

编译时，由于墙的原因，有些依赖包需要特殊下载，相关资料请参考：

http://www.cnblogs.com/ghj1976/p/4549602.html

创建客户端

这部分代码可以在 https://github.com/grpc/grpc-go/blob/master/examples/route_guide/client/client.go 看到。

建立通道

要调用服务，我们需要先创建一个 gRPC 通道与服务器进行通讯，我们这里通过 grpc.Dial 来指定服务器地址和端口来创建这个通道。

一旦gRPC通道建立后，我们需要一个客户端stub去执行RPC，这里我们使用 .proto 文件生产的 NewRouteGuideClient 方法。