Документация / 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 г.