GraphQL API

GraphQL API 是数据墙DBW 提供的另一种数据访问方式，与 REST API 共享同一份实体配置和权限模型。引擎会根据实体配置自动生成 GraphQL 架构，为每个实体提供查询和变更能力。

端点

GraphQL 端点统一托管在 /graphql，所有请求通过 POST 方法发送，查询语句放在请求体的 query 字段中：

POST /graphql
Content-Type: application/json

{ "query": "{ books { items { id title } } }" }

GraphQL 支持变量分离，可以将查询结构与参数值分别传递。

查询类型

每个实体在 GraphQL 架构中自动生成两种查询入口：

查询	说明	示例
{entities}	返回记录列表	books { items { ... } }
{entity}_by_pk	按主键返回单条记录	book_by_pk(id: 1)

变更操作

GraphQL 支持 create、update、delete 三种变更操作：

mutation {
  createBook(item: { title: "新书" }) { id title }
  updateBook(id: 1, item: { title: "更新" }) { id title }
  deleteBook(id: 1) { id }
}

存储过程实体会自动添加 execute 前缀，例如 executeGetBookById。

查询能力

GraphQL 查询支持与 REST 同等的数据操作能力，但语法风格不同：

• filter：按条件筛选，使用嵌套对象格式。例如 filter: { title: { contains: "基础" } } 或组合逻辑 filter: { or: [{ year: { ge: 2000 } }, { title: { eq: "Dune" } }] }。
• orderBy：按字段排序，支持多字段和升降序。例如 orderBy: { year: DESC, title: ASC }。
• first / after：游标分页。使用 first: -1 可请求配置的最大分页大小。

IMPORTANT

GraphQL 变更操作需要数据库连接池支持。如果连接字符串设置了 Pooling=False 或 MultipleActiveResultSets=False，变更会失败。SQL Server 需确保 Pooling=True 和 MultipleActiveResultSets=True。

关系查询

实体之间配置的关系会在 GraphQL 架构中自动体现为嵌套字段。客户端可以在一次请求中获取关联数据：

{
  books {
    items {
      title
      authors { items { name } }
    }
  }
}

聚合查询

对于 SQL 系列数据库，GraphQL 支持 count、sum、avg、min、max 等聚合操作，可以在服务端完成统计计算。

分页

GraphQL 使用游标分页，响应中返回 hasNextPage 和 endCursor 字段。客户端将 endCursor 传递给下一次请求的 after 参数即可翻页。

多重变更

GraphQL 支持在一个 mutation 中执行多个变更操作，引擎会将它们按顺序执行：

mutation {
  createBook(item: { title: "新书" }) { id title }
  updateBook(id: 1, item: { title: "更新" }) { id title }
}

架构内省

默认情况下，GraphQL 端点支持架构内省（Introspection），允许客户端自动发现可用的查询、变更和字段类型。生产环境中可通过 runtime.graphql.allow-introspection 关闭。