openai/openai-go: 供应商适配与 I/O 边界¶
openai-go 解决的核心问题不是“如何少写 HTTP 请求”，而是如何将供应商的异构现实（模型端点、流式协议、错误分类）收口为 Go 原生的类型化对象。
1. 资源导向的 Client 建模¶
SDK 的主语是供应商资源，而不是“业务任务”。
- 资源面平铺：
Client.Chat.Completions、Client.Embeddings、Client.Files。这种平铺结构是为了原样映射 OpenAI 的 API 矩阵。 - 输入/输出解耦：请求体使用
NewParams结构，响应体使用独立的Response结构。工程直觉：不要在业务代码中直接传播 SDK 的原始 Params，而应在Provider Adapter层完成业务意图到 SDK 对象的转换。
2. 流式语义与错误治理¶
这是 SDK 真正发挥“防腐层”价值的地方：
- Streaming 稳压器：流式协议（Server-Sent Events）极其零碎。SDK 负责将底层的增量事件（Chunks）解码为可消费的 Go Channel 或 Iterator。上层业务不需要关心 SSE 的拼接逻辑和结束标志。
- 错误语义归一：SDK 必须能区分：
- 网络错误：可重试（Retryable）。
- API 错误 (401/429/500)：需进入降级或流控逻辑。
- 业务错误 (Content Filter/Invalid Request)：需上报业务层处理。
3. 工程防腐：SDK 的止步之处¶
很多团队因为 SDK 提供的便利而丧失了架构边界。
- 不要泄漏 SDK 类型：严禁在 Service、Repository 或外部接口中直接引用
openai包的类型。一旦未来需要切换 Anthropic 或自建模型，这些代码将成为沉重的技术债。 - 执行权归还宿主：即便 SDK 解析出了
tool_calls，它也不负责执行工具。模型只是“提出建议”，服务端执行权、参数注入、权限校验与审计必须由宿主系统闭环。
4. 常见误区与失效模式¶
- Transport 资源浪费：没有复用
http.Client或正确设置MaxIdleConns，导致高并发下连接耗尽。 - Context 丢失：未将
context.Context传进 SDK 调用，导致上游请求取消后，后台仍持续消耗 Token 产生费用。 - 忽略 Token 成本归因：直接抛弃 Response 里的
Usage信息，导致系统无法进行精准的成本治理与分账。
5. 排查顺序：从连接到语义¶
- 查 Transport 层：HTTP 状态码是什么？是否有网络超时或连接池排队？
- 查协议一致性：请求 Params 是否符合最新的 Schema？模型名称是否写错？
- 分析流式解析：是否出现了解码错误？Chunk 拼接是否在中间断裂？
- 查业务防腐：Adapter 转换逻辑是否有误？供应商的错误码是否被正确映射到了系统的统一错误体？
结论：
SDK 是供应商能力的翻译官，不是业务逻辑的替代品。好的架构是让 openai-go 守住 I/O 边界，将供应商的异构性挡在 Adapter 层之外。