Магия декларативности и схемы. Часть 6: Защита от злобных уничтожителей полей

Как еще мы можем обеспечить надежность нашего приложения?

Кажется все уже очень хорошо, но осталась одна нерешенная проблема. Что, если под покровом ночи один из ваших коллег удалит парочку полей из схемы? Если вы храните схему в репозитории, ее же можно и забыть обновить :)

Второй нерешенный вопрос – а как вообще безопасно удалять все поля. Их же наверняка кто-то использует? Давайте разбираться

Директива @deprecated

Чуть-чуть теории: GraphQL поддерживает механизм директив. Вы можете помечать кусочки схемы директивами и учить GraphQL engine их понимать. Чтобы создать директиву, вам нужно объявить ее в схеме. Можно добавить директиве аргументов

directive @typeClass(name: String!) on FIELD

и потом использовать в запросе:

query {
  allTypes @typeClass(name: "Applicative") {
    name
    id
  }
}

Ну и реализовать логику обработки этой директивы в резолвере. Для нашего примера нужно будет возвращать только типы принадлежащие к типу классов Applicative. Если вы не понимаете смысл последнего предложения, это окей:) если понимаете – то я очень рада, что кто-то неравнодушный к FP заглянул в мой блог.

В GraphQL есть несколько встроенных директив. Одна из них @deprecated, вот она нам и понадобится.

Мы можем помечать поля этой директивой, намекая коллегам, что пора бы сие поле выпилить.

Как выпиливать поля безопасно?

Для начала хорошо бы убедиться, что все изменения в нашей схеме понятны и прозрачны.

Давайте рассмотрим новую версию нашей схемы, в которой мы удалили одно из полей:

Вот так можно обнаружить удаленное поле:

Мы пробежались по двум версиям схемы, собрали все поля в структуру вида { [имяПоля]: количество_таких_полей } и посчитали разницу для двух схем.

Получилось

Конечно, есть готовые и намного более мощные инструменты, которые умеют делать такой же трюк. Например, graphql-inspector сравнивает схемы, находит опасные изменения, строит из этого читабельный репорт. В дополнение к этим суперфичам инспектор из коробки работает на CI.

Настоящий комбайн :)

Еще один мощный инструмент - Apollo Studio. Чуть-чуть перескажу документацию:

Apollo Studio сидит в облаке и предоставляет вам очень крутой инструментарий. Вы можете создавать разные версии ваших схем и трекать их изменения. Это полезно, если вы не хотите хранить ваши схемы в репо проекта. Каждый раз, когда ваша схема меняется, вы можете пушить новую версия в Apollo Studio. Можно делать это на CI или через CLI. Если вы используете Apollo Server, то за пару строчек можно настроить автоматическую отправку вашей новой схемы в Apollo Studio.

Там же вы можете посмотреть доки для схемы. Как это весело и удобно, мы обсуждали в третьей части этой серии постов.

Apollo Studio может собирать и агрегировать различные метрики вашего приложения. Например, можно посмотреть, какие кусочки схемы используются и какие поля тормозят.

Разумеется, провалидировать вашу схему оно тоже может :)

Одна из очень мощных фич этого инструмента — поддержка распределенного графа.

И что же у нас получилось?

Мы разобрались с тем, как устроена GraphQL схема, как ее парсить и траверсить. Мы посмотрели на различные представления GraphQL схемы и подумали о том, как они могут помочь в разработке и коммуникации с командой. Мы теперь понимаем, как и зачем валидировать запросы, как настроить свою IDE и CI, чтобы при помощи схемы сделать наше приложение более надежным. ~~Ленивые~~ Эффективные разработчики теперь будут еще эффективнее, ибо знают, как настроить codegen. Мы посмотрели, как писать и рефакторить тесты для наших ографкуэленых компонентов. И, наконец, мы научились правильно депрекейтить поля и готовы запустить нашу схему в космос :)

Наше путешествие в мир схем и GraphQL подошло к концу 🎉

Мы не обсудили кучу интересных топиков, связанных со схемами: конфиденциальность, как их расширять, как разолвить запросы, что забавного можно сделать со схемой на клиенте. Но, кажется, у нас достаточно материала, чтобы начать восхищаться декларативным подходом и подумать о том, чтобы притащить какую-нибудь симпатичную схему в ваш проект. Для этого вам не обязательно использовать GraphQL, для вашего API наверняка наверняка найдется что-то похожее.

Спасибо что прочитали этот пост. Если у вас остались вопросы или фидбек, несите их скорее! Мои контакты в футере :)