调研 Go 重构的初步不可更改约束

[muverystrong]

背景

当前项目为 Java/Spring Boot 实现的 AI API 网关（bella-openapi），承载 150M+ 日调用量。在推进 Go 重构之前，需要先以文档形式明确"哪些外部协议、可观察行为、治理/计费/观测口径，以及执行链路中的内在约定，在 Go 版本中都不能改变"，为后续方案设计和验收提供清晰的硬边界。

诉求

完成一份"现状契约与不变量盘点"文档（已有初稿 docs/design/refactor2go-task1-contract-inventory.md），覆盖以下盘点范围：

Runtime 能力点

• /v1/chat/completions、/v1/messages、/v1/responses
• /v1/audio/*（TTS、Realtime ASR、Flash ASR、OpenAI Transcriptions、Async Transcription、Speaker）
• /v1/embeddings、/v1/images/*、/v1/ocr/*、/v1/videos
• /v1/web/*、/v1/document/*
• /v1/models、/v1/meta/*、/v1/route、/v1/log、/v1/metrics

管理类能力

• /v1/apikey/*、/v1/space/*、/v1/userInfo/*、/console/*

横向公共语义

• 鉴权与入口约束
• 请求上下文与特殊 Header（X-BELLA-* 系列）
• 错误归一（@EndpointAPI vs @BellaAPI 两套出口）
• 路由 / Direct / Mock / Private 模式
• 治理 / 限流 / 配额
• 观测 / 日志 / 收口
• 用量 / 计费
• Queue / Worker 执行语义

P0 回归验证基线（见文档第 6 章）：C-001 ~ C-010 共 10 个核心验证场景，覆盖鉴权、请求上下文、Chat/Messages/Responses 流式非流式、Realtime WebSocket、路由模式、Queue/Worker、用量计费观测。

预期影响

• 输出一份"不变量清单"，作为 Go 重构方案设计的硬边界与验收依据
• 明确哪些内容属于需要兼容的外部协议，哪些属于可自由重构的内部实现，避免范围蔓延或遗漏
• 为双栈对比测试（Java vs Go）提供协议级断言基准，而不是只检查调用是否成功
• 为团队对齐重构范围、分阶段交付和 P0 验收提供统一参考

证据

初稿文档已存在：docs/design/refactor2go-task1-contract-inventory.md

该文档目前已覆盖：

• 3.1～3.18 各能力点的"对外协议"与"不能改变的行为"两级盘点结构
• 第 4 章横向公共语义总结（鉴权、Header、错误、路由、治理、观测、计费、Queue）
• 第 6 章 P0 回归验证基线（C-001～C-010）及验证方式（历史回放、双栈对比、协议级断言、横向专项抽查）

相关链接

• 初稿文档：docs/design/refactor2go-task1-contract-inventory.md

[wjn161]

目前我们也在考虑使用go还是java（jdk25)来构建AI Gateway，调研了 newapi 和 litellm，确实go和python的生态更有优势， 目前团队熟悉java技术栈，想了解作者重构的原因和背景是什么，jdk版本升级之后(virtual thread)带来的性能收益不足以解决现有问题吗？

[nil4u]

目前我们也在考虑使用go还是java（jdk25)来构建AI Gateway，调研了 newapi 和 litellm，确实go和python的生态更有优势， 目前团队熟悉java技术栈，想了解作者重构的原因和背景是什么，jdk版本升级之后(virtual thread)带来的性能收益不足以解决现有问题吗？

@wjn161 不是为了吞吐/延迟这类性能考虑，模型网关这种io密集的项目java并没有太大劣势。
核心的考量点有3个：第一是资源占用，我们初步估算换golang我们的实例数能降一半以上。第二是部署上要容易很多，ci/cd会更方便。第三是现在的模型能力强了，试点一下用ai能不能较快完成较为复杂的项目重写。

[wjn161]

目前我们也在考虑使用go还是java（jdk25)来构建AI Gateway，调研了 newapi 和 litellm，确实go和python的生态更有优势， 目前团队熟悉java技术栈，想了解作者重构的原因和背景是什么，jdk版本升级之后(virtual thread)带来的性能收益不足以解决现有问题吗？

@wjn161 不是为了吞吐/延迟这类性能考虑，模型网关这种io密集的项目java并没有太大劣势。 核心的考量点有3个：第一是资源占用，我们初步估算换golang我们的实例数能降一半以上。第二是部署上要容易很多，ci/cd会更方便。第三是现在的模型能力强了，试点一下用ai能不能较快完成较为复杂的项目重写。

@nil4u 感谢回答，我们最终还是选了用jdk 25做第一个版本，考虑的也是2个原因：第一是人员知识储备，虽然大部分代码是AI写的，但是还是需要人工兜住风险。第二就是通过真实项目沉淀出一些java技术栈AI Coding和AI Ops的最佳实践，后期需要输出到其他业务线（其他业务线很难换到go的生态)。

[nil4u]

目前我们也在考虑使用go还是java（jdk25)来构建AI Gateway，调研了 newapi 和 litellm，确实go和python的生态更有优势， 目前团队熟悉java技术栈，想了解作者重构的原因和背景是什么，jdk版本升级之后(virtual thread)带来的性能收益不足以解决现有问题吗？

@wjn161 不是为了吞吐/延迟这类性能考虑，模型网关这种io密集的项目java并没有太大劣势。 核心的考量点有3个：第一是资源占用，我们初步估算换golang我们的实例数能降一半以上。第二是部署上要容易很多，ci/cd会更方便。第三是现在的模型能力强了，试点一下用ai能不能较快完成较为复杂的项目重写。

@nil4u 感谢回答，我们最终还是选了用jdk 25做第一个版本，考虑的也是2个原因：第一是人员知识储备，虽然大部分代码是AI写的，但是还是需要人工兜住风险。第二就是通过真实项目沉淀出一些java技术栈AI Coding和AI Ops的最佳实践，后期需要输出到其他业务线（其他业务线很难换到go的生态)。

@wjn161 那其实你可以考虑基于这个项目来构建，有好的建议也期待你反馈回来。