自动生成 GraphQL API

数据墙DBW 会根据实体配置自动生成 GraphQL 架构，让客户端能够以声明方式精确获取所需数据。同一份实体模型可以同时驱动 REST 和 GraphQL，无需为不同协议编写重复配置。

端点

GraphQL 端点统一托管在：

https://{host}/graphql

所有请求都通过 POST 方法发送，查询语句放在请求体的 query 字段中。你也可以同时传递 variables 来分离查询结构与参数值。

查询与变更

每个实体在 GraphQL 架构中自动生成以实体名称命名的查询和变更入口：

类型	命名规则	示例
列表查询	{entities}	books { items { ... } }
单条查询	{entity}_by_pk	book_by_pk(id: 1010)
创建	create{Entity}	createBook(item: {...})
更新	update{Entity}	updateBook(id: 1, item: {...})
删除	delete{Entity}	deleteBook(id: 1)

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

关系查询

实体之间的关系会在 GraphQL 架构中自动体现。配置了一对多、多对一或多对多关系后，客户端可以在一次请求中获取关联数据：

{
  books {
    items {
      title
      authors {
        items { first_name last_name }
      }
    }
  }
}

无需手写 JOIN 语句或额外 API 调用，关系查询由引擎自动处理。

聚合查询

对于 SQL 系列数据库，GraphQL 端点支持聚合查询，可以直接在 API 层完成 count、sum、avg、min、max 等统计操作，而不需要将原始数据拉回客户端再计算。

查询参数

GraphQL 查询支持与 REST 同等的查询能力：

参数	用途
filter	按条件筛选记录
orderBy	定义排序规则
first	限制返回条数
after	分页游标

筛选支持嵌套逻辑（and、or）和多种运算符（eq、neq、lt、lte、gt、gte、contains、isNull 等）。

分页

GraphQL 响应使用游标分页，返回 hasNextPage 和 endCursor 字段：

{
  "data": {
    "books": {
      "items": [...],
      "hasNextPage": true,
      "endCursor": "eyJpZCI6NX0="
    }
  }
}

客户端通过将 endCursor 值传递给下一请求的 after 参数来实现翻页。

多重变更

GraphQL 支持在一次请求中组合多个变更操作。例如在一个 mutation 中同时创建两本书——引擎保证按顺序执行并返回各自结果。这让客户端减少网络往返次数。

架构命名自定义

你可以通过 graphql.type 配置项自定义 GraphQL 架构中的类型名称：

{
  "graphql": {
    "type": {
      "singular": "Book",
      "plural": "Books"
    }
  }
}

下一步

• 查看使用 GraphQL API 了解详细调用方式。
• 了解配置实体关系 掌握关系查询配置。