Go¶

下面的程序使用 Go SDK 连接 MOI Catalog Service，并列出当前身份可见的 Catalog。它使用带超时的 context，只执行读取操作，适合作为连接与鉴权检查。

创建模块¶

SDK 的 go.mod 当前声明 Go 1.24.3。确认本地工具链兼容后，创建一个新模块并添加依赖：

mkdir moi-sdk-quickstart
cd moi-sdk-quickstart
go mod init example.com/moi-sdk-quickstart
go get github.com/matrixorigin/moi-go-sdk@latest

该 SDK 尚未发布带语义版本的 Go tag，因此 @latest 可能解析为基于 commit 的伪版本。生产项目应保留 go.mod 和 go.sum，并在升级前验证解析到的新 commit。

提供服务配置¶

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

这里的环境变量名是示例约定。Base URL 和 SDK Key 应由 MOI 部署或管理员提供；SDK 会通过 moi-key 请求头发送密钥。不要把 Genesis 模型 API Key、浏览器 Cookie 或数据库密码当作 Catalog Service 凭据，除非部署方明确说明它们可用于该服务。

编写并运行程序¶

将以下内容保存为 main.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"),
		sdk.WithHTTPTimeout(30*time.Second),
	)
	if err != nil {
		log.Fatalf("create MOI 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 message=%s",
				apiErr.Code, apiErr.RequestID, apiErr.Message,
			)
		case errors.As(err, &httpErr):
			log.Fatalf("HTTP error: status=%d", httpErr.StatusCode)
		default:
			log.Fatalf("list catalogs: %v", err)
		}
	}

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

格式化、编译并运行：

gofmt -w main.go
go run .

请求成功后会打印可见 Catalog 的数量和名称。返回空列表不一定是错误，也可能只是该身份还没有可见资源。

理解客户端和错误¶

包的模块路径是 github.com/matrixorigin/moi-go-sdk，包名则是 sdk，因此示例显式使用了 sdk 导入别名。

RawClient 提供类型化的资源方法。ListCatalogs 返回 *sdk.CatalogListResponse，无需手动解析服务端响应包络。需要文件导入、表权限角色或 SQL 执行等高级操作时，可以复用底层客户端：

highLevelClient := sdk.NewSDKClient(client)

服务返回非 2xx 状态时，SDK 返回 *sdk.HTTPError；HTTP 成功但响应包络包含业务错误码时，返回 *sdk.APIError。后者的 RequestID 应保留用于排查。网络错误和 context 超时则会作为其它 Go error 返回。

接入检查¶

NewRawClient 报错时，确认 Base URL 包含协议和主机名。末尾的 / 会被自动去除。
收到 401 或 403 时，检查 Key 类型、目标环境和资源权限，不要在日志中输出 Key。
应用应为每次调用传入可取消的 context；示例同时设置了 HTTP 客户端超时和调用级超时。
SDK 没有语义版本 tag 时，评审 go get -u 造成的伪版本变化，并在 CI 中运行自己的集成测试。
完整方法和结构体以官方 Go SDK 仓库中当前依赖版本的源码与 Go 文档为准。

完成首次调用后，可继续查看 SDK 数据主题了解资源范围。