Потоковая отдача: страница приходит частями

В прошлой статье данные брались await прямо в компоненте, и это оказалось короче и честнее, чем эффект с запросом. У приёма есть цена, и видна она не на одном запросе, а на настоящей странице товара.

// app/product/page.tsx — серверный компонент: в песочнице он не выполняется,
// но компилятор его проверяет как обычно
interface Rating {
  score: number;
  count: number;
}

async function loadTitle(): Promise<string> {
  return "Кофеварка X200";
}

// оценка считается по всей базе отзывов — почти секунда
async function loadRating(): Promise<Rating> {
  return { score: 4.7, count: 812 };
}

async function ProductPage() {
  // запросы уходят разом, водопада здесь нет — узкое место не в этом
  const [title, rating] = await Promise.all([loadTitle(), loadRating()]);
  return (
    <main>
      <h1>{title}</h1>
      <p>
        {rating.score} из 5 по {rating.count} отзывам
      </p>
    </main>
  );
}

Запросы здесь уходят разом, водопада нет — и всё равно страница целиком заперта самым медленным из них. Компонент — это функция: пока она не вернула разметку, возвращать нечего, а значит, и отправлять в браузер нечего. Шапка, меню и название готовы через несколько миллисекунд, но ждут почти секунду вместе с оценкой.

Правый столбец — это и есть потоковая отдача. Ничего нового в React для неё не появилось: линия отрыва — тот же <Suspense>, что вы ставили в браузере. Меняется только то, что происходит на границе: вместо «показать заглушку в DOM» сервер отдаёт заглушку в первом куске ответа, а готовый блок дошлёт тем же соединением.

Файл loading.tsx из главы про Next — ровно такая граница, поставленная фреймворком вокруг всего сегмента: либо весь сегмент ждёт, либо весь сегмент показан. Дальше речь о нарезке помельче — внутри одной страницы.

Числа в таблице условные, а соотношение типичное: шапка и текст готовы почти мгновенно, а секунду отнимает один-два блока, ради которых читатель обычно и не пришёл.

HTTP-ответ — не файл, а поток байтов: сервер вправе начать его отдавать, ещё не зная, чем закончит. На этом всё и держится. React отправляет первую порцию, как только готова оболочка — всё дерево за вычетом приостановленных мест. На месте каждой границы в разметке стоит её fallback и невидимая метка с адресом.

Вот что уходит в браузер у страницы товара, под границами которой стоят оценки и «похожие товары». Это не пересказ документации: так выглядит поток настоящего серверного рендера React 19, если записать его кусками с отметками времени.

Заметьте порядок: блок, который в разметке стоит вторым, ушёл первым — просто потому, что раньше досчитался. Куски адресованы, поэтому порядок на проводе роли не играет. Соберём эту сборку сами.

// Модель провода: у каждой границы есть адрес и содержимое.
// Сначала уходит оболочка с заглушками, потом — куски по мере готовности.
type Chunk = { at: number; slot: string; html: string };

const page = new Map<string, string>([
  ["B:0", "Считаем оценки…"],
  ["B:1", "Ищем похожее…"],
]);

const stream: Chunk[] = [
  { at: 300, slot: "B:1", html: "3 похожих товара" },
  { at: 900, slot: "B:0", html: "4.7 из 5" },
];

const show = () => [...page].map(([slot, html]) => slot + " → " + html).join(" | ");

console.log("0 мс:  ", show());
for (const chunk of stream) {
  page.set(chunk.slot, chunk.html);
  console.log(chunk.at + " мс:", show());
}

Три состояния одной и той же страницы. Важное в первом: страница уже полная — в ней есть все места, просто два из них заняты заглушками. Читатель видит осмысленный экран, пока сервер ещё считает.

Поток рвётся снаружи: прокси или CDN, который буферизует ответ целиком, сложит все куски вместе и отдаст их разом — выигрыш исчезнет, а код останется правильным. Это первое, что стоит проверять, если в проде поток «не работает».

Первая и самая частая ошибка выглядит абсолютно разумно: страница берёт данные, как раньше, а медленный блок на всякий случай обёрнут границей. В песочнице сервера нет, но приостановка работает точно так же, поэтому опыт ставится честно. Заглушка живёт отдельным компонентом и печатает, когда её показали. Предскажите: сколько строк будет в выводе и какие?

// сети в песочнице нет, поэтому «медленный запрос» — это таймер
function after<T>(value: T, ms: number): Promise<T> {
  return new Promise<T>((resolve) => {
    setTimeout(() => resolve(value), ms);
  });
}

const started = Date.now();
const at = () => Math.round((Date.now() - started) / 100) * 100;

const titlePromise = after("Кофеварка X200", 100);
const ratingPromise = after("4.7 из 5 по 812 отзывам", 900);

function Skeleton() {
  console.log("заглушка на экране, мс:", at());
  return <p>Считаем оценки…</p>;
}

function Rating({ text }: { text: string }) {
  return <p>{text}</p>;
}

function ProductPage() {
  const title = React.use(titlePromise);
  const rating = React.use(ratingPromise);
  console.log("страница на экране, мс:", at());
  return (
    <div>
      <h1>{title}</h1>
      <React.Suspense fallback={<Skeleton />}>
        <Rating text={rating} />
      </React.Suspense>
    </div>
  );
}

ReactDOM.createRoot(document.getElementById("root")!).render(<ProductPage />);

Одна строка, и та на девятисотой миллисекунде. Заглушка не печаталась вовсе — её никто не рисовал. Приостановка ищет ближайшую границу вверх по дереву, а обёртка стоит внутри того самого компонента, который приостановился: до неё дело просто не дошло. Всё, что ниже use, — включая <Suspense> — существует только после того, как ожидание закончилось.

