gRPC-Web 与 GraphQL 混合架构：微服务通信分层实战

// api/order/v1/order.proto
syntax = "proto3";
package api.order.v1;

import "google/protobuf/timestamp.proto";

message Order {
  string id = 1;
  string user_id = 2;
  repeated OrderItem items = 3;
  OrderStatus status = 4;
  google.protobuf.Timestamp created_at = 5;
  Address shipping_address = 6;

  oneof payment {
    CardPayment card = 7;
    WalletPayment wallet = 8;
  }
}

message OrderItem {
  string sku = 1;
  int32 quantity = 2;
  double unit_price = 3;
}

enum OrderStatus {
  ORDER_STATUS_UNSPECIFIED = 0;
  ORDER_STATUS_PENDING = 1;
  ORDER_STATUS_PAID = 2;
  ORDER_STATUS_SHIPPED = 3;
  ORDER_STATUS_DELIVERED = 4;
}

message Address {
  string country = 1;
  string province = 2;
  string city = 3;
  string street = 4;
  string zip = 5;
}

message CardPayment {
  string card_last_four = 1;
  string network = 2; // visa, master, amex
}

message WalletPayment {
  string wallet_type = 1; // alipay, wechat
  string transaction_id = 2;
}

scalar Timestamp
scalar Long

enum OrderStatus {
  UNSPECIFIED
  PENDING
  PAID
  SHIPPED
  DELIVERED
}

type Order {
  id: ID!
  userId: String!
  items: [OrderItem!]!
  status: OrderStatus!
  createdAt: Timestamp!
  shippingAddress: Address!
  card: CardPayment
  wallet: WalletPayment
}

type OrderItem {
  sku: String!
  quantity: Int!
  unitPrice: Float!
}

type Address {
  country: String!
  province: String!
  city: String!
  street: String!
  zip: String!
}

type CardPayment {
  cardLastFour: String!
  network: String!
}

type WalletPayment {
  walletType: String!
  transactionId: String!
}

// 统一以 RFC 3339 字符串形式传输，网关层负责 Timestamp ↔ String 转换

type StringValuePair {
  key: String!
  value: String!
}

type Product {
  # map<string, string> attributes = 1;
  attributes: [StringValuePair!]!
}

# envoy.yaml
static_resources:
  listeners:
    - name: listener_0
      address:
        socket_address: { address: 0.0.0.0, port_value: 8080 }
      filter_chains:
        - filters:
            - name: envoy.filters.network.http_connection_manager
              typed_config:
                "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
                stat_prefix: ingress_http
                codec_type: AUTO
                route_config:
                  name: local_route
                  virtual_hosts:
                    - name: backend
                      domains: ["*"]
                      routes:
                        - match:
                            prefix: "/api.order.v1.OrderService/"
                          route:
                            cluster: order_service
                            timeout: 10s
                        - match:
                            prefix: "/api.payment.v1.PaymentService/"
                          route:
                            cluster: payment_service
                            timeout: 10s
                        - match:
                            prefix: "/api.inventory.v1.InventoryService/"
                          route:
                            cluster: inventory_service
                            timeout: 10s
                http_filters:
                  - name: envoy.filters.http.grpc_web
                    typed_config:
                      "@type": type.googleapis.com/envoy.extensions.filters.http.grpc_web.v3.GrpcWeb
                  - name: envoy.filters.http.cors
                    typed_config:
                      "@type": type.googleapis.com/envoy.extensions.filters.http.cors.v3.CorsPolicy
                  - name: envoy.filters.http.router
                    typed_config:
                      "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router

  clusters:
    - name: order_service
      connect_timeout: 5s
      type: STRICT_DNS
      lb_policy: ROUND_ROBIN
      typed_extension_protocol_options:
        envoy.extensions.upstreams.http.v3.HttpProtocolOptions:
          "@type": type.googleapis.com/envoy.extensions.upstreams.http.v3.HttpProtocolOptions
          upstream_protocol_options:
            explicit_http_config:
              http2_protocol_options: {}
      load_assignment:
        cluster_name: order_service
        endpoints:
          - lb_endpoints:
              - endpoint:
                  address:
                    socket_address:
                      address: order-service
                      port_value: 50051

    - name: payment_service
      connect_timeout: 5s
      type: STRICT_DNS
      lb_policy: ROUND_ROBIN
      typed_extension_protocol_options:
        envoy.extensions.upstreams.http.v3.HttpProtocolOptions:
          "@type": type.googleapis.com/envoy.extensions.upstreams.http.v3.HttpProtocolOptions
          upstream_protocol_options:
            explicit_http_config:
              http2_protocol_options: {}
      load_assignment:
        cluster_name: payment_service
        endpoints:
          - lb_endpoints:
              - endpoint:
                  address:
                    socket_address:
                      address: payment-service
                      port_value: 50051

    - name: inventory_service
      connect_timeout: 5s
      type: STRICT_DNS
      lb_policy: ROUND_ROBIN
      typed_extension_protocol_options:
        envoy.extensions.upstreams.http.v3.HttpProtocolOptions:
          "@type": type.googleapis.com/envoy.extensions.upstreams.http.v3.HttpProtocolOptions
          upstream_protocol_options:
            explicit_http_config:
              http2_protocol_options: {}
      load_assignment:
        cluster_name: inventory_service
        endpoints:
          - lb_endpoints:
              - endpoint:
                  address:
                    socket_address:
                      address: inventory-service
                      port_value: 50051

