Чтобы понимать, какие запросы можно отправлять в GraphQL API и что можно получить в ответе, нужно уметь читать его схему. Это как WSDL в SOAP API — описание всех доступных методов.
Да, программы типа Postman или Apollo сами считывают схему и показывают вам всё в красивом виде — просто ходи да «натыкивай» запросы. Но если само API ещё в разработке, чтение схемы поможет понять, что вас ожидает.
Поэтому в этой статье я расскажу, что такое Schema GraphQL API и как её читать.
Содержание
Что такое схема и что там есть
Схема содержит:
данные, которые мы можем получить в ответе;
доступные запросы (query и mutation).
Описывается по schema definition language (SDL). И выглядит примерно как несколько идущих подряд JSON-объектов. Так что, если знакомы с форматом JSON, схему тоже прочитать сможете!
См также:
По сути своей схема — это ТЗ. Когда нужно создать GraphQL API, аналитик размышляет, какую информацию туда выводить, и пишет схему. Скажем, у нас есть список книг (только их названия для простоты) и нужен метод для получения этого списка. Схема будет выглядеть примерно вот так:
type Book { title: String } type Query { getAllBooks: [Book] }
Теперь вспомним, что схема содержит, и что можно понять, читая её:
данные, которые мы можем получить в ответе — объект книги Book, его поле title;
доступные запросы (query и mutation) — только запросы типа query. И у нас будет всего 1 запрос: getAllBooks.
Что и делает разработчик, добавляя обвязку в коде, которая даст возможность получать всю эту информацию.
Соответственно, схема — идеальное ТЗ, которое всегда актуально. Ведь здесь невозможно сделать описание, как в «обычных», привычных нам soap или rest методах, где есть четкое «что на входе» и не менее четкое «что на выходе».
В GraphQL формат вывода данных более гибкий. Чтобы описать, что именно можно попросить на входе, нужно будет для каждого метода делать копипасту со схемы. А это трудозатратно и неэффективно — если что-то изменится, нужно исправлять во всех местах?
Проще дать общее описание методов и их логики + ссылку на схему. Поэтому давайте посмотрим, что мы можем найти в схеме.
Объекты, с которыми мы будем работать
Объекты в схеме описываются через ключевое слово type. Общий синтаксис:
Ключевое слово type
Название объекта
Внутри фигурных скобок — набор полей объекта и их типов (через двоеточие, название поля: его тип)
Если какой-либо метод возвращает объект (сам по себе, или через связанный объект) — мы можем вернуть в ответе любое из его полей.
Подробнее про типы полей, которые встречаются в объекте, см ниже.
Аргументы внутри объекта
У любого поля объекта (который создается с помощью type) могут быть аргументы. То есть такая запись тоже нормальная:
type Author { name: String books(limit: Int): [Book] }
Хотя обычно аргументы используют внутри запросов и мутаций (это ведь тоже объекты, которые создаются через type):
type Query { getBook(id: ID!): Book } type Mutation { createBook(id: ID!, title:String!): Book }
См также:
Аргументы внутри объекта Schema GraphQL — для чего нужны — подробнее разберем, зачем это нужно в простом объекте, а не запросе / мутации.
Запросы и мутации
По сути своей запрос или мутация — это тоже объект. Поэтому начинаются они с ключевого слова type. Разница только в том, что идет внутри фигурных скобок:
Простой объект — название поля: его тип данных.
Запрос или мутация — название метода: то, что он возвращает в ответ.
Вот, например, как может выглядеть схема, где мы возвращаем все книги и всех авторов (в разных запросах):
type Query { books: [Book] authors: [Author] }
Здесь у нас в типе Query (запрос) есть два метода — books и authors. Теперь, при наличии такой схемы, мы можем вызвать любой из этих методов, например:
query { authors { name } } }
Как именно назвать метод — решает разработчик. Он может дать и привычные глазу названия:
type Query { getAllBooks: [Book] getAllAuthors: [Author] }
Тогда при вызове метода мы будем указывать уже getAllAuthors:
query { getAllAuthors { name } } }
Но это не является каким-то обязательным требованием. Как захотел — так и назвал.
И помните, что по сути своей название метода — это просто поле объекта Query (или Mutation). Соответственно, у него могут быть аргументы:
type Query { getBook(id: ID!): Book }
В мутации всё делается по аналогии, разве что аргументов там обычно сильно больше, особенно в методах создания сущности:
type Mutation { createBook(id: ID!, title:String!, desc:String, author: Author, publish_date: String): Book }
Есть ещё один вариант методов — Subscriptions (подписки). В схеме они описываются аналогично запросам и мутациям.
Массивы и обязательные поля
Если у поля стоит «!» — оно обязательное. И мы ожидаем, что сервер будет возвращать ненулевое значение. Восклицательный знак ставится в схеме после указания типа данных поля:
type User { name: String! age: Int }
Ненулевым может быть не только само поле, но и какой-то его аргумент. Если в запросе есть ненулевой аргумент — его обязательно надо указать, иначе получим ошибку. В схеме ставим «!» после типа данных аргумента:
type Query { getUser(id: ID!): User }
Массив — это набор значе��ий. Он указывается в схеме через квадратные скобки, как и массив в json. Допустим, что у книги есть поле с её цветом (colors) — она может быть цветная, может быть черно-белая, но могут быть и оба варианта. Тогда указываем массив:
type Book { title: String! author: Author! colors: [String]! }
А как ставятся восклицательные знаки у массивов? Тут есть разные варианты:
1. Непустое значение внутри массива
Массив может быть пустым, но если внутри что-то есть, то непустое!
В схеме это записывается так:
colors: [String!]
+ Допустимые варианты ответа:
colors: null
colors: []
colors: ["Цвет", "Ч/б"]
- Недопустимые варианты:
colors: ["Цвет", null, "Ч/б"]
2. Обязательный массив, но могут быть пустые значения внутри
В схеме это записывается так:
colors: [String]!
+ Допустимые варианты ответа:
colors: []
colors: ["Цвет", "Ч/б"]
colors: ["Цвет", null, "Ч/б"]
- Недопустимые варианты:
colors: null
3. Обязательный массив без пустых значений
В схеме это записывается так:
colors: [String!]!
+ Допустимые варианты ответа:
colors: []
colors: ["Цвет", "Ч/б"]
- Недопустимые варианты:
colors: null
colors: ["Цвет", null, "Ч/б"]
Соберем всё вместе для наглядности:
Комментарии
SDL (schema definition language) поддерживает добавление комментариев. Куда же без них?
Комментарии начинаются с символа «#» и могут идти как перед какой-то строкой, так и сразу после неё:
# Книги, выпущенные нашим издательством type Book { title: String! author: Author publish_date: String! # Дата может быть указана как просто годом, так и «Июль 2020», поэтому делаем просто строкой }
Все, что следует за символом «#» на той же строке, будет игнорироваться парсером GraphQL.
Если нужен многострочный комментарий, используются тройные кавычки:
""" Тут был Ооооооочень длинный Комментарий """ type Book { title: String! author: Author }
Документация
Тройные кавычки используются для многострочных комментариев и документации. Их уже парсер не игнорирует, а наоборот.
Некоторые инструменты (например, Apollo) могут автоматически извлекать комментарии, заключенные в тройные кавычки, для генерации документации.
И если у нас такая схема:
""" Книги, выпущенные нашим издательством """ type Book { """ Название книги """ title: String! """ Автор книги """ author: Author }
То при натыкивании запроса система будет давать подсказки к полям:
title — Название книги
author — Автор книги
См также:
Типы данных в схеме
Object (type)
Объект — коллекция полей и их типов. Записывается почти как в json — элементы коллекции идут внутри фигурных скобок, только не разделяются запятыми.
Сами элементы зависят от того, что за объект:
Простой объект (любое название, кроме Query и Mutation) — название поля: его тип данных.
Запрос или мутация — название метода: то, что он возвращает в ответ.
Объект может включать в себя другой объект.
Например, есть такой кусок схемы:
type Book { title: String author: Author } type Author { name: String books: [Book] }
В объекте книги (Book) есть поле автора — и это ссылка на объект «Автор» (Author).
В объекте автора (Author) есть поле «книги автора» — и это массив объектов «Книга» (Book).
Если один объект включает в себя другой, то элементы «дочернего» объекта можно вызвать в запросе. Если у нас есть запрос с названием getAllBooks, который получает список всех книг, мы можем запросить в ответе и название книги, и имя её автора:
query { getAllBooks { title author { name } } }
А ещё в каждом объекте есть поле «__typename»! Его не надо прописывать в схеме отдельно, оно есть по умолчанию. Это поле возвращает тип объекта. Например, для приведенной выше схемы мы можем вызвать такой запрос:
query { getAllBooks { title __typename author { name __typename } } }
Ответ будет такого плана:
"data": { "getAllBooks": { "title": "Книга", "__typename": "Book", "author": { "name": "Петр Иванов", "__typename": "Author" } } } }
Это поле помогает нам понять, где мы находимся в данный момент, на каком уровне вложенности — ведь у нас может быть объект в объекте внутри объекта, и так хоть 10 раз!
Scalar
Scalar — аналог примитивных типов в языке программирования:
Int — целочисленное значение
Float — дробное значение
String — строка
Boolean — true или false
ID — идентификатор
В этом примере схемы:
type Book { title: String author: Author }
Поле «title» у книги — это скалярный тип, простая строка (String). Это базовые типы, их будет много в схеме: строки, числа…
Можно сделать свой тип данных: custom scalar type. Он нужен, когда нам нужно сделать доп проверки вокруг базовых типов. Например:
Date — чтобы это была не просто строка, а именно дата
URL — вроде строка, но там гарантированно корректный URL
ODD — только нечетные числа Int
…
Как это выглядит в схеме:
scalar MyCustomScalar scalar Date ...
И всё, используем дальше этот тип там, где может быть другой скалярный тип (тип поля объекта, тип аргумента):
type Book { title: String! author: Author publish_date: Date! }
А остальное делается в коде разработчиком.
Input
Input — специальный тип объекта, позволяет использовать иерархические данные в аргументах.
Например, у нас в системе хранятся пользователи и их банковские карты. Если я хочу создать пользователя сразу с картами, как бы мне эти самые карты указать? Тут есть варианты ��� или внутри мутации указывать просто набор полей (банк, номер карты, баланс), или соединить их вместе и вынести в инпут.
Это будет выглядеть как-то так:
type Mutation { addUserWithCards(name: String!, age: Int, cards: [CardInput]): User! } Input CardInput { bank: Bank number: String balance: Float }
Name, age — простые типы, их можно использовать в качестве аргументов.
Cards — иерархический тип: у него не одно поле, а несколько. Вот для его описания и нужен Input! Потому что просто написать фигурные скобки объекта внутри аргумента нельзя.
Внутри Input могут быть только скалярные типы, enum или другой input. То есть если нужен объект в объекте, создаем несколько input и вкладываем один в другой! Например:
input BlogPostContent { title: String body: String media: [MediaDetails!] } input MediaDetails { format: MediaFormat! url: String! } enum MediaFormat { IMAGE VIDEO }
Enum
Enum — перечисление корректных значений для заданного поля. Никакие другие значения это поле принимать / возвращать не будет. Это как выпадающий список в GUI — там можно выбрать одно из заданных в списке значений, но ввести своё нельзя.
Например, у нас есть такой список цветов:
enum Color { RED GREEN BLUE }
Допустимы только 3 цвета: красный, зеленый, синий. Ввести желтый (YELLOW) нельзя!
Enum — простой тип данных, как скаляр, используется везде, где и скаляр (в объектах, инпутах, в аргументах)
Union
Union — абстрактный тип, который позволяет возвращать в поле один из нескольких типов объектов. Это как UNION в SQL.
Union перечисляет, какие объекты он может возвращать. Например, я делаю поиск в книжном магазине. В строку поиска я могу ввести как название книги, так и имя автора, и ожидаю увидеть или книги, или карточку автора.
В схеме это записывается через Union:
union SearchResult = Book | Author type Book { title: String! } type Author { name: String! } type Query { search(contains: String): [SearchResult!] }
Но тут возникает вопрос — А как мне перечислять, какие поля я ожидаю в ответе?
Для этого в запросе используется синтаксис с многоточием (... on TypeName).
В нашем примере запрос будет выглядеть примерно так:
query { search(contains: "Пушкин") { __typename ... on Book { title } ... on Author { name } } }
Писать «__typename» необязательно, но крайне желательно, чтобы точно понимать, где что вернулось.
Пример ответа на такой запрос:
{ "data": { "search": [ { "__typename": "Book", "title": "Сказки Пушкина" }, { "__typename": "Author", "name": "Пушкин" } ] } }
Interface
Interface (интерфейс) — абстрактный тип, он задает набор полей, которые могут иметь разные объекты.
И если объект имплементирует интерфейс, он обязан содержать все поля из этого интерфейса. Но при этом у него могут быть и свои уникальные поля.
Таким образом, если нам нужно сделать несколько похожих друг на друга объектов, то вместо копипасты одинаковых полей лучше вынести их в интерфейс:
interface Book { title: String! author: Author! } type Textbook implements Book { title: String! author: Author! id: ID } type ColoringBook implements Book { title: String! author: Author! colors: [String!]! } type Query { books: [Book!]! }
В данном примере у нас есть:
Book — интерфейс, который задает стандартный для всех типов книг набор полей
Textbook — текстовая книга, так как имплементирует интерфейс, то содержит его поля + свои (id)
ColoringBook — также имплементирует интерфейс, поэтому есть все поля интерфейса + собственное поле colors
Интерфейс можно возвращать в запросе. В данной схеме мы видим Query.books — этот запрос возвращает список, в котором могут быть как Textbook, так и ColoringBook.
В ответе от сервера мы можем возвращать все поля интерфейса и поля из конкретных объектов, его имплементирующих.
Запрос для общих полей:
query GetBooks { books { title author } }
Чтобы указать поля конкретного объекта, используется синтаксис с многоточием (... on TypeName), как в Union.
Запрос, учитывающий особенности разных объектов (опять же, поле «__typename» крайне рекомендуется, с ним будет проще читать ответ):
query GetBooks { books { __typename title ... on Textbook { id } ... on ColoringBook { colors } } }
Пример ответа:
{ "data": { "books": [ { "__typename": "Textbook", "title": "Тест-дизайн", "id": "aaaa-1234-bbbb-3333" }, { "__typename": "ColoringBook", "title": "SQL", "colors": ["Цвет", "Ч/б"] } ] } }
Итого
Если вы сталкивались с JSON-форматом, то прочитать схему GraphQL API не составит труда. А ведь из неё можно узнать много полезной информации.
Тем более что схема — это самое самое актуальное ТЗ. И даже если в «официальной» документации метода что-то устарело, можно обратиться в схеме и узнать из неё, как это работает.
Поэтому уметь читать схему полезно. Надеюсь, эта статья вам в этом хоть немного поможет =))
См также (полезные статьи про схему на англ языке в официальной документации):
PS — больше полезных статей ищите в моем блоге по метке «полезное». А полезные видео — на моем youtube-канале
