> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Go SDK：从 v3 迁移到 v4

> 将 Square Cloud Go SDK 从 v3 升级到 v4：/v4 导入路径、会报告恢复仍在进行的 snapshot Restore、带时间范围的 Metrics，以及 409 RESTORE_IN_PROGRESS。

v4 是一个破坏性版本，因为有两个签名发生了变化。snapshot 的 `Restore` 现在会告诉你恢复是否仍在进行，`Metrics` 则接受一个时间范围。其他一切都是在此基础上新增的：两个新操作（总计 69 个）、新字段和新错误代码。

## 概览

| | v3 | v4 |
| - | - | - |
| 模块 | `github.com/squarecloudofc/sdk-api-go/v3` | `github.com/squarecloudofc/sdk-api-go/v4` |
| 操作 | 67 | 69，新增 `Apps.Snapshots.RestoreState` 和 `Databases.Snapshots.RestoreState` |
| Snapshot 恢复 | `Restore(ctx, id, name, versionID) error`。约 90 秒后仍在进行的恢复会返回 `nil`，就像它已经完成一样 | `Restore(ctx, id, name, versionID) (SnapshotRestored, error)`。恢复仍在进行时 `Pending` 为 `true`，并由 `RestoreState` 跟踪 |
| 指标 | `Metrics(ctx, id)`，仅限最近 24 小时 | `Metrics(ctx, id, rng)`，其中 `rng` 为 `""` 或 `"24h"`，或者为 `"7d"` 以获取带峰值的每小时数据点 |
| `RESTORE_IN_PROGRESS` | HTTP 403 | HTTP 409 |
| `CodeMetricsNotSupported` | 由 API 发送 | 已弃用：API 不再发送它 |
| Go 版本和依赖 | Go 1.22，没有依赖 | 不变 |

## 导入路径

只有导入路径发生变化。`New` 和每个 `Option` 都保持原有的签名和默认值，默认的 `User-Agent` 变为 `squarecloud-sdk-go/4.0.0`。

```diff theme={"system"}
-import "github.com/squarecloudofc/sdk-api-go/v3"
+import "github.com/squarecloudofc/sdk-api-go/v4"
```

```bash theme={"system"}
go get github.com/squarecloudofc/sdk-api-go/v4@v4.0.0
```

## 破坏性变更

下面的示例都在一个返回 `error` 的函数中运行。

### Snapshot 恢复

`Apps.Snapshots.Restore` 和 `Databases.Snapshots.Restore` 返回 `(SnapshotRestored, error)`，而不是 `error`。耗时超过约 90 秒的恢复会在调用返回后继续运行。v3 对它返回 `nil`，因此调用方会在恢复仍在进行时报告“已恢复”。v4 对它返回 `Pending: true`，对已完成的恢复返回 `Pending: false`。

```go theme={"system"}
// v3
if err := c.Apps.Snapshots.Restore(ctx, appID, snap.Name, snap.VersionID); err != nil {
	return err
}

// v4
res, err := c.Apps.Snapshots.Restore(ctx, appID, snap.Name, snap.VersionID)
if err != nil {
	return err
}
for res.Pending { // still running: follow it, never send the restore again
	time.Sleep(10 * time.Second)
	st, err := c.Apps.Snapshots.RestoreState(ctx, appID)
	if err != nil {
		return err
	}
	if st.State == "error" {
		return fmt.Errorf("restore failed: %s", st.Code)
	}
	res.Pending = st.State == "queued" || st.State == "running"
}
```

