gRPC-Connect協議：Go微服務前後端統一通信實戰2026

技术架构

引言：為什麼你的微服務前後端通訊方案還是一團糟

2026年了，如果你的Go微服務還在用REST + JSON手動維護兩套API定義（後端Protobuf + 前端TypeScript），那你一定深陷以下泥潭：後端改了欄位前端不知道、Swagger文件永遠過期、流式通訊只能用WebSocket硬湊、錯誤碼前後端各定義一套……

gRPC-Connect協議的出現終結了這一切。它基於Protobuf定義一套服務，後端用gRPC高效能通訊，前端用Connect-RPC的HTTP/JSON模式無縫呼叫，一套Proto，兩端通用。Buf生態的成熟讓這一切變得前所未有地簡單。

本文將帶你用Go從零構建5個gRPC-Connect核心模式，涵蓋從服務定義到生產級閘道的完整鏈路。

核心概念速覽

概念 說明 生態工具
gRPC-Connect 基於HTTP/2的RPC協議，同時支援gRPC和Connect協議 connect-go
Connect-RPC Connect協議的Go實作，支援gRPC/gRPC-Web/Connect三種模式 connectrpc.com
Buf Protobuf建構工具鏈，替代protoc buf.build
gRPC-Web 瀏覽器端gRPC協議 connect-web
Protobuf 介面定義語言 google.golang.org/protobuf
流式通訊 Server/Client/Bidirectional Streaming connect-go
Interceptor Connect中介層機制 connect-go

五大痛點：傳統前後端通訊為什麼撐不住了

痛點1：雙套API定義維護噩夢。後端用Protobuf定義gRPC服務，前端用TypeScript介面定義REST API，兩套定義永遠不同步。

痛點2：Swagger文件形同虛設。手動維護的OpenAPI文件總是落後於實際程式碼，前端開發者經常對著過期文件除錯。

痛點3：流式通訊方案割裂。gRPC的Streaming在瀏覽器端不可用，被迫引入WebSocket，導致通訊協議碎片化。

痛點4：錯誤處理不一致。gRPC用Status Code，REST用HTTP Status Code，前端需要兩套錯誤處理邏輯。

痛點5：程式碼生成工具鏈混亂。protoc外掛版本衝突、生成程式碼風格不統一、CI/CD整合困難。

模式一：Connect-RPC服務定義

使用Buf和Connect-RPC定義服務，一套Proto同時生成Go後端和TypeScript前端程式碼。

// 執行環境: Buf v1.47+, connect-go v1.18+, protoc-gen-go v1.34+
// 檔案: proto/order/v1/order.proto

syntax = "proto3";

package order.v1;

option go_package = "github.com/example/gen/order/v1;orderv1";

service OrderService {
  rpc CreateOrder(CreateOrderRequest) returns (CreateOrderResponse) {}
  rpc GetOrder(GetOrderRequest) returns (GetOrderResponse) {}
  rpc StreamOrders(StreamOrdersRequest) returns (stream Order) {}
  rpc UploadOrders(stream UploadOrderRequest) returns (UploadOrdersResponse) {}
  rpc OrderChat(stream ChatMessage) returns (stream ChatMessage) {}
}

message CreateOrderRequest {
  string user_id = 1;
  repeated OrderItem items = 2;
  string shipping_address = 3;
}

message CreateOrderResponse {
  string order_id = 1;
  string status = 2;
  int64 created_at = 3;
}

message GetOrderRequest {
  string order_id = 1;
}

message GetOrderResponse {
  Order order = 1;
}

message Order {
  string order_id = 1;
  string user_id = 2;
  repeated OrderItem items = 3;
  string status = 4;
  int64 created_at = 5;
  int64 updated_at = 6;
}

message OrderItem {
  string product_id = 1;
  string product_name = 2;
  int32 quantity = 3;
  double price = 4;
}

message StreamOrdersRequest {
  string user_id = 1;
}

message UploadOrderRequest {
  string user_id = 1;
  repeated OrderItem items = 2;
}

message UploadOrdersResponse {
  int32 total_created = 1;
  repeated string order_ids = 2;
}

message ChatMessage {
  string sender = 1;
  string message = 2;
  int64 timestamp = 3;
}

# 檔案: buf.yaml
version: v2
modules:
  - path: proto
    name: buf.build/example/orders
lint:
  use:
    - STANDARD
breaking:
  use:
    - FILE

