該篇文章介紹了golang的grpc編程。

通過下面的例子，你將會學(xué)到：
1. 在一個.proto文件里define一個service
2. 用protocol buffer 編譯工具生成server和client代碼
3. 用go grpc的api寫一個簡單的server和client

你應(yīng)該已經(jīng)讀過 概述( Overview),并且對 protocol buffers有所了解，注意教程中的例子用了protocol buffer 的proto3版本：詳情見以下兩個鏈接 proto3 language guide , Go generated code guide.

為什么用grpc？

我們的示例是一個簡單的路由映射應(yīng)用程序，它允許客戶機(jī)獲取有關(guān)其路由上功能的信息，創(chuàng)建其路由的摘要，并與服務(wù)器和其他客戶機(jī)交換路由信息，如流量更新。
用grpc我們可以在.proto文件中定義我們的服務(wù)，并且支持任何語言的server和client..這些server和client可以在從谷歌的內(nèi)部服務(wù)器到你的平板電腦上運行。所有的不同平臺的語言的通訊的復(fù)雜性都由grpc為你處理。用protocol buffer的優(yōu)勢包括高效的序列化/簡單的IDL/高可用的接口更新

實例代碼和setup

示例代碼在 grpc/grpc-go/examples/route_guide。去下載示例代碼并且clone grpc-go通過運行如下命令：

$ go get google.golang.org/grpc

cd到grpc-go/examples/route_guide：

$ cd GOPATH/src/google.golang.org/grpc/examples/route_guide

你應(yīng)該已經(jīng)安裝了相應(yīng)的工具來生成server和client的接口代碼。如果沒有看如下鏈接：Go quick start guide.

定義service

我們的第一步是通過protoco buffer 定義grpc的service以及response和request的類型.你可以在examples/route_guide/routeguide/route_guide.proto看到完成的.proto文件。
在proto文件中定義service：

service RouteGuide {
   ...
}

然后再service里定義rpc方法，指定他們的request和response方法。grpc允許你定義四種類型的rpc方法。他們在RouteGuide 里都有用到。

• 一個簡單的RPC，客戶端用stub發(fā)送請求到服務(wù)端，等待一個回應(yīng)。就像普通的函數(shù)調(diào)用。

// Obtains the feature at a given position.
rpc GetFeature(Point) returns (Feature) {}

• 一個server側(cè)streaming RPC，客戶端發(fā)送一個請求到server，獲取一個stream,可以read一系列message?？蛻舳藃ead這個stream直到全部讀完。在例子中可以看到，你指定server側(cè)streaming方法，通過在response類型前面放置stream關(guān)鍵字。

// 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) {}

• 一個客戶端側(cè)streaming RPC，客戶端通過一個提供的stream,寫入一系列的messages,并且發(fā)送到server。一旦客戶端全部寫完，他等待server全部讀完，并且返回一個response。你指定客戶端側(cè)streaming方法，通過在request類型前面放置stream關(guān)鍵字。

// Accepts a stream of Points on a route being traversed, returning a
// RouteSummary when traversal is completed.
rpc RecordRoute(stream Point) returns (RouteSummary) {}

• 一個雙向的streaming RPC,兩側(cè)都通過read-write stream發(fā)送一串message。這兩個steam的操作是獨立的。因此client和server可以以任何進(jìn)行讀/寫。例如server可以等message讀完了之后回一個response。也可以讀完之前回復(fù)response。也可以讀一個回復(fù)一個，或者其他的讀寫組合。每個stream內(nèi)message的順序是保存好的。stream關(guān)鍵字在request/response前面。

// 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) {}

.proto文件包含protocol buffer message類型（request/response的參數(shù)）的定義。例如下面是Point類型

// 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;
}

生產(chǎn)client/server代碼

下面我們要通過.proto文件生成grpc client/server的接口。我們通過一個帶有g(shù)o插件的編譯工具protoc。這類似于我們在quickstart guide所作的。
在route_guide實例目錄執(zhí)行：

protoc -I routeguide/ routeguide/route_guide.proto --go_out=plugins=grpc:routeguide

