Server SDK(Go)
Go 后端 / 受控管理脚本以项目 API Key 调用 Server SDK(module agentbase-go-sdk,方法名 PascalCase、service 包小写连排)。API Key 请求跳过行级权限检查(hasRole),只存受控服务端。Node / Java / Python 面见同目录 nodejs.md / java.md / python.md。
制品与安装
要求 go 1.22.5+,SDK 零第三方依赖。不发布到公共 Go module proxy:从 agentbase-sdks release ZIP 解压后,在应用模块 go.mod 中以 replace 指向本地目录(require 版本固定写 v0.0.0),或直接复制源码树 / go mod vendor。下载、校验与 replace 完整命令见 ../examples/go.md「获取与安装」;Go 面自 agentbase-sdks v2.7.0 起交付(2.6.0 无该语言面)。
初始化
facade 包 agentbase-go-sdk/agentbase 提供统一入口:
import "agentbase-go-sdk/agentbase"
cl := agentbase.NewClient(
agentbase.WithEndpoint("https://appbuild.oceanbase.com/v1"), // SIT: https://appbuild-sit.oceanbase.com/v1
agentbase.WithProject("<PROJECT_ID>"),
agentbase.WithKey("<SERVER_API_KEY>"), // 最小 scope 的项目 API Key
)With* 选项还有 WithTimeout、WithSelfSigned、WithJWT、WithSession、WithOrganization(后三者仅用于 endpoint 明确要求用户身份的受控流程)。
调用约定
必选参数按位置传,可选参数用挂在 service 上的 With* 方法(命名规则 With<方法名><参数名>,全量以模块源码为准);查询用 agentbase-go-sdk/query、ID 用 agentbase-go-sdk/id:
tables := agentbase.NewTablesDB(cl)
_, err := tables.CreateTable("app-db", "tasks", "Tasks",
tables.WithCreateTableRowSecurity(true),
tables.WithCreateTableEnabled(true),
tables.WithCreateTableColumns([]models.DatabaseColumnDefinition{
{Key: "title", Type: "string", Size: 256, Required: true},
}),
tables.WithCreateTableIndexes([]models.DatabaseIndexDefinition{
{Key: "idx_title", Type: "unique", Attributes: []string{"title"}},
}),
)行/文档等列表与详情模型的自定义业务字段不进 struct,经 Decode() 取原始 JSON:
row, err := tables.GetRow("app-db", "tasks", "<rowId>")
payload := map[string]interface{}{}
_ = row.Decode(&payload)客户端配置选项、游标分页与文件上传实战
agentbase.NewClient 采用函数式选项(Functional Options)模式构造客户端,所有服务通过 agentbase.New<Service>(cl) 共享该客户端实例:
NewClient 选项函数 | 注入的 HTTP 请求头 / 行为 | 适用场景与安全约束 |
|---|---|---|
WithEndpoint(url) | 请求基准地址 | 必填,如 https://appbuild-sit.oceanbase.com/v1 或 https://appbuild.oceanbase.com/v1。 |
WithProject(projectId) | X-Appwrite-Project | 必填,目标项目 ID(如演示项目 enterprise-ai-hub-210)。 |
WithKey(apiKey) | X-Appwrite-Key | 服务端主用鉴权方式,跳过 RLS(hasRole),按最小 scope 授权。 |
WithJWT(jwt) | X-Appwrite-JWT | 代表特定登录用户调用数据面接口(受该用户 RLS 行级权限约束)。 |
WithSession(session) | X-Appwrite-Session | 服务端转发浏览器登录会话 Cookie 时装载。 |
WithOrganization(orgId) | X-Appwrite-Organization | 组织级查询与治理接口指定组织上下文(如 69c6d1aa00062e6bb60)。 |
WithLocale(locale) | X-Appwrite-Locale | 指定国际化返回语种(如 zh-CN)。 |
WithTimeout(duration) | HTTP 客户端超时 | 默认 10 秒;大文件上传或长耗时 AI 调用建议设为 30 * time.Second 或更高。 |
WithSelfSigned(true) | TLS 证书校验开关 | 仅用于自签名证书的私有测试实例,生产环境严禁开启。 |
游标分页、自定义结构体解码与文件上传完整示例
以下示例展示在 Go 后端中遍历业务库 enterprise_biz_db 的 customer_tickets 工单表(使用 query.CursorAfter 游标分页与 row.Decode 解码业务字段)、上传文件(file.NewInputFile)以及对 429/5xx 错误做退避重试:
package main
import (
"errors"
"fmt"
"os"
"time"
"agentbase-go-sdk/agentbase"
agentbaseclient "agentbase-go-sdk/client"
"agentbase-go-sdk/file"
"agentbase-go-sdk/id"
"agentbase-go-sdk/query"
)
type TicketPayload struct {
ID string `json:"$id"`
TicketNo string `json:"ticketNo"`
Title string `json:"title"`
Status string `json:"status"`
Priority string `json:"priority"`
}
func main() {
cl := agentbase.NewClient(
agentbase.WithEndpoint("https://appbuild-sit.oceanbase.com/v1"),
agentbase.WithProject("enterprise-ai-hub-210"),
agentbase.WithKey(os.Getenv("APPBASE_API_KEY")),
agentbase.WithTimeout(30*time.Second),
)
tables := agentbase.NewTablesDB(cl)
storage := agentbase.NewStorage(cl)
// 1. 游标分页拉取未完结工单并解码至强类型结构体
cursor := ""
pageSize := 50
for {
queries := []string{
query.Equal("status", []interface{}{"open", "in_progress"}),
query.OrderAsc("$id"),
query.Limit(pageSize),
}
if cursor != "" {
queries = append(queries, query.CursorAfter(cursor))
}
page, err := tables.ListRows("enterprise_biz_db", "customer_tickets",
tables.WithListRowsQueries(queries),
tables.WithListRowsTotal(false), // 关闭 count(*) 提升大表分页性能
)
if err != nil {
var aerr *agentbaseclient.AgentbaseError
if errors.As(err, &aerr) {
fmt.Printf("HTTP %d: %s\n", aerr.GetStatusCode(), aerr.GetMessage())
}
break
}
if len(page.Rows) == 0 {
break
}
for _, row := range page.Rows {
var t TicketPayload
_ = row.Decode(&t)
fmt.Printf("Ticket %s [%s]: %s\n", t.TicketNo, t.Priority, t.Title)
}
if len(page.Rows) < pageSize {
break
}
cursor = page.Rows[len(page.Rows)-1].Id
}
// 2. 上传本地文件到知识库文档桶 kb_enterprise_docs
inputFile := file.NewInputFile("/tmp/智能客服SOP标准作业手册.md", "智能客服SOP标准作业手册.md")
uploaded, err := storage.CreateFile("kb_enterprise_docs", id.Unique(), inputFile)
if err == nil {
fmt.Println("Uploaded file ID:", uploaded.Id)
}
}与 Console SDK(agentbase-console-go-sdk)并用
Go 交付包同时提供 Server SDK(agentbase-go-sdk)与 Console SDK(agentbase-console-go-sdk)。在同一个 Go module 中,可通过 go.mod 的两条 replace 指令同时引入两个模块,并用包别名(如 serverfacade "agentbase-go-sdk/agentbase" 与 consolefacade "agentbase-console-go-sdk/agentbase")区分项目数据面与管理控制面调用(详见 ../console-sdk/go.md)。
功能面导航
服务面与 Node 面同构(facade 全量构造器 NewTablesDB、NewStorage、NewUsers、NewMemory、NewKnowledgeBases、NewLlmGateway、NewAiGateway、NewObservability、NewModeration 等),全量映射见 nodejs.md「功能面导航」;各功能页:数据库、存储、函数、站点、用户、团队、消息、记忆、知识库、LLM Gateway、AI Gateway、可观测、审核、横切服务。
无 Sql 服务(SQL 走 HTTP 形态或 Console SDK,../databases/sql-proxy.md);无 Realtime(客户端能力)。
错误处理
错误统一为 *client.AgentbaseError(agentbase-go-sdk/client):
import (
"errors"
agentbaseclient "agentbase-go-sdk/client"
)
_, err := tables.GetRow("app-db", "tasks", "missing-row")
var aerr *agentbaseclient.AgentbaseError
if errors.As(err, &aerr) && aerr.GetStatusCode() == 404 {
// not found;另可用 GetMessage() / GetResponse()(原始响应体)
}示例指引
Go(Server / Console)完整调用写法:../examples/go.md