# 檔案: buf.gen.yaml
version: v2
managed:
  enabled: true
  override:
    - file_option: go_package_prefix
      value: github.com/example/gen
plugins:
  - remote: buf.build/connectrpc/go:v1.18.0
    out: gen/go
    opt: paths=source_relative
  - remote: buf.build/protocolbuffers/go:v1.34.0
    out: gen/go
    opt: paths=source_relative
  - remote: buf.build/connectrpc/es:v2.0.0
    out: gen/ts
  - remote: buf.build/bufbuild/es:v2.0.0
    out: gen/ts

// 執行環境: Go 1.22+, connect-go v1.18.0
// 檔案: server/main.go
package main

import (
	"context"
	"fmt"
	"log"
	"net/http"
	"time"

	"connectrpc.com/connect"
	"connectrpc.com/grpcreflect"
	"github.com/example/gen/order/v1/orderv1connect"

	orderpb "github.com/example/gen/order/v1"
)

// OrderServiceHandler 訂單服務實作
type OrderServiceHandler struct {
	orders map[string]*orderpb.Order
}

// CreateOrder 建立訂單
func (h *OrderServiceHandler) CreateOrder(
	ctx context.Context,
	req *connect.Request[orderpb.CreateOrderRequest],
) (*connect.Response[orderpb.CreateOrderResponse], error) {
	msg := req.Msg

	orderID := fmt.Sprintf("ord-%d", time.Now().UnixNano())
	order := &orderpb.Order{
		OrderId:    orderID,
		UserId:     msg.UserId,
		Items:      msg.Items,
		Status:     "CREATED",
		CreatedAt:  time.Now().Unix(),
		UpdatedAt:  time.Now().Unix(),
	}
	h.orders[orderID] = order

	resp := connect.NewResponse(&orderpb.CreateOrderResponse{
		OrderId:   orderID,
		Status:    "CREATED",
		CreatedAt: order.CreatedAt,
	})

	resp.Header().Set("X-Request-Id", fmt.Sprintf("req-%d", time.Now().UnixNano()))
	return resp, nil
}

// GetOrder 取得訂單
func (h *OrderServiceHandler) GetOrder(
	ctx context.Context,
	req *connect.Request[orderpb.GetOrderRequest],
) (*connect.Response[orderpb.GetOrderResponse], error) {
	order, exists := h.orders[req.Msg.OrderId]
	if !exists {
		return nil, connect.NewError(connect.CodeNotFound,
			fmt.Errorf("訂單 %s 不存在", req.Msg.OrderId))
	}

	resp := connect.NewResponse(&orderpb.GetOrderResponse{
		Order: order,
	})
	return resp, nil
}

// StreamOrders 服務端串流推送訂單
func (h *OrderServiceHandler) StreamOrders(
	ctx context.Context,
	req *connect.Request[orderpb.StreamOrdersRequest],
	stream *connect.ServerStream[orderpb.Order],
) error {
	for _, order := range h.orders {
		if order.UserId == req.Msg.UserId {
			if err := stream.Send(order); err != nil {
				return fmt.Errorf("傳送訂單串流失敗: %w", err)
			}
			time.Sleep(100 * time.Millisecond)
		}
	}
	return nil
}

// UploadOrders 客戶端串流上傳訂單
func (h *OrderServiceHandler) UploadOrders(
	ctx context.Context,
	stream *connect.ClientStream[orderpb.UploadOrderRequest],
) (*connect.Response[orderpb.UploadOrdersResponse], error) {
	var totalCreated int32
	var orderIDs []string

	for stream.Receive() {
		msg := stream.Msg()
		orderID := fmt.Sprintf("ord-%d", time.Now().UnixNano())
		order := &orderpb.Order{
			OrderId:   orderID,
			UserId:    msg.UserId,
			Items:     msg.Items,
			Status:    "CREATED",
			CreatedAt: time.Now().Unix(),
		}
		h.orders[orderID] = order
		totalCreated++
		orderIDs = append(orderIDs, orderID)
	}

	if stream.Err() != nil {
		return nil, connect.NewError(connect.CodeInternal, stream.Err())
	}

	resp := connect.NewResponse(&orderpb.UploadOrdersResponse{
		TotalCreated: totalCreated,
		OrderIds:     orderIDs,
	})
	return resp, nil
}

