Adatlekérés: useFetch, useAsyncData, $fetch

5.1A három eszköz, és mire való mindegyik

Elsőre zavaró, hogy három dolog is „adatot kér le”. Valójában rétegek:

A hiba, amit szinte mindenki elkövet

<script setup>
const projects = await $fetch('/api/projects')
</script>

Ez működni fog — és ettől a legrosszabb. Ami történik: a setup lefut a szerveren, lekéri az adatot, kirendereli a HTML-t. Aztán a böngészőben, a hydration alatt ugyanez a setup újra lefut, és mivel a $fetch-nek fogalma sincs a szerveren már megtörtént lekérésről, megint lekérdezi. Kétszeres adatbázis-terhelés, plusz egy fölösleges kör a böngészőből.

<script setup>
const { data: projects, status, error } = await useFetch('/api/projects')
</script>

Döntési szabály

// eseménykezelőben $fetch — itt nincs SSR, nincs mit átvinni
async function archive(id: string) {
  await $fetch(`/api/projects/${id}/archive`, { method: 'POST' })
  await refresh()          // a useFetch-ből kapott refresh
}

5.2A kulcs — a legfontosabb paraméter, amiről nem beszélnek

Minden useAsyncData/useFetch hívásnak van egy kulcsa. Ez azonosítja az eredményt a payloadban, ezen keresztül talál rá a kliens a szerveren lekért adatra, és ez alapján osztozik két komponens ugyanazon az adaton.

A useFetch automatikusan generál kulcsot (a hívás helye és az URL alapján). Ez a legtöbbször jó — de amint az URL dinamikus, érdemes átvenni az irányítást:

<script setup lang="ts">
const route = useRoute()

// reaktív URL: ha az id változik, automatikusan újratölt (Nuxt 4: reaktív kulcsok)
const { data: project } = await useFetch(
  () => `/api/projects/${route.params.id}`,
  { key: () => `project:${route.params.id}` },
)
</script>

Két képesség, amit a kulcs ad:

• Megosztott adat. Ha két komponens ugyanazt a kulcsot használja, ugyanazt a példányt kapják — nincs második lekérés. Máshonnan is elérhető: useNuxtData('project:42').
• Célzott frissítés. refreshNuxtData('project:42') csak azt az egy bejegyzést tölti újra, nem az egész oldalt.

const { slug } = useTenant()
const filters = ref({ status: 'active' })

const { data: projects } = await useFetch('/api/projects', {
  query: filters,
  key: () => `projects:${slug.value}:${filters.value.status}`,
  watch: [slug, filters],
})

5.3Opció-referencia

Ezt a táblát fogod visszakeresni. A félkövérek azok, amiket hetente használsz:

Visszatérési értékek

const {
  data,      // az eredmény (ref)
  status,    // 'idle' | 'pending' | 'success' | 'error'  ← ezt használd a sablonban
  error,     // a hiba, ha volt
  refresh,   // újratöltés
  execute,   // ugyanaz, immediate:false mellett használatos
  clear,     // data/error/status visszaállítása
} = await useFetch('/api/projects')

<template>
  <ProjectSkeleton v-if="status === 'pending'" />
  <ErrorBox v-else-if="status === 'error'" :error="error" />
  <ProjectList v-else :items="data" />
</template>

5.4Hibakezelés

A két eszköz máshogy viselkedik hibánál, és ez rendszeresen meglep:

• useFetch nem dob kivételt — a hibát az error ref-be teszi, és a status lesz 'error'. Neked kell megjelenítened.
• $fetch dob — try/catch kell köré. A hiba FetchError, a szerver válasza a err.data-ban van.

// szerveroldalon így keletkezik a hiba:
throw createError({
  statusCode: 404,
  statusMessage: 'Nincs ilyen projekt',   // ← ezt LÁTJA a kliens
  data: { field: 'id' },                   // ← ez is átmegy, ha megadod
  message: 'projects.findFirst returned null for tenant 42', // ← ez NEM megy ki élesben
})

// kliensoldalon, eseménykezelőben:
try {
  await $fetch('/api/projects', { method: 'POST', body })
} catch (e: any) {
  if (e.statusCode === 422) formErrors.value = e.data?.errors
  else toast.error('Nem sikerült létrehozni')
}

Ha egy hiba az egész oldalt érvényteleníti (nincs ilyen projekt, nincs jogosultság), akkor fatal: true-val vagy showError()-ral az app/error.vue-ra dobod — ez a 4. modulban volt.

5.5A payload — a csapda, amiről kevesen tudnak

Amikor a useFetch a szerveren lefut, az eredményt valahogy át kell adni a kliensnek, hogy az ne kérje le újra. Ez a payload: a Nuxt beleírja az eredményt a HTML-be, egy <script id="__NUXT_DATA__"> elembe.

