gRPC-Gateway与REST互通实践

概述gRPC 在内部服务间高效，而 REST/JSON 更易对外与前端。本文提供 gRPC-Gateway 的转码实践，涵盖字段映射、错误与分页、认证与文档生成。字段与路由（已验证）在 `.proto` 中使用 `google.api.http` 注解映射路径与方法；字段命名与 JSON 映射保持一致性（snake_case ↔ camelCase）；错误与分页错误映射：`grpc-status` 映射为 HTTP 状态与统一错误结构 `{ code, message, traceId }`；分页：标准 `page/page_size` 或 `cursor`，返回 `total/next`；认证与网关网关层校验 JWT 与速率限制；传递用户与租户上下文到 gRPC 后端；文档与校验生成 OpenAPI 文档并校验；保持 `.proto` 与文档的一致性；示例（片段）service UserService { rpc ListUsers (ListUsersRequest) returns (ListUsersResponse) { option (google.api.http) = { get: "/v1/users" }; } } 验证与监控指标：请求成功率、P95/P99、错误映射分布；路由命中与认证失败原因统计；常见误区`.proto` 与 OpenAPI 不一致导致对接问题；错误结构混乱，监控与排障困难；结语以注解驱动的路由与统一错误分页规范，结合认证与文档生成，gRPC-Gateway 可实现内外协议互通与一致的开发体验。