Server routes és a h3 — Express-ből érkezve

8.1A fájl adja a végpontot — és a metódust is

server/
  api/
    projects/
      index.get.ts        →  GET    /api/projects
      index.post.ts       →  POST   /api/projects
      [id].get.ts         →  GET    /api/projects/:id
      [id].patch.ts       →  PATCH  /api/projects/:id
      [id].delete.ts      →  DELETE /api/projects/:id
      [id]/archive.post.ts→  POST   /api/projects/:id/archive
    health.ts             →  minden metódus a /api/health-en
  routes/
    sitemap.xml.get.ts    →  GET /sitemap.xml   ← NINCS /api prefix
    webhooks/
      stripe.post.ts      →  POST /webhooks/stripe
  middleware/
    1.request-id.ts          minden kérésnél fut
    2.tenant.ts
  utils/
    db.ts                    auto-import, csak szerveroldalon
    session.ts
  plugins/
    error-logging.ts         Nitro-szintű plugin (nem app-plugin!)

Két dolog, ami elsőre nem nyilvánvaló:

• server/api/ vs. server/routes/: az előbbi automatikusan /api prefixet kap, az utóbbi nem. Ami nem a saját frontendednek szól — webhookok, sitemap.xml, robots.txt, OAuth callback —, az a routes/ alá való.
• A metódus a fájlnévben van. Ha elhagyod (health.ts), akkor minden metódusra válaszol. Ez ritkán az, amit akarsz — a metódus-utótag egyben dokumentáció is.

8.2Az event és a h3-eszköztár

Expressben két objektumot kapsz (req, res), és rajtuk hívsz metódusokat. h3-ban egy objektumot kapsz (event), és függvényeket hívsz rá. Ennyi a különbség — de emiatt más lesz a kód formája:

router.patch('/:id', requireAuth, async (req, res, next) => {
  try {
    const { name } = req.body
    if (!name) return res.status(422).json({ error: 'name kötelező' })

    const updated = await db.project.update({
      where: { id: req.params.id, tenantId: req.session.tenantId },
      data: { name },
    })

    res.set('X-Request-Id', req.id)
    res.json(updated)
  } catch (err) { next(err) }
})

export default defineEventHandler(async (event) => {
  const { tenantId } = await requireSession(event)          // server/utils, auto-import
  const id   = getRouterParam(event, 'id')!
  const body = await readValidatedBody(event, updateProjectSchema.parse)

  const updated = await useDb(event).update(projects)
    .set({ name: body.name })
    .where(and(eq(projects.id, id), eq(projects.tenantId, tenantId)))
    .returning()

  if (!updated.length) throw createError({ statusCode: 404, statusMessage: 'Nincs ilyen projekt' })

  setResponseHeader(event, 'X-Request-Id', event.context.requestId)
  return toProjectDto(updated[0])          // a visszatérési érték a válasz teste
})

Négy szerkezeti különbség, amit érdemes rögtön beépíteni a reflexbe:

1. Nincs next(err) és nincs try/catch boilerplate. Dobsz egy createError-t, és a Nitro elintézi. A nem várt kivételeket is elkapja és 500-ra fordítja.
2. A visszatérési érték a válasz. Objektumból JSON lesz, stringből szöveg/HTML, ReadableStream-ből stream. Nincs res.json().
3. Nincs middleware-lánc a route-on. Az requireAuth nem middleware, hanem egy függvény, amit meghívsz. Ez explicitebb, és látszik a kódban, hogy mi fut le.
4. Egy fájl = egy végpont. Nincs 400 soros routes/projects.js.

A teljes megfeleltetés

8.3Validáció

Expressben ezt jellemzően middleware-rel oldottad meg (express-validator, celebrate). h3-ban egy függvényhívás, és a típus is jön vele:

// shared/schemas/project.ts — mindkét oldal használhatja (2. modul: shared/)
import { z } from 'zod'

export const createProjectSchema = z.object({
  name:        z.string().min(1).max(120),
  description: z.string().max(2000).optional(),
  status:      z.enum(['active', 'archived']).default('active'),
})
export type CreateProject = z.infer<typeof createProjectSchema>

// server/api/projects/index.post.ts
export default defineEventHandler(async (event) => {
  const { tenantId, userId } = await requireSession(event)

  // hiba esetén automatikusan 400-at dob — a body típusos lesz
  const body = await readValidatedBody(event, createProjectSchema.parse)

  // query-re ugyanez: getValidatedQuery(event, listQuerySchema.parse)

  const [row] = await useDb(event).insert(projects)
    .values({ ...body, tenantId, createdBy: userId })
    .returning()

  setResponseStatus(event, 201)
  return toProjectDto(row)
})

const raw = await readBody(event)
const parsed = createProjectSchema.safeParse(raw)
if (!parsed.success) {
  throw createError({
    statusCode: 422,
    statusMessage: 'Érvénytelen adat',
    data: { errors: parsed.error.flatten().fieldErrors },
  })
}

8.4Hibakezelés

throw createError({
  statusCode:    403,
  statusMessage: 'Nincs jogosultság',   // ✓ a kliens LÁTJA
  data:          { needed: 'admin' },      // ✓ a kliens LÁTJA
  message:       'user 42 lacks role on tenant 7', // belső — élesben nem megy ki
  fatal:         false,                  // true → az egész oldal a hibaoldalra megy
})

