Type-Safe Next.js API Routes

Zod tabanlı doğrulama, typed fetch ve test mimarisi

TypeScript ve Zod birlikteliği, API katmanında runtime doğrulamasını güçlü hale getirir. Bu yol haritası TypeScript platform mühendisi profiline yönelik hazırlanmış olup Next.js API Routes, Zod, ts-rest, Vitest araçlarıyla uygulanabilir.

Şema ve Doğrulama

Zod şemaları paylaşılamazsa client-server tür uyuşmazlığı yaşanır.

• Shared package ile schema export
• Infer edilen TypeScript türleri
• ts-rest ile contract-first yaklaşım

Typed Fetch ve SDK

Typed fetch wrapper’ı olmadan istemci hataları geç fark edilir.

• ts-rest client jenerasyonu
• React Query adapter’
• Error boundary ile tür tabanlı ayrım

Test ve Observability

API testleri kontratı kontrol etmezse refactor riski artar.

• Vitest + Supertest ile e2e
• Contract snapshot testleri
• Structured log ile hata izleme

Başarı Metrikleri

• Runtime validation hatası: -%50 — Zod şemaları paylaşılınca azaldı.
• Client bug raporu: -%35 — Typed fetch wrapper sayesinde.
• Test kapsamı: +%20 — Contract snapshot testleri eklendi.

Kod Örneği — Zod + ts-rest route

export const appRouter = initServer().router({
  create: {
    method: 'POST',
    path: '/',
    responses: {
      201: PostSchema,
    },
    body: PostSchema.pick({ title: true }),
  },
});

Uygulama Kontrol Listesi

• Shared schema paketi oluştur.
• ts-rest ile typed SDK üret.
• React Query adapter’ı yaz.
• Contract snapshot testleri ekle.
• Structured logging’i standartlaştır.

Anahtar odaklar: typescript, nextjs api, validation.