通过 HTTP 提供服务

HTTP 是使用 GraphQL 时最常见的客户端-服务器协议选择，因为它无处不在。以下是一些关于设置 GraphQL 服务器以通过 HTTP 运行的指南。

Web 请求管道#

大多数现代 Web 框架使用管道模型，其中请求通过中间件（也称为过滤器/插件）堆栈传递。当请求流经管道时，可以检查、转换、修改或终止它以进行响应。GraphQL 应该放在所有身份验证中间件之后，以便您可以访问与 HTTP 端点处理程序中相同的会话和用户信息。

URI、路由#

HTTP 通常与 REST 相关联，REST 使用“资源”作为其核心概念。相反，GraphQL 的概念模型是实体图。因此，GraphQL 中的实体不是通过 URL 标识的。相反，GraphQL 服务器在一个 URL/端点上运行，通常是 /graphql，并且给定服务的 GraphQL 请求都应该指向此端点。

HTTP 方法、标头和正文#

您的 GraphQL HTTP 服务器应该处理 HTTP GET 和 POST 方法。

GET 请求#

当收到 HTTP GET 请求时，GraphQL 查询应该在“query”查询字符串中指定。例如，如果我们要执行以下 GraphQL 查询

{
  me {
    name
  }
}

此请求可以通过以下 HTTP GET 发送

http://myapi/graphql?query={me{name}}

查询变量可以作为 JSON 编码的字符串发送到名为 variables 的附加查询参数中。如果查询包含多个命名操作，则可以使用 operationName 查询参数来控制应该执行哪个操作。

POST 请求#

标准 GraphQL POST 请求应该使用 application/json 内容类型，并包含以下形式的 JSON 编码正文

{
  "query": "...",
  "operationName": "...",
  "variables": { "myVariable": "someValue", ... }
}

operationName 和 variables 是可选字段。operationName 仅在查询中存在多个操作时才需要。

响应#

无论使用哪种方法发送查询和变量，响应都应以 JSON 格式返回到请求主体中。如规范中所述，查询可能会导致一些数据和一些错误，这些数据和错误应以以下形式的 JSON 对象返回

{
  "data": { ... },
  "errors": [ ... ]
}

如果未返回任何错误，则响应中不应存在 "errors" 字段。如果未返回任何数据，根据 GraphQL 规范，只有在执行过程中未发生错误时才应包含 "data" 字段。

节点#

如果您使用的是 NodeJS，我们建议您查看 服务器实现列表。

草案传输规范#

一个详细的 HTTP 传输规范 正在开发中。虽然它尚未最终确定，但这些草案规范充当 GraphQL 客户端和库维护者的单一真相来源，详细说明了如何使用 HTTP 传输来公开和使用 GraphQL API。与语言规范不同，遵守不是强制性的，但大多数实现正在朝着这些标准发展，以最大限度地提高互操作性。