This resume is also available in English.

三、拆成微服務第 2 / 4 篇 · 全部目錄

專欄 › 三、拆成微服務 › 第 10 篇

gRPC 與 Protocol Buffers

gRPC and Protocol Buffers in Go

用一份 .proto 契約定義服務之間的介面,以 protoc 產生型別安全的 Go 程式碼,實作一元與串流呼叫,並學會 deadline、狀態碼、攔截器與向後相容的欄位演進規則。

  • Go
  • gRPC
  • Protobuf
  • Microservices
這篇的步驟
  1. 這篇要解決什麼
  2. 第 1 步:設計 proto 契約
  3. 第 2 步:產生 Go 程式碼
  4. 第 3 步:實作伺服器
  5. 第 4 步:實作用戶端:連線、deadline 與狀態碼
  6. 第 5 步:攔截器:gRPC 的中介層
  7. 第 6 步:讓契約可以演進:向後相容規則
  8. 常見陷阱
  9. 重點整理
  10. 下一篇

上一篇〈什麼時候該拆:邊界與拆分策略〉我們把商店整理成 order、payment、inventory 三個模組,並且讓 order 只透過 InventoryService 介面跟庫存溝通。這篇接著把那個介面「搬到網路上」:當 inventory 變成獨立服務,order 要用什麼方式呼叫它,才能像呼叫本地函式一樣有型別檢查,又能處理逾時與錯誤?

這篇要解決什麼

服務之間最直覺的溝通方式是 JSON over HTTP,用〈net/http 與中介層〉學到的東西就能完成。但服務數量變多以後,幾個問題會越來越明顯:

  • 契約散落各處:請求與回應長什麼樣子,只寫在文件或對方的程式碼裡。對方改了欄位名稱,你要到執行期才會發現。
  • 每個服務都在重複寫序列化與錯誤處理:狀態碼怎麼對應、錯誤訊息放哪裡,各寫各的。
  • 缺少標準的逾時傳遞與串流:要自己約定標頭、自己處理長連線。

gRPC 搭配 Protocol Buffers(簡稱 Protobuf)把這些問題一次標準化:用一份 .proto 檔描述服務與訊息,工具產生雙方的程式碼;傳輸用 HTTP/2,訊息用緊湊的二進位格式;deadline、狀態碼、metadata、串流都有統一的規則。

這篇會依序完成:

  1. 設計 inventory 服務的 .proto 契約。
  2. 用 protoc 搭配 protoc-gen-go 與 protoc-gen-go-grpc 產生 Go 程式碼。
  3. 實作伺服器:一元呼叫與伺服器串流。
  4. 實作用戶端:grpc.NewClient、deadline 與狀態碼處理。
  5. 用攔截器處理日誌、panic 復原與請求 ID 傳遞。
  6. 學會在不破壞舊用戶端的前提下修改契約。

提示:本篇的 Go 程式碼依賴 google.golang.org/grpc 與 google.golang.org/protobuf 兩個第三方模組,所以以片段形式呈現。它們使用目前的 API(例如 grpc.NewClient,而不是已標示為不建議使用的 grpc.Dial)。

第 1 步:設計 proto 契約

依照系列的專案結構,契約放在 api/proto/ 底下,並依「服務/版本」分目錄:api/proto/inventory/v1/inventory.proto。版本號放在套件名稱與路徑裡,未來真的需要不相容的大改版時,可以讓 v1 與 v2 並存一段時間。

syntax = "proto3";

package shop.inventory.v1;

import "google/protobuf/timestamp.proto";

option go_package = "example.com/shop/api/proto/inventory/v1;inventoryv1";

// 庫存服務:給訂單服務預留庫存,也能訂閱庫存變化。
service InventoryService {
  // 一元呼叫:一個請求、一個回應。
  rpc ReserveStock(ReserveStockRequest) returns (ReserveStockResponse);
  // 伺服器串流:訂閱後,伺服器持續推送庫存變化。
  rpc WatchStock(WatchStockRequest) returns (stream StockEvent);
}

