Пошук уроків, статей та іншого контенту
Створіть перший Route Handler у Next.js та розберіться зі структурою API-маршрутів у папці app.
Route Handler — це спеціальний файл у папці app, який обробляє HTTP-запити в Next.js. За його допомогою можна створити API-маршрут без окремого сервера.
Route Handler:
розміщується у файлі route.js або route.ts;
визначає обробники HTTP-методів: GET, POST, PUT, PATCH, DELETE та інших;
повертає об’єкт Response;
доступний за URL, який відповідає його розташуванню в папці app.
Наприклад, файл:
app/api/hello/route.jsстворює API-маршрут:
/api/helloЯкщо застосунок запущено локально, повна адреса буде:
http://localhost:3000/api/helloУ Next.js файл route.js повинен розміщуватися всередині папки маршруту:
app/
└── api/
└── hello/
└── route.jsНазви папок стають частинами URL:
app/api/hello/route.jsвідповідає маршруту:
/api/helloФайл route.js не є звичайним React-компонентом. Він не повертає JSX, а формує HTTP-відповідь.
Створіть у проєкті таку структуру:
app/
└── api/
└── hello/
└── route.jsДодайте до route.js такий код:
export async function GET() {
return Response.json({
message: "Привіт із Route Handler!",
});
}Тепер запустіть застосунок:
npm run devВідкрийте в браузері адресу:
http://localhost:3000/api/helloУ відповідь ви побачите JSON:
{
"message": "Привіт із Route Handler!"
}export async function GET() {
return Response.json({
message: "Привіт із Route Handler!",
});
}GET — назва HTTP-методу, який обробляє функція.
export — функція повинна бути експортована з файлу.
Response.json() — створює HTTP-відповідь із JSON-даними.
Об’єкт усередині Response.json() автоматично перетворюється на JSON.
Функцію можна оголосити і без async, якщо в ній немає асинхронних операцій:
export function GET() {
return Response.json({
message: "Успішна відповідь",
});
}Другим аргументом Response.json() можна передати налаштування відповіді. Наприклад, статус HTTP:
export function GET() {
return Response.json(
{
message: "Дані отримано",
},
{
status: 200,
}
);
}Статус 200 означає, що запит виконано успішно. Для простих відповідей Next.js зазвичай використовує цей статус автоматично.
Можна також повернути помилку:
export function GET() {
return Response.json(
{
error: "Ресурс не знайдено",
},
{
status: 404,
}
);
}В одному файлі можна оголосити кілька обробників. Наприклад, GET для отримання даних і POST для створення даних:
export function GET() {
return Response.json({
message: "Це GET-запит",
});
}
export async function POST() {
return Response.json(
{
message: "Це POST-запит",
},
{
status: 201,
}
);
}Тепер:
GET /api/hello викличе функцію GET;
POST /api/hello викличе функцію POST.
Статус 201 означає, що новий ресурс було створено.
Запит GET легко перевірити у браузері. Для POST можна використати команду curl:
curl -X POST http://localhost:3000/api/helloОчікувана відповідь:
{
"message": "Це POST-запит"
}Route Handler отримує об’єкт Request. Його можна використати, щоб прочитати URL, заголовки або тіло запиту.
Наприклад, Route Handler може прочитати JSON із POST-запиту:
export async function POST(request) {
const body = await request.json();
return Response.json({
received: body,
});
}Перевірити його можна так:
curl -X POST http://localhost:3000/api/hello \
-H "Content-Type: application/json" \
-d '{"name":"Олена"}'Відповідь:
{
"received": {
"name": "Олена"
}
}Метод request.json() асинхронний, тому функцію POST оголошено з ключовим словом async.
Папки в app можуть бути динамічними. Назва в квадратних дужках означає параметр маршруту.
Структура:
app/
└── api/
└── users/
└── [id]/
└── route.jsТакий файл обробляє запити на кшталт:
/api/users/42
/api/users/100Приклад Route Handler:
export async function GET(request, { params }) {
const { id } = await params;
return Response.json({
userId: id,
});
}Запит:
http://localhost:3000/api/users/42поверне:
{
"userId": "42"
}Параметр URL зазвичай є рядком. Якщо потрібне число, його можна перетворити окремо:
const userId = Number(id);Route Handler та сторінка можуть бути в одному проєкті, але не в одному сегменті маршруту.
Наприклад, така структура є коректною:
app/
├── page.js
└── api/
└── hello/
└── route.jsВона створює:
сторінку /;
API-маршрут /api/hello.
Але не слід створювати одночасно такі файли в одній папці:
app/
└── api/
└── hello/
├── page.js
└── route.jspage.js і route.js призначені для різних типів маршрутів, тому їх потрібно розділяти за структурою URL.
Якщо проєкт використовує TypeScript, замість route.js можна створити route.ts:
export function GET() {
return Response.json({
message: "Привіт із TypeScript Route Handler!",
});
}Структура маршруту залишається такою самою:
app/
└── api/
└── hello/
└── route.tsRoute Handler повинен називатися саме route.js або route.ts і бути всередині app.
Неправильно:
app/
└── api/
└── hello.jsПравильно:
app/
└── api/
└── hello/
└── route.jsNext.js шукає функції з назвами HTTP-методів:
export function GET() {
return Response.json({ ok: true });
}Функція з довільною назвою не буде обробником маршруту:
export function getUsers() {
return Response.json([]);
}Route Handler повинен повертати Response, наприклад через Response.json():
export function GET() {
return Response.json({
data: [],
});
}Не слід повертати звичайний JavaScript-об’єкт:
export function GET() {
return {
data: [],
};
}Якщо у файлі оголошено лише GET, а надіслано POST, маршрут не виконає функцію GET.
Для кожного методу, який має підтримувати маршрут, потрібно створити окрему експортовану функцію:
export function GET() {
return Response.json({ method: "GET" });
}
export function POST() {
return Response.json({ method: "POST" });
}Route Handler створюється у файлі route.js або route.ts.
Файл розміщується всередині папки app.
Шлях до файлу визначає URL API-маршруту.
Функції GET, POST, PUT, PATCH та інші відповідають HTTP-методам.
Для JSON-відповіді використовується Response.json().
Об’єкт запиту можна отримати через параметр request.
Динамічні сегменти URL записуються в квадратних дужках, наприклад [id].
Route Handler повертає HTTP-відповідь, а не JSX.