pkg/grpc — gRPC Server 封裝

設計理念

pkg/server → HTTP/1.1 + HTTP/2 + HTTP/3(REST + WebSocket) :8080
pkg/grpc → gRPC Server :9090
兩者共用:
 app/models/ ← 資料結構
 app/services/ ← 業務邏輯
 pkg/errors/ ← Error Catalog
 pkg/hidb/ ← 資料庫
 pkg/logger/ ← 日誌
 pkg/config/ ← 設定

快速上手

建立 gRPC 專案

hyp new grpc userservice && cd userservice && go mod tidy
make proto # 編譯 .proto → Go code
go run .

在既有專案中加入 gRPC

import (
 hypgrpc "github.com/maoxiaoyue/hypgo/pkg/grpc"
 "github.com/maoxiaoyue/hypgo/pkg/grpc/interceptor"
)
grpcSrv := hypgrpc.New(hypgrpc.Config{
 Addr: ":9090",
 EnableReflection: true,
 EnableHealthCheck: true,
}, logger,
 grpc.ChainUnaryInterceptor(
 interceptor.Recovery(logger),
 interceptor.Logger(logger),
 ),
)
// 註冊服務
pb.RegisterUserServiceServer(grpcSrv.GRPCServer(), &UserServer{})
// 啟動
go grpcSrv.Start()
// 優雅關閉
grpcSrv.GracefulStop()

Config

type Config struct {
 Addr string // 監聽地址(預設 ":9090")
 TLS *TLSConfig // TLS 配置(nil = plaintext)
 EnableReflection bool // 啟用 gRPC reflection(grpcurl 偵錯)
 EnableHealthCheck bool // 啟用 gRPC health check 服務
 MaxRecvMsgSize int // 最大接收訊息大小(預設 4MB)
 MaxSendMsgSize int // 最大發送訊息大小(預設 4MB)
}
type TLSConfig struct {
 CertFile string
 KeyFile string
}

Server API

Interceptor(gRPC 中間件)

使用 Interceptor

s := hypgrpc.New(cfg, logger,
 grpc.ChainUnaryInterceptor(
 interceptor.Recovery(logger), // 最外層:捕獲 panic
 interceptor.Logger(logger), // 記錄每個 RPC
 interceptor.Auth(myAuthFunc, // 驗證 token
 "/grpc.health.v1.Health/Check", // 跳過 health check
 ),
 interceptor.RateLimit(interceptor.RateLimitConfig{
 MaxRequests: 100, // 每分鐘 100 次
 Window: time.Minute,
 }),
 ),
)

Auth Interceptor 詳解

// 定義驗證函式
authFn := func(ctx context.Context, token string) (interface{}, error) {
 // 驗證 JWT token
 claims, err := jwt.Validate(token)
 if err != nil {
 return nil, err // → codes.Unauthenticated
 }
 return claims, nil // 存入 context
}
// 在 RPC handler 中取出使用者
func (s *Server) GetUser(ctx context.Context, req *pb.GetUserReq) (*pb.UserResp, error) {
 user, ok := interceptor.UserFromContext(ctx)
 if !ok {
 return nil, status.Error(codes.Internal, "no user in context")
 }
 // user 是 authFn 回傳的物件
}

RateLimit 安全設計

專案結構

hyp new grpc userservice

userservice/
├── app/
│ ├── proto/userservicepb/
│ │ └── userservice.proto ← Protobuf 定義
│ ├── rpc/
│ │ └── userservice_server.go ← gRPC 服務實作
│ ├── models/ ← 共用資料結構
│ ├── services/ ← 共用業務邏輯
│ └── config/config.yaml
├── main.go
├── Makefile ← make proto
└── go.mod

新增更多服務

hyp generate proto order
# → app/proto/orderpb/order.proto
# → app/rpc/order_server.go

與 REST 的共存

func main() {
 // REST Server
 srv := server.New(cfg, log)
 routers.Setup(srv.Router())
 // gRPC Server
 grpcSrv := hypgrpc.New(hypgrpc.Config{Addr: ":9090"}, log)
 pb.RegisterUserServiceServer(grpcSrv.GRPCServer(), &UserServer{})
 // 同時啟動
 go srv.Start() // :8080 REST
 go grpcSrv.Start() // :9090 gRPC
 // 優雅關閉
 quit := make(chan os.Signal, 1)
 signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
 <-quit
 srv.Shutdown(ctx)
 grpcSrv.GracefulStop()
}

共用 Service 層

Controller (REST) ─┐
 ├─→ UserService (app/services/) ─→ Database
RPC Handler (gRPC) ─┘

安全

必要工具

# protoc 編譯器
# https://github.com/protocolbuffers/protobuf/releases
# Go protobuf 插件
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
# 偵錯工具(可選)
go install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest