Frontend Academy · Lezione

Route API e Middleware di Next.js

Creare endpoint API serverless nella directory api/, elaborare le richieste nei Route Handler ed eseguire Middleware edge per autenticazione e redirect

Lezione 4 di 414 passaggi

Route API e Middleware di Next.js è una lezione Frontend Academy gratuita su CoddyKit. Questa è la lezione 4 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento Frontend Academy, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso Frontend Academy include 4 lezioni in totale.

Perché usare le API Routes?

Next.js include un server insieme all'app: può scrivere endpoint backend accanto alle pagine senza un progetto Node separato. È ideale per proxy, invio di moduli, webhook e API di piccole dimensioni.

API Routes del Pages Router

I file in pages/api/ esportano una funzione predefinita con req/res in stile Express.

// pages/api/users.ts
import type { NextApiRequest, NextApiResponse } from 'next';

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  if (req.method === 'GET') {
    const users = await db.users.findMany();
    return res.json(users);
  }
  if (req.method === 'POST') {
    const user = await db.users.create({ data: req.body });
    return res.status(201).json(user);
  }
  return res.status(405).end();
}

Route Handlers dell'App Router

L'App Router utilizza le API standard del Web Request/Response. Ogni metodo HTTP è un'esportazione denominata.

// app/api/users/route.ts
import { NextResponse } from 'next/server';

export async function GET() {
  const users = await db.users.findMany();
  return NextResponse.json(users);
}

export async function POST(request: Request) {
  const body = await request.json();
  const user = await db.users.create({ data: body });
  return NextResponse.json(user, { status: 201 });
}

API Routes dinamiche

I segmenti dinamici funzionano allo stesso modo: app/api/users/[id]/route.ts corrisponde a /api/users/123.

// app/api/users/[id]/route.ts
export async function GET(req: Request, { params }: { params: { id: string }}) {
  const user = await db.users.findUnique({ where: { id: params.id }});
  if (!user) return new Response('Not Found', { status: 404 });
  return Response.json(user);
}

Leggere cookie e header

Nell'App Router, utilizzi gli helper di next/headers, con ambito limitato alla richiesta.

import { cookies, headers } from 'next/headers';

export async function GET() {
  const token = cookies().get('token')?.value;
  const userAgent = headers().get('user-agent');
  // ...
}

Risposte in streaming

I route handler possono restituire una risposta in streaming, utile per i completamenti di chat basati sull'IA o per la generazione di file di grandi dimensioni.

export async function GET() {
  const encoder = new TextEncoder();
  const stream = new ReadableStream({
    async start(controller) {
      for (let i = 0; i < 5; i++) {
        controller.enqueue(encoder.encode(`chunk ${i}\n`));
        await new Promise(r => setTimeout(r, 500));
      }
      controller.close();
    }
  });
  return new Response(stream);
}

Middleware — Esecuzione prima delle route

middleware.ts nella radice del progetto viene eseguito prima che le richieste raggiungano le pagine o le API Routes. Lo utilizzi per controlli di autenticazione, reindirizzamenti, riscrittura degli header e test A/B.

// middleware.ts
import { NextResponse, type NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
  const token = request.cookies.get('token');
  if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {
    return NextResponse.redirect(new URL('/login', request.url));
  }
  return NextResponse.next();
}

Matcher del middleware

Limiti i percorsi sui quali viene eseguito il middleware con una configurazione matcher.

export const config = {
  matcher: [
    '/dashboard/:path*',
    '/api/:path*',
    '/((?!_next/static|_next/image|favicon.ico).*)'
  ]
};

Runtime del middleware

Il middleware viene eseguito per impostazione predefinita nell'Edge Runtime, un V8 isolate leggero, non un Node completo. Le API disponibili sono limitate: niente moduli Node come fs né dipendenze native.

Schema di autenticazione con il middleware

Schema comune: verifichi un JWT nel middleware, reindirizzi al login se manca o non è valido e aggiunga l'utente decodificato a un header della richiesta che le route a valle possono leggere.

import jwt from 'jsonwebtoken';

export function middleware(req: NextRequest) {
  const token = req.cookies.get('token')?.value;
  if (!token) return NextResponse.redirect(new URL('/login', req.url));
  try {
    const decoded = jwt.verify(token, process.env.SECRET!);
    const res = NextResponse.next();
    res.headers.set('x-user-id', String(decoded.sub));
    return res;
  } catch {
    return NextResponse.redirect(new URL('/login', req.url));
  }
}

Limitazione della frequenza nel middleware

Combini il middleware con un archivio KV, come Upstash o Vercel KV, per applicare limiti di frequenza per indirizzo IP prima di raggiungere la logica delle API.

Quando NON usare le API Routes

Per microservizi separati o API condivise, distribuisca un backend reale, come Hono, Express o NestJS. Le API Routes di Next.js sono ideali per proxy, webhook ed endpoint specifici dell'app, non per fornire un'API pubblica ad altri client.

Verifica rapida

Dove viene eseguito il middleware di Next.js e qual è il caso d'uso più comune?

Rispondi nella lezione interattiva

Riepilogo: API Routes e middleware

Pages Router: pages/api con req/res. App Router: app/api/.../route.ts con esportazioni dei metodi (GET/POST/e così via) che utilizzano Request/Response. Legga cookie e header tramite next/headers. Utilizzi ReadableStream per le risposte in streaming. middleware.ts viene eseguito sull'Edge prima delle route: autenticazione, reindirizzamenti e header. La configurazione matcher limita i percorsi. Utilizzi un backend reale per le API pubbliche.

Gratis per iniziare

Impara HTML con un tutor IA — gratis

Scrivi ed esegui vero codice nel tuo browser, ricevi aiuto istantaneo da un tutor IA disponibile 24/7, e riprendi da dove hai lasciato sul web o nell'app.

Corsi: 41
Lezioni: 163

Inizia a imparare gratis Visualizza il corso completo

Domande Frequenti

La lezione «Route API e Middleware di Next.js» è gratuita?

Sì — il testo completo di «Route API e Middleware di Next.js» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso Frontend Academy, passa a CoddyKit PRO. Il corso Frontend Academy include 4 lezioni in totale.

Cosa imparerò in «Route API e Middleware di Next.js»?

Creare endpoint API serverless nella directory api/, elaborare le richieste nei Route Handler ed eseguire Middleware edge per autenticazione e redirect Eserciti Frontend Academy con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.

Ho bisogno di esperienza per iniziare Frontend Academy?

Non è richiesta alcuna esperienza precedente. Frontend Academy su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 4 di 4.

Quanto tempo richiede la lezione «Route API e Middleware di Next.js»?

La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.

Posso scrivere ed eseguire codice in questa lezione Frontend Academy?

Sì. Ogni lezione Frontend Academy include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.

Tutte le lezioni di questo corso

← Torna a Frontend Academy