Docs
文档目录

GraphQL

这是什么 / 何时用

Graphql 服务允许开发者使用标准 GraphQL query(只读查询)与 mutation(数据变更)语句访问平台数据面资源(如 Account、Users、Teams、TablesDB/Databases、Storage、Functions 等),其底层权限校验、行级安全(RLS)与配额限流体系同 REST 接口完全一致。

在前端聚合页面或复杂 BFF(Backend For Frontend)场景中(如演示项目 enterprise-ai-hub-210 同时需要读取当前登录账号信息、所属团队列表以及工单表 customer_tickets 的摘要数据),使用 GraphQL 可在一次 HTTP 请求中按需裁剪返回字段并组合多个查询,减少多轮往返开销与冗余字段传输。

前置

使用骨架

  1. 初始化客户端与 Graphql 服务:构造 Client 并实例化 new Graphql(client)。

  2. 执行只读查询(graphql.query):传入包含 query(GraphQL 查询字符串)及可选 variables(参数化变量对象)、operationName 的 JSON 载荷,从返回对象的 data 字段读取按需投影的结果。

  3. 执行数据变更(graphql.mutation):传入 mutation 变更语句与 variables(如创建行、更新偏好设置、创建团队等),确保所有动态用户输入均通过 $variable 变量绑定传入,切勿直接拼接 GraphQL 字符串。

  4. 校验业务级 errors 数组:GraphQL 规范下,即使部分或全部字段解析失败,HTTP 状态码通常仍为 200;调用方必须在拿到响应后优先检查 response.errors 是否非空。

关键参数与返回

方法与请求载荷

SDK 方法(Node / Web / Java / Python)Go 方法REST 端点请求参数(query 载荷对象)说明
query({ query })Query(query)POST /v1/graphql{ query: string, variables?: object, operationName?: string }执行 GraphQL 只读查询或变更请求。
mutation({ query })Mutation(query)POST /v1/graphql/mutation{ query: string, variables?: object, operationName?: string }专用于执行 GraphQL mutation 变更操作的语义化入口。

请求体字段明细

字段类型必填约束 / 默认值说明
querystring是非空 GraphQL 文档串标准 GraphQL query 或 mutation 语句,支持片段(Fragment)与变量声明。
variablesobject否默认 {}变量键值映射表,对应 GraphQL 语句中声明的 $varName 参数。
operationNamestring否字符串当 query 文档内包含多个命名操作时,指定本次执行的操作名。

返回结构(GraphQL 标准响应包络)

字段类型说明
dataobject | null按查询 Selection Set 投影返回的业务数据对象;若顶层执行失败则为 null。
errorsobject[](可选)执行或语法校验错误列表。每项含 message(错误描述)、locations([{ line, column }])、path(出错字段路径)及可选 extensions。

错误与边界

SDK 类别差异

SDK 类别支持范围鉴权方式典型场景
Server SDK(Node.js / Java / Python / Go)query、mutation 全量项目 API Key(按实际访问资源校验 scope)后端 BFF 聚合查询、跨模块批量数据组装
Client / Web SDK(Web)query、mutation 全量用户 Session / JWT(受 RLS 行级权限约束)前端单页应用一次请求拉取用户信息与业务列表
Console SDK(Node.js / Java / Python / Go)query、mutation 全量管理面 Session / 短期 JWT管理后台自定义聚合查询

各语言调用示例

客户端与服务端均可用;Web 页签走用户 Session,受数据面权限约束。

import { Client, Graphql, AgentbaseException } from 'agentbase-node-sdk';

const client = new Client()
    .setEndpoint(process.env.APPBASE_ENDPOINT ?? 'https://appbuild-sit.oceanbase.com/v1')
    .setProject(process.env.APPBASE_PROJECT_ID ?? 'enterprise-ai-hub-210')
    .setKey(process.env.APPBASE_API_KEY!);

const graphql = new Graphql(client);

try {
    // 1. 执行只读查询(带参数化 variables)
    const queryRes: any = await graphql.query({
        query: {
            query: `query GetLocaleAndDatabases {
                localeGet { countryCode country currency }
                tablesDBList { total databases { _id name } }
            }`,
            variables: {},
        },
    });
    if (queryRes.errors?.length) {
        console.error('GraphQL 业务错误:', queryRes.errors);
    } else {
        console.log('查询结果:', queryRes.data);
    }

    // 2. 执行变更(mutation)
    const mutationRes: any = await graphql.mutation({
        query: {
            query: `mutation CreateSupportTeam($teamId: String!, $name: String!) {
                teamsCreate(teamId: $teamId, name: $name) { _id name total }
            }`,
            variables: {
                teamId: 'team_tier2_support',
                name: '二线技术支持专家组',
            },
        },
    });
    if (mutationRes.errors?.length) {
        console.error('GraphQL 变更错误:', mutationRes.errors);
    }
} catch (err) {
    if (err instanceof AgentbaseException) {
        console.error(`HTTP 异常 [${err.code} ${err.type}]: ${err.message}`);
    }
    throw err;
}

示例指引