Client

要求

Go 1.24 或更新版本
零外部依赖 —— SDK 仅基于 Go 标准库构建
一个有效的 API 密钥 —— 可在 Square Cloud 控制台的 My Account → Regenerate API/CLI KEY 中申请

安装

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

该模块提供两个包：

包	导入路径	内容
`rest`	`github.com/squarecloudofc/sdk-api-go/v2/rest`	HTTP 客户端、资源接口、请求选项、错误、SSE 流
`squarecloud`	`github.com/squarecloudofc/sdk-api-go/v2/squarecloud`	所有请求/响应类型和结构体

实例化客户端

package main

import (
	"fmt"
	"os"

	"github.com/squarecloudofc/sdk-api-go/v2/rest"
)

func main() {
	client := rest.NewClient(os.Getenv("SQUARECLOUD_API_KEY"))
	defer client.Close()

	api := rest.New(client)

	user, err := api.SelfUser()
	if err != nil {
		panic(err)
	}
	fmt.Println(user.Name)
}

rest.NewClient(token, opts...) 构建底层 HTTP 客户端；rest.New(client) 将其包装为 rest.Rest，即暴露所有资源的接口。始终 defer client.Close() 以释放空闲连接。

客户端配置（`ConfigOpt`）

rest.NewClient 在 token 之后接受可选的 ConfigOpt：

选项	默认值	说明
`rest.WithLogger(*slog.Logger)`	丢弃日志	用于请求/响应调试的结构化日志器
`rest.WithHTTPClient(*http.Client)`	30s 超时	自定义 `*http.Client`（代理、传输层、超时）
`rest.WithURL(string)`	`https://api.squarecloud.app/v2`	API 基础 URL
`rest.WithUserAgent(string)`	SDK 默认值	自定义 `User-Agent` 请求头

client := rest.NewClient(
	os.Getenv("SQUARECLOUD_API_KEY"),
	rest.WithLogger(slog.Default()),
	rest.WithHTTPClient(&http.Client{Timeout: 10 * time.Second}),
)

模块

rest.Rest 按资源领域内嵌了一个接口，外加本页记录的用户和服务方法：

接口	覆盖范围	文档
`Applications`	管理、上传、文件、环境变量、snapshot、部署、网络、实时流	管理应用
`Databases`	创建、管理、凭据和 snapshot	数据库
`Workspaces`	创建、成员、共享应用	Workspaces

获取已认证用户

api.SelfUser() 返回一个包含账户详情和当前套餐的 squarecloud.User。

user, err := api.SelfUser()
if err != nil {
	panic(err)
}

fmt.Println(user.ID)       // "abcdef0123456789abcdef01"
fmt.Println(user.Name)     // "John Doe"
fmt.Println(user.Email)    // "john@example.com"
fmt.Println(user.Locale)   // "en-US"
fmt.Println(user.Plan.Name)             // e.g. "standard"
fmt.Println(user.Plan.Duration)         // plan duration, e.g. "monthly"
fmt.Println(user.Plan.Memory.Limit)     // MB
fmt.Println(user.Plan.Memory.Available) // MB
fmt.Println(user.Plan.Memory.Used)      // MB
fmt.Println(user.CreatedAt)

字段	类型	说明
`ID`	`string`	用户 ID（24 位十六进制字符）
`Name`	`string`	显示名称
`Email`	`string`	账户邮箱
`Locale`	`string`	首选语言环境，例如 `"en-US"`
`Plan`	`squarecloud.UserPlan`	`Name`、`Memory{Limit, Available, Used}`（MB）和 `Duration`
`CreatedAt`	`string`	账户创建日期

列出你的应用和数据库

api.GetApplications() 和 api.GetDatabases() 通过 /users/me endpoint 列出你拥有的一切，返回精简的 squarecloud.UserApplication / squarecloud.UserDatabase 描述符：

apps, err := api.GetApplications()
if err != nil {
	panic(err)
}
for _, app := range apps {
	fmt.Printf("%s (%s) — %dMB\n", app.Name, app.ID, app.RAM)
}

