Протокол gRPC-Connect: Унифицированная frontend-backend коммуникация для Go-микросервисов 2026

Введение: Почему frontend-backend коммуникация ваших микросервисов всё ещё в хаосе

На дворе 2026 год. Если ваши Go-микросервисы всё ещё используют REST + JSON и вручную поддерживают два набора определений API (Protobuf бэкенда + TypeScript фронтенда), вы глубоко увязли в следующем болоте: бэкенд меняет поле, а фронтенд не знает, документация Swagger всегда устарела, потоковая коммуникация требует костылей с WebSocket, коды ошибок определяются отдельно на каждой стороне...

Протокол gRPC-Connect кладёт этому конец. Он определяет один набор сервисов на основе Protobuf, бэкенд использует gRPC для высокопроизводительной коммуникации, а фронтенд без проблем вызывает используя HTTP/JSON режим Connect-RPC. Один Proto — работают обе стороны. Зрелость экосистемы Buf делает это проще, чем когда-либо.

Эта статья проведёт вас через создание 5 ключевых паттернов gRPC-Connect в Go, охватывая всю цепочку от определения сервисов до продакшн-шлюза.

Ключевые концепции с первого взгляда

Концепция	Описание	Инструменты экосистемы
gRPC-Connect	RPC-протокол на основе HTTP/2, поддерживающий протоколы 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
Streaming	Серверный/Клиентский/Двунаправленный стриминг	connect-go
Interceptor	Механизм middleware Connect	connect-go

Пять болевых точек: Почему традиционная frontend-backend коммуникация не поспевает

Болевая точка 1: Кошмар поддержки двойных определений API. Бэкенд определяет сервисы gRPC с Protobuf, фронтенд определяет REST API с интерфейсами TypeScript — два набора определений, которые никогда не синхронизированы.

Болевая точка 2: Документация Swagger бесполезна. Вручную поддерживаемая документация OpenAPI всегда отстаёт от реального кода. Разработчики фронтенда постоянно отлаживают против устаревшей документации.

Болевая точка 3: Фрагментированные решения для стриминга. gRPC Streaming недоступен в браузерах, что вынуждает использовать WebSocket и приводит к фрагментации протокола.

Болевая точка 4: Несогласованная обработка ошибок. gRPC использует Status Codes, REST использует HTTP Status Codes — фронтенду нужны два набора логики обработки ошибок.

Болевая точка 5: Хаотичный инструментарий генерации кода. Конфликты версий плагинов protoc, несогласованные стили сгенерированного кода и сложная интеграция CI/CD.

Паттерн 1: Определение сервисов Connect-RPC

Определите сервисы используя Buf и Connect-RPC — один Proto генерирует как код бэкенда Go, так и код фронтенда TypeScript.

// Runtime: Buf v1.47+, connect-go v1.18+, protoc-gen-go v1.34+
// File: 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;
}

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

# 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

// Runtime: Go 1.22+, connect-go v1.18.0
// File: 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 implements the order service
type OrderServiceHandler struct {
	orders map[string]*orderpb.Order
}

// CreateOrder creates a new order
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 retrieves an order by ID
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("order %s not found", req.Msg.OrderId))
	}

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

// StreamOrders streams orders to the client
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("failed to stream order: %w", err)
			}
			time.Sleep(100 * time.Millisecond)
		}
	}
	return nil
}

// UploadOrders handles client streaming upload
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 handles bidirectional streaming chat
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("Received from %s: %s", msg.Sender, msg.Message),
			Timestamp: time.Now().Unix(),
		}

		if err := stream.Send(reply); err != nil {
			return fmt.Errorf("failed to send reply: %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 server starting on :8080")
	log.Println("Supported protocols: gRPC, gRPC-Web, Connect")
	log.Fatal(http.ListenAndServe(":8080", mux))
}

Паттерн 2: Вызовы frontend gRPC-Web

Используйте Connect-Web для вызова сервисов gRPC напрямую из фронтенда, устраняя слой REST-middleware.

// Runtime: TypeScript 5.5+, @connectrpc/connect-web v2.0.0
// File: frontend/src/client.ts

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

// Create Connect transport (HTTP/1.1 compatible)
const connectTransport = createConnectTransport({
  baseUrl: "https://api.example.com",
});

