Học từ Facebook #32: Gộp lời gọi API trong cùng một tick

Một trang danh sách có 12 thẻ người dùng. Mỗi thẻ là một component tự lấy dữ liệu của nó khi mount: fetch('/user/1'), fetch('/user/2')… Code gọn, mỗi component độc lập. Nhưng trình duyệt phải gửi 12 request, mỗi request trả chi phí riêng (header, cookie, hàng đợi ở server), và với HTTP/1.1 thì chỉ chạy song song khoảng 6 cái mỗi host.

Cách quen thuộc là kéo việc lấy dữ liệu lên component cha và gọi một API "lấy nhiều". Đổi lại, component con không còn tự chủ, và API phía server phải có endpoint "lấy nhiều" cho mọi loại dữ liệu.

Facebook giữ được cả hai: component vẫn gọi API riêng lẻ, còn một lớp ở giữa gom các lời gọi phát ra trong cùng một tick thành một request.

▶ Mở demo toàn màn hình ↗ · Sửa code trên StackBlitz ↗ · Xem source trên GitHub ↗

#Facebook làm thế nào?

ApiBatcher nằm trong 107.js, cạnh ApiClient. Đây là phần code gọi Graph API mà facebook.com dùng chung với Facebook JavaScript SDK (các module có tiền tố sdk. như sdk.safelyParseResponse).

#Gom và hẹn giờ

Đổi tên biến cho dễ đọc:

const MAX_BATCH = 50;
const DEFAULT_BATCH_APP_ID = 105440539523;

scheduleBatchCall(...args) {
  const { body, callback, method, relative_url } = ApiBatcher.prepareBatchParams(args);
  const request = { method, relative_url };
  if (body) request.body = body;
  this.requests.push(request);
  this.callbacks.push(callback);
  if (this.requests.length == MAX_BATCH) {
    if (this.timer) clearTimeout(this.timer);
    this.dispatch();                                  // đủ 50: gửi ngay
  } else if (!this.timer) {
    this.timer = setTimeout(() => this.dispatch(), 0); // lời gọi đầu tiên: hẹn cuối tick
  }
}

prepareBatchParams chuẩn hoá từng lời gọi theo định dạng batch của Graph API: bỏ tham số method khỏi URL; với POST thì chuyển toàn bộ query sang body (đã mã hoá dạng a=1&b=2) và chỉ giữ lại trên URL những khoá nằm trong danh sách cho phép.

#Gửi và trả kết quả

dispatch() {
  const requests = this.requests, callbacks = this.callbacks;
  this.requests = []; this.callbacks = []; this.timer = null;

  if (requests.length === 1) {                 // một lời gọi: gửi thẳng, khỏi bọc batch
    const r = requests[0];
    this.executeRequest(r.relative_url, r.method, r.body ? QueryString.decode(r.body) : null, callbacks[0]);
    return;
  }

  this.executeRequest('/', 'POST', {
    batch: requests,
    include_headers: false,                    // không cần header của từng response
    batch_app_id: this.appId || DEFAULT_BATCH_APP_ID,
  }, (response) => {
    if (Array.isArray(response)) {
      response.forEach((item, i) => callbacks[i](safelyParseResponse(item && item.body)));
    } else {
      callbacks.forEach((cb) => cb({ error: { message: 'Fatal: batch call failed.' } }));
    }
  });
}

Vài điều đáng chú ý:

• Khớp theo vị trí. Graph API trả về mảng cùng thứ tự với mảng request, nên callbacks[i] nhận response[i]. Không cần id.
• include_headers: false bỏ header của từng phần tử trong response, response gọn hơn.
• Lỗi từng phần tử không được tách riêng. Mỗi phần tử có code (mã HTTP) và body, nhưng callback chỉ nhận body đã parse. Phần tử lỗi 404 vẫn đi vào callback như dữ liệu bình thường, caller phải tự nhìn vào body.error. Phần tử null (Graph API trả null cho request không chạy được) thì thành safelyParseResponse(undefined).
• Cả batch lỗi (response không phải mảng) thì mọi callback nhận chung một lỗi.

