Restore 现在会告诉你恢复是否仍在进行,Metrics 则接受一个时间范围。其他一切都是在此基础上新增的:两个新操作(总计 69 个)、新字段和新错误代码。
概览
导入路径
只有导入路径发生变化。New 和每个 Option 都保持原有的签名和默认值,默认的 User-Agent 变为 squarecloud-sdk-go/4.0.0。
破坏性变更
下面的示例都在一个返回error 的函数中运行。
Snapshot 恢复
Apps.Snapshots.Restore 和 Databases.Snapshots.Restore 返回 (SnapshotRestored, error),而不是 error。耗时超过约 90 秒的恢复会在调用返回后继续运行。v3 对它返回 nil,因此调用方会在恢复仍在进行时报告“已恢复”。v4 对它返回 Pending: true,对已完成的恢复返回 Pending: false。
RestoreState 报告 queued 或 running 以及当前的 Step;结束后 1 小时内报告 success 或 error 以及 Code。超过这一小时后,或没有近期恢复时,它报告 none。它允许每分钟调用 30 次。参见 Snapshots。
指标
Apps.Metrics 和 Databases.Metrics 以时间范围作为最后一个参数。传入 "" 可保持 v3 的行为,即覆盖最近 24 小时。
"7d" 返回每小时一个的数据点,带有该小时的平均值及其 CPUMax 和 RAMMax 峰值,适用于 Pro 和 Enterprise 套餐上 512 MB 或以上的应用。其他套餐和更小的应用会得到 24 小时的结果且不会报错,因此请检查拿到的数据点,而不要假定是 7 天。其他任何时间范围都返回 400 INVALID_PARAMETERS。对于数据库,"7d" 需要 Pro 或 Enterprise 套餐。参见指标。
RESTORE_IN_PROGRESS 改为 409
在应用和数据库的删除以及数据库的启动和停止上,RESTORE_IN_PROGRESS 从 403 改为 409。它也以 409 的形式新出现在应用的启动、停止和重启以及 snapshot 的 Create 和 Restore 上。请只匹配代码:
新增的类型和字段
新字段只会破坏这些类型中省略了字段名的结构体字面量。请使用字段名。
错误
- 新常量:
CodeAIWeeklyLimitReached、CodeEnvBusy(409)、CodeGitBranchDeleted和CodeGitRefNotSupported(只发送给 GitHub 推送 webhook)、CodeRestoreInterrupted、CodeSnapshotsUnavailable(503)、CodeSnapshotCorrupt、CodeSnapshotInProgress(409)、CodeSnapshotRestoreProcessing(以SnapshotRestored.Pending的形式报告,从不作为错误)、CodeWriteFailed,以及CodeWrongHost(421,从不返回给本 SDK 的调用)。 CodeMetricsNotSupported已弃用,但仍保留。- 恢复失败时可能返回
SNAPSHOT_RESTORE_FAILED以外的更多代码。完整列表请参见 Snapshots。 - SDK 不会重试任何新代码。
SNAPSHOTS_UNAVAILABLE要求你等待约 30 秒,CLUSTER_MAINTENANCE_TRY_LATER会持续数分钟,两者都比重试的等待时间更长。资源繁忙时的 409 由你决定如何处理。 - SDK 自身的错误
INVALID_API_KEY、INVALID_ID和FILE_TOO_LARGE有了新消息,会说明出了什么问题以及如何修复。请比较Code,而不是Message。
行为变更
- Snapshot 链接在 1 小时后过期。 它们以前的有效期为 30 天,因此请在列出或创建 snapshot 后立即下载。只有
Create会在 API 密钥缺少snapshots:read时返回空的URL和Key,并带有Pending: false。 - Snapshot 列表(
Account.Snapshots、Apps.Snapshots.List和Databases.Snapshots.List)在 snapshot 存储无法响应时返回 503SNAPSHOTS_UNAVAILABLE,而不是空列表。 - 指标。 低于 512 MB 的应用现在也有指标,每 10 分钟一个数据点,而以前它们会得到 400
METRICS_NOT_SUPPORTED。 - 环境变量。 当另一次写入正在进行时,
Envs.Set、Envs.Replace和Envs.Delete返回 409ENV_BUSY。使用缺少envs:read的 API 密钥时,Envs.Set只返回你发送的变量,而不是完整的集合,Envs.Delete返回空集合。 - 文件。
Files.Read和Files.Write可能返回 400READ_FAILED和WRITE_FAILED,Commit可能返回 403BLOCKED_PATH。 - 并行上传。 API 限制一个账户可以同时发送的大型上传数量。超出限制会返回 429
RATE_LIMITED,SDK 从不重试它。 - AI。
AI.Chat返回的 429 可能是weekly_limit_reached。 - User-Agent 为
squarecloud-sdk-go/4.0.0。
检查清单
1
更改导入路径
在所有地方导入
github.com/squarecloudofc/sdk-api-go/v4,并运行 go get github.com/squarecloudofc/sdk-api-go/v4@v4.0.0。2
跟踪待处理的恢复
将
err := c.Apps.Snapshots.Restore(...) 替换为 res, err := ...。当 res.Pending 为 true 时,轮询 RestoreState(例如每 10 秒一次),直到 State 为 success 或 error。切勿再次发送恢复请求。3
向 Metrics 传入时间范围
在
Apps.Metrics 和 Databases.Metrics 的最后一个参数位置添加 ""、"24h" 或 "7d"。4
匹配 409 RESTORE_IN_PROGRESS
在原先匹配
403 的地方改为匹配 409,或者只匹配代码。5
处理 503 SNAPSHOTS_UNAVAILABLE
在 snapshot 列表上处理它,而不是把空列表理解为“没有 snapshot”。
6
比较代码,而不是消息
在原先比较
INVALID_API_KEY、INVALID_ID 或 FILE_TOO_LARGE 的 Message 的地方,改为检查 Code。后续步骤
客户端
安装 SDK 并创建客户端。
Snapshots
创建、恢复和跟踪 snapshot。
错误
错误类、重试和速率限制。

