Механика DataLoader: батчинг на границе тика

Что делает DataLoader

DataLoader — небольшая библиотека, изначально извлечённая из реализации GraphQL в Facebook и поддерживаемая GraphQL Foundation. Конструктор: new DataLoader(batchLoadFn, options), где batchLoadFn(keys: Array<K>): Promise<Array<V | Error>> — твой батчевый fetcher (функция пакетной загрузки).

Резолверы вызывают loader.load(key) и получают Promise. Под капотом — вот что стоит понять, прежде чем трогать любой production DataLoader:

1. Каждый .load(key) ставит ключ во внутренний массив. Запрос ещё не выполняется.
2. Когда текущий синхронный шаг JavaScript заканчивается — когда очередь микротасок начинает сливаться — DataLoader берёт все накопленные ключи и вызывает batchLoadFn один раз со всем массивом.
3. batchLoadFn выполняет один WHERE id IN (...) и возвращает значения в том же порядке, что входные ключи.
4. DataLoader разрешает каждый ожидающий Promise его значением.

Граница тика — естественная точка склейки: движок GraphQL заканчивает обход одного уровня запроса синхронно. Все 50 вызовов резолвера Post.author ставят ID в очередь во время обхода этого уровня. Микротаска DataLoader срабатывает после — когда все ID уже накоплены.

Почему фиксированное временное окно было бы хуже

Буфер в 5 мс либо добавил бы 5 мс латентности к каждому запросу (ненужное ожидание), либо сработал бы слишком рано под нагрузкой (не захватив все ID). Граница тика срабатывает в самый ранний возможный момент, когда все ID для текущего уровня уже в очереди — без лишнего ожидания.

Тик event loop (GraphQL разрешает уровень 2):
  Post.author(post1) → loader.load(7)   // в очереди
  Post.author(post2) → loader.load(9)   // в очереди
  Post.author(post3) → loader.load(7)   // деdup: уже в очереди

Микротаска (тик кончился):
  batchLoadFn([7, 9])
  → SELECT id, name FROM users WHERE id IN (7, 9)
  → разрешает: 7→Bea, 9→Sven

Все три Post.author Promise разрешаются: post1→Bea, post2→Sven, post3→Bea

Дедупликация внутри одного запроса

Если loader.load(7) вызывается дважды в одном запросе, DataLoader возвращает тот же Promise — ключ появляется в батче только один раз. Это полезно, когда одна сущность доступна по нескольким путям в документе (например, автор поста и автор комментария — один и тот же user). Отключается через options.cache = false для резолверов, которым нужны свежие чтения внутри одного запроса (редко: паттерн write-after-read).

Правило per-request инстанса

DataLoader-инстанс — это кеш. Его время жизни должно быть request, не процесс. Модульно-скоупленный DataLoader, разделённый между всеми запросами:

• Возвращает stale-данные: Request A грузит user 7, строка обновляется, Request B грузит user 7 из кеша и получает pre-update строку.
• Утекает между арендаторами: Request A и B принадлежат разным tenant’ам. Tenant B получает закешированную строку Tenant A для того же ID.

Дисциплина: создавай DataLoader внутри фабрики request-context (функция, которую Apollo Server вызывает на каждый запрос), прикрепляй к context, дай GC почистить по окончании запроса.

// Фабрика context Apollo Server — правильно
context: async ({ req }) => ({
  loaders: {
    author: new DataLoader(batchAuthors),
    tags:   new DataLoader(batchTags),
  },
})

// Резолвер — правильно
Post: {
  author: (post, _args, ctx) => ctx.loaders.author.load(post.authorId),
}