Next.js API Routes: Rakenna backend-järjestelmäsi vaivattomasti

Next.js on mullistanut front-end-kehityksen tehokkailla ominaisuuksillaan ja intuitiivisella rakenteellaan. Mutta tiesitkö, että se voi myös merkittävästi yksinkertaistaa backend-kehitystä? Next.js API Routes -reittien avulla voit luoda serverless- eli palvelimettomia API-päätepisteitä suoraan Next.js-sovellukseesi, mikä poistaa tarpeen erilliselle backend-palvelimelle monissa tapauksissa. Tämä kattava opas opastaa sinut läpi vankan ja skaalautuvan backend-järjestelmän rakentamisen Next.js API Routes -reittejä käyttäen.

Mitä ovat Next.js API Routes -reitit?

API Routes -reitit ovat palvelimettomia funktioita, joita luot Next.js-projektisi /pages/api-hakemistoon. Nämä funktiot käsittelevät saapuvia HTTP-pyyntöjä ja palauttavat vastauksia, aivan kuten perinteinen backend-API. Keskeinen ero on, että ne otetaan käyttöön palvelimettomina funktioina, mikä tarkoittaa, että sinun ei tarvitse hallita palvelimia tai infrastruktuuria.

Ajattele niitä kevyinä, tarpeen mukaan käytettävinä backend-funktioina, jotka on integroitu saumattomasti Next.js-front-endiisi.

Next.js API Routes -reittien käytön edut

• Yksinkertaistettu kehitys: Kirjoita sekä front-end- että backend-koodisi samaan projektiin käyttäen JavaScriptiä tai TypeScriptiä. Ei enää kontekstin vaihtamista eri projektien ja teknologioiden välillä.
• Palvelimeton arkkitehtuuri: Hyödy palvelimettoman laskennan skaalautuvuudesta, luotettavuudesta ja kustannustehokkuudesta. Maksat vain käyttämistäsi resursseista.
• Helppo käyttöönotto: Ota koko sovelluksesi (front-end ja backend) käyttöön yhdellä komennolla käyttäen Vercelin tai Netlifyn kaltaisia alustoja.
• Sisäänrakennettu tietoturva: Next.js ja palvelimettomat alustat tarjoavat sisäänrakennettuja tietoturvaominaisuuksia API-päätepisteidesi suojaamiseksi.
• Parempi suorituskyky: API Routes -reitit voidaan ottaa käyttöön lähempänä käyttäjiäsi, mikä vähentää viivettä ja parantaa suorituskykyä, mikä on erityisen hyödyllistä maailmanlaajuisille käyttäjille.
• Koodin uudelleenkäytettävyys: Jaa koodia front-end- ja backend-osiesi välillä, mikä vähentää koodin päällekkäisyyttä ja parantaa ylläpidettävyyttä.

Next.js API Routes -reittien käytön aloittaminen

Luodaan yksinkertainen API-reitti, joka palauttaa JSON-vastauksen. Varmista ensin, että sinulla on Next.js-projekti valmiina. Jos ei, luo sellainen komennolla:

            npx create-next-app my-app
cd my-app
            

              
                Copy
              
            
          

Luo nyt tiedosto nimeltä hello.js /pages/api-hakemiston sisään:

            // pages/api/hello.js
export default function handler(req, res) {
  res.status(200).json({ name: 'Matti Meikäläinen' })
}

            

              
                Copy
              
            
          

Tämä koodi määrittelee yksinkertaisen API-reitin, joka vastaa JSON-objektilla, joka sisältää nimen "Matti Meikäläinen". Päästäksesi käsiksi tähän API-reittiin, käynnistä Next.js-kehityspalvelin:

            npm run dev
            

              
                Copy
              
            
          

Avaa sitten selaimesi ja siirry osoitteeseen http://localhost:3000/api/hello. Sinun pitäisi nähdä seuraava JSON-vastaus:

            {"name": "Matti Meikäläinen"}
            

              
                Copy
              
            
          

API-reitin käsittelijän ymmärtäminen

API-reittisi handler-funktio vastaanottaa kaksi argumenttia:

• req: http.IncomingMessage-instanssi, joka sisältää tietoa saapuvasta pyynnöstä, kuten pyynnön metodin, otsakkeet ja rungon.
• res: http.ServerResponse-instanssi, jonka avulla voit lähettää vastauksen takaisin asiakkaalle.

Voit käyttää näitä objekteja erilaisten pyyntöjen käsittelyyn, datan lukemiseen pyynnön rungosta, vastausotsakkeiden asettamiseen ja erilaisten vastausten lähettämiseen.

Eri HTTP-metodien käsittely

Voit käyttää req.method-ominaisuutta määrittämään saapuvan pyynnön HTTP-metodin ja käsitellä eri metodeja vastaavasti. Esimerkiksi:

            // pages/api/method.js
export default function handler(req, res) {
  if (req.method === 'GET') {
    // Käsittele GET-pyyntö
    res.status(200).json({ message: 'Tämä on GET-pyyntö' })
  } else if (req.method === 'POST') {
    // Käsittele POST-pyyntö
    res.status(200).json({ message: 'Tämä on POST-pyyntö' })
  } else {
    // Käsittele muut metodit
    res.status(405).json({ message: 'Metodi ei ole sallittu' })
  }
}

            

              
                Copy
              
            
          

Tässä esimerkissä API-reitti käsittelee sekä GET- että POST-pyyntöjä. Jos pyynnön metodi on GET, se vastaa JSON-objektilla, joka sisältää viestin "Tämä on GET-pyyntö". Jos pyynnön metodi on POST, se vastaa JSON-objektilla, joka sisältää viestin "Tämä on POST-pyyntö". Jos pyynnön metodi on jotain muuta, se vastaa 405 Method Not Allowed -virheellä.

Datan lukeminen pyynnön rungosta

POST-, PUT- ja PATCH-pyynnöissä sinun on usein luettava dataa pyynnön rungosta. Next.js tarjoaa sisäänrakennetun tuen JSON- ja URL-koodattujen pyyntöjen runkojen jäsentämiseen. Voit jäsentää JSON-pyynnön rungon käyttämällä req.body-ominaisuutta. Esimerkiksi:

            // pages/api/post.js
export default async function handler(req, res) {
  if (req.method === 'POST') {
    const { name, email } = req.body

    // Käsittele data
    console.log('Nimi:', name)
    console.log('Sähköposti:', email)

    res.status(200).json({ message: 'Data vastaanotettu onnistuneesti' })
  } else {
    res.status(405).json({ message: 'Metodi ei ole sallittu' })
  }
}

            

              
                Copy
              
            
          

Testataksesi tätä API-reittiä, voit käyttää työkalua kuten Postman tai curl lähettääksesi POST-pyynnön JSON-rungolla:

            curl -X POST -H "Content-Type: application/json" -d '{"name": "Maija Meikäläinen", "email": "maija.meikalainen@example.com"}' http://localhost:3000/api/post
            

              
                Copy
              
            
          

Vastausotsakkeiden asettaminen

Voit käyttää res.setHeader()-metodia asettaaksesi vastausotsakkeita. Tämä on hyödyllistä sisällön tyypin, välimuistin hallinnan ja muiden tärkeiden tietojen asettamisessa. Esimerkiksi:

            // pages/api/headers.js
export default function handler(req, res) {
  res.setHeader('Content-Type', 'application/json')
  res.setHeader('Cache-Control', 's-maxage=3600')
  res.status(200).json({ message: 'Hei, maailma!' })
}

            

              
                Copy
              
            
          

Tässä esimerkissä API-reitti asettaa Content-Type-otsakkeen arvoon application/json, mikä osoittaa, että vastaus on JSON-objekti. Se asettaa myös Cache-Control-otsakkeen arvoon s-maxage=3600, mikä kehottaa selainta ja CDN:ää tallentamaan vastauksen välimuistiin jopa tunnin ajaksi.

Virheidenkäsittely