// OrderChat 雙向串流聊天
func (h *OrderServiceHandler) OrderChat(
	ctx context.Context,
	stream *connect.BidiStream[orderpb.ChatMessage, orderpb.ChatMessage],
) error {
	for {
		msg, err := stream.Receive()
		if err != nil {
			return nil
		}

		reply := &orderpb.ChatMessage{
			Sender:    "system",
			Message:   fmt.Sprintf("已收到來自 %s 的訊息: %s", msg.Sender, msg.Message),
			Timestamp: time.Now().Unix(),
		}

		if err := stream.Send(reply); err != nil {
			return fmt.Errorf("傳送回覆失敗: %w", err)
		}
	}
}

func main() {
	handler := &OrderServiceHandler{
		orders: make(map[string]*orderpb.Order),
	}

	mux := http.NewServeMux()

	path, orderHandler := orderv1connect.NewOrderServiceHandler(handler)
	mux.Handle(path, orderHandler)

	reflector := grpcreflect.NewStaticReflector(
		orderv1connect.OrderServiceName,
	)
	mux.Handle(grpcreflect.NewHandlerV1(reflector))
	mux.Handle(grpcreflect.NewHandlerV1Alpha(reflector))

	log.Println("Connect-RPC服務啟動在 :8080")
	log.Println("支援協議: gRPC, gRPC-Web, Connect")
	log.Fatal(http.ListenAndServe(":8080", mux))
}

模式二：前端gRPC-Web呼叫

使用Connect-Web在前端直接呼叫gRPC服務，無需REST中介層。

// 執行環境: TypeScript 5.5+, @connectrpc/connect-web v2.0.0
// 檔案: frontend/src/client.ts

import { createConnectTransport } from "@connectrpc/connect-web";
import { createClient } from "@connectrpc/connect";
import { OrderService } from "../gen/ts/order/v1/order_pb";

// 建立Connect傳輸層
const connectTransport = createConnectTransport({
  baseUrl: "https://api.example.com",
});

// 建立gRPC-Web傳輸層
const grpcWebTransport = createConnectTransport({
  baseUrl: "https://api.example.com",
  httpVersion: "2",
});

// 建立訂單服務客戶端
const orderClient = createClient(OrderService, connectTransport);

// === Unary呼叫 ===
async function createOrder() {
  try {
    const response = await orderClient.createOrder({
      userId: "user-123",
      items: [
        { productId: "prod-1", productName: "Go程式設計", quantity: 1, price: 89.0 },
        { productId: "prod-2", productName: "Rust實戰", quantity: 2, price: 99.0 },
      ],
      shippingAddress: "台北市信義區",
    });

    console.log("訂單建立成功:", response.orderId, response.status);
  } catch (err) {
    console.error("建立訂單失敗:", err.code, err.message);
  }
}

// === 取得訂單 ===
async function getOrder(orderId: string) {
  try {
    const response = await orderClient.getOrder({ orderId });
    console.log("訂單詳情:", response.order);
  } catch (err: any) {
    if (err.code === "NOT_FOUND") {
      console.warn("訂單不存在");
    } else {
      console.error("取得訂單失敗:", err.message);
    }
  }
}

// === Server Streaming ===
async function streamOrders(userId: string) {
  try {
    for await (const order of orderClient.streamOrders({ userId })) {
      console.log("即時訂單更新:", order.orderId, order.status);
      updateOrderInUI(order);
    }
  } catch (err) {
    console.error("訂單串流中斷:", err.message);
  }
}

// === Client Streaming ===
async function uploadOrders() {
  const orders = [
    { userId: "user-1", items: [{ productId: "p1", productName: "商品1", quantity: 1, price: 10 }] },
    { userId: "user-2", items: [{ productId: "p2", productName: "商品2", quantity: 2, price: 20 }] },
  ];

  try {
    const response = await orderClient.uploadOrders(orders);
    console.log(`成功上傳 ${response.totalCreated} 個訂單`);
  } catch (err) {
    console.error("上傳訂單失敗:", err.message);
  }
}

function useOrderService() {
  return { createOrder, getOrder, streamOrders, uploadOrders };
}

function updateOrderInUI(order: any) {}

模式三：錯誤處理與重試

Connect-RPC提供統一的錯誤處理機制，前後端使用相同的錯誤碼和訊息格式。

// 執行環境: Go 1.22+, connect-go v1.18.0
// 檔案: server/errors.go
package main

import (
	"context"
	"fmt"
	"log"
	"net/http"
	"time"

	"connectrpc.com/connect"
)

