Мимо страниц: route.ts и proxy.ts

В папке app адрес занимает файл page.tsx — это вы знаете из статьи «App Router: адрес — это папка». Рядом с ним есть второе зарезервированное имя: route.ts. Оно тоже забирает себе адрес папки, но отвечает не деревом React, а тем, что вы вернули: JSON, текстом, файлом, пустотой с кодом статуса.

Обработчик — обычная функция. Она принимает Request и возвращает Response: те самые объекты веб-платформы, которые вы видели с другой стороны провода в статье про fetch. Никакого res.send и никакого фреймворкового объекта ответа здесь нет.

В настоящем route.ts перед функцией стоит export. Песочница выполняет один файл без модулей, поэтому в примерах это слово опущено — во всём остальном код тот же.

// app/api/search/route.ts
function GET(request: Request): Response {
  const { searchParams } = new URL(request.url);
  const q = searchParams.get("q") ?? "";
  // Response.json сам сериализует объект: JSON.stringify не нужен
  return Response.json({ q, found: q.length > 0 });
}

// Next зовёт обработчик ровно так же: строит Request и ждёт Response.
// Значит, его можно позвать руками — что мы и делаем
const answer = GET(new Request("https://example.com/api/search?q=react"));
console.log(answer.status, answer.headers.get("content-type"));
answer.json().then((data) => console.log(data));

Статус 200 и заголовок content-type никто не выставлял — их поставил Response.json. И обратите внимание на последние две строки примера: обработчик вызван напрямую, без сервера, без Next, без сети. Это не поблажка песочницы, а суть route.ts — там лежит функция, которую можно вызвать и протестировать как любую другую.

const data = { tasks: 2 };
const manual = new Response(JSON.stringify(data));
const helper = Response.json(data);
console.log("вручную:", manual.headers.get("content-type"));
console.log("через json:", helper.headers.get("content-type"));

В одной папке эти два имени не уживаются: адрес у папки один, и делить его не с кем. Документация Next формулирует это без оговорок: «There cannot be a route.js file at the same route as page.js». Поэтому обработчики обычно держат отдельным поддеревом app/api/…, где страниц нет вовсе.

И ещё одно, о чём стоит знать заранее: обработчик по умолчанию динамический. В таблице сборки он помечен ƒ — Dynamic, то есть выполняется на каждый запрос. Статическим ответ становится, только если попросить об этом явно: export const dynamic = "force-static", revalidate или 'use cache' — про это две предыдущие статьи главы.

Своему же интерфейсу отдельный /api в App Router чаще всего не нужен: данные серверный компонент читает прямо в себе (await вместо useEffect), а изменения делают Server Actions. route.ts остаётся там, где клиент — не ваша страница: вебхук чужого сервиса, публичный API, выгрузка файла, ответ монитору «жив».

Экспортов в файле может быть несколько, и имя функции — это и есть метод запроса. Next знает семь имён: GET, HEAD, OPTIONS, POST, PUT, DELETE, PATCH. Функция с любым другим именем просто не будет никем вызвана.

Имена строго прописными. Экспорт get вместо GET в режиме разработки даёт ошибку в консоли сервера: «Detected lowercase method 'get'… Export the uppercase 'GET' method name to fix this error». А export default, обязательный для page.tsx, здесь запрещён — на него Next отвечает «Export a named export for each HTTP method instead».

Интереснее другое: что случится с методом, которого вы не написали? Ответ Next достраивает сам, и правила у него ровно такие, как в примере ниже.

type Handler = (request: Request) => Response;

// route.ts глазами Next: объект из того, что файл экспортировал.
// Здесь экспортирован один GET — про остальные методы файл молчит
const userland: Record<string, Handler | undefined> = {
  GET: () => Response.json({ tasks: ["купить хлеб"] })
};

const METHODS = ["GET", "HEAD", "OPTIONS", "POST", "PUT", "DELETE", "PATCH"];

function resolve(method: string): Handler {
  const own = userland[method];
  if (own) return own;
  // HEAD — это GET без тела, поэтому его берут у GET
  if (method === "HEAD" && userland.GET) return userland.GET;
  if (method === "OPTIONS") {
    const allow = METHODS.filter((name) => userland[name] !== undefined);
    if (allow.includes("GET")) allow.push("HEAD");
    allow.push("OPTIONS");
    const headers = { Allow: allow.sort().join(", ") };
    return () => new Response(null, { status: 204, headers });
  }
  return () => new Response(null, { status: 405 });
}

