Если 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 про key | SDL subgraphs | @key fields, types и federation version |
| Router не обновил schema | Build pipeline | Compose result и active supergraph revision |
| Entity целиком null | Reference resolver | Representation и lookup result |
| Только поле null | Field resolver или authorization | Parent object и error path |
| Работает, но создаёт N+1 | Batching 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 к данным
- Собрать все subgraph SDL той же revision, что использует router.
- Запустить local supergraph composition или schema check.
- Убедиться, что новый supergraph действительно активирован.
- Открыть query plan и найти переход к receiving subgraph.
- Проверить source response: key field присутствует и не null.
- В test environment вызвать _entities с одной representation.
- Сравнить key normalization и lookup в reference resolver.
- Повторить 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 линейно.