Go SDK：快速上手与客户端

本页记录的是 github.com/squarecloudofc/sdk-api-go/v3（v3.0.0），这是 SDK 的一次重写。正从 v2 升级？请阅读 v2 → v3 迁移指南。

要求

Go 1.22 或更新版本。
一个 API 密钥（参见 API 密钥与作用域）。

该模块除 Go 标准库外没有任何依赖，并以 MIT 许可证发布（v2 为 AGPL-3.0）。其包名为 squarecloud。

安装

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

import "github.com/squarecloudofc/sdk-api-go/v3" // package squarecloud

API 密钥与作用域

在 squarecloud.app/account/security 创建密钥。SDK 会将其原样放入 Authorization 请求头发送（不带 Bearer 前缀）。密钥可以限制为特定的作用域（apps:read、apps:deploy、apps:control、ai:chat……）以及特定的应用或数据库：

超出这些限制的调用会返回 *APIError，状态为 403，代码为 MISSING_SCOPE 或 RESOURCE_NOT_ALLOWED。
列表方法（Account.Me、Apps.StatusAll……）只返回该密钥可见的资源。
未知、已撤销或已过期的密钥会返回 401 ACCESS_DENIED。

不要将密钥写入源代码，也不要将其放入你分发的二进制文件中。请从环境变量或密钥存储中读取它。

示例从环境变量 SQUARECLOUD_API_KEY 读取密钥。请在运行示例的终端中设置它：

macOS / Linux
Windows (PowerShell)

export SQUARECLOUD_API_KEY="your-api-key"

$env:SQUARECLOUD_API_KEY = "your-api-key"

创建客户端

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/squarecloudofc/sdk-api-go/v3"
)

func main() {
	ctx := context.Background()
	c := squarecloud.New(os.Getenv("SQUARECLOUD_API_KEY"))

	me, err := c.Account.Me(ctx)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("Hi %s, you have %d apps\n", me.User.Name, len(me.Applications))
}

将它保存为模块中的 main.go（先运行 go mod init example.com/hello，再运行上面的 go get），然后运行 go run .。它会打印你的账户名称，以及该密钥可以看到的应用数量：

Hi Jane, you have 3 apps

squarecloud.New(apiKey, opts...) 返回一个 *Client，并且从不返回错误。*Client 可以安全地并发使用：只需构建一次，然后在各个 goroutine 之间共享。由于 New 不会失败，空密钥或仅含空白字符的密钥不会在此处被拒绝。相反，除 Service.Status 外的每个调用都会在发送任何请求之前于本地以 INVALID_API_KEY（状态 0）失败。该代码仅存在于 Go SDK 中。

选项

在密钥之后将选项传给 New：

c := squarecloud.New(os.Getenv("SQUARECLOUD_API_KEY"),
	squarecloud.WithBaseURL(squarecloud.DefaultBaseURL), // "https://api.squarecloud.app/v2" (default)
	squarecloud.WithTimeout(30*time.Second),
	squarecloud.WithMaxRetries(2),
	squarecloud.WithUserAgent("my-bot/1.0"),
	squarecloud.WithHTTPClient(&http.Client{ // proxy, tracing, tests
		Transport: &http.Transport{Proxy: http.ProxyFromEnvironment},
	}),
)

选项	默认值	说明
`WithBaseURL(u)`	`https://api.squarecloud.app/v2`	API 基础 URL。末尾的 `/` 会被去除。也以 `DefaultBaseURL` 导出。
`WithTimeout(d)`	`30*time.Second`	当调用的 `ctx` 没有截止时间时使用的默认截止时间。它覆盖整个调用，包括重试。参见超时。
`WithMaxRetries(n)`	`2`	仅针对安全失败的重试次数（最多 3 次尝试）。负值视为 `0`。参见重试。
`WithUserAgent(ua)`	`squarecloud-sdk-go/<version>`	替换整个 `User-Agent` 请求头。
`WithHTTPClient(hc)`	`&http.Client{}`	用于代理、追踪或测试的自定义 `*http.Client`。`nil` 保留默认值。

不要在传给 WithHTTPClient 的 *http.Client 上设置 Timeout。该超时也覆盖读取响应体的过程，因此会切断实时流和 snapshot 下载。请改用 context、WithTimeout 以及 http.Transport 的超时。

SDK 从不输出日志。要追踪请求，请包装传给 WithHTTPClient 的客户端的 http.RoundTripper。

API 密钥存储在客户端的一个未导出字段中。fmt 会打印未导出字段，因此不要使用 %v 或 %+v 打印客户端。

运行示例

Go SDK 各页面中的代码片段都是片段。每个片段都可以在这个程序中单独运行，该程序声明了片段所用的 ctx、c 和 appID：

package main

