Gateway：HTTP-to-HTTP 路由功能

作者：Kevin Wan
日期：2025-01-28

功能概述

HTTP-to-HTTP 网关功能允许你：

  • 将 HTTP 请求路由到 HTTP 后端服务
  • 为后端服务配置 URL 路径前缀
  • 为每个上游服务设置请求超时
  • 保留所有现有的 gRPC 网关功能

配置说明

以下是在网关配置中设置 HTTP 上游的方式：

  1. Upstreams:
  2.   - Name: userservice  # 可选，如果未指定则使用 target
  3.     Http:
  4.       Target: localhost:8080
  5.       Prefix: /api/v1  # 可选
  6.       Timeout: 3000    # 单位为毫秒，默认值 3000
  7.     Mappings:
  8.       - Method: GET
  9.         Path: /users
  10.       - Method: POST
  11.         Path: /users/create

作为对比，这是 gRPC 上游的配置方式：

  1. Upstreams:
  2.   - Name: orderservice
  3.     Grpc:
  4.       Target: localhost:9000
  5.       Timeout: 3000
  6.     ProtoSets:
  7.       - order.pb
  8.     Mappings:
  9.       - Method: GET
  10.         Path: /orders
  11.         RpcPath: order.OrderService/GetOrders

使用示例

让我们看一个完整的示例，演示如何设置 HTTP-to-HTTP 路由：

  1. package main
  3. import (
  4.     "github.com/zeromicro/go-zero/gateway"
  5.     "github.com/zeromicro/go-zero/rest"
  6. )
  8. func main() {
  9.     var c gateway.GatewayConf
  10.     conf.MustLoad("gateway.yaml", &c)
  12.     gw := gateway.MustNewServer(c)
  13.     defer gw.Stop()
  15.     gw.Start()
  16. }

对应的 gateway.yaml 配置如下：

  1. Name: gateway
  2. Host: 0.0.0.0
  3. Port: 8888
  4. Upstreams:
  5.   - Name: userapi
  6.     Http:
  7.       Target: localhost:8080
  8.       Prefix: /api
  9.     Mappings:
  10.       - Method: GET
  11.         Path: /users
  12.       - Method: POST
  13.         Path: /users
  14.       - Method: GET
  15.         Path: /users/:id

核心特性

  1. 灵活的路由

    • 在同一网关中支持 HTTP 和 gRPC 后端
    • 基于路径的路由，支持前缀配置
    • 基于方法的路由（GET、POST、PUT、DELETE 等）

  2. 配置选项

    • 可配置的每个上游超时时间
    • 可选的 URL 前缀用于路径重写
    • HTTP 和 gRPC 配置的清晰分离

  3. 错误处理

    • 正确传递 HTTP 状态码
    • 配置问题的详细错误信息
    • 后端服务的超时处理

  4. 请求头管理

    • 保留请求/响应头信息
    • 自动处理内容类型

实现细节

该实现保持了关注点分离，并与现有网关功能无缝集成：

  • 配置中 HTTP 上游和 gRPC 上游互斥
  • 请求转发保持原始 HTTP 方法和头信息
  • 保留响应状态码和头信息
  • 超时处理符合 go-zero 的一贯模式

性能考虑

HTTP-to-HTTP 网关的设计充分考虑了性能因素：

  • 高效的请求转发
  • 路由层最小开销
  • 合理的连接管理
  • 内存高效的请求/响应处理

最佳实践

使用 HTTP-to-HTTP 网关功能时的建议：

  1. 始终为上游服务设置适当的超时时间
  2. 为上游服务使用有意义的名称以提高可观察性
  3. 考虑使用 URL 前缀避免路径冲突
  4. 部署前验证配置

结语

HTTP-to-HTTP 支持的加入使得 go-zero 的网关更加通用，适用于更广泛的微服务架构场景。无论你使用 gRPC 服务、HTTP 服务还是两者都有，现在都可以使用单个网关来管理所有路由需求。

更多信息请参考：