M

MLOG

Suomi

Opi rakentamaan serverless-backend suoraan Next.js-sovellukseen API Routes -reiteillä. Opas kattaa kaiken perusteista edistyneisiin tekniikoihin.

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

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

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' })
}

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

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

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

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

API-reittisi handler-funktio vastaanottaa kaksi argumenttia:

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' })
  }
}

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' })
  }
}

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

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!' })
}

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' })
  }
}

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:

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' })
  }
}

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

npm install mongodb

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:

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' })
  }
}

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

npm install jsonwebtoken

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:

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)
  }
}

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)

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

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.