// OrderError 訂單業務錯誤
type OrderError struct {
	Code      connect.Code `json:"code"`
	Message   string       `json:"message"`
	Detail    string       `json:"detail,omitempty"`
	Retryable bool         `json:"retryable"`
}

func (e *OrderError) Error() string {
	return fmt.Sprintf("[%s] %s: %s", e.Code, e.Message, e.Detail)
}

// ToConnectError 轉換為Connect錯誤
func (e *OrderError) ToConnectError() *connect.Error {
	err := connect.NewError(e.Code, fmt.Errorf("%s: %s", e.Message, e.Detail))
	if e.Retryable {
		err.Meta().Set("Retry-After", "5")
		err.Meta().Set("X-Retryable", "true")
	}
	return err
}

var (
	ErrOrderNotFound = &OrderError{
		Code:      connect.CodeNotFound,
		Message:   "訂單不存在",
		Retryable: false,
	}
	ErrOrderAlreadyCancelled = &OrderError{
		Code:      connect.CodeFailedPrecondition,
		Message:   "訂單已取消",
		Retryable: false,
	}
	ErrInsufficientStock = &OrderError{
		Code:      connect.CodeResourceExhausted,
		Message:   "庫存不足",
		Retryable: true,
	}
	ErrPaymentTimeout = &OrderError{
		Code:      connect.CodeDeadlineExceeded,
		Message:   "付款逾時",
		Retryable: true,
	}
)

// RetryInterceptor 客戶端重試中介層
type RetryInterceptor struct {
	maxRetries     int
	initialDelay   time.Duration
	maxDelay       time.Duration
	retryableCodes map[connect.Code]bool
}

func NewRetryInterceptor() *RetryInterceptor {
	return &RetryInterceptor{
		maxRetries:   3,
		initialDelay: 100 * time.Millisecond,
		maxDelay:     5 * time.Second,
		retryableCodes: map[connect.Code]bool{
			connect.CodeUnavailable:       true,
			connect.CodeResourceExhausted: true,
			connect.CodeDeadlineExceeded:  true,
			connect.CodeAborted:           true,
		},
	}
}

func (i *RetryInterceptor) WrapUnary(next connect.UnaryFunc) connect.UnaryFunc {
	return func(ctx context.Context, req connect.AnyRequest) (connect.AnyResponse, error) {
		var lastErr error

		for attempt := 0; attempt <= i.maxRetries; attempt++ {
			resp, err := next(ctx, req)
			if err == nil {
				return resp, nil
			}

			connectErr, ok := err.(*connect.Error)
			if !ok {
				return nil, err
			}

			if !i.retryableCodes[connectErr.Code()] {
				return nil, err
			}

			retryAfter := connectErr.Meta().Get("Retry-After")
			delay := i.calculateDelay(attempt, retryAfter)

			lastErr = err
			log.Printf("重試 %d/%d, 延遲 %v, 錯誤: %v",
				attempt+1, i.maxRetries, delay, connectErr.Message())

			select {
			case <-time.After(delay):
			case <-ctx.Done():
				return nil, ctx.Err()
			}
		}

		return nil, lastErr
	}
}

func (i *RetryInterceptor) calculateDelay(attempt int, retryAfter string) time.Duration {
	if retryAfter != "" {
		if d, err := time.ParseDuration(retryAfter + "s"); err == nil {
			return d
		}
	}

	delay := i.initialDelay * time.Duration(1<<uint(attempt))
	if delay > i.maxDelay {
		delay = i.maxDelay
	}
	return delay
}

// RecoveryInterceptor 服務端錯誤恢復中介層
func RecoveryInterceptor() connect.UnaryInterceptorFunc {
	return func(next connect.UnaryFunc) connect.UnaryFunc {
		return func(ctx context.Context, req connect.AnyRequest) (resp connect.AnyResponse, err error) {
			defer func() {
				if r := recover(); r != nil {
					log.Printf("[PANIC] 請求處理panic: %v", r)
					err = connect.NewError(connect.CodeInternal,
						fmt.Errorf("服務內部錯誤，請稍後重試"))
				}
			}()
			return next(ctx, req)
		}
	}
}

