GraphQL: доступ запрещен

Жил-был один маленький разработчик, работал себе над REST API и горя не знал. Но вот приходит к нему тимлид и предлагает затащить GraphQL. Казалось бы: классный и мощный GraphQL — это запросто! Но в процессе проектирования API разработчик столкнулся с неожиданными проблемами и суровыми испытаниями: система оказалась довольно сложна и полна различных прав и ролей.

Всем привет! Меня зовут Олег, я — бэкенд-разработчик системы Talantix. В этой статье я расскажу о том, как работать с доступом к данным в GraphQL.

Немного про доменную область

Talantix — это ATS для HR. А если простыми словами — рабочий стол рекрутера. Здесь он ведет вакансии, перемещает по этапам кандидатов, пишет им письма, оставляет злобные комментарии, создает встречи, в общем, делает всё что душеньке угодно.

В данной статье примеры будут завязаны на кандидатах. В нашем коде у них исторически сложилось название persons, а если по-русски — персоны. Другие многочисленные сущности Talantix нам сейчас не пригодятся.

Обработка ошибок «по старинке»

Сразу договоримся, что взаимодействие между клиентом и сервером будет происходить по протоколу HTTP. Но все рассказанное в дальнейшем об обработке ошибок в GraphQL на протоколе не завязано, и применимо на любой из них.

Как же мы работали со всем этим в REST API? Допустим, у нас есть GET на кандидата, кандидат в базе существует и доступен пользователю. В этом случае мы отдаем ответ со статусом 200, а в теле ответа — данные кандидата.

GET /persons/1 200 OK  {   "id": 1,   "firstName": "Олег" }

Если же кандидата нет или он недоступен нашему пользователю, мы можем отдать ответ 404, а в теле ответа прокомментируем, почему произошла данная ошибка и какой тип она имеет. Похожим образом API ведет себя в случае изменяющих запросов, например, при желании удалить некоторого кандидата, мы можем получить ответ 403. А в теле ответа будет присутствовать пояснение, что у вас не хватает на это прав.

GET /persons/1 404 Not Found  {   "errorType": "NOT_FOUND",   "message": "Кандидат не найден" }  DELETE /persons/1 403 Forbidden  {   "errorType": "ACCESS_DENIED",   "message": "Вы не имеете права удалять кандидатов" }

GraphQL не завязан на конкретный протокол общения, и, в случае с HTTP, мы имеем один endpoint, который принимает на вход запрос, возвращает код 200 и в теле ответа данные, которые мы попросили. Код ответа в этом случае ни на что не влияет и никак не обрабатывается, и для обработки ошибок нужен иной механизм.

Ошибки бывают разные

Важно различать виды ошибок. Условно они делятся на технические и бизнес-ошибки. Техническими мы называем ошибки, которые не ожидаются при корректной работе системы и правильно составленных запросах, такие как: ошибки валидации, таймауты к базе данных или исключения в коде.

В мире GraphQL есть готовый механизм, а точнее поле errors, для выдачи ошибок. На скриншоте видно, как при ошибке в указании id в поле errors появляется объект с описанием и типом ошибки, путем до узла в котором ошибка возникла и другими полями. Данное поле можно расширять под свои нужды, дополняя иными данными. Техническая ошибка здесь выглядит уместно и удобно, но с бизнес-ошибками все сложнее. Их мы рассмотрим далее.

Вникаем в проблему с null

Допустим, в нашей системе имеется тип Person, у которого есть поля id и firstName:

type Person {   id: Int!,   firstName: String }

Пользователь хочет запросить персону по некоторому id,

{   person(id: 123) {     id     firstName   } }

но такого кандидата в нашей системе нет. Самый простой способ сказать ему об этом — отдать null в качестве ответа:

{     "person": null }

В этом случае такой подход сработает. Единственное ограничение — пользователю никак не различить кейс «кандидат отсутствует» от «кандидат ему недоступен». Однако, если это не требуется, такой способ вполне сгодится.

Теперь немного усложним задачу — добавим персоне опциональное поле email.

type Person {   id: Int!,   firstName: String,   email: String }

Допустим, в нашей системе есть роли, которым недоступны контактные данные кандидата — например, наблюдатели за вакансией. Тогда на их запрос данных кандидата в качестве email мы обязаны отдать null.

