M

MLOG

Lietuvių

Sužinokite, kaip panaudoti Next.js API maršrutus, kad sukurtumėte „serverless“ backend tiesiogiai savo Next.js programoje. Šis vadovas apima viską nuo pradinės sąrankos iki pažangių metodų, skirtų autentifikavimui, duomenų išsaugojimui ir kt.

Next.js API maršrutai: lengvas „backend“ kūrimas

Next.js sukėlė revoliuciją „front-end“ kūrime dėl savo galingų funkcijų ir intuityvios struktūros. Bet ar žinojote, kad jis taip pat gali žymiai supaprastinti „backend“ kūrimą? Next.js API maršrutai leidžia kurti „serverless“ API galinius taškus tiesiogiai jūsų Next.js programoje, daugeliu atvejų pašalinant poreikį turėti atskirą „backend“ serverį. Šis išsamus vadovas padės jums sukurti tvirtą ir keičiamo dydžio „backend“ naudojant Next.js API maršrutus.

Kas yra Next.js API maršrutai?

API maršrutai yra „serverless“ funkcijos, kurias kuriate savo /pages/api kataloge savo Next.js projekte. Šios funkcijos apdoroja gaunamas HTTP užklausas ir grąžina atsakymus, lygiai taip pat, kaip tradicinis „backend“ API. Pagrindinis skirtumas yra tas, kad jos diegiamos kaip „serverless“ funkcijos, o tai reiškia, kad jums nereikia valdyti serverių ar infrastruktūros.

Pagalvokite apie jas kaip apie lengvas, pagal poreikį veikiančias „backend“ funkcijas, kurios yra sklandžiai integruotos su jūsų Next.js „front-end“ dalimi.

Next.js API maršrutų naudojimo privalumai

Darbo su Next.js API maršrutais pradžia

Sukurkime paprastą API maršrutą, kuris grąžina JSON atsakymą. Pirmiausia įsitikinkite, kad turite paruoštą Next.js projektą. Jei ne, sukurkite jį naudodami:

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

Dabar sukurkite failą pavadinimu hello.js /pages/api kataloge:

// pages/api/hello.js
export default function handler(req, res) {
  res.status(200).json({ name: 'Jonas Jonaitis' })
}

Šis kodas apibrėžia paprastą API maršrutą, kuris atsako su JSON objektu, turinčiu vardą „Jonas Jonaitis“. Norėdami pasiekti šį API maršrutą, paleiskite savo Next.js kūrimo serverį:

npm run dev

Tada atsidarykite naršyklę ir pereikite į http://localhost:3000/api/hello. Turėtumėte pamatyti šį JSON atsakymą:

{"name": "Jonas Jonaitis"}

API maršruto tvarkyklės (handler) supratimas

handler funkcija jūsų API maršrute gauna du argumentus:

Galite naudoti šiuos objektus, kad tvarkytumėte skirtingų tipų užklausas, skaitytumėte duomenis iš užklausos turinio, nustatytumėte atsakymo antraštes ir siųstumėte skirtingų tipų atsakymus.

Skirtingų HTTP metodų tvarkymas

Galite naudoti req.method savybę, norėdami nustatyti gaunamos užklausos HTTP metodą ir atitinkamai tvarkyti skirtingus metodus. Pavyzdžiui:

// pages/api/method.js
export default function handler(req, res) {
  if (req.method === 'GET') {
    // Tvarkyti GET užklausą
    res.status(200).json({ message: 'Tai yra GET užklausa' })
  } else if (req.method === 'POST') {
    // Tvarkyti POST užklausą
    res.status(200).json({ message: 'Tai yra POST užklausa' })
  } else {
    // Tvarkyti kitus metodus
    res.status(405).json({ message: 'Metodas neleidžiamas' })
  }
}

Šiame pavyzdyje API maršrutas tvarko tiek GET, tiek POST užklausas. Jei užklausos metodas yra GET, jis atsako JSON objektu su pranešimu „Tai yra GET užklausa“. Jei užklausos metodas yra POST, jis atsako JSON objektu su pranešimu „Tai yra POST užklausa“. Jei užklausos metodas yra bet koks kitas, jis atsako su 405 Method Not Allowed klaida.