#Lớp bên ngoài: giới hạn số request đồng thời

ApiClient còn một hàng đợi riêng: biến đếm số request đang chạy và giới hạn p. Vượt giới hạn thì request được đẩy vào mảng chờ, xong một request thì lấy cái tiếp theo ra chạy. Giới hạn bằng 0 nghĩa là không giới hạn. Batch và hàng đợi này bổ sung cho nhau: batch giảm số request, hàng đợi chặn số request chạy cùng lúc.

sequenceDiagram
  participant A as "Thẻ 1"
  participant B as "Thẻ 2"
  participant C as "Thẻ 3"
  participant Q as "ApiBatcher"
  participant S as "Graph API"
  A->>Q: "call(/user/1)"
  Q->>Q: "hẹn setTimeout(0)"
  B->>Q: "call(/user/2)"
  C->>Q: "call(/user/3)"
  Note over Q: "hết task hiện tại"
  Q->>S: "POST / batch=[3 lời gọi]"
  S-->>Q: "[res1, res2, res3]"
  Q-->>A: "res1"
  Q-->>B: "res2"
  Q-->>C: "res3"

#Bên trong trình duyệt: "cùng một tick" là bao lâu?

setTimeout(fn, 0) đưa fn vào hàng đợi task. Nó chạy sau khi task hiện tại kết thúc và sau khi mọi microtask (Promise) đã chạy xong. Tức là gom được:

• mọi code đồng bộ trong task hiện tại (một vòng lặp gọi 12 lần, hay React chạy 12 effect của 12 component con trong cùng một lần commit);
• mọi lời gọi phát ra trong các then nối tiếp nhau, vì microtask chạy hết trước khi tới lượt timer.

Nếu dùng queueMicrotask thay cho setTimeout, request đi sớm hơn một chút nhưng chỉ gom được code đồng bộ: lời gọi nằm trong một then phía sau có thể lỡ chuyến. Bản viết lại cho chọn cả hai, mặc định giống Facebook.

Còn một chi tiết về trình duyệt: setTimeout(0) không thật sự là 0ms. Sau vài lần lồng nhau, trình duyệt kẹp tối thiểu 4ms, và tab nền có thể bị giãn tới 1 giây. Với việc gom request thì không sao, nhưng nên biết khi đo.

Về lợi ích: mỗi request HTTP có chi phí cố định (header, cookie, TLS record, xếp hàng ở load balancer và server), không đổi theo kích thước body. Demo giả lập 180ms chi phí cố định cho mỗi request và 6ms cho mỗi lời gọi, cộng giới hạn 6 request song song. Kết quả Playwright trên bản build:

#Viết lại

