集成方式

本页帮助你判断应该使用 OpenTrans 的哪一种接入方式，以及不同方式各自适合放在系统的哪一层。

选择建议

目标	推荐入口	说明
直接处理 HTTP body	ConvertRequestBody / ConvertResponseBody / ConvertStreamEventBody	最适合网关、兼容层、代理层
需要插入中间逻辑	Normalize* + Marshal*	适合做日志、路由、字段改写
已经持有 typed struct	Convert*Model 或 provider 结构体 Normalize* / Marshal*	避免不必要 JSON 往返
重复执行同一种协议转换	Converter	降低调用层样板代码
Gin 服务直接拦截	pkg/opentrans/ginx	适合服务端中间件接入
直接部署转换服务	services/opentransd	适合工具化、自助转换、调试环境

模式一：Body -> Body

这是最直接的接入方式，输入和输出都是 []byte。

out, err := opentrans.ConvertRequestBody(
	body,
	opentrans.ProtocolOpenAI,
	opentrans.ProtocolClaude,
)

优点：

• 接入最简单
• 适合 HTTP 网关
• 与现有 handler/代理逻辑容易拼接

注意点：

• 输入 body 必须符合源协议格式
• 如果你需要改写中间字段，这种方式不如标准化结构直观

模式二：标准化中间结构

先归一化，再按目标协议输出：

req, err := opentrans.NormalizeRequest(opentrans.ProtocolOpenAI, body)
if err != nil {
	return err
}

req.Metadata = map[string]any{
	"route": "fallback-a",
}

out, err := opentrans.MarshalRequest(req, opentrans.ProtocolClaude)

适合做：

• 模型路由
• 统一审计
• Prompt 注入或改写
• 工具定义裁剪
• 附加内部元信息

模式三：结构体模式

如果项目内已经使用 provider struct，可以直接在结构体之间转换。

单步模型转换

out, err := opentrans.ConvertRequestModel(
	openaiReq,
	opentrans.ProtocolOpenAI,
	opentrans.ProtocolClaude,
)

分步控制

req, err := opentrans.NormalizeClaudeMessageParams(claudeReq)
out, err := opentrans.MarshalGeminiGenerateContentRequest(req)

适合做：

• 内部 SDK 封装
• 单元测试
• 基准测试
• 强类型编排

模式四：Converter 复用实例

如果一种协议组合会被反复使用，可以复用一个转换器实例：

converter := opentrans.MustNewConverter(
	opentrans.ProtocolOpenAI,
	opentrans.ProtocolGemini,
)

out, err := converter.Convert(body)

Converter 同时支持请求、响应、流式和 model 转换，适合放在：

• provider adapter
• router handler
• 复用型服务组件

模式五：Gin 中间件

pkg/opentrans/ginx 适合把转换直接挂到 Web 服务链路里：

router.POST(
	"/v1/chat/completions",
	ginx.ConvertRequestBody(opentrans.ProtocolOpenAI, opentrans.ProtocolClaude),
	handler,
)

支持三类中间件：

• ConvertRequestBody
• ConvertResponseBody
• ConvertStreamEventBody

流式中间件当前支持：

• SSE data: 帧转换
• CRLF 换行
• 多行 data:
• event: / id: / comment 透传

更多细节见：Gin 中间件

模式六：独立 Web 服务

如果你希望先用一个现成服务验证协议转换效果，或者给团队提供一个浏览器可视化调试页，可以直接部署：

go run ./services/opentransd/cmd/opentransd

适合：

• 团队内部调试环境
• 协议回归验证
• 分享转换示例
• 文档演示和 QA 使用

更多细节见：Web 服务与 Docker

选型建议

如果你不确定从哪里开始：

• 只做网关桥接：优先用 Body -> Body
• 需要插入业务逻辑：优先用标准化结构
• 已有 typed client：优先用结构体模式
• 在 Gin 里做代理：优先用 ginx
• 想先给团队提供一个可见工具：优先用 opentransd