gRPC网关与HTTP转码实战：Envoy gRPC-JSON转码与grpc-gateway统一接入

# buf.yaml
version: v2
deps:
  - buf.build/googleapis/googleapis

syntax = "proto3";

package user.v1;

import "google/api/annotations.proto";

option go_package = "github.com/example/user/gen/user/v1;userv1";

service UserService {
  rpc ListUsers(ListUsersRequest) returns (ListUsersResponse) {
    option (google.api.http) = {
      get: "/v1/users"
    };
  }
  rpc GetUser(GetUserRequest) returns (User) {
    option (google.api.http) = {
      get: "/v1/users/{id}"
    };
  }
  rpc CreateUser(CreateUserRequest) returns (User) {
    option (google.api.http) = {
      post: "/v1/users"
      body: "*"
    };
  }
  rpc UpdateUser(UpdateUserRequest) returns (User) {
    option (google.api.http) = {
      patch: "/v1/users/{user.id}"
      body: "user"
    };
  }
  rpc DeleteUser(DeleteUserRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = {
      delete: "/v1/users/{id}"
    };
  }
}

message User {
  int64 id = 1;
  string name = 2;
  string email = 3;
  string created_at = 4;  // 注意：json_name 默认将 created_at 序列化为 created_at
}

message GetUserRequest { int64 id = 1; }
message ListUsersRequest { int32 page_size = 1; string page_token = 2; }
message ListUsersResponse {
  repeated User users = 1;
  string next_page_token = 2;
}
message CreateUserRequest { User user = 1; }
message UpdateUserRequest { User user = 1; }
message DeleteUserRequest { int64 id = 1; }

rpc SearchUsers(SearchUsersRequest) returns (ListUsersResponse) {
  option (google.api.http) = {
    get: "/v1/users:search"
    additional_bindings {
      post: "/v1/users:search"
      body: "*"
    }
  };
}

static_resources:
  listeners:
  - name: ingress_listener
    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
          route_config:
            name: local_route
            virtual_hosts:
            - name: backend
              domains: ["*"]
              routes:
              - match: { prefix: "/" }
                route: { cluster: user_grpc_service }
          http_filters:
          - name: envoy.filters.http.grpc_json_transcoder
            typed_config:
              "@type": type.googleapis.com/envoy.extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder
              proto_descriptor: "/data/user_service.pb"
              services: ["user.v1.UserService"]
              print_options:
                add_whitespace: true
          - name: envoy.filters.http.router
            typed_config:
              "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router

# 方式一：protoc
protoc -I . --include_imports --include_source_info \
  --descriptor_set_out=user_service.pb \
  user/v1/user.proto

# 方式二：buf（推荐，自动处理依赖）
buf build -o user_service.pb

# HTTP/JSON 请求，Envoy 自动转码为 gRPC
curl -s http://localhost:8080/v1/users/123 \
  -H "Authorization: Bearer <token>"

# 返回 JSON
{"id":"123","name":"Alice","email":"alice@example.com"}

# 创建用户
curl -s -X POST http://localhost:8080/v1/users \
  -H "Content-Type: application/json" \
  -d '{"name":"Bob","email":"bob@example.com"}'

go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-grpc-gateway@latest
go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv2@latest
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest

protoc -I . \
  --go_out ./gen --go_opt paths=source_relative \
  --go-grpc_out ./gen --go-grpc_opt paths=source_relative \
  --grpc-gateway_out ./gen --grpc-gateway_opt paths=source_relative \
  --grpc-gateway_opt generate_unbound_methods=true \
  user/v1/user.proto

# buf.gen.yaml
version: v2
inputs:
  - directory: proto
plugins:
  - local: protoc-gen-go
    out: gen
    opt: paths=source_relative
  - local: protoc-gen-go-grpc
    out: gen
    opt: paths=source_relative
  - local: protoc-gen-grpc-gateway
    out: gen
    opt: paths=source_relative
  - local: protoc-gen-openapiv2
    out: gen/openapiv2

package main

import (
	"context"
	"net/http"

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

	userv1 "github.com/example/user/gen/user/v1"
)

func main() {
	ctx := context.Background()

	// gRPC 服务监听地址
	grpcAddr := "localhost:9090"

	// 创建 gateway mux
	mux := runtime.NewServeMux(
		runtime.WithErrorHandler(runtime.DefaultHTTPErrorHandler),
	)

	opts := []grpc.DialOption{grpc.WithTransportCredentials(insecure.NewCredentials())}
	if err := userv1.RegisterUserServiceHandlerFromEndpoint(ctx, mux, grpcAddr, opts); err != nil {
		panic(err)
	}

	// REST 入口
	if err := http.ListenAndServe(":8080", mux); err != nil {
		panic(err)
	}
}

http_filters:
- name: envoy.filters.http.jwt_authn     # 1. 先鉴权
  typed_config:
    "@type": type.googleapis.com/envoy.extensions.filters.http.jwt_authn.v3.JwtAuthentication
    providers:
      issuer:
        issuer: https://issuer.example.com
        audiences: ["api.example.com"]
        remote_jwks:
          http_uri:
            uri: https://issuer.example.com/.well-known/jwks.json
            cluster: jwks_cluster
          cache_duration: 300s
- name: envoy.filters.http.grpc_json_transcoder  # 2. 再转码
  typed_config:
    "@type": type.googleapis.com/envoy.extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder
    proto_descriptor: "/data/user_service.pb"
    services: ["user.v1.UserService"]
- name: envoy.filters.http.router
  typed_config:
    "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router

typed_config:
  ...
  auto_mapping: true
  # 将后端返回的 x-request-id metadata 暴露为 HTTP 头
  response_headers_to_ignore: []

package user.v1;   // v1 版本
package user.v2;   // v2 版本

service UserService {
  rpc GetUser(user.v2.GetUserRequest) returns (user.v2.User);
}

route:
  cluster: user_grpc_service
  timeout: 5s
  retry_policy:
    retry_on: connect-failure,reset,resource-exhausted
    num_retries: 2
    per_try_timeout: 2s