GraphQL не обязан выбрасывать весь ответ из-за одного resolver. Поле с ошибкой превращается в null и добавляет запись в errors. Но если поле объявлено Non-Null, null недопустим: ошибка поднимается к родителю. Непрерывная цепочка типов с ! может довести её до корня, и тогда data действительно станет null.
Возьмите path из первой ошибки и пройдите его справа налево по SDL. Это быстрее, чем перехватывать исключения во всех resolver. Цель — найти первое nullable-поле, где распространение должно остановиться, либо доказать, что схема обещает обязательность, которую источник данных обеспечить не может.
Одинаковый сбой по-разному проходит через типы
| Фрагмент типа | Если вложенное значение null | Что увидит клиент |
|---|---|---|
| nickname: String | Ошибка остаётся на поле | nickname: null и errors |
| nickname: String! | Поднимается к объекту | Родитель становится null, если он nullable |
| profile: Profile! | Поднимается ещё выше | Следующий nullable-предок либо data: null |
| friends: [User!] | Null элемента обнуляет список | friends: null и errors |
| friends: [User!]! | Null списка тоже запрещён | Ошибка продолжает путь к родителю |
Пустой список и null — разные состояния. Тип [User!]! допускает [], но не допускает null ни для списка, ни для элемента. Если бизнес-смысл требует «данных пока нет», схема должна описать это явно, а не заставлять resolver выдавать фиктивный объект ради выполнения Non-Null контракта.
Path связывает JSON с конкретным resolver
# SDL
type Query { viewer: User! }
type User { profile: Profile! }
type Profile { displayName: String! }
# Response при ошибке displayName
{
"data": null,
"errors": [{
"message": "profile source unavailable",
"path": ["viewer", "profile", "displayName"]
}]
}Пример условный, но следует правилу спецификации: displayName не может быть null, profile тоже не может быть null, затем viewer не может быть null — nullable-границы до root нет. Если изменить viewer на User или profile на Profile, клиент сохранит данные выше этой границы и увидит null только для соответствующей ветки.
Сначала восстановите resolver, затем обсуждайте SDL
Non-Null не является причиной database timeout, ошибки авторизации или некорректного mapper. Исправьте исходный сбой, добавьте correlation ID в extensions без stack trace и проверьте, что resolver различает «объект отсутствует» и «зависимость не ответила». Возврат null вместо исключения не делает обязательное поле корректным.
- Сверить errors[].path с именами полей и индексами списка в ответе.
- Открыть SDL каждого сегмента и выписать модификаторы List и Non-Null.
- Повторить только минимальный query без соседних полей и aliases.
- Проверить resolver отдельно с теми же identity, locale и tenant context.
- Не отправлять клиенту SQL, stack trace, внутренний hostname или исходный exception.
Nullable-граница — продуктовое решение
Поле следует оставлять Non-Null, когда сервер действительно способен гарантировать значение для любого допустимого объекта. Если данные приходят из необязательного профиля или внешней системы, nullable может честнее отражать контракт. Для ожидаемых бизнес-отказов — например, недостатка средств — удобнее typed result или errors-as-data, а не execution error.
Ослабление типа влияет на сгенерированные клиенты и их проверки. Сначала найдите потребителей, добавьте контрактный тест и выпускайте изменение как эволюцию схемы. Усиление nullable до Non-Null ещё опаснее: старые записи с null должны быть исправлены до публикации нового обещания.
Контрольный тест обязан проверять и data, и errors
- Заставить один вложенный resolver вернуть контролируемую ошибку.
- Проверить точный path, message и отсутствие секретных extensions.
- Убедиться, что данные сохраняются до выбранной nullable-границы.
- Проверить отдельный сценарий null внутри списка Non-Null элементов.
- Запустить тест на реальном клиенте: он не должен считать HTTP 200 полным успехом без анализа errors.
Для разбора подготовьте минимальный query, variables без персональных данных, JSON-ответ и небольшой фрагмент SDL вдоль path. Этого достаточно, чтобы отличить ошибку исполнения от неверного обещания схемы и выбрать границу, не превращая весь API в набор nullable-полей.