12. NestJS Mimarisi: Route Wildcard ve Prefixler (10. Bölüm)

Rota Yönetiminde Bir Seviye Yukarı: Wildcard ve Prefix Kullanımı

Normalde rotaları şöyle tanımlarız:

@Controller('users')
export class UserController {
  @Get()
  getAll() { ... }

  @Get(':id')
  getById(@Param('id') id: string) { ... }
}

Ama bazı durumlarda daha esnek tanımlamalar gerekebilir:

Tüm istekleri karşılayan bir “catch-all” route
Belirli bir grup route’a ön ek tanımlama
Statik dosyalar, client-side SPA fallback gibi durumlar

İşte burada wildcard ve prefix kavramları devreye giriyor.

1. Route Prefix Nedir?

Prefix, bir grup route’un başına otomatik olarak eklenen ortak path’tir.

Global Prefix:

Tüm uygulamanın başına bir ön ek eklemek için main.ts içinde:

const app = await NestFactory.create(AppModule);
app.setGlobalPrefix('api');

Artık tüm route’lar /api ile başlar: Örneğin GET /users -> GET /api/users

Versiyonlama için Prefix Kullanımı:

app.setGlobalPrefix('v1');

veya dinamik:

app.setGlobalPrefix('api/v1');

Bu yöntem, API sürümlerini yönetmenin basit ama etkili bir yoludur.

2. Controller Bazlı Prefix (Decorator Üzerinden)

@Controller('auth')
export class AuthController {
  @Get('login')
  login() {} // /auth/login
}

Yani prefix sadece setGlobalPrefix ile değil, @Controller('prefix') ile de tanımlanabilir.

Bunlar birbirinin üzerine bindirilebilir.

app.setGlobalPrefix('api');
@Controller('users')
// -> /api/users

3. Route Wildcard Nedir?

Wildcard = “joker” karakterdir. Belirli bir pattern’e uymayan istekleri karşılamak için kullanılır.

@Controller('*')
export class FallbackController {
  @Get()
  handleAll(@Req() req: Request) {
    return `Böyle bir route yok: ${req.url}`;
  }
}

Bu yapı, tanımlanmamış tüm GET isteklerini yakalar. Özellikle Single Page Application (SPA) projelerinde, frontend’e fallback yapılmak isteniyorsa ideal çözümdür.

Route İçinde Wildcard Kullanımı:

@Get('docs/*')
handleDocs(@Req() req: Request) {
  return `Docs yolu: ${req.url}`;
}

Bu, tüm docs/... yollarını karşılar. Yani /docs/intro, /docs/setup, /docs/anything hepsi bu method’a gelir.

4. @All() - Tüm HTTP Metodlarını Yakalamak

@All('*')
handleAnything(@Req() req: Request) {
  return `Method: ${req.method}, Path: ${req.url}`;
}

Bu, sadece path’i değil aynı zamanda GET, POST, PUT, DELETE gibi tüm HTTP metodlarını kapsar. Genelde fallback API handler’larda, loglamalarda veya yetkisiz erişim yakalayıcılarında kullanılır.

5. Wildcard Kullanırken Nelere Dikkat Etmeli?

Sıralama önemli: NestJS route tanımlarını sırayla işler. @Get('*') gibi wildcard route’lar en sona bırakılmalıdır, aksi takdirde diğer route’lar çalışmaz.
Performance: Çok geniş wildcard tanımları (örneğin *) response time’ı etkileyebilir. Özellikle log veya proxy gibi yapılarda dikkatli ol.
Test yazmayı zorlaştırır: Her şeyi yakalayan controller, hata ayıklarken nereye düştüğünü anlamayı zorlaştırabilir.

Ne Zaman Kullanılır, Ne Zaman Kullanılmaz?

SenaryoKullanım Uygun mu?SPA fallback (Angular, React, Vue frontend)EvetTüm bilinmeyen route’ları loglamakEvetAdmin panel prefix yapısıEvetAPI sürümlemeEvetTüm rotaları tek * ile karşılamakHayır, kötü pratik“Kodu az olsun” diye tüm path’leri wildcard yapmakÇok kötü fikir

Özet

setGlobalPrefix() -> tüm uygulamanın path başına ön ek ekler
@Controller('prefix') -> controller bazında ön ek tanımlar
@Get('*'), @All('*') gibi wildcard tanımlarla bilinmeyen path’ler yakalanabilir
SPA uygulamalarında client-side route’lara düşmek için kullanılır
Dikkatsiz wildcard kullanımı diğer rotaların çalışmamasına yol açar
Wildcard route’lar en sona yazılmalı