GraphQL 端点参考

数据墙DBW 根据实体配置自动生成 GraphQL 架构，提供查询和变更能力。本文档完整描述 GraphQL 端点的访问方式、请求格式和架构生成规则。

端点

POST {host}/{graphql-path}

组成部分	说明	默认值
host	服务主机地址和端口	localhost:5000
graphql-path	GraphQL 端点路径	/graphql（通过 runtime.graphql.path 配置）

请求格式

所有 GraphQL 请求通过 HTTP POST 方法发送，使用 JSON 请求体：

POST /graphql
Content-Type: application/json

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

使用变量

{
  "query": "query GetBook($id: Int!) { book_by_pk(id: $id) { id title } }",
  "variables": { "id": 1 }
}

请求体字段	类型	必需	说明
query	string	是	GraphQL 查询或变更语句
variables	object	否	查询变量，键值对形式
operationName	string	否	当 query 包含多个操作时指定要执行的操作名

响应格式

成功

{
  "data": {
    "books": {
      "items": [
        { "id": 1, "title": "示例" }
      ]
    }
  }
}

所有查询结果嵌套在 data.{实体名}.items 中，分页相关字段 hasNextPage 和 endCursor 始终出现。

错误

{
  "errors": [
    {
      "message": "Could not find item with the given key.",
      "locations": [{ "line": 1, "column": 3 }],
      "path": ["book_by_pk"]
    }
  ]
}

错误字段	说明
message	人类可读的错误描述
locations	错误在查询中的行号和列号
path	错误在响应数据中的路径

部分成功

当多个操作中出现部分失败时，data 和 errors 可能同时存在：

{
  "data": { "book_by_pk": null, "author_by_pk": { "name": "张三" } },
  "errors": [{ "message": "Could not find item with the given key." }]
}

自动生成的架构类型

每个实体在 GraphQL 架构中自动生成以下类型和操作：

查询（Query）

类型	命名规则	示例
列表查询	{entity-plural}	books
按主键查询	{entity-singular}_by_pk	book_by_pk

单数/复数命名：

• 默认基于实体名自动推断。
• 可通过 graphql.type.singular 和 graphql.type.plural 自定义。

变更（Mutation）

类型	命名规则	示例
创建	create{Entity}	createBook
更新	update{Entity}	updateBook
删除	delete{Entity}	deleteBook

存储过程

存储过程在 GraphQL 中自动添加 execute 前缀：

实体名	GraphQL 操作名
GetBookById	executeGetBookById
SearchProducts	executeSearchProducts

存储过程的挂载位置由 graphql.operation 控制：

值	架构位置
"query"	出现在 Query 类型下
"mutation"（默认）	出现在 Mutation 类型下

架构内省

GraphQL 端点默认支持内省（Introspection），客户端可以查询 __schema 和 __type 来发现完整架构。

控制

{
  "runtime": {
    "graphql": {
      "allow-introspection": true
    }
  }
}

值	说明
true（默认）	允许内省查询
false	禁止内省查询，生产环境推荐

查询深度限制

{
  "runtime": {
    "graphql": {
      "depth-limit": 5
    }
  }
}

值	说明
null（默认）	无深度限制
integer	查询的最大嵌套深度，超过则拒绝

实体级 GraphQL 配置

每个实体可以通过 graphql 配置独立控制其 GraphQL 暴露行为：

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

字段	说明	默认值
enabled	是否出现在 GraphQL 架构中	true
type.singular	单数类型名	实体名
type.plural	复数类型名	实体名复数形式
operation	存储过程挂载位置	mutation

全局 GraphQL 配置

{
  "runtime": {
    "graphql": {
      "enabled": true,
      "path": "/graphql",
      "allow-introspection": true,
      "depth-limit": null,
      "multiple-mutations": {
        "create": { "enabled": false }
      }
    }
  }
}

字段	说明	默认值
enabled	全局启用/禁用 GraphQL	true
path	端点路径	/graphql
allow-introspection	允许内省	true
depth-limit	查询最大深度	null
multiple-mutations.create.enabled	多重创建	false

下一步

• GraphQL 查询 — 查询语法和参数完整参考。
• GraphQL 变更 — 创建、更新和删除操作参考。
• GraphQL 聚合 — 聚合函数和分组查询。