func ErrorLoggingInterceptor() connect.UnaryInterceptorFunc {
	return func(next connect.UnaryFunc) connect.UnaryFunc {
		return func(ctx context.Context, req connect.AnyRequest) (connect.AnyResponse, error) {
			startTime := time.Now()
			resp, err := next(ctx, req)

			if err != nil {
				connectErr, ok := err.(*connect.Error)
				if ok {
					log.Printf("[ERROR] method=%s code=%s msg=%s duration=%v",
						req.Spec().Procedure,
						connectErr.Code(),
						connectErr.Message(),
						time.Since(startTime),
					)
				}
			}

			return resp, err
		}
	}
}

func main() {
	mux := http.NewServeMux()

	interceptors := []connect.Interceptor{
		RecoveryInterceptor(),
		ErrorLoggingInterceptor(),
	}

	_ = interceptors

	log.Println("錯誤處理服務啟動在 :8080")
	log.Fatal(http.ListenAndServe(":8080", mux))
}

模式四：流式通訊

Connect-RPC完整支援三種流式通訊模式，前後端使用統一的Protobuf定義。

// 執行環境: Go 1.22+, connect-go v1.18.0
// 檔案: server/streaming.go
package main

import (
	"context"
	"fmt"
	"io"
	"log"
	"math/rand"
	"net/http"
	"sync"
	"time"

	"connectrpc.com/connect"
)

// OrderStatusStream 訂單狀態串流
type OrderStatusStream struct {
	subscribers map[string]chan *OrderStatusUpdate
	mu          sync.RWMutex
}

type OrderStatusUpdate struct {
	OrderID string `json:"order_id"`
	Status  string `json:"status"`
	Message string `json:"message"`
}

func NewOrderStatusStream() *OrderStatusStream {
	return &OrderStatusStream{
		subscribers: make(map[string]chan *OrderStatusUpdate),
	}
}

func (s *OrderStatusStream) Subscribe(userID string) <-chan *OrderStatusUpdate {
	s.mu.Lock()
	defer s.mu.Unlock()

	ch := make(chan *OrderStatusUpdate, 100)
	s.subscribers[userID] = ch
	return ch
}

func (s *OrderStatusStream) Unsubscribe(userID string) {
	s.mu.Lock()
	defer s.mu.Unlock()

	if ch, ok := s.subscribers[userID]; ok {
		close(ch)
		delete(s.subscribers, userID)
	}
}

func (s *OrderStatusStream) Publish(update *OrderStatusUpdate) {
	s.mu.RLock()
	defer s.mu.RUnlock()

	for _, ch := range s.subscribers {
		select {
		case ch <- update:
		default:
			log.Printf("訂閱者通道已滿，丟棄更新: %s", update.OrderID)
		}
	}
}

// BatchOrderImporter 批次訂單匯入器
type BatchOrderImporter struct {
	processedCount int
	failedCount    int
	mu             sync.Mutex
}

func (b *BatchOrderImporter) ProcessStream(
	ctx context.Context,
	stream *connect.ClientStream[OrderImportRequest],
) (*BatchImportResult, error) {
	batchID := fmt.Sprintf("batch-%d", time.Now().UnixNano())

	for stream.Receive() {
		req := stream.Msg()
		if err := b.processOne(ctx, req); err != nil {
			b.mu.Lock()
			b.failedCount++
			b.mu.Unlock()
			continue
		}
		b.mu.Lock()
		b.processedCount++
		b.mu.Unlock()
	}

	if stream.Err() != nil {
		return nil, connect.NewError(connect.CodeInternal, stream.Err())
	}

	return &BatchImportResult{
		BatchID:        batchID,
		ProcessedCount: int32(b.processedCount),
		FailedCount:    int32(b.failedCount),
	}, nil
}

func (b *BatchOrderImporter) processOne(ctx context.Context, req *OrderImportRequest) error {
	select {
	case <-time.After(time.Duration(rand.Intn(50)) * time.Millisecond):
	case <-ctx.Done():
		return ctx.Err()
	}
	return nil
}

// CollaborationRoom 協作房間
type CollaborationRoom struct {
	clients map[string]chan *CollabMessage
	mu      sync.RWMutex
}

type CollabMessage struct {
	UserID  string `json:"user_id"`
	Content string `json:"content"`
	Type    string `json:"type"`
}

type OrderImportRequest struct {
	UserID string `json:"user_id"`
	Data   string `json:"data"`
}

type BatchImportResult struct {
	BatchID        string `json:"batch_id"`
	ProcessedCount int32  `json:"processed_count"`
	FailedCount    int32  `json:"failed_count"`
}

