Phorge 现代化改造实战（十四）：为 Go 服务建立统一的 Phorge API 入口，网关可以换框架，Conduit 协议不能变
内容提要
本文介绍Phorge现代化改造中新增的Conduit网关，使Go服务能经统一入口调用Phorge API。网关处理认证、限流，保持Conduit协议格式，并迁移至Fiber v3。文章强调协议兼容、中间件顺序、测试验证及版本对齐等关键点，确保服务稳定集成。
延伸解读
协议一致性是网关设计的核心约束
网关在代理成功时逐字节透传 Conduit 响应，避免包裹 Gorge 的 {data,error} 信封，因为现有 Conduit 客户端依赖顶层的 result、error_code 和 error_info。同时，网关自身产生的错误（如鉴权失败、限流）也必须使用 Conduit 信封，否则同一 /api/:method 会因失败位置不同返回两种错误协议，迫使客户端先猜测 JSON 归属。
中间件顺序与路由细节影响行为
鉴权先于限流执行，避免未认证请求消耗合法客户端的限流配额。由于 Fiber 的 group 级 Use 在子路由绑定参数前执行，限流必须作为具体路由的 handler 才能读取 :method。此外，/api 和 /api/ 路径需显式交给代理，否则会落入默认 404 并返回 Gorge 信封，破坏协议一致性。
迁移到 Fiber v3 的取舍与风险
为统一 monorepo 运行纪律，网关从 Echo v4 重写为 Fiber v3，避免长期维护两个 Web 框架。但内部仍使用 net/http.Client 请求上游，以利用成熟的超时和上下文控制。需注意 fasthttp 的流式 body 生命周期陷阱，因此缓冲响应体以避免截断。
版本对齐与调用方切流验证
Phorge 的 r3 与 Gorge r3 版本名对齐，但 Phorge 无新增代码，确保源码、构建和镜像版本一致。调用方（如 gorge-worker）需配置 CONDUIT_URL 指向网关，且 CONDUIT_URL 为空时委托 handler 不注册。验证需确认调用方已切流，而不仅是“可以使用”。
Q&A
Phorge 现代化改造中，为什么需要为 Go 服务建立统一的 Conduit API 入口？
因为如果每个 Go 服务都直接连接 Phorge，每个调用方都要各自处理认证、限流、超时和将来的审计。通过网关（gorge-conduit）可以统一处理这些横切能力，并集中实施访问策略。
gorge-conduit 网关的主要功能是什么？
网关接收其它 Go 服务发来的 ANY /api/:method 请求，完成服务令牌认证和按 IP 限流，然后把请求转发给 Phorge 自己的 Conduit API，并原样返回响应。
在将独立仓库 soulteary/gorge-conduit 迁入 monorepo 时，为什么选择重写为 Fiber v3 而不是保留 Echo？
为了保持 monorepo 的统一运行纪律：一个 go.mod、一套优雅关闭、同一种健康探针、同一次 go test ./...，并由分层测试禁止平台层反向依赖业务域。保留第二个 Web 框架会增加依赖升级和排障成本。
Conduit 网关如何处理成功和失败的响应格式？
成功响应必须逐字节透传，保持 Conduit 原有的 {result, error_code, error_info} 格式，不能包装成 Gorge 的 {data, error} 信封。网关自身产生的失败也必须使用 Conduit 信封，并定义了 ERR-CONDUIT-CORE、ERR-CONDUIT-AUTH、ERR-RATE-LIMIT、ERR-CONDUIT-PROXY 四个错误码。
为什么限流器不能挂在 /api group 上，而必须作为具体路由的 handler？
因为 Fiber 的 group 级 Use 会在子路由绑定参数之前执行，此时 c.Params("method") 还是空字符串，无法读取 :method 来豁免 conduit.ping 和 conduit.getcapabilities。因此鉴权可以挂在 group 上，但限流必须放在具体路由的 handler 中。
在网关中，为什么 /api 和 /api/ 路径需要显式处理？
如果只注册 /:method，/api 和 /api/ 会落进平台的默认 404，返回 Gorge 的 {data,error} 信封。这两个无方法名路径必须显式交给代理 handler，让 method == "" 产生 ERR-CONDUIT-CORE，保持协议一致性。
gorge-worker 如何配置以使用 Conduit 网关？
gorge-worker 读取 CONDUIT_URL 环境变量，当它指向 http://gorge-conduit:8150 时，请求会经过网关；当 CONDUIT_URL 为空时，委托型 handler 不会注册；指向 Phorge 时表示直连。同时需要设置 CONDUIT_TOKEN 作为服务令牌。
网关的限流器有哪些默认豁免和默认值？
conduit.ping 和 conduit.getcapabilities 默认豁免限流，因为 Phorge 和 Arcanist 会频繁调用它们进行探测。服务自身的限流默认值是 RPS=0（默认关闭），但在 Phorge r2 的叠加编排中主动设置为 RPS=20、burst=40。
