Route Handler ve proxy

Hangisi Ne İçin

Next.js'te sunucuda kod çalıştırmanın dört yolu var. Yanlış olanı seçmek, App Router'daki en yaygın hatalardan biri:¹

Route Handler

route.ts dosyası, Web standardı Request ve Response ile çalışan bir HTTP uç noktasıdır. Her HTTP metodu için bir fonksiyon export edersiniz.²

// app/api/products/[slug]/route.ts
import type { NextRequest } from "next/server";

import { getProduct } from "@/lib/products";

export async function GET(_request: NextRequest, ctx: RouteContext<"/api/products/[slug]">) {
  const { slug } = await ctx.params;
  const product = await getProduct(slug);

  if (!product) {
    return Response.json({ error: "Not found" }, { status: 404 });
  }

  return Response.json({ slug: product.slug, name: product.name, price: product.price });
}

RouteContext, PageProps gibi global bir yardımcıdır; params tipini klasörden üretir.² Aynı klasörde hem page.tsx hem route.ts olamaz; ikisi de o adresin tüm isteklerini üstlenir.²

Cache Components açıkken GET handler'ları sayfalarla aynı kurala uyar: istek verisi okumuyorsa build'de statik üretilir, okuyorsa istek anında çalışır. "use cache"'i doğrudan handler'a değil, çağırdığı yardımcı fonksiyona yazın.²

Webhook: CMS Değişince Cache'i Yenilemek

Bir CMS içerik değişince sizin adresinize istek atabilir. Handler isteği doğrular ve ilgili etiketi yeniler:³

// app/api/revalidate/route.ts
import { revalidateTag } from "next/cache";
import type { NextRequest } from "next/server";

export async function POST(request: NextRequest) {
  if (request.headers.get("x-revalidate-secret") !== process.env.REVALIDATE_SECRET) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { slug } = (await request.json()) as { slug?: string };
  revalidateTag(slug ? `product-${slug}` : "products", "max");

  return Response.json({ revalidated: true });
}

Route Handler'lar da açık uç noktalardır. Dokümanın güvenlik listesi kısa: gelen başlıklara güvenmeyin, rate limit koyun, webhook gövdesini sağlayıcının imzasıyla doğrulayın ve korunan kaynaklarda yetki kontrol edin.³ Rol kontrolü örneği Yetkilendirme ve roller dersinde.

Yanıttan sonra çalışacak işler (log, analitik) için after() kullanın; kullanıcı yanıtı beklemez.⁴

import { after } from "next/server";

after(() => logEvent("product_revalidated"));

proxy.ts

Next.js 16'da middleware.ts'in adı proxy.ts oldu. İş aynı: istek uygulamaya ulaşmadan önce çalışır, yönlendirir, rewrite eder ya da başlık değiştirir. Varsayılan olarak Node.js runtime'ında çalışır.⁵⁶

Örnek: ana sayfanın iki tasarımını A/B testiyle denemek. Kullanıcı bir gruba atanır, B grubu URL değişmeden /home-b sayfasını görür:

// proxy.ts
import { type NextRequest, NextResponse } from "next/server";

export function proxy(request: NextRequest) {
  const bucket = request.cookies.get("home-test")?.value ?? (Math.random() < 0.5 ? "a" : "b");

  const response =
    bucket === "b"
      ? NextResponse.rewrite(new URL("/home-b", request.url))
      : NextResponse.next();

  response.cookies.set("home-test", bucket);
  return response;
}

export const config = {
  matcher: "/",
};

İki kural:

• matcher'ı unutmayın. Yoksa proxy statik dosyalar ve görseller dahil her istekte çalışır; yanlış bir yönlendirme CSS'i ve resimleri de engelleyebilir.⁵

• Basit yönlendirme için önce next.config.ts'teki redirects'e bakın. Proxy, istek verisine bakan mantık için.⁶

Kendin Dene

• app/api/products/[slug]/route.ts'i yazın ve curl localhost:3000/api/products/canvas-sneaker ile çağırın.

• Webhook'u gizli anahtar olmadan ve anahtarla çağırın; iki yanıtı karşılaştırın.

• A/B örneğini kurun, home-test cookie'sini DevTools'tan silip sayfayı birkaç kez yenileyin.

• proxy.ts'ten matcher'ı silin ve her isteğe console.log yazdırın. Bir sayfa açılınca kaç kez çalışıyor?

• next.config.ts'e /old-shop → /products yönlendirmesini redirects ile ekleyin.

Detaylı Öğrenmek İçin

• Resmi doküman: "Backend for Frontend" rehberi; içerik türleri, bir backend'e proxy'leme, webhook'lar, güvenlik ve sınırlar.³

• Yazı: Lee Robinson, "Common mistakes with the Next.js App Router"; Route Handler'ı gereksiz kullanmak ve diğer hatalar.¹

• Resmi doküman: proxy.js referansı; matcher kalıpları, cookie ve başlık okuma, middleware'den geçiş.⁵