Duomenų skaitymas iš užklausos turinio

POST, PUT ir PATCH užklausoms dažnai reikia skaityti duomenis iš užklausos turinio. Next.js teikia integruotą palaikymą JSON ir URL koduotų užklausų turinių analizavimui. Norėdami išanalizuoti JSON užklausos turinį, galite naudoti req.body savybę. Pavyzdžiui:

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

    // Apdoroti duomenis
    console.log('Vardas:', name)
    console.log('El. paštas:', email)

    res.status(200).json({ message: 'Duomenys sėkmingai gauti' })
  } else {
    res.status(405).json({ message: 'Metodas neleidžiamas' })
  }
}

Norėdami išbandyti šį API maršrutą, galite naudoti įrankį, pvz., „Postman“ arba „curl“, kad išsiųstumėte POST užklausą su JSON turiniu:

curl -X POST -H "Content-Type: application/json" -d '{"name": "Ona Onaitė", "email": "ona.onaite@example.com"}' http://localhost:3000/api/post

Atsakymo antraščių nustatymas

Galite naudoti res.setHeader() metodą atsakymo antraštėms nustatyti. Tai naudinga nustatant turinio tipą, talpyklos valdymą ir kitą svarbią informaciją. Pavyzdžiui:

// 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: 'Sveikas, pasauli!' })
}

Šiame pavyzdyje API maršrutas nustato Content-Type antraštę į application/json, nurodydamas, kad atsakymas yra JSON objektas. Jis taip pat nustato Cache-Control antraštę į s-maxage=3600, kuri nurodo naršyklei ir CDN talpinti atsakymą iki 1 valandos.

Klaidų tvarkymas

Svarbu tinkamai tvarkyti klaidas jūsų API maršrutuose. Galite naudoti „try-catch“ blokus, kad sugautumėte išimtis ir išsiųstumėte atitinkamus klaidų atsakymus klientui. Pavyzdžiui:

// pages/api/error.js
export default async function handler(req, res) {
  try {
    // Imituoti klaidą
    throw new Error('Kažkas nutiko negerai')
  } catch (error) {
    console.error(error)
    res.status(500).json({ message: 'Vidinė serverio klaida' })
  }
}

Šiame pavyzdyje API maršrutas imituoja klaidą, išmesdamas naują Error objektą. „catch“ blokas sugauna klaidą, įrašo ją į konsolę ir siunčia 500 Internal Server Error atsakymą klientui. Apsvarstykite galimybę naudoti patikimą registravimo sistemą, tokią kaip Sentry ar Datadog, gamybinėse aplinkose.

Prisijungimas prie duomenų bazės

Vienas iš dažniausių API maršrutų naudojimo atvejų yra prisijungimas prie duomenų bazės. Next.js API maršrutai sklandžiai integruojasi su įvairiomis duomenų bazėmis, įskaitant:

Štai pavyzdys, kaip prisijungti prie MongoDB duomenų bazės Next.js API maršrute:

// 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('Prašome pridėti savo Mongo URI į .env.local')
}

if (process.env.NODE_ENV === 'development') {
  // Kūrimo režime naudokite globalų kintamąjį, kad vertė
  // būtų išsaugota po modulių perkrovimų, kuriuos sukelia HMR (Hot Module Replacement).
  if (!global._mongoClientPromise) {
    client = new MongoClient(uri, options)
    global._mongoClientPromise = client.connect()
  }
  clientPromise = global._mongoClientPromise
} else {
  // Gamybos režime geriausia nenaudoti globalaus kintamojo.
  client = new MongoClient(uri, options)
  clientPromise = client.connect()
}

// Eksportuokite modulio apimties MongoClient pažadą. Tai darant
// atskirame modulyje, klientas gali būti saugiai pakartotinai naudojamas per kelias
// funkcijas. Žr.: 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: 'Nepavyko gauti vartotojų' })
  }
}

Prieš paleisdami šį kodą, įsitikinkite, kad turite įdiegtą mongodb paketą:

npm install mongodb