// Create gRPC-Web transport
const grpcWebTransport = createConnectTransport({
  baseUrl: "https://api.example.com",
  httpVersion: "2",
});

// Create order service client
const orderClient = createClient(OrderService, connectTransport);

// === Unary call ===
async function createOrder() {
  try {
    const response = await orderClient.createOrder({
      userId: "user-123",
      items: [
        { productId: "prod-1", productName: "Go Programming", quantity: 1, price: 89.0 },
        { productId: "prod-2", productName: "Rust in Action", quantity: 2, price: 99.0 },
      ],
      shippingAddress: "123 Main St, San Francisco",
    });

    console.log("Order created:", response.orderId, response.status);
  } catch (err) {
    console.error("Failed to create order:", err.code, err.message);
  }
}

// === Get order ===
async function getOrder(orderId: string) {
  try {
    const response = await orderClient.getOrder({ orderId });
    console.log("Order details:", response.order);
  } catch (err: any) {
    if (err.code === "NOT_FOUND") {
      console.warn("Order not found");
    } else {
      console.error("Failed to get order:", err.message);
    }
  }
}

// === Server Streaming ===
async function streamOrders(userId: string) {
  try {
    for await (const order of orderClient.streamOrders({ userId })) {
      console.log("Real-time order update:", order.orderId, order.status);
      updateOrderInUI(order);
    }
  } catch (err) {
    console.error("Order stream interrupted:", err.message);
  }
}

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

  try {
    const response = await orderClient.uploadOrders(orders);
    console.log(`Successfully uploaded ${response.totalCreated} orders`);
  } catch (err) {
    console.error("Failed to upload orders:", err.message);
  }
}

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

function updateOrderInUI(order: any) {}

Паттерн 3: Обработка ошибок и повторные попытки

Connect-RPC предоставляет унифицированный механизм обработки ошибок — и фронтенд, и бэкенд используют одни и те же коды ошибок и формат сообщений.

// Runtime: Go 1.22+, connect-go v1.18.0
// File: server/errors.go
package main

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

	"connectrpc.com/connect"
)

// OrderError represents a business error
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 converts to a Connect error
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:   "Order not found",
		Retryable: false,
	}
	ErrOrderAlreadyCancelled = &OrderError{
		Code:      connect.CodeFailedPrecondition,
		Message:   "Order already cancelled",
		Retryable: false,
	}
	ErrInsufficientStock = &OrderError{
		Code:      connect.CodeResourceExhausted,
		Message:   "Insufficient stock",
		Retryable: true,
	}
	ErrPaymentTimeout = &OrderError{
		Code:      connect.CodeDeadlineExceeded,
		Message:   "Payment timeout",
		Retryable: true,
	}
)

// RetryInterceptor implements client-side retry logic
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("Retry %d/%d, delay %v, error: %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 recovers from panics in handlers
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] Handler panic: %v", r)
					err = connect.NewError(connect.CodeInternal,
						fmt.Errorf("internal server error, please retry later"))
				}
			}()
			return next(ctx, req)
		}
	}
}

// ErrorLoggingInterceptor logs errors
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("Error handling service starting on :8080")
	log.Fatal(http.ListenAndServe(":8080", mux))
}

Паттерн 4: Потоковая коммуникация

Connect-RPC полностью поддерживает три режима потоковой коммуникации с унифицированными определениями Protobuf для фронтенда и бэкенда.

// Runtime: Go 1.22+, connect-go v1.18.0
// File: server/streaming.go
package main

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

	"connectrpc.com/connect"
)

// OrderStatusStream manages order status subscriptions
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("Subscriber channel full, dropping update: %s", update.OrderID)
		}
	}
}

