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

  1. Заставить один вложенный resolver вернуть контролируемую ошибку.
  2. Проверить точный path, message и отсутствие секретных extensions.
  3. Убедиться, что данные сохраняются до выбранной nullable-границы.
  4. Проверить отдельный сценарий null внутри списка Non-Null элементов.
  5. Запустить тест на реальном клиенте: он не должен считать HTTP 200 полным успехом без анализа errors.

Для разбора подготовьте минимальный query, variables без персональных данных, JSON-ответ и небольшой фрагмент SDL вдоль path. Этого достаточно, чтобы отличить ошибку исполнения от неверного обещания схемы и выбрать границу, не превращая весь API в набор nullable-полей.

Проверенные источники