cors:
  allow_origins:
    - match:
        exact: "https://app.example.com"
  allow_methods: ["GET", "POST", "OPTIONS"]
  allow_headers: ["content-type", "x-grpc-web", "x-user-agent"]
  expose_headers: ["grpc-status", "grpc-message"]
  max_age: "86400s"

protoc \
  --proto_path=api/order/v1 \
  --js_out=import_style=commonjs:./src/generated \
  --grpc-web_out=import_style=typescript,mode=grpcwebtext:./src/generated \
  api/order/v1/order.proto

import { OrderServiceClient } from "./generated/order_grpc_web_pb";
import { GetOrderRequest, Order } from "./generated/order_pb";

const client = new OrderServiceClient("https://api.example.com", null, null);

const request = new GetOrderRequest();
request.setOrderId("ORD-2026-88123");

client.getOrder(request, { "Authorization": "Bearer " + token }, (err, response: Order) => {
  if (err) {
    console.error("gRPC-Web error:", err.code, err.message);
    return;
  }
  console.log("Order ID:", response.getId());
  console.log("Status:", response.getStatus());
});

// 支持的服务端流示例：实时推送订单状态变更
rpc StreamOrderStatusUpdates(StreamOrderStatusRequest)
    returns (stream OrderStatusUpdate);

// api/order/v1/order.proto
syntax = "proto3";
package api.order.v1;

import "google/api/annotations.proto";
import "google/protobuf/timestamp.proto";
import "protoc-gen-openapiv2/options/annotations.proto";

option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
  info: {
    title: "Order Service API";
    version: "1.0.0";
    description: "订单服务 gRPC & REST 双协议接口";
  };
  host: "api.example.com";
  schemes: HTTPS;
  consumes: "application/json";
  produces: "application/json";
};

service OrderService {
  rpc GetOrder(GetOrderRequest) returns (Order) {
    option (google.api.http) = {
      get: "/v1/orders/{order_id}"
    };
  }

  rpc ListOrders(ListOrdersRequest) returns (ListOrdersResponse) {
    option (google.api.http) = {
      get: "/v1/orders"
    };
  }

  rpc CreateOrder(CreateOrderRequest) returns (Order) {
    option (google.api.http) = {
      post: "/v1/orders"
      body: "*"
    };
  }

  rpc UpdateOrderStatus(UpdateOrderStatusRequest) returns (Order) {
    option (google.api.http) = {
      patch: "/v1/orders/{order_id}/status"
      body: "*"
    };
  }
}

message GetOrderRequest {
  string order_id = 1;
}

message ListOrdersRequest {
  int32 page = 1;
  int32 page_size = 2;
  OrderStatus status = 3;
}

message ListOrdersResponse {
  repeated Order orders = 1;
  int32 total = 2;
  bool has_more = 3;
}

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

message UpdateOrderStatusRequest {
  string order_id = 1;
  OrderStatus status = 2;
  string reason = 3;
}

protoc \
  -I . -I third_party/googleapis \
  --go_out=. --go_opt=paths=source_relative \
  --go-grpc_out=. --go-grpc_opt=paths=source_relative \
  --grpc-gateway_out=. --grpc-gateway_opt=paths=source_relative \
  --openapiv2_out=. --openapiv2_opt=allow_merge=true,merge_file_name=order \
  api/order/v1/order.proto

package main

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

	"github.com/grpc-ecosystem/grpc-gateway/v2/runtime"
	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials/insecure"

	orderv1 "example.com/api/order/v1"
)