// BatchOrderImporter handles batch order imports
type BatchOrderImporter struct {
	processedCount int
	failedCount    int
	mu             sync.Mutex
}

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 (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 manages real-time collaboration
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"`
}

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("Client %s channel full", 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("failed to send collab message: %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("Streaming service starting on :8080")
	log.Fatal(http.ListenAndServe(":8080", nil))
}

Паттерн 5: Продакшн-шлюз Connect

Постройте продакшн-шлюз Connect-RPC с аутентификацией, ограничением частоты запросов, мониторингом и корректным завершением работы.

// Runtime: Go 1.22+, connect-go v1.18.0
// File: 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("missing authentication token"))
			}

			token = strings.TrimPrefix(token, "Bearer ")
			claims, err := validateJWT(token, jwtSecret)
			if err != nil {
				return nil, connect.NewError(connect.CodeUnauthenticated,
					fmt.Errorf("invalid authentication token: %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("rate limit exceeded, please retry later"))
			}
			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 gateway starting on %s", gw.server.Addr)
		log.Println("Supported protocols: 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("gateway failed to start: %w", err)
	case sig := <-gw.shutdownCh:
		log.Printf("Received signal %v, starting graceful shutdown...", sig)
		return gw.Shutdown()
	}
}

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

	log.Println("Stopping new request acceptance...")
	if err := gw.server.Shutdown(ctx); err != nil {
		return fmt.Errorf("gateway shutdown failed: %w", err)
	}

	log.Println("Gateway gracefully shut down")
	return nil
}

func main() {
	gateway := NewConnectGateway(":8080")
	if err := gateway.Start(); err != nil {
		log.Fatalf("Gateway failed: %v", err)
	}
}

Руководство по подводным камням: 5 продакшн-ловушек

Ловушка 1: Конфликты версий генерации кода Buf. Разные версии плагинов генерируют несовместимый код, вызывая ошибки компиляции. Решение: Зафиксировать версии плагинов в buf.gen.yaml, использовать buf generate в CI вместо локального protoc.

Ловушка 2: Сбой согласования HTTP/2. Некоторые обратные прокси (старые версии Nginx) не поддерживают HTTP/2, вызывая ошибки вызовов gRPC. Решение: Использовать протокол Connect (совместимый с HTTP/1.1) как резервный вариант или обновить прокси для поддержки h2c.

Ловушка 3: Незаметное отключение стримов. Сетевые колебания вызывают разрыв потоковых соединений без ведома сервера. Решение: Реализовать механизмы heartbeat (ping каждые 30 секунд), установить таймауты чтения/записи и автореконнект клиента.

Ловушка 4: Большие тела сообщений вызывают OOM. Стриминг загрузки больших файлов заполняет буфер приёмника, вызывая OOM. Решение: Установить максимальный размер тела сообщения (по умолчанию Connect — 4 МБ), обрабатывать потоковыми чанками, реализовать обратное давление.

Ловушка 5: Отсутствующая конфигурация CORS. Вызовы Connect со стороны браузера блокируются политикой CORS. Решение: Настроить CORS-middleware на уровне шлюза, разрешив 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-middleware на уровне шлюза
`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. Использовать BSR (Buf Schema Registry) Buf для управления версиями файлов Proto, включая версионирование API и проверки обратной совместимости.

Совет 2: Стратегия резервного протокола Connect. Автоматический выбор протокола на основе возможностей клиента: gRPC (backend-to-backend), gRPC-Web (старые браузеры), Connect (современные браузеры) — без необходимости ручного переключения.

Совет 3: Контроль обратного давления в стримах. Реализовать обратное давление в серверном стриминге путём динамической регулировки скорости push на основе скорости потребления клиента, предотвращая переполнение буфера.

Совет 4: Пакетирование запросов. Использовать Client Streaming Connect для объединения нескольких мелких запросов в один потоковый запрос, сокращая сетевые обходы.

Совет 5: Интеграция наблюдаемости. Интегрировать OpenTelemetry в интерцепторы для автоматической генерации Spans и 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)
Кривая обучения	Низкая	Средняя	Средняя
Производительность	Средняя	Высокая	Высокая
Унификация frontend-backend	Нет	Нет	Да

Заключение

5 ключевых паттернов протокола gRPC-Connect решают основные болевые точки frontend-backend коммуникации микросервисов: определение сервисов Connect-RPC позволяет использовать один Proto для обеих сторон, вызовы frontend gRPC-Web устраняют слой REST-middleware, унифицированная обработка ошибок и механизмы повторных попыток обеспечивают надёжность, потоковая коммуникация предоставляет полные возможности коммуникации в реальном времени, а продакшн-шлюз Connect обеспечивает стабильность системы.

gRPC-Connect — это не замена REST — это лучшая практика унифицированной frontend-backend коммуникации. Если вы строите систему Go-микросервисов, экосистема gRPC-Connect + Buf — это технологический стек, в который стоит инвестировать в 2026 году. Помните: одно определение — работают обе стороны, и в этом суть gRPC-Connect.