message LineItem {
  string sku = 1;
  int32 quantity = 2;
}

message ReserveStockRequest {
  string order_id = 1;
  repeated LineItem items = 2;
  // 欄位 3 曾經是 string warehouse,已移除;號碼與名稱都保留,避免被重複使用。
  reserved 3;
  reserved "warehouse";
}

message ReserveStockResponse {
  string reservation_id = 1;
  google.protobuf.Timestamp expires_at = 2;
}

message WatchStockRequest {
  repeated string skus = 1;
}

message StockEvent {
  string sku = 1;
  int32 available = 2;
  google.protobuf.Timestamp changed_at = 3;
}

逐項說明這份檔案的設計考量:

  • syntax = "proto3":目前最普遍的語法。較新的 Protobuf 也支援以 edition = "2023" 開頭的「版本(editions)」寫法,它把 proto2 與 proto3 的差異改成可個別設定的功能旗標;對大部分新服務來說,proto3 已經足夠,而且所有工具鏈都支援。
  • package shop.inventory.v1:Protobuf 自己的命名空間,會出現在 gRPC 的方法全名裡,例如 /shop.inventory.v1.InventoryService/ReserveStock。
  • option go_package:產生的 Go 程式碼要放在哪個 import 路徑、套件叫什麼名字。分號後面的 inventoryv1 是套件名稱,避免每個版本都叫 v1 而互相衝突。
  • 每個 RPC 都有自己專屬的 Request 與 Response 訊息:即使現在只有一個欄位,也不要直接用 string 或共用的訊息。專屬訊息讓你日後加欄位時不必改方法簽章。
  • 欄位號碼才是線上格式真正認的東西,名稱只是給人看的。號碼 1 到 15 編碼只佔一個位元組,留給最常用的欄位。
  • reserved:被刪除的欄位,號碼和名稱都要保留,防止日後有人重複使用同一個號碼而讀到意義不同的舊資料。
  • 時間用 google.protobuf.Timestamp,不要自己用字串或整數,跨語言時才不會有時區與精度的爭議。
  • 金額:商店的金額一律用 int64 的「分」表示(和 Order.Total 一致),不要用 double。

第 2 步:產生 Go 程式碼

需要三樣工具:Protobuf 編譯器 protoc,以及兩個 Go 外掛。protoc-gen-go 產生訊息型別,protoc-gen-go-grpc 產生服務的用戶端與伺服器介面。

# 安裝兩個外掛(裝到 $GOBIN,需在 PATH 裡)
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest

# 在專案根目錄產生程式碼,輸出到 proto 檔旁邊
protoc -I api/proto \
  --go_out=api/proto --go_opt=paths=source_relative \
  --go-grpc_out=api/proto --go-grpc_opt=paths=source_relative \
  inventory/v1/inventory.proto

# 會得到:
#   api/proto/inventory/v1/inventory.pb.go       訊息型別
#   api/proto/inventory/v1/inventory_grpc.pb.go  Client/Server 介面

# 把 grpc 與 protobuf 加進 go.mod
go get google.golang.org/grpc google.golang.org/protobuf

paths=source_relative 讓輸出位置跟著 .proto 的相對路徑走,所以產生的套件 import 路徑就是 example.com/shop/api/proto/inventory/v1,和 go_package 一致。

inventory.proto 唯一的契約 protoc + go、go-grpc 外掛 inventory.pb.go 訊息型別、序列化 inventory_grpc.pb.go Client 與 Server 介面 兩個服務都從同一份 proto 產生程式碼,型別不一致會在編譯期就發現

圖:一份 inventory.proto 經過 protoc 與兩個外掛,產生訊息型別與服務介面;伺服器與用戶端都 import 同一份產生的程式碼。