Globális hibakezelés

// server/plugins/errors.ts — Nitro-plugin, nem app-plugin
export default defineNitroPlugin((nitro) => {
  nitro.hooks.hook('error', (error, { event }) => {
    // a 4xx-eket ne zajongd tele — csak a valódi hibákat
    const code = (error as any).statusCode ?? 500
    if (code < 500) return

    console.error('[hiba]', {
      requestId: event?.context.requestId,
      tenant:    event?.context.tenant?.slug,
      path:      event?.path,
      message:   (error as Error).message,
    })
  })
})

8.5Server middleware

A server/middleware/ alatti fájlok minden szerverre érkező kérésnél lefutnak — az SSR-nél és a /api-hívásoknál is. A sorrendet a fájlnevek adják (ábécésorrend), ezért szokás számmal prefixálni:

// server/middleware/1.request-id.ts
export default defineEventHandler((event) => {
  event.context.requestId =
    getHeader(event, 'cf-ray') ?? crypto.randomUUID()
})

// server/middleware/2.tenant.ts  (4. modul)
export default defineEventHandler(async (event) => {
  event.context.tenant = await resolveTenant(event)
})

8.6Szervezés: server/utils és a rétegek

A server/utils/ auto-importált és csak szerveroldalon létezik — itt lakik minden, ami nem HTTP-kezelés. Érdemes három réteget elkülöníteni, még ha kicsi is a projekt:

// server/api/projects/index.post.ts — a handler vékony
export default defineEventHandler(async (event) => {
  const { tenantId, userId } = await requireSession(event)
  const body = await readValidatedBody(event, createProjectSchema.parse)

  const project = await createProject(useDb(event), { tenantId, userId, ...body })

  setResponseStatus(event, 201)
  return toProjectDto(project)
})

8.7Három minta, ami biztosan kelleni fog

① Webhook: a nyers törzs csapdája

// server/routes/webhooks/stripe.post.ts
export default defineEventHandler(async (event) => {
  // FONTOS: nyers törzs kell az aláírás-ellenőrzéshez — a readBody() már JSON-t ad,
  // és az újraszerializálva NEM egyezik bájtra az eredetivel
  const raw = await readRawBody(event, 'utf8')
  const sig = getHeader(event, 'stripe-signature')

  if (!raw || !sig || !(await verifySignature(raw, sig, useRuntimeConfig(event).stripeSecret))) {
    throw createError({ statusCode: 400, statusMessage: 'Érvénytelen aláírás' })
  }

  const payload = JSON.parse(raw)

  // gyors 200, a munka a háttérben — Workers-en waitUntil vagy Queue
  event.context.cloudflare.context.waitUntil(handleStripeEvent(payload))
  return { received: true }
})

② Fájlfeltöltés R2-be

// server/api/uploads.post.ts
export default defineEventHandler(async (event) => {
  const { tenantId } = await requireSession(event)
  const parts = await readMultipartFormData(event)
  const file  = parts?.find(p => p.name === 'file')

  if (!file) throw createError({ statusCode: 422, statusMessage: 'Hiányzó fájl' })
  if (file.data.length > 10_000_000) {
    throw createError({ statusCode: 413, statusMessage: 'Túl nagy fájl' })
  }

  // a kulcs ELSŐ szegmense a tenant — így a jogosultság az útból is látszik
  const key = `${tenantId}/${crypto.randomUUID()}-${sanitize(file.filename!)}`
  await event.context.cloudflare.env.BUCKET.put(key, file.data, {
    httpMetadata: { contentType: file.type ?? 'application/octet-stream' },
  })

  return { key }
})

③ Streamelt válasz

// server/api/export.get.ts — nagy CSV, nem a memóriából
export default defineEventHandler(async (event) => {
  const { tenantId } = await requireSession(event)

  setResponseHeader(event, 'content-type', 'text/csv; charset=utf-8')
  setResponseHeader(event, 'content-disposition', 'attachment; filename="export.csv"')

  const stream = new ReadableStream({
    async start(controller) {
      const enc = new TextEncoder()
      controller.enqueue(enc.encode('id,nev,statusz\n'))
      for await (const row of iterateProjects(useDb(event), tenantId)) {
        controller.enqueue(enc.encode(`${row.id},${csv(row.name)},${row.status}\n`))
      }
      controller.close()
    },
  })

  return stream          // a ReadableStream visszaadható válaszként
})

8.8Ami a Nuxt 5-tel változni fog

A h3 következő major verziója (v2) a Nitro v3-mal, vagyis a Nuxt 5-tel érkezik, és néhány segédfüggvény neve, illetve a belső Request/Response-kezelés változik. Amit most tehetsz, hogy ne fájjon:

• Tartsd vékonyan a handlereket. Ha a HTTP-kezelés 10 sor, és az üzleti logika a service-rétegben van, akkor egy esetleges átnevezés-hullám 10 soros fájlokat érint, nem 300 sorosakat.
• Kerüld a h3 belsőségeit. A dokumentált get*/set*/read* segédfüggvények stabilak; az event.node.req-hez nyúlás nem — és Workers-en amúgy sem mindig van értelme.
• Maradj a legfrissebb 4.x-en, mert a deprecation-figyelmeztetések ott jönnek.

8.9Ellenőrizd magad