type orderServer struct {
	orderv1.UnimplementedOrderServiceServer
}

func (s *orderServer) GetOrder(ctx context.Context, req *orderv1.GetOrderRequest) (*orderv1.Order, error) {
	// TODO: 实际查询逻辑
	return &orderv1.Order{
		Id:     req.OrderId,
		UserId: "user-001",
		Status: orderv1.OrderStatus_ORDER_STATUS_PAID,
	}, nil
}

func main() {
	grpcAddr := ":50051"
	gwAddr := ":8080"

	// gRPC Server
	lis, err := net.Listen("tcp", grpcAddr)
	if err != nil {
		log.Fatal(err)
	}
	grpcServer := grpc.NewServer()
	orderv1.RegisterOrderServiceServer(grpcServer, &orderServer{})

	go func() {
		log.Printf("gRPC server listening on %s", grpcAddr)
		if err := grpcServer.Serve(lis); err != nil {
			log.Fatal(err)
		}
	}()

	// gRPC-Gateway HTTP Server
	ctx := context.Background()
	mux := runtime.NewServeMux()
	opts := []grpc.DialOption{grpc.WithTransportCredentials(insecure.NewCredentials())}

	if err := orderv1.RegisterOrderServiceHandlerFromEndpoint(ctx, mux, grpcAddr, opts); err != nil {
		log.Fatal(err)
	}

	log.Printf("HTTP gateway listening on %s", gwAddr)
	if err := http.ListenAndServe(gwAddr, mux); err != nil {
		log.Fatal(err)
	}
}

package graph

import (
	"context"
	"fmt"

	orderv1 "example.com/api/order/v1"
	"example.com/graph/model"
)

type Resolver struct {
	OrderClient orderv1.OrderServiceClient
}

func (r *queryResolver) Order(ctx context.Context, id string) (*model.Order, error) {
	resp, err := r.OrderClient.GetOrder(ctx, &orderv1.GetOrderRequest{OrderId: id})
	if err != nil {
		return nil, fmt.Errorf("get order: %w", err)
	}

	items := make([]*model.OrderItem, 0, len(resp.Items))
	for _, it := range resp.Items {
		items = append(items, &model.OrderItem{
			Sku:       it.Sku,
			Quantity:  int(it.Quantity),
			UnitPrice: it.UnitPrice,
		})
	}

	return &model.Order{
		ID:        resp.Id,
		UserID:    resp.UserId,
		Status:    model.OrderStatus(resp.Status.String()),
		Items:     items,
		CreatedAt: resp.CreatedAt.AsTime().Unix(),
	}, nil
}

package dataloader

import (
	"context"
	"time"

	"github.com/graph-gophers/dataloader/v7"
)

type OrderLoader struct {
	Client orderv1.OrderServiceClient
}

func (l *OrderLoader) BatchGetOrders(ctx context.Context, keys []string) ([][]*model.Order, []error) {
	// 将多个单条查询合并为一次批量 gRPC 调用
	resp, err := l.Client.BatchGetOrders(ctx, &orderv1.BatchGetOrdersRequest{OrderIds: keys})
	if err != nil {
		return nil, []error{err}
	}
	// ... 按 key 顺序重组结果
}

# 列出服务与方法
grpcurl -plaintext localhost:50051 list api.order.v1.OrderService

# 调用具体方法
grpcurl -plaintext -d '{"order_id": "ORD-2026-88123"}' \
  localhost:50051 api.order.v1.OrderService/GetOrder

# 使用 proto 文件反射（服务端需开启反射服务）
grpcurl -plaintext -proto api/order/v1/order.proto \
  -d '{"page": 1, "page_size": 10}' \
  localhost:50051 api.order.v1.OrderService/ListOrders

// 服务侧 Go 代码：gRPC Interceptor 注入追踪
import (
	"go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc"
	"google.golang.org/grpc"
)

grpcServer := grpc.NewServer(
	grpc.UnaryInterceptor(otelgrpc.UnaryServerInterceptor()),
	grpc.StreamInterceptor(otelgrpc.StreamServerInterceptor()),
)

tracing:
  http:
    name: envoy.tracers.zipkin
    typed_config:
      "@type": type.googleapis.com/envoy.config.trace.v3.ZipkinConfig
      collector_cluster: jaeger
      collector_endpoint: "/api/v2/spans"
      shared_span_context: false
      collector_endpoint_version: HTTP_JSON