Frontend'den backend'e · 11 durak

NestJS Hattı

Bu eğitim, Next.js ve TypeScript deneyimi olan frontend geliştiriciler için hazırlanmıştır. Bir HTTP isteğinin sunucuya ulaşmasından veritabanına yazılıp yanıt olarak dönmesine kadar geçen süreç, NestJS üzerinden adım adım ele alınır.

Duraklar sıralıdır; istenen durağa doğrudan geçilebilir.

Paket bir HTTP isteğini temsil eder. Duraklar boyunca isteğin doğrulanması, servislerde işlenmesi, veritabanına yazılması ve yanıt olarak dönmesi Paket üzerinden gösterilir.

Bilet · tek yön

Frontend Fullstack

11 durak5 hat~3 sa 50 dk

İlk durak01

Hat haritası

Bir durağa tıklanarak o durağa geçilir. Ziyaret edilen duraklar dolu gösterilir.

Next.js karşılıkları

Next.js projelerinde kullanılan yapıların NestJS'teki karşılıkları.

Next.js'teNestJS'teDurak

app/(shop), app/(account) route group'ları→Domain'e göre ayrılmış modüller

app/api/orders/route.ts→Controller

lib/ altındaki iş mantığı fonksiyonları→Service

Context Provider + useContext→Provider + constructor injection

proxy.ts→Middleware, Guard, Interceptor

Zod şeması ile form doğrulama→DTO + class-validator

if (!res.ok) kontrolü→HTTP status + Exception

Prisma / Drizzle şeması→Entity + Repository

Sıralı veya seçmeli

Duraklar birbirinin üzerine kurulur; ancak her durak tek başına da okunabilir. Üst şeritteki hattan istenen durağa geçilebilir.

Etkileşimli sahneler

Sahnelerdeki kontroller animasyonları yeniden oynatır ve farklı durumların karşılaştırılmasını sağlar.

Klavye ile gezinme

← → tuşlarıyla duraklar arasında geçiş yapılır. Her durak kısa bir değerlendirme ile sona erer.

01

Temel hattı · Durak 01 · ~15 dk

Type Safety

Type safety, bir fonksiyonun veya verinin giriş ve çıkış tiplerinin açıkça tanımlanmasıdır. Bu durakta önce tanım, sağladıkları ve sınırları ele alınır; ardından beş örnekle pekiştirilir.

Tanım

Type safety nedir?

type safetytip güvenliği

Bir fonksiyonun veya verinin giriş ve çıkış tiplerinin açıkça tanımlanması ve bu tanımlara uyulduğunun derleyici tarafından denetlenmesidir.

Fonksiyon yalnızca tanımlanan tipte veriyi kabul eder ve yalnızca tanımlanan tipte veriyi döndürür. Böylece fonksiyonu yazan ile çağıran arasındaki beklenti nettir. Tip tanımı olmasaydı, örneğin number beklenen bir yerde string işlenebilir veya döndürülebilir ve hata ancak çalışma anında fark edilirdi.

function orderTotal(price: number, shipping: number): number {
  return price + shipping;
}

giriş tipleriçıkış tipi

price değeri:

Giriş tipleri uygun. Çıkış tipi number olarak tanımlı olduğundan sonuç da number: 150.

Ne sağlar

Net sözleşme. Fonksiyonun ne aldığı ve ne döndürdüğü imzasından okunur.
Erken hata tespiti. Uyumsuz çağrılar kod yazılırken ve derleme sırasında raporlanır.
Güvenli değişiklik. Bir tip değiştiğinde etkilenen tüm noktalar derleyici tarafından listelenir.
Editör desteği. Otomatik tamamlama ve öneriler tip bilgisine göre çalışır.

Tanımlanmazsa

number beklenen yerde string işlenebilir veya döndürülebilir: "120" + 30 sonucu "12030" olur.
Hata derlemede değil, çalışma anında ve çoğunlukla production'da ortaya çıkar.
Hatalı veri veritabanına yazılabilir ve o veriyi okuyan tüm istemcileri etkiler.
Fonksiyonun davranışı ancak kod okunarak veya çalıştırılarak anlaşılır.

Sınırları

Tipler yalnızca derleme anında denetlenir; derleme sonrasında koddan silinir.
Dışarıdan gelen veri (request body) için ayrıca runtime validation gerekir (Durak 07).
Tiplerin yazılması ve güncel tutulması ek emek gerektirir.
any kullanımı ve kapalı strict mod korumayı zayıflatır.

Aşağıdaki beş örnek bu tanımı sırasıyla pekiştirir: tipsiz giriş, hatanın yakalandığı aşama, backend'deki etki, null ve strict mod, tiplerin çalışma anındaki sınırı.

Örnek 1 · Tipsiz giriş

Giriş tipi tanımlanmamış bir fonksiyon

Bu örnek, giriş tipi tanımlanmamış bir fonksiyonun yanlış tipte veriyle çağrıldığında nasıl davrandığını gösterir.

orderTotal fonksiyonu fiyat ile kargo ücretini toplar. Mobil uygulama fiyatı "199.90" (string) olarak gönderdiğinde + operatörü toplama yerine metin birleştirme yapar. Uygulama hata vermez; yanlış toplam müşteriye ulaşır. TypeScript sürümünde aynı çağrı derleme aşamasında reddedilir.

order.js

function orderTotal(price, shipping) {
  return price + shipping;
}

orderTotal("199.90", 29.9);
// → "199.9029.9"

order.ts

function orderTotal(
  price: number,
  shipping: number,
): number {
  return price + shipping;
}

orderTotal("199.90", 29.9);
// TS2345: Argument of type 'string' is not
//! assignable to parameter of type 'number'.

Uygulama hata vermedi; yanlış toplam (₺199.9029.9) müşteriye ulaştı.

Örnek 2 · Yakalanma aşaması

Hata ne kadar geç yakalanırsa maliyeti o kadar artar.

Bu örnek, tip tanımının hatanın hangi aşamada yakalandığını nasıl değiştirdiğini gösterir. Bir hata kullanıcıya ulaşmadan önce dört aşamadan geçer: kod yazımı, build, test ve production. Tip tanımlı kodda tip hataları ilk aşamada, editörde raporlanır. Tip tanımı olmayan kodda bu hatalar genellikle production'da fark edilir.

Hatalı çağrı gönderilmeye hazır.

Örnek 3 · Backend'de etki

Backend'deki tip hatası kalıcı veriyi etkiler.

Bu örnek, tip hatasının frontend ve backend'de neden farklı ölçekte sonuç doğurduğunu gösterir. Frontend'deki bir tip hatası genellikle tek bir ekranı etkiler ve sayfa yenilendiğinde ortadan kalkar. Backend'de ise hatalı değer veritabanına yazılır; bu veriyi okuyan tüm istemciler (web, mobil, admin paneli, raporlama) aynı hatalı veriyi alır.

Mobil uygulama bir sipariş göndermek üzere.

Örnek 4 · null ve strict

null ihtimali tipin bir parçasıdır.

Bu örnek, çıkış tipinin bir parçası olan null ihtimalinin derleyici tarafından nasıl denetlendiğini gösterir. Veritabanında aranan kayıt bulunamayabilir; bu nedenle TypeORM'un findOneBy metodu Product | null döndürür. strict mod kapalıyken derleyici null ihtimalini dikkate almaz. Açıkken bu ihtimal ele alınmadan kod derlenmez.

products.service.tsstrict: false

