DataLoader: батчинг по дереву резолверов

GraphQL-запрос me { posts { author { name } } } для 50 постов запускает 1 + 50 запросов к авторам. Подход с ORM eager load здесь не помогает — потребность в данных разбросана по 50 независимым вызовам резолвера, не сконцентрирована в одном месте запроса. DataLoader — структурный фикс.

Почему ORM eager loading недостаточен для GraphQL

ORM eager loading (includes, select_related, joinedload) работает путём объявления связей в точке построения запроса. Вы пишете один запрос со связями, объявленными заранее. В GraphQL-сервере нет одной точки построения запроса — каждый резолвер запускается независимо для каждого родительского объекта. Нет естественного места сказать “кстати, мне также понадобится автор для всех этих постов.”

Когда 50 резолверов постов каждый вызывает db.user.findUnique({ where: { id: authorId } }), ORM не знает, что все они запрашивают один и тот же тип данных. Он выполняет 50 запросов.

DataLoader решает это, перенося батчинг в scope запроса, а не области запроса к БД.

Как работает DataLoader

Facebook открыл исходники DataLoader в 2015 году вместе с GraphQL.js. Механизм:

1. Экземпляр DataLoader создаётся один раз на запрос (не на вызов).
2. Любой код в запросе вызывает loader.load(id), который возвращает Promise и ставит id в очередь внутри — он не выполняет запрос.
3. Когда текущая синхронная работа заканчивается и event loop достигает следующего тика, loader выполняет один батч-запрос: SELECT * FROM users WHERE id IN (все поставленные в очередь id).
4. Loader распределяет результаты каждому ждущему Promise по порядку.

// Создаётся один раз на запрос (например, в GraphQL context)
const userLoader = new DataLoader(async (ids) => {
  // ids — это батч: все ID, поставленные в очередь с последнего тика
  const users = await db.user.findMany({
    where: { id: { in: ids } },
  });
  // Должен вернуть результаты в том же порядке, что и ids
  return ids.map(id => users.find(u => u.id === id) ?? null);
});

// В резолвере Post — вызывается 50 раз для 50 постов
const resolveAuthor = async (post) => {
  return userLoader.load(post.authorId);
  // НЕ запрашивает сразу — ставит ID в очередь
};
// После того как все 50 резолверов поставили свои ID в очередь,
// DataLoader выполняет один запрос:
// SELECT * FROM users WHERE id IN (1, 2, ..., 50)

Три свойства, которые даёт DataLoader:

1. Автоматический батчинг — множество вызовов load(id) в одном тике event loop становятся одним запросом.
2. Автоматическое кэширование — load(id), вызванный дважды в одном запросе, возвращает кэшированный результат без второго запроса.
3. Request scope — кэш ограничен объектом запроса, поэтому устаревшие данные не утекают между запросами.

GraphQL четырёхуровневый N+1

Форма умножается с глубиной вложенности. Для запроса me { teams { projects { members { name } } } }:

• резолвер teams: 1 запрос
• резолвер projects (на каждую team): N запросов
• резолвер members (на каждый project): N×M запросов
• name: включено в members, нет лишних запросов

Итого без DataLoader: 1 + N + (N×M) запросов. С DataLoader на тип: 4 запроса всего — один на тип на запрос.

// Каждый loader батчит один тип
const teamLoader = new DataLoader(ids => batchLoadTeams(ids));
const projectLoader = new DataLoader(ids => batchLoadProjects(ids));
const memberLoader = new DataLoader(ids => batchLoadMembers(ids));

// Каждый резолвер просто вызывает loader:
const resolveTeams = (user) => teamLoader.load(user.id);
const resolveProjects = (team) => projectLoader.load(team.id);
const resolveMembers = (project) => memberLoader.load(project.id);

Эффект: количество запросов падает в 100–1000 раз в зависимости от глубины fan-out. p99 падает с 1.4 с до ~150 мс для типичного четырёхуровневого запроса.

DataLoader vs ORM eager loading: когда использовать каждый

DataLoader более мощный и более сложный, чем ORM eager loading. Выбирайте по тому, откуда возникают потребности в данных:

• Известная форма в точке запроса → ORM eager loading. Одно объявление, ORM справляется.
• Потребности в данных разбросаны по многим путям кода → DataLoader. Батчит по деревьям резолверов или границам модулей.

Решающий вопрос: “знаю ли я в одном месте кода, что нужны все данные?” Если да — eager load. Если нет — DataLoader.