Лечится это не обёрткой, а переносом ожидания. Медленное чтение уезжает в отдельный компонент, и граница оказывается над ним, а не под.

function after<T>(value: T, ms: number): Promise<T> {
  return new Promise<T>((resolve) => {
    setTimeout(() => resolve(value), ms);
  });
}

const started = Date.now();
const at = () => Math.round((Date.now() - started) / 100) * 100;

const titlePromise = after("Кофеварка X200", 100);
const ratingPromise = after("4.7 из 5 по 812 отзывам", 900);

function Skeleton() {
  console.log("заглушка на экране, мс:", at());
  return <p>Считаем оценки…</p>;
}

function Rating() {
  const text = React.use(ratingPromise);
  console.log("оценки на экране, мс:", at());
  return <p>{text}</p>;
}

function ProductPage() {
  const title = React.use(titlePromise);
  console.log("страница на экране, мс:", at());
  return (
    <div>
      <h1>{title}</h1>
      <React.Suspense fallback={<Skeleton />}>
        <Rating />
      </React.Suspense>
    </div>
  );
}

ReactDOM.createRoot(document.getElementById("root")!).render(<ProductPage />);

Теперь строк три: страница и её заглушка — на сотой миллисекунде, оценки — на девятисотой. Разметка не изменилась ни на символ, изменилось место, где написано слово ожидания.

На сервере правка выглядит так же — только слово ожидания другое, await вместо use.

// app/product/page.tsx — та же правка на сервере: медленное ожидание
// уехало в отдельный компонент, а страница о нём больше не знает
interface Rating {
  score: number;
  count: number;
}

async function loadRating(): Promise<Rating> {
  return { score: 4.7, count: 812 };
}

async function RatingBlock() {
  const rating = await loadRating();
  return (
    <p>
      {rating.score} из 5 по {rating.count} отзывам
    </p>
  );
}

function ProductPage() {
  return (
    <main>
      <h1>Кофеварка X200</h1>
      <React.Suspense fallback={<p>Считаем оценки…</p>}>
        <RatingBlock />
      </React.Suspense>
    </main>
  );
}

Правило запоминается одной фразой: всё, что стоит выше границы, задерживает первый кусок. Поэтому в серверной странице await оставляют только для того, без чего оболочку не собрать, — а остальное уезжает в собственный компонент под <Suspense>.

Расставлять границы вы умеете со статьи про use(). Здесь важно другое — что происходит, когда границ несколько, а данные приходят вразнобой. Три блока, у каждого своя граница, в разметке они стоят от самого медленного к самому быстрому. Предскажите обе части вывода: порядок прибытия и порядок на странице.

// три части страницы, каждая под своей границей
function after<T>(value: T, ms: number): Promise<T> {
  return new Promise<T>((resolve) => {
    setTimeout(() => resolve(value), ms);
  });
}

const started = Date.now();
const at = () => Math.round((Date.now() - started) / 100) * 100;

const reviews = after("отзывы", 900);
const related = after("похожие товары", 600);
const price = after("цена", 300);

function Part({ from }: { from: Promise<string> }) {
  const text = React.use(from);
  console.log("дошло:", text, at());
  return <li>{text}</li>;
}

function Page() {
  return (
    <ul id="page">
      <React.Suspense fallback={<li>отзывы…</li>}>
        <Part from={reviews} />
      </React.Suspense>
      <React.Suspense fallback={<li>похожие…</li>}>
        <Part from={related} />
      </React.Suspense>
      <React.Suspense fallback={<li>цена…</li>}>
        <Part from={price} />
      </React.Suspense>
    </ul>
  );
}

ReactDOM.createRoot(document.getElementById("root")!).render(<Page />);

setTimeout(() => {
  const list = document.getElementById("page")!;
  const order = Array.from(list.children, (item) => item.textContent).join(" / ");
  console.log("на странице:", order);
}, 1200);

Пришли в обратном порядке — 300, 600, 900, — а на странице встали ровно так, как записаны в разметке. Место каждого блока всё это время держала его заглушка, и приехавший кусок занял именно его, а не пристроился в конец. Поэтому потоковая страница не прыгает: заполняются дырки, а не добавляются строки.

Это и есть ответ на вопрос, зачем в каждом куске адрес. Сервер не выстраивает блоки в очередь и не ждёт «своего» порядка: досчитал — отправил, а расставит их браузер.

Раз порядок значения не имеет, остаётся один настоящий вопрос — что именно резать.

Заглушка должна занимать примерно столько же места, сколько займёт готовый блок: иначе в момент подстановки страница дёрнется и читатель промахнётся мимо кнопки. Скелет по размеру блока лучше строчки «Загрузка…».

У потока есть свойство, о котором вспоминают поздно и больно. Код ответа и заголовки — это самые первые байты, они уходят раньше разметки. Как только первый кусок покинул сервер, менять в них нечего: они уже в сети.

Отсюда практическое правило, которое стоит помнить целиком: всё, от чего зависит код ответа, решается выше границы. Проверка «есть ли такой товар» — до <Suspense>, в самой странице; «сколько у него отзывов» — под границей, сколько угодно медленно.

С ошибками то же самое, только мягче. Упавший компонент под границей никуда поток не роняет: error.tsx из главы про App Router поймает ошибку, и его разметка дошлётся обычным куском, встанет на место заглушки. Читатель увидит аккуратный блок «не удалось загрузить отзывы» вместо оборванной страницы — а код ответа останется тем, что ушёл первым куском.

Отладка потока начинается с curl -N — без буферизации: если куски печатаются по одному, с паузами, сервер работает правильно и разбираться нужно с прокси. Браузерная вкладка «Сеть» показывает уже собранный ответ и в этом вопросе не помощник.