On tärkeää käsitellä virheet siististi API-reiteissäsi. Voit käyttää try-catch-lohkoja poikkeusten sieppaamiseen ja asianmukaisten virhevastausten lähettämiseen asiakkaalle. Esimerkiksi:

            // pages/api/error.js
export default async function handler(req, res) {
  try {
    // Simuloi virhe
    throw new Error('Jotain meni pieleen')
  } catch (error) {
    console.error(error)
    res.status(500).json({ message: 'Sisäinen palvelinvirhe' })
  }
}

            

              
                Copy
              
            
          

Tässä esimerkissä API-reitti simuloi virheen heittämällä uuden Error-objektin. Catch-lohko sieppaa virheen, kirjaa sen konsoliin ja lähettää 500 Internal Server Error -vastauksen asiakkaalle. Harkitse vankan lokitusjärjestelmän, kuten Sentryn tai Datadogin, käyttöä tuotantoympäristöissä.

Yhdistäminen tietokantaan

Yksi yleisimmistä API-reittien käyttötapauksista on yhdistäminen tietokantaan. Next.js API Routes -reitit integroituvat saumattomasti erilaisiin tietokantoihin, mukaan lukien:

• MongoDB: Suosittu NoSQL-tietokanta, joka sopii hyvin joustavalle ja rakenteettomalle datalle.
• PostgreSQL: Tehokas ja avoimen lähdekoodin relaatiotietokanta, joka on tunnettu luotettavuudestaan ja datan eheydestä.
• MySQL: Toinen suosittu avoimen lähdekoodin relaatiotietokanta, jota käytetään laajalti verkkosovelluksissa.
• Firebase: Pilvipohjainen alusta, joka tarjoaa reaaliaikaisen tietokannan ja muita palveluita.
• FaunaDB: Palvelimeton tietokanta, joka on suunniteltu maailmanlaajuisiin sovelluksiin.

Tässä on esimerkki siitä, miten yhdistetään MongoDB-tietokantaan Next.js API -reitissä:

            // pages/api/mongodb.js
import { MongoClient } from 'mongodb'

const uri = process.env.MONGODB_URI
const options = {}

let client
let clientPromise

if (!process.env.MONGODB_URI) {
  throw new Error('Lisää Mongo URI tiedostoon .env.local')
}

if (process.env.NODE_ENV === 'development') {
  // Kehitystilassa käytetään globaalia muuttujaa, jotta arvo
  // säilyy HMR:n (Hot Module Replacement) aiheuttamien moduulien uudelleenlatausten välillä.
  if (!global._mongoClientPromise) {
    client = new MongoClient(uri, options)
    global._mongoClientPromise = client.connect()
  }
  clientPromise = global._mongoClientPromise
} else {
  // Tuotantotilassa on parasta olla käyttämättä globaalia muuttujaa.
  client = new MongoClient(uri, options)
  clientPromise = client.connect()
}

// Vie moduulin laajuinen MongoClient-lupaus. Tekemällä tämän
// erillisessä moduulissa, asiakasta voidaan turvallisesti käyttää uudelleen useissa
// funktioissa. Katso: https://github.com/vercel/next.js/blob/canary/examples/with-mongodb/lib/mongodb.js
export default async function handler(req, res) {
  try {
    const client = await clientPromise
    const db = client.db(process.env.MONGODB_DB)
    const collection = db.collection('users')

    const users = await collection.find({}).toArray()

    res.status(200).json({ users })
  } catch (e) {
    console.error(e)
    res.status(500).json({ message: 'Käyttäjien nouto epäonnistui' })
  }
}

            

              
                Copy
              
            
          

Ennen tämän koodin suorittamista, varmista, että sinulla on mongodb-paketti asennettuna:

            npm install mongodb
            

              
                Copy
              
            
          

Sinun on myös asetettava MONGODB_URI- ja MONGODB_DB-ympäristömuuttujat. Nämä muuttujat tulee määrittää .env.local-tiedostossasi (tai tuotannossa isännöintipalvelusi ympäristömuuttuja-asetuksissa). MONGODB_URI sisältää yhteysmerkkijonon MongoDB-tietokantaasi, ja MONGODB_DB määrittää tietokannan nimen.