產生的程式碼要不要提交進版本控制?兩種做法都常見。提交的好處是 go build 不需要額外工具,壞處是要記得重新產生;不提交則要在 CI 裡加一步產生。無論哪種,都建議用 Makefile 或 go generate 把上面的指令固定下來,並鎖定外掛版本,避免不同人產生出不同結果。也有團隊改用 buf 這類工具來管理產生設定與相容性檢查,第 6 步會提到。

第 3 步:實作伺服器

protoc-gen-go-grpc 產生了一個 InventoryServiceServer 介面,我們要做的就是實作它,然後註冊到 grpc.Server。下面是 cmd/inventory/main.go 的精簡版本,包含一元呼叫 ReserveStock、伺服器串流 WatchStock,以及兩個攔截器(第 5 步說明):

// 片段:inventory 服務的 gRPC 伺服器
package main

import (
	"context"
	"log"
	"net"
	"sync"
	"time"

	"google.golang.org/grpc"
	"google.golang.org/grpc/codes"
	"google.golang.org/grpc/status"
	"google.golang.org/protobuf/types/known/timestamppb"

	inventoryv1 "example.com/shop/api/proto/inventory/v1"
)

type inventoryServer struct {
	// 內嵌 Unimplemented:proto 新增方法時舊實作仍能編譯,未實作的方法回傳 Unimplemented。
	inventoryv1.UnimplementedInventoryServiceServer

	mu    sync.Mutex
	stock map[string]int32
}

func (s *inventoryServer) ReserveStock(ctx context.Context, req *inventoryv1.ReserveStockRequest) (*inventoryv1.ReserveStockResponse, error) {
	if req.GetOrderId() == "" || len(req.GetItems()) == 0 {
		return nil, status.Error(codes.InvalidArgument, "order_id and items are required")
	}
	s.mu.Lock()
	defer s.mu.Unlock()
	for _, it := range req.GetItems() {
		if it.GetQuantity() <= 0 {
			return nil, status.Errorf(codes.InvalidArgument, "quantity of %s must be positive", it.GetSku())
		}
		if s.stock[it.GetSku()] < it.GetQuantity() {
			// 業務上的「不夠」用 FailedPrecondition,呼叫端不該盲目重試
			return nil, status.Errorf(codes.FailedPrecondition, "sku %s out of stock", it.GetSku())
		}
	}
	if err := ctx.Err(); err != nil { // 呼叫端已放棄就別再扣庫存
		return nil, status.FromContextError(err).Err()
	}
	for _, it := range req.GetItems() {
		s.stock[it.GetSku()] -= it.GetQuantity()
	}
	return &inventoryv1.ReserveStockResponse{
		ReservationId: "rsv-" + req.GetOrderId(),
		ExpiresAt:     timestamppb.New(time.Now().Add(15 * time.Minute)),
	}, nil
}

func (s *inventoryServer) WatchStock(req *inventoryv1.WatchStockRequest, stream grpc.ServerStreamingServer[inventoryv1.StockEvent]) error {
	ticker := time.NewTicker(2 * time.Second)
	defer ticker.Stop()
	for {
		select {
		case <-stream.Context().Done(): // 用戶端斷線或逾時
			return status.FromContextError(stream.Context().Err()).Err()
		case <-ticker.C:
			s.mu.Lock()
			for _, sku := range req.GetSkus() {
				ev := &inventoryv1.StockEvent{Sku: sku, Available: s.stock[sku], ChangedAt: timestamppb.Now()}
				if err := stream.Send(ev); err != nil {
					s.mu.Unlock()
					return err
				}
			}
			s.mu.Unlock()
		}
	}
}