{   "person": {     "id": 123,     "firstName": "Олег",     "email": null   } }

И здесь вновь пользователь не сможет понять — кандидат просто не заполнил email или email ему недоступен в принципе, что уже является более критичной проблемой как минимум для нас. Мы хотели бы рисовать плашку «пользователь скрыл какие-то данные от вас».

Для полноты рассмотренных вариантов сделаем email обязательным полем. Об этом в схеме GraphQL нам говорит восклицательный знак:

type Person {   id: Int!,   firstName: String,   email: String! }

И здесь возникает другая проблема: при отсутствии доступа мы обязаны отдать null в качестве email, но при этом будем конфликтовать с нашей же схемой. Тогда в лучшем случае будет ругаться наш валидатор, а в худшем — наш пользователь.

Первый заход на решение

Напомним, что в REST в различных ситуациях мы отдавали различный статус ответа: 200, 404 и другие. Попробуем сэмулировать такой статус ответа отдельным полем в нашей схеме. Введем новый тип UserError:

enum ErrorType {   NOT_FOUND   ACCESS_DENIED }  type UserError {   errorType: ErrorType!   message: String }

Он будет содержать enum, который по сути является текстовым аналогом такого статуса ответа. 404 будет соответствовать NOT_FOUND, 403 — ACCESS_DENIED. Кроме такого enum в UserError присутствует еще и сообщение об ошибке, если оно требуется. Тип ошибки — это прекрасно, но надо ее где-то вернуть, а наша схема — это граф. Мы могли бы вернуть данную ошибку в узле errors, как поступаем с техническими ошибками, но обработка такой ошибки неудобна, а отсутствие строгости схемы в этом поле влечет за собой проблему поддержки контракта.

Поэтому самым удобным вариантом, на наш взгляд, является наличие ошибки рядом с самой сущностью, к которой эта ошибка относится. Как вариант, ошибку можно вложить внутрь сущности, например, в узле persons мы можем вложить объект с типом ошибки и сообщением:

{   person(id: 123) {     error {       errorType       message     }     id     firstName     email   } }

Но тут же можно понять, что данный способ не работает. Если кандидат не найден, наш ответ будет полностью противоречить схеме, ведь нам придется вернуть null там, где это запрещено:

{   "person": {     "error": {       "errorType": "NOT_FOUND",       "message": "Кандидат не найден"     },     "id": null,     "firstName": null,     "email": null   } }

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

Пока вы читали все эти выкладки, возможно вам в голову пришла идея — «Можно же просто не отдавать поля персоны в ответе, ведь undefined !== null«. Увы, но нет.

Во-первых, это не соответствует стандарту GraphQL, если пользователь запросил поле — мы обязаны его отдать. Во-вторых, клиент может работать в той же Java, и при парсинге ответа в класс персоны с ошибкой внутри так же получит объект, не соответствующий схеме, вне зависимости от того, отсутствовало ли поле или было равно null. Наверняка есть решение получше.

Решение получше

В REST, кроме разных статусов ответа, мы также давали различное тело ответа в зависимости от ошибки. И тут на горизонте появляется тип union, присутствующий в стандарте GraphQL. Сделаем тип Person объединением двух других типов — PersonError и PersonItem:

enum PersonErrorType {   NOT_FOUND }  type PersonError {   errorType: PersonErrorType!   message: String }  union Person = PersonItem | PersonError

Это означает, что узел типа Person в ответе вернется нам как объект типа PersonItem с полями кандидата, либо как объект типа PersonError с полями ошибки. С точки зрения схемы эти два типа теперь взаимоисключающие, что будет отражено и в запросе в дальнейшем.

Нам было удобно изменить наш UserError: мы сузили его до кандидата и назвали PersonError. Теперь он содержит только те ошибки, которые в действительности может вернуть наш сервер. А другие ошибки в enum-е, такие как ACCESS_DENIED, не смущают нашего пользователя, заставляя обрабатывать их для тех сущностей, для которых их просто не может быть согласно бизнес логике нашей системы.

Как же будет выглядеть наш запрос?

{   person(id: 123) {     __typename     ... on PersonError {       errorType       message     }     ... on PersonItem {       id       firstName       email     }   } }