func (r *CollaborationRoom) Join(userID string) chan *CollabMessage {
	r.mu.Lock()
	defer r.mu.Unlock()

	ch := make(chan *CollabMessage, 50)
	r.clients[userID] = ch
	return ch
}

func (r *CollaborationRoom) Leave(userID string) {
	r.mu.Lock()
	defer r.mu.Unlock()

	if ch, ok := r.clients[userID]; ok {
		close(ch)
		delete(r.clients, userID)
	}
}

func (r *CollaborationRoom) Broadcast(msg *CollabMessage, excludeUserID string) {
	r.mu.RLock()
	defer r.mu.RUnlock()

	for userID, ch := range r.clients {
		if userID == excludeUserID {
			continue
		}
		select {
		case ch <- msg:
		default:
			log.Printf("客戶端 %s 通道已滿", userID)
		}
	}
}

func (r *CollaborationRoom) HandleCollabStream(
	ctx context.Context,
	stream *connect.BidiStream[CollabMessage, CollabMessage],
) error {
	userID := stream.RequestHeader().Get("X-User-Id")
	if userID == "" {
		userID = fmt.Sprintf("user-%d", rand.Int63())
	}

	recvCh := r.Join(userID)
	defer r.Leave(userID)

	errCh := make(chan error, 1)
	go func() {
		for {
			msg, err := stream.Receive()
			if err != nil {
				if err == io.EOF {
					errCh <- nil
					return
				}
				errCh <- err
				return
			}
			r.Broadcast(msg, userID)
		}
	}()

	for {
		select {
		case msg := <-recvCh:
			if err := stream.Send(msg); err != nil {
				return fmt.Errorf("傳送協作訊息失敗: %w", err)
			}
		case err := <-errCh:
			return err
		case <-ctx.Done():
			return ctx.Err()
		}
	}
}

func main() {
	room := &CollaborationRoom{
		clients: make(map[string]chan *CollabMessage),
	}
	statusStream := NewOrderStatusStream()

	_ = room
	_ = statusStream

	log.Println("串流通訊服務啟動在 :8080")
	log.Fatal(http.ListenAndServe(":8080", nil))
}

模式五：生產級Connect閘道

構建生產級Connect-RPC閘道，整合認證、限流、監控和優雅關閉。

// 執行環境: Go 1.22+, connect-go v1.18.0
// 檔案: server/gateway.go
package main

import (
	"context"
	"fmt"
	"log"
	"net/http"
	"os"
	"os/signal"
	"strings"
	"sync/atomic"
	"syscall"
	"time"

	"connectrpc.com/connect"
	"connectrpc.com/grpcreflect"
	"golang.org/x/net/http2"
	"golang.org/x/net/http2/h2c"
)

func AuthInterceptor(jwtSecret string) connect.UnaryInterceptorFunc {
	return func(next connect.UnaryFunc) connect.UnaryFunc {
		return func(ctx context.Context, req connect.AnyRequest) (connect.AnyResponse, error) {
			if strings.HasSuffix(req.Spec().Procedure, "/Health/Check") {
				return next(ctx, req)
			}

			token := req.Header().Get("Authorization")
			if token == "" {
				return nil, connect.NewError(connect.CodeUnauthenticated,
					fmt.Errorf("缺少認證令牌"))
			}

			token = strings.TrimPrefix(token, "Bearer ")
			claims, err := validateJWT(token, jwtSecret)
			if err != nil {
				return nil, connect.NewError(connect.CodeUnauthenticated,
					fmt.Errorf("無效的認證令牌: %w", err))
			}

			ctx = context.WithValue(ctx, "userID", claims.UserID)
			ctx = context.WithValue(ctx, "scopes", claims.Scopes)

			return next(ctx, req)
		}
	}
}

type JWTClaims struct {
	UserID string   `json:"user_id"`
	Scopes []string `json:"scopes"`
}

func validateJWT(token, secret string) (*JWTClaims, error) {
	return &JWTClaims{
		UserID: "user-from-token",
		Scopes: []string{"orders:read", "orders:write"},
	}, nil
}

type RateLimiter struct {
	tokens     atomic.Int64
	maxTokens  int64
	refillRate time.Duration
}

func NewRateLimiter(maxTokens int64, refillRate time.Duration) *RateLimiter {
	rl := &RateLimiter{
		maxTokens:  maxTokens,
		refillRate: refillRate,
	}
	rl.tokens.Store(maxTokens)

	go func() {
		ticker := time.NewTicker(refillRate)
		defer ticker.Stop()
		for range ticker.C {
			current := rl.tokens.Load()
			if current < maxTokens {
				rl.tokens.CompareAndSwap(current, current+1)
			}
		}
	}()

	return rl
}

