GraphQL API¶

Требования применяются к разработке, тестированию и сборке GraphQL provider и consumer. Уровни обязательности определены в корневом README.md.

INT-GQL-001. Версионируемая схема¶

Уровень: MUST

Применяется к: каждому GraphQL API

Schema Definition Language (SDL), включая custom scalar и directive, должен храниться в GitLab как машинно-проверяемый контракт. Сборка provider и генерация consumer должны использовать одну зафиксированную версию схемы.

Обоснование¶

Исполняемый resolver без опубликованной схемы не образует проверяемый контракт.

Проверка¶

синтаксическая проверка SDL;
генерация типов provider и consumer;
contract-тест схемы и реализации.

Исключения¶

Не допускаются для опубликованного API.

INT-GQL-002. Совместимость схемы¶

Уровень: MUST

Применяется к: изменению опубликованной GraphQL-схемы

Удаление поля, аргумента или значения enum, добавление обязательного аргумента, сужение nullability входа, расширение nullability результата и изменение семантики считаются несовместимыми. CI должен выполнять schema diff и блокировать необъявленное несовместимое изменение.

Добавление значения enum в результат считается потенциально несовместимым для consumer с исчерпывающим разбором и должно проверяться по сохранённым операциям и поддерживаемым client toolchain.

Обоснование¶

Единый endpoint не устраняет необходимость независимого обновления consumers.

Проверка¶

automated schema diff;
contract tests сохранённых consumer operations;
тест предыдущего consumer с новой схемой.

Исключения¶

Удаление до первой публикации не считается изменением опубликованной схемы.

INT-GQL-003. Ограничение операций¶

Уровень: MUST

Применяется к: входящей GraphQL query, mutation или subscription

Provider должен до выполнения проверять синтаксис, типы, максимальную глубину, сложность и размер операции. Для коллекций должна требоваться ограниченная pagination. Превышение лимита должно возвращать стабильную GraphQL-ошибку без частичного выполнения mutation.

Обоснование¶

Типизированная схема не ограничивает стоимость вложенной операции.

Проверка¶

тест глубины, aliases, fragments и размера коллекции;
тест отклонения до вызова resolver;
нагрузочный тест граничной разрешённой операции.

Исключения¶

Иной алгоритм оценки стоимости допустим, если он машинно проверяет конечную верхнюю границу.

INT-GQL-004. Авторизация каждого resolver¶

Уровень: MUST

Применяется к: полю, раскрывающему защищённые данные или выполняющему mutation

Авторизация должна проверяться по доверенному контексту для фактически запрошенного объекта и поля. Проверка только верхнего query resolver или скрытие поля клиентским кодом недостаточны. Batch-loader не должен объединять данные разных контекстов доступа.

Обоснование¶

Клиент свободно формирует форму GraphQL-операции и может обойти предположение UI.

Проверка¶

security-тест прямого запроса каждого защищённого поля;
тест aliases и fragments;
параллельный тест batch-loader разных субъектов.

Исключения¶

Публичное поле не требует проверки субъекта, если это зафиксировано в схеме доступа.

INT-GQL-005. Ошибки и частичный результат¶

Уровень: MUST

Применяется к: GraphQL response с errors

Контракт должен определять, для каких операций допустим частичный data. Ошибка должна иметь стабильный машинный код в extensions и не раскрывать stack trace или внутреннее исключение. Consumer не должен трактовать наличие data как полный успех при наличии применимой ошибки.

Обоснование¶

GraphQL допускает одновременные данные и ошибки, что требует явной семантики.

Проверка¶

contract-тест полного и частичного отказа;
тест маскирования внутренней ошибки;
consumer-тест обработки data вместе с errors.

Исключения¶

Не допускаются для mutation с атомарным контрактом.