// 記錄每個呼叫的方法、耗時與狀態碼的一元攔截器。
func logUnary(ctx context.Context, req any, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (any, error) {
	start := time.Now()
	resp, err := handler(ctx, req)
	log.Printf("method=%s code=%s dur=%s", info.FullMethod, status.Code(err), time.Since(start))
	return resp, err
}

// 把 panic 轉成 Internal,避免整個行程掛掉。
func recoverUnary(ctx context.Context, req any, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (resp any, err error) {
	defer func() {
		if r := recover(); r != nil {
			log.Printf("panic in %s: %v", info.FullMethod, r)
			err = status.Error(codes.Internal, "internal error")
		}
	}()
	return handler(ctx, req)
}

func main() {
	lis, err := net.Listen("tcp", ":9003")
	if err != nil {
		log.Fatal(err)
	}
	srv := grpc.NewServer(
		grpc.ChainUnaryInterceptor(recoverUnary, logUnary), // 由外而內依序執行
	)
	inventoryv1.RegisterInventoryServiceServer(srv, &inventoryServer{
		stock: map[string]int32{"SKU-1": 10, "SKU-2": 3},
	})
	log.Println("inventory gRPC listening on :9003")
	log.Fatal(srv.Serve(lis))
}

幾個值得注意的地方:

  • 內嵌 UnimplementedInventoryServiceServer:這是 grpc-go 預設要求的寫法(以值內嵌)。將來 proto 加了新方法,舊的實作仍然能編譯,呼叫新方法只會得到 Unimplemented 錯誤,而不是整個服務編譯失敗。
  • 錯誤一律用 status.Error / status.Errorf 回傳:直接回傳一般的 error,用戶端只會看到 Unknown,無法判斷該不該重試。
  • 用 getter 讀欄位:req.GetOrderId() 在 req 為 nil 時也安全,是 Protobuf 產生程式碼的慣例。
  • 檢查 ctx:用戶端已經放棄(逾時或取消)就不要再做有副作用的事。status.FromContextError 會把 context.DeadlineExceeded 轉成對應的 gRPC 狀態碼。這是〈context:取消、逾時與資料傳遞〉的原則在 gRPC 上的應用。
  • 串流方法的簽章:目前版本的產生程式碼用泛型型別 grpc.ServerStreamingServer[StockEvent],Send 送出一則事件,stream.Context() 在用戶端斷線時會被取消。

gRPC 定義了四種呼叫方式,對應 proto 裡 stream 關鍵字出現的位置:

用戶端 伺服器 一元 伺服器串流 用戶端串流 雙向串流 實線箭頭:請求 強調色箭頭:回應

圖:一元呼叫是一問一答;伺服器串流是一個請求、多個回應;用戶端串流是多個請求、一個回應;雙向串流則兩邊都能持續傳送。

呼叫方式proto 寫法典型用途
一元(unary)rpc A(Req) returns (Resp)絕大多數的查詢與命令,例如預留庫存
伺服器串流rpc A(Req) returns (stream Resp)訂閱變化、分批回傳大量結果
用戶端串流rpc A(stream Req) returns (Resp)上傳大量資料後回傳一個摘要
雙向串流rpc A(stream Req) returns (stream Resp)聊天、即時協作、長時間雙向同步

建議以一元呼叫為主。串流很強大,但負載平衡、重試與除錯都更複雜:一條長串流會一直黏在同一個後端實例上,後端重新部署時也要處理串流中斷後的重連。

第 4 步:實作用戶端:連線、deadline 與狀態碼

用戶端這邊是 order 服務呼叫 inventory。重點有三個:連線建立一次、每次呼叫都帶 deadline、依狀態碼決定後續動作。

// 片段:訂單服務呼叫 inventory 服務
package main

import (
	"context"
	"errors"
	"io"
	"log"
	"time"

	"google.golang.org/grpc"
	"google.golang.org/grpc/codes"
	"google.golang.org/grpc/credentials/insecure"
	"google.golang.org/grpc/status"

	inventoryv1 "example.com/shop/api/proto/inventory/v1"
)

func main() {
	// NewClient 不會立刻連線,第一次呼叫時才建立連線;整個行程共用這一個 conn。
	conn, err := grpc.NewClient("dns:///inventory:9003",
		grpc.WithTransportCredentials(insecure.NewCredentials()), // 正式環境改用 TLS
	)
	if err != nil {
		log.Fatal(err)
	}
	defer conn.Close()
	client := inventoryv1.NewInventoryServiceClient(conn)

	// 每一次呼叫都帶 deadline
	ctx, cancel := context.WithTimeout(context.Background(), 800*time.Millisecond)
	defer cancel()
	resp, err := client.ReserveStock(ctx, &inventoryv1.ReserveStockRequest{
		OrderId: "o-1001",
		Items:   []*inventoryv1.LineItem{{Sku: "SKU-1", Quantity: 2}},
	})
	switch status.Code(err) {
	case codes.OK:
		log.Printf("reserved %s until %s", resp.GetReservationId(), resp.GetExpiresAt().AsTime())
	case codes.FailedPrecondition:
		log.Printf("out of stock: %s", status.Convert(err).Message())
	case codes.DeadlineExceeded, codes.Unavailable:
		log.Printf("inventory temporarily unavailable: %v", err) // 交給重試策略處理
	default:
		log.Printf("reserve failed: %v", err)
	}

	// 伺服器串流:一直 Recv 直到 io.EOF 或錯誤
	wctx, wcancel := context.WithTimeout(context.Background(), 10*time.Second)
	defer wcancel()
	stream, err := client.WatchStock(wctx, &inventoryv1.WatchStockRequest{Skus: []string{"SKU-1"}})
	if err != nil {
		log.Fatal(err)
	}
	for {
		ev, err := stream.Recv()
		if errors.Is(err, io.EOF) {
			break
		}
		if err != nil {
			log.Printf("watch ended: %v", status.Code(err))
			break
		}
		log.Printf("%s available=%d", ev.GetSku(), ev.GetAvailable())
	}
}

連線:grpc.NewClient 只是建立一個 *grpc.ClientConn 物件,不會阻塞等待連線成功;真正的連線在第一次呼叫時才建立,之後斷線也會自動重連。一個 ClientConn 底下可以有多條 HTTP/2 連線,每條又能同時跑許多請求,所以整個行程應該共用一個,在 cmd/order/main.go 建立後透過依賴注入交給需要的地方,而不是每次呼叫都新建。目標字串 dns:///inventory:9003 表示用 DNS 解析,這和服務發現息息相關,留到〈服務發現與負載平衡〉詳談。

Deadline:gRPC 預設沒有逾時。不帶 deadline 的呼叫在對方卡住時會一直等,最後拖垮呼叫端的 goroutine 與連線。規則很簡單:每一次呼叫都用 context.WithTimeout 包一層。更好的是,gRPC 會把剩餘時間放進 grpc-timeout 標頭傳給伺服器,伺服器端的 ctx 自動帶著同一個期限;如果伺服器又呼叫下游,只要把同一個 ctx 傳下去,整條呼叫鏈就共用同一份時間預算。

API Gateway 預算 1 秒 訂單服務 剩 900ms 庫存服務 剩 780ms ctx ctx grpc-timeout 標頭帶著剩餘時間往下傳 任何一跳逾時:整條鏈一起收到 DeadlineExceeded,不再浪費資源 (數字僅為示意)

圖:每一跳都扣掉已經花掉的時間,剩下的預算繼續往下傳;任何一跳逾時,整條鏈一起停止。

狀態碼:gRPC 有一組固定的狀態碼,用戶端用 status.Code(err) 取得。最常用的幾個:

狀態碼意義用戶端該怎麼做
OK成功—
InvalidArgument請求本身有問題不要重試,修正請求
NotFound資源不存在不要重試
AlreadyExists要建立的東西已存在通常視為成功(冪等)
FailedPrecondition系統狀態不允許,例如庫存不足不要盲目重試,回報給使用者
PermissionDenied / Unauthenticated沒有權限/沒有登入不要重試
ResourceExhausted配額或限流稍後再試
DeadlineExceeded逾時視操作是否冪等決定
Unavailable服務暫時無法使用可以退避後重試
Internal / Unknown伺服器端的錯誤記錄、告警

伺服器端選對狀態碼,用戶端才能做出正確決定。最常見的錯誤是把所有失敗都回成 Internal,結果用戶端無法分辨「不該重試的業務錯誤」與「可以重試的暫時錯誤」。何時、怎麼重試,會在〈逾時、重試與熔斷〉完整討論。

提示:DeadlineExceeded 不代表伺服器沒有執行。請求可能已經成功扣了庫存,只是回應來不及送回。所以有副作用的操作要搭配冪等鍵,這是〈冪等與分散式鎖〉的主題。

第 5 步:攔截器:gRPC 的中介層

〈net/http 與中介層〉裡,我們用包裝 http.Handler 的方式加入日誌、復原等橫切邏輯。gRPC 的對應物是攔截器(interceptor),分成伺服器端與用戶端、一元與串流四種。

第 3 步的伺服器已經用了兩個一元攔截器:recoverUnary 把 panic 轉成 Internal 錯誤,logUnary 記錄方法名稱、耗時與狀態碼。grpc.ChainUnaryInterceptor(recoverUnary, logUnary) 會由外而內依序執行,就像洋蔥的外層到內層。

用戶端也能加攔截器。下面這個例子把 ctx 裡的請求 ID 放進 gRPC 的 metadata(相當於 HTTP 標頭),讓下游服務的日誌能對得上同一個請求;伺服器端則用 metadata.FromIncomingContext 讀回來:

// 片段:用戶端攔截器,把請求 ID 放進 metadata 傳給下游
package middleware

import (
	"context"

	"google.golang.org/grpc"
	"google.golang.org/grpc/metadata"
)

type requestIDKey struct{}

func RequestIDUnary(ctx context.Context, method string, req, reply any,
	cc *grpc.ClientConn, invoker grpc.UnaryInvoker, opts ...grpc.CallOption) error {
	if id, ok := ctx.Value(requestIDKey{}).(string); ok {
		ctx = metadata.AppendToOutgoingContext(ctx, "x-request-id", id)
	}
	return invoker(ctx, method, req, reply, cc, opts...)
}

// 伺服器端讀回來
func RequestIDFrom(ctx context.Context) string {
	if md, ok := metadata.FromIncomingContext(ctx); ok {
		if v := md.Get("x-request-id"); len(v) > 0 {
			return v[0]
		}
	}
	return ""
}

在用戶端建立連線時,用 grpc.WithChainUnaryInterceptor(RequestIDUnary) 掛上去即可。實務上,日誌、指標與分散式追蹤通常不需要自己寫攔截器:OpenTelemetry 為 grpc-go 提供了現成的 stats handler,這會在〈可觀測性:日誌、指標、追蹤〉介紹。自己寫攔截器時要記得:metadata 的 key 一律是小寫;不要把敏感資料放進 metadata;攔截器裡出錯時也要回傳 status 錯誤。

除了攔截器,伺服器上線前通常還會註冊兩個標準服務:健康檢查(grpc.health.v1.Health,給負載平衡器與 Kubernetes 探測用)與反射(reflection,讓 grpcurl 這類工具能列出服務、方便除錯;正式環境可視安全需求決定是否開啟)。

第 6 步:讓契約可以演進:向後相容規則

服務獨立部署以後,新舊版本一定會同時在線上:inventory 已經升級,但還有舊版的 order 在跑,或反過來。Protobuf 的設計讓這件事有機會做對,前提是遵守規則:

修改安全嗎說明
新增欄位(用新號碼)安全舊程式讀到不認得的欄位會略過;新程式讀舊資料拿到零值
新增 RPC 方法安全舊伺服器收到會回 Unimplemented
刪除欄位並 reserved 號碼與名稱安全舊資料裡的那個欄位被略過
修改欄位名稱線上格式安全,但會破壞程式碼與 JSON 對應盡量避免
修改欄位號碼不安全等於刪除舊欄位再新增
修改欄位型別大多不安全只有少數相容型別例外,不要依賴
重複使用已刪除的號碼非常危險舊資料會被解讀成完全不同的意思
修改套件或服務名稱不安全方法全名改變,舊用戶端找不到

還有一個語意上的陷阱:proto3 的純量欄位沒有「沒填」與「填了零值」的區別,quantity 是 0 時你分不出是對方沒送,還是真的送了 0。如果業務上需要區分,可以在欄位前加 optional,產生的 Go 欄位會變成指標,以是否為 nil 判斷有沒有設定。

列舉(enum)也要注意:第一個值一定要是 0,而且建議命名為 XXX_UNSPECIFIED 當作「未設定」,例如 ORDER_STATUS_UNSPECIFIED = 0,接著才是 ORDER_STATUS_PENDING、ORDER_STATUS_PAID、ORDER_STATUS_CANCELLED。這樣舊程式收到新增的列舉值時,至少不會被誤認成某個有意義的狀態。

把這些規則交給工具檢查最可靠。buf breaking 可以比對目前的 proto 與主分支上的版本,在 CI 裡直接擋下不相容的修改。真的必須做不相容的大改時,就新增 v2 套件,讓兩個版本並存,等所有用戶端都遷移後再移除 v1。

常見陷阱

  • 沒有設 deadline:gRPC 預設會一直等,下游一卡住,上游的 goroutine 就跟著堆積。每一次呼叫都要有逾時。
  • 每次呼叫都新建連線:grpc.NewClient 應該在啟動時建立一次、整個行程共用;每次新建會浪費 TCP 與 TLS 握手,也讓負載平衡失效。
  • 回傳一般 error:沒有用 status.Error 包裝,用戶端只看到 Unknown,無法決定要不要重試。
  • 重複使用欄位號碼:刪掉欄位卻沒有 reserved,日後有人用同一個號碼放別的東西,舊資料就被讀成錯的值。
  • 把 proto 訊息當成領域模型到處傳:產生的型別帶有內部狀態,不能直接複製;而且把它滲進業務邏輯,會讓契約變更牽動所有程式碼。在 handler 層把它轉成自己的領域型別(例如 Order)。
  • 濫用串流:長串流會黏在同一個實例上,負載不均、部署時大量中斷。能用一元呼叫就用一元呼叫。
  • 在正式環境用 insecure.NewCredentials():叢集內部也建議用 TLS 或 mTLS,或交給服務網格處理。
  • 訊息過大:預設接收上限約 4 MB。需要傳大量資料時改用串流分批,或改傳物件儲存的位址,而不是一味調高上限。

重點整理

  • gRPC+Protobuf 用一份 .proto 契約定義服務,工具產生雙方型別安全的程式碼,傳輸用 HTTP/2。
  • 契約放在 api/proto/<服務>/<版本>/,每個 RPC 有專屬的 Request/Response,時間用 Timestamp,金額用 int64 的分。
  • protoc 搭配 protoc-gen-go 與 protoc-gen-go-grpc 產生程式碼,指令與外掛版本要固定下來。
  • 伺服器內嵌 Unimplemented...Server,錯誤用 status 回傳並選對狀態碼,執行有副作用的動作前檢查 ctx。
  • 用戶端用 grpc.NewClient 建立一次、全行程共用;每次呼叫都帶 deadline,並依狀態碼決定是否重試。
  • 攔截器是 gRPC 的中介層,適合處理日誌、panic 復原、請求 ID 與追蹤。
  • 契約演進只新增、不改號碼、刪除就 reserved;用 buf breaking 在 CI 裡檢查。

下一篇

服務之間現在能用 gRPC 溝通了,但瀏覽器與外部合作夥伴不會直接呼叫內部的 gRPC 服務,認證、限流與請求 ID 也不該在每個服務裡各寫一次。下一篇〈API Gateway:路由、認證、限流〉會用標準函式庫寫一個小型 Gateway,把這些工作集中在系統的入口處理。