執(zhí)行這個命令，在routeguide目錄下生產(chǎn)文件：

route_guide.pb.go

文件包含：

• 用于填充、序列化和檢索請求和響應(yīng)消息類型的所有的protocol buffer代碼
• 被客戶端調(diào)用的一個接口類型(或 stub),包含在RouteGuide service中定義的一個方法。
• 被服務(wù)端實現(xiàn)的一個接口類型(或 stub),包含在RouteGuide service中定義的一個方法。

創(chuàng)建server

首先我們來看看如何生產(chǎn)RouteGuide server。如果你只對生產(chǎn)rpc client 感興趣，請?zhí)^該章節(jié)。跳到Creating the client

• 實現(xiàn)由service定義生成的service interface.
• 運行g(shù)RPC服務(wù)器來偵聽來自客戶機(jī)的請求并將其發(fā)送到正確的服務(wù)實現(xiàn)。
  RouteGuide server的實現(xiàn)在 grpc-go/examples/route_guide/server/server.go。讓我們進(jìn)一步看一下，他們是如何工作的：

實現(xiàn)RouteGuide

如下，我們的server有routeGuideServer 結(jié)構(gòu)體，來實現(xiàn)生成的RouteGuideServer接口：

type routeGuideServer struct {
        ...
}
...

func (s *routeGuideServer) GetFeature(ctx context.Context, point *pb.Point) (*pb.Feature, error) {
        ...
}
...

func (s *routeGuideServer) ListFeatures(rect *pb.Rectangle, stream pb.RouteGuide_ListFeaturesServer) error {
        ...
}
...

func (s *routeGuideServer) RecordRoute(stream pb.RouteGuide_RecordRouteServer) error {
        ...
}
...

func (s *routeGuideServer) RouteChat(stream pb.RouteGuide_RouteChatServer) error {
        ...
}
...

簡單的rpc

routeGuideServer 實現(xiàn)所有的services方法。先看一下最簡單的GetFeature，它從客戶端獲取Point然后return一個對應(yīng)的feature信息。

func (s *routeGuideServer) GetFeature(ctx context.Context, point *pb.Point) (*pb.Feature, error) {
    for _, feature := range s.savedFeatures {
        if proto.Equal(feature.Location, point) {
            return feature, nil
        }
    }
    // No feature was found, return an unnamed feature
    return &pb.Feature{"", point}, nil
}

這個方法傳遞一個context對象和client的Pointprotocol buffer 請求。它返回一個包含response信息的Featureprotocol buffer 對象和error。

server側(cè)streaming RPC

我們來看一個streaming RPCs。 ListFeatures是一個server側(cè)的streaming rpc，因此我們需要發(fā)送多個Fearute到client。

func (s *routeGuideServer) ListFeatures(rect *pb.Rectangle, stream pb.RouteGuide_ListFeaturesServer) error {
    for _, feature := range s.savedFeatures {
        if inRange(feature.Location, rect) {
            if err := stream.Send(feature); err != nil {
                return err
            }
        }
    }
    return nil
}

函數(shù)有一個請求參數(shù)（client想要通過Rectangle 來查找Features)和一個RouteGuide_ListFeaturesServer對象去write responses.
函數(shù)中，我們填充并return所有的Feature，通過Send()把他們寫到RouteGuide_ListFeaturesServer 。

client側(cè)streaming RPC

現(xiàn)在來看一下復(fù)雜一點的：客戶端側(cè)streaming方法RecordRoute。我們從客戶端收到一個stream（內(nèi)有多個Point），并且返回單個RouteSummary 。正如你所看到的，這次沒有request參數(shù)，只有一個RouteGuide_RecordRouteServer stream，server可以用來讀寫message，通過Recv()讀,通過SendAndClose()寫。