Phần gom và hẹn giờ:

  function scheduleFlush() {
    if (scheduled) return;
    scheduled = true;
    const myGeneration = generation;
    const run = () => {
      // chuyến này đã bị gửi sớm vì đủ maxBatchSize thì bỏ qua lần hẹn cũ
      if (myGeneration === generation) flush();
    };
    if (schedule === 'microtask') queueMicrotask(run);
    else timer = setTimeout(run, 0);
  }

  function flush() {
    if (timer != null) clearTimeout(timer);
    timer = null;
    scheduled = false;
    generation++;
    const batch = pending;
    pending = [];
    if (batch.length === 0) return;

  return {
    call<T = unknown>(request: BatchRequest): Promise<T> {
      return new Promise<T>((resolve, reject) => {
        pending.push({ request, resolve: resolve as (v: unknown) => void, reject });
        if (pending.length >= maxBatchSize) flush();
        else scheduleFlush();
      });
    },

Phần gửi và trả kết quả về từng lời gọi, có tách lỗi từng phần tử:

    if (slots.length === 1) {
      listeners.forEach((l) => l({ size: 1, mode: 'single' }));
      executeSingle(slots[0]).then(
        (value) => waiters[0].forEach((w) => w.resolve(value)),
        (error) => waiters[0].forEach((w) => w.reject(error)),
      );
      return;
    }

    listeners.forEach((l) => l({ size: slots.length, mode: 'batch' }));
    executeBatch(slots).then(
      (responses) => {
        if (!Array.isArray(responses) || responses.length !== slots.length) {
          const error = new Error('Batch response malformed');
          waiters.flat().forEach((w) => w.reject(error));
          return;
        }
        responses.forEach((response, i) => {
          for (const w of waiters[i]) {
            if (response == null) w.reject(new BatchItemError(0, 'no response for this item'));
            else if (response.code >= 400) w.reject(new BatchItemError(response.code, response.body));
            else w.resolve(parseBody(response.body));
          }
        });
      },
      (error) => waiters.flat().forEach((w) => w.reject(error)),
    );
  }

/**
 * Gộp các lời gọi API phát ra trong cùng một tick thành một request "batch".
 *
 * Ý tưởng từ ApiBatcher (dùng trong ApiClient của Facebook để gọi Graph API):
 * - Lời gọi đầu tiên hẹn setTimeout(0); mọi lời gọi tới trước khi hẹn giờ chạy đi chung chuyến.
 * - Đủ 50 lời gọi thì gửi ngay, không chờ (Graph API nhận tối đa 50 request mỗi batch).
 * - Chuyến chỉ có 1 lời gọi thì gửi thẳng request đó, khỏi bọc batch.
 * - Kết quả trả về là mảng, khớp với lời gọi theo vị trí; cả batch lỗi thì mọi lời gọi cùng lỗi.
 */

export interface BatchRequest {
  method: 'GET' | 'POST' | 'DELETE';
  /** đường dẫn tương đối, vd "/me?fields=name" */
  relativeUrl: string;
  /** body đã mã hoá dạng query string cho POST (giống Graph API batch) */
  body?: string;
}

/** Một phần tử trong mảng kết quả batch. null khi server không chạy được request đó. */
export type BatchItemResponse = { code: number; body: string } | null;

export interface ApiBatcherOptions {
  executeSingle: (request: BatchRequest) => Promise<unknown>;
  executeBatch: (requests: BatchRequest[]) => Promise<BatchItemResponse[]>;
  /** mặc định 50 như bản gốc */
  maxBatchSize?: number;
  /**
   * 'task' (mặc định, như FB): gom tới hết task hiện tại, bắt được cả lời gọi phát ra từ
   * các callback/microtask nối nhau. 'microtask': gửi sớm hơn nhưng chỉ gom được code đồng bộ.
   */
  schedule?: 'task' | 'microtask';
  /** gộp các GET trùng URL trong cùng chuyến thành một (bản gốc không có) */
  dedupeGets?: boolean;
}

export class BatchItemError extends Error {
  constructor(
    public code: number,
    public body: string,
  ) {
    super(`Batch item failed with ${code}`);
  }
}

interface Pending {
  request: BatchRequest;
  resolve: (value: unknown) => void;
  reject: (reason: unknown) => void;
}

function parseBody(body: string): unknown {
  try {
    return JSON.parse(body);
  } catch {
    return body;
  }
}

export function createApiBatcher(options: ApiBatcherOptions) {
  const { executeSingle, executeBatch, maxBatchSize = 50, schedule = 'task', dedupeGets = false } = options;
  let pending: Pending[] = [];
  let scheduled = false;
  let timer: ReturnType<typeof setTimeout> | null = null;
  let generation = 0;
  const listeners = new Set<(info: { size: number; mode: 'single' | 'batch' }) => void>();

  function scheduleFlush() {
    if (scheduled) return;
    scheduled = true;
    const myGeneration = generation;
    const run = () => {
      // chuyến này đã bị gửi sớm vì đủ maxBatchSize thì bỏ qua lần hẹn cũ
      if (myGeneration === generation) flush();
    };
    if (schedule === 'microtask') queueMicrotask(run);
    else timer = setTimeout(run, 0);
  }

  function flush() {
    if (timer != null) clearTimeout(timer);
    timer = null;
    scheduled = false;
    generation++;
    const batch = pending;
    pending = [];
    if (batch.length === 0) return;

    // dedupe: các GET trùng URL dùng chung một chỗ trong batch
    const slots: BatchRequest[] = [];
    const waiters: Pending[][] = [];
    const indexByKey = new Map<string, number>();
    for (const item of batch) {
      const key = item.request.method === 'GET' && dedupeGets ? `GET ${item.request.relativeUrl}` : null;
      const existing = key != null ? indexByKey.get(key) : undefined;
      if (existing !== undefined) {
        waiters[existing].push(item);
        continue;
      }
      if (key != null) indexByKey.set(key, slots.length);
      slots.push(item.request);
      waiters.push([item]);
    }

    if (slots.length === 1) {
      listeners.forEach((l) => l({ size: 1, mode: 'single' }));
      executeSingle(slots[0]).then(
        (value) => waiters[0].forEach((w) => w.resolve(value)),
        (error) => waiters[0].forEach((w) => w.reject(error)),
      );
      return;
    }

    listeners.forEach((l) => l({ size: slots.length, mode: 'batch' }));
    executeBatch(slots).then(
      (responses) => {
        if (!Array.isArray(responses) || responses.length !== slots.length) {
          const error = new Error('Batch response malformed');
          waiters.flat().forEach((w) => w.reject(error));
          return;
        }
        responses.forEach((response, i) => {
          for (const w of waiters[i]) {
            if (response == null) w.reject(new BatchItemError(0, 'no response for this item'));
            else if (response.code >= 400) w.reject(new BatchItemError(response.code, response.body));
            else w.resolve(parseBody(response.body));
          }
        });
      },
      (error) => waiters.flat().forEach((w) => w.reject(error)),
    );
  }

  return {
    call<T = unknown>(request: BatchRequest): Promise<T> {
      return new Promise<T>((resolve, reject) => {
        pending.push({ request, resolve: resolve as (v: unknown) => void, reject });
        if (pending.length >= maxBatchSize) flush();
        else scheduleFlush();
      });
    },
    flush,
    onDispatch(listener: (info: { size: number; mode: 'single' | 'batch' }) => void) {
      listeners.add(listener);
      return () => listeners.delete(listener);
    },
  };
}

Khác bản gốc:

• call() trả Promise thay vì nhận callback.
• Phần tử lỗi (code >= 400) và phần tử null reject riêng lời gọi đó bằng BatchItemError; các lời gọi khác trong cùng batch vẫn thành công. Bản gốc trả body cho mọi phần tử, kể cả phần tử lỗi.
• Response có số phần tử không khớp với số request thì reject tất cả, thay vì gọi lệch callback.
• Có tuỳ chọn dedupeGets: các GET trùng URL trong cùng chuyến chỉ chiếm một chỗ trong batch và dùng chung kết quả.
• Có tuỳ chọn schedule: 'microtask'.

#Đi qua code

1. call() đẩy lời gọi vào pending. Đủ maxBatchSize thì flush() ngay (đồng bộ); chưa đủ thì scheduleFlush().
2. scheduleFlush() chỉ hẹn một lần cho mỗi chuyến. Biến generation để bỏ qua lần hẹn cũ nếu chuyến đó đã bị gửi sớm vì đủ 50 (với queueMicrotask thì không huỷ được lần hẹn, nên cần bộ đếm này).
3. flush() lấy toàn bộ pending ra, dựng mảng slots (request thực sự gửi) và waiters (các lời gọi chờ từng slot; nhiều lời gọi chung một slot khi bật dedupe).
4. Một slot: gọi executeSingle. Nhiều slot: gọi executeBatch rồi duyệt response theo vị trí, resolve hoặc reject từng lời gọi.

Demo dùng đúng mẫu "mỗi thẻ tự gọi API khi mount": mỗi UserCard gọi fetchUser(id) trong useEffect của chính nó. 12 component con chạy effect trong cùng một lần commit, nên 12 lời gọi rơi vào cùng một tick và đi chung một request. Bật "/user/7 trả 404": chỉ hai thẻ của người số 7 báo lỗi, 10 thẻ còn lại vẫn hiện tên. Bật thêm "Gộp GET trùng URL": batch giảm từ 12 xuống 9 lời gọi vì có 3 người xuất hiện hai lần.

#Tại sao không làm cách khác?

Kéo dữ liệu lên cha và gọi API "lấy nhiều"? Hiệu quả nhất, nhưng mọi màn hình phải biết trước con của nó cần gì. Batcher cho phép component con giữ quyền tự lấy dữ liệu mà vẫn không tốn thêm request.

DataLoader (Node.js/GraphQL)? Chính là cùng một ý tưởng, phổ biến ở phía server: gom lời gọi load(key) trong một tick rồi gọi một hàm batchLoad(keys). Khác biệt: DataLoader gom theo key và mặc định có cache theo key; ApiBatcher gom request bất kỳ (method, URL, body) vì Graph API có endpoint batch tổng quát.

HTTP/2 rồi thì cần gì batch? HTTP/2 bỏ giới hạn 6 kết nối và dùng chung một kết nối, nên lợi ích giảm nhiều. Nhưng mỗi request vẫn mang header, cookie, vẫn đi qua middleware xác thực, vẫn tốn một lượt xử lý ở server. Với 50 lời gọi nhỏ, một batch vẫn rẻ hơn.

GraphQL thì sao? GraphQL giải bài toán này ở tầng query: một query lấy nhiều thứ. Relay còn gộp fragment của nhiều component thành một query. ApiBatcher là cách tương tự cho REST.

#Edge case và cạm bẫy

• Lỗi từng phần tử: đừng chỉ kiểm tra lỗi của cả batch. Server batch thường trả 200 cho cả batch dù vài phần tử bên trong lỗi.
• Thứ tự phụ thuộc: các phần tử trong một batch có thể chạy song song phía server. Nếu lời gọi B cần kết quả của A (tạo bài rồi đăng ảnh vào bài), đừng gom chúng chung một batch, hoặc dùng cơ chế phụ thuộc của server (Graph API có depends_on và name cho việc này).
• Một phần tử chậm làm cả batch chậm: cả batch chỉ trả về khi phần tử chậm nhất xong. Đừng gom request "nặng" (xuất báo cáo) chung với request nhẹ.
• Kích thước response: batch 50 phần tử có thể trả về vài MB. Không có phần tử nào hiển thị được cho tới khi cả response về.
• Dedupe chỉ an toàn với GET. POST/DELETE trùng nhau có thể là hai hành động thật (bấm thích hai bài giống URL?), không được gộp.
• Huỷ (AbortSignal) khó làm: một lời gọi trong batch không thể huỷ riêng. Bản viết lại không hỗ trợ; component unmount thì chỉ bỏ qua kết quả (biến alive trong demo).

#Dùng trong dự án

import { createApiBatcher, type BatchRequest } from './apiBatcher';

// server cần một endpoint nhận mảng request và trả mảng response cùng thứ tự
const batcher = createApiBatcher({
  executeSingle: async (r) => {
    const res = await fetch(`/api${r.relativeUrl}`, { method: r.method, body: r.body });
    if (!res.ok) throw new Error(String(res.status));
    return res.json();
  },
  executeBatch: async (requests) => {
    const res = await fetch('/api/batch', { method: 'POST', body: JSON.stringify({ batch: requests }) });
    if (!res.ok) throw new Error(String(res.status));
    return res.json();
  },
  dedupeGets: true,
});

export const getUser = (id: string) =>
  batcher.call<User>({ method: 'GET', relativeUrl: `/users/${id}?fields=name,avatar` });

Dùng chung với TanStack Query: đặt getUser làm queryFn. Query lo cache và dedupe theo key, batcher lo gom các query khác nhau vào một request.

#Kiểm thử

import { describe, expect, it, vi } from 'vitest';
import { BatchItemError, createApiBatcher, type BatchRequest } from './apiBatcher';

const get = (id: number): BatchRequest => ({ method: 'GET', relativeUrl: `/user/${id}` });
const ok = (reqs: BatchRequest[]) => reqs.map((r) => ({ code: 200, body: JSON.stringify({ url: r.relativeUrl }) }));

describe('createApiBatcher', () => {
  it('các lời gọi trong cùng một tick đi chung một batch, kết quả khớp theo vị trí', async () => {
    const executeBatch = vi.fn(async (reqs: BatchRequest[]) => ok(reqs));
    const batcher = createApiBatcher({ executeSingle: vi.fn(), executeBatch });
    const results = await Promise.all([1, 2, 3].map((id) => batcher.call(get(id))));
    expect(executeBatch).toHaveBeenCalledTimes(1);
    expect(results).toEqual([{ url: '/user/1' }, { url: '/user/2' }, { url: '/user/3' }]);
  });

  it('chỉ một lời gọi thì gửi thẳng, không bọc batch', async () => {
    const executeSingle = vi.fn(async () => ({ id: 1 }));
    const executeBatch = vi.fn();
    const batcher = createApiBatcher({ executeSingle, executeBatch });
    await batcher.call(get(1));
    expect(executeSingle).toHaveBeenCalledTimes(1);
    expect(executeBatch).not.toHaveBeenCalled();
  });

  it('đủ 50 lời gọi thì gửi ngay, phần dư đi chuyến sau', async () => {
    const sizes: number[] = [];
    const batcher = createApiBatcher({
      executeSingle: vi.fn(),
      executeBatch: async (reqs) => {
        sizes.push(reqs.length);
        return ok(reqs);
      },
    });
    const calls = Array.from({ length: 120 }, (_, i) => batcher.call(get(i)));
    expect(sizes).toEqual([50, 50]); // hai chuyến đầu đi ngay, đồng bộ
    await Promise.all(calls);
    expect(sizes).toEqual([50, 50, 20]);
  });

  it('một phần tử lỗi chỉ làm hỏng lời gọi đó; cả batch lỗi thì mọi lời gọi cùng lỗi', async () => {
    const batcher = createApiBatcher({
      executeSingle: vi.fn(),
      executeBatch: async (reqs) => reqs.map((r, i) => (i === 1 ? { code: 404, body: '{}' } : { code: 200, body: `"${r.relativeUrl}"` })),
    });
    const [a, b] = await Promise.allSettled([batcher.call(get(1)), batcher.call(get(2))]);
    expect(a).toEqual({ status: 'fulfilled', value: '/user/1' });
    expect(b.status === 'rejected' && b.reason).toBeInstanceOf(BatchItemError);

    const broken = createApiBatcher({ executeSingle: vi.fn(), executeBatch: () => Promise.reject(new Error('500')) });
    const settled = await Promise.allSettled([broken.call(get(1)), broken.call(get(2))]);
    expect(settled.map((s) => s.status)).toEqual(['rejected', 'rejected']);
  });

  it('dedupeGets: GET trùng URL chỉ chiếm một chỗ trong batch', async () => {
    const executeBatch = vi.fn(async (reqs: BatchRequest[]) => ok(reqs));
    const batcher = createApiBatcher({ executeSingle: vi.fn(), executeBatch, dedupeGets: true });
    const [x, y] = await Promise.all([batcher.call(get(7)), batcher.call(get(7)), batcher.call(get(8))]);
    expect(executeBatch.mock.calls[0][0]).toHaveLength(2);
    expect(x).toEqual(y);
  });
});

#So với thư viện và chuẩn web

• Graph API batch là tính năng công khai: POST tới / với tham số batch là mảng request, tối đa 50 request mỗi batch. Chính là định dạng ApiBatcher gửi đi.
• DataLoader (thư viện do Facebook mở mã nguồn, dùng nhiều trong server GraphQL) gom theo key: lô được gửi sau khi các Promise đang chờ đã chạy xong (trong Node dùng process.nextTick), nên gom được cả lời gọi phát ra từ các then nối tiếp.
• Apollo Client có BatchHttpLink gom nhiều GraphQL operation trong một khoảng thời gian (batchInterval, mặc định 10ms) vào một request; Relay thì gộp ở tầng query.
• Không có API trình duyệt nào gom request hộ bạn; HTTP/2 và HTTP/3 chỉ làm request rẻ hơn, không làm chúng biến mất.

Bài này thuộc series Học từ mã nguồn Facebook (106 bài, đọc theo thứ tự).

Code + demo: examples/facebook-patterns · Mở trên StackBlitz