dbs, err := api.GetDatabases()
if err != nil {
	panic(err)
}
for _, db := range dbs {
	fmt.Printf("%s (%s)\n", db.Name, db.ID)
}

要获取单个资源的完整记录，请使用 GetApplication / GetDatabase —— 参见管理应用和数据库。

列出 snapshot 历史（账户级）

api.UserSnapshots(scope) 返回你在给定领域拥有的所有 snapshot：

appSnapshots, err := api.UserSnapshots(squarecloud.SnapshotScopeApplications)
if err != nil {
	panic(err)
}

dbSnapshots, err := api.UserSnapshots(squarecloud.SnapshotScopeDatabases)
if err != nil {
	panic(err)
}

关于 snapshot 载荷的详情，请参阅 Snapshots。

平台状态

api.ServiceStatus() 暴露聚合后的平台健康状况（与公开状态页展示的数据相同）。

status, err := api.ServiceStatus()
if err != nil {
	panic(err)
}

fmt.Println(status.Status)  // "ok" | "degraded" | "down"
fmt.Println(status.Message) // human-readable summary

与大多数 v2 endpoint 不同，此路由不会将其载荷包裹在标准的 { status, code, response } 信封中 —— 它直接以 { status, message } 响应。

请求选项

每个方法都接受末尾的 ...rest.RequestOpt，用于自定义单个请求：

选项	说明
`rest.WithContext(ctx)`	附加一个 `context.Context`，用于取消或设置截止时间
`rest.WithQueryParam(key, value)`	追加一个查询参数
`rest.WithHeader(key, value)`	设置一个请求头
`rest.WithToken(token)`	仅为本次请求覆盖认证 token

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

user, err := api.SelfUser(rest.WithContext(ctx))
if err != nil {
	panic(err)
}

错误处理

任何非 2xx 响应都会以 *rest.APIError 返回，暴露 StatusCode、Code 和 Message。使用惯用的 errors.As 解包：

app, err := api.GetApplication("invalid-id")
if err != nil {
	var apiErr *rest.APIError
	if errors.As(err, &apiErr) {
		fmt.Println(apiErr.StatusCode) // e.g. 404
		fmt.Println(apiErr.Code)       // e.g. "APP_NOT_FOUND"
		fmt.Println(apiErr.Message)
	}
	return
}

两个辅助函数简化了常见检查：

rest.ErrorCode(err) string —— 返回 API 错误代码（当错误不是 *rest.APIError 时返回 ""）
rest.IsRateLimit(err) bool —— 报告该错误是否属于任一速率限制代码（KEEP_CALM、RATE_LIMIT、RATE_LIMIT_EXCEEDED、RATELIMIT、DELAY_NOW）

if err != nil {
	if rest.IsRateLimit(err) {
		time.Sleep(5 * time.Second)
		// retry...
	}

	switch rest.ErrorCode(err) {
	case "APP_NOT_FOUND":
		fmt.Println("application does not exist")
	case "ACCESS_DENIED":
		fmt.Println("invalid API key")
	}
}

这些错误代码与 @squarecloud/api-types 使用的相同 —— 参见 JS SDK 参考中的完整代码表。

服务

Runtimes

平台

故障排除

CLI

SDKs

Changelog

要求

安装

实例化客户端

客户端配置（`ConfigOpt`）

模块

获取已认证用户

列出你的应用和数据库

列出 snapshot 历史（账户级）

平台状态

请求选项

错误处理

​要求

​安装

​实例化客户端

​客户端配置（ConfigOpt）

​模块

​获取已认证用户

​列出你的应用和数据库

​列出 snapshot 历史（账户级）

​平台状态

​请求选项

​错误处理

要求

安装

实例化客户端

客户端配置（`ConfigOpt`）

模块

获取已认证用户

列出你的应用和数据库

列出 snapshot 历史（账户级）

平台状态

请求选项

错误处理