Autentikointi ja auktorisointi

API-reittien suojaaminen on ratkaisevan tärkeää tietoturvan kannalta. Next.js API Routes -reittejä voidaan suojata käyttämällä erilaisia autentikointi- ja auktorisointitekniikoita, mukaan lukien:

• JSON Web Tokens (JWT): Standardi tiedon turvalliseen välittämiseen osapuolten välillä JSON-objektina.
• API-avaimet: Yksinkertainen tapa rajoittaa pääsyä API-päätepisteisiisi.
• OAuth: Delegoitu valtuutusprotokolla, joka antaa käyttäjille mahdollisuuden myöntää kolmannen osapuolen sovelluksille pääsyn resursseihinsa jakamatta tunnuksiaan.
• NextAuth.js: Täydellinen avoimen lähdekoodin autentikointiratkaisu Next.js-sovelluksille.

Tässä on esimerkki siitä, miten API-reitti suojataan JWT-autentikoinnilla:

            // pages/api/protected.js
import jwt from 'jsonwebtoken'

const secret = process.env.JWT_SECRET

export default function handler(req, res) {
  const token = req.headers.authorization?.split(' ')[1]

  if (!token) {
    return res.status(401).json({ message: 'Luvaton pääsy' })
  }

  try {
    const decoded = jwt.verify(token, secret)
    // "decoded"-objekti sisältää tokeniin upotetun käyttäjätiedon
    // Esimerkiksi: const userId = decoded.userId;

    // Jatka pyynnön käsittelyä
    res.status(200).json({ message: 'Suojattuun resurssiin pääsy onnistui' })
  } catch (error) {
    return res.status(401).json({ message: 'Virheellinen token' })
  }
}

            

              
                Copy
              
            
          

Ennen tämän koodin suorittamista, varmista, että sinulla on jsonwebtoken-paketti asennettuna:

            npm install jsonwebtoken
            

              
                Copy
              
            
          

Sinun on myös asetettava JWT_SECRET-ympäristömuuttuja. Tämän tulisi olla vahva, satunnaisesti luotu salainen avain, jota käytetään JWT-tokenien allekirjoittamiseen ja varmentamiseen. Säilytä tämä turvallisesti äläkä koskaan paljasta sitä client-puolen koodissasi.

Middleware

Vaikka Next.js ei tarjoa perinteistä middleware-toiminnallisuutta API-reiteille samalla tavalla kuin Express.js, voit saavuttaa vastaavan toiminnallisuuden käärimällä API-reittikäsittelijäsi uudelleenkäytettäviin funktioihin. Tämä mahdollistaa tehtävien suorittamisen, kuten:

• Autentikointi: Varmenna käyttäjän tunnukset ennen pääsyn sallimista API-päätepisteisiin.
• Auktorisointi: Tarkista, onko käyttäjällä tarvittavat oikeudet suorittaa tietty toimenpide.
• Lokitus: Kirjaa saapuvat pyynnöt ja lähtevät vastaukset auditointia ja virheenkorjausta varten.
• Validointi: Vahvista pyynnön data varmistaaksesi, että se täyttää tietyt kriteerit.
• Käyttörajoitukset (Rate Limiting): Suojaa API:asi väärinkäytöltä rajoittamalla pyyntöjen määrää, jonka käyttäjä voi tehdä tietyn ajanjakson aikana.

Tässä on esimerkki yksinkertaisen lokitus-middlewaren luomisesta:

            // utils/middleware.js
export function withLogging(handler) {
  return async function(req, res) {
    console.log(`[${new Date().toISOString()}] ${req.method} ${req.url}`)
    return handler(req, res)
  }
}

            

              
                Copy
              
            
          

Käyttääksesi tätä middlewarea, kääri API-reittikäsittelijäsi withLogging-funktiolla:

            // pages/api/logged.js
import { withLogging } from '../../utils/middleware'

async function handler(req, res) {
  res.status(200).json({ message: 'Tämä pyyntö on lokitettu' })
}

export default withLogging(handler)

            

              
                Copy
              
            
          

