Next.js từ cơ bản đến nâng cao
Trang chủ / Module 8
🛣️ Module 8 / 18 · 4 ngày 📅 Tuần 5 ●●○○ Trung bình

Route Handlers, proxy (middleware) và after()

Khi nào dùng Route Handler thay vì Server Action, viết API REST và webhook, streaming response, proxy.ts (trước là middleware.ts) cho redirect/rewrite/i18n/kiểm tra nhanh, và after() cho việc sau phản hồi.

route.tsproxy.tsWebhookafter()
📌 Vì sao module này quan trọng

Không phải mọi thứ đều là Server Action: webhook từ Stripe, API cho app mobile, OAuth callback, tải file cần một endpoint HTTP thật. Proxy chạy trước mọi request — mạnh nhưng nguy hiểm nếu dùng làm lớp bảo mật duy nhất.

🎯 Mục tiêu học tập

  • Viết Route Handler cho REST API, webhook, streaming
  • Chọn đúng giữa Server Action, Route Handler và Server Component
  • Viết proxy.ts cho redirect, rewrite, header, i18n
  • Hiểu giới hạn của proxy và bài học CVE-2025-29927
  • Dùng after() cho việc nền sau khi trả phản hồi

Route Handler

// app/api/products/route.ts
import { NextResponse, type NextRequest } from 'next/server';

export async function GET(req: NextRequest) {
  const q = req.nextUrl.searchParams.get('q') ?? '';
  const items = await searchProducts(q);
  return NextResponse.json({ items }, { headers: { 'Cache-Control': 'public, s-maxage=60' } });
}

export async function POST(req: NextRequest) {
  const session = await verifyBearer(req.headers.get('authorization'));
  if (!session) return NextResponse.json({ error: 'unauthorized' }, { status: 401 });
  const body = CreateProductSchema.safeParse(await req.json());
  if (!body.success) return NextResponse.json({ error: z.flattenError(body.error) }, { status: 422 });
  const created = await createProduct(body.data);
  return NextResponse.json(created, { status: 201, headers: { Location: `/api/products/${created.id}` } });
}

// app/api/products/[id]/route.ts
export async function GET(_req: Request, ctx: RouteContext<'/api/products/[id]'>) {
  const { id } = await ctx.params;
  // ...
}

route.ts và page.tsx không được nằm cùng một segment. GET handler không cache mặc định (từ Next.js 15).

Chọn công cụ nào

ViệcDùng
Đọc dữ liệu để render trangServer Component
Mutation từ giao diện của chính appServer Action
Webhook (Stripe, GitHub, CMS), OAuth callbackRoute Handler
API công khai cho mobile/đối tác, cần versioning, OpenAPIRoute Handler — hoặc backend riêng (NestJS) khi lớn
Trả file, stream (CSV, SSE, AI response)Route Handler
Client Component fetch dữ liệu (polling, infinite scroll)Route Handler + TanStack Query

Webhook và streaming

// app/api/webhooks/stripe/route.ts
export async function POST(req: Request) {
  const raw = await req.text();                                   // chữ ký tính trên body thô
  const sig = req.headers.get('stripe-signature')!;
  let event: Stripe.Event;
  try { event = stripe.webhooks.constructEvent(raw, sig, process.env.STRIPE_WEBHOOK_SECRET!); }
  catch { return new Response('invalid signature', { status: 400 }); }

  const firstTime = await markEventProcessed(event.id);          // idempotency: Stripe có thể gửi lại
  if (firstTime && event.type === 'checkout.session.completed') await fulfillOrder(event.data.object);
  return new Response('ok');                                      // trả nhanh; việc nặng đẩy vào queue
}

// Server-Sent Events
export async function GET() {
  const stream = new ReadableStream({
    async start(controller) {
      for await (const chunk of generateReport()) controller.enqueue(new TextEncoder().encode(`data: ${chunk}\n\n`));
      controller.close();
    },
  });
  return new Response(stream, { headers: { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache' } });
}

proxy.ts

Next.js 16 đổi tên middleware.ts thành proxy.ts (hàm export tên proxy) để nói rõ vai trò: một lớp đứng trước ứng dụng, chạy trên Node.js runtime. middleware.ts cũ vẫn chạy nhưng đã deprecated.

// proxy.ts (cùng cấp app/ hoặc trong src/)
import { NextResponse, type NextRequest } from 'next/server';

const LOCALES = ['vi', 'en'];

export function proxy(req: NextRequest) {
  const { pathname } = req.nextUrl;

  // 1. i18n: thêm locale vào URL
  if (!LOCALES.some(l => pathname === `/${l}` || pathname.startsWith(`/${l}/`))) {
    const locale = req.headers.get('accept-language')?.startsWith('en') ? 'en' : 'vi';
    return NextResponse.redirect(new URL(`/${locale}${pathname}`, req.url));
  }

  // 2. Kiểm tra lạc quan: chưa có cookie phiên thì về trang login (KHÔNG phải kiểm tra quyền thật)
  if (pathname.includes('/dashboard') && !req.cookies.has('session')) {
    return NextResponse.redirect(new URL('/vi/login', req.url));
  }

  // 3. Gắn header
  const res = NextResponse.next();
  res.headers.set('x-request-id', crypto.randomUUID());
  return res;
}

export const config = {
  matcher: ['/((?!api|_next/static|_next/image|favicon.ico|.*\\.(?:png|jpg|svg)$).*)'],
};
⚠️ Bài học CVE-2025-29927

Tháng 3/2025, một lỗ hổng cho phép bỏ qua hoàn toàn middleware bằng cách gửi header nội bộ x-middleware-subrequest. Ứng dụng nào chỉ kiểm tra quyền trong middleware đều bị lộ. Nguyên tắc: proxy dùng cho redirect/rewrite và kiểm tra lạc quan; kiểm tra quyền thật nằm gần dữ liệu — trong Data Access Layer, Server Action, Route Handler (Module 9, 10).

Proxy chạy trên mọi request khớp matcher → giữ nó nhẹ: không query DB nặng, không gọi API chậm.

after(): làm việc sau khi đã trả phản hồi

import { after } from 'next/server';

export async function POST(req: Request) {
  const order = await createOrder(await req.json());
  after(async () => {                       // chạy sau khi response đã gửi
    await sendConfirmationEmail(order);
    await analytics.track('order_created', { id: order.id });
  });
  return Response.json(order, { status: 201 });
}

Dùng được trong Server Component, Server Action, Route Handler, proxy. Việc quan trọng phải đảm bảo chạy (trừ tiền, gửi hàng) vẫn nên đưa vào queue bền (Cloud Tasks, BullMQ, Inngest) — after không retry khi tiến trình chết.

🚩 Sai lầm hay gặp

  • Kiểm tra quyền chỉ trong proxy/middleware.
  • Webhook không xác minh chữ ký, không idempotent.
  • Proxy query DB trên mọi request (kể cả ảnh, CSS) vì matcher quá rộng.

🏋️ Bài tập thực hành

API công khai + webhook + i18n

Viết /api/v1/products (GET danh sách có phân trang, POST tạo có Bearer token) kèm tài liệu OpenAPI ngắn; webhook giả lập có xác minh HMAC và idempotency; proxy.ts xử lý locale vi/en. Dùng after() ghi log truy cập API.

📚 Tài nguyên học tập

✅ Tự đánh giá hoàn thành

  • Tôi chọn đúng giữa Server Component, Server Action, Route Handler
  • Tôi viết được webhook xác minh chữ ký và idempotent
  • Tôi viết được proxy.ts với matcher hợp lý
  • Tôi giải thích được bài học CVE-2025-29927