Skip to content

Latest commit

 

History

History
82 lines (56 loc) · 5.83 KB

serving-over-http.md

File metadata and controls

82 lines (56 loc) · 5.83 KB

Serving over HTTP

HTTP - самый распространенный выбор клиент-серверного протокола, когда используется GraphQL, из-за его распространенности. Вот несколько рекомендаций для настройки сервера GraphQL при работе через HTTP.

Web Request Pipeline

Большинство современных фреймворков использует модель Pipeline (туннель), в которой запросы проходят через стек промежуточного ПО (известные как фильтры, плагины). Т.к. запрос проходит через туннель, он может быть проверен, преобразован, изменен или прерван с ответом. GraphQL должен быть расположен после всего аутентификационного ПО, чтобы у вас был доступ к той же сессии и информации о пользователе, которую вы получаете в конечных HTTP обработчиках.

URIs, Routes

HTTP часто ассоциируется с REST, который использует "ресурсы" как основную концепцию. С другой стороны, концептуальная модель GraphQL - граф сущностей. В результате, сущности в GraphQL не идентифицируются с URL. Вместо этого, сервер GraphQL работает с одним URL (конечной точкой), обычно /graphql, а все запросы GraphQL для данного сервиса должны быть направлены в эту точку.

HTTP Methods, Headers, and Body

Ваш GraphQL HTTP сервер должен обрабатывать методы GET и POST.

GET request

При получении запроса GET HTTP, запрос GraphQL должен быть указан в "query" строки запроса. Например, если мы хотим выполнить следующий запрос GraphQL:

{
  me {
    name
  }
}

Этот запрос может быть отправлен через HTTP GET следующим образом:

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

Переменные запроса могут быть отправленны как JSON строка в дополнительной переменной запроса variables. Если запрос содержит несколько именованных операций, может быть использован параметр запроса ``operationName` для определения, какая именно операция должна быть выполнена.

POST request

Стандартный GraphQL POST запрос должен использовать Content-Type header application/json, и включать тело в виде JSON следующего вида:

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

operationName и variables являются необязательными полями. operationName требуется, только если в запросе присутствует несколько операций.

В дополнение к сказанному выше, мы рекомендуем поддерживать два дополнительных случая:

  • Если параметр "query" в строке запроса присутствует (как в примере выше), он должен быть разобран и обрабатывается таким же образом, как и в случае HTTP GET.
  • Если есть Content-Type header "application/graphql", необходимо рассматривать содержимое тела HTTP POST так же, как строку query запроса GraphQL.

Если вы используете express-graphql, то это уже включено.

Response

Вне зависимости от метода, которым отправляются запрос и переменные, отклик должен быть возвращен в теле запроса в формате JSON. Как отмечено в спецификации, запрос может завершиться возватом данных и каких-то ошибок. Все это должно быть возвращено в JSON объекте в форме:

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

Если в ответе нет ошибок, поле "errors" не должно присутствовать в ответе. Если запрос не вернул никакой информации в ответе, в соответствии со спецификацией GraphQL, поле "data" должно быть включено в запрос только в случае, если во время выполнения запроса возникла ошибка.

GraphiQL

GraphiQL полезна во время тестирования и разработки, но должна быть отключена в производстве по умолчанию. Если вы используете express-graphql, вы можете переключить его c помощью переменной окружения NODE_ENV:

app.use ( '/ graphql', graphqlHTTP ({
  Схема: MySessionAwareGraphQLSchema,
  graphiql: process.env.NODE_ENV === 'развитие',
}));

Если вы используете NodeJS, мы рекомендуем использовать express-graphql или graphql-server.