Nuxt Tutorial 4 - Serverová část

Dosud jsme se pohybovali v tzv. klientské části Nuxt aplikace. Stránky (/pages) tvořené komponentami (/components) a poháněné logikou umístěnou ve složkách /composables a /utils jsou základní stavební prvky toho, co nakonec vidí uživatel - frontend. Pro řadu aplikací, zejména těch menších, to úplně stačí.

Nuxt ale nabízí funkcionalitu i pro backendové operace. Umožňuje vystavit API endpointy, přijímat a zpracovávat na ně přijímané požadavky, a sloužit tak i jako prakticky plnohodnotný server.

Nitro

Nuxt funguje dynamicky díky internímu webovému server enginu Nitro. Nitro si vytváří vlastní runtime nezávislý na všem ostatním a tvoří běhové prostředí aplikace, které poskytuje řadu skvělých funkcí. Vývojáři ocení třeba hot-module-reload (HMR) při vývoji - stačí uložit soubor a změny se ihned promítnou a nasadí do lokálně běžící verze. Pokud s programováním začínáte dnes, může vám to už připadat jako samozřejmost, ale nebylo to vždycky tak snadné...

Další vymožeností Nitra je API vrstva, která umožňuje jednoduše tvořit a vystavovat endpointy, které pak lze přes HTTP(S) požadavky provolávat.

/server

Soubor, kterým se API endpoint realizuje, vypadá jednoduše takto:

export default defineEventHandler((event) => {
  // obslužný kód
})

Stačí jej umístit do další speciální složky /server/api nebo /server/routes a Nuxt si ho automaticky zpracuje a začne vystavovat. Rozdíl mezi uvedenými dvěma složkami je, že obslužný handler ze souboru /server/api/foo.ts bude vystaven na http://localhost:3000/api/foo, zatímco ze souboru /server/routes/foo.ts přímo na http://localhost:3000/foo. Podsložka /server/api je tedy de-facto totéž jako /server/routes/api. Použití prefixu /api je poměrně časté, proto existuje jako samostatná možnost, pokud ale trváte na větší volnosti, můžete použít /routes a uvnitř rozvinout svou strukturu podle libosti.

Pomocí suffixů za tečkou v názvech souborů lze jednoduše upřesnit, kterou HTTP metodu handler obsluhuje. Soubor /server/api/foo.get.ts umožní na http://localhost:3000/api/foo volat GET, /server/api/foo.post.ts vystaví na http://localhost:3000/api/foo POST. Logika obou může být výrazně odlišná. Podle dokumentace jsou podporovány metody GET, POST, PUT a DELETE, tedy ne úplně všechny, ale ty zbylé v běžném provozu stejně příliš často nepotkáte.

Obslužný callback defineEventHandler může přijmout vstupní parametr event, který je typu H3Event z frameworku h3. Tento minimalistický HTTP framework, který v sobě Nuxt, resp. Nitro integruje, nabízí celou řadu užitečných funkcí. Například načíst obsah příchozího POST požadavku k dalšímu zpracování můžeme jednoduše takto:

export default defineEventHandler(async (event) => {
    const postData = await readBody(event)
    // další zpracování vstupu
}

V proměnné event.node.req zase naleznete parametry příchozího HTTP požadavku ve formátu Node.js HTTP. Snadno si tak lze sáhnout například na HTTP hlavičky, které jsou umístěny v poli headers.

Případová studie

Na úvodní stránce naleznete několik odrážek „Co nového v XY?“ Data, která se zde zobrazují, pocházejí z mých seznamů článků na GitHubu, které si průběžně udržuju. Například ZDE je přehled novinek v Nuxt/Vue světě. Na tyto zdrojové soubory se odkazují Nuxt-powered webové služby, které z nich načítají nejnovějších 5 článků. Služba pro Nuxt novinky běží zde: https://alois-seckar.cz/nuxt-news.

Její vlastní implementace je velmi jednoduchá, hlavní práci obstará utility funkce, která si přečte zadanou URL s markdown souborem a pomocí knihovny node-html-parser z ní vybere potřebná data.

Demo projekt

Zdrojový kód ukázkové implementace naleznete zde: nuxt-api @ GitHub

Serverová část projektu vystavuje dva API endpointy:

• sample.get.ts - vrátí text „Hello, Nuxt!“ + aktuální datum a čas (aby bylo vidět, že se požadavek pokaždé znovu procesuje)
• error.get.ts - úmyslně vrací náhodnou HTTP chybu 400-410

Jednoduchý frontend provolává a zobrazuje výsledek sample.get.ts. Endpoint s chybou si můžete zkusmo provolat sami, když do prohlížeče zadáte:

http://localhost:3000/api/error

Další odkazy

• Web scraper in Nuxt 3 (Alois Sečkár) (EN) - můj čtyřdílný step-by-step návod jak pracovat s Nuxt backendem
• Server Routes in Nuxt 3 (Michael Thiessen) (EN)
• Dokumentace - Nuxt /server (EN)
• Dokumentace - h3 (EN)

Shrnutí

Serverová část Nuxt frameworku je určena k de-facto backendovým operacím. Umožňuje tvořit a vystavovat vlastní API, které lze poskytovat buďto navenek do internetu, nebo ji také lze využít k logické separaci kódu - serverová část slouží k obsluze volání externích API a k manipulaci s daty, které pak aplikace v klientské frontendové části pouze zobrazuje.

Stejně jako složka /pages umožňuje routing na straně klienta, složky /server/api a /server/routes abstrahují vývojáře od nutnosti definovat vlastní cesty.

Další část tutoriálu představí koncept middleware, což jsou obslužné metody, které je možné automaticky volat před vykreslením frontendu nebo před zpracováním dat v serverové části.