AppBase 云控制台
浏览全部文档 · 31/37
已支持已进入 main

GraphQL Query 与 Mutation

SDK、REST、GraphQL 与错误处理

版本验证信息发布状态与验证 Commit
发布状态
已进入 main
后端验证 Commit
0363062a1c7ea08741975bb5ba0c3361663c9353

功能简介

GraphQL 端点提供 Query 与 Mutation，覆盖账号、数据、存储、函数、消息等主要服务，但不承诺与 REST 全量同构。GraphQL Subscription 未实现；实时事件必须使用 Realtime WebSocket。

当前支持范围

  • GraphQL（SUPPORTED）：提供 GraphQL Query 与 Mutation，覆盖账号、数据、存储、函数和消息等主要服务；不宣称与 REST 全量同构。

适用场景

  • 一次请求组合多个已支持字段。
  • 使用类型化 Query/Mutation 访问主要服务。
  • 在 REST 与 GraphQL 之间按能力覆盖选择接口。

前置条件

  • Project 已启用 GraphQL API。
  • 查询字段存在于当前服务端 Schema。
  • 请求身份拥有底层 Resolver 所需 Scope/Permission。

Console 操作路径

Console 不提供统一 GraphQL Subscription 页面。GraphQL 调用通过 SDK 或 /v1/graphql；实时事件转到 Realtime。

SDK 示例

SDK · TypeScript
import { Client } from 'appbase-web-sdk';

const client = new Client()
  .setEndpoint('https://<APPBASE_HOST>/v1')
  .setProject('<PROJECT_ID>');
import { Graphql } from 'appbase-web-sdk';
const graphql = new Graphql(client);

const result = await graphql.query({
  query: {
    query: `query {
      accountGet { _id name email }
    }`
  }
});

REST 示例

REST · Bash
curl 'https://<APPBASE_HOST>/v1/graphql' \
  -X POST \
  -H 'X-Appwrite-Project: <PROJECT_ID>' \
  -H 'X-Appwrite-JWT: <USER_JWT>' \
  -H 'Content-Type: application/json' \
  --data '{"query":"query { accountGet { _id name email } }"}'

权限模型

GraphQL 请求先解析身份，再由具体 Resolver/Action 执行 Scope 与资源 Permission。单个 Query 中的多个字段不会共享超出各字段定义的权限。

常见错误

现象处理建议
GraphQL validation error核对当前服务端 Schema、字段名和变量类型。
字段返回 access forbidden检查该字段背后的 Scope 与资源 Permission。
找不到 Subscription operation这是明确不支持项；改用 Realtime SDK。
请求过大或复杂度受限拆分 Query，并遵循实例限流和请求大小限制。

当前限制

  • 不与 REST 全量同构。
  • 不支持 GraphQL Subscription。
  • AppBase 新增能力是否进入 GraphQL 必须逐字段核验，不能从 REST 路由推断。

Appwrite 兼容说明

Query/Mutation 接入方式保持兼容；能力范围以 AppBase GraphQL Schema 与测试为准。

AppBase 增强说明

AppBase 继续保留 GraphQL 入口，但新增能力优先以已核验 REST/SDK 页面为准并明确覆盖差异。

发布状态和验证 Commit

origin/main 已核验。验证 Commit：0363062a1c7ea08741975bb5ba0c3361663c9353。

权威来源文件列表

  • backend-candidate:app/controllers/api/graphql.php
  • backend-candidate:docs/references/graphql/
  • backend-candidate:src/Appwrite/GraphQL/
  • backend-candidate:tests/e2e/Services/GraphQL/

Appwrite taxonomy 仅作信息架构参考：https://appwrite.io/docs/apis/graphql。上游页面不是 AppBase 实现证据。

继续阅读