gRPC-Gateway

gRPC-Gateway 根据 .proto 的 google.api.http 注解，自动生成 REST 反向代理 到 gRPC 后端。实现「内网 gRPC、边缘 REST」——但 不意味着 替换 CodeRoadMap 已有 /tracks 实现。

学习目标

• 理解 option (google.api.http) 映射规则
• 知道 Gateway 在架构中的位置（BFF / 边缘）
• 评估：本站是否需要在 lab 外引入 Gateway

核心内容

.proto HTTP 注解

import "google/api/annotations.proto";

service TrackService {
  rpc GetTrack(GetTrackRequest) returns (GetTrackResponse) {
    option (google.api.http) = {
      get: "/v1/tracks/{slug}"
    };
  }
  rpc ListTracks(ListTracksRequest) returns (ListTracksResponse) {
    option (google.api.http) = {
      get: "/v1/tracks"
    };
  }
}

Gateway 监听 HTTP，转调 localhost:9090 gRPC。路径 /v1/tracks 与现有 /tracks 并存实验，避免破坏 Next.js 硬编码 URL。

架构示意

Browser / Next.js
    │ GET /tracks          → 现有 Spring @RestController（生产）
    │ GET /v1/tracks (lab) → gRPC-Gateway → gRPC TrackService

与 graphql-essentials「REST + GraphQL 并存」类似：双协议维护成本 需团队预算。生产权威仍 MySQL + REST Controller。

生成与运行（概念）

# protoc-gen-grpc-gateway 生成 reverse proxy stub
protoc -I . --grpc-gateway_out=. track.proto

Java 生态也可用独立 Gateway 进程或 Envoy gRPC-JSON transcoding（spring-cloud-essentials 网关层）。

何时值得用

• 移动端/浏览器必须 HTTP JSON，核心微服务仅 gRPC
• 统一 .proto 契约同时服务内外部

CodeRoadMap：已有成熟 REST /tracks + OpenAPI，无需为课程 API 上 Gateway；lab 用于理解行业模式即可。

练习

• 为 GetTrack 写 google.api.http 注解
• 画架构图：Gateway vs 直接 REST Controller
• 列出维护双路径（/tracks 与 /v1/tracks）的 3 项成本

小结

Gateway = REST façade → gRPC 后端；本站生产仍直连 REST /tracks。 下一课 gRPC vs REST 选型。