跳转到主要内容
v4 是一个破坏性版本,因为有两个签名发生了变化。snapshot 的 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 存储无法响应时返回 503 SNAPSHOTS_UNAVAILABLE,而不是空列表。
  • 指标。 低于 512 MB 的应用现在也有指标,每 10 分钟一个数据点,而以前它们会得到 400 METRICS_NOT_SUPPORTED。
  • 环境变量。 当另一次写入正在进行时,Envs.Set、Envs.Replace 和 Envs.Delete 返回 409 ENV_BUSY。使用缺少 envs:read 的 API 密钥时,Envs.Set 只返回你发送的变量,而不是完整的集合,Envs.Delete 返回空集合。
  • 文件。 Files.Read 和 Files.Write 可能返回 400 READ_FAILED 和 WRITE_FAILED,Commit 可能返回 403 BLOCKED_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。

错误

错误类、重试和速率限制。