Taip pat turite nustatyti MONGODB_URI ir MONGODB_DB aplinkos kintamuosius. Šie kintamieji turėtų būti apibrėžti jūsų .env.local faile (arba jūsų prieglobos paslaugų teikėjo aplinkos kintamųjų nustatymuose gamybai). MONGODB_URI yra jūsų MongoDB duomenų bazės prisijungimo eilutė, o MONGODB_DB nurodo duomenų bazės pavadinimą.

Autentifikavimas ir autorizavimas

Apsaugoti jūsų API maršrutus yra labai svarbu saugumui. Next.js API maršrutus galima apsaugoti naudojant įvairias autentifikavimo ir autorizavimo technikas, įskaitant:

Štai pavyzdys, kaip apsaugoti API maršrutą naudojant JWT autentifikavimą:

// 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: 'Neautorizuota' })
  }

  try {
    const decoded = jwt.verify(token, secret)
    // "decoded" objektas turi vartotojo informaciją, įterptą į liudijimą
    // Pavyzdžiui: const userId = decoded.userId;

    // Tęsti užklausos apdorojimą
    res.status(200).json({ message: 'Saugomas išteklius sėkmingai pasiektas' })
  } catch (error) {
    return res.status(401).json({ message: 'Neteisingas liudijimas' })
  }
}

Prieš paleisdami šį kodą, įsitikinkite, kad turite įdiegtą jsonwebtoken paketą:

npm install jsonwebtoken

Taip pat turite nustatyti JWT_SECRET aplinkos kintamąjį. Tai turėtų būti stiprus, atsitiktinai sugeneruotas slaptas raktas, kuris naudojamas pasirašyti ir patikrinti JWT. Laikykite jį saugiai ir niekada neatskleiskite savo kliento pusės kode.

Tarpinė programinė įranga (Middleware)

Nors Next.js nesiūlo tradicinės tarpinės programinės įrangos API maršrutams taip, kaip Express.js, galite pasiekti panašų funkcionalumą apgaubdami savo API maršrutų tvarkykles pakartotinai naudojamomis funkcijomis. Tai leidžia atlikti tokias užduotis kaip:

Štai pavyzdys, kaip sukurti paprastą registravimo tarpinę programinę įrangą:

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

Norėdami naudoti šią tarpinę programinę įrangą, tiesiog apgaubkite savo API maršruto tvarkyklę withLogging funkcija:

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

async function handler(req, res) {
  res.status(200).json({ message: 'Ši užklausa buvo užregistruota' })
}

export default withLogging(handler)

Geriausios praktikos kuriant Next.js API maršrutus

Pažangios technikos

Fono darbai

Ilgai trunkančioms užduotims, kurios neturėtų blokuoti API atsakymo, apsvarstykite galimybę naudoti fono darbus. Galite naudoti bibliotekas, tokias kaip BullMQ ar Bree, kad valdytumėte savo fono darbus ir apdorotumėte juos asinchroniškai.

WebSockets

Realaus laiko programoms galite naudoti WebSockets savo Next.js API maršrutuose. Bibliotekos, tokios kaip Socket.IO ir ws, palengvina nuolatinių ryšių tarp kliento ir serverio sukūrimą.

GraphQL

Jei jums reikia lankstesnio ir efektyvesnio būdo gauti duomenis, apsvarstykite galimybę naudoti GraphQL. Galite naudoti bibliotekas, tokias kaip Apollo Server ar Yoga, kad sukurtumėte GraphQL API galinį tašką savo Next.js programoje.

Išvada

Next.js API maršrutai suteikia galingą ir patogų būdą kurti „serverless“ „backend“ tiesiogiai jūsų Next.js programoje. Pasinaudodami „serverless“ architektūros privalumais, galite supaprastinti kūrimą, pagerinti našumą ir sumažinti išlaidas. Nesvarbu, ar kuriate paprastą kontaktų formą, ar sudėtingą el. prekybos platformą, Next.js API maršrutai gali padėti jums lengvai sukurti tvirtą ir keičiamo dydžio „backend“. Turėdami tvirtą pagrindų supratimą ir taikydami geriausias praktikas, galite pasinaudoti šiuo galingu įrankiu kurdami efektyvias, saugias ir visame pasaulyje prieinamas programas.