# Go SDK

使用 Go SDK 连接 Catalog Service，读取和管理目录、数据库、表、卷、文件等资源。本页使用带截止时间的 `context` 列出当前身份可见的目录。

## 安装

Go SDK 当前要求 Go 1.24.3 或更高版本。在已有 Go module 中添加依赖：

```bash
go get github.com/matrixorigin/moi-go-sdk@latest
```

该模块当前没有稳定的语义化发布标签。生产项目应保留 `go.mod` 和 `go.sum`，并在升级前检查解析到的版本和自己的集成测试。

## 配置客户端

向部署方获取 Catalog Service 地址和 SDK Key，并设置为环境变量：

```bash
export MOI_BASE_URL="https://<catalog-service-host>"
export MOI_API_KEY="<sdk-api-key>"
```

`MOI_BASE_URL` 必须包含协议和主机名。`RawClient` 会规范化地址，并在请求中发送 `moi-key`。不要将 Genesis 访问令牌、浏览器 Cookie 或数据库密码当作 Catalog Service 的 SDK Key。

## 列出可见目录

创建 `main.go`：

```go
package main

import (
	"context"
	"errors"
	"fmt"
	"log"
	"os"
	"time"

	sdk "github.com/matrixorigin/moi-go-sdk"
)

func requiredEnv(name string) string {
	value := os.Getenv(name)
	if value == "" {
		log.Fatalf("set %s before running this program", name)
	}
	return value
}

func main() {
	client, err := sdk.NewRawClient(
		requiredEnv("MOI_BASE_URL"),
		requiredEnv("MOI_API_KEY"),
	)
	if err != nil {
		log.Fatalf("create client: %v", err)
	}

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

	response, err := client.ListCatalogs(ctx)
	if err != nil {
		var apiErr *sdk.APIError
		var httpErr *sdk.HTTPError
		switch {
		case errors.As(err, &apiErr):
			log.Fatalf("MOI API error: code=%s request_id=%s", apiErr.Code, apiErr.RequestID)
		case errors.As(err, &httpErr):
			log.Fatalf("HTTP error: status=%d", httpErr.StatusCode)
		default:
			log.Fatalf("list catalogs: %v", err)
		}
	}

	for _, catalog := range response.List {
		fmt.Printf("%s (id=%d)\n", catalog.CatalogName, catalog.CatalogID)
	}
}
```

格式化并运行：

```bash
gofmt -w main.go
go run .
```

调用成功后会打印当前身份可见的目录。空列表不一定表示错误，也可能表示该身份尚未拥有可见目录。

## 选择客户端

包的模块路径是 `github.com/matrixorigin/moi-go-sdk`，示例使用 `sdk` 作为导入别名。`RawClient` 提供 Catalog Service 的资源调用；需要表权限角色、文件导入或 SQL 等组合操作时，可复用底层客户端创建 `SDKClient`：

```go
highLevelClient := sdk.NewSDKClient(client)
```

使用前确认目标能力属于 Go SDK；不要将 Product SDK 的客户端或示例混入此处。

## 处理错误

服务返回业务错误时，SDK 返回 `*sdk.APIError`，其中的 `Code` 和 `RequestID` 可用于定位请求。服务返回非成功 HTTP 状态时，SDK 返回 `*sdk.HTTPError`。网络错误和 `context` 超时会作为其他 Go `error` 返回。

将 `context` 传给每次调用，并为需要及时返回的操作设置截止时间。调用超时只表示客户端停止等待，不表示服务端操作一定没有继续执行。写操作超时后，先查询目标资源或任务状态，再决定是否重试。

## 下一步

- 使用 [Python SDK](python-sdk.md) 在 Python 应用中调用 Catalog Service。
- 使用 [Product SDK](product-sdk/index.md) 管理 MOI 产品资源。