通过 HTTP 提供服务

¥Serving over HTTP

由于 HTTP 的普遍性，它是使用 GraphQL 时最常见的客户端-服务器协议选择。以下是设置 GraphQL 服务器通过 HTTP 运行的一些指南。

¥HTTP is the most common choice for client-server protocol when using GraphQL because of its ubiquity. Here are some guidelines for setting up a GraphQL server to operate over HTTP.

网络请求管道

¥Web Request Pipeline

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

¥Most modern web frameworks use a pipeline model where requests are passed through a stack of middleware (AKA filters/plugins). As the request flows through the pipeline, it can be inspected, transformed, modified, or terminated with a response. GraphQL should be placed after all authentication middleware, so that you have access to the same session and user information you would in your HTTP endpoint handlers.

URI、路由

¥URIs, Routes

HTTP 通常与 REST 联系在一起，REST 使用 “resources” 作为其核心概念。相比之下，GraphQL 的概念模型是实体图。因此，GraphQL 中的实体不是通过 URL 来标识的。相反，GraphQL 服务器在单个 URL/端点（通常是 /graphql）上运行，并且给定服务的所有 GraphQL 请求都应定向到该端点。

¥HTTP is commonly associated with REST, which uses “resources” as its core concept. In contrast, GraphQL’s conceptual model is an entity graph. As a result, entities in GraphQL are not identified by URLs. Instead, a GraphQL server operates on a single URL/endpoint, usually /graphql, and all GraphQL requests for a given service should be directed at this endpoint.

HTTP 方法、标头和正文

¥HTTP Methods, Headers, and Body

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

¥Your GraphQL HTTP server should handle the HTTP GET and POST methods.

GET 请求

¥GET request

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

¥When receiving an HTTP GET request, the GraphQL query should be specified in the “query” query string. For example, if we wanted to execute the following GraphQL query:

{
  me {
    name
  }
}

该请求可以通过 HTTP GET 发送，如下所示：

¥This request could be sent via an HTTP GET like so:

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

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

¥Query variables can be sent as a JSON-encoded string in an additional query parameter called variables. If the query contains several named operations, an operationName query parameter can be used to control which one should be executed.

POST 请求

¥POST request

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

¥A standard GraphQL POST request should use the application/json content type, and include a JSON-encoded body of the following form:

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

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

¥operationName and variables are optional fields. operationName is only required if multiple operations are present in the query.

响应

¥Response

无论发送查询和变量的方法如何，响应都应以 JSON 格式在请求正文中返回。正如规范中提到的，查询可能会导致一些数据和一些错误，这些数据应该以以下形式的 JSON 对象返回：

¥Regardless of the method by which the query and variables were sent, the response should be returned in the body of the request in JSON format. As mentioned in the spec, a query might result in some data and some errors, and those should be returned in a JSON object of the form:

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

如果没有返回错误，则响应中不应出现 "errors" 字段。如果没有返回数据，则只有在执行过程中没有发生错误的情况下才应包含 根据 GraphQL 规范、"data" 字段。

¥If there were no errors returned, the "errors" field should not be present on the response. If no data is returned, according to the GraphQL spec, the "data" field should only be included if no errors occurred during execution.

Node

如果你使用的是 Node.js，我们建议你查看 服务器实现列表。

¥If you are using Node.js, we recommend looking at the list of server implementations.

运输规范草案

¥Draft Transport Specification

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

¥A detailed HTTP transport specification is in development. Though it is not yet finalized, these draft specifications act as a single source of truth for GraphQL client & library maintainers, detailing how to expose and consume a GraphQL API using an HTTP transport. Unlike the language specification, adherence is not mandatory, but most implementations are moving towards these standards to maximize interoperability.