Здесь мы видим специальный синтаксис фрагментов с ключевым словом on. В нашем запросе он говорит: «отдай мне поля errorType и message, если вернулся тип PersonError. Если же тип этого узла равен PersonItem, то отдай мне поля кандидата». В отличие от включения ошибки внутрь самой сущности, поля ошибки и поля самого кандидата взаимоисключают друг друга и не могут быть в ответе одновременно.

Здесь же можно заметить интересное поле __typename — так называемое метаполе в GraphQL. Метаполя в GraphQL присутствуют по умолчанию во всех узлах запроса. Поле __typename, как можно догадаться из названия, равно имени типа этого узла. При использовании с union, это поле особенно полезно, так как пользователь API может завязываться не на какие-то специфичные поля самих типов, а на его имя.

То, как будет выглядеть ответ на такой запрос, будет зависеть от доступности нашего кандидата. Если кандидат присутствует в системе и доступен нашему пользователю, мы отдадим его поля, а поле __typename будет равно PersonItem:

{   "person": {     "__typename": "PersonItem",     "id": 123,     "firstName": "Олег",     "email": "email"   } }

Все это может напоминать прием со скрытием лишних полей, но здесь мы честно отдаем все поля одного из типов в union, и любой клиент, согласно схеме, будет валидировать ответ только по правилам этого типа.

Если кандидат недоступен или его просто нет в базе, поле __typename станет равным PersonError, а вместо полей кандидата в JSON будет присутствовать errorType и message.

{   "person": {     "__typename": "PersonError",     "errorType": "NOT_FOUND",     "message": "Кандидат не найден"   } }

В нашем примере с кандидатом поле errorType принимает одно допустимое значение. Может показаться, что это необоснованное усложнение схемы — можно вернуться к случаю, когда мы возвращали null, ведь нам не нужно разбирать причину отсутствия данных. Частично это так, но надо помнить, что наша система постоянно обрастает новой функциональностью, а ее бизнес-логика усложняется. И если в один прекрасный момент появится новый вид ошибки для кандидата, вроде ACCESS_DENIED, то в API, где предусмотрены пользовательские ошибки на уровне типов, будет очень просто добавить новую ошибку в enum, расширяя это API, а не переделывая нашу схему кардинально.

Реализация на бэкенде

Для работы с GraphQL мы используем библиотеку SPQR, которая основана на базовой библиотеке graphql-java. Если хотите узнать плюсы и минусы различных библиотек для GraphQL на java, то советую почитать статью от Артема (в ней есть и видеоверсия). В этой библиотеке используется code-first подход: сначала вы пишете классы сущностей, описываете связи между ними, пишете резолверы, а после этого библиотека сама генерирует схему для клиента.

Итак, у нас будет базовый интерфейс Person, помеченный нотацией GraphQLUnion:

@GraphQLUnion(   name = "Person",    description = "person",    possibleTypeAutoDiscovery = true ) public interface Person {}  public class PersonItem implements Person {   private Integer id;   private String firstName;   //... }  public class PersonError implements Person {   private PersonErrorType errorType;   private String message;   //... }

Здесь мы указываем имя типа для union, также опциально можно указать описание для нашей документации. Еще у нас имеется параметр possibleTypeAutoDiscovery равный true, который говорит библиотеке, чтобы она сама поискала имплементации данного интерфейса в рантайме. Именно они станут перечислением типов в нашем union. Но есть и другой вариант: там вы можете сами перечислить необходимые вам реализации, используя параметр possibleTypes.

Преимущества работы с union

• Схема иерархии типов сама показывает, какие сущности могут вернуться в виде ошибки. Пользователю не нужно читать документацию или искать среди полей сущности нечто похожее на ошибку — это удобно.

• Нет никаких конфликтов с NonNull аннотациями.

• Поле __typename позволяет удобно организовать обработку ответа, например, с помощью паттерна стратегия и не завязываться на какие-либо поля самой сущности.

• Кастомизированный errorType под каждую сущность. На первый взгляд может показаться, что это увеличение бойлерплейта и однотипных классов. Но с другой стороны — получается самодокументируемое API, поэтому возможные ошибки в каждом конкретном случае диктуются и ограничиваются самой схемой.

Но как же email…

На примерах с персоной мы поняли как классно работать с union, посмотрели как это выглядит на бэкенде. Но тут мы вспоминаем, что в способе с null разбирали примеры с email, и перед нами встала проблема различимости заполненности поля от его недоступности. Напомню, у нас есть персона с обязательным полем email и пользователи, роль которых не позволяет им просматривать контактные данные кандидата. Городить отдельный тип со своей ошибкой для такого простого поля, как email, кажется оверхедом, ведь это всего лишь строка.

Подойдем к этой проблеме с другой стороны, по факту у нас есть полная версия кандидата, и версия этого же кандидата без каких-то полей. В данном случае оно одно — email. Посему попробуем описать это на языке типов в нашей схеме. Введем новый тип персоны PersonPublicItem , который будет содержать ограниченный набор полей, доступный пользователям независимо от их роли в системе. А также введем еще один тип — PersonFullItem, с полной информацией о кандидате, которая доступна только определенным менеджерам:

type PersonPublicItem {   id: Int!   firstName: String }  type PersonFullItem {   id: Int!   firstName: String   email: String! }  union Person = PersonError | PersonPublicItem | PersonFullItem

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

Но в реальных задачах та же открытая персона может содержать немало полей, и в этом случае нам придется копировать их все в тип закрытой персоны. При этом схема никак не контролирует согласованность в количестве этих полей, одинаковом названии и типе. В ООП мы бы использовали наследование, в GraphQL наряду с union присутствуют интерфейсы.

Заведем интерфейс PesonItem с базовыми полями, которые мы хотим видеть во всех его реализациях:

interface PersonItem {   id: Int!   firstName: String }  type PersonPublicItem implements PersonItem {   id: Int!   firstName: String }  type PersonFullItem implements PersonItem {   id: Int!   firstName: String   email: String! }

Два наших типа будут имплементировать данный интерфейс. В нашем случае PersonPublicItem ничем не отличается от базового интерфейса, но создание отдельного типа требует стандарт. Дублирование в схеме как будто только увеличилось, и теперь мы пишем поля аж целых три раза.

Однако преимущества налицо:

• Во-первых, данный интерфейс на уровне схемы обязывает нас иметь все базовые поля в классах реализация. Это добавляет строгости к типизации и неймингу этих полей.

• Во-вторых, в коде такой интерфейс будет являться абстрактным классом, поэтому вам не придется дублировать его поля в имплементациях. Учитывая, что мы используем code-first подход, за нас данную схему сгенерирует библиотека.

• И в-третьих, это добавляет нам свободы при составлении запроса, мы можем перечислить две реализации с их полями, а можем вынести базовые поля в общий фрагмент, таким образом убрав дублирование уже в самом запросе.
  Более того, если нам не нужен email, мы можем убрать упоминания о полной персоне, оставить в запросе только базовый интерфейс без упоминания его реализации.

# Запрос без дублирования {      person(id: 123) {     ... on PersonItem {       id                firstName           }           ... on PersonFullItem {       email           }       } }

Таким образом, грамотное выделение общего интерфейса позволит составить удобную систему типов, в которой присутствуют и ошибки и ограничиваются некоторые наборы данных.

Заключение

В статье мы разобрали различные варианты работы с правами и доступом в GraphQL: от простого null в ответе, до развернутой системы типов с union и интерфейсом. Мы отбросили совсем уж неработающие варианты, когда наше решение начинало конфликтовать со схемой или когда присутствовало дублирование с не строгой типизацией.

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

Также важно отметить, что в случаях, когда сущности простые и нет необходимости различать причины отсутствия данных в ответе, вполне сгодится подход с null — развернутая система типов с ошибкам не потребуется. Профит от такого усложнения схемы стоит оценивать заранее и выбирать подходящее решение под вашу бизнес-логику.

Видеоверсию этой статьи можно посмотреть на нашем канале по ссылке.

Где вам хочется работать 

Мы запускаем ежегодное исследование узнаваемости брендов IT-компаний на российском рынке. Каждый год изучаем, какие айтишки у нас знают лучше, и в каких хочется работать большинству специалистов. 

Пройдите этот опрос и расскажите о своих впечатлениях от сегодняшнего IT в РФ.

Ваши ответы помогут нам составить наиболее объективную картину, которой мы по традиции поделимся со всеми.