for (const method of ["GET", "HEAD", "POST", "OPTIONS"]) {
  const response = resolve(method)(new Request("https://example.com/api/tasks", { method }));
  console.log(method, response.status, response.headers.get("allow") ?? "—");
}

Ненаписанный метод получает 405 Method Not Allowed, а не 404: адрес существует, просто так с ним разговаривать нельзя. HEAD Next подставляет из GET, а OPTIONS отвечает сам — пустым телом, кодом 204 и заголовком Allow, в котором перечислено всё, что этот адрес принимает. Ни одной из этих строк в вашем файле нет.

Метод, которого нет в списке семи, до вашего файла вообще не доходит: на какой-нибудь PROPFIND Next отвечает 400 сам — произвольному имени из запроса нечего делать в диспетчере.

У Request те же методы чтения, что вы вызывали у ответа на клиенте: await request.json(), await request.text(), await request.formData(). Всё, что пришло по сети, — это unknown, и разбирать его нужно самому: тип на границе программы вы уже проходили в статье «Данные извне — это unknown».

type NewTask = { title?: unknown };

async function POST(request: Request): Promise<Response> {
  const body = (await request.json()) as NewTask;
  const title = typeof body.title === "string" ? body.title.trim() : "";
  if (title === "") {
    // ошибка клиента — это код ответа, а не текст «что-то пошло не так»
    return Response.json({ error: "нужно поле title" }, { status: 422 });
  }
  return Response.json({ id: 7, title }, { status: 201, headers: { Location: "/api/tasks/7" } });
}

function ask(payload: unknown): Request {
  return new Request("https://example.com/api/tasks", {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify(payload)
  });
}

async function main() {
  const good = await POST(ask({ title: "купить хлеб" }));
  console.log(good.status, good.headers.get("location"), await good.json());
  const bad = await POST(ask({ title: "   " }));
  console.log(bad.status, await bad.json());
}
void main();

Второй аргумент Response.json — обычный ResponseInit: статус и заголовки. 201 означает «создано», 422 — «данные пришли, но они негодные». Клиенту этого достаточно, чтобы отличить свою ошибку от вашей, не разбирая текст.

А теперь самая частая поломка в обработчиках. Разработчик добавляет строку «посмотреть, что пришло» — и всё перестаёт работать. Предскажите, что напечатает пример.

async function POST(request: Request): Promise<Response> {
  console.log("пришло:", await request.text());
  const body = await request.json();
  return Response.json(body, { status: 201 });
}

async function main() {
  const request = new Request("https://example.com/api/tasks", {
    method: "POST",
    body: JSON.stringify({ title: "хлеб" })
  });
  try {
    const response = await POST(request);
    console.log(response.status);
  } catch (error) {
    console.log("упало:", (error as Error).name);
  }
}
void main();

Тело запроса — поток, и вычерпать его можно один раз. Первое чтение забрало всё, второму не досталось ничего. Текст сообщения у каждого движка свой, а тип один — TypeError. Лечится тем же, чем и любое двойное чтение: читаем один раз, а дальше работаем со строкой — const raw = await request.text(), затем JSON.parse(raw). Если нужны именно два независимых чтения, есть request.clone(), но обычно это признак того, что код стоит перечитать.

async function POST(request: Request): Promise<Response> {
  let data: unknown;
  try {
    // тело пришло из сети: разбор может провалиться, и это не наша вина
    data = await request.json();
  } catch {
    return Response.json({ error: "тело не разобралось как JSON" }, { status: 400 });
  }
  return Response.json({ got: data }, { status: 201 });
}

async function main() {
  const broken = new Request("https://example.com/api/tasks", { method: "POST", body: "{не json" });
  const response = await POST(broken);
  console.log(response.status, await response.json());
}
void main();

Если на адрес отправляют форму — например, обычный <form action="/api/tasks"> без единой строчки JS, — тело читают через request.formData(). Это тот же объект FormData, что вы разбирали в статье про неуправляемые поля.

Квадратные скобки в имени папки работают у обработчиков так же, как у страниц: app/api/tasks/[id]/route.ts отвечает на /api/tasks/7. Сегмент приезжает вторым аргументом — в объекте контекста. И там его ждёт ровно та же ловушка, что в статье про динамические сегменты.

// app/api/tasks/[id]/route.ts
type Context = { params: Promise<{ id: string }> };

async function GET(request: Request, context: Context): Promise<Response> {
  const id = context.params.id;
  return Response.json({ id });
}

