x/gateway Primer

Beta — API 在 minor 版本内保持稳定。采用前请查看发布策略和扩展成熟度。

当你已经通过 x/* 家族确认问题明显属于 edge transport 行为，而不是最小 canonical 服务形态时，就打开这一页：代理上游请求、重写路径、在后端之间做负载均衡，或 wiring gateway 级健康检查。

x/gateway 是 Plumego 中 gateway 与 edge transport 工作的规范且唯一的面向应用的入口点。它的所有下级包首先通过 x/gateway 访问，而不是直接打开：

x/gateway/cache — gateway edge 层 HTTP 响应缓存
x/gateway/discovery — 服务实例解析
x/gateway/ipc — 进程间传输
x/gateway/protocol — 协议适配器注册表（gRPC、GraphQL 转码）
x/gateway/protocolmw — 代理管道中协议感知的 middleware
x/gateway/transform — 请求/响应 header、查询参数与 body 变换链

稳定性与采用

当兼容性很重要时，gateway 和 edge transport 行为应通过应用本地配置隔离。生产中采用 proxy、rewrite、balancer、discovery 或 IPC API 前，请检查 x/gateway/module.yaml、发布策略和扩展成熟度。

什么时候从这里开始

你正在构建或修改反向代理行为（proxy.go）
你正在配置 gateway 路由规则或路径重写（rewrite.go）
你正在添加或调优负载均衡策略（balancer.go）
你正在在 gateway edge 层 wiring 缓存层（cache/）
你正在实现 gateway 级健康检查（health.go）
你正在添加基于服务发现的后端解析或 IPC transport 助手
你正在通过代理管道适配 gRPC 或 GraphQL 上游协议（protocol/、protocolmw/）
你正在 gateway edge 层组合 header、查询参数或 body 变换（transform/）

什么时候不该从这里开始

改动关于可复用 CRUD 资源 API — 那属于 x/rest
工作引入了 tenant 专属的 edge 策略 — 与 x/tenant 协调
改动是 core bootstrap 或稳定根入口点
工作是烘焙进扩展基础元语的业务专属 gateway 策略

当前仓库里先读哪些文件

x/gateway/module.yaml
x/gateway/entrypoints.go
x/gateway/backend.go
x/gateway/balancer.go
x/gateway/rewrite.go（如果涉及路径重写）
x/gateway/cache/（如果涉及缓存）

更具体的归属例子

这些工作适合留在 `x/gateway`	一旦变成这些问题就应移出
`proxy`：反向代理 handler 构造、上游选择、请求转发	可复用资源接口 CRUD transport — 那属于 `x/rest`
`rewrite`：路径重写、header 注入与 modifier 组合	属于应用代码的业务专属 gateway 策略
`balancer`：后端池管理与负载均衡策略选择	tenant 专属路由策略或每租户后端分配
`cache`：gateway edge 响应缓存适配器	非 edge 层的应用级数据缓存 — 使用 `x/data/cache` 代替
`health`：gateway 级后端健康追踪与断路状态	稳定 `health` 模块中细粒度的组件健康类型
`protocol`：协议适配器注册表、proxy edge 的 gRPC 和 GraphQL 转码	业务级协议逻辑 — 保留在应用代码中
`protocolmw`：将协议适配器组合进代理管道的协议感知 middleware	与协议适配无关的通用 HTTP middleware — 使用 `middleware/`
`transform`：header 注入/删除、查询参数编辑、JSON body 改写、method/status 覆盖	gateway edge 之外的应用级响应塑形
通过 `x/gateway` 入口点使用 `discovery` / `ipc`	为属于 gateway 表面的工作直接打开 `x/gateway/discovery` 或 `x/gateway/ipc`

使用方式

导入

import "github.com/spcent/plumego/x/gateway"

静态后端反向代理

proxy := gateway.NewGateway(gateway.GatewayConfig{
    Targets: []string{
        "http://backend-1:8080",
        "http://backend-2:8080",
    },
    LoadBalancer: gateway.NewRoundRobinBalancer(),
})

// 作为独立 handler
r.Handle("/api/*", proxy)

// 或作为 middleware
r.Handle("/api/*", proxy.Middleware()(nextHandler))

一次调用注册代理路由

proxy, err := gateway.RegisterProxy(router, "/api/*", gateway.GatewayConfig{
    Targets:      []string{"http://upstream:9000"},
    LoadBalancer: gateway.NewRoundRobinBalancer(),
})

负载均衡策略

构造函数	策略
`NewRoundRobinBalancer()`	按顺序轮询后端
`NewRandomBalancer()`	随机选择后端
`NewWeightedRoundRobinBalancer()`	按后端权重轮询
`NewIPHashBalancer()`	同一客户端 IP 路由到同一后端
`NewLeastConnectionsBalancer()`	发送到活跃连接数最少的后端

proxy := gateway.NewGateway(gateway.GatewayConfig{
    Targets:      []string{"http://a:8080", "http://b:8080"},
    LoadBalancer: gateway.NewLeastConnectionsBalancer(),
})

路径重写

proxy := gateway.NewGateway(gateway.GatewayConfig{
    Targets:     []string{"http://upstream:9000"},
    PathRewrite: gateway.StripPrefix("/api/v1"),
})

可用的重写助手：

函数	效果
`StripPrefix(prefix)`	转发前去掉路径前缀
`AddPrefix(prefix)`	在转发路径前添加前缀
`ReplacePrefix(old, new)`	将一个前缀替换为另一个
`RewriteMap(rules)`	应用第一条匹配的精确路径规则
`Chain(rewriters...)`	从左到右组合多个重写器

后端池与健康检查

pool, err := gateway.NewBackendPool([]string{
    "http://backend-1:8080",
    "http://backend-2:8080",
})
if err != nil {
    log.Fatal(err)
}

checker := gateway.NewHealthChecker(pool, &gateway.HealthCheckConfig{
    Interval: 10 * time.Second,
    Timeout:  2 * time.Second,
    Path:     "/healthz",
})
checker.Start()
defer checker.Stop()

为什么单独写这一页

Gateway 与 edge transport 是”路由”（属于 router）与”代理”（属于这里）之间混淆最容易导致边界漂移的地方。x/gateway 是所有 6 个下级包的守门人：在直接打开 cache、discovery、ipc、protocol、protocolmw 或 transform 之前，始终先从这里开始。这种间接层使面向应用的表面保持稳定，即使下级包内部在演进。

x/gateway Primer

x/gateway Primer

稳定性与采用

什么时候从这里开始

什么时候不该从这里开始

当前仓库里先读哪些文件

更具体的归属例子

使用方式

导入

静态后端反向代理

一次调用注册代理路由

负载均衡策略

路径重写

后端池与健康检查

为什么单独写这一页

下一步阅读