import (
	"context"
	"os"

	"github.com/squarecloudofc/sdk-api-go/v3"
)

var (
	ctx   = context.Background()
	c     = squarecloud.New(os.Getenv("SQUARECLOUD_API_KEY"))
	appID = "abc123def456abc123def456" // one of your apps: see Account below
)

func main() {
	// Paste one snippet here, then run goimports.
}

每次只粘贴一个片段到 main 中，然后运行 goimports -w . 来添加它所需的导入（fmt、log、time……）。使用 go install golang.org/x/tools/cmd/goimports@latest 安装它，或者让编辑器的 Go 扩展（gopls）在保存时添加导入。需要其他 ID（例如数据库或 workspace 的 ID）的页面，会以它们自己版本的程序开头。

模块

字段	涵盖内容	页面
`c.Account`	`Me`、`Snapshots(ctx, scope)`	账户和 Snapshots
`c.Service`	`Status`	平台状态
`c.Apps`	获取、删除、状态、生命周期、日志、指标、域名、负载均衡器	管理应用
`c.Apps.Create` / `Commit`	上传	Commit 与上传
`c.Apps.Files`	文件管理器	管理文件
`c.Apps.Envs`	环境变量	环境变量
`c.Apps.Deploys`	Webhook 和 GitHub App deploy	Deploys
`c.Apps.Network`	分析、日志、DNS、自定义域名、缓存	网络
`c.Apps.Realtime`	实时日志和状态	实时
`c.Apps.Snapshots` / `c.Databases.Snapshots` / `c.DownloadSnapshot`	备份	Snapshots
`c.Databases`	托管数据库	数据库
`c.Workspaces`	Workspace、成员和共享应用	Workspaces
`c.AI`	`Chat`	AI

除了 New 和各个 With* 选项之外，该包还导出 DefaultBaseURL 和 Version 常量、APIError 类型（每个错误代码对应一个 Code* 常量）、用于枚举输入的类型化常量（DatabaseRedis、GroupView、ResetPassword、SnapshotScopeDatabases……），以及与每种 API 结构对应的结构体，你可以在自己的代码中使用它们：

func appNames(apps []squarecloud.AppSummary) []string {
	names := make([]string, 0, len(apps))
	for _, app := range apps {
		names = append(names, app.Name)
	}
	return names
}

约定

Context 和 ID 在前，返回类型化数据

每个方法都以 context.Context 作为第一个参数、资源 ID 作为第二个参数，并返回普通结构体（没有方法，没有缓存）。json 标签就是 API 自身的字段名（created_at、version_id、lastModified、joinedAt、netIO……），因此 API 参考可直接适用：CreatedAt 即 created_at，VersionID 即 version_id。API 之后新增的字段会被忽略，因此永远不会导致解码失败。

变更操作只返回 error，除非 API 返回数据（Envs.*、Deploys.SetWebhook、Deploys.LinkGithubApp、Databases.ResetCredentials 以及各 Create 方法）。
当 API 未返回字符串结果时，其值为 ""。
API 可能以 null 发送的字段是指针：使用前请检查是否为 nil。
计数器和字节大小为 int64。
列表一次调用即完整返回：没有分页。

app, err := c.Apps.Get(ctx, appID)
if err != nil {
	log.Fatal(err)
}
if app.Domain != nil { // *string: nil for apps without a web domain
	fmt.Println("https://" + *app.Domain)
}

资源组是普通的结构体字段，因此可以保存方法值：

restart, logs := c.Apps.Restart, c.Apps.Logs

if err := restart(ctx, appID); err != nil {
	log.Fatal(err)
}
out, err := logs(ctx, appID)
if err != nil {
	log.Fatal(err)
}
fmt.Println(out)

Workspace 应用

每个 appID 也接受组合形式 <appId>-<workspaceId>，用于操作通过 workspace 与你共享的应用。Workspaces.Get 和 Workspaces.List 返回原始 ID；组合 ID 需要你自行构建：

workspaceID := "0123456789abcdef0123456789abcdef"

if err := c.Apps.Restart(ctx, appID+"-"+workspaceID); err != nil {
	log.Fatal(err)
}

ID 会被编码

URL 路径中的 ID 会进行百分号编码。空的、. 或 .. 的 ID 会到达不同的路由，因此会在发送任何内容之前于本地以 INVALID_ID（状态 0）失败。Workspace 路由则将 ID 放在请求体中发送：在那里，INVALID_ID（400）来自服务器。

日期

start 和 end 参数（参见网络）是 time.Time 值，以 UTC 的 RFC 3339 格式（精确到整秒）发送。在响应中，API 的 ISO 8601 字符串会解码为 time.Time，而 API 以 Unix 毫秒发送的字段仍保持为数字（Plan.Duration 和 Uptime 为 *int64，FileEntry.LastModified 为 *float64）：请使用 time.UnixMilli 进行转换。

