Docs
文档目录

Server SDK(Go)

示例中的 <APPBASE_ENDPOINT_WITH_V1>、<APPBASE_CONSOLE_ORIGIN> 和 <APPBASE_CONSOLE_HOST> 均需按实际使用位置替换为目标环境信息;先确认环境再运行。

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 (
    "errors"
    "net/http"
    "agentbase-go-sdk/agentbase"
)

cl := agentbase.NewClient(
    agentbase.WithEndpoint("<APPBASE_ENDPOINT_WITH_V1>"),   // SIT: https://appbuild-sit.oceanbase.com/v1
    agentbase.WithProject("<PROJECT_ID>"),
    agentbase.WithKey("<SERVER_API_KEY>"),                          // 最小 scope 的项目 API Key
)
cl.Client.CheckRedirect = func(_ *http.Request, _ []*http.Request) error {
	return errors.New("refuse redirects")
}

With* 选项还有 WithTimeout、WithSelfSigned、WithJWT、WithSession、WithOrganization(后三者仅用于 endpoint 明确要求用户身份的受控流程)。

上述 Go 2.12 客户端在初始化后禁止自动跳转。WithTimeout 会替换 HTTP 客户端,因此必须在所有初始化选项执行后设置 CheckRedirect;之后若替换 cl.Client,需要重新设置并验证该策略。

调用约定

必选参数按位置传,可选参数用挂在 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):

package main

import (
	"net/http"
	"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(os.Getenv("APPBASE_ENDPOINT")),
		agentbase.WithProject(os.Getenv("APPBASE_PROJECT_ID")),
		agentbase.WithKey(os.Getenv("APPBASE_API_KEY")),
		agentbase.WithTimeout(30*time.Second),
	)
	cl.Client.CheckRedirect = func(_ *http.Request, _ []*http.Request) error {
		return errors.New("refuse redirects")
	}
	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())
			}
			return
		}
		if len(page.Rows) == 0 {
			break
		}
		for _, row := range page.Rows {
			var t TicketPayload
			if err := row.Decode(&t); err != nil {
				fmt.Println("Decode row failed:", err)
				return
			}
			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("Upload failed:", err)
		return
	}
	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()(原始响应体)
}

示例指引