func (rl *RateLimiter) Allow() bool {
	for {
		current := rl.tokens.Load()
		if current <= 0 {
			return false
		}
		if rl.tokens.CompareAndSwap(current, current-1) {
			return true
		}
	}
}

func RateLimitInterceptor(limiter *RateLimiter) connect.UnaryInterceptorFunc {
	return func(next connect.UnaryFunc) connect.UnaryFunc {
		return func(ctx context.Context, req connect.AnyRequest) (connect.AnyResponse, error) {
			if !limiter.Allow() {
				return nil, connect.NewError(connect.CodeResourceExhausted,
					fmt.Errorf("請求頻率超限，請稍後重試"))
			}
			return next(ctx, req)
		}
	}
}

func TracingInterceptor() connect.UnaryInterceptorFunc {
	return func(next connect.UnaryFunc) connect.UnaryFunc {
		return func(ctx context.Context, req connect.AnyRequest) (connect.AnyResponse, error) {
			startTime := time.Now()
			traceID := req.Header().Get("X-Trace-Id")
			if traceID == "" {
				traceID = fmt.Sprintf("trace-%d", startTime.UnixNano())
			}

			log.Printf("[TRACE] id=%s method=%s start=%v",
				traceID, req.Spec().Procedure, startTime)

			resp, err := next(ctx, req)

			duration := time.Since(startTime)
			status := "OK"
			if err != nil {
				status = "ERROR"
			}

			log.Printf("[TRACE] id=%s method=%s status=%s duration=%v",
				traceID, req.Spec().Procedure, status, duration)

			if resp != nil {
				resp.Header().Set("X-Trace-Id", traceID)
				resp.Header().Set("X-Response-Time", duration.String())
			}

			return resp, err
		}
	}
}

type ConnectGateway struct {
	server     *http.Server
	limiter    *RateLimiter
	shutdownCh chan os.Signal
}

func NewConnectGateway(addr string) *ConnectGateway {
	gw := &ConnectGateway{
		limiter:    NewRateLimiter(1000, time.Second),
		shutdownCh: make(chan os.Signal, 1),
	}

	mux := http.NewServeMux()

	reflector := grpcreflect.NewStaticReflector()
	mux.Handle(grpcreflect.NewHandlerV1(reflector))

	mux.HandleFunc("/healthz", func(w http.ResponseWriter, r *http.Request) {
		w.WriteHeader(http.StatusOK)
		w.Write([]byte("ok"))
	})

	interceptors := []connect.Interceptor{
		TracingInterceptor(),
		RateLimitInterceptor(gw.limiter),
		AuthInterceptor("your-jwt-secret"),
	}

	_ = interceptors

	gw.server = &http.Server{
		Addr:    addr,
		Handler: h2c.NewHandler(mux, &http2.Server{}),
	}

	return gw
}

func (gw *ConnectGateway) Start() error {
	signal.Notify(gw.shutdownCh, syscall.SIGINT, syscall.SIGTERM)

	errCh := make(chan error, 1)
	go func() {
		log.Printf("Connect閘道啟動在 %s", gw.server.Addr)
		log.Println("支援協議: gRPC, gRPC-Web, Connect (HTTP/1.1 & HTTP/2)")
		if err := gw.server.ListenAndServe(); err != http.ErrServerClosed {
			errCh <- err
		}
	}()

	select {
	case err := <-errCh:
		return fmt.Errorf("閘道啟動失敗: %w", err)
	case sig := <-gw.shutdownCh:
		log.Printf("收到信號 %v，開始優雅關閉...", sig)
		return gw.Shutdown()
	}
}

func (gw *ConnectGateway) Shutdown() error {
	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
	defer cancel()

	log.Println("停止接受新請求...")
	if err := gw.server.Shutdown(ctx); err != nil {
		return fmt.Errorf("閘道關閉失敗: %w", err)
	}

	log.Println("閘道已優雅關閉")
	return nil
}

func main() {
	gateway := NewConnectGateway(":8080")
	if err := gateway.Start(); err != nil {
		log.Fatalf("閘道執行失敗: %v", err)
	}
}

避坑指南：5個生產級大坑

