Go SDK：从 v2 迁移到 v3

​

概览

​

构造和选项

-import (
-	"github.com/squarecloudofc/sdk-api-go/v2/rest"
-	"github.com/squarecloudofc/sdk-api-go/v2/squarecloud"
-)
-client := rest.NewClient(token, rest.WithUserAgent(ua), rest.WithLogger(logger))
-api := rest.New(client)
-defer client.Close()
+import "github.com/squarecloudofc/sdk-api-go/v3"
+
+c := squarecloud.New(token, squarecloud.WithUserAgent(ua))

go get github.com/squarecloudofc/sdk-api-go/v3@v3.0.0

​

逐个方法对照

​

类型

​

错误

// v2
if rest.IsRateLimit(err) { ... }

// v3
var apiErr *squarecloud.APIError
if errors.As(err, &apiErr) && apiErr.Status == 429 {
	fmt.Println(apiErr.Code, apiErr.Message) // KEEP_CALM or RATE_LIMITED
}

• 网络失败现在是 *APIError，Status 为 0，Code 为 NETWORK_ERROR 或 TIMEOUT，Message 为原因的文本，并且可以解包为原因（errors.Is(err, context.Canceled) 能正常工作）。
• 本地检查（Status 为 0：INVALID_ID、FILE_TOO_LARGE、INVALID_API_KEY）以及不是 JSON 的 2xx 响应体（UNKNOWN_ERROR，Invalid JSON in HTTP <status> response）也是如此。
• 声明 "status": "error" 的 2xx 响应体现在被视为错误（v2 将其报告为成功）。应用和数据库启动/停止时集群的拒绝会以 409 CONTAINER_ALREADY_STARTED、CONTAINER_ALREADY_STOPPED、CONTAINER_TEMPORARILY_SUSPENDED、CONTAINER_NOT_FOUND、CONTAINER_INSUFFICIENT_DISK_SPACE、CONTAINER_NETWORK_CONFLICT 或 ACTION_FAILED 返回，且没有消息。SDK 会将“已经……”类的响应作为错误返回：如有需要，请自行将其视为成功。
• 没有代码的响应的 Code 为 UNKNOWN_ERROR。
• 已过期的 API 密钥与未知密钥一样返回 401 ACCESS_DENIED。
• API 公开记录的每个代码都有一个 Code* 常量。API 现在在原先发送 RATE_LIMIT 和 RATE_LIMIT_EXCEEDED 的地方发送 429 RATE_LIMITED（CodeRateLimited）；CodeRateLimit 和 CodeRateLimitExceeded 仍然保留，但已弃用。
• 每个 AI.Chat 错误都采用 OpenAI 格式，带有小写代码（access_denied、rate_limit_exceeded、server_overloaded……），Code 会原样携带这些代码。
• Error() 输出 squarecloud: <METHOD> <path>: HTTP <status> <CODE>: <message>（v2：squarecloud: <message> (<CODE>, HTTP <status>)）。请根据字段进行匹配，而不是依赖文本。

​

行为变更

• 空 API 密钥： New("")（或仅含空白字符的密钥）仍然返回一个客户端（它无法返回错误），但除 Service.Status 外的每个调用都会在本地以 INVALID_API_KEY 失败。
• Snapshot 202： v2 返回 StatusCode 为 202 的 *APIError。v3 返回 Pending: true 的 SnapshotCreated，错误为 nil。
• 实时： Next 现在返回 RealtimeEvent。请根据 ev.Event（system、status、logs、error、message）进行分支处理。对于日志，打印 ev.Line（\u0001/\u0002 字节已被去除；ev.Data 保持为原始帧），并使用 ev.Stream 区分 stdout/stderr。对于状态，请使用 ev.Status：在状态事件中永远不为 nil，并在各帧和重新连接之间进行浅合并。在 REALTIME_DISCONNECTED 之后，Next 返回 io.EOF。流不再在 30 秒后中断，重新连接会在上一次打开后至少等待 5.5 秒，并且在响应头到达之前，打开阶段受客户端超时的限制。参见实时。
• 超时： v2 对所有调用使用固定 30 秒的 http.Client 超时。v3 仅在 ctx 没有截止时间时才应用默认截止时间：大多数调用使用客户端超时（WithTimeout，30 秒）；启动/停止/重启、数据库创建、snapshot 创建/恢复以及 AI.Chat 至少为 2 分钟；上传、内容超过 1 MiB 的文件写入以及 snapshot 下载则没有截止时间。WithTimeout(0) 会禁用所有这些截止时间。
• 空的网络窗口： 当窗口内没有流量时，Analytics、Errors 和 Performance 返回 nil 指针。
• 请求头： 每个 API 请求都会发送 Accept: application/json（实时则为 text/event-stream）。默认的 User-Agent 从 Square GO 改为 squarecloud-sdk-go/3.0.0（WithUserAgent 仍然可以覆盖它）。
• ID： 每个 ID 现在都会作为单个路径段进行百分号编码（v2 会将其原样拼接到路径中），空的、. 或 .. 的 ID 会在本地以 INVALID_ID 失败。
• 文件写入： v2 总是以字符串发送内容，这会损坏二进制文件，并且无法写入空文件。v3 始终以 base64 编码发送内容，因此每个字节都能完整往返，空内容会写入一个空文件，超过 10 MB 的内容会在本地以 FILE_TOO_LARGE 失败。对于无法解码的内容，API 返回 400 INVALID_CONTENT。
• 文件读取： v3 始终以 base64 请求并解码，而不是像 v2 那样读取 JSON 字节数组（API 已弃用该格式）。超过 10 MB 的文件返回 413 FILE_TOO_LARGE。
• 文件列表： 列出不存在的目录会返回 404 FILE_NOT_FOUND；以前返回的是空列表。
• Snapshots： 列表条目携带来自 API 的 VersionID 和 URL；不再从 Key 中解析任何内容。
• 重试： 新增。GET 的网络错误、503 UPLOAD_BUSY/ANALYTICS_BUSY 以及 GET 上的 503 DATABASE_UNAVAILABLE 默认重试两次；WithMaxRetries(0) 可恢复 v2 的行为。DATABASE_UNAVAILABLE 可能在变更操作已经开始之后才到达，因此 SDK 从不在其他方法上重试它；如有需要，请自行重试幂等的变更操作。参见重试。
• Go 版本： 最低版本从 Go 1.24 降至 Go 1.22。

​

后续步骤