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.
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.tscho 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ệc | Dùng |
|---|---|
| Đọc dữ liệu để render trang | Server Component |
| Mutation từ giao diện của chính app | Server Action |
| Webhook (Stripe, GitHub, CMS), OAuth callback | Route Handler |
| API công khai cho mobile/đối tác, cần versioning, OpenAPI | Route 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)$).*)'],
};
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
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
-
Next.js — Route HandlersHướng dẫnDocs
-
Next.js — proxy.jsAPI referenceDocs
-
Next.js — afterAPI referenceDocs
✅ 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