Документация / GraphQL
Интерфейсы, объединения и входные типы
Интерфейсы
Как и многие системы типов, GraphQL поддерживает абстрактные типы. Первый из них — интерфейс: набор полей, которые должен содержать конкретный объектный тип или другой интерфейс, чтобы его реализовать.
Например, интерфейс Character может представлять любого персонажа трилогии «Звёздные войны»:
interface Character {
id: ID!
name: String!
friends: [Character]
appearsIn: [Episode]!
}
Любой тип, который реализует Character, должен содержать в точности эти поля — с теми же аргументами и
типами значений.
Вот типы, которые могут реализовывать Character:
type Human implements Character {
id: ID!
name: String!
friends: [Character]
appearsIn: [Episode]!
starships: [Starship]
totalCredits: Int
}
type Droid implements Character {
id: ID!
name: String!
friends: [Character]
appearsIn: [Episode]!
primaryFunction: String
}
Оба типа содержат все поля интерфейса Character, но добавляют и свои — totalCredits, starships и
primaryFunction, — характерные именно для этого вида персонажей.
Интерфейсы полезны, когда нужно вернуть объект или набор объектов, которые могут быть разных типов. Например, следующий запрос возвращает ошибку:
{
hero(episode: JEDI) {
name
primaryFunction
}
}
Ответ:
{
"errors": [
{
"message": "Cannot query field \"primaryFunction\" on type \"Character\". Did you mean to use an inline fragment on \"Droid\"?",
"locations": [
{
"line": 4,
"column": 5
}
]
}
]
}
Поле hero возвращает тип Character, то есть в зависимости от аргумента episode это может быть и Human,
и Droid. В таком запросе можно спрашивать только поля, которые есть в интерфейсе Character, а
primaryFunction в нём нет.
Чтобы запросить поле конкретного объектного типа, нужен встроенный фрагмент:
{
hero(episode: JEDI) {
name
... on Droid {
primaryFunction
}
}
}
Ответ:
{
"data": {
"hero": {
"name": "R2-D2",
"primaryFunction": "Astromech"
}
}
}
Интерфейс может реализовывать другие интерфейсы:
interface Node {
id: ID!
}
interface Character implements Node {
id: ID!
name: String!
friends: [Character]
appearsIn: [Episode]!
}
Интерфейс не может реализовывать сам себя, а интерфейсы не могут циклически ссылаться друг на друга.
Общие поля у типов API ещё не повод вводить интерфейс только ради одинаковых имён. Интерфейс — способ показать общее поведение реализующих его типов. Он должен иметь смысл для разработчиков клиентов — как
Character, полезная абстракция для людей и дроидов.
На карте схемы реализация интерфейса показана пунктирной стрелкой от типа к интерфейсу. Если тип не повторил поле интерфейса, редактор сообщит об ошибке: «Тип Droid не содержит поле Character.appearsIn из интерфейса».
Объединения
Второй абстрактный тип GraphQL — объединение (union). Объединения похожи на интерфейсы, но не могут задавать общие поля для входящих в них типов.
Объединение определяется перечнем объектных типов-участников:
union SearchResult = Human | Droid | Starship
Там, где схема возвращает SearchResult, может прийти Human, Droid или Starship. Участниками объединения
могут быть только конкретные объектные типы — не интерфейсы и не другие объединения.
Если запросить поле, которое возвращает объединение SearchResult, то поля типов-участников выбираются
встроенными фрагментами:
{
search(text: "an") {
__typename
... on Human {
name
height
}
... on Droid {
name
primaryFunction
}
... on Starship {
name
length
}
}
}
Ответ:
{
"data": {
"search": [
{
"__typename": "Human",
"name": "Han Solo",
"height": 1.8
},
{
"__typename": "Human",
"name": "Leia Organa",
"height": 1.5
},
{
"__typename": "Starship",
"name": "TIE Advanced x1",
"length": 9.2
}
]
}
}
Поле __typename — особое мета-поле: оно автоматически есть у каждого объектного типа и возвращает имя
этого типа. Так клиент различает типы данных.
Поскольку у Human и Droid общий интерфейс Character, их общие поля можно запросить в одном месте —
результат будет тем же:
{
search(text: "an") {
__typename
... on Character {
name
}
... on Human {
height
}
... on Droid {
primaryFunction
}
... on Starship {
name
length
}
}
}
Ответ:
{
"data": {
"search": [
{
"__typename": "Human",
"name": "Han Solo",
"height": 1.8
},
{
"__typename": "Human",
"name": "Leia Organa",
"height": 1.5
},
{
"__typename": "Starship",
"name": "TIE Advanced x1",
"length": 9.2
}
]
}
}
Обратите внимание: у Starship поле name по-прежнему указано отдельно — иначе его не было бы в результате,
ведь Starship не реализует Character.
На карте схемы объединение — отдельная карточка, от которой точечные стрелки ведут к типам-участникам.
Входные типы
В большинстве примеров выше объектные типы, скаляры, перечисления, интерфейсы и объединения использовались как выходные типы — типы значений полей. Но аргументы полей тоже должны иметь типы — входные.
До сих пор во входных типах использовались только скаляры (например, перечисления или String). Но в аргумент
можно передать и сложный объект — с помощью входного типа
(Input Object), последнего из видов именованных типов GraphQL.
Особенно это полезно в изменениях, когда нужно передать целый объект для создания.
На SDL входной тип выглядит как обычный объектный тип, но с ключевым словом input вместо type:
input ReviewInput {
stars: Int!
commentary: String
}
type Mutation {
createReview(episode: Episode, review: ReviewInput!): Review
}
Так входной тип используется в изменении:
mutation {
createReview(
episode: JEDI
review: {
stars: 5
commentary: "Отличный фильм!"
}
) {
stars
commentary
}
}
Ответ:
{
"data": {
"createReview": {
"stars": 5,
"commentary": "Отличный фильм!"
}
}
}
Поля входного типа могут ссылаться на другие входные типы, но смешивать входные и выходные типы в схеме нельзя. У полей входного типа не бывает аргументов.
Входные типы не показываются на карте схемы (как и в GraphQL Voyager) — их описание открывается в панели «Описание» по щелчку на типе аргумента.
Что выбрать
| Задача | Решение |
|---|---|
У типов есть общие поля и общее поведение (id, createdAt) | Интерфейс |
| Разные по смыслу результаты одного поля (поиск, лента событий) | Объединение |
| Сложный или вложенный аргумент, данные для создания объекта | Входной тип |
Дальше
Следующая страница — директивы и документирование схемы.
Похожие инструменты
Обновлено: 17 октября 2026 г.
