Phorge 现代化改造实战（十一）：升级 Gorge 的 HTTP 框架，接口没变，行为也不能变
内容提要
本文介绍Gorge服务将HTTP框架从Echo v4迁移至Fiber v3，并更换WebSocket库。迁移保持外部契约不变，重点处理响应提交状态、错误码映射、严格路由等兼容细节。通过分层迁移和四层验证，确保测试覆盖率不降，最终成功替换底层框架，验证了平台层对业务逻辑的隔离效果。
延伸解读
框架迁移的隐藏风险：响应提交状态
Echo 的 Response 带有 Committed 状态，用于判断 handler 是否已写出响应。Fiber 没有直接对应物，Gorge 通过 c.Locals 标记 httpx.OK 或 httpx.Fail 写出的响应，防止全局错误处理器覆盖或追加内容。这层薄封装守护了域级错误码，如 ERR_HIGHLIGHT_FAILED，避免被降级为通用 ERR_INTERNAL。测试也相应调整，断言线上结果而非内部状态。
严格路由与错误码映射：契约的细节
Fiber 默认弱化尾斜杠差异，但 Gorge 的 notification 管理端口要求 /status/ 与 /status 不同，因此显式开启 StrictRouting。错误码映射表确保 413 对应 ERR_TOO_LARGE，400 对应 ERR_BAD_REQUEST，且业务层不能将非 400 的 *fiber.Error 改写为 JSON 错误。这些细节不易被类型系统发现，需通过契约测试固定。
测试策略：内存测试与真实监听互补
app.Test 适合大多数路由测试，但无法复现真实网络栈的请求体限制检查。Gorge 通过监听 127.0.0.1:0 并发送真实 TCP 请求来验证前置 413。WebSocket 握手也依赖真实监听。内存测试覆盖 handler 分支，真实监听测试覆盖网络层行为，两者结合确保迁移后行为不变。
迁移验证的四层保障
Gorge 采用四层验证：静态检查（gofmt、go vet、go build）、全量单元测试与覆盖率、契约测试（验证外部形状）、真实监听测试（覆盖网络栈行为）。迁移后测试函数从 416 增至 421，总覆盖率保持 74.9%，httpx 覆盖率提升至 99.1%。这防止了通过删除难测代码来制造假绿。
Q&A
Gorge 服务从 Echo v4 迁移到 Fiber v3 的主要原因是什么？
主要为了统一技术栈，并验证现有契约能否跨框架保持稳定。Gorge 服务没有遇到性能瓶颈，但希望所有 Go 服务使用同一套熟悉的 HTTP 技术栈，减少维护差异。
在迁移过程中，Gorge 如何保证外部契约不变？
通过分层迁移和四层验证。先迁移平台层，再让业务域逐个接回；验证包括静态检查、全量单元测试与覆盖率、契约测试、真实监听测试。同时确保测试数量不降、覆盖率不降，并保留原有故障假设。
Echo 和 Fiber 在处理器签名和测试方式上有什么主要差异？
处理器签名从 func(c echo.Context) error 变为 func(c fiber.Ctx) error。测试入口从使用 httptest.NewRecorder 和 e.ServeHTTP 变为使用 app.Test 方法，断言对象从 httptest.ResponseRecorder 变为 *http.Response。
Gorge 如何处理响应提交状态，以避免错误处理器覆盖已写出的响应？
Fiber 没有 Response().Committed，Gorge 通过 c.Locals 设置标记，所有经过 httpx.OK 或 httpx.Fail 写出的响应都会标记为已提交。全局错误处理器先检查该标记，若已提交则直接返回，不再覆盖或追加响应。
Gorge 如何保持请求体过大和 JSON 格式错误的错误码映射？
通过 parseBodyLimit 将配置中的可读大小（如 2M）转换为字节数，并设置 fiber.Config.BodyLimit。全局错误处理器根据状态码映射错误码，如 413 映射为 ERR_TOO_LARGE，400 映射为 ERR_BAD_REQUEST。业务层在绑定错误时，若遇到非 400 的 *fiber.Error 则原样交还平台错误处理器，避免降级。
为什么 notification 服务的管理端口要开启严格路由？
因为 Phorge 客户端依赖 /status/ 与 /status 是不同路径，前者返回状态，后者应为 404。Fiber 默认会弱化尾斜杠差异，开启 StrictRouting 可以保持原有路径语义，避免将“更宽松”误判为“更兼容”。
notification 服务的客户端口有哪些历史兼容约束？
普通 HTTP GET / 必须返回 501 和 'Use Websockets\n'，不能返回 200；WebSocket 连接升级后，只能出现 WebSocket frame，不能混入 HTTP JSON 信封。
迁移后 WebSocket 库更换带来了哪些影响？
底层连接从 *gorilla/websocket.Conn 变为 *fasthttp/websocket.Conn，核心接口接近，主要改动在升级层。另外，hijack 后不能可靠读取 Fiber 通配参数，需在外层 handler 中通过 c.Path() 解析 instance 并存入 c.Locals。
Gorge 迁移后如何验证测试覆盖率和测试数量不降？
迁移前有 416 个测试函数，总覆盖率 74.9%；迁移后为 421 个测试函数，覆盖率仍为 74.9%。通过全量单元测试和覆盖率统计来确认没有删除难改的测试，并防止旧路径失去执行机会。
迁移后 file-storage 服务的响应格式有何特殊之处？
file-storage 成功时返回 application/octet-stream 字节流，失败时返回 JSON 错误。迁移后使用 SendStream 输出文件，并设置 Content-Length，零字节文件也必须明确返回成功。