Parhaat käytännöt Next.js API -reittien rakentamiseen

• Pidä API-reittisi pieninä ja kohdennettuina. Jokaisen API-reitin tulisi käsitellä tiettyä tehtävää tai resurssia.
• Käytä ympäristömuuttujia arkaluontoisille tiedoille. Älä koskaan kovakoodaa salaisuuksia tai API-avaimia koodiisi.
• Validoi pyyntöjen data estääksesi tietoturvahaavoittuvuuksia. Käytä kirjastoa, kuten Joi tai Yup, pyyntöjen runkojen validoimiseen.
• Käsittele virheet siististi ja anna informatiivisia virheilmoituksia. Käytä try-catch-lohkoja ja kirjaa virheet keskitettyyn paikkaan.
• Käytä välimuistia parantaaksesi suorituskykyä. Tallenna usein käytetty data välimuistiin vähentääksesi tietokannan kuormitusta.
• Seuraa API-reittiesi suorituskykyä ja virheitä. Käytä seurantatyökalua, kuten Sentry tai Datadog, API:si tilan seuraamiseen.
• Dokumentoi API-reittisi työkalulla, kuten Swagger tai OpenAPI. Tämä helpottaa muiden kehittäjien API:si käyttöä.
• Harkitse TypeScriptin käyttöä tyyppiturvallisuuden vuoksi. TypeScript voi auttaa sinua havaitsemaan virheet aikaisin ja parantamaan koodisi ylläpidettävyyttä.
• Mieti kansainvälistämistä (i18n) alusta alkaen. Jos sovellustasi käyttävät eri maista tulevat käyttäjät, suunnittele API-reittisi tukemaan useita kieliä ja valuuttoja. Esimerkiksi verkkokaupan API-päätepisteiden on ehkä käsiteltävä erilaisia verokantoja ja toimituskuluja käyttäjän sijainnin perusteella.
• Toteuta asianmukainen CORS (Cross-Origin Resource Sharing) -määritys. Tämä on ratkaisevan tärkeää, kun API:asi käytetään eri verkkotunnuksesta kuin Next.js-sovelluksesi. Määritä CORS huolellisesti salliaksesi vain valtuutettujen alkuperien pääsyn API-resursseihisi.

Edistyneet tekniikat

Taustatehtävät

Pitkäkestoisiin tehtäviin, joiden ei pitäisi estää API-vastausta, harkitse taustatehtävien käyttöä. Voit käyttää kirjastoja, kuten BullMQ tai Bree, hallitaksesi taustatehtäviäsi ja käsitelläksesi niitä asynkronisesti.

WebSockets

Reaaliaikaisia sovelluksia varten voit käyttää WebSockets-yhteyksiä Next.js API -reiteissäsi. Kirjastot, kuten Socket.IO ja ws, tekevät pysyvien yhteyksien luomisesta asiakkaan ja palvelimen välille helppoa.

GraphQL

Jos tarvitset joustavamman ja tehokkaamman tavan noutaa dataa, harkitse GraphQL:n käyttöä. Voit käyttää kirjastoja, kuten Apollo Server tai Yoga, luodaksesi GraphQL API -päätepisteen Next.js-sovellukseesi.

Yhteenveto

Next.js API Routes -reitit tarjoavat tehokkaan ja kätevän tavan rakentaa palvelimettomia backend-järjestelmiä suoraan Next.js-sovellukseesi. Hyödyntämällä palvelimettoman arkkitehtuurin etuja voit yksinkertaistaa kehitystä, parantaa suorituskykyä ja vähentää kustannuksia. Olitpa rakentamassa yksinkertaista yhteydenottolomaketta tai monimutkaista verkkokauppa-alustaa, Next.js API Routes -reitit voivat auttaa sinua luomaan vankan ja skaalautuvan backendin vaivattomasti. Vahvalla perusteiden ymmärryksellä ja parhaiden käytäntöjen soveltamisella voit hyödyntää tätä tehokasta työkalua luodaksesi tehokkaita, turvallisia ja maailmanlaajuisesti saavutettavia sovelluksia.