恢复运行时，`RestoreState` 报告 `queued` 或 `running` 以及当前的 `Step`；结束后 1 小时内报告 `success` 或 `error` 以及 `Code`。超过这一小时后，或没有近期恢复时，它报告 `none`。它允许每分钟调用 30 次。参见 [Snapshots](https://docs.squarecloud.app/zh/sdks/go/snapshots.md#跟踪恢复)。

### 指标

`Apps.Metrics` 和 `Databases.Metrics` 以时间范围作为最后一个参数。传入 `""` 可保持 v3 的行为，即覆盖最近 24 小时。

```go theme={"system"}
// v3
points, err := c.Apps.Metrics(ctx, appID)

// v4
points, err := c.Apps.Metrics(ctx, appID, "") // "" or "24h": the last 24 hours
```

`"7d"` 返回每小时一个的数据点，带有该小时的平均值及其 `CPUMax` 和 `RAMMax` 峰值，适用于 Pro 和 Enterprise 套餐上 512 MB 或以上的应用。其他套餐和更小的应用会得到 24 小时的结果且不会报错，因此请检查拿到的数据点，而不要假定是 7 天。其他任何时间范围都返回 400 `INVALID_PARAMETERS`。对于数据库，`"7d"` 需要 Pro 或 Enterprise 套餐。参见[指标](https://docs.squarecloud.app/zh/sdks/go/managing_application.md#指标)。

### `RESTORE_IN_PROGRESS` 改为 409

在应用和数据库的删除以及数据库的启动和停止上，`RESTORE_IN_PROGRESS` 从 403 改为 409。它也以 409 的形式新出现在应用的启动、停止和重启以及 snapshot 的 `Create` 和 `Restore` 上。请只匹配代码：

```go theme={"system"}
var apiErr *squarecloud.APIError

// v3
if errors.As(err, &apiErr) && apiErr.Status == 403 && apiErr.Code == squarecloud.CodeRestoreInProgress {
	// a snapshot restore is running
}

// v4
if errors.As(err, &apiErr) && apiErr.Code == squarecloud.CodeRestoreInProgress {
	// a snapshot restore is running (HTTP 409)
}
```

## 新增的类型和字段

| 类型 | v4 中的新增内容 |
| - | - |
| `SnapshotRestored` | 新类型：`Pending bool`，由 `Restore` 返回 |
| `SnapshotRestoreState` | 新类型：`State`、`Step` 和 `Code`（`string`），`StartedAt` 和 `FinishedAt`（`*int64`，Unix 毫秒），由 `RestoreState` 返回 |
| `ServiceStatus` | `Incidents []ServiceIncident`，即进行中的事件和维护窗口；以及 `Components []ServiceComponent`，即平台中未完全正常运行的部分。`Status` 可能为 `"maintenance"`，而 `"unknown"` 表示检查无法运行 |
| `MetricPoint` | `Disk []int64`，即自上次启动以来读取和写入的字节数；以及 `Storage *int64`，即磁盘上的字节数，两者在没有读数的数据点上都为 `nil`。`CPUMax` 和 `RAMMax *float64`，即每小时的峰值，仅在使用 `"7d"` 时设置 |
| `RuntimeStats`、`RuntimeStatsRaw` | `Restoring bool` |
| `DNSRecord` | `Errors []string`，最多 3 条说明记录为何尚未生效的消息；以及 `Fallback bool`，用于标记那条可以代替所有 SSL TXT 记录的 `_acme-challenge` CNAME |
| `AnalyticsTimeBucket` | `BytesIn int64` |
| `ChatRequest` | `MaxCompletionTokens int`，优先于 `MaxTokens` |

新字段只会破坏这些类型中省略了字段名的结构体字面量。请使用字段名。

## 错误

* 新常量：`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](https://docs.squarecloud.app/zh/sdks/go/snapshots.md#恢复-snapshot)。
* SDK 不会重试任何新代码。`SNAPSHOTS_UNAVAILABLE` 要求你等待约 30 秒，`CLUSTER_MAINTENANCE_TRY_LATER` 会持续数分钟，两者都比重试的等待时间更长。资源繁忙时的 409 由你决定如何处理。
* SDK 自身的错误 `INVALID_API_KEY`、`INVALID_ID` 和 `FILE_TOO_LARGE` 有了新消息，会说明出了什么问题以及如何修复。请比较 `Code`，而不是 `Message`。

完整参考请参见[错误](https://docs.squarecloud.app/zh/sdks/go/errors.md)。

## 行为变更

* **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`。

## 后续步骤

> [card] [客户端](https://docs.squarecloud.app/zh/sdks/go/client.md)
>
> 安装 SDK 并创建客户端。

> [card] [Snapshots](https://docs.squarecloud.app/zh/sdks/go/snapshots.md)
>
> 创建、恢复和跟踪 snapshot。

> [card] [错误](https://docs.squarecloud.app/zh/sdks/go/errors.md)
>
> 错误类、重试和速率限制。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.