选择 API 类型

数据墙DBW 基于同一份实体配置同时提供 REST 和 GraphQL 两种 API。它们共享权限和字段规则，但在使用方式和适用场景上各有侧重。你不需要二选一——可以同时启用，也可以只开放其中一种。

REST vs GraphQL 对比

维度	REST	GraphQL
请求方式	标准 HTTP 方法（GET/POST/PUT/DELETE）	统一 POST /graphql，查询放在请求体中
数据获取	返回固定字段集合	由客户端声明要哪些字段
筛选排序	URL 查询参数（$filter、$orderby）	查询参数（filter、orderBy）
分页	nextLink 游标分页	endCursor 游标分页
关联查询	需要多次请求	单次请求嵌套查询
接口文档	自动生成 OpenAPI + Swagger	架构内省（Introspection）
学习成本	低，任何 HTTP 客户端可用	中等，需理解 GraphQL 语法

选择 REST 的情况

以下场景优先使用 REST：

• 前端和移动端：REST 接口简单直观，任何 HTTP 客户端都能直接调用，前端开发者学习成本为零。
• 低代码平台：大多数低代码平台通过 HTTP 连接器对接 REST API，支持导入 OpenAPI 规范自动生成数据源配置。
• 第三方集成：对外开放的 API 通常用 REST，调用方不需要理解 GraphQL 语法。
• 简单 CRUD：如果你的需求就是标准的增删改查 + 列表查询，REST 已经能完全满足。

选择 GraphQL 的情况

以下场景优先使用 GraphQL：

• 灵活字段选择：客户端需要按需取字段，避免传输不需要的数据。移动端带宽敏感的场景尤其受益。
• 关联数据查询：需要在一次请求中获取实体及其关联数据（如书籍和作者），GraphQL 的关系查询省去了多次 REST 调用的开销。
• 聚合统计：需要在服务端完成 count、sum、avg 等统计计算。注意聚合仅 SQL Server 支持。
• 前端驱动的 API：前端团队希望自行决定数据的形状，减少"为了一个字段要多加一个接口"的沟通成本。
• 多重变更：需要在一个请求中执行多个变更操作，减少网络往返。

同时启用

你可以同时启用 REST 和 GraphQL，这是数据墙DBW 的默认行为。同时启用的好处是：

• 不同消费方按自己的偏好选择协议——前端用 REST，数据分析用 GraphQL。
• 同一份权限和字段规则对两种协议生效，不会出现安全策略不一致。
• 配置一次，两种接口自动生成。

如果只想启用其中一种，可以在配置中关闭：

{
  "runtime": {
    "rest": { "enabled": false },
    "graphql": { "enabled": true }
  }
}

选择建议

你的情况	推荐
对外提供标准 HTTP API	REST
前端/移动端调用	REST
接入低代码平台	REST
需要服务端聚合统计	GraphQL（SQL Server）
复杂关联数据、灵活字段选择	GraphQL
不确定，都想试试	两者都开，各取所需

下一步

• 阅读使用 REST API 了解接口详情。
• 阅读使用 GraphQL API 了解接口详情。