On yıllık kodu ajanla taşımak: Önce kalıbı sen kur, sonra köprü, en son test listesi

Neyi taşıdı?

Wes Bos’un kurs sitesi on yılı aşkın süredir Express üzerinde çalışıyordu. Pazarlama sayfaları, ücretsiz ve ücretli kurslar, yönetim paneli, istatistikler, kullanıcı rolleri hep aynı kod tabanındaydı. Sunucuda üretilen sayfalar Pug şablonlarıyla yazılmıştı. Hedef, web standartlarına dayanan Hono framework’üne ve JSX (TSX) şablonlarına geçmekti. Video izleme ve yönetim için yazılmış React uygulamalarına dokunulmadı.

Neden Hono? Express kendi req ve res nesneleriyle çalışıyor. Hono ise tarayıcıdaki fetch’ten tanıdığın standart Request ve Response nesnelerini kullanıyor. Bu sayede aynı kod Node.js, Bun, Deno ya da Cloudflare Workers’ta çalışabiliyor.

Adım 1: Kalıbı önce sen kur

Wes’in ilk dersi şu: Ajanı serbest bırakmadan önce birkaç örneği elle yaz. Ajan, kod tabanında gördüğü kalıbı kopyalar. Kalıp yoksa her dosyada başka bir şey uydurur.

Wes iki şey yaptı. Yeni yazdığı kodda istek bilgisini Express’in req nesnesine eklemek yerine Node’un AsyncLocalStorage özelliğini kullandı. Bu özellik, bir isteğe ait bilgiyi fonksiyondan fonksiyona elle taşımadan her yerden okumanı sağlıyor. Ayrıca gövde ve parametreleri kontrolcünün en başında çıkardı. Böylece iş mantığı Express’e özgü hiçbir şey bilmiyordu. Sonra Express için küçük bir TSX şablon motoru yazdı. Bir Pug dosyasının adını .tsx yapıp aynı verilerle çalıştırabiliyordu.

Adım 2: İki dünyayı bağlayan köprü

Asıl püf noktası bir köprü. Wes, Express isteğini standart bir Request nesnesine çeviren bir dönüştürücü yazdı. Böylece rotaları tek tek taşıyabildi. Taşınan rota yeni dünyada, taşınmayan eski dünyada çalıştı ve site hiç durmadı. Taşıma bitince köprü silindi.

Bu fikrin bir adı var: Martin Fowler’ın Strangler Fig dediği yöntem. Eski sistemi bir anda değiştirmek yerine yenisini parça parça etrafına kurup eskisini yavaş yavaş emekliye ayırıyorsun.

Adım 3: Plan ve test listesi

Kalıp ve köprü hazır olunca Wes ajana kod tabanını taratıp bir plan yazdırdı. Kimlik doğrulama, istek sınırlama, CSRF koruması ve JWT gibi hassas konular plana girdi. Bölüme göre planın oturması 20–30 tur sürdü.

Sonra ajana bir de elle test listesi çıkarttı. Yaklaşık 150 madde, hesap birleştirme ya da e-postayla gelen giriş bağlantısı gibi kimsenin aklına gelmeyecek uç durumlar dahil. Ajan asıl taşımayı üç-dört saatte bitirdi. İş mantığının çoğu aynı kaldı, değişen rota imzaları ve tiplerdi.

Adım 4: Elle dene, izleyerek yayına al

Birim testleri yetmedi. Wes listeyi elle tek tek geçti ve 20–30 hata buldu. Çoğu Pug’dan JSX’e geçişteki şablon hatalarıydı. Yayına bir pazartesi, hata izleme aracı açıkken aldı. İlk uyarılar hemen geldi ve ilerleme kaydıyla ilgili hatalar da böyle yakalandı. O sırada eski arayüzle video izleyen kullanıcılar vardı. Bu yüzden API’lerin dışarıya görünen şekli hiç değiştirilmedi.

Wes’in son uyarısı: Taşıma sırasında yeni özellik ekleme. Yatay bir geçiş olarak kalsın, yoksa iş bitmez.

Aynı mantığın çok daha büyük bir örneği için vinext yazımıza bakabilirsin: Cloudflare, Next.js’in testlerini tek tek taşıyarak onu Vite üzerinde yeniden yazdı. Ajanı testlerle sınırlamanın genel hâlini de ajanı raylarda tutmak yazısında anlattık.

Düşün

• Taşımak istediğin eski bir projede, ajana örnek olacak “doğru” ilk üç dosya hangileri olurdu?
• Eski ve yeni kodu aynı anda çalıştırabileceğin bir köprü kurabilir misin? Kuramıyorsan neden?

Kendi cümlelerimizle yazılmış bir özettir, çeviri değildir. Tüm kaynaklar yukarıda.