Next.js Middleware: перехоплення запитів та прикордонна логіка (Edge)

Навіщо це потрібно: проблематика та архітектурний контекст#

У промисловій розробці критично важливо контролювати вхідний трафік до того, як ресурси сервера додатків будуть витрачені на рендеринг компонентів або виконання ресурсомістких обчислень:

• Захист закритих сегментів (Auth Guards): Централізована перевірка токенів сесій без дублювання авторизаційних перевірок у кожній сторінці.
• Географічна маршрутизація та локалізація: Визначення країни, мови та регіону користувача за заголовками CDN (x-vercel-ip-country) з перенаправленням на відповідний префікс.
• Ін'єкція заголовків інформаційної безпеки: Централізоване встановлення Content Security Policy (CSP) з генерацією одноразових криптографічних токенів (nonces) та HSTS.
• Мультитенантна маршрутизація та A/B-експерименти: Проксіювання запитів субдоменів на внутрішні папки сегментів без зміни видимого URL для користувача.

Next.js вирішує ці завдання через спеціальний шлюзовий механізм — Next.js Middleware. Це код, що виконується на прикордонних CDN-вузлах (Edge Network) для кожного вхідного HTTP-запиту до вирішення дерева маршрутів і перевірки серверного кешу.

Ментальна модель: Edge Network та конвеєр виконання#

Файл middleware.ts оголошується суворо в корені проєкту (на одному рівні з директоріями app або src).

Ключова архітектурна особливість Middleware в Next.js — виконання в Edge Runtime. Це ізольована пісочниця на базі движка V8 з доступом до стандартних Web API (fetch, Request, Response, Web Crypto, Headers), але без нативних системних бібліотек Node.js (fs, child_process, TCP-сокетів).

За рахунок роботи на периферії мережі Middleware забезпечує запуск швидше 10 мс, виконуючи фільтрацію запитів ще до того, як пакет даних досягне основного дата-центру.

Алгоритм виконання та життєвий цикл (Runtime Execution)#

Синтаксис та API: контракти Edge Runtime#

1. Базова структура та конфігурація Matcher#

Файл middleware.ts експортує функцію middleware та об'єкт конфігурації config.matcher:

import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
  const token = request.cookies.get('session_token')?.value;

  // Авторизаційний гард для закритих розділів
  if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {
    const loginUrl = new URL('/login', request.url);
    loginUrl.searchParams.set('from', request.nextUrl.pathname);
    return NextResponse.redirect(loginUrl);
  }

  return NextResponse.next();
}

// Конфігурація шляхів, на яких повинен спрацьовувати Middleware
export const config = {
  matcher: [
    /*
     * Виключаємо службові шляхи для оптимізації продуктивності:
     * - api (якщо не потрібен глобальний middleware)
     * - _next/static (статичні JS/CSS файли)
     * - _next/image (оптимізовані зображення)
     * - favicon.ico, sitemap.xml, robots.txt
     */
    '/((?!api|_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
  ],
};

2. Мутація заголовків запиту для передачі в Server Components#

Next.js дозволяє збагачувати вхідний запит додатковими заголовками (наприклад, інжектувати ідентифікатор користувача або криптографічний nonce для CSP):

import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
  // Клонуємо заголовки вхідного запиту
  const requestHeaders = new Headers(request.headers);
  requestHeaders.set('x-gateway-timestamp', Date.now().toString());
  requestHeaders.set('x-client-ip', request.ip ?? 'unknown');

  // Передаємо змінені заголовки в серверні компоненти
  return NextResponse.next({
    request: {
      headers: requestHeaders,
    },
  });
}

Практичні патерни: архітектурна організація#

Патерн: Мультитенантна маршрутизація через rewrite#

Патерн побудови SaaS-платформ, де клієнт відкриває адресу company.platform.com, а сервер непомітно перенаправляє запит на сегмент app/tenants/[tenant]/page.tsx:

import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
  const hostname = request.headers.get('host') ?? '';
  const pathname = request.nextUrl.pathname;

  // Витягуємо субдомен (наприклад, acme.platform.com -> acme)
  const currentHost = hostname.replace(`.${process.env.NEXT_PUBLIC_ROOT_DOMAIN}`, '');

  // Якщо це субдомен, проксіюємо на внутрішній сегмент
  if (currentHost && currentHost !== 'www' && currentHost !== 'localhost:3000') {
    return NextResponse.rewrite(
      new URL(`/tenants/${currentHost}${pathname}`, request.url)
    );
  }

  return NextResponse.next();
}

Поширені помилки: граничні збої та безпека#

Питання на співбесіді: Staff / Lead рівень#