Go SDK 接入教程
内容提要
本文介绍Ace Data Cloud官方Go SDK的接入教程。SDK将chat completions、images等API封装为方法链，支持SSE流式、自动重试和类型化错误处理。文章详细演示了安装、配置API Token、非流式与流式调用示例、错误处理及客户端复用方法，并说明当前稳定功能与alpha阶段功能，最后提示在控制台查看额度和使用历史。
延伸解读
版本与稳定性提示
当前 Go SDK 未打 semver 标签，go get 拉取的是 commit 伪版本，依赖会被锁进 go.sum，团队协作时能保证依赖一致。但需注意，chat.completions 是稳定路径，而 images、video、audio 及 TaskHandle 轮询仍处于 alpha 阶段，接口可能变动，生产环境使用这些功能需谨慎评估。
设计取舍与使用注意
SDK 响应统一为 map[string]any，需要手动类型断言，这是为了支持多模型路由而不绑定单一上游 schema。同时，SDK 不会自动读取环境变量，需通过 os.Getenv 显式注入 token，这样在多账号或测试场景下更可控。建议在服务启动时通过 NewClient 校验 token 配置，避免运行时才发现错误。
性能与复用建议
首次请求耗时较长（示例中约 6.4 秒），主要花在 TLS 握手和模型生成上，复用 client 实例后延迟可降至 2~3 秒。SDK 内部使用连接池和 HTTP/2，推荐在进程生命周期内只创建一个 *adc.Client 并跨 goroutine 共享，所有方法并发安全，可提升性能并减少资源开销。
Q&A
如何安装 Ace Data Cloud 的 Go SDK？
使用 go get 命令安装：go get github.com/AceDataCloud/SDK/go。当前没有 semver 标签，go get 会拉取 commit 伪版本，并锁定在 go.sum 中。
Go SDK 如何配置 API Token？
先通过环境变量导出 token：export ACEDATACLOUD_API_TOKEN={token}，然后在构造客户端时通过 WithAPIToken(os.Getenv("ACEDATACLOUD_API_TOKEN")) 显式注入。Go SDK 不会自动读取环境变量，需要业务代码调用 os.Getenv。
Go SDK 支持哪些功能？哪些是稳定版，哪些是 alpha 阶段？
稳定功能包括 chat.completions 的同步和流式调用、类型化错误处理、自动重试。alpha 阶段包括 images、video、audio 等多媒体资源以及 TaskHandle 异步轮询，这些建议优先使用 TypeScript 或 Python SDK。
如何使用 Go SDK 进行非流式 chat.completions 调用？
创建客户端后，调用 client.OpenAI().Chat().Completions().Create(ctx, request) 即可。请求中需指定模型、消息等参数，响应为 map[string]any，需要自行类型断言获取内容。
Go SDK 的流式调用（SSE）如何使用？
调用 CreateStream 方法，返回两个 channel：一个用于接收解析好的 SSE chunk，另一个用于接收错误。通过 range 遍历 chunk，流结束时自动退出循环，错误 channel 最多 yield 一个元素。
Go SDK 如何处理错误？
SDK 提供类型化错误 adc.APIError，覆盖 401/403/404/422/429/5xx 等状态码。业务代码使用 errors.As 获取结构化字段（StatusCode、Code、Message）。网络层错误如 DNS 失败、连接被拒等会返回标准 Go 错误，如 context.DeadlineExceeded、net.OpError。
Go SDK 有哪些配置选项？
配置选项包括 WithAPIToken（必填）、WithBaseURL（默认 https://api.acedata.cloud）、WithTimeout（默认 5 分钟）、WithMaxRetries（默认 2）、WithHeader（自定义请求头）。NewClient 在 token 为空且未传 WithPaymentHandler 时会立即报错。
Go SDK 客户端是否可以复用？
可以。SDK 内部使用 *http.Client 和 http.Transport，自带连接池和 HTTP/2 复用。推荐在进程生命周期内只创建一个 *adc.Client，并跨 goroutine 共享，因为所有方法都是并发安全的。
如何查看剩余额度和使用历史？
通过 Ace Data Cloud 控制台的“应用列表”查看剩余额度，通过“使用历史”查看所有使用历史和扣费详情。
