Если Product находится в products subgraph, но поле reviews из второго subgraph возвращает null, начните не с cache router. Возьмите один failing key и пройдите цепочку: source subgraph вернул key field, router сформировал representation с __typename, receiving subgraph принял тот же key, а __resolveReference нашёл запись в своём источнике.

Composition и runtime resolution — разные этапы. Несовместимые schemas могут вообще не собрать новый supergraph; тогда router продолжит работать на предыдущей конфигурации. Успешная composition не гарантирует, что конкретный ID существует или что reference resolver использует правильное поле и формат.

Симптом сразу сужает участок цепочки

СимптомВероятный слойЧто сравнить
Composition error про keySDL subgraphs@key fields, types и federation version
Router не обновил schemaBuild pipelineCompose result и active supergraph revision
Entity целиком nullReference resolverRepresentation и lookup result
Только поле nullField resolver или authorizationParent object и error path
Работает, но создаёт N+1Batching reference lookupЧисло calls на один operation

Один key должен означать один объект

# Products subgraph
type Product @key(fields: "upc") {
  upc: ID!
  name: String!
}

# Reviews subgraph
type Product @key(fields: "upc") {
  upc: ID!
  reviews: [Review!]!
}

Оба subgraphs объявляют entity Product через upc одинакового GraphQL type. Key field должен быть уникальным и ненулевым для каждого instance. Если один сервис считает upc строкой с ведущими нулями, а другой превращает её в число, одинаковый товар станет разными ключами даже при успешной схеме.

В Federation 2 subgraph, который добавляет уникальное поле entity, должен уметь разрешить reference для поддерживаемого key. Несколько @key допустимы, но router выбирает доступный путь; каждый заявленный resolvable key обязан действительно работать. Не добавляйте фиктивный key только для прохождения composition.

Representation — минимальный пакет для перехода

{
  "__typename": "Product",
  "upc": "000123"
}

Product: {
  __resolveReference(ref) {
    return productsByUpc.load(ref.upc);
  }
}

Router формирует representation автоматически из __typename и @key fields. Reference resolver получает её первым аргументом и возвращает поля, за которые отвечает subgraph. Если resolver ждёт id, а schema объявляет upc, lookup неизбежно вернёт null. Логируйте operation fingerprint, typename, имя key и hash значения, но не весь object.

Проверка идёт от schema к данным

  1. Собрать все subgraph SDL той же revision, что использует router.
  2. Запустить local supergraph composition или schema check.
  3. Убедиться, что новый supergraph действительно активирован.
  4. Открыть query plan и найти переход к receiving subgraph.
  5. Проверить source response: key field присутствует и не null.
  6. В test environment вызвать _entities с одной representation.
  7. Сравнить key normalization и lookup в reference resolver.
  8. Повторить batch из нескольких entities и проверить порядок результатов.

_entities — внутренний federation entry point, его не открывают публично ради диагностики. Тест выполняют в защищённом subgraph окружении с синтетическим ID. Если прямой reference lookup работает, а federated operation нет, проблема вероятнее в source key, query plan или active supergraph revision.

Null и error должны сохранять различие причин

  • Not found: key корректен, объект отсутствует в receiving data source.
  • Forbidden: объект существует, но caller не имеет права на поле.
  • Bad representation: отсутствует key или неверен его тип.
  • Dependency error: lookup не завершился из-за timeout или outage.
  • Composition failure: новая schema не стала active.
  • Resolver bug: exception содержит internal reference, но не secret и не raw query variables.

Не превращайте все варианты в тихий null: клиент потеряет причину, а on-call будет искать проблему в router. При этом публичная GraphQL error не должна раскрывать SQL, внутренний URL или stack trace. Correlation ID связывает безопасное сообщение с закрытым log.

Reference resolver не должен создавать N+1

Один operation может запросить много entities, и Apollo documentation отдельно предупреждает, что reference resolver вызывается многократно. Batch loader группирует keys, сохраняет порядок и возвращает отдельный результат на каждый input. Cache loader ограничивают рамками request, если authorization или tenant влияет на видимость.

Приёмка проверяет переход между владельцами

known key             -> entity fields resolved
unknown key           -> documented not-found behavior
key with leading zero -> unchanged through representation
wrong tenant          -> forbidden, never cross-tenant data
20 entities           -> batched lookup, stable ordering
composition failure   -> old supergraph stays active

Для разбора соберите subgraph SDL, federation and router versions, composition output, active supergraph revision, query plan, одну обезличенную representation и reference resolver metrics. Успех — entity одинаково находится по каждому заявленному key, ошибки различимы, а batch не увеличивает число backend calls линейно.

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