async getPrice(id: number): Promise<number> {  const product = await this.productRepo.findOneBy({ id });  if (!product) {    throw new NotFoundException('Ürün bulunamadı');  }  return product.price; // product: Product}

Derleyicinin gördüğü tip

product:Product| null

Örnek 5 · Tiplerin sınırı

Tipler yalnızca derleme anında vardır.

Bu örnek, tanımın "Sınırları" başlığındaki ilk maddeyi gösterir. TypeScript bir derleme aracıdır: tsc kodu JavaScript'e çevirirken tüm tip tanımlarını kaldırır ve sunucuda çalışan kod JavaScript'tir. Bu nedenle dışarıdan gelen istek gövdesi (request body) çalışma anında tip denetiminden geçmez.

Derleme sonrasında tip tanımlarına ne olduğunu görmek için Derle'ye basın.

order-item.tsderleme anı

interface OrderItem {
  product_id: number;
  quantity: number;
}

function lineTotal(item: OrderItem, unitPrice: number): number {
  return item.quantity * unitPrice;
}

Çalışma anı · sunucuya gelen istek

POST /orders/items { "product_id": 7, "quantity": "iki" }

lineTotal(item, 199.9) → NaN

TypeScriptDerleme anında, yazılan kodu denetler.

DTO + validationÇalışma anında, dışarıdan gelen veriyi denetler.

create-order-item.dto.tsDurak 07

export class CreateOrderItemDto {
  @IsInt()
  product_id: number;

  @IsInt()
  @Min(1)
  quantity: number;
}

Kurallar

Backend'de TypeScript kullanım kuralları

Aşağıdaki altı kural, tip güvenliğinin projede tutarlı biçimde uygulanmasını sağlar. Her kartta önce kurala aykırı kullanım gösterilir; Düzelt butonu kurala uygun hâlini ve derleyicinin tepkisini gösterir.

strict: true kullanın

Önce

Projenin başında etkinleştirilmelidir. Sonradan etkinleştirmek, birikmiş çok sayıda hatanın aynı anda düzeltilmesini gerektirir.

// tsconfig.json
{
  "compilerOptions": {
    "strict": false
  }
}

// tsconfig.json
{
  "compilerOptions": {
    "strict": true
  }
}
// null denetimi, implicit any
// ve diğer kontroller etkin

any yerine unknown

Önce

any tip denetimini tamamen devre dışı bırakır. unknown ise değerin kullanılmadan önce doğrulanmasını zorunlu kılar.

const body: any = await res.json();
body.totl.toFixed(2);
// yazım hatası, derleyici uyarmaz

const body: unknown = await res.json();
body.total;
// TS18046: 'body' is of type 'unknown'.
//! Değer kullanılmadan önce doğrulanmalı.

Dönüş tipini yazın

Önce

Dönüş tipi fonksiyonun sözleşmesidir. Yanlış yapıda veri döndürülmesi derleme aşamasında yakalanır.

async getSummary(id: number) {
  return { totl: 120 };
}
// dönüş tipi çıkarım ile belirleniyor,
// yazım hatası fark edilmiyor

async getSummary(
  id: number,
): Promise<OrderSummary> {
  return { totl: 120 };
}
// TS2561: 'totl' does not exist
//! in type 'OrderSummary'.

Sabit değerler için union

Önce

Sipariş durumları sonlu bir kümedir. Bu küme tip olarak tanımlandığında yazım hataları derleyici tarafından yakalanır.

order.status = 'shiped';
// yazım hatası fark edilmiyor

type OrderStatus =
  | 'pending'
  | 'paid'
  | 'shipped';

order.status = 'shiped';
// TS2820: Did you mean '"shipped"'?

Inline tip yerine isimli tip

Önce

Aynı yapı birden fazla yerde tanımlanırsa bir yerdeki değişiklik diğerlerinde unutulabilir. Yapı tek bir dosyada tanımlanmalı ve isimle kullanılmalıdır.

create(body: {
  name: string;
  price: number;
}) {}

update(body: {
  name: string;
  price: number;
}) {}

// dto/create-product.dto.ts
export class CreateProductDto {
  name: string;
  price: number;
}

create(body: CreateProductDto) {}

Tekrar yerine generic

Önce

Sayfalama yapısı tüm listelerde aynıdır. Yapı bir kez generic olarak tanımlanır, içerik tipi parametre olarak verilir.

interface ProductPage {
  items: Product[];
  total: number;
}
interface OrderPage {
  items: Order[];
  total: number;
}

interface Paginated<T> {
  items: T[];
  total: number;
}

type ProductPage = Paginated<Product>;
type OrderPage = Paginated<Order>;

Değerlendirme

Beş soru

Her cevaptan sonra doğru cevabın gerekçesi gösterilir.

Hazır olduğunuzda başlayabilirsiniz.

02

Mimari hattı · Durak 02 · ~20 dk

Business Domain & Modüller

Business domain, yazılımın hizmet ettiği iş alanıdır. Bu durakta domain, subdomain ve modül kavramları tanımlanır; ardından kodun bu kavramlara göre nasıl bölündüğü beş örnekle pekiştirilir.

Tanım

Business domain, subdomain ve modül nedir?

business domainiş alanı

Yazılımın çözdüğü problemin ait olduğu iş alanıdır; o alana ait kavramları, kuralları ve süreçleri kapsar.

subdomainalt alan: Domain içinde kendi kavramları ve kuralları olan, görece bağımsız bölümdür. Her subdomain tek bir iş sorusunu yanıtlar. Örnek: katalog, sipariş, ödeme.
modulemodül: NestJS'te bir subdomain'e ait controller, service, entity ve DTO'ları tek bir sınır içinde toplayan yapıdır (@Module).

Modüler yapı, kodun dosya türüne göre değil, ait olduğu iş alanına göre bölünmesidir. Her modül tek bir subdomain'den sorumludur ve diğer modüllere yalnızca açıkça dışa aktardığı (exports) servisler üzerinden erişim verir. Bu ayrım yapılmazsa ilgili kod projeye dağılır, modüller birbirinin verisine doğrudan erişir ve bir değişikliğin etkisi öngörülemez hale gelir.

Seviyeler arasında geçiş yapılabilir; Sipariş kutusu doğrudan seçilebilir.

Domain: e-ticaret. İş alanı, her biri tek bir iş sorusunu yanıtlayan altı subdomain'e ayrılır.

Ne sağlar

Bulunabilirlik. Bir iş kuralının hangi dosyada olduğu, ait olduğu iş alanından çıkarılır.
Sınırlı değişiklik. Bir iş alanındaki değişiklik çoğunlukla tek bir modülü etkiler.
Paralel çalışma. Ekipler farklı modüllerde birbirini engellemeden çalışabilir.
Kontrollü erişim. Modüller arası erişim yalnızca dışa aktarılan servisler üzerinden yapılır.

Ayrım yapılmazsa

İlgili kod controllers/, services/ gibi klasörlere dağılır; tek bir değişiklik birçok klasöre dokunur.
Modüller birbirinin verisine doğrudan erişir; bir kuralın nerede uygulandığı izlenemez.
Modüller arasında döngüsel bağımlılıklar oluşur.
Sahibi belirsiz kod common/ veya utils/ altında birikir.

Sınırları

Domain sınırlarının tek bir doğru cevabı yoktur; iş bilgisi ve ekip içi karar gerektirir.
Çok küçük modüllere bölmek gereksiz karmaşıklık ve modüller arası trafik üretir.
Bazı işlemler birden fazla subdomain'i kapsar; sorumlu modülün açıkça belirlenmesi gerekir.
İş geliştikçe sınırlar değişebilir; modül yapısı zamanla yeniden düzenlenir.

Aşağıdaki beş örnek bu tanımı sırasıyla pekiştirir: kavramların gruplanması, türe göre ve domain'e göre bölme, bir kuralın ait olduğu modül, modül sınırı ve bağımlılık yönü.

Örnek 1 · Kavramları gruplamak

Subdomain'ler kavramların gruplanmasıyla bulunur.

Bu örnek, bir domain'in subdomain'lere hangi ölçütle ayrıldığını gösterir. E-ticaret domain'inde geçen kavramlar listelenir; birlikte değişen ve aynı süreçte kullanılan kavramlar aynı gruba alınır. Her grup bir subdomain'dir ve NestJS'te bir modüle, dolayısıyla bir klasöre karşılık gelir.

E-ticaret domain'inde geçen 13 kavram henüz gruplanmadı.

Örnek 2 · Türe göre, domain'e göre

Bölme ölçütü, bir değişikliğin kaç klasöre dağıldığını belirler.

Bu örnek, kodun dosya türüne göre bölünmesi ile domain'e göre bölünmesi arasındaki farkı tek bir değişiklik talebi üzerinden gösterir. Talep: siparişe kargo takip numarası (tracking_number) eklenecek. Bu talep controller, service, entity ve response DTO dosyalarını etkiler.

Etkilenen dosyalar ve klasörler iki yapıda karşılaştırılır.

Türe göre bölünmüş0 klasör

src/
controllers/
products.controller.ts
orders.controller.ts+ endpoint
users.controller.ts
services/
products.service.ts
orders.service.ts+ kural
users.service.ts
entities/
product.entity.ts
order.entity.ts+ kolon
user.entity.ts
dto/
create-product.dto.ts
order.response.dto.ts+ alan
create-user.dto.ts

Domain'e göre bölünmüş0 klasör

src/
products/
products.controller.ts
products.service.ts
entities/product.entity.ts
orders/
orders.controller.ts+ endpoint
orders.service.ts+ kural
entities/order.entity.ts+ kolon
dto/order.response.dto.ts+ alan
users/
users.controller.ts
users.service.ts
entities/user.entity.ts

Talep henüz uygulanmadı.

Örnek 3 · Kural nereye ait?

Bir kural, verisinin sahibi olan modüle aittir.

Bu örnek, bir iş kuralının hangi modülde yer alacağının nasıl belirlendiğini gösterir. Ölçüt: kural, değiştirdiği veya doğruladığı verinin sahibi olan modüle aittir. Kuralı hangi akışın tetiklediği bu kararı değiştirmez. Her kural için ilgili modül seçilir; gerekçe seçimden sonra gösterilir.

Kural 1 / 7

İş kuralı

Ölçüt: Kural, değiştirdiği veya doğruladığı verinin sahibine aittir.

Örnek 4 · Modül sınırı

Bir modülün servisi, varsayılan olarak modüle özeldir.

Bu örnek, bir modülün başka bir modüldeki servisi hangi koşulda kullanabildiğini gösterir. OrdersService, sipariş tutarını hesaplamak için ProductsService'e ihtiyaç duyar. Bunun için iki koşul gerekir: ProductsModule servisi exports ile dışa aktarmalı, OrdersModule de ProductsModule'ü imports ile içe aktarmalıdır. Konsoldaki hata mesajları NestJS 11 ile alınmıştır.

orders.service.ts

@Injectable()export class OrdersService {  constructor(    private readonly productsService: ProductsService,  ) {}}

products.module.ts

@Module({  imports: [TypeOrmModule.forFeature([Product])],  controllers: [ProductsController],  providers: [ProductsService],  exports: [ProductsService],})export class ProductsModule {}

orders.module.ts

@Module({  imports: [    TypeOrmModule.forFeature([Order, OrderItem]),    ProductsModule,  ],  controllers: [OrdersController],  providers: [OrdersService],})export class OrdersModule {}

Modüller ve sınırları

Örnek 5 · Bağımlılık yönü

Modüller arası bağımlılıklar tek yönlü olmalıdır.

Bu örnek, modüller arasındaki bağımlılıkların neden tek yönlü olması gerektiğini ve döngünün nasıl giderildiğini gösterir. Grafikteki her ok, bir modülün diğerini içe aktardığını (imports) belirtir. common/ klasörü tüm modüller tarafından kullanılabilir; ancak kendisi hiçbir domain modülünü kullanmaz.

Bağımlılıklar tek yönlüdür: üstteki modüller alttakileri kullanır, alttakiler üsttekileri kullanmaz. Her modül ayrı ayrı anlaşılabilir ve test edilebilir.

common/ için uygun

Sayfalama DTO'su (page, limit)
Standart yanıt zarfı ve hata biçimi
Tarih ve para birimi biçimlendirme yardımcıları
Ortak entity alanları (created_at, updated_at)

common/ için uygun değil

Sipariş toplamı hesabı: orders/ modülüne aittir
Stok düşme kuralı: products/ modülüne aittir
Ödeme durum geçişleri: payments/ modülüne aittir
Herhangi bir domain modülünü içe aktaran kod

Kurallar

Modül tasarımında uygulanan kurallar

Aşağıdaki altı kural, modül sınırlarının projede tutarlı biçimde korunmasını sağlar. Her kartta önce kurala aykırı kullanım gösterilir; Düzelt butonu kurala uygun hâlini gösterir.

Klasörleri domain'e göre açın

Önce

Klasör adları dosya türünü değil, iş alanını belirtmelidir. Böylece bir değişiklik tek bir klasörde toplanır.

src/
  controllers/
  services/
  entities/
  dto/

src/
  products/
  orders/
  users/
  common/

Başka modülün repository'sini kullanmayın

Önce

Bir veriyi değiştiren kural, verinin sahibi olan modülde kalmalıdır. Diğer modüller bu işlemi sahibinin servisi üzerinden ister.

// orders.service.ts
await this.productRepo.decrement(
  { id: product_id },
  'stock',
  quantity,
);
//! Stok kuralı products dışında uygulandı.

// orders.service.ts
await this.productsService.decreaseStock(
  product_id,
  quantity,
);
// Stok kuralı products modülünde kalır.

Yalnızca gerekeni dışa aktarın

Önce

exports listesi modülün genel arayüzüdür. Arayüz küçük tutulduğunda modülün iç yapısı serbestçe değiştirilebilir.

exports: [
  ProductsService,
  PriceCalculator,
  StockValidator,
  TypeOrmModule,
],

exports: [ProductsService],

// PriceCalculator ve StockValidator
// modüle özel kalır.

İş kuralını common'a taşımayın

Önce

common/ yalnızca domain'den bağımsız yardımcıları içerir. Bir iş kuralı oraya taşındığında sahibi belirsizleşir.

// common/utils/order-total.ts
export function calculateOrderTotal(
  items: OrderItem[],
): number {
  // sipariş kuralı common içinde
}

// orders/orders.service.ts
private calculateTotal(
  items: OrderItem[],
): number {
  // sipariş kuralı orders içinde
}

Modülü iş alanının adıyla adlandırın

Önce

Modül adı sorumlu olduğu iş alanını belirtmelidir. Helper, Manager, Data gibi genel adlar sorumluluğu belirsizleştirir.

HelperModule
ManagerModule
DataModule

ProductsModule
OrdersModule
PaymentsModule

Döngüyü forwardRef ile gizlemeyin

Önce

forwardRef() döngüsel bağımlılık hatasını giderir; ancak döngüyü ortadan kaldırmaz. Öncelikle bağımlılık yönü düzeltilmelidir.

// products.module.ts
imports: [forwardRef(() => OrdersModule)]

// orders.module.ts
imports: [forwardRef(() => ProductsModule)]

// reports.module.ts
@Module({
  imports: [OrdersModule, ProductsModule],
  providers: [ReportsService],
})
export class ReportsModule {}

Değerlendirme

Beş soru

Her cevaptan sonra doğru cevabın gerekçesi gösterilir.

Hazır olduğunuzda başlayabilirsiniz.

03

Mimari hattı · Durak 03 · ~20 dk

Klasör Yapısı

Klasör yapısı, projedeki dosyaların hangi klasörde ve hangi adla yer alacağını belirleyen düzendir. Bu durakta bir modül klasörünün içeriği, dosyaların sorumlulukları ve adlandırma kuralları tanımlanır; ardından beş örnekle pekiştirilir.

Tanım

Klasör yapısı nedir?

klasör yapısıfolder structure

Projedeki dosyaların hangi klasörde ve hangi adla yer alacağını belirleyen düzendir. NestJS'te her modül kendi klasöründe bulunur; klasördeki her dosyanın tek bir sorumluluğu vardır ve bu sorumluluk dosya adının rol ekiyle belirtilir.

module*.module.ts: Modülün tanımıdır. Hangi controller ve service'leri içerdiğini, hangi modülleri içe aktardığını ve neyi dışa aktardığını bildirir.
controller*.controller.ts: HTTP isteğini karşılar: route, parametre ve yanıt. İş kuralı içermez; işi service'e devreder.
service*.service.ts: İş mantığını yürütür: kuralları uygular ve veriye repository üzerinden erişir. HTTP isteğini bilmez.
entityentities/*.entity.ts: Veritabanı tablosunun sınıf karşılığıdır; her alanı bir kolona karşılık gelir. Ayrıntıları Durak 09'da ele alınır.
dtodto/*.dto.ts: İstekle gelen ve yanıtla dönen verinin şeklidir (Data Transfer Object). Doğrulama kuralları Durak 07'de ele alınır.

Sorumlulukların ayrı dosyalarda tutulması, bir dosyanın içeriğinin adından anlaşılmasını ve her katmanın diğerlerinden bağımsız olarak değiştirilip test edilebilmesini sağlar. Ayrım yapılmazsa HTTP, iş kuralı ve veritabanı kodu tek dosyada birikir; aynı kural birden fazla yerde tekrarlanır ve bir değişikliğin hangi dosyayı etkileyeceği öngörülemez.

Klasör yapısı üç kararı sabitler: dosyanın yeri, sorumluluğu ve adı.

Klasör: Her modül src/ altında kendi klasöründe bulunur; kök dizinde yalnızca uygulamanın girişi ve ortak kod yer alır.

Ne sağlar

Öngörülebilirlik. Bir dosyanın içeriği adından ve konumundan anlaşılır; aramak gerekmez.
Bağımsız değişiklik. HTTP, iş kuralı ve veri erişimi ayrı dosyalarda olduğundan biri diğerine dokunmadan değiştirilir.
Test edilebilirlik. Service, HTTP katmanı olmadan doğrudan test edilebilir.
Ortak düzen. Nest CLI aynı yapıyı üretir; ekipteki herkes bir dosyayı aynı yerde arar.

Ayrım yapılmazsa

Doğrulama, iş kuralı ve sorgu controller'da birikir; tek bir metot onlarca satıra ulaşır.
Aynı kural birden fazla endpoint'e kopyalanır; biri güncellenirken diğeri unutulur.
İş kuralı HTTP nesnelerine bağımlı hale gelir; zamanlanmış görev gibi HTTP dışı bir akıştan çağrılamaz.
Satır içi tipler çoğalır; aynı veri şekli farklı dosyalarda farklı biçimde tanımlanır.

Sınırları

Nest dosyaları adından veya konumundan tanımaz. Klasörde bulunan bir modül AppModule'e eklenmezse uygulama hatasız başlar; ancak route'ları oluşmaz ve istekler 404 alır.
Dosya desenine dayanan ayarlar ada bağlıdır. Örneğin entities: ['**/*.entity{.ts,.js}'] deseni yalnızca bu son eki taşıyan dosyaları tarar.
Doğru adlandırılmış bir dosyaya yanlış sorumluluk yüklenebilir; ayrımı yapı değil, kod incelemesi korur.
Küçük bir modülde her alt klasörün açılması gereksizdir; klasör ihtiyaç doğduğunda açılır.

Aşağıdaki beş örnek bu tanımı sırasıyla pekiştirir: products/ klasörünün incelenmesi, katmanlar arasındaki akış, kod satırlarının ait olduğu dosya, adlandırma ve aşırı yüklenmiş bir controller'ın ayrılması.

Örnek 1 · products/ klasörünün incelenmesi

Nest CLI, bir modülün iskeletini tek komutla üretir.

Bu örnek, nest g resource products komutunun ürettiği klasörü inceler. Komut iki soru sorar, dosyaları oluşturur ve yeni modülü app.module.ts dosyasına ekler. Terminal çıktısı ve dosya içerikleri Nest CLI 11 ile alınmıştır. Üretim tamamlandığında her dosya seçilerek sorumluluğu incelenebilir.

Dosyalar, üretim tamamlandığında seçilebilir.

~/shop-api $

shop-api0 dosya üretildi

src/
güncellendi
products/
dto/
entities/

Komut çalıştırıldığında üretilen dosyalar burada incelenebilir.

Örnek 2 · Katmanlar

Controller isteği karşılar, service karar verir, repository veriye erişir.

Bu örnek, GET /products/:id isteğinin üç katmandan nasıl geçtiğini gösterir. Her katman yalnızca kendi sorumluluğundaki bilgiyi kullanır. Repository, TypeORM'un sağladığı Repository<Product> nesnesidir; service'e enjekte edilir ve ayrı bir dosya gerektirmez. Ayrıntıları Durak 09'da ele alınır. Hata yanıtları NestJS 11 ile alınmıştır.

products.controller.ts

@Get(':id')
findOne(@Param('id', ParseIntPipe) id: number) {
  return this.productsService.findOne(id);
}

products.service.ts

constructor(
  @InjectRepository(Product)
  private readonly productRepo: Repository<Product>,
) {}

async findOne(id: number): Promise<ProductResponseDto> {
  const product = await this.productRepo.findOneBy({ id });
  if (!product) throw new NotFoundException('Ürün bulunamadı');
  return {
    id: product.id,
    name: product.name,
    unit_price: product.unit_price,
  };
}

Katmanlar

Örnek 3 · Kod satırı nereye ait?

Her kod satırının ait olduğu tek bir dosya vardır.

Bu örnek, sorumluluk tanımlarının bir kod satırına nasıl uygulandığını gösterir. Ölçüt, satırın hangi bilgiyi kullandığıdır: HTTP bilgisi controller'a, iş kuralı ve veri erişimi service'e, verinin şekli DTO'ya, tablo tanımı entity'ye, kayıt bilgisi modül dosyasına aittir. Her satır için ilgili dosya seçilir; gerekçe seçimden sonra gösterilir.

Satır 1 / 8

Kod satırı

Ölçüt: Satırın kullandığı bilgi, ait olduğu dosyayı belirler.

Örnek 4 · Adlandırma

Dosya adı, içeriği ve rolü birlikte belirtir.

Bu örnek, bir dosyanın ve içindeki sınıfın adının nasıl oluşturulduğunu gösterir. Kurallar Nest CLI'ın ürettiği adlarla aynıdır: modül klasörü, module, controller ve service adları çoğuldur; entity ve DTO adları tekil varlığı belirtir. Dosya adı kebab-case, sınıf adı PascalCase yazılır. Varlık ve rol seçilerek sonuç incelenebilir.

Varlık

Rol

Dosya yolu

Sınıf adı

İçe aktarma

Çoğul modül klasörü · module · controller · service Tekil entity · dto kebab-case dosya adı PascalCase sınıf adı

Örnek 5 · Aşırı yüklenmiş controller

Controller'da biriken kod, ait olduğu dosyalara taşınır.

Bu örnek, en sık yapılan yapı hatasını gösterir: doğrulama, iş kuralı, veritabanı erişimi ve yanıt dönüşümünün tek bir controller metodunda toplanması. Kod çalışır; ancak kural başka bir akıştan çağrılamaz, HTTP olmadan test edilemez ve aynı kontroller diğer endpoint'lerde tekrarlanır. İkinci adımda her satır grubu ait olduğu dosyaya taşınır.

products.controller.ts23 satır

@Controller('products')export class ProductsController {  constructor(    @InjectRepository(Product)    private readonly productRepo: Repository<Product>,  ) {}  constructor(private readonly productsService: ProductsService) {}   @Post()  async create(@Body() body: { name: string; unit_price: number }) {    if (!body.name || body.name.length > 120)      throw new BadRequestException('Geçersiz ürün adı');    if (body.unit_price <= 0)      throw new BadRequestException('Fiyat pozitif olmalıdır');    const exists = await this.productRepo.findOneBy({ name: body.name });    if (exists) throw new ConflictException('Bu adla bir ürün var');    const product = await this.productRepo.save({ ...body });    return {      id: product.id,      name: product.name,      unit_price: product.unit_price,    };  create(@Body() dto: CreateProductDto): Promise<ProductResponseDto> {    return this.productsService.create(dto);  }}

dto/create-product.dto.tsyeni

export class CreateProductDto {  @IsString()  @MaxLength(120)  name: string;   @IsPositive()  unit_price: number;}

products.service.ts

@Injectable()export class ProductsService {  constructor(    @InjectRepository(Product)    private readonly productRepo: Repository<Product>,  ) {}   async create(dto: CreateProductDto): Promise<ProductResponseDto> {    const exists = await this.productRepo.findOneBy({ name: dto.name });    if (exists) throw new ConflictException('Bu adla bir ürün var');    const product = await this.productRepo.save({ ...dto });    return { id: product.id, name: product.name, unit_price: product.unit_price };  }}

dto/product.response.dto.tsyeni

export class ProductResponseDto {  id: number;  name: string;  unit_price: number;}

Tek dosya: Doğrulama, iş kuralı, veri erişimi ve yanıt dönüşümü aynı metotta bulunuyor.

Kurallar

Klasör yapısında uygulanan kurallar

Aşağıdaki altı kural, dosya sorumluluklarının projede tutarlı biçimde korunmasını sağlar. Her kartta önce kurala aykırı kullanım gösterilir; Düzelt butonu kurala uygun hâlini gösterir.

Controller'da iş kuralı yazmayın

Önce

Controller isteği karşılar ve işi service'e devreder. Kural service'te olduğunda başka bir akıştan da çağrılabilir.

@Post()
async create(@Body() dto: CreateProductDto) {
  const exists = await this.productRepo
    .findOneBy({ name: dto.name });
  //! İş kuralı controller'da.
  if (exists) throw new ConflictException();
  return this.productRepo.save(dto);
}

@Post()
create(@Body() dto: CreateProductDto) {
  return this.productsService.create(dto);
}

// Kural ve veri erişimi
// products.service.ts içindedir.

Satır içi tip yerine DTO dosyası açın

Önce

İstek ve yanıt şekilleri dto/ altında ayrı dosyalarda tanımlanır. Böylece aynı şekil tek bir yerde tutulur ve doğrulanabilir.

@Post()
create(
  @Body() body: {
    name: string;
    unit_price: number;
  },
) {}
//! Şekil controller'a gömüldü.

// dto/create-product.dto.ts
export class CreateProductDto {
  name: string;
  unit_price: number;
}

@Post()
create(@Body() dto: CreateProductDto) {}

Dosya adını rol ekiyle bitirin

Önce

Dosya adı, içeriğin ne olduğunu ve rolünü belirtir. Rol eki olmayan adlar, dosyanın açılmadan anlaşılmasını engeller.

products/
  product.ts
  productHelper.ts
  ProductDTO.ts
  productsCtrl.ts

products/
  entities/product.entity.ts
  products.service.ts
  dto/create-product.dto.ts
  products.controller.ts

Service'e HTTP nesnesi vermeyin

Önce

Service, isteğin kendisini değil, istekten çıkarılmış veriyi alır. Böylece HTTP dışındaki akışlardan da çağrılabilir ve kolayca test edilir.

@Get()
findAll(@Req() req: FastifyRequest) {
  return this.productsService.findAll(req);
}
//! Service, HTTP isteğine bağımlı.

@Get()
findAll(@Query() query: ProductQueryDto) {
  return this.productsService.findAll(query);
}

Klasörü ihtiyaç doğduğunda açın

Önce

Alt klasör, aynı türden birden fazla dosya oluştuğunda açılır. Önceden açılan boş klasörler yapıyı okunmaz hale getirir.

products/
  constants/
  helpers/
  interfaces/
  types/
  utils/
  products.service.ts

products/
  dto/
  entities/
  products.controller.ts
  products.module.ts
  products.service.ts

Yeni modülü AppModule'e ekleyin

Önce

Nest, modülleri klasörden değil, modül ağacından tanır. Elle oluşturulan bir modül AppModule'e eklenmezse route'ları oluşmaz.

@Module({
  imports: [UsersModule],
})
export class AppModule {}
//! GET /products → 404 Cannot GET /products

@Module({
  imports: [UsersModule, ProductsModule],
})
export class AppModule {}
// Nest CLI bu satırı kendisi ekler.

Değerlendirme

Beş soru

Her cevaptan sonra doğru cevabın gerekçesi gösterilir.

Hazır olduğunuzda başlayabilirsiniz.

04

Mimari hattı · Durak 04 · ~25 dk

Dependency Injection

Dependency injection, bir sınıfın ihtiyaç duyduğu nesneleri kendisinin oluşturmayıp dışarıdan almasıdır. Bu durakta NestJS'in bu nesneleri nasıl oluşturduğu, sakladığı ve sınıflara nasıl verdiği tanımlanır; ardından yedi örnekle pekiştirilir.

Tanım

Dependency injection nedir?

dependency injectionbağımlılık enjeksiyonu

Bir sınıfın ihtiyaç duyduğu nesneleri (bağımlılıklarını) kendisinin oluşturmayıp dışarıdan almasıdır. NestJS'te sınıf, bağımlılıklarını constructor parametreleri olarak bildirir; IoC container bu nesneleri oluşturur, saklar ve sınıfa verir.

bağımlılıkdependency: Bir sınıfın işini yapabilmek için kullandığı başka bir nesnedir. Örnek: OrdersService, ürünün stoğunu öğrenmek için ProductsService'i kullanır; ProductsService, OrdersService'in bağımlılığıdır.
providerproviders: [...]: Container'ın oluşturup sınıflara verebildiği nesnedir. Genellikle @Injectable() ile işaretlenmiş bir service'tir ve modülün providers listesine kaydedilir.
tokeninjection token: Container'ın bir provider'ı tanıdığı anahtardır. Sınıf olarak kaydedilen provider'da token sınıfın kendisidir; constructor parametresinin tipi, istenen token'ı belirtir.
IoC containerinversion of control: Provider'ları oluşturan, saklayan ve dağıtan Nest bileşenidir. Nesneleri oluşturma kontrolü sınıftan alınıp container'a verildiği için bu yaklaşıma kontrolün tersine çevrilmesi denir.
singletonvarsayılan kapsam: Bir provider'dan uygulama boyunca tek bir örnek oluşturulmasıdır. Aynı token'ı isteyen tüm sınıflar aynı örneği alır.

Sınıf, bağımlılığının nasıl oluşturulduğunu bilmez; yalnızca neye ihtiyaç duyduğunu bildirir. Böylece her nesne tek bir yerde oluşturulur, sınıflar arasında paylaşılır ve testte sahtesiyle değiştirilebilir. Dependency injection kullanılmazsa her sınıf bağımlılıklarını new ile kendisi oluşturur: bağımlılığın bağımlılıklarını da bilmek zorunda kalır, aynı nesnenin birden fazla kopyası oluşur ve sınıf gerçek veritabanı olmadan test edilemez.

Container üç işi sırayla yapar: bildirilen token'ı bulur, örneği oluşturur ve sınıfa verir.

Bildirim: OrdersController, ihtiyaç duyduğu nesneyi constructor parametresinin tipiyle bildirir. Nesneyi kendisi oluşturmaz.

Ne sağlar

Tek noktada oluşturma. Bir nesnenin nasıl oluşturulduğu yalnızca container'da tanımlıdır; constructor değiştiğinde onu kullanan sınıflar etkilenmez.
Paylaşım. Her provider'dan bir örnek oluşur ve tüm sınıflar aynı örneği kullanır; aynı kaynak tekrar tekrar oluşturulmaz.
Test edilebilirlik. Testte bağımlılığın yerine sahte bir nesne verilir; sınıf veritabanı olmadan test edilir.
Açık bağımlılıklar. Bir sınıfın neye ihtiyaç duyduğu constructor'ından okunur.

Kullanılmazsa

Her sınıf bağımlılığını new ile oluşturur ve bağımlılığın bağımlılıklarını da bilmek zorunda kalır.
Bir constructor değiştiğinde, o sınıfı oluşturan tüm dosyalar güncellenmelidir.
Aynı nesnenin birden fazla kopyası oluşur; her kopya kendi kaynağını açar.
Sınıf test edilirken gerçek bağımlılıkları da çalışır; veritabanı olmadan test yazılamaz.

Sınırları

Container yalnızca kayıtlı provider'ları tanır. Kayıtlı olmayan bir token istenirse uygulama başlatılamaz.
@Injectable() unutulursa uygulama hatasız başlar; ancak bağımlılık undefined olur ve hata ilk çağrıda ortaya çıkar.
Varsayılan kapsamda her provider'dan tek örnek oluşur; örneğin alanında saklanan istek verisi, eş zamanlı istekler arasında karışabilir.
İki sınıfın birbirini istediği döngüsel bağımlılık kendiliğinden çözülmez; uygulama başlatılamaz. Döngünün nedeni ve giderilmesi Örnek 6 ve 7'de ele alınır.

Aşağıdaki yedi örnek bu tanımı sırasıyla pekiştirir: new ile oluşturma ve constructor üzerinden alma, container'ın bağımlılık grafiğini çözmesi, @Injectable() dekoratörünün görevi, testte mock kullanımı, singleton kapsamı, döngüsel bağımlılığın nedeni ve döngünün giderilmesi.

Örnek 1 · new ve constructor

Nesneyi new ile oluşturan sınıf, onun nasıl oluşturulduğunu da bilmek zorundadır.

Bu örnekte üç sınıf ProductsService'i kullanır. Soldaki yaklaşımda her sınıf nesneyi new ile kendisi oluşturur; sağdakinde constructor üzerinden alır. İkinci adımda ProductsService'in constructor'ına yeni bir bağımlılık (StockService) eklenir ve iki yaklaşımda değişmesi gereken dosyalar karşılaştırılır. Hata mesajı TypeScript 5.9 ile alınmıştır.

products.service.tsdeğişmedi

new ile0 dosya değişmeli3 ProductsService örneği

constructor ile0 dosya değişmeli1 ProductsService örneği

Başlangıç: İki yaklaşım da çalışır. Soldakinde üç ayrı ProductsService ve üç ayrı PricingService örneği oluşur; sağdakinde container her birinden bir örnek oluşturur.

Örnek 2 · IoC container

Container, bağımlılık grafiğini bağımlılıklardan başlayarak çözer.

Bu örnek, uygulama başlatılırken container'ın sınıfları hangi sırayla oluşturduğunu gösterir. Her ok, bir sınıfın constructor'ında diğerini istediğini belirtir. Container önce bağımlılığı olmayan sınıfı, ardından onu kullananları oluşturur. İki sınıfın istediği ProductsService yalnızca bir kez oluşturulur. İkinci adımda bir provider kaydı silinir ve hata mesajının nasıl okunacağı gösterilir. Oluşturma sırası, constructor'lara eklenen console.log satırlarıyla NestJS 11 üzerinde alınmıştır; hata mesajı da NestJS 11 çıktısıdır.

Bağımlılık grafiği

products.module.ts

Örnek 3 · @Injectable

Container, constructor tiplerini derleyicinin bıraktığı meta veriden okur.

Durak 01'de tiplerin derleme sırasında kaldırıldığı görülmüştü. Bu durumda container'ın constructor parametresinin tipini nasıl bildiği sorusu ortaya çıkar. Yanıt dekoratördür: emitDecoratorMetadata ayarı açıkken TypeScript, dekoratör taşıyan sınıfların constructor tiplerini derlenen koda yazar. Bu örnek aynı sınıfın @Injectable() ile ve onsuz derlenmiş hâlini karşılaştırır. Derlenmiş kod TypeScript 5.9, çalışma anı çıktısı NestJS 11 ile alınmıştır. Modüller arası erişim için gereken imports ve exports Durak 02, Örnek 4'te ele alınmıştır.

orders.service.tssrc · TypeScript

orders.service.jsdist · derlenmiş

Container'ın okuduğu

Örnek 4 · Testte mock

Test, bağımlılığın yerine kontrol edilen bir nesne verir.

Bu örnek OrdersService'in birim testini inceler. OrdersService ürünün stoğunu ProductsService'ten alır; ProductsService ise veritabanına erişir. Testte gerçek ProductsService kullanılırsa veritabanı bağlantısı da gerekir. Bunun yerine aynı token'a sahte bir nesne (mock) kaydedilir. OrdersService constructor'ından ne aldığını bilmez ve değiştirilmeden test edilir. Test çıktıları Jest 29 ve NestJS 11 ile alınmıştır.

orders.service.ts

orders.service.spec.ts

Test modülü

Örnek 5 · Singleton kapsamı

Aynı provider'ı kullanan tüm sınıflar ve tüm istekler aynı örneği paylaşır.

Nest, bir provider'dan varsayılan olarak tek bir örnek oluşturur ve uygulama kapanana kadar saklar. Bu örnek önce paylaşımı, ardından paylaşımın yol açabileceği hatayı gösterir: örneğin alanında saklanan istek verisi, aynı anda gelen başka bir isteğin verisiyle karışabilir. Eş zamanlı iki isteğin sonucu, tek bir CartService örneği üzerinde Node.js ile çalıştırılan bir simülasyondan alınmıştır.

cart.module.ts

Örnek 6 · Döngüsel bağımlılık

Birbirini isteyen iki provider ile uygulama başlatılamaz.

Döngüsel bağımlılık (circular dependency), iki provider'ın constructor'larında birbirini istemesidir. Container önce bağımlılığı olmayan sınıfı oluşturur (Örnek 2); döngüdeki sınıfların ise her biri, diğeri oluşturulmadan oluşturulamaz. Bu örnekte ProductsService, ürün sayfasındaki satış adedini almak için OrdersService'i ister; OrdersService ise sipariş oluştururken zaten ProductsService'i kullanmaktadır. İki service ayrı modüllerde olduğu için döngü modüller arasında da oluşur. Hata mesajları NestJS 11 ile alınmıştır.

Bağımlılık grafiği

değişen dosyalar

Örnek 7 · Döngünün giderilmesi

forwardRef hatayı giderir; döngü ise bağımlılıkların yönü düzeltilerek kaldırılır.

Bu örnek, Örnek 6'daki döngü için üç çözümü karşılaştırır. İlki Nest'in önerdiği forwardRef()'tir: uygulama başlar, ancak iki service birbirini istemeye devam eder. Diğer ikisi döngüyü kaldırır: satış adedini birleştiren iş üçüncü bir service'e taşınır ya da bağımlılığın yönü tersine çevrilir. Üç çözümün çıktıları, constructor'lara eklenen console.log satırlarıyla NestJS 11 üzerinde alınmıştır.

Bağımlılık grafiği

0 forwardRefdöngü: var

değişen dosyalar

forwardRef

Hata giderilir; döngü kalır. İki modül ve iki service birlikte değiştirilir ve birlikte test edilir.
Constructor çalışırken karşı tarafın alanları henüz atanmamıştır (OrdersService {}); constructor'dan çağrılan metotlar bu alanlara erişemez.
Yalnızca döngünün kısa sürede kaldırılamadığı durumlarda geçici bir çözümdür.

Üçüncü service

İki domain'in verisini birleştiren iş için uygundur: rapor, ürün sayfası özeti.
ProductsService ve OrdersService birbirini bilmez; her biri ayrı test edilir.
Birleştirilmiş veriyi döndüren endpoint de üstteki modülde (reports) yer alır.

Yönün tersine çevrilmesi

Bir tarafın, diğer tarafta gerçekleşen bir olaydan haberdar olması gerektiğinde uygundur: sipariş oluşturulunca satış adedi artar.
ProductsService, OrdersService'i hiç bilmez; satış adedi ürün kaydında tutulur.
Kopyalanan değer tutarlı tutulmalıdır: sipariş iptal edildiğinde satış adedi azaltılır.

Kurallar

Dependency injection kullanılırken uygulanan kurallar

Aşağıdaki yedi kural, bağımlılıkların container üzerinden doğru biçimde alınmasını ve paylaşılmasını sağlar. Her kartta önce kurala aykırı kullanım gösterilir; Düzelt butonu kurala uygun hâlini gösterir.

Bağımlılığı new ile oluşturmayın

Önce

Bağımlılık constructor üzerinden alındığında container onu bir kez oluşturur ve paylaştırır. new ile oluşturulan nesne, kendi bağımlılıklarının da bilinmesini gerektirir.

@Injectable()
export class OrdersService {
  //! Her sınıf kendi kopyasını oluşturur.
  private readonly products =
    new ProductsService(
      new PricingService(),
    );
}

@Injectable()
export class OrdersService {
  constructor(
    private readonly products:
      ProductsService,
  ) {}
}

Constructor parametresini private readonly tanımlayın

Önce

private readonly, parametreyi aynı satırda sınıf alanı yapar; alanın dışarıdan okunmasını ve sonradan başka bir nesneyle değiştirilmesini engeller.

@Injectable()
export class OrdersService {
  products: ProductsService;

  constructor(
    products: ProductsService,
  ) {
    this.products = products;
  }
}
//! Alan public ve yeniden atanabilir.

@Injectable()
export class OrdersService {
  constructor(
    private readonly products:
      ProductsService,
  ) {}
}

Provider sınıfını @Injectable() ile işaretleyin

Önce

Dekoratör olmadan TypeScript constructor tiplerini derlenen koda yazmaz. Uygulama hatasız başlar; ancak bağımlılık undefined olur ve ilk çağrıda hata verir.

export class OrdersService {
  constructor(
    private readonly products:
      ProductsService,
  ) {}
}
//! TypeError: Cannot read properties
//! of undefined (reading 'findOne')

@Injectable()
export class OrdersService {
  constructor(
    private readonly products:
      ProductsService,
  ) {}
}

Başka modülün service'ini providers listesine eklemeyin

Önce

Service'in sahibi olan modül onu dışa aktarır; kullanan modül bu modülü içe aktarır. providers listesine eklenen service, bağımlılıklarıyla birlikte bu modülde yeniden oluşturulmaya çalışılır.

@Module({
  providers: [
    OrdersService,
    ProductsService,
  ],
})
export class OrdersModule {}
//! ...argument PricingService at
//! index [0] is available in the
//! OrdersModule module.

@Module({
  imports: [ProductsModule],
  providers: [OrdersService],
})
export class OrdersModule {}

// ProductsModule:
// exports: [ProductsService]

Singleton service'te istek verisini alanda tutmayın

Önce

Service'in tek örneği tüm isteklerce paylaşılır. İsteğe ait veri alanda değil, parametreyle taşınır.

private userId: number;

async getCart(userId: number) {
  this.userId = userId;
  const items = await this.loadItems();
  //! Başka bir istek alanı
  //! bu sırada değiştirebilir.
  const coupon = await this.loadCoupon();
  return { items, coupon };
}

async getCart(userId: number) {
  const items =
    await this.loadItems(userId);
  const coupon =
    await this.loadCoupon(userId);
  return { items, coupon };
}

Constructor'da iş yapmayın

Önce

Constructor yalnızca bağımlılıkları almak içindir ve asenkron olamaz. Başlangıçta yapılacak iş onModuleInit metodunda yapılır; Nest bu metodu bağımlılıklar hazır olduğunda çağırır ve tamamlanmasını bekler.

constructor(
  private readonly cache: CacheService,
) {
  //! Promise beklenmez,
  //! hata yakalanmaz.
  this.cache.warmUp();
}

constructor(
  private readonly cache: CacheService,
) {}

async onModuleInit() {
  await this.cache.warmUp();
}

Provider döngüsünü forwardRef ile gizlemeyin

Önce

forwardRef(), birbirini isteyen iki provider'ın oluşturulmasını sağlar; döngüyü kaldırmaz. İki service'i birleştiren iş üçüncü bir service'e taşınır ya da bağımlılığın yönü tersine çevrilir.

// products.service.ts
constructor(
  @Inject(
    forwardRef(() => OrdersService),
  )
  private readonly orders:
    OrdersService,
) {}
//! Döngü kalır; iki service
//! birlikte değişir.

// reports.service.ts
constructor(
  private readonly products:
    ProductsService,
  private readonly orders:
    OrdersService,
) {}

Değerlendirme

Altı soru

Her cevaptan sonra doğru cevabın gerekçesi gösterilir.

Hazır olduğunuzda başlayabilirsiniz.

05

Akış hattı · Durak 05 · ~20 dk

Request Lifecycle

Request lifecycle, bir HTTP isteğinin sunucuya ulaşmasından yanıtın istemciye dönmesine kadar geçtiği katmanların sırasıdır. Bu durakta katmanların sırası, her katmanın isteğin hangi hâlini gördüğü ve bir katman isteği reddettiğinde zincirin nasıl durduğu tanımlanır; ardından beş örnekle pekiştirilir.

Tanım

Request lifecycle nedir?

request lifecycleisteğin yaşam döngüsü

Bir HTTP isteğinin NestJS'te geçtiği katmanların sırasıdır. Sıra sabittir: middleware → guard → interceptor → pipe → handler. Handler'ın döndürdüğü değer aynı interceptor'dan geri geçerek yanıta dönüşür. Herhangi bir katmanda exception fırlatılırsa sonraki katmanlar çalışmaz; exception filter hatayı HTTP yanıtına çevirir.

middlewareNestMiddleware: Nest'in diğer katmanlarından önce çalışan fonksiyondur. Ham istek ve yanıt nesnelerini alır; hangi controller metodunun çalışacağını bilmez. İşini bitirince next()'i çağırarak isteği sonraki katmana geçirir.
guardCanActivate: İsteğin handler'a ulaşıp ulaşmayacağına karar veren sınıftır. canActivate() true döndürürse istek devam eder; false döndürürse 403 yanıtı döner.
interceptorNestInterceptor: Handler'ın öncesinde ve sonrasında çalışan sınıftır. Handler'ın döndürdüğü değeri, yanıta dönüşmeden önce görür ve değiştirebilir.
pipePipeTransform: Handler'a verilecek argümanı dönüştüren ve doğrulayan sınıftır. Örnek: ParseIntPipe, '42' metnini 42 sayısına çevirir; çeviremezse 400 yanıtı döner.
handlercontroller metodu: İsteği karşılayan controller metodudur. İşi service'e devreder ve sonucu döndürür. Örnek: OrdersController.findOne().
exception filterExceptionFilter: Fırlatılan exception'ı yakalayıp HTTP yanıtına çeviren sınıftır. Nest'in varsayılan filter'ı, statusCode ve message alanlarını içeren bir JSON yanıtı üretir.

Her katmanın görevi ve gördüğü veri, sıradaki yerine bağlıdır. Örneğin guard pipe'tan önce çalıştığı için route parametresini henüz dönüştürülmemiş hâliyle, metin olarak görür. Sıra bilinmezse kontroller yanlış katmana konur: dönüştürülmüş veri beklenen yerde metin gelir, yetkisiz bir istek gereksiz yere pipe'lardan geçer ya da aynı kontrol her handler'da tekrarlanır.

Paket, GET /api/v1/orders/42 isteğini taşır.

Gidiş: İstek, istemciden çıkarak katmanlardan sırayla geçer.

Ne sağlar

Öngörülebilir sıra. Her istek aynı sırayla işlenir; bir hatanın hangi katmanda oluştuğu loglardan okunur.
Erken reddetme. Yetkisiz istek guard'da durur; pipe, handler ve service hiç çalışmaz.
Görev ayrımı. Handler yalnızca iş akışını içerir; erişim kararı, dönüşüm ve yanıt biçimi kendi katmanlarındadır.
Tek biçimli hata yanıtı. Exception hangi katmanda fırlatılırsa fırlatılsın, exception filter aynı biçimde yanıt üretir.

Sırası bilinmezse

Guard'da sayı beklenen parametre metin olarak gelir; '42' === 42 gibi karşılaştırmalar sessizce false döner.
Handler'a konan yetki kontrolü pipe'lardan sonra çalışır; token'sız bir istek 401 yerine 400 alabilir.
Interceptor'ın sonra kısmına konan loglama hata durumunda çalışmaz; hatalı istekler loglarda görünmez.
@Res() ile gönderilen yanıt interceptor'ların dönüşümünden geçmez; yanıt biçimleri endpoint'ler arasında farklılaşır.

Sınırları

Middleware hangi handler'ın çalışacağını bilmez; route'a bağlı bir karar (örneğin rol kontrolü) middleware'de verilemez.
Guard ve interceptor pipe'tan önce çalışır; parametreler bu katmanlarda doğrulanmamış ve dönüştürülmemiştir.
Exception filter yalnızca fırlatılan exception'ları yakalar; handler'ın return ettiği bir hata nesnesi 200 durum koduyla gönderilir.
Middleware next()'i çağırmaz ve yanıtı da göndermezse zincir durur; istemciye yanıt dönmez.

Aşağıdaki beş örnek bu tanımı sırasıyla pekiştirir: bir isteğin katmanlardaki yolculuğu ve her katmanın gördüğü veri, zincirin durduğu noktalar, global, controller ve route kapsamlarının sırası, handler'ın döndürdüğü değerin dönüş yolu ve katmanların sıraya dizildiği bir uygulama.

Örnek 1 · Bir isteğin yolculuğu

Her katman isteği, sıradaki yerine göre farklı bir hâlde görür.

Bu örnekte GET /api/v1/orders/42 isteği Authorization: Bearer abc başlığıyla gönderilir. Oynatıcı isteği katman katman ilerletir; her adımda katmanın konsola yazdığı satır ve o katmanda erişilebilen değerler gösterilir. Değerler, her katmana eklenen console.log satırlarıyla NestJS 11 ve Fastify üzerinde alınmıştır.

Middlewarelogger.middleware.ts
Guardauth.guard.ts
Interceptor · öncelogging.interceptor.ts
PipeParseIntPipe
Handlerorders.controller.ts
Serviceorders.service.ts
Interceptor · sonralogging.interceptor.ts
YanıtHTTP

Bu katmanda erişilebilen değerler

İstek henüz gönderilmedi

Oynat butonu isteği gönderir; Sonraki adım butonu isteği bir katman ilerletir.

Örnek 2 · Zincirin durduğu nokta

Bir katman exception fırlattığında sonraki katmanlar çalışmaz.

Bu örnekte Örnek 1'deki endpoint'e dört farklı istek gönderilir. Guard, Authorization başlığı yoksa UnauthorizedException fırlatır; Bearer musteri token'ı için false döndürür (bu kullanıcının kayda erişim yetkisi yoktur). Çalışan katmanlar yeşil, isteği durduran katman kırmızı, hiç çalışmayan katmanlar soluk gösterilir. Loglar ve yanıtlar NestJS 11 ile alınmıştır; guard'ın log satırları kodda gösterilmemiştir.

auth.guard.ts · logging.interceptor.ts

Örnek 3 · Kapsam sırası

Guard ve interceptor dıştan içe çalışır; exception'ı en içteki filter yakalar.

Guard, interceptor ve filter üç kapsamda tanımlanabilir: global (main.ts), controller (sınıfın üstü) ve route (metodun üstü). Bu örnekte her kapsama, yalnızca kapsamın adını loglayan bir guard (LogGuard), interceptor (LogInterceptor) ve filter (LogFilter) kaydedilmiştir. Tablo, aynı istekte hangisinin hangi sırayla çalıştığını gösterir; kesikli hücreler o kapsamda kayıt olmadığını belirtir. Kayıt yöntemlerinin ayrıntıları Durak 06'da ele alınır. Loglar NestJS 11 ile alınmıştır.

main.ts · orders.controller.ts · products.controller.ts

GUARD

Global → controller → route. Biri reddederse sonrakiler çalışmaz.

INTERCEPTOR

Önce kısımları global → controller → route; sonra kısımları ters sırada: route → controller → global.

FILTER

Önce route, sonra controller, en son global kapsamına bakılır. Exception'ı yalnızca bulunan ilk filter yakalar.

Örnek 4 · Dönüş yolu

Handler'ın döndürdüğü değer, yanıta dönüşmeden önce interceptor'dan geçer.

Handler'ın return ettiği değer doğrudan istemciye gönderilmez: önce interceptor'lardan geri geçer, ardından Nest onu JSON'a çevirip yanıt olarak gönderir. Bu örnekteki interceptor, değeri { data } zarfına koyar. İkinci adımda handler yanıtı @Res() ile aldığı nesne üzerinden kendisi gönderir; üçüncü adımda aynı nesne passthrough: true ile yalnızca başlık eklemek için kullanılır. Loglar ve yanıtlar NestJS 11 ve Fastify ile alınmıştır; kodlarda log satırları gösterilmemiştir.

envelope.interceptor.ts · orders.controller.ts

Örnek 5 · Uygulama

Katmanları, isteğin onlara ulaştığı sırayla dizin.

İki turdan oluşur. İlk turda GET /api/v1/orders/42 isteğinin geçtiği katmanlar, ikinci turda farklı kapsamlarda tanımlanmış guard ve interceptor'lar sıraya dizilir. Kartlara isteğin onlara ulaştığı sırayla tıklayın; doğru kart hatta eklenir, yanlış kartta neden henüz sırasının gelmediği açıklanır.

Tur 1 / 2 0 hatalı seçim

Kurallar

İstek akışı düşünülerek uygulanan kurallar

Aşağıdaki altı kural, kontrollerin doğru katmana konmasını ve yanıtın katmanlardan beklenen biçimde geçmesini sağlar. Her kartta önce kurala aykırı kullanım gösterilir; Düzelt butonu kurala uygun hâlini gösterir. Yorum satırlarındaki sonuçlar NestJS 11 ile alınmıştır.

Guard'da dönüştürülmüş veri beklemeyin

Önce

Guard pipe'tan önce çalışır. Route parametresi bu noktada dönüştürülmemiştir; req.params.id değeri '42' metnidir.

// owner.guard.ts · GET /users/:id
canActivate(ctx: ExecutionContext) {
  const req = ctx.switchToHttp()
    .getRequest();
  // req.user.id: 42 (number)
  return req.params.id === req.user.id;
}
//! '42' === 42 → false: kullanıcı
//! kendi kaydına da erişemez.

// owner.guard.ts · GET /users/:id
canActivate(ctx: ExecutionContext) {
  const req = ctx.switchToHttp()
    .getRequest();
  const id = Number(req.params.id);
  return id === req.user.id;
}

Yetki kontrolünü handler'a koymayın

Önce

Handler'daki kontrol pipe'lardan sonra çalışır. Token'sız ve geçersiz id'li bir istek 401 yerine 400 alır; yetkisiz istek gereksiz yere pipe'lardan geçer.

@Get(':id')
findOne(
  @Param('id', ParseIntPipe) id: number,
  @Headers('authorization') auth?: string,
) {
  if (!auth) {
    throw new UnauthorizedException();
  }
  return this.ordersService.findOne(id);
}
//! GET /orders/abc, token yok → 400

@Controller('orders')
@UseGuards(AuthGuard)
export class OrdersController {
  @Get(':id')
  findOne(
    @Param('id', ParseIntPipe) id: number,
  ) {
    return this.ordersService.findOne(id);
  }
}
// GET /orders/abc, token yok → 401

Interceptor'da hataları da izleyin

Önce

tap(fn) yalnızca handler bir değer döndürdüğünde çalışır. Exception fırlatıldığında interceptor'ın sonra kısmı atlanır; tap'e error fonksiyonu da verilir.

// logging.interceptor.ts
return next.handle().pipe(
  tap(() => this.logger.log('başarılı')),
);
//! Exception fırlatıldığında
//! çalışmaz; 400 ve 404 loglanmaz.

// logging.interceptor.ts
return next.handle().pipe(
  tap({
    next: () =>
      this.logger.log('başarılı'),
    error: (e: Error) =>
      this.logger.warn(e.message),
  }),
);

@Res() ile dönüş yolunu kesmeyin

Önce

@Res() kullanıldığında yanıtı handler gönderir; interceptor'ın dönüşümü yanıta yansımaz. Yanıt nesnesine yalnızca başlık eklemek gerekiyorsa passthrough: true kullanılır ve değer return edilir.

@Get(':id')
findOne(
  @Param('id', ParseIntPipe) id: number,
  @Res() res: FastifyReply,
) {
  res.header('x-cache', 'miss');
  res.send(
    this.ordersService.findOne(id),
  );
}
//! Yanıt { data } zarfına konmaz.

@Get(':id')
findOne(
  @Param('id', ParseIntPipe) id: number,
  @Res({ passthrough: true })
  res: FastifyReply,
) {
  res.header('x-cache', 'miss');
  return this.ordersService.findOne(id);
}

Hata yanıtını return ile kurmayın

Önce

Handler'ın döndürdüğü nesne, içinde statusCode alanı olsa da başarılı yanıt olarak gönderilir. Exception fırlatıldığında exception filter doğru durum kodunu üretir.

const order = await this.ordersService
  .findOne(id);
if (!order) {
  return {
    statusCode: 404,
    message: 'Sipariş bulunamadı',
  };
}
//! HTTP 200 {"statusCode":404,...}

const order = await this.ordersService
  .findOne(id);
if (!order) {
  throw new NotFoundException(
    'Sipariş bulunamadı',
  );
}
// HTTP 404 Not Found

Birden fazla filter'ın çalışmasını beklemeyin

Önce

Exception'ı yalnızca en dar kapsamdaki filter yakalar (Örnek 3). Route'a filter eklendiğinde global filter o route'un hataları için çalışmaz. Yalnızca mesaj farklılaşacaksa mesaj exception'a verilir.

// main.ts
app.useGlobalFilters(
  new ErrorLogFilter(),
);

// orders.controller.ts
@Get(':id')
@UseFilters(OrderNotFoundFilter)
findOne(
  @Param('id', ParseIntPipe) id: number,
) { /* ... */ }
//! Bu route'un hataları
//! ErrorLogFilter'a ulaşmaz.

// main.ts
app.useGlobalFilters(
  new ErrorLogFilter(),
);

// orders.service.ts
throw new NotFoundException(
  'Sipariş bulunamadı',
);
// Hata ErrorLogFilter'dan geçer.

Değerlendirme

Altı soru

Her cevaptan sonra doğru cevabın gerekçesi gösterilir.

Hazır olduğunuzda başlayabilirsiniz.

06

Akış hattı · Durak 06 · ~20 dk

Middleware, Guard & Interceptor

Middleware, guard ve interceptor, isteğin handler'a ulaşmadan önce ve yanıt dönerken çalışan sınıflardır. Bu durakta üçünün aldığı argümanlar, verebildikleri kararlar ve uygulamaya nasıl kaydedildikleri tanımlanır; ardından istek kimliği, kimlik ve rol kontrolü ile yanıt zarfı örnekleriyle pekiştirilir.

Tanım

Middleware, guard ve interceptor nedir?

middleware · guard · interceptoristek hattındaki kontrol noktaları

Üçü de handler'ın çevresinde çalışan ve isteğe ortak kurallar uygulayan sınıflardır. Aralarındaki fark, aldıkları argümanlar ve bu argümanlarla verebildikleri karardır. Middleware ham istek ve yanıt nesnelerini alır. Guard, çalışacak handler'ı da içeren ExecutionContext nesnesini alır ve isteğin devam edip etmeyeceğine karar verir. Interceptor ise handler'ı çalıştıran next.handle() çağrısını sarar ve handler'ın döndürdüğü değeri görür.

middlewareuse(req, res, next): Ham istek ve yanıt nesnelerini alan sınıftır. İşini bitirince next()'i çağırır ya da yanıtı kendisi gönderir. Modülün configure() metodunda forRoutes() ile route'lara bağlanır.
guardcanActivate(context): true döndürürse istek devam eder. Exception fırlatırsa exception'ın durum kodu, false döndürürse 403 yanıtı döner.
interceptorintercept(context, next): next.handle() handler'ı çalıştırır ve sonucunu bir Observable olarak döndürür. Interceptor bu akışa RxJS operatörleri ekler: tap sonucu değiştirmeden izler, map sonucu dönüştürür.
ExecutionContextçalışma bağlamı: Çalışan isteğin bağlamıdır. getHandler() handler fonksiyonunu, getClass() controller sınıfını, switchToHttp().getRequest() istek nesnesini verir.
Reflectormetadata okuyucu: @Public(), @Roles() gibi dekoratörlerin handler'a ya da sınıfa eklediği metadata'yı okuyan Nest servisidir. Guard'a ve interceptor'a constructor üzerinden enjekte edilir.
APP_GUARD · APP_INTERCEPTORglobal kayıt token'ları: Global guard ve interceptor'ı bir modülün providers dizisine kaydetmek için kullanılan token'lardır. Bu yolla kaydedilen sınıfı DI container oluşturur; sınıf bağımlılıklarını constructor üzerinden alır.

Katman seçiminin ölçütü, gereksinimin hangi bilgiye ihtiyaç duyduğudur. Hangi route'a gittiğinden bağımsız olarak her istekte yapılacak iş middleware'e, route'a ve kullanıcıya bağlı erişim kararı guard'a, handler'ın sonucuna bağlı iş interceptor'a aittir. Aşağıdaki tablo, her katmanın neye erişebildiğini gösterir.

Değerler NestJS 11 ve Fastify üzerinde ölçülmüştür.

Karar verdiği soru

Kayıt

Ne sağlar

Tek yerde tanımlanan kural. Kimlik kontrolü bir kez yazılır ve tüm route'lara uygulanır; yeni eklenen bir route varsayılan olarak korunur.
Handler üzerinde görünen istisnalar. @Public() ve @Roles('admin') gibi dekoratörler, kuralın hangi route'ta nasıl uygulanacağını handler'ın üstünde gösterir.
Tek biçimli yanıt. Interceptor tüm başarılı yanıtları aynı zarfla döndürür; istemci her endpoint için ayrı ayrıştırma kodu yazmaz.
Yalnızca iş akışı içeren handler. Handler loglama, kimlik kontrolü ve yanıt biçimi kodu içermez.

Katman yanlış seçilirse

Rol kontrolü middleware'e konursa hangi route'un hangi rolü istediği okunamaz; route listesi middleware'de elle tutulur ve yeni route eklendiğinde güncellenmesi unutulur.
İstek loglaması interceptor'a konursa guard'ın reddettiği (401) ve eşleşen route'u olmayan (404) istekler loglanmaz.
Yanıt zarfı middleware'de kurulmaya çalışılırsa handler'ın döndürdüğü değere erişilemez; gövde ancak gönderilmiş metin olarak yakalanabilir.
Kimlik kontrolü her handler'a ayrı ayrı yazılırsa yeni bir route'ta unutulabilir; korumasız endpoint fark edilmez.

Sınırları

Middleware ExecutionContext almaz; @Public() gibi handler metadata'sını okuyamaz.
Guard ve interceptor yalnızca eşleşen bir route olduğunda çalışır; bilinmeyen adreslere gelen isteklerde çalışmaz.
Interceptor'ın map ve tap(fn) kısımları yalnızca başarılı sonuçta çalışır; hata yanıtının biçimi exception filter'da belirlenir (Durak 08).
Global guard'lar providers dizisindeki kayıt sırasıyla çalışır; birbirinin sonucunu kullanan guard'ların sırası kayıtla belirlenir.

Aşağıdaki beş örnek bu tanımı sırasıyla pekiştirir: her isteğe kimlik atayan ve isteği loglayan middleware, token kontrolü yapan global guard ve @Public(), rol kontrolü yapan ikinci guard ve guard'ların kayıt sırası, süre ölçen ve yanıtı zarfa koyan interceptor, son olarak gereksinimlerin katmanlara ayrıldığı bir uygulama.

Örnek 1 · Middleware

Middleware, route'tan bağımsız işleri her isteğe uygular.

Bu örnekte iki middleware tanımlanır. RequestIdMiddleware her isteğe bir x-request-id atar; istemci bu başlığı göndermişse aynı değeri korur. LoggerMiddleware, yanıt gönderildiğinde yöntemi, adresi, durum kodunu ve süreyi loglar. İkisi de forRoutes('{*splat}') ile tüm route'lara bağlanır; uygulamada henüz guard ve interceptor yoktur. Loglar NestJS 11 ve Fastify üzerinde gerçek HTTP istekleriyle alınmıştır; controller'daki log satırı kodda gösterilmemiştir.

request-id.middleware.ts · logger.middleware.ts · app.module.ts

Örnek 2 · Guard: kimlik

Global guard her route'u korur; @Public() istisnayı handler'ın üstünde bildirir.

Bu örnekte AuthGuard, APP_GUARD token'ıyla global olarak kaydedilir; böylece tüm route'lar varsayılan olarak token ister. Guard önce Reflector ile @Public() metadata'sını okur, ardından Authorization başlığındaki token'ı AuthService ile doğrular ve bulunan kullanıcıyı req.user alanına yazar. AuthService.verify(), token'a karşılık gelen kullanıcıyı ya da null döndürür; örnekte sabit bir token tablosu kullanılır, JWT doğrulaması da bu metoda yerleşir. Örnek 1'deki middleware'ler de kayıtlıdır. Loglar NestJS 11 ve Fastify ile alınmıştır; guard'daki ve controller'daki log satırları kodda gösterilmemiştir.

public.decorator.ts · auth.guard.ts · app.module.ts

Örnek 3 · Guard: rol

Rol kontrolü, kimlik kontrolünün yazdığı kullanıcıyı okur; bu yüzden ondan sonra çalışmalıdır.

Bu örnekte ikinci bir global guard eklenir. RolesGuard, handler'a @Roles('admin') ile eklenen rol listesini Reflector ile okur ve req.user.role değeriyle karşılaştırır. Rol listesi olmayan route'larda kontrol yapmadan true döndürür. Ayşe'nin token'ı müşteri, Mehmet'in token'ı admin rolündeki kullanıcıya aittir. Dördüncü adımda iki guard'ın providers dizisindeki sırası değiştirilir. Loglar NestJS 11 ve Fastify ile alınmıştır.

roles.decorator.ts · roles.guard.ts · admin.controller.ts · app.module.ts

Örnek 4 · Interceptor

tap sonucu değiştirmeden izler; map sonucu dönüştürür.

Bu örnekte ResponseInterceptor, APP_INTERCEPTOR token'ıyla global olarak kaydedilir. next.handle() handler'ı çalıştırır ve sonucunu bir akış olarak döndürür; interceptor bu akışa önce süreyi loglayan bir tap, ardından sonucu { data, meta } zarfına koyan bir map ekler. Birinci adımda yalnızca tap vardır; üçüncü adımda zarf tap ile kurulmaya çalışılır. Örnek 2'deki AuthGuard ve Örnek 1'deki middleware'ler de kayıtlıdır. Loglar NestJS 11 ve Fastify ile alınmıştır.

response.interceptor.ts · app.module.ts

Örnek 5 · Uygulama

Her gereksinim, ihtiyaç duyduğu bilgiye erişen katmana aittir.

Bu örnek, tanımdaki ölçütün gereksinimlere uygulanmasıdır. Gereksinim, hangi route'a gittiğinden bağımsız olarak her isteği ilgilendiriyorsa middleware'e; route'a ve kullanıcıya bağlı bir erişim kararıysa guard'a; handler'ın sonucuna ya da çalışıp çalışmayacağına bağlıysa interceptor'a aittir. Her gereksinim için katman seçilir; gerekçe seçimden sonra gösterilir.

Gereksinim 1 / 9

Gereksinim

Ölçüt: Gereksinimin ihtiyaç duyduğu bilgi, ait olduğu katmanı belirler.

Kurallar

Middleware, guard ve interceptor yazılırken uygulanan kurallar

Aşağıdaki yedi kural, katmanların doğru kaydedilmesini ve beklenen biçimde çalışmasını sağlar. Her kartta önce kurala aykırı kullanım gösterilir; Düzelt butonu kurala uygun hâlini gösterir. Yorum satırlarındaki sonuçlar NestJS 11 ve Fastify ile alınmıştır.

Middleware'de next()'i çağırın ya da yanıtı gönderin

Önce

Middleware ne next()'i çağırır ne de yanıtı gönderirse istek o noktada bekler; istemciye yanıt dönmez. Yanıtı kendisi gönderen middleware ise next()'i çağırmadan return eder.

use(req: RawRequest, res: ServerResponse,
    next: () => void) {
  const start = Date.now();
  res.on('finish', () => { /* log */ });
}
//! Hiçbir istek yanıt almaz;
//! istemci zaman aşımına uğrar.

use(req: RawRequest, res: ServerResponse,
    next: () => void) {
  const start = Date.now();
  res.on('finish', () => { /* log */ });
  next();
}

Fastify'da adres için req.originalUrl kullanın

Önce

Fastify'da middleware'e gelen ham istekte req.url tam adresi içermez; ölçümde GET /api/v1/products isteği için değeri '/' idi. Tam adres req.originalUrl alanındadır.

// logger.middleware.ts
console.log(req.method + ' ' + req.url);
//! GET /api/v1/products → "GET /"

// logger.middleware.ts
console.log(req.method + ' ' + req.originalUrl);
// GET /api/v1/products
//   → "GET /api/v1/products"

Tüm route'lar için '{*splat}' desenini yazın

Önce

NestJS 11'in route sözdiziminde joker karakter adlandırılır. Global prefix kullanılan uygulamada '*' deseni bu sözdizimine uymaz; Nest başlangıçta uyarı verir ve deseni dönüştürmeye çalışır.

consumer
  .apply(RequestIdMiddleware)
  .forRoutes('*');
//! WARN [LegacyRouteConverter]
//! Unsupported route path: "/api/v1/*".

consumer
  .apply(RequestIdMiddleware)
  .forRoutes('{*splat}');
// Uyarı yok; bilinmeyen adresler dahil
// tüm isteklerde çalışır.

Global guard'ı APP_GUARD ile kaydedin

Önce

main.ts içinde new ile oluşturulan guard DI container'dan geçmez; constructor bağımlılıkları verilmez. APP_GUARD ile kaydedilen guard'ı container oluşturur.

// main.ts
app.useGlobalGuards(new AuthGuard());
//! TS2554: Expected 2 arguments,
//! but got 0.

// app.module.ts
providers: [
  AuthService,
  { provide: APP_GUARD, useClass: AuthGuard },
],
// Reflector ve AuthService enjekte edilir.

Metadata'yı handler'dan ve sınıftan birlikte okuyun

Önce

Dekoratör metoda da sınıfa da konabilir. Yalnızca getHandler() okunduğunda sınıfa konan @Public() görülmez.

const isPublic = this.reflector.get<boolean>(
  IS_PUBLIC_KEY,
  context.getHandler(),
);
//! @Public() sınıftaysa okunmaz:
//! GET /categories → 401

const isPublic = this.reflector
  .getAllAndOverride<boolean>(IS_PUBLIC_KEY, [
    context.getHandler(),
    context.getClass(),
  ]);
// GET /categories → 200

RolesGuard'ı AuthGuard'dan sonra kaydedin

Önce

Global guard'lar kayıt sırasıyla çalışır. RolesGuard önce çalışırsa req.user henüz atanmamıştır; rol okunurken TypeError fırlatılır.

providers: [
  { provide: APP_GUARD, useClass: RolesGuard },
  { provide: APP_GUARD, useClass: AuthGuard },
],
//! TypeError: Cannot read properties
//! of undefined (reading 'role') → 500

providers: [
  { provide: APP_GUARD, useClass: AuthGuard },
  { provide: APP_GUARD, useClass: RolesGuard },
],
// Müşteri → 403, admin → 200

Yanıtı tap ile değil map ile dönüştürün

Önce

tap'e verilen fonksiyonun dönüş değeri yok sayılır; akıştaki değer değişmez. Değeri dönüştürmek için map kullanılır.

return next.handle().pipe(
  tap((data) => ({ data })),
);
//! Yanıt değişmez:
//! [{"id":42,"status":"hazırlanıyor"}]

return next.handle().pipe(
  map((data) => ({ data })),
);
// {"data":[{"id":42,...}]}

Değerlendirme

Altı soru

Her cevaptan sonra doğru cevabın gerekçesi gösterilir.

Hazır olduğunuzda başlayabilirsiniz.

07

Akış hattı · Durak 07 · ~20 dk

DTO & Validation

DTO (Data Transfer Object), istemci ile sunucu arasında taşınan verinin alanlarını ve tiplerini tanımlayan sınıftır. Validation ise gelen verinin bu tanıma uyup uymadığının çalışma anında denetlenmesidir. Bu durakta DTO sınıfı, class-validator kuralları ve ValidationPipe tanımlanır; ardından kural ihlalleri, tanımsız alanlar, iç içe nesneler ve yanıtta yer alacak alanlar örneklerle pekiştirilir.

Tanım

DTO ve validation nedir?

DTO · validationisteğin sözleşmesi ve denetimi

DTO, bir endpoint'in kabul ettiği ya da döndürdüğü verinin alanlarını ve tiplerini tanımlayan sınıftır. Validation, gelen verinin bu tanıma uyup uymadığının çalışma anında denetlenmesidir. NestJS'te DTO bir class olarak yazılır ve kurallar alanların üstüne class-validator dekoratörleriyle eklenir. Global olarak kaydedilen ValidationPipe, handler'ın parametre tipini okur, gövdeyi o sınıfın bir örneğine dönüştürür ve kuralları denetler. Kurallardan biri ihlal edilirse handler çalışmadan 400 yanıtı döner.

input DTOcreate-product.dto.ts: İstemciden gelen gövdenin, sorgu parametrelerinin ya da route parametrelerinin şeklidir. Her alanın kuralı, alanın üstüne yazılan dekoratörlerle tanımlanır.
response DTOuser.response.dto.ts: Yanıtta yer alacak alanları tanımlar. Kayıtta bulunan diğer alanlar, örneğin password_hash, yanıta girmez.
class-validator@IsInt(), @Min(1): Dekoratörlerle tanımlanan kuralları bir nesne üzerinde denetleyen kütüphanedir. İhlal edilen her kural için bir mesaj üretir.
class-transformerplainToInstance(): JSON'dan gelen düz nesneyi bir class örneğine, class örneğini de düz nesneye dönüştüren kütüphanedir. @Type() ve @Expose() dekoratörleri bu dönüşümü yönlendirir.
ValidationPipe@nestjs/common: Handler'ın parametre tipi bir class ise gövdeyi o class'ın örneğine dönüştürür ve doğrular. main.ts içinde app.useGlobalPipes() ile kaydedilir; bağımlılığı olmadığı için new ile oluşturulabilir.
whitelist · transformValidationPipe seçenekleri: whitelist: true, DTO'da kuralı olmayan alanları siler. transform: true, handler'a gövdenin kendisi yerine DTO sınıfının örneğini verir.

ValidationPipe parametrenin tipini, derleyicinin emitDecoratorMetadata ayarıyla koda eklediği metadata'dan okur. Class çalışma anında da var olduğu için bu metadata class'ı gösterir; interface ise derlemeden sonra silinir ve metadata'da Object olarak görünür (Durak 01). Aşağıdaki akış, aynı endpoint'e geçerli ve geçersiz gövde gönderildiğinde ve DTO class yerine interface olarak tanımlandığında olanları gösterir.

Değerler NestJS 11, Fastify ve class-validator 0.15 ile ölçülmüştür.

main.ts · create-product.dto.ts · products.controller.ts

Ne sağlar

Tek tanım, iki görev. DTO sınıfı hem TypeScript tipi hem de çalışma anında denetlenen kural listesidir; tip ile kural ayrı yerlerde tutulmaz.
Handler'a ulaşmayan geçersiz istek. Bir kural ihlal edilirse handler ve service çalışmaz; istemci her ihlal için ayrı bir mesaj alır.
Ayıklanan alanlar. whitelist, DTO'da tanımlı olmayan alanları siler; response DTO, yanıtta yalnızca belirtilen alanları bırakır.
Sınıf örneği olarak gelen veri. transform: true ile handler, gövdenin kendisini değil DTO sınıfının bir örneğini alır; ölçümde seçenek olmadan dto düz bir Object idi.

DTO kullanılmazsa

Gövdenin tipi yalnızca TypeScript'te tanımlıysa derlemeden sonra silinir; ölçümde "unit_price": -5 içeren gövde 201 ile kabul edildi.
İstemcinin eklediği "role": "admin" gibi alanlar nesneye kopyalanır ve kullanıcının rolünü değiştirir (Örnek 2).
Kayıt doğrudan döndürülürse password_hash gibi alanlar yanıtta yer alır (Örnek 4).
Kontroller handler'lara dağılır; her endpoint farklı mesajla ve farklı durum koduyla yanıt verir.

Sınırları

Hazır dekoratörler gelen değerin biçimini denetler. Veritabanına bağlı kurallar, örneğin e-posta benzersizliği ve stok, service'te denetlenir.
ValidationPipe yalnızca parametre tipi bir class olduğunda çalışır; interface ve type ile tanımlanan parametreler denetlenmez.
İç içe nesneler, @ValidateNested() ve @Type() birlikte yazılmadıkça denetlenmez (Örnek 3).
400 yanıtının biçimi (message dizisi) varsayılandır; değiştirilmesi Durak 08'de ele alınır.

Aşağıdaki beş örnek bu tanımı sırasıyla pekiştirir: her değerin hangi kuralı ihlal ettiğinin izlendiği bir form, tanımsız alanları ayıklayan whitelist, iç içe nesnelerin denetlenmesi, yanıtta yer alacak alanları belirleyen response DTO, son olarak kuralların DTO, ValidationPipe ve service arasında paylaştırıldığı bir uygulama.

Örnek 1 · Kurallar ve mesajlar

Her kural ayrı denetlenir; ihlal edilen her kural bir mesaj üretir.

Bu örnekteki CreateProductDto, Durak 03'te oluşturulan create-product.dto.ts dosyasına kurallar eklenmiş hâlidir. POST /api/v1/products endpoint'ine gönderilen gövde, aşağıdaki seçeneklerle değiştirilir. Seçilebilen 80 gövdenin her biri NestJS 11 ve Fastify üzerinde gerçek HTTP isteğiyle gönderilmiş, yanıtlar olduğu gibi kaydedilmiştir; kural göstergeleri bu yanıtlardaki mesajlardan çizilir. Göstergedeki numara, mesajın message dizisindeki sırasıdır.

name

unit_price

stock

create-product.dto.ts

Örnek 2 · whitelist

DTO'da tanımlı olmayan alan, handler'a ulaşmadan silinmeli ya da reddedilmelidir.

Bu örnekte kayıt endpoint'ine gönderilen gövdeye istemci "role": "admin" alanını ekler. RegisterDto'da bu alan yoktur. Handler gövdeyi Object.assign(new User(), dto) ile bir User nesnesine kopyalar; User sınıfında role alanının varsayılan değeri 'customer''dır. Üç adımda yalnızca ValidationPipe'ın seçenekleri değişir. Loglar NestJS 11 ve Fastify ile alınmıştır; controller'daki log satırı kodda gösterilmemiştir.

register.dto.ts · user.ts · auth.controller.ts · main.ts

Örnek 3 · İç içe DTO

Dizideki nesneler, @ValidateNested() ve @Type() birlikte yazıldığında denetlenir.

Bu örnekte sipariş gövdesi bir kalem dizisi içerir; her kalem Durak 01'deki CreateOrderItemDto sınıfıyla tanımlanır. @ValidateNested(), dizideki nesnelerin de doğrulanacağını bildirir. @Type(), class-transformer'a dizideki düz nesnelerin hangi sınıfa dönüştürüleceğini söyler; TypeScript'teki CreateOrderItemDto[] tipi çalışma anında okunamaz. Adımlarda items alanının dekoratörleri ve gövde değişir; ValidationPipe whitelist: true ve transform: true ile kayıtlıdır.

create-order-item.dto.ts · create-order.dto.ts

Örnek 4 · Response DTO

Yanıtta yer alacak alanlar, response DTO'da @Expose() ile tek tek belirtilir.

Bu örnekte GET /api/v1/users/7 endpoint'i Ayşe'nin kaydını döndürür. Kayıtta parolanın hash'i (password_hash) da bulunur. UsersService.findById() kaydı sabit bir veriden döndürür; veritabanı Durak 09'da eklenir. Adımlarda yalnızca handler'ın dönüş satırı değişir. Loglar NestJS 11 ve Fastify ile alınmıştır; controller'daki log satırı, döndürülen nesnenin sınıfını ve alanlarını yazar ve kodda gösterilmemiştir.

user.response.dto.ts · users.controller.ts

Örnek 5 · Uygulama

Biçim kuralı DTO'ya, uygulama genelindeki davranış ValidationPipe'a, veriye bağlı kural service'e aittir.

Bu örnek, tanımdaki sınırların gereksinimlere uygulanmasıdır. Gereksinim yalnızca gelen değerin biçimine bakıyorsa DTO dekoratörüyle; tüm DTO'lara aynı biçimde uygulanacak bir davranışsa ValidationPipe seçeneğiyle; veritabanındaki kayıtlara ya da kullanıcıya bağlıysa service'te karşılanır. Her gereksinim için yer seçilir; gerekçe seçimden sonra gösterilir.

Gereksinim 1 / 9

Gereksinim

Ölçüt: Kuralın karar vermek için neye baktığı, yazılacağı yeri belirler.

Kurallar

DTO yazılırken uygulanan kurallar

Aşağıdaki yedi kural, doğrulamanın ve dönüşümün beklenen biçimde çalışmasını sağlar. Her kartta önce kurala aykırı kullanım gösterilir; Düzelt butonu kurala uygun hâlini gösterir. Yorum satırlarındaki sonuçlar NestJS 11, Fastify ve class-validator 0.15 ile alınmıştır.

DTO'yu interface değil class olarak tanımlayın

Önce

Interface derlemeden sonra silinir; ValidationPipe parametre tipini Object olarak görür ve doğrulamayı atlar. Class çalışma anında da vardır ve dekoratörlerin eklediği kurallar onun üzerinde okunur.

export interface CreateProductDto {
  name: string;
  unit_price: number;
  stock: number;
}
//! {"name":"","unit_price":-5,"stock":25}
//!   → 201; gövde doğrulanmadı

export class CreateProductDto {
  @IsString()
  @IsNotEmpty()
  name: string;
  // unit_price ve stock kuralları
}
// {"name":"","unit_price":-5,"stock":25}
//   → 400 "name should not be empty",
//     "unit_price must be a positive number"

İsteğe bağlı alana @IsOptional() ekleyin

Önce

Alan adındaki ? yalnızca TypeScript tipini etkiler. Gönderilmeyen alanın değeri undefined'dır ve alanın tüm kuralları bu değerle denetlenir. @IsOptional(), değer undefined ya da null olduğunda kuralları atlar.

@IsString()
@MaxLength(200)
note?: string;
//! note gönderilmezse → 400
//! "note must be shorter than or equal
//!  to 200 characters", "note must be a string"

@IsOptional()
@IsString()
@MaxLength(200)
note?: string;
// note gönderilmezse → 201
// "note": 42 → 400; kurallar yine çalışır

İç içe DTO'da @ValidateNested() ile @Type()'ı birlikte yazın

Önce

@Type() olmadan dizideki nesneler düz nesne olarak kalır. Düz nesnede kural bulunmadığı için whitelist tüm alanlarını siler; hata oluşmaz, veri kaybolur.

@IsArray()
@ArrayMinSize(1)
@ValidateNested({ each: true })
items: CreateOrderItemDto[];
//! {"items":[{"product_id":3,"quantity":2}]}
//!   → handler'a gelen: {"items":[{}]}

@IsArray()
@ArrayMinSize(1)
@ValidateNested({ each: true })
@Type(() => CreateOrderItemDto)
items: CreateOrderItemDto[];
// → {"items":[{"product_id":3,"quantity":2}]}

Sayı beklenen sorgu parametresine @Type(() => Number) ekleyin

Önce

Sorgu parametreleri her zaman metin olarak gelir; transform: true metni kendiliğinden sayıya çevirmez. @Type(() => Number) çevirir. Sayıya çevrilemeyen değer NaN olur ve @IsInt() kuralını ihlal eder.

// product-query.dto.ts
@IsOptional()
@IsInt()
@Min(1)
page?: number;
//! GET /products?page=2 → 400
//! "page must not be less than 1",
//! "page must be an integer number"

// product-query.dto.ts
@IsOptional()
@Type(() => Number)
@IsInt()
@Min(1)
page?: number;
// ?page=2   → page: 2 (number)
// ?page=abc → 400; NaN tam sayı değildir

Yanıtı dönüş tipine güvenmeden DTO'ya dönüştürün

Önce

TypeScript yapısal tip denetimi yapar; fazladan alanı olan nesne, daha az alanlı bir tipe atanabilir. Dönüş tipi çalışma anında hiçbir alanı silmez.

async findOne(
  @Param('id', ParseIntPipe) id: number,
): Promise<UserResponseDto> {
  return this.usersService.findById(id);
}
//! tsc hata vermez; yanıtta password_hash var

const user = await this.usersService.findById(id);
return plainToInstance(UserResponseDto, user, {
  excludeExtraneousValues: true,
});
// {"id":7,"email":"ayse@ornek.com","name":"Ayşe",
//  "role":"customer","created_at":"2026-03-14T…"}

Response DTO'da yanıta girecek her alana @Expose() ekleyin

Önce

excludeExtraneousValues: true yalnızca @Expose() ile işaretlenen alanları kopyalar. İşaret unutulan alan yanıttan sessizce düşer; hata oluşmaz.

export class UserResponseDto {
  @Expose() id: number;
  @Expose() email: string;
  name: string;
  @Expose() role: Role;
  @Expose() created_at: Date;
}
//! Yanıtta name yok: {"id":7,"email":
//!  "ayse@ornek.com","role":"customer",…}

export class UserResponseDto {
  @Expose() id: number;
  @Expose() email: string;
  @Expose() name: string;
  @Expose() role: Role;
  @Expose() created_at: Date;
}
// {"id":7,"email":"ayse@ornek.com",
//  "name":"Ayşe","role":"customer",…}

Update DTO'yu PartialType ile türetin

Önce

Kuralsız yazılan update DTO'sunda whitelist her alanı tanımsız sayar ve siler; güncelleme sessizce atlanır. PartialType, create DTO'sunun kurallarını alır ve her alana @IsOptional() ekler.

export class UpdateProductDto {
  name?: string;
  unit_price?: number;
  stock?: number;
}
//! PATCH {"unit_price":-1} → dto: {} → 200
//! PATCH {"unit_price":1199.9} → dto: {} → 200

import { PartialType } from '@nestjs/mapped-types';

export class UpdateProductDto
  extends PartialType(CreateProductDto) {}
// PATCH {"unit_price":-1}
//   → 400 "unit_price must be a positive number"
// PATCH {"unit_price":1199.9}
//   → dto: {"unit_price":1199.9}

Değerlendirme

Altı soru

Her cevaptan sonra doğru cevabın gerekçesi gösterilir.

Hazır olduğunuzda başlayabilirsiniz.

08

Akış hattı · Durak 08 · ~20 dk

Exception & HTTP Status

Exception, bir işlemin beklenen şekilde tamamlanamadığını bildiren hata nesnesidir. HTTP status kodu ise bu sonucun istemciye standart biçimde iletilmesini sağlar. Bu durakta exception'ın yanıta nasıl dönüştüğü, status kod aileleri ve hazır exception sınıfları tanımlanır; ardından yanlış kodun ve yutulan hatanın sonuçları, hata yanıtlarını tek biçimde döndüren exception filter ve durumlara göre kod seçimi örneklerle pekiştirilir.

Tanım

Exception ve HTTP status nedir?

exception · HTTP statushatanın bildirilmesi ve sınıflandırılması

Exception, bir işlemin beklenen şekilde tamamlanamadığını bildirmek için throw ile fırlatılan hata nesnesidir. HTTP status kodu, yanıtın ilk satırında yer alan ve sonucu sınıflandıran üç basamaklı sayıdır. NestJS'te service ya da controller içinde fırlatılan exception, çağıran fonksiyonlara doğru ilerler ve Nest'in exception katmanında yakalanır. Exception HttpException sınıfından türüyorsa yanıtın status kodu ve gövdesi bu nesneden okunur. Türemiyorsa, örneğin bir TypeError ise, yanıt 500 Internal Server Error olur ve hata konsola loglanır. İstemci sonucun başarılı olup olmadığını status kodundan anlar.

exception · throwthrow new NotFoundException(): Fırlatıldığı satırda fonksiyonun çalışmasını durdurur; yakalanmazsa çağıran fonksiyonlara doğru ilerler. Service, controller'a "kayıt yok" bilgisini bu yolla iletir.
HttpException@nestjs/common: Status kodunu ve yanıt gövdesini taşıyan exception sınıfıdır. NotFoundException, ConflictException gibi hazır sınıflar bu sınıftan türer.
HTTP status kodu200, 404, 500: Yanıtın sonucunu sınıflandırır. İlk basamak aileyi belirtir: 2xx başarı, 4xx istemci hatası, 5xx sunucu hatası.
exception katmanıExceptionsHandler: Nest'in yerleşik exception filter'ıdır. Yakalanmayan her exception'ı yanıta dönüştürür; HttpException olmayan hataları [ExceptionsHandler] bağlamıyla loglar.
exception filter@Catch(): Exception'ın yanıta nasıl dönüştürüleceğini belirleyen sınıftır. Global olarak kaydedildiğinde bütün hata yanıtları tek biçimde döndürülür (Örnek 4).
HttpStatusHttpStatus.NO_CONTENT: Status kodlarının adlandırılmış karşılıklarını içeren enum'dur. Kodda 204 yerine HttpStatus.NO_CONTENT yazılır.

Aşağıdaki akışta GET /api/v1/products/999 isteği gönderilir; 999 numaralı ürün yoktur. Üç adımda yalnızca ProductsService.findOne() metodunun, ürün bulunamadığında yaptığı iş değişir. İkinci adımdaki kod, Nest CLI'ın varsayılan ayarı olan strictNullChecks açıkken de hatasız derlenir: filter() sonucunun ilk elemanının tipi undefined olasılığını göstermez.

Değerler NestJS 11 ve Fastify ile ölçülmüştür.

products.service.ts · products.controller.ts

Ne sağlar

Sınıflandırılmış sonuç. İstemci gövdeyi okumadan önce sonucu status kodundan anlar; fetch'in res.ok değeri yalnızca 200–299 aralığında true olur.
Service'ten doğrudan bildirim. Service, HTTP katmanını bilmeden throw ile işlemi durdurur; controller'da dönüş değerini kontrol eden bir if yazılmaz.
Ayrılan sunucu hataları. HttpException olmayan hata 500'e dönüşür ve loglanır; hatanın ayrıntısı istemciye gönderilmez.
Tek biçim. Global bir exception filter ile bütün hata yanıtları aynı alanlarla döndürülür (Örnek 4).

Doğru kod dönülmezse

Bulunamayan kayıt 200 ve boş gövdeyle döner; istemci başarılı sandığı yanıtı işlerken res.json() hata fırlatır (3. adım).
Kontrol edilmeyen durum 500'e dönüşür; istemcinin düzeltebileceği bir durum sunucu hatası olarak bildirilir ve loglara gereksiz hata kaydı düşer (2. adım).
Kayıtlı e-posta için 401 dönülürse ön yüzün oturum kontrolü kullanıcıyı giriş sayfasına gönderir (Örnek 3).
Sunucu hatalarının oranını izleyen alarmlar, 500 olarak dönen istemci hatalarıyla karışır.

Sınırları

Status kodu sonucun yalnızca ailesini bildirir; neyin yanlış olduğunu gövdedeki mesaj anlatır.
Exception katmanı yalnızca istek işlenirken fırlatılan hatayı görür. await edilmeyen promise'in hatası bu katmana ulaşmaz (Kural 7).
Nest, bilinçli olarak fırlatılan HttpException'ları loglamaz; açıkça fırlatılan InternalServerErrorException da ölçümde loglanmadı (Örnek 2).
Varsayılan hata gövdesinin biçimi hataya göre değişir; tek biçim exception filter ile sağlanır (Örnek 4).

Aşağıdaki beş örnek bu tanımı sırasıyla pekiştirir: status kod aileleri ve kodların nereden geldiği, hazır exception sınıflarının gövde biçimleri, yanlış kodun ve yutulan hatanın sonuçları, hata yanıtlarını tek biçimde döndüren exception filter, son olarak verilen durumlar için doğru kodun seçildiği bir uygulama.

Örnek 1 · Status kod aileleri

Status kodunun ilk basamağı, sonucun kime ait olduğunu bildirir.

Bu örnekte aynı uygulamaya on istek gönderilir. Endpoint'ler önceki duraklarda tanımlanmıştır: AuthGuard ve RolesGuard global olarak kayıtlıdır (Durak 06), ValidationPipe whitelist ve transform seçenekleriyle çalışır (Durak 07). Bir istek seçildiğinde yanıtın status kodu ölçek üzerinde işaretlenir ve kodu üreten satır gösterilir. İstekler NestJS 11 ve Fastify üzerinde gerçek HTTP ile gönderilmiştir.

Örnek 2 · Hazır exception sınıfları

Exception sınıfı status kodunu, verilen argüman gövdenin biçimini belirler.

Bu örnekte bir handler, seçilen sınıfı seçilen argümanla fırlatır; global bir exception filter kayıtlı değildir. Altı sınıf ve beş argüman biçimi gerçek HTTP ile ölçülmüştür. Kart, yanıt gövdesindeki alanları JSON'daki sıralarıyla gösterir. Kesik çizgili satır, bu biçimde yer almayan standart alandır.

Sınıf

Argüman

products.controller.ts

Örnek 3 · Yanlış kod ve yutulan hata

Status kodu durumu doğru tanımlamalı; beklenmeyen hata başka bir koda çevrilmemelidir.

Bu örnekte POST /api/v1/auth/register endpoint'ine istek gönderilir. Ayşe'nin e-posta adresi kayıtlıdır; Durak 07'de bu kontrolün service'e ait olduğu belirlenmişti. 1. ve 2. adımda kayıtlı e-postayla, 3. ve 4. adımda yeni bir e-postayla istek gönderilir. createTokens() metodunda bilinçli bir hata vardır: jwt ayarı yüklenmemiştir. Ön yüzde istekleri gönderen yardımcı fonksiyonun yanıtı aşağıdaki gibi yorumladığı varsayılır; bu ön yüz kodu bir örnektir ve ölçülmemiştir.

// lib/api.ts (Next.js · örnek ön yüz kodu)
if (res.status === 401) redirect('/login'); // oturum sona ermiş sayılır
if (res.status === 409) return { error: body.message }; // formda gösterilir
if (!res.ok) throw new Error('Beklenmeyen hata'); // hata sayfası

auth.service.ts

Örnek 4 · Exception filter

Global exception filter, bütün hata yanıtlarını tek biçimde döndürür.

Durak 06'daki interceptor başarılı yanıtları { data, meta } zarfına koyar; hata yanıtları bu zarfa girmez. Nest'in varsayılan hata gövdesi üç biçimdedir: HttpException için { message, error, statusCode }, doğrulama hatasında message alanı bir dizi (Durak 07), beklenmeyen hatada alan sırası ters çevrilmiş { statusCode, message }. Bu örnekte aynı istekler, AllExceptionsFilter kaydedilmeden ve APP_FILTER ile kaydedildikten sonra gönderilir. RequestIdMiddleware ve ResponseInterceptor Durak 06'dakiyle aynıdır.

all-exceptions.filter.ts · app.module.ts

Örnek 5 · Uygulama

Her durum için, sonucu en doğru sınıflandıran kod seçilir.

Bu örnek, tanımdaki ailelerin durumlara uygulanmasıdır. Önce sorunun istemcide mi sunucuda mı olduğuna, ardından istemci hatasının türüne bakılır: biçim hatası 400, kimliğin doğrulanamaması 401, yetkinin olmaması 403, kaydın bulunamaması 404, mevcut durumla çelişki 409'dur. Her durum için kod seçilir; gerekçe seçimden sonra gösterilir.

Durum 1 / 10

Durum

Ölçüt: İsteği kim düzeltebilir ve neyi değiştirmesi gerekir?

Kurallar

Hata yönetiminde uygulanan kurallar

Aşağıdaki yedi kural, hatanın doğru kodla bildirilmesini, kaybolmamasını ve istemciye tek biçimde ulaşmasını sağlar. Her kartta önce kurala aykırı kullanım gösterilir; Düzelt butonu kurala uygun hâlini gösterir. Yorum satırlarındaki sonuçlar NestJS 11, Fastify ve Node 24 ile alınmıştır.

Bulunamayan kayıt için exception fırlatın

Önce

Service undefined döndürdüğünde exception oluşmaz ve yanıt 200 olur. İstemci başarılı sandığı yanıtı işlemeye devam eder. NotFoundException, durumu status koduyla bildirir.

findOne(id: number): Product | undefined {
  return this.products.find((p) => p.id === id);
}
//! GET /products/999 → 200, gövde boş
//! res.json() → SyntaxError:
//!   Unexpected end of JSON input

findOne(id: number) {
  const product = this.products.find(
    (p) => p.id === id,
  );
  if (!product) {
    throw new NotFoundException('Ürün bulunamadı');
  }
  return product;
}
// GET /products/999 → 404
//   {"message":"Ürün bulunamadı",
//    "error":"Not Found","statusCode":404}

Durumu tanımlayan exception sınıfını seçin

Önce

401, kimliğin doğrulanamadığını bildirir; ön yüz bu kodda kullanıcıyı çoğunlukla giriş sayfasına gönderir. Kayıtlı e-posta, isteğin mevcut kayıtla çeliştiği bir durumdur ve 409 ile bildirilir.

if (existing) {
  throw new UnauthorizedException(
    'Bu e-posta adresi zaten kayıtlı',
  );
}
//! → 401 Unauthorized
//! ön yüz: redirect('/login')

if (existing) {
  throw new ConflictException(
    'Bu e-posta adresi zaten kayıtlı',
  );
}
// → 409 Conflict
// ön yüz: mesaj formda gösterilir

Yalnızca anlamı bilinen hatayı yakalayın

Önce

Bütün hataları yakalayıp tek bir HttpException'a çeviren catch, yazılımdaki hatayı istemcinin hatası gibi bildirir ve logdan siler. Belirli bir hata yakalanacaksa yalnızca o hata kontrol edilir; diğerleri throw err ile yeniden fırlatılır.

try {
  return this.createTokens(user);
} catch {
  throw new UnauthorizedException(
    'Token oluşturulamadı',
  );
}
//! → 401 "Token oluşturulamadı"
//! sunucu konsolunda kayıt yok

return this.createTokens(user);
// → 500 {"statusCode":500,
//   "message":"Internal server error"}
// [ExceptionsHandler] TypeError: Cannot read
//   properties of undefined (reading 'secret')

Hata gövdesinin biçimini filter'da kurun

Önce

Exception'a nesne verildiğinde gövde bu nesnenin kendisi olur; statusCode ve error alanları eklenmez. Her handler kendi biçimini ürettiğinde istemci her yanıtı ayrı okumak zorunda kalır. Biçim tek yerde, exception filter'da kurulur.

throw new NotFoundException({
  code: 'PRODUCT_NOT_FOUND',
  message: 'Ürün bulunamadı',
});
//! → {"code":"PRODUCT_NOT_FOUND",
//!    "message":"Ürün bulunamadı"}

throw new NotFoundException('Ürün bulunamadı');
// AllExceptionsFilter (Örnek 4) ile:
// → {"error":{"status_code":404,
//     "message":"Ürün bulunamadı"},
//    "meta":{"request_id":"…",
//     "path":"/api/v1/products/999"}}

Filter'da 5xx hatalarını loglayın

Önce

@Catch() filter'ı, Nest'in yerleşik exception katmanının yerini alır ve onun yazdığı log da kaybolur. 500 yanıtının nedeni yalnızca sunucuda bulunabildiği için 5xx hataları filter'da loglanır.

const status = isHttp
  ? exception.getStatus()
  : HttpStatus.INTERNAL_SERVER_ERROR;
// loglama yok
//! GET /orders/42/invoice → 500
//! sunucu konsolunda kayıt yok

if (status >= 500) {
  this.logger.error(
    exception instanceof Error
      ? exception.stack
      : String(exception),
  );
}
// [ExceptionFilter] TypeError: Cannot read
//   properties of undefined (reading 'number')

500 yanıtında iç hata mesajını göndermeyin

Önce

Beklenmeyen hatanın mesajı kodun iç yapısını, veritabanı sorgularını ya da dosya yollarını içerebilir. İstemciye genel bir mesaj gönderilir; ayrıntı logda kalır ve request_id ile eşleştirilir.

message = exception instanceof Error
  ? exception.message
  : 'Sunucuda beklenmeyen bir hata oluştu';
//! → {"error":{"status_code":500,"message":
//!    "Cannot read properties of undefined
//!     (reading 'number')"},...}

let message =
  'Sunucuda beklenmeyen bir hata oluştu';
if (isHttp) { /* HttpException mesajı okunur */ }
// → {"error":{"status_code":500,"message":
//    "Sunucuda beklenmeyen bir hata oluştu"},
//    "meta":{"request_id":"…",...}}

Promise'i await edin ya da hatasını yakalayın

Önce

await edilmeyen promise'in hatası istek bittikten sonra oluşur ve exception katmanına ulaşmaz. Node 24.21 ile yapılan ölçümde yanıt 201 olarak gönderildi, ardından Node'un varsayılan davranışıyla süreç 1 çıkış koduyla kapandı; global filter kayıtlıyken de sonuç aynıydı. Sonuç işlemi etkiliyorsa await edilir, etkilemiyorsa .catch() ile loglanır.

void this.mailService.sendConfirmation(order.id);
return order;
//! → 201 {"id":43,"status":"hazırlanıyor"}
//! Error: SMTP bağlantısı kurulamadı
//! Node.js v24.21.0 · süreç kapandı (exit 1)

// Sonuç siparişi etkiliyorsa:
await this.mailService.sendConfirmation(order.id);
// → 500, [ExceptionsHandler] logu; süreç çalışır

// Etkilemiyorsa:
this.mailService
  .sendConfirmation(order.id)
  .catch((err: Error) => this.logger.error(
    'Onay e-postası gönderilemedi: ' + err.message,
  ));
// → 201; [CheckoutController] Onay e-postası
//   gönderilemedi: SMTP bağlantısı kurulamadı

Değerlendirme

Altı soru

Her cevaptan sonra doğru cevabın gerekçesi gösterilir.

Hazır olduğunuzda başlayabilirsiniz.

09

Veri hattı · Durak 09 · ~25 dk

Veritabanına Giriş

Veritabanı, verinin kalıcı, tutarlı ve sorgulanabilir biçimde saklandığı sistemdir. Entity ise bir veritabanı tablosunun kod tarafındaki karşılığıdır. Bu durakta önce veritabanı, tablo ve entity tanımlanır; ardından constraint'ler, entity'den üretilen SQL, repository metotları, bağlantı yapılandırması, migration, index ve kolon tipi seçimi örneklerle pekiştirilir. Örneklerdeki bütün çıktılar NestJS 11, TypeORM 0.3 ve PostgreSQL 18 ile alınmıştır.

Tanım

Veritabanı ve entity nedir?

veritabanı · entityverinin kalıcı saklanması ve kod karşılığı

Veritabanı, verinin kalıcı, tutarlı ve sorgulanabilir biçimde saklandığı sistemdir. Bu eğitimde kullanılan PostgreSQL ilişkisel bir veritabanıdır: veri tablolarda, satır ve kolonlar hâlinde tutulur ve SQL ile sorgulanır. Uygulamanın süreci kapansa da veri diskte kalır; aynı anda gelen yazma işlemleri birbirinin kaydını ezmez; tablo tanımındaki kurallara uymayan satır reddedilir. Entity, bir tablonun kod tarafındaki karşılığı olan sınıftır: sınıf tabloya, her alan bir kolona, sınıfın her örneği bir satıra karşılık gelir. TypeORM gibi bir ORM, entity tanımından tabloyu oluşturur ve repository üzerinden yapılan metot çağrılarını SQL'e çevirir.

tablo · satır · kolonproducts: Tablo aynı türdeki kayıtları tutar. Her satır bir kayıttır, her kolon kayıtların bir alanıdır; kolonun tipi, o alana yazılabilecek değeri sınırlar.
primary keyid: Satırı tekil olarak tanımlayan kolondur. Aynı değer ikinci kez yazılamaz; PostgreSQL bu kolon için otomatik olarak bir index oluşturur.
constraintNOT NULL · UNIQUE · CHECK: Tabloya yazılacak satırın uyması gereken kuraldır. Kurala uymayan INSERT ya da UPDATE veritabanı tarafından reddedilir (Örnek 1).
entity@Entity('products'): Tablonun sınıf karşılığıdır. Dekoratörler kolonların tipini ve kurallarını tanımlar (Örnek 2).
ORM · TypeORM@nestjs/typeorm: Entity'ler ile tablolar arasında çeviri yapan kütüphanedir. Sorgular metot çağrılarıyla yazılır; TypeORM bunları parametreli SQL'e çevirir (Örnek 3).
repositoryRepository<Product>: Bir entity'nin tablosuna erişen nesnedir; find, save, update, delete metotlarını sunar. Service'e @InjectRepository ile enjekte edilir (Durak 03).
migrationmigration:run: Şema değişikliğini SQL olarak kaydeden ve sırayla çalıştırılan dosyadır (Örnek 5).
index@Column({ unique: true }): Bir kolondaki değerleri sıralı bir yapıda tutarak aramayı hızlandırır; tablo her değiştiğinde güncellenir (Örnek 6).

Durak 03–08'de ürünler service içindeki bir dizide tutuldu. Aşağıdaki akışta aynı POST /api/v1/products endpoint'i üç farklı depoyla çalıştırılır: bellekteki dizi, diske yazılan bir JSON dosyası ve PostgreSQL. Her adımda önce bir ürün, ardından aynı anda 20 ürün eklenir; sonra sunucunun süreci sonlandırılıp yeniden başlatılır ve 1 numaralı ürün istenir. Durak 06'daki zarf interceptor'ı ve Durak 08'deki exception filter kayıtlıdır.

Sunucu ayrı bir süreçte çalıştırılmış, istekler gerçek HTTP ile gönderilmiştir.

products.service.ts

Ne sağlar

Kalıcılık. Süreç yeniden başlatıldıktan sonra 21 kaydın tamamı yerindeydi (3. adım).
Eşzamanlı yazmada tutarlılık. Aynı anda gönderilen 20 istek 20 ayrı satır ve 20 farklı id üretti.
Kurallar. Constraint'e uymayan satır, uygulamayı atlayan bir betikten yazılmak istense de reddedilir (Örnek 1).
Sorgu. Filtreleme, sıralama ve sayfalama veritabanında yapılır; uygulamaya yalnızca istenen satırlar gelir (Örnek 3).

Kullanılmazsa

Bellekteki veri süreçle birlikte kaybolur; ölçümde yeniden başlatmadan sonra 0 kayıt kaldı (1. adım).
JSON dosyasında aynı anda yapılan oku-değiştir-yaz işlemleri birbirini ezer: 20 isteğin hepsi id: 2 ile yanıtlandı, dosyada 2 kayıt kaldı (2. adım).
Aynı anda yazılan dosya bozulabilir: beş denemenin ikisinde dosya geçersiz JSON'a dönüştü ve sonraki bütün okumalar 500 döndü.
Uygulamanın birden fazla kopyası çalıştırıldığında kopyalar aynı belleği ya da aynı dosyayı güvenle paylaşamaz.

Sınırları

Veritabanı iş kuralını bilmez. "Stok eksiye düşemez" kuralı ancak bir CHECK constraint olarak tanımlanırsa uygulanır (Örnek 1).
Veritabanı DTO'nun yerini tutmaz. 399.999 fiyatı reddedilmedi, 400.00'e yuvarlanarak kaydedildi (Örnek 1); bu biçim kuralı Durak 07'deki DTO'da uygulanır.
Her sorgu ağ üzerinden ayrı bir sunucuya gider. Sorgu sayısı ve index kullanımı yanıt süresini belirler (Örnek 6).
Veritabanı ayrı bir sistemdir: bağlantı bilgisi yönetilmeli, şema değişiklikleri migration ile yapılmalıdır (Örnek 4 ve 5).

Veritabanı olmayanlar

Excel · Google Sheets

Veriyi tablo görünümünde tutar; ancak constraint, eşzamanlı yazma güvencesi ve uygulamanın gönderdiği sorgulara yanıt verme özelliği yoktur.

Cache · Redis

Veriyi hızlı okumak için bellekte tutar. Kayıtlar süresi dolduğunda ya da bellek dolduğunda silinebilir; asıl kayıt veritabanında bulunur.

JSON dosyası

Kalıcıdır, ancak eşzamanlı yazmaları yönetmez (2. adım). Tek bir kaydı bulmak için dosyanın tamamı okunur.

Aşağıdaki yedi örnek bu tanımı sırasıyla pekiştirir: tablonun yapısı ve constraint'ler, entity'den üretilen SQL ve kolon tiplerinin JavaScript karşılıkları, repository metotlarının ürettiği sorgular, bağlantının yapılandırılması, synchronize ve migration, index, son olarak alanlar için kolon tipinin seçildiği bir uygulama.

Örnek 1 · Tablo, satır, kolon, primary key, constraint

Tablo tanımındaki kurallar, uygulamayı atlayan yazmaları da reddeder.

products tablosunda üç satır vardır. Aşağıdaki INSERT ifadeleri DTO'dan geçmeyen bir yolu temsil eder: bir veri aktarım betiği, başka bir servis ya da bir veritabanı istemcisinde elle yazılan sorgu. Bir ifade seçildiğinde PostgreSQL 18'e gönderilir; yanıtı ve SQLSTATE hata kodu gösterilir. Tablo, Örnek 2'deki entity'den oluşturulmuştur.

product.entity.ts

Örnek 2 · Entity'den tabloya

Entity'deki her dekoratör, tablonun SQL tanımında bir parçaya karşılık gelir.

Uygulama synchronize: true ile başlatıldığında TypeORM, entity'yi okuyup tabloyu oluşturan SQL'i çalıştırır ve logging açıkken bu SQL'i konsola yazar. Soldaki entity'de bir satır seçildiğinde, sağdaki SQL'de o satırdan üretilen parça işaretlenir. TypeORM'un tek satır olarak yazdığı SQL, okunabilirlik için satırlara bölünmüştür.

product.entity.ts

TypeORM logu · CREATE TABLE

numeric kolonun JavaScript'teki tipi

unit_price alanının TypeScript tipi number'dır; PostgreSQL'in pg sürücüsü ise numeric değerini, hassasiyet kaybolmasın diye string olarak döndürür. Derleyici bu farkı göremez: tip, çalışma zamanındaki değeri garanti etmez (Durak 01). Aşağıda tabloya iki ürün eklenmiş, ardından GET /api/v1/products/2 isteği gönderilmiş ve iki ürünün fiyatı toplanmıştır.

product.entity.ts · products.service.ts

Örnek 3 · ORM ve Repository

Repository metodu parametreli SQL'e çevrilir; SQL yalnızca verilen koşulları içerir.

Tabloda beş ürün vardır; Webcam satışta değildir (is_active: false). Bir çağrı seçildiğinde TypeORM'un ürettiği SQL, parametreler ve sonuç gösterilir. SQL'deki $1, $2 yer tutuculardır; değerler sorgu metnine eklenmez, PARAMETERS listesiyle ayrı gönderilir. Çağrılar listedeki sırayla aynı tablo üzerinde çalıştırılmıştır. Turuncu kenarlı üç çağrı hatalı kullanımları, son iki çağrı ise string birleştirmenin güvenli karşılıklarını gösterir.

products.service.ts

Örnek 4 · Bağlantı ve yapılandırma

Bağlantı bilgisi ortam değişkenlerinden okunur; eksik değer uygulama başlarken bildirilmelidir.

Veritabanının adresi, kullanıcı adı ve parolası kodda değil, .env dosyasında tutulur. ConfigModule bu dosyayı okur; TypeOrmModule.forRootAsync değerleri ConfigService'ten alır. Bu örnekte uygulama dört farklı .env içeriğiyle başlatılmıştır. TypeOrmModule, bağlantı kurulamadığında varsayılan olarak 3 saniye arayla 9 kez dener. Zaman çizelgesi, gerçek başlangıç loglarındaki zaman damgalarından çizilmiştir.

.env · app.module.ts

Örnek 5 · synchronize ve migration

synchronize tabloyu entity'ye eşitler, ancak bunu hangi SQL ile yaptığını önceden göstermez.

Ürünlere sonradan eklenen description kolonu varchar(500)'dür ve iki üründe açıklama vardır. Açıklamalar uzadığı için entity'deki uzunluk 1000'e çıkarılır. Bu değişiklik dört yolla uygulanmıştır: synchronize: true ile, migration:generate ile üretilen dosya düzenlenmeden çalıştırılarak, aynı dosya düzenlenerek ve son olarak NOT NULL bir kolonda synchronize ile. Her adımda tablonun önceki ve sonraki hâli ölçülmüştür.

Örnek 6 · Index ve unique constraint

Unique index, e-postayı bütün tabloyu okumadan bulur ve tekrarını engeller.

Durak 07 ve 08'deki kayıt endpoint'i, e-postanın kayıtlı olup olmadığını findOneBy({ email }) ile kontrol eder. Yeni bir e-posta için bu sorgu sonuç bulamaz; index yoksa PostgreSQL bunu ancak tablonun tamamını okuyarak anlar. users tablosu 1.000, 100.000 ve 1.000.000 satırla doldurulmuş, sorgu EXPLAIN ANALYZE ile her biri için 7 kez çalıştırılmıştır. Süre, 7 ölçümün ortancasıdır; bir sayfa 8 KB'tır.

user.entity.ts · TypeORM logu

Aynı anda gelen iki kayıt isteği

Service'teki findOneBy kontrolü, iki istek aynı anda geldiğinde yetersiz kalır: iki istek de kontrolü kayıt yokken yapar ve ikisi de INSERT'e geçer. Aşağıda aynı e-postayla iki istek eşzamanlı gönderilmiş, deneme 10 kez tekrarlanmıştır. Tek tek gönderilen ikinci istek her üç adımda da service'teki kontrole takıldı ve 409 döndü.

auth.service.ts

Örnek 7 · Uygulama

Kolon tipi, alana yazılacak değerin türüne ve hassasiyetine göre seçilir.

Bu örnekte her alan için bir PostgreSQL kolon tipi seçilir. Ölçüt, alanın tuttuğu değerdir: sınırlı uzunlukta metin, kesin ondalık sayı, tam sayı, doğru/yanlış, saat dilimiyle zaman ya da tahmin edilemeyen benzersiz kimlik. Gerekçe seçimden sonra gösterilir.

Alan 1 / 10

Alan

Ölçüt: Alana hangi değer yazılır ve hangi hassasiyetle saklanmalıdır?

Kurallar

Veritabanıyla çalışırken uygulanan kurallar

Aşağıdaki yedi kural, verinin doğru tipte saklanmasını, sorguların istenmeyen satırlara ulaşmamasını ve şema değişikliklerinin veri kaybına yol açmamasını sağlar. Her kartta önce kurala aykırı kullanım gösterilir; Düzelt butonu kurala uygun hâlini gösterir. Yorum satırlarındaki sonuçlar NestJS 11, TypeORM 0.3 ve PostgreSQL 18 ile alınmıştır.

Para tutarlarını numeric ile saklayın

Önce

Kayan noktalı sayılar (real, double precision) ondalık değerleri ikilik sistemde yaklaşık olarak saklar; toplama ve çarpmada kuruş farkları oluşur. numeric(p,s), değeri yazıldığı ondalık hâliyle tutar.

@Column({ type: 'double precision' })
unit_price: number;
//! SELECT 0.1::float8 + 0.2::float8
//!   → 0.30000000000000004
//! SELECT 19.99::real * 3
//!   → 59.96999931335449

@Column({
  type: 'numeric', precision: 10, scale: 2,
})
unit_price: number;
// SELECT 0.1::numeric + 0.2::numeric → 0.3
// SELECT 19.99::numeric(10,2) * 3 → 59.97

numeric kolonu number'a çevirin

Önce

pg sürücüsü numeric değerini string olarak döndürür; TypeScript tipi number olduğu için derleyici uyarmaz. Toplama işlemi sayıları toplamak yerine metinleri birleştirir. Transformer, değeri okunurken sayıya çevirir.

@Column({
  type: 'numeric', precision: 10, scale: 2,
})
unit_price: number;
//! typeof product.unit_price → 'string'
//! reduce((sum, p) => sum + p.unit_price, 0)
//!   → "01299.902450.00"

@Column({
  type: 'numeric', precision: 10, scale: 2,
  transformer: new DecimalTransformer(),
})
unit_price: number;
// typeof product.unit_price → 'number'
// reduce((sum, p) => sum + p.unit_price, 0)
//   → 3749.9

where'e undefined değer geçmeyin

Önce

findOneBy, değeri undefined ya da null olan koşulu sorguya eklemez; koşulu kalmayan sorgu tablonun ilk satırını döndürür. Derleyici bu çağrıyı kabul eder. İsteğe bağlı değer, sorgudan önce kontrol edilir.

// query.id isteğe bağlı; istekte yok
return this.productRepo.findOneBy({
  id: query.id,
});
//! SELECT … FROM "products" LIMIT 1
//! → {"id":1,"name":"Kablosuz Kulaklık",…}

if (query.id === undefined) {
  throw new BadRequestException('id gerekli');
}
return this.productRepo.findOneBy({
  id: query.id,
});
// SQL'de WHERE "id" = $1 her zaman bulunur

Kullanıcı girdisini SQL metnine eklemeyin

Önce

Girdi sorgu metnine eklendiğinde, girdideki tırnak işareti sorgunun yapısını değiştirebilir (SQL injection). Repository metotları ve $1 yer tutucusu değeri sorgudan ayrı gönderir; değer yalnızca karşılaştırılan bir veri olarak kalır.

return this.productRepo.query(
  "SELECT id, name FROM products " +
    "WHERE name = '" + q + "'",
);
//! q = x' OR '1'='1
//! → 5 satır: tablonun tamamı

return this.productRepo.find({
  select: { id: true, name: true },
  where: { name: q },
});
// WHERE "name" = $1
// PARAMETERS: ["x' OR '1'='1"] → []

Bağlantı bilgisini getOrThrow ile okuyun

Önce

get(), eksik değişken için undefined döndürür; hata bağlantı sırasında sürücünün derinliklerinden gelir ve nedeni anlaşılmaz. getOrThrow(), eksik değişkeni adıyla ve uygulama başlarken bildirir.

password: config.get<string>('DB_PASSWORD'),
//! 9 deneme, 24,3 sn sonra çıkış kodu 1:
//! SASL: SCRAM-SERVER-FIRST-MESSAGE:
//!   client password must be a string

password: config.getOrThrow<string>(
  'DB_PASSWORD',
),
// 0,1 sn sonra çıkış kodu 1:
// TypeError: Configuration key
//   "DB_PASSWORD" does not exist

Şemayı migration ile değiştirin

Önce

synchronize: true, uygulama her başladığında tabloyu entity'ye eşitler ve çalıştırdığı SQL önceden incelenemez. Production'da synchronize kapatılır; değişiklik migration dosyasına yazılır, dosya okunur ve gerekirse düzeltilir.

TypeOrmModule.forRoot({
  synchronize: true,
});
//! length 500 → 1000:
//! DROP COLUMN "description"
//! → 2 açıklama NULL oldu

TypeOrmModule.forRoot({
  synchronize: false,
});
// migration (düzenlenmiş):
// ALTER COLUMN "description"
//   TYPE character varying(1000)
// → açıklamalar korundu

Benzersiz alana unique constraint ekleyin

Önce

Service'teki kontrol, aynı anda gelen iki isteği ayırt edemez. Benzersizliği yalnızca veritabanı garanti eder. Constraint'in hatası (23505) yakalanıp 409'a çevrilir; diğer hatalar yeniden fırlatılır (Durak 08, Kural 3).

@Column({ type: 'varchar', length: 254 })
email: string;
//! eşzamanlı 2 istek, 10 deneme:
//! 9 denemede 201 + 201,
//! tabloda aynı e-postayla 2 satır

@Column({
  type: 'varchar', length: 254, unique: true,
})
email: string;
// service: driverError.code === '23505'
//   → ConflictException
// 10 denemenin hepsinde bir 201, bir 409;
// tabloda 1 satır

Değerlendirme

Altı soru

Her cevaptan sonra doğru cevabın gerekçesi gösterilir.

Hazır olduğunuzda başlayabilirsiniz.