Nézd meg magad: nyiss meg egy Nuxt-oldalt, és a forrást nézd (nem a DevTools Elements fülét, mert az már a hidratált DOM). A HTML alján ott lesz az összes szerveroldali lekérésed eredménye — nyersen, JSON-szerű formában.

// server/api/projects/[id].get.ts
export default defineEventHandler(async (event) => {
  return await useDb(event).query.projects.findFirst({
    where: eq(projects.id, getRouterParam(event, 'id')!),
    with: { owner: true },        // ← és a teljes user-sor is, jelszó-hash-sel együtt
  })
})

export default defineEventHandler(async (event) => {
  const { tenantId } = await requireSession(event)

  const p = await useDb(event).query.projects.findFirst({
    where: and(
      eq(projects.id, getRouterParam(event, 'id')!),
      eq(projects.tenantId, tenantId),      // a tenant-szűrés MINDIG a lekérdezésben
    ),
    with: { owner: { columns: { id: true, name: true, avatarUrl: true } } },
  })

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

  // és a válasz alakja is explicit — nem a DB-séma szivárog ki az API-ba
  return {
    id: p.id, name: p.name, status: p.status, updatedAt: p.updatedAt,
    owner: { id: p.owner.id, name: p.owner.name, avatarUrl: p.owner.avatarUrl },
  }
})

A második védvonal: pick és transform

Ezek a kliensoldali hívásnál szűkítik a payloadot — a szerveren futnak le, mielőtt a szerializálás megtörténik, tehát tényleg csökkentik, ami kimegy:

const { data } = await useFetch('/api/projects', {
  pick: ['id', 'name', 'status'],
})

// vagy összetettebb esetben:
const { data } = await useFetch('/api/projects', {
  transform: (rows) => rows.map(r => ({ id: r.id, name: r.name })),
})

Amit ne engedj a payloadba

• Idegen tenant bármely mezője — beleértve a tenant_id-t, ami már önmagában is felderítést tesz lehetővé.
• Jelszó-hash, session-token, API-kulcs — kapcsolt user-sorral ez véletlenül is bekerül.
• Belső üzleti adat: beszerzési ár, árrés, belső megjegyzés, moderációs jelölés.
• Soft-delete és audit mezők — a deleted_at elárulja, mit töröltek és mikor.

Ha valami tényleg csak a bejelentkezett felhasználónak szól és nem kell SSR-ben, a server: false a helyes eszköz — akkor a lekérés kizárólag a böngészőben történik, és semmi nem kerül a HTML-be:

// személyre szabott, nem indexelendő, nem cache-elhető rész
const { data: notifications } = await useFetch('/api/me/notifications', {
  server: false,
  lazy: true,
})

5.6Vízesés és párhuzamosítás

A soros await-ek vízesést csinálnak: a második lekérés csak az első befejeződése után indul el.

const { data: user }     = await useFetch('/api/me')
const { data: projects } = await useFetch('/api/projects')
const { data: usage }    = await useFetch('/api/usage')

const [{ data: user }, { data: projects }, { data: usage }] = await Promise.all([
  useFetch('/api/me'),
  useFetch('/api/projects'),
  useFetch('/api/usage'),
])

// server/api/dashboard.get.ts — egy adatbázis-menet, egy válasz
export default defineEventHandler(async (event) => {
  const { userId, tenantId } = await requireSession(event)
  const db = useDb(event)

  const [projects, usage] = await Promise.all([
    db.query.projects.findMany({ where: eq(projects.tenantId, tenantId), limit: 10 }),
    getUsage(db, tenantId),
  ])

  return { projects: projects.map(toProjectDto), usage }
})

5.7getCachedData — hasznos, de vigyázz vele

Alapból a useAsyncData minden navigációnál újratölt. A getCachedData-val megmondhatod, hogy ha már megvan az adat, ne kérje le újra:

const { data } = await useFetch('/api/settings', {
  key: () => `settings:${slug.value}`,
  getCachedData: (key, nuxtApp, ctx) => {
    // kézi frissítéskor mindig menjen új kérés
    if (ctx.cause === 'refresh:manual') return undefined
    return nuxtApp.payload.data[key] ?? nuxtApp.static.data[key]
  },
})

5.8Ellenőrzőlista egy adatot lekérő oldalhoz

• A fő tartalom useFetch-csel jön (nem $fetch-csel a setup-ban)?
• A kulcs tartalmaz mindent, amitől a válasz függ — tenant, felhasználó, szűrők?
• A server route DTO-t ad vissza, nem nyers adatbázis-sort?
• A tenant-szűrés a lekérdezésben van, nem a válasz szűrésében?
• A személyre szabott részek server: false-szal jönnek, hogy a HTML cache-elhető maradjon?
• A párhuzamosítható lekérések tényleg párhuzamosak (vagy egy végpontba vontad össze)?
• Megnézted a forráskódban, mi van a __NUXT_DATA__-ban?

5.9Ellenőrizd magad