SDK API

本页汇总 OpenTrans 对外暴露的主要 SDK 能力，并按开发者最常见的使用路径组织。

导入方式

推荐从模块根路径导入：

import opentrans "github.com/xy200303/OpenTrans"

根目录 opentrans.go 已统一暴露公开 API。

协议常量

当前支持的协议常量：

opentrans.ProtocolOpenAI
opentrans.ProtocolResponses
opentrans.ProtocolClaude
opentrans.ProtocolGemini

一、Body 级转换 API

这是最常用的一组 API，适合处理原始 []byte。

请求体转换

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

非流式响应体转换

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

流式事件 payload 转换

out, err := opentrans.ConvertStreamEventBody(
	body,
	opentrans.ProtocolResponses,
	opentrans.ProtocolClaude,
)

二、标准化结构 API

如果你要在协议中间层插入自己的业务逻辑，推荐先归一化到标准化结构。

请求

req, err := opentrans.NormalizeRequest(opentrans.ProtocolGemini, body)
out, err := opentrans.MarshalRequest(req, opentrans.ProtocolOpenAI)

响应

resp, err := opentrans.NormalizeResponse(opentrans.ProtocolClaude, body)
out, err := opentrans.MarshalResponse(resp, opentrans.ProtocolResponses)

流式事件

evt, err := opentrans.NormalizeStreamEvent(opentrans.ProtocolOpenAI, body)
out, err := opentrans.MarshalStreamEvent(evt, opentrans.ProtocolClaude)

适用场景：

• 日志采集
• 路由决策
• prompt 改写
• 审计与风控
• provider 特有字段透传

三、Model 级转换 API

如果你已经有 provider struct，可以直接走 model 级接口。

统一入口

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

out, err := opentrans.ConvertResponseModel(
	claudeResp,
	opentrans.ProtocolClaude,
	opentrans.ProtocolOpenAI,
)

out, err := opentrans.ConvertStreamEventModel(
	claudeEvt,
	opentrans.ProtocolClaude,
	opentrans.ProtocolResponses,
)

分协议 Normalize / Marshal 入口

OpenTrans 同时暴露 provider 结构体到标准化结构的薄封装。

请求相关：

req, err := opentrans.NormalizeOpenAIChatCompletionParams(openaiParams)
req, err := opentrans.NormalizeResponsesRequest(responsesReq)
req, err := opentrans.NormalizeClaudeMessageParams(claudeParams)
req, err := opentrans.NormalizeGeminiGenerateContentRequest(geminiReq)

响应相关：

resp, err := opentrans.NormalizeOpenAIChatCompletion(openaiResp)
resp, err := opentrans.NormalizeClaudeMessage(claudeResp)
resp, err := opentrans.NormalizeResponsesResponse(responsesResp)
resp, err := opentrans.NormalizeGeminiGenerateContentResponse(geminiResp)

流式相关：

evt, err := opentrans.NormalizeOpenAIChatCompletionChunk(openaiChunk)
evt, err := opentrans.NormalizeClaudeMessageStreamEvent(claudeEvt)
evt, err := opentrans.NormalizeResponsesStreamEvent(responsesEvt)
evt, err := opentrans.NormalizeGeminiGenerateContentStreamChunk(geminiChunk)

四、Converter

Converter 适合复用固定的源协议和目标协议组合。

创建方式

converter, err := opentrans.NewConverter(
	opentrans.ProtocolOpenAI,
	opentrans.ProtocolGemini,
)

或：

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

支持的方法

请求相关：

• Normalize
• Marshal
• Convert
• ConvertRequestModel

响应相关：

• NormalizeResponse
• MarshalResponse
• ConvertResponse
• ConvertResponseModel

流式相关：

• NormalizeStreamEvent
• MarshalStreamEvent
• ConvertStreamEvent
• ConvertStreamEventModel

五、事件类型常量

当前公开的统一事件类型常量：

opentrans.EventTypeResponseStart
opentrans.EventTypeContentDelta
opentrans.EventTypeResponseStop
opentrans.EventTypeUsage

六、Gin 中间件

pkg/opentrans/ginx 提供 Gin 适配层：

• ginx.ConvertRequestBody(source, target)
• ginx.ConvertResponseBody(source, target)
• ginx.ConvertStreamEventBody(source, target)
• ginx.MiddlewareOptions

这组 API 适合直接接入网关或代理层 handler 链路。

更多细节见：Gin 中间件

七、推荐使用顺序

如果你不确定应该从哪一层开始：

1. 优先尝试 ConvertRequestBody / ConvertResponseBody
2. 需要插入业务逻辑时切到 Normalize* + Marshal*
3. 项目里已经有 typed struct 时使用 Convert*Model
4. 在 Web 服务中直接代理时使用 ginx