Как устроены server API routes в Nuxt (Nitro)?

Вопрос

Как создавать серверные API-эндпоинты в Nuxt и как они работают под капотом?

Короткий ответ

Nuxt использует серверный движок Nitro: любой файл в server/api/ автоматически становится HTTP-эндпоинтом, доступным по соответствующему пути, без отдельного backend-фреймворка.

Подробный ответ

Структура определяет маршрут и метод:

• server/api/users.get.ts → GET /api/users
• server/api/users.post.ts → POST /api/users
• server/api/users/[id].ts → GET /api/users/:id (без суффикса — любой метод)

Каждый файл экспортирует event handler, созданный через defineEventHandler. Внутри доступны утилиты из h3 (движок, на котором построен Nitro):

• getRouterParam(event, 'id') — параметры динамического маршрута.
• getQuery(event) — query-параметры.
• readBody(event) — тело запроса.
• createError({ statusCode, message }) — выброс ошибки с нужным статус-кодом.
• setResponseStatus(event, 201) — явная установка статуса ответа.

Nitro — универсальный движок: один и тот же код можно задеплоить на Node.js-сервер, serverless-функции (Vercel, AWS Lambda) или edge-окружения без изменений.

Пример

// server/api/users/[id].get.ts
export default defineEventHandler(async (event) => {
  const id = getRouterParam(event, 'id')

  const user = await findUserById(id)
  if (!user) {
    throw createError({ statusCode: 404, statusMessage: 'Пользователь не найден' })
  }

  return user
})

<script setup>
// На клиенте — просто useFetch, Nuxt сам разберётся, SSR это или CSR-запрос
const { data: user } = await useFetch(`/api/users/${route.params.id}`)
</script>

Дополнительные вопросы

• Чем server/api отличается от server/routes?
• Как в server route получить доступ к переменным окружения безопасно?
• Что такое server middleware и чем оно отличается от route middleware?