坑1：Buf程式碼生成版本衝突。不同外掛版本生成的程式碼不相容，導致編譯失敗。解決方案：在buf.gen.yaml中鎖定外掛版本，CI中使用buf generate而非本地protoc。

坑2：HTTP/2協商失敗。某些反向代理（Nginx舊版本）不支援HTTP/2，導致gRPC呼叫失敗。解決方案：使用Connect協議（HTTP/1.1相容）作為降級方案，或升級代理支援h2c。

坑3：串流通訊連線斷開無感知。網路抖動導致串流連線斷開，但服務端不知道。解決方案：實作心跳機制（每30秒傳送ping），設定讀寫逾時，客戶端自動重連。

坑4：大訊息體導致記憶體溢位。串流上傳大檔案時，接收端緩衝區滿導致OOM。解決方案：設定最大訊息體大小（Connect預設4MB），串流分塊處理，背壓控制。

坑5：CORS配置遺漏。瀏覽器端Connect呼叫被CORS策略阻止。解決方案：在閘道層配置CORS中介層，允許Content-Type: application/proto和application/json。

報錯排查速查表

報錯資訊 原因 解決方案
connect: code = Unauthenticated 缺少或無效的認證令牌 檢查Authorization標頭和JWT有效性
connect: code = NotFound 請求的資源不存在 檢查請求參數和資源ID
connect: code = ResourceExhausted 請求頻率超限 降低請求頻率或調整限流配置
connect: code = Unavailable 服務不可用 檢查服務健康狀態和網路連通性
http2: frame too large 訊息體超過預設限制 調整connect.MaxRecvMsgSize選項
CORS policy: No Access-Control-Allow-Origin 缺少CORS配置 在閘道新增CORS中介層
proto: invalid wire format Protobuf編解碼不匹配 檢查Proto檔案版本一致性
buf: plugin not found Buf外掛未安裝 執行buf generate使用遠端外掛
stream recv: context canceled 客戶端取消請求或逾時 增加逾時時間或檢查客戶端邏輯
tls: handshake failure TLS配置不正確 檢查憑證配置或使用h2c開發模式

進階最佳化：5個生產級技巧

技巧1：Proto檔案版本管理。使用Buf的BSR（Buf Schema Registry）管理Proto檔案版本，實作API版本化和向後相容性檢查。

技巧2：Connect協議降級策略。根據客戶端能力自動選擇協議：gRPC（後端間）、gRPC-Web（舊瀏覽器）、Connect（現代瀏覽器），無需手動切換。

技巧3：串流背壓控制。在服務端串流推送中實作背壓機制，根據客戶端消費速率動態調整推送速度，防止緩衝區溢位。

技巧4：請求合併與批次處理。使用Connect的Client Streaming將多個小請求合併為一個串流請求，減少網路往返次數。

技巧5：可觀測性整合。在中介層中整合OpenTelemetry，自動產生Span和Metrics，將Connect呼叫鏈路納入全鏈路追蹤體系。

對比分析

維度 REST + JSON gRPC gRPC-Connect
協議 HTTP/1.1 HTTP/2 HTTP/1.1 + HTTP/2
資料格式 JSON Protobuf Protobuf + JSON
瀏覽器支援 原生 需要gRPC-Web 原生（Connect協議）
串流通訊 WebSocket 原生 原生
程式碼生成 OpenAPI/Swagger protoc Buf
型別安全 弱（JSON） 強（Protobuf） 強（Protobuf）
錯誤處理 HTTP Status Code gRPC Status Connect Status（相容gRPC）
學習曲線 低 中 中
效能 中 高 高
前後端統一 否 否 是

總結

gRPC-Connect協議的5個核心模式解決了微服務前後端通訊的核心痛點：Connect-RPC服務定義實作一套Proto兩端通用，前端gRPC-Web呼叫消除REST中介層，統一錯誤處理與重試機制保證可靠性，串流通訊提供完整的即時通訊能力，生產級Connect閘道確保系統穩定執行。

gRPC-Connect不是REST的替代品，而是前後端統一通訊的最佳實踐。如果你正在構建Go微服務系統，gRPC-Connect + Buf生態是2026年最值得投入的技術棧。記住：一套定義，兩端通用，這就是gRPC-Connect的核心價值。

線上工具推薦

本站提供瀏覽器本地工具，免註冊即可試用 →

#gRPC-Connect#Go微服务#前后端通信#Connect-RPC#Buf#2026#技术架构