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

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

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

為什么用grpc？

我們的示例是一個簡單的路由映射應用程序，它允許客戶機獲取有關其路由上功能的信息告抄，創(chuàng)建其路由的摘要，并與服務器和其他客戶機交換路由信息嵌牺，如流量更新打洼。
用grpc我們可以在.proto文件中定義我們的服務，并且支持任何語言的server和client..這些server和client可以在從谷歌的內(nèi)部服務器到你的平板電腦上運行逆粹。所有的不同平臺的語言的通訊的復雜性都由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

你應該已經(jī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ā)送請求到服務端退敦，等待一個回應。就像普通的函數(shù)調用蚣抗。

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

• 一個server側streaming RPC苛聘，客戶端發(fā)送一個請求到server，獲取一個stream,可以read一系列message忠聚∩杌客戶端read這個stream直到全部讀完。在例子中可以看到两蟀，你指定server側streaming方法网梢，通過在response類型前面放置stream關鍵字。

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

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

// 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,兩側都通過read-write stream發(fā)送一串message手趣。這兩個steam的操作是獨立的。因此client和server可以以任何進行讀/寫肥荔。例如server可以等message讀完了之后回一個response绿渣。也可以讀完之前回復response。也可以讀一個回復一個燕耿，或者其他的讀寫組合中符。每個stream內(nèi)message的順序是保存好的。stream關鍵字在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的接口。我們通過一個帶有go插件的編譯工具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

文件包含：

• 用于填充踏志、序列化和檢索請求和響應消息類型的所有的protocol buffer代碼
• 被客戶端調用的一個接口類型(或 stub),包含在RouteGuide service中定義的一個方法阀捅。
• 被服務端實現(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.
• 運行gRPC服務器來偵聽來自客戶機的請求并將其發(fā)送到正確的服務實現(xiàn)圆雁。
  RouteGuide server的實現(xiàn)在 grpc-go/examples/route_guide/server/server.go忍级。讓我們進一步看一下，他們是如何工作的：

實現(xiàn)RouteGuide

如下伪朽，我們的server有routeGuideServer 結構體轴咱，來實現(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一個對應的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側streaming RPC

我們來看一個streaming RPCs戈稿。 ListFeatures是一個server側的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側streaming RPC

現(xiàn)在來看一下復雜一點的：客戶端側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服務器上注冊我們的服務實現(xiàn)曼氛。
4. 調用Serve()阻塞等待豁辉，直到進程被kill或者Stop()被調用。

創(chuàng)建一個client

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

創(chuàng)建一個stub

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

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

如果service要求的話，你可以在grpc.Dial中用DialOptions設置授權證書聊浅。
我們通過.proto文件生成的pb package中的NewRouteGuideClient 方法獲取client stub餐抢。

client := pb.NewRouteGuideClient(conn)

調用service的方法

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

簡單的RPC

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

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

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

log.Println(feature)

server側streaming RPC

這里我們調用server側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()方法重復讀取服務器的響應到protocol buffer對象秉溉，直到不再有消息：客戶端需要檢查每次調用后recv()返回的錯誤。如果為nil碗誉，可以繼續(xù)讀日偎弧；如果為io.eof哮缺，則消息流已結束弄跌；否則，必須存在一個通過err傳遞的rpc錯誤尝苇。

client側streaming RPC

客戶端流方法recordroute與服務器端方法類似铛只，只是我們只傳遞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()方法淳玩，我們可以使用它向服務器發(fā)送請求。一旦我們使用send()將客戶機的請求寫入流非竿，我們就需要對該流調用closeAndrecv蜕着，讓grpc知道我們已經(jīng)完成了寫入，并期望收到響應红柱。我們從closeAndrecv返回的錯誤中獲取RPC狀態(tài)承匣。如果狀態(tài)為nil，那么closeAndrecv的第一個返回值將是有效的服務器響應豹芯。

雙向streaming RPC

最后悄雅，讓我們看看雙向流式RPC RouteChat()。就像在recordroute中一樣铁蹈，我們只傳遞方法一個context對象宽闲，并返回一個可以用來寫和讀消息的流众眨。但是，這一次我們通過自己的方法的stream返回response容诬，而服務器仍在繼續(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

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

Try it out!

編譯和運行服務器习蓬，假設您在文件夾中$GOPATH/src/google.golang.org/grpc/examples/route_guide:

$ go run server/server.go

同樣纽什，要運行客戶機：

$ go run client/client.go

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