async function main() {
  const response = await GET(
    new Request("https://example.com/api/tasks/7"),
    { params: Promise.resolve({ id: "7" }) }
  );
  console.log(response.status, await response.json());
}
void main();

Диагностика показывает главное: params — промис, а не объект. Но посмотрите на вывод: код всё равно выполнился и ответил 200. id оказался undefined, JSON.stringify молча выбросил такое поле — и клиент получил бодрое «всё хорошо» с пустым телом. От такого ответа вас отделяла ровно одна диагностика компилятора.

// app/api/tasks/[id]/route.ts
type Context = { params: Promise<{ id: string }> };

async function GET(request: Request, context: Context): Promise<Response> {
  const { id } = await context.params;
  // сегмент адреса — всегда строка: то, что в нём число, надо проверить
  if (!/^\d+$/.test(id)) {
    return Response.json({ error: "id должен быть числом" }, { status: 400 });
  }
  return Response.json({ id: Number(id) });
}

async function main() {
  const url = "https://example.com/api/tasks/";
  const ok = await GET(new Request(url + "7"), { params: Promise.resolve({ id: "7" }) });
  console.log(ok.status, await ok.json());
  const bad = await GET(new Request(url + "abc"), { params: Promise.resolve({ id: "abc" }) });
  console.log(bad.status, await bad.json());
}
void main();

Тип контекста можно не писать руками: next typegen раскладывает по проекту глобальный RouteContext, и для нашей папки это RouteContext<"/api/tasks/[id]"> — имена сегментов он берёт из дерева папок, а не из вашей памяти.

Есть код, которому нужно выполниться раньше всех маршрутов: увести неавторизованного на /login, перенаправить старые адреса, подмешать заголовок, выбрать вариант A/B-теста. В Next до шестнадцатой версии это был файл middleware.ts; в Next 16 он называется proxy.ts, а функция внутри — proxy. Лежит он в корне проекта (или в src) рядом с папкой app, а не внутри неё.

Переименование — не косметика, а уточнение смысла. «Middleware» звучало как слой приложения, куда можно положить бизнес-логику; на деле это привратник на входе, который смотрит на запрос до того, как Next решит, кто будет отвечать. Порядок такой:

Четвёртый шаг — это и есть «выбор маршрута». Всё, что делает proxy.ts, происходит до него: обработчик из route.ts в этот момент ещё даже не выбран.

// proxy.ts в корне проекта, рядом с app
function proxy(request: Request): Response | undefined {
  const url = new URL(request.url);
  const token = request.headers.get("authorization");
  if (url.pathname.startsWith("/admin") && token === null) {
    // 307 сохраняет метод: POST после редиректа останется POST
    return Response.redirect(new URL("/login", url), 307);
  }
  // ничего не вернули — запрос идёт дальше, к странице или к route.ts
  return undefined;
}

const requests = [
  new Request("https://example.com/"),
  new Request("https://example.com/admin"),
  new Request("https://example.com/admin/users", { headers: { authorization: "Bearer 123" } })
];

for (const request of requests) {
  const answer = proxy(request);
  const path = new URL(request.url).pathname;
  console.log(path, answer ? answer.status + " -> " + answer.headers.get("location") : "пропущен");
}

Вернули Response — на этом всё, ответ уходит клиенту и до маршрута дело не доходит. Не вернули ничего — запрос идёт дальше своим чередом. В настоящем proxy.ts вместо голого Response обычно берут NextResponse из next/server: NextResponse.redirect(url), NextResponse.rewrite(url) и NextResponse.next() — то же самое плюс удобная работа с куками и заголовками. Первый аргумент функции тогда типизируют как NextRequest: у него есть request.cookies и разобранный request.nextUrl.

Кому именно достаётся вызов, решает не if внутри функции, а matcher снаружи: export const config = { matcher: ["/admin/:path*"] }. Без него proxy зовётся вообще на всё — на картинки, на служебные адреса, на каждый префетч. Это работа на пути каждого запроса, и оплачивается она задержкой для пользователя.

В Next 16 proxy всегда выполняется в Node-рантайме, и задать в этом файле runtime нельзя: сборка падает с «Route segment config is not allowed in Proxy file». Раньше middleware жил в Edge-рантайме, где половины Node-API не было.

Чего в proxy.ts делать не стоит — тяжёлой работы и единственной проверки доступа. Редирект неавторизованного на /login здесь уместен: это удобство. Но настоящая проверка обязана стоять там, где лежат данные, — в обработчике, в действии, в серверном компоненте. Привратник, которого можно обойти, охраной не считается.