Документация / GraphQL
Глобальная идентификация объектов
Единообразный доступ к объектам упрощает кеширование и поиск объектов
Чтобы клиенты GraphQL могли удобно кешировать и повторно загружать данные, серверы GraphQL должны открывать идентификаторы объектов стандартным образом.
Для этого клиенту нужен стандартный способ запросить объект по идентификатору, а схеме — стандартный способ возвращать эти идентификаторы в ответе.
Об объекте почти ничего не известно, кроме его идентификатора, поэтому такие объекты называют узлами (nodes). Пример запроса узла:
{
node(id: "4") {
id
... on User {
name
}
}
}
- Схема GraphQL устроена так, что любой объект можно получить полем
nodeкорневого объекта запросов. Оно возвращает объекты, которые соответствуют интерфейсуNode. - Поле
idможно безопасно извлечь из ответа и сохранить для кеширования и повторной загрузки. - Сведения, специфичные для типа, который реализует интерфейс
Node, клиент получает фрагментами по интерфейсу. Здесь этоUser.
Интерфейс Node выглядит так:
# Объект с глобально уникальным идентификатором
interface Node {
# Идентификатор объекта.
id: ID!
}
А тип User соответствует ему так:
type User implements Node {
id: ID!
# Полное имя
name: String!
}
Полная схема с узлами — её можно открыть в редакторе:
"Объект с глобально уникальным идентификатором"
interface Node {
"Идентификатор объекта"
id: ID!
}
type User implements Node {
id: ID!
"Полное имя"
name: String!
}
type Query {
"Любой объект по глобальному идентификатору"
node(id: ID!): Node
}
Спецификация
Ниже — более формальные требования к идентификации объектов, которые обеспечивают единообразие реализаций серверов. Требования основаны на том, как сервер становится совместимым с клиентом API Relay, но полезны для любого клиента.
Зарезервированные типы
Сервер GraphQL, совместимый с этой спецификацией, должен зарезервировать некоторые типы и имена типов для единой модели идентификации объектов. Спецификация задаёт правила для:
- интерфейса с именем
Node; - поля
nodeкорневого типа запросов.
Интерфейс Node
Сервер должен предоставлять интерфейс Node. В интерфейсе должно быть ровно одно поле — id, возвращающее
обязательный ID.
Этот id должен быть глобально уникальным идентификатором объекта: по одному id сервер должен уметь повторно
загрузить объект.
Интроспекция
Сервер, правильно реализующий этот интерфейс, примет следующий запрос интроспекции и вернёт приведённый ответ:
{
__type(name: "Node") {
name
kind
fields {
name
type {
kind
ofType {
name
kind
}
}
}
}
}
вернёт
{
"__type": {
"name": "Node",
"kind": "INTERFACE",
"fields": [
{
"name": "id",
"type": {
"kind": "NON_NULL",
"ofType": {
"name": "ID",
"kind": "SCALAR"
}
}
}
]
}
}
Корневое поле node
Сервер должен предоставлять корневое поле node, которое возвращает интерфейс Node. У поля должен быть ровно
один аргумент — обязательный ID с именем id.
Если запрос вернул объект, реализующий Node, то при передаче значения его поля id в аргумент id корневого
поля node должен вернуться тот же самый объект.
Сервер должен приложить все усилия, чтобы получить эти данные, но это не всегда возможно. Например, сервер вернул
User с корректным id, но при повторной загрузке через корневое поле node база пользователей недоступна или
пользователь удалил учётную запись. Тогда результат запроса этого поля должен быть null.
Интроспекция
Сервер, правильно реализующий это требование, примет следующий запрос интроспекции и вернёт ответ, содержащий приведённый фрагмент:
{
__schema {
queryType {
fields {
name
type {
name
kind
}
args {
name
type {
kind
ofType {
name
kind
}
}
}
}
}
}
}
вернёт
{
"__schema": {
"queryType": {
"fields": [
{
"name": "node",
"type": {
"name": "Node",
"kind": "INTERFACE"
},
"args": [
{
"name": "id",
"type": {
"kind": "NON_NULL",
"ofType": {
"name": "ID",
"kind": "SCALAR"
}
}
}
]
}
]
}
}
}
В массиве fields могут быть и другие элементы.
Стабильность полей
Если в запросе встречаются два объекта, оба реализуют Node и у них одинаковые идентификаторы, эти объекты должны
быть равны.
Равенство объектов здесь определяется так:
- если поле запрошено у обоих объектов, результат этого поля у первого объекта должен быть равен результату у
второго:
- если поле возвращает скаляр, равенство определяется так, как принято для этого скаляра;
- если поле возвращает перечисление, равенство означает одинаковые значения перечисления;
- если поле возвращает объект, равенство определяется рекурсивно по тем же правилам.
Например:
{
fourNode: node(id: "4") {
id
... on User {
name
userWithIdOneGreater {
id
name
}
}
}
fiveNode: node(id: "5") {
id
... on User {
name
userWithIdOneLess {
id
name
}
}
}
}
может вернуть:
{
"fourNode": {
"id": "4",
"name": "Mark Zuckerberg",
"userWithIdOneGreater": {
"id": "5",
"name": "Chris Hughes"
}
},
"fiveNode": {
"id": "5",
"name": "Chris Hughes",
"userWithIdOneLess": {
"id": "4",
"name": "Mark Zuckerberg"
}
}
}
fourNode.id и fiveNode.userWithIdOneLess.id совпадают, поэтому условия выше гарантируют, что
fourNode.name равно fiveNode.userWithIdOneLess.name, — так и есть.
Множественные идентифицирующие корневые поля
Представим корневое поле username, которое принимает имя пользователя и возвращает этого пользователя:
{
username(username: "zuck") {
id
}
}
может вернуть:
{
"username": {
"id": "4"
}
}
Объект ответа — пользователя с идентификатором 4 — явно можно сопоставить с запросом пользователя с именем «zuck».
Теперь представим корневое поле usernames, которое принимает список имён и возвращает список объектов:
{
usernames(usernames: ["zuck", "moskov"]) {
id
}
}
может вернуть:
{
"usernames": [
{
"id": "4"
},
{
"id": "6"
}
]
}
Чтобы клиент мог сопоставить имена с ответами, ему нужно знать, что массив ответа того же размера, что и массив аргумента, и порядок элементов совпадает. Такие поля называются множественными идентифицирующими корневыми полями (plural identifying root fields); требования к ним — ниже.
Поля
Сервер по этой спецификации может предоставлять корневые поля, которые принимают список входных значений и возвращают список ответов. Чтобы клиенты по спецификации могли ими пользоваться, такие поля должны быть множественными идентифицирующими корневыми полями и выполнять следующие требования.
Сервер по спецификации может предоставлять и корневые поля, которые не являются множественными идентифицирующими; клиент по спецификации просто не сможет использовать их как корневые поля в своих запросах.
У множественного идентифицирующего корневого поля должен быть один аргумент. Его тип — обязательный список
обязательных значений. В примере с usernames поле принимало бы один аргумент usernames типа (в записи системы
типов) [String!]!.
Тип значения множественного идентифицирующего корневого поля — список или обязательный список. Элементы списка —
интерфейс Node, объект, реализующий Node, или обязательная обёртка над ними.
При каждом использовании такого поля длина списка в ответе должна совпадать с длиной списка в аргументах. Каждый
элемент ответа должен соответствовать своему элементу входа: формально, если входной список Lin дал выходное
значение Lout, то для произвольной перестановки P передача P(Lin) должна дать P(Lout).
Поэтому серверам советуют не делать элементы ответа обязательными: если объект для какого-то элемента входа
получить не удалось, для него всё равно нужно вернуть значение, и null для этого удобен.
Похожие инструменты
Обновлено: 17 октября 2026 г.