func (s *routeGuideServer) RecordRoute(stream pb.RouteGuide_RecordRouteServer) error {
    var pointCount, featureCount, distance int32
    var lastPoint *pb.Point
    startTime := time.Now()
    for {
        point, err := stream.Recv()
        if err == io.EOF {
            endTime := time.Now()
            return stream.SendAndClose(&pb.RouteSummary{
                PointCount:   pointCount,
                FeatureCount: featureCount,
                Distance:     distance,
                ElapsedTime:  int32(endTime.Sub(startTime).Seconds()),
            })
        }
        if err != nil {
            return err
        }
        pointCount++
        for _, feature := range s.savedFeatures {
            if proto.Equal(feature.Location, point) {
                featureCount++
            }
        }
        if lastPoint != nil {
            distance += calcDistance(lastPoint, point)
        }
        lastPoint = point
    }
}

通過Recv()持續(xù)讀，直到io.EOF。

雙向streaming RPC

最后，我們來看一下雙向streaming RPC RouteChat()

func (s *routeGuideServer) RouteChat(stream pb.RouteGuide_RouteChatServer) error {
    for {
        in, err := stream.Recv()
        if err == io.EOF {
            return nil
        }
        if err != nil {
            return err
        }
        key := serialize(in.Location)
                ... // look for notes to be sent to client
        for _, note := range s.routeNotes[key] {
            if err := stream.Send(note); err != nil {
                return err
            }
        }
    }
}

這里讀和寫的語法和我們的client-streaming 的方法特別像，不同點是server用stream的Send()方法，而不是SendAndClose()，因為需要寫入多個response。

啟動server

我們完成所有的方法后，需要啟動gRPC server，client才能發(fā)送請求。下面的片段展示了我們?nèi)绾螁覴outeGuide service的。

flag.Parse()
lis, err := net.Listen("tcp", fmt.Sprintf(":%d", *port))
if err != nil {
        log.Fatalf("failed to listen: %v", err)
}
grpcServer := grpc.NewServer()
pb.RegisterRouteGuideServer(grpcServer, &routeGuideServer{})
... // determine whether to use TLS
grpcServer.Serve(lis)

新建并且啟動一個server：

1. 指定用來監(jiān)聽request的的端口，使用lis, err := net.Listen("tcp", fmt.Sprintf(":%d", *port))
2. 用grpc.NewServer()創(chuàng)建gRPC server的實例。
3. 在GRPC服務(wù)器上注冊我們的服務(wù)實現(xiàn)。
4. 調(diào)用Serve()阻塞等待，直到進(jìn)程被kill或者Stop()被調(diào)用。

創(chuàng)建一個client

這一部分我們會看一下如何為RouteGuideservice創(chuàng)建GO client。你可以看到完整的client code在 grpc-go/examples/route_guide/client/client.go

創(chuàng)建一個stub

為了調(diào)用服務(wù)的method,我們首先需要創(chuàng)建通訊的管道。把server的地址和port傳到grpc.Dial(),如下：

conn, err := grpc.Dial(*serverAddr)
if err != nil {
    ...
}
defer conn.Close()

如果service要求的話，你可以在grpc.Dial中用DialOptions設(shè)置授權(quán)證書。
我們通過.proto文件生成的pb package中的NewRouteGuideClient 方法獲取client stub。

client := pb.NewRouteGuideClient(conn)

調(diào)用service的方法

現(xiàn)在讓我們看一下如何調(diào)用service方法。在gRPC-Go，PRCs操作是在阻塞/同步模式，PRC操作需要等待server 的response，要么返回response要么返回error。

簡單的RPC

調(diào)用簡單的RPC GetFeature就像調(diào)用本地的函數(shù)一樣簡單。

feature, err := client.GetFeature(context.Background(), &pb.Point{409146138, -746188906})
if err != nil {
        ...
}

函數(shù)的參數(shù)為protocol buffer對象(point)和context.Context對象，通過context參數(shù)我們可以改變PRC的行為，比如超時/取消。如果調(diào)用沒有返回錯誤，我們可以從第一個return值中讀到response信息。

log.Println(feature)

server側(cè)streaming RPC

這里我們調(diào)用server側(cè)streaming的方法ListFeatures,該方法返回一串Feature。

