客户端¶

MOI SDK 的 Client 连接 Catalog Service。它的构造参数只有 Base URL、API Key 和可选的 HTTP 配置，没有独立的 Workspace ID 参数；调用能看到和修改哪些资源，由 Key 所属身份及服务端权限决定。

因此，应用切换 Workspace 时不能只改页面状态。应取得对应 Workspace 可用的凭据，并为不同环境或身份维护明确分开的 Client。

RawClient 与 SDKClient¶

RawClient 是所有调用的基础，每个公开方法对应一个服务端能力。SDKClient 包装一个 RawClient，提供需要多个请求或客户端逻辑的辅助方法。

需求	选择
创建、查询或删除单个 Catalog / Database / Table 等资源	`RawClient`
需要完整控制请求类型、CallOption 和返回结构	`RawClient`
创建或复用表权限角色、导入本地文件、等待工作流作业	`SDKClient`
同一应用同时使用两层	保留 `RawClient`，并用它构造 `SDKClient`

Python：

import os
from moi import RawClient, SDKClient
from moi.options import with_timeout, with_user_agent

raw = RawClient(
    os.environ["MOI_BASE_URL"],
    os.environ["MOI_API_KEY"],
    with_timeout(60.0),
    with_user_agent("catalog-sync/1.0"),
)
client = SDKClient(raw)

catalogs = raw.list_catalogs()

Go：

raw, err := sdk.NewRawClient(
	os.Getenv("MOI_BASE_URL"),
	os.Getenv("MOI_API_KEY"),
	sdk.WithHTTPTimeout(60*time.Second),
	sdk.WithUserAgent("catalog-sync/1.0"),
)
if err != nil {
	log.Fatal(err)
}
client := sdk.NewSDKClient(raw)

catalogs, err := raw.ListCatalogs(ctx)

不要把示例中的超时当作服务承诺。非流式 HTTP 请求默认超时为 30 秒；应按文件大小、操作耗时和调用方截止时间调整。

Client 生命周期¶

在进程启动时创建 Client 并复用连接池。Go 的 RawClient 和 SDKClient 可在多个 goroutine 中并发使用。Python RawClient 默认持有一个 requests.Session；可以复用 Client，但若应用采用复杂的多线程共享方式，应按 requests.Session 的并发约束设计，或为独立执行单元提供各自的 Session。

推荐按下列边界拆分 Client：

边界	做法
开发、测试、生产环境	每个 Base URL 与 Key 对创建独立 Client，禁止自动跨环境回退
不同 Workspace / 租户	使用各自授权的 Key 和 Client，不在全局实例上改写身份
Key 轮换	创建新 Client 并通过健康检查后，再停止旧 Client
特殊身份调用	使用 `with_special_user` / `WithSpecialUser` 返回的新实例

自定义 HTTP Client 适合统一代理、TLS、连接池或观测配置。Python 使用 with_http_client(requests.Session)；Go 使用 WithHTTPClient(*http.Client)。传入后，超时和 Transport 等生命周期由应用负责。

单次调用的控制¶

ClientOption 在构造时影响所有请求；CallOption 只影响一次调用。

配置	Python	Go
总体 HTTP 超时	`with_timeout`	`WithHTTPTimeout`
自定义 HTTP Client	`with_http_client`	`WithHTTPClient`
User-Agent	`with_user_agent`	`WithUserAgent`
默认请求头	`with_default_header(s)`	`WithDefaultHeader(s)`
请求 ID	`with_request_id`	`WithRequestID`
单次请求头	`with_header(s)`	`WithHeader(s)`
查询参数	`with_query_param` / `with_query`	`WithQueryParam` / `WithQuery`

Go 的每个方法都接收 context.Context。为外部请求设置截止时间，并在上游取消后让 SDK 调用尽快结束：

ctx, cancel := context.WithTimeout(parentCtx, 20*time.Second)
defer cancel()

catalogs, err := raw.ListCatalogs(ctx, sdk.WithRequestID(requestID))

Python 没有逐调用 context；使用 Client 超时、流读取超时和应用层取消机制。

Workspace 的用户与角色配置见用户权限。具体资源方法继续阅读 SDK 各主题章节。