超时

调用	默认截止时间
其他所有调用	`WithTimeout`（30 秒）
服务器保持连接的调用：应用的 `Start`/`Stop`/`Restart`、数据库的 `Start`/`Stop`、`Databases.Create`、snapshot 的 `Create`/`Restore`、`AI.Chat`	至少 2 分钟（更大的 `WithTimeout` 优先）
上传（`Apps.Create`、`Apps.Commit`）、超过 1 MiB 的 `Files.Write`、`DownloadSnapshot`	无：取消 `ctx`
`Apps.Realtime`	仅在响应头到达之前

默认截止时间仅在 ctx 没有截止时间时生效。ctx 上的截止时间始终优先，无论它比默认值更短还是更长，下限也包括在内。
一个截止时间覆盖整个调用：每次尝试以及重试之间的等待。
WithTimeout(0)（或任何 d <= 0）会禁用所有默认截止时间，包括 2 分钟的下限。

每个方法都接受 ctx，因此你可以限制或取消任何调用：

ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
defer cancel()

f, err := os.Open("build.zip")
if err != nil {
	log.Fatal(err)
}
defer f.Close()

if err := c.Apps.Commit(ctx, appID, f, "", ""); err != nil {
	log.Fatal(err)
}

ctx 到期的调用会返回代码为 TIMEOUT 的 *APIError，ctx 被取消的调用会返回 NETWORK_ERROR，两者的状态均为 0。它们可以解包为 context 的错误，因此 errors.Is(err, context.DeadlineExceeded) 和 errors.Is(err, context.Canceled) 都能正常工作。实时循环则直接返回 ctx.Err()。

账户

c.Account.Me(ctx) 返回已认证的用户，以及该密钥可见的应用和数据库。

me, err := c.Account.Me(ctx)
if err != nil {
	log.Fatal(err)
}

user := me.User
fmt.Println(user.ID, user.Name, user.Email, user.Plan.Name)
fmt.Println(user.Plan.Memory.Limit, user.Plan.Memory.Available, user.Plan.Memory.Used) // MB
if user.Plan.Duration != nil {
	fmt.Println("expires", time.UnixMilli(*user.Plan.Duration))
} else {
	fmt.Println("never expires")
}

字段	说明
`User`（`user`）	`ID`、`Name`、`Email`、`Locale`、`CreatedAt` 和 `Plan`（`Name`、`Memory`、`Duration`：套餐到期时的 Unix 毫秒时间，永不到期时为 `nil`）
`Applications`（`applications`）	`[]AppSummary`：`ID`、`Name`、`Description`（`desc`）、`RAM`、`Lang`、`Domain`（`string`）、`Custom`（`string`）、`Cluster`、`CreatedAt`
`Databases`（`databases`）	`[]DatabaseSummary`：`ID`、`Name`、`RAM`、`Type`、`Cluster`、`CreatedAt`

c.Account.Snapshots(ctx, scope) 列出账户的所有 snapshot：参见 Snapshots。

平台状态

c.Service.Status(ctx) 返回公开的平台状态。该路由不需要密钥，并且它是唯一一个在使用空密钥构建的客户端上也能工作的方法。

status, err := c.Service.Status(ctx)
if err != nil {
	log.Fatal(err)
}

fmt.Println(status.Status) // "online" | "degraded" | "unknown"
fmt.Println(status.Message)

for name, service := range status.Services {
	fmt.Println(name, service.Status) // "operational" | "degraded" | "outage" | "maintenance" | "unknown"
}

unknown 表示检查本身无法运行：这并不代表发生了故障。

后续步骤

管理应用

状态、生命周期、日志和指标。

错误

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

API 简介

基础 URL、身份验证和第一个请求。

CLI 快速开始

在终端中部署和管理应用。

CLI

VS Code

SDKs

Go SDK：快速上手与客户端

要求

安装

API 密钥与作用域

创建客户端

选项

运行示例

模块

约定

Context 和 ID 在前，返回类型化数据

Workspace 应用

ID 会被编码

日期

超时

账户

平台状态

后续步骤

管理应用

错误

API 简介

CLI 快速开始

​要求

​安装

​API 密钥与作用域

​创建客户端

​选项

​运行示例

​模块

​约定

​Context 和 ID 在前，返回类型化数据

​Workspace 应用

​ID 会被编码

​日期

​超时

​账户

​平台状态

​后续步骤

管理应用

错误

API 简介

CLI 快速开始

要求

安装

API 密钥与作用域

创建客户端

选项

运行示例

模块

约定

Context 和 ID 在前，返回类型化数据

Workspace 应用

ID 会被编码

日期

超时

账户

平台状态

后续步骤