rect := &pb.Rectangle{ ... }  // initialize a pb.Rectangle
stream, err := client.ListFeatures(context.Background(), rect)
if err != nil {
   ...
}
for {
   feature, err := stream.Recv()
   if err == io.EOF {
       break
   }
   if err != nil {
       log.Fatalf("%v.ListFeatures(_) = _, %v", client, err)
   }
   log.Println(feature)
}

這里返回值是一個RouteGuide_ListFeaturesClient實例，客戶端可以通過RouteGuide_ListFeaturesClient讀取server的一系列返回值。
我們使用routeguide_ListFeaturesClient的recv()方法重復(fù)讀取服務(wù)器的響應(yīng)到protocol buffer對象，直到不再有消息：客戶端需要檢查每次調(diào)用后recv()返回的錯誤。如果為nil，可以繼續(xù)讀取；如果為io.eof，則消息流已結(jié)束；否則，必須存在一個通過err傳遞的rpc錯誤。

client側(cè)streaming RPC

客戶端流方法recordroute與服務(wù)器端方法類似，只是我們只傳遞context參數(shù)獲取routeguide_recordroute client stream，我們可以使用它來寫入和讀取消息。

// Create a random number of random points
r := rand.New(rand.NewSource(time.Now().UnixNano()))
pointCount := int(r.Int31n(100)) + 2 // Traverse at least two points
var points []*pb.Point
for i := 0; i < pointCount; i++ {
    points = append(points, randomPoint(r))
}
log.Printf("Traversing %d points.", len(points))
stream, err := client.RecordRoute(context.Background())
if err != nil {
    log.Fatalf("%v.RecordRoute(_) = _, %v", client, err)
}
for _, point := range points {
    if err := stream.Send(point); err != nil {
        log.Fatalf("%v.Send(%v) = %v", stream, point, err)
    }
}
reply, err := stream.CloseAndRecv()
if err != nil {
    log.Fatalf("%v.CloseAndRecv() got error %v, want %v", stream, err, nil)
}
log.Printf("Route summary: %v", reply)

routeguide_recordrouteclient有一個send()方法，我們可以使用它向服務(wù)器發(fā)送請求。一旦我們使用send()將客戶機(jī)的請求寫入流，我們就需要對該流調(diào)用closeAndrecv，讓grpc知道我們已經(jīng)完成了寫入，并期望收到響應(yīng)。我們從closeAndrecv返回的錯誤中獲取RPC狀態(tài)。如果狀態(tài)為nil，那么closeAndrecv的第一個返回值將是有效的服務(wù)器響應(yīng)。

雙向streaming RPC

最后，讓我們看看雙向流式RPC RouteChat()。就像在recordroute中一樣，我們只傳遞方法一個context對象，并返回一個可以用來寫和讀消息的流。但是，這一次我們通過自己的方法的stream返回response，而服務(wù)器仍在繼續(xù)向其消息流寫入消息。

stream, err := client.RouteChat(context.Background())
waitc := make(chan struct{})
go func() {
    for {
        in, err := stream.Recv()
        if err == io.EOF {
            // read done.
            close(waitc)
            return
        }
        if err != nil {
            log.Fatalf("Failed to receive a note : %v", err)
        }
        log.Printf("Got message %s at point(%d, %d)", in.Message, in.Location.Latitude, in.Location.Longitude)
    }
}()
for _, note := range notes {
    if err := stream.Send(note); err != nil {
        log.Fatalf("Failed to send a note: %v", err)
    }
}
stream.CloseSend()
<-waitc

這里的讀寫語法與我們的客戶端流方法非常相似，只是我們在完成調(diào)用后使用了流的closesend()方法。盡管每一方總是按照對方的消息被寫入的順序來獲取對方的消息，但是客戶機(jī)和服務(wù)器都可以以任何順序讀寫——流完全獨立地運行。

Try it out!

編譯和運行服務(wù)器，假設(shè)您在文件夾中$GOPATH/src/google.golang.org/grpc/examples/route_guide:

$ go run server/server.go

同樣，要運行客戶機(jī)：

$ go run client/client.go

參考文檔：https://grpc.io/docs/tutorials/basic/go.html#try-it-out