Mikroframework'ler Esnek ve Özelleştirilebilir Mimarilere Nasıl Olanak Verir

Mikroframeworkler Nedir ve Neden Önemlidir

Mikroframeworkler, temel işlevlere odaklanan hafif web çerçeveleridir: bir isteği almak, doğru handler’a yönlendirmek ve yanıt döndürmek. Tam yığın framework’lerin aksine, genellikle ihtiyacınız olabilecek her şeyi (admin panelleri, ORM/veritabanı katmanları, form oluşturucular, arka plan işleri, kimlik doğrulama akışları) paketlemezler. Bunun yerine küçük, stabil bir çekirdek sağlarlar ve ürününüzün gerçekten gerektirdiği şeyleri eklemenize izin verirler.

Mikroframeworkler vs. tam yığın framework’ler

Tam yığın bir framework, tamamen döşenmiş bir ev satın almaya benzer: tutarlı ve kullanışlıdır ama yeniden şekillendirmesi zordur. Bir mikroframework ise yapısal olarak sağlam ama boş bir alan gibidir: odaları, mobilyaları ve altyapıyı siz belirlersiniz.

Bu özgürlük, özel mimari dediğimiz şeyin özüdür—takımınızın ihtiyaçları, domain’iniz ve operasyonel kısıtlarınız etrafında şekillenen bir sistem tasarımı. Basitçe: bileşenleri (loglama, veritabanı erişimi, doğrulama, auth, arka plan işleme) siz seçersiniz ve nasıl bağlanacaklarına siz karar verirsiniz; önceden tanımlanmış “tek doğru yol”u kabul etmezsiniz.

Takımlar neden mikroframeworkleri seçer

Takımlar genellikle mikroframeworklere şu isteklerle yönelir:

• Ağır bir yığına bağlı kalmadan ilk endpoint’e hızlı ulaşmak
• Belirli kütüphaneleri benimseme (veya kaçınma) konusunda esneklik
• Serverless fonksiyonları, edge runtime’lar veya minimal containerlar gibi kısıt dostu dağıtımlar
• Kod tabanı büyüdükçe servisler veya modüller arasında net sınırlar

Bu makalede neler olacak (ve neler olmayacak)

Mikroframeworklerin modüler tasarımı nasıl desteklediğine odaklanacağız: yapı taşlarını birleştirmek, middleware kullanımı ve bağımlılık enjeksiyonu eklemek—projenizi bir bilim deneyi haline getirmeden.

Belirli framework’leri satır satır karşılaştırmayacağız veya mikroframeworklerin her zaman daha iyi olduğunu iddia etmeyeceğiz. Amaç, yapılandırmayı kasıtlı seçmenize yardımcı olmak ve gereksinimler değiştikçe güvenli biçimde evrilmesini sağlamak.

Temel Fikir: Yalnızca Gerekli Parçaları Birleştirin

Mikroframeworkler, uygulamanızı önceden inşa edilmiş bir ev değil, bir kit gibi ele aldığınızda daha iyi çalışır. Dayatmacı bir yığını kabul etmek yerine, küçük bir çekirdek ile başlayıp yetenekleri ancak karşılığını verdiğinde eklersiniz.

En küçük yararlı çekirdekle başlayın

Pratik bir “çekirdek” genellikle şunlardır:

• Routing: URL’leri handler’lara eşlemek
• İstek/yanıt işleme: girdiyi okumak ve çıktıyı döndürmek için tutarlı bir yol
• Hata yönetimi: hataları temiz yanıtlar haline getiren tek bir yer

Bu, çalışan bir API endpoint’i veya web sayfası göndermek için yeterlidir. Diğer her şey somut bir gerekçe olana kadar isteğe bağlıdır.

Özellikleri açık modüller olarak ekleyin

Kimlik doğrulama, doğrulama veya loglama gerektiğinde, bunları ayrı bileşenler olarak ekleyin—tercihen net arayüzlerin arkasında. Bu, mimarinizi anlaşılır tutar: her yeni parçanın “hangi problemi çözüyor?” ve “nereye takılıyor?” sorularına cevap vermesi gerekir.

“Sadece ihtiyacın olanı ekle” modül örnekleri:

• Gerçek kullanıcılar veya üçüncü taraf erişimi olduğunda Auth
• Girdiler hata veya destek maliyetine neden olduğunda Doğrulama
• Üretimde sorun gidermek için gerekli olduğunda Loglama/metric

Erken kararları geri alınabilir tutun

Başlangıçta sizi sıkıştırmayacak çözümleri seçin. Derin framework sihrinden ziyade ince sarmalayıcılar ve konfigürasyon tercih edin. Bir modülü iş mantığını yeniden yazmadan değiştirebiliyorsanız doğru yapıyorsunuz demektir.

Mimari seçimler için basit bir tamamlanma tanımı: takım her modülün amacını açıklayabiliyor, bir iki günde değiştirebiliyor ve bağımsız test edebiliyor olmalı.

Karıştırıp Eşleştirebileceğiniz Mimari Yapı Taşları

Mikroframeworkler tasarım gereği küçük kalır; bu da uygulamanızın “organlarını” seçmenize izin verir. Bu, özel mimariyi pratik kılan şeydir: minimal başlayıp gerçek bir ihtiyaç ortaya çıktıkça parçalar eklersiniz.

İstek işleme: router, handler’lar, middleware

Çoğu mikroframework tabanlı uygulama, URL’leri controller’lara (veya daha basit request handler’lara) eşleyen bir router ile başlar. Controller’lar özelliklere (faturalandırma, hesaplar) ya da arayüze (web vs. API) göre düzenlenebilir; bu, kodu nasıl korumak istediğinize bağlıdır.

Middleware tipik olarak istek/yanıt akışını sarar ve çapraz-kesit endişeleri için en iyi yerdir:

• Kimlik doğrulama ve yetkilendirme
• Hız sınırlama
• Önbellekleme
• Metrikler, loglama ve istek izleme

Middleware bileşebilir olduğu için bunu global (her şey loglanmalı) veya belirli rotalara (admin endpoint’leri daha sıkı auth gerektirir) uygulayabilirsiniz.

Veri erişimi: doğru soyutlama seviyesini seçin

Mikroframeworkler nadiren bir veri katmanı dayatır, bu yüzden takımınıza ve iş yükünüze uygun bir şey seçebilirsiniz:

• Üretkenlik ve tutarlı modelleme istiyorsanız bir ORM
• Her şeyi el ile yazmadan daha sıkı kontrol için bir sorgu oluşturucu
• Performans hassasiyeti veya karmaşık raporlama için ham SQL

İyi bir desen, veri erişimini bir repository veya servis katmanının arkasına koymaktır; böylece araç değiştirme handler’lara yayılmaz.

İsteğe bağlı modüller: arka plan işleri ve kuyruklar

Her ürün ilk günden itibaren asenkron işlem gerektirmez. Gerektiğinde, bir job runner ve kuyruk ekleyin (e‑posta gönderimi, video işleme, webhook’lar). Arka plan işleri, iş mantığınıza HTTP katmanından ayrı bir “giriş noktası” gibi davranmalı; kuralları çoğaltmak yerine aynı servisleri paylaşmalıdır.

Çapraz-Kesit Endişeler İçin Omurga: Middleware

Middleware, mikroframeworklerin en büyük verimliliği sağladığı yerdir: tüm isteklerin alması gereken işleri her route handler’ı şişirmeden yapmanızı sağlar. Amaç basit: handler’ları iş mantığına odaklı tutmak, tesisatla ilgili işleri middleware’e bırakmak.

Paylaşılan işleri yukarı taşıyarak handler’ları küçültün

Her endpoint’te aynı kontrolleri ve başlıkları tekrarlamak yerine, bir kez middleware ekleyin. Temiz bir handler şu şekilde görünmelidir: girdiyi ayrıştır, bir servisi çağır, yanıtı döndür. Diğer her şey—auth, loglama, doğrulama varsayılanları, yanıt biçimlendirme—önce veya sonra gerçekleşebilir.

Tipik middleware sırası (ve neden önemli olduğu)

Sıra davranıştır. Yaygın ve okunabilir bir dizi:

1. Request ID + temel loglama: korelasyonu erken oluşturun ki her log satırı aynı isteğe ait olsun.
2. Hata yönetimi / recovery: geri kalanını sarın ki istisnalar tutarlı hata yanıtlarına dönüşsün.
3. Güvenlik ve HTTP başlıkları: CORS, hız sınırı, auth/session ayrıştırma—gerçek işe başlamadan önce.
4. Body parsing + girdi normalizasyonu: handler’ların öngörülebilir veri almasını sağlayın.
5. Sıkıştırma: nihai yanıt gövdesini sıkıştırabilmesi için sona yakın.

Sıkıştırma çok erken çalışırsa hataları kaçırabilir; hata yönetimi çok geç çalışırsa stack trace sızdırabilir veya tutarsız formatlar dönebilirsiniz.

Hemen kullanacağınız pratik örnekler

• Request ID’ler: X-Request-Id başlığı ekleyin ve bunu loglara dahil edin.
• Hata yönetimi: istisnaları stabil bir JSON şekline eşleyin ({ error, message, requestId }).
• CORS: izin verilen origin’leri ve başlıkları merkezi olarak zorunlu kılın.
• Sıkıştırma: JSON ağırlıklı API’lerde yük boyutlarını azaltın.

“Middleware spaghetti”den kaçının

Middleware’i amaçlarına göre gruplayın (gözlemlenebilirlik, güvenlik, ayrıştırma, yanıt şekillendirme) ve doğru kapsamda uygulayın: gerçekten evrensel kurallar için global, belirli alanlar için route-group middleware. Her middleware’e net bir isim verin ve kurulumun yakınında beklenen sırayı kısa bir yorumla belgeleyin ki gelecekteki değişiklikler sessizce davranışı bozmasın.

IoC ve DI: Karmaşıklık Olmadan

Mikroframework size ince bir “istek girer, yanıt çıkar” çekirdeği sağlar. Geri kalan her şey—veritabanı erişimi, önbellek, e‑posta, üçüncü taraf API’ler—değiştirilebilir olmalı. İşte burada Inversion of Control (IoC) ve Dependency Injection (DI) devreye girer, kod tabanınızı bir bilim deneyi haline getirmeden.

IoC basitçe: kodunuzun “alışverişe” gitmesine izin vermeyin

Bir özellik veritabanına ihtiyaç duyduğunda, onu doğrudan orada oluşturmak cazip gelebilir ("burada yeni veritabanı istemcisi"). Dezavantaj: her “alışverişe giden” yer o özel veritabanı istemcisine sıkı sıkıya bağlı olur.

IoC bunu tersine çevirir: özellik neye ihtiyaç duyduğunu söyler, uygulama kablajı onu verir. Özelliğiniz yeniden kullanılabilir ve değiştirmesi kolay olur.

DI: parçaları takmak, içlerine sabitlemek yerine

Dependency Injection, bağımlılıkları içeride yaratmak yerine dışarıdan geçirmek demektir. Bir mikroframework kurulumunda bu genellikle başlatmada yapılır:

• gerçek bileşenleri oluşturun (veritabanı, HTTP istemcisi, logger)
• bunları route handler’lara/servislere verin
• bu kablolamayı tek öngörülebilir yerde tutun

Büyük bir DI container’a ihtiyaç yoktur. Basit bir kural: bağımlılıkları bir yerde oluşturun ve aşağı doğru geçirin.

Pratik yaklaşım: depolama ve API etrafında arayüzler + adaptörler

Bileşenleri değiştirilebilir kılmak için, "neye ihtiyacınız olduğunu" küçük bir arayüz olarak tanımlayın, sonra belirli araçlar için adaptörler yazın.

Örnek desen:

• UserRepository (arayüz): findById, create, list
• PostgresUserRepository (adaptör): Postgres kullanarak bu metodları uygular
• InMemoryUserRepository (adaptör): testler için aynı metodları uygular

İş mantığınız sadece UserRepository’yi bilir, Postgres’i bilmez. Depolamayı değiştirmek konfigürasyon seçimi olur, yeniden yazma değil.

Aynı fikir harici API’ler için de geçerlidir:

• PaymentsGateway arayüzü
• StripePaymentsGateway adaptörü
• Lokal geliştirme için FakePaymentsGateway

Konfigürasyonu merkezileştirin ve öngörülebilir tutun

Mikroframeworkler konfigürasyonun modüller arasında rastgele dağılmasını kolaylaştırır—buna direnin.

Sürdürülebilir bir desen:

• çevre değişkenlerini bir kere okuyan bir konfigürasyon modülü
• bağımlılık grafiğini inşa eden bir kompozisyon kökü (başlangıç dosyası)
• zaten kablolanmış servisleri alan rotalar

Bunu yapınca ana hedefi elde edersiniz: bileşenleri yeniden yazmadan takas etmek. Veritabanını değiştirmek, bir API istemcisini yenilemek veya bir kuyruk eklemek kablolama katmanında küçük bir değişiklik olur—geriye kalan kod stabil kalır.

Mikroframeworklerin Desteklediği Yaygın Desenler

Mikroframeworkler kodunuzu tek bir “doğru yol”a zorlamaz. Bunun yerine routing, istek/yanıt işleme ve birkaç uzatma noktası sağlar—böylece takım büyüklüğünüze, ürün olgunluğunuza ve değişim hızına uyan desenleri benimseyebilirsiniz.

Katmanlı (Controller / Service / Repository)

Bu, tanıdık “temiz ve basit” kuruludur: controller’lar HTTP kaygılarını ele alır, servisler iş kurallarını tutar ve repository’ler veritabanıyla konuşur.

Domaininiz açıksa, takımınız küçük‑orta büyüklükteyse ve kod koymak için öngörülebilir yerler istiyorsanız iyi uyar. Mikroframeworkler bunu doğal olarak destekler: rotalar controller’lara eşlenir, controller’lar servisleri çağırır ve repository’ler hafif manuel kompozisyonla kablolanır.

Altıgen (Ports-and-Adapters)

Altıgen mimari, sisteminizin bugün seçtiğiniz bileşenlerden (veritabanı, mesaj kuyruğu, üçüncü taraf API’ler, hatta UI) daha uzun ömürlü olmasını bekliyorsanız faydalıdır.

Mikroframeworkler burada güzel çalışır çünkü “adaptör” katmanı genellikle HTTP handler’larınız ve domain komutlarına ince bir çeviri adımıdır. Portlar domain’deki arayüzlerdir, adaptörler onları uygular (SQL, REST istemcileri, kuyruklar). Framework kenarda, merkezde değil.

Modüler Monolit (Özellik Modülleri ile Sınırlar)

Operasyonel yükü artırmadan mikroservis benzeri netlik istiyorsanız, modüler bir monolit güçlü bir seçenek olabilir. Tek deploy edilebilir uygulamayı korursunuz, ama onu özellik modüllerine (ör. Billing, Accounts, Notifications) açık public API’lerle bölersiniz.

Mikroframeworkler bunu kolaylaştırır çünkü her modül kendi rotalarını, bağımlılıklarını ve veri erişimini kaydedebilir; böylece sınırlar görünür olur ve kazara aşılması zorlaşır.

Minimum kısıt, maksimum niyet

Bu üç desenin her birinde fayda aynıdır: kuralları siz seçersiniz—klasör düzeni, bağımlılık yönü ve modül sınırları—mikroframework ise takılacak küçük, stabil bir yüzey sağlar.

Monolitten Mikroservislere: Doğru Şekli Seçmek

Mikroframeworkler küçük başlamayı ve esnek kalmayı kolaylaştırır, ama daha büyük soruyu cevaplamazlar: sisteminiz hangi “şekli” olmalı? Doğru seçim teknolojiye değil, takım büyüklüğüne, sürüm sıklığına ve koordinasyonun ne kadar acı verdiğine bağlıdır.

Kısa karşılaştırma: monolit, modüler monolit, mikroservisler

Bir monolit tek deploy edilebilir birim olarak gönderilir. Genellikle en hızlı yoludur: tek build, tek log kümesi, hata ayıklamak için tek yer.

Bir modüler monolit hâlâ tek deploy edilebilirdir, ama iç olarak net modüllere ayrılmıştır (paketler, bounded context’ler, özellik klasörleri). Kod tabanı büyüdüğünde sıklıkla en iyi "sonraki adım" budur—özellikle mikroframeworklerle, modülleri açık tutabilirsiniz.

Mikroservisler deployable birimleri birden çok servise böler. Bu ekipler arasındaki coupling’i azaltabilir ama operasyonel işi çarpar.

Servis sınırları: ne zaman bölünmeli (ve ne zaman bölünmemeli)

Bir sınırı şu durumlarda ayırın:

• Farklı ekiplerin bağımsız sürüm yapması gerekiyor.
• Bir modülün veri sahipliği ve kuralları gerçekten farklı (sadece farklı endpoint’ler değil).
• Ölçek gereksinimleri farklı (ör. yoğun arka plan işleme vs. hafif okuma).

Sadece klasör büyük diye bölmekten kaçının veya servislerin aynı veritabanı tablolarını paylaşacağı durumlarda bölmeyin. Bu, henüz kararlı bir sınır bulamadığınızın işaretidir.

API gateway ve paylaşılan kütüphaneler: artılar ve eksiler

Bir API gateway istemcileri basitleştirebilir (tek giriş noktası, merkezi auth/hız sınırlama). Dezavantaj: çok akıllı hale geldikçe darboğaz ve tek hata noktası olabilir.

Paylaşılan kütüphaneler geliştirmeyi hızlandırır (ortak doğrulama, loglama, SDK’lar) ama gizli coupling de yaratır. Birden fazla servisin aynı anda yükseltme zorunluluğu varsa, dağıtık bir monolit yaratırsınız.

Planlanması gereken operasyonel yük

Mikroservisler tekrar eden maliyetler getirir: daha fazla deploy pipeline’ı, versiyonlama, servis keşfi, izleme, izleme (tracing), olay müdahalesi ve on-call rotasyonları. Takımınız bu makinayı rahatça çalıştıramıyorsa, mikroframework bileşenleriyle inşa edilmiş modüler bir monolit genellikle daha güvenli mimaridir.

Pratik Bir Plan: Sürdürülebilir Bir Mikroframework Kurulumu

Mikroframework size özgürlük verir, ama sürdürülebilirlik tasarlamanız gereken bir şeydir. Amaç, “özel” parçaların kolay bulunur, kolay değiştirilir ve kötüye kullanılmasının zor olduğu bir yapı kurmaktır.

1) Temiz, sıradan bir proje yapısıyla başlayın

Bir dakikada açıklayabileceğiniz ve kod inceleme ile uygulayabileceğiniz bir yapı seçin. Pratik bir ayrım:

• app/ (kompozisyon kökü: modülleri kablolayan yer)
• modules/ (iş yetenekleri)
• transport/ (HTTP yönlendirme, istek/yanıt eşlemesi)
• shared/ (çapraz‑kesit yardımcıları: konfig, loglama, hata tipleri)
• tests/

İsimlendirmeyi tutarlı tutun: modül klasörleri isimleri isim (billing, users) ile ve giriş noktaları öngörülebilir (index, routes, service).

2) Modül sahipliğini ve public API’leri tanımlayın

Her modülü küçük bir ürün gibi ele alın:

• Küçük bir public yüzey açın (örn. modules/users/public.ts)
• İç yapıları private tutun (modules/users/internal/*)
• Sahipliği belgeleyin ("buraya kim onay verir") ve beklentileri (SLA, veri kuralları)

modules/orders/internal/db.ts gibi “reach-through” importlara izin vermeyin. Başka bir bölüm buna ihtiyaç duyuyorsa, onu public API’ye taşıyın.

3) Gün 1’den itibaren gözlemlenebilirlik ekleyin

Küçük servisler bile temel görünürlüğe ihtiyaç duyar:

• İstek ID’leri ile yapısal loglar
• Küçük bir metrik seti (gecikme, hata oranı, ana iş sayacı)
• Outbound çağrılar için tracing hook’ları (HTTP, DB, kuyruk)

Bunları shared/observability içinde tutun ki her route handler aynı kuralları kullansın.

4) Doğrulama ve hata yanıtlarını standardize edin

Hataları istemciler için öngörülebilir, insanlar için anlaşılır yapın. Tek bir hata şekli tanımlayın (örn. code, message, details, requestId) ve endpoint başına bir doğrulama şeması belirleyin. Dahili istisnalar→HTTP yanıtı eşlemesini merkezileştirin ki handler’lar iş mantığına odaklansın.

Koder.ai nerede devreye girer (hız istiyorsanız ama kilitlenmek istemiyorsanız)

Hedefiniz hızlı ilerlemek ama mikroframework tarzı mimariyi açık tutmaksa, Koder.ai iskelet oluşturma ve yineleme aracı olarak faydalı olabilir—iyi tasarımın yerine değil, destekçisi olarak. Sohbette modül sınırlarınızı, middleware yığınınızı ve hata formatınızı tarif ederek çalışan bir başlangıç uygulaması (ör. React frontend ile Go + PostgreSQL backend) oluşturup sonra kablolamayı kasıtlı biçimde düzeltebilirsiniz.

İki özellik özellikle özel mimari çalışmalarına iyi uyar:

• Planning mode: kod üretmeden önce yapı (modüller, ports/adapters, route grupları) üzerinde hizalanmanızı sağlar.
• Snapshots and rollback: DI eklemek, bir modül çıkarmak veya kuyruk eklemek gibi mimari değişiklikleri risksizce denemenize izin verir.

Koder.ai source code export desteklediği için, üretilen içeriğin sahipliği sizde kalır ve repoda el yapımı bir mikroframework projesi gibi evriltilebilir.

Özel Mimarileri Güvende Tutan Test Stratejileri

Mikroframework tabanlı sistemler “el yapımı” hissi verebilir; bu yüzden testler tek bir framework’ün kuralları değil, parçalar arasındaki dikişleri korumaya odaklanmalıdır. Amaç, değişiklikleri kapsamlı entegrasyon çalıştırmak zorunda kalmadan güven duymaktır.

Birim vs entegrasyon: neye öncelik verilmeli

İş kuralları için (doğrulama, fiyatlama, izin mantığı) hızlı birim testlerine başlayın—bunlar hızlıdır ve hatayı net gösterir. Sonra, kablolamayı test eden az sayıda yüksek katma değer entegrasyon testi ekleyin: routing → middleware → handler → persistence sınırı. Bu, bileşenler birleştiğinde ortaya çıkan ince hataları yakalar.

Middleware ve handler’ları etkili test etme

Middleware genelde çapraz‑kesit davranışları saklar (auth, loglama, hız limiti). Bunu bir pipeline gibi test edin:

• Minimal bir istek bağlamı oluşturun.
• Middleware’i, aldığı şeyi kaydeden bir “next handler” ile çalıştırın.
• Hem yan etkileri (ör. eklenen başlıklar) hem de kontrol akışını (eksik auth’ta isteğin engellenmesi) assert edin.

Handler’lar için, iç fonksiyon çağrıları yerine halka açık HTTP şekli (status kodları, başlıklar, yanıt gövdesi) test edilmeli. Bu, içler değişse bile testlerin stabil kalmasını sağlar.

Harici servisleri DI veya fake’lerle izole etme

Gerçek bağımlılıkları fake’lerle değiştirmek için DI kullanın veya yapıcı parametreler kullanın:

• Ağ çağrılarını önlemek için sahte e‑posta/ödeme istemcileri
• Birim testler için bellek içi repository’ler
• Birkaç entegrasyon testi için lokal veritabanı konteyneri

Ekip büyüdüğünde kontrat testleri

Birden fazla ekip veya servis bir API’ye güveniyorsa, istek/yanıt beklentilerini sabitleyen kontrat testleri ekleyin. Sağlayıcı tarafında kontrat testleri, tüketicileri kazara bozmamanızı garanti eder, framework ve iç modüller evrilse bile.

Dikkat Edilmesi Gereken Ödünler ve Tuzaklar

Mikroframeworkler özgürlük verir, ama özgürlük otomatik olarak açıklık sağlamaz. Ana riskler genellikle ekip büyüdüğünde, kod tabanı genişlediğinde ve “geçici” kararlar kalıcı hale geldiğinde ortaya çıkar.

Esneklik tutarsızlığa dönüşebilir

Daha az yerleşik kural olduğunda, iki ekip aynı özelliği iki farklı tarzda yazabilir (routing, hata yönetimi, yanıt formatı, loglama). Bu tutarsızlık incelemeleri yavaşlatır ve işe alım sürecini zorlaştırır.

Basit bir koruyucu: kısa bir “servis şablonu” dokümanı yazın (proje yapısı, isimlendirme, hata formatı, log alanları) ve bunu bir başlangıç deposu ile birkaç lint kuralı aracılığıyla zorlayın.

Gizli bağlılıklar ve shared-utils yayılması

Projeler temiz başlar sonra utils/ klasörü sessizce ikinci bir framework’e dönüşebilir. Modüller yardımcılar, sabitler ve global durum paylaştıkça sınırlar bulanıklaşır ve değişiklikler sürpriz kırılmalara yol açar.

Açık paylaşılan paketleri tercih edin ve sürümlendirin; paylaşımı sınırlı tutun: tipler, arayüzler ve iyi test edilmiş primitivler. Bir yardımcı iş kurallarına bağımlıysa, büyük olasılıkla domain modülünde olmalıdır, utils/ içinde değil.

Kendi kimlik doğrulamanızı ve doğrulamanızı kurarken güvenlik açıkları

Auth, yetkilendirme, girdi doğrulama ve hız sınırlamayı elle bağlarken bir rotayı atlamanız, bir middleware’i unutmamanız veya sadece “mutlu yol” girdilerini doğrulamanız kolaydır.

Güvenlik varsayılanlarını merkezileştirin: güvenli başlıklar, tutarlı auth kontrolleri ve uçta doğrulama. Korunan endpoint’lerin gerçekten korunup korunmadığını doğrulayan testler ekleyin.

Middleware zincirleri performansa zarar verebilir

Planlanmamış middleware katmanları ek yük getirir—özellikle birden fazla middleware gövdeleri parse ediyor, depolamaya erişiyor veya log serileştiriyorsa.

Middleware’i küçük ve ölçülebilir tutun. Standart sırayı belgeleyin ve yeni middleware’i maliyet açısından gözden geçirin. Şişkinlikten şüphelenirseniz istekleri profil çıkarın ve gereksiz adımları kaldırın.

Mimari Seçmek İçin Basit Bir Karar Rehberi

Mikroframeworkler size seçenekler sunar—ancak seçeneklerin bir karar süreci olmalı. Amaç, ekibinizin sorunsuzca kurup işletip değiştirebileceği bir şekil seçmektir, “en iyi” mimariyi bulmak değil.

Adım 1: Hızlı bir kontrol listesi çalıştırın

Monolit veya mikroservis seçmeden önce şunlara cevap verin:

• Takım büyüklüğü ve yetenekleri: Birden fazla deploy edilebilir hizmeti (on-call, CI/CD, gözlemlenebilirlik) gerçekçi şekilde destekleyebilir misiniz, yoksa tek, daha basit bir runtime mı tercih etmelisiniz?
• Zaman baskıları: Hız en önemliyse, daha az hareketli parça ile başlayın ve bölmeyi erteleyin.
• Uyumluluk ve güvenlik gereksinimleri: Denetim, veri konumu ve erişim kontrolleri genellikle performanstan daha fazla yapı gerektirir.

Emin değilseniz, mikroframework ile inşa edilmiş modüler bir monolit ile başlayın. Bu, sınırları açık tutarken göndermeyi kolay kılar.

Adım 2: Erken kuralları seçin (ve yazılı hale getirin)

Mikroframeworkler sizin için tutarlılığı zorlamaz, bu yüzden baştan kuralları seçin:

• Routing stili (RESTful kaynaklar vs. action route’lar)
• Klasör düzeni (özellik bazlı vs. teknik katman bazlı)
• Tutarlı bir hata formatı (istemcilerin hataları güvenilir şekilde ele alabilmesi için)

Bir sayfalık "service contract" dokümanı /docs içinde çoğunlukla yeterlidir.

Adım 3: Olmazsa olmaz modüllerini belirle

Her yerde ihtiyaç duyacağınız çapraz‑kesit parçalarla başlayın:

• Kimlik doğrulama/yetkilendirme
• Loglama ve istek izleme
• Girdi doğrulama ve hata yönetimi

Bunları paylaşılan modüller olarak ele alın, kopyala‑yapıştır snippet’ler olarak değil.

Adım 4: Üç ayda bir yeniden değerlendirin

Mimari gereksinimlere göre değişmelidir. Her çeyrekte, deploy’ların nerede yavaşladığını, hangi parçaların farklı ölçeklendiğini ve en çok neyin kırıldığını gözden geçirin. Bir alan darboğaz haline geldiyse, bir sonraki ayırma adayı odur—tüm sistemi bölmek değil.

Örnek Evrim: Özel Bir Mimari Nasıl Büyür

Bir mikroframework kurulumu nadiren baştan tam tasarlanmış olur. Çoğunlukla tek bir API, tek bir takım ve sıkı bir teslim tarihi ile başlar. Değer, ürün büyüdükçe ortaya çıkar: yeni özellikler gelir, daha fazla kişi koda dokunur ve mimari esnemeli ama kopmamalıdır.

Aşama 1: Birkaç rota ile tek API

Minimal servise başlarsınız: routing, istek ayrıştırma ve bir veritabanı adaptörü. Çoğu mantık endpoint’lere yakın durur çünkü gönderme hızı önemlidir.

Aşama 2: Özellikler modüllere dönüşür

Auth, ödemeler, bildirimler ve raporlama ekledikçe bunları modüllere ayırırsınız (klasörler veya paketler) ve net public arayüzler sunarsınız. Her modül kendi modellerinin, iş kurallarının ve veri erişiminin sahibi olur, sadece gerekeni dışarı açar.

Aşama 3: Çapraz‑kesit endişeler middleware’e taşınır

Loglama, auth kontrolleri, hız sınırlama ve istek doğrulama middleware’e taşınır ki her endpoint tutarlı davransın. Sıra önemli olduğundan bunu belgelemelisiniz.

Büyümenin Öngörülebilir Kalması İçin Neyi Belgelemelisiniz

Belgeleyin:

• Modül sınırları: her modülün neye sahip olduğu ve neleri değiştirmemesi gerektiği
• Middleware sırası: ne önce çalışır, ne sonra ve neden
• SLA/beklentiler: gecikme hedefleri, hata bütçeleri ve bağımlılık sözleşmeleri (ilk başta gayri resmi olsa bile)

Yeniden faktörleme veya servis ayırma zamanı olduğuna dair sinyaller

Modüller çok fazla iç paylaşmaya başladığında, build süreleri belirgin şekilde yavaşladığında veya "küçük bir değişiklik" için birden fazla modülde düzenleme yapmak gerektiğinde refaktörleyin.

Takımları paylaşılan deploy’lar yüzünden bloklanıyorsa, farklı parçaların farklı ölçek gereksinimleri varsa veya bir entegrasyon sınırı zaten ayrı bir ürün gibi davranıyorsa, servisleri ayırmayı düşünün.

Sonuç ve Sonraki Adımlar

Mikroframeworkler, uygulamayı dayatılmış bir yığın etrafında şekillendirmek yerine domain’iniz etrafında şekillendirmek istediğinizde iyi çalışır. Açıklıkı konforun önüne koyan takımlar için özellikle uygundur: birkaç ana yapı taşını seçip korumayı kabul edersiniz, karşılığında kod tabanı gereksinimler değiştikçe anlaşılır kalır.

Sizi yolda tutacak temel çıkarımlar

Esnekliğiniz ancak onu birkaç alışkanlıkla korursanız işe yarar:

• Sınırlar önce: neyin birlikte olması gerektiğine (modüller/servisler) ve neyin sızmaması gerektiğine karar verin.
• Modüller sihir yerine: açık sorumlulukları olan küçük bileşenleri tercih edin, minimal paylaşılan durumla.
• Tutarlılık yaratıcılıktan daha önemlidir: istek/yanıt şekilleri, hata yönetimi, log alanları ve konfigürasyon kalıplarında standartlaşın.
• Testler güvenlik ağıdır: mimariyi özelleştirdikten sonra refaktörleri güvenli ve entegrasyonları öngörülebilir kılan testlerdir.

Bu hafta yapabileceğiniz sonraki adımlar

İki hafif belgeyle başlayın:

1. Modül haritası taslağı: temel modüllerinizi, public arayüzlerini ve aralarındaki izin verilen bağımlılıkları listeleyin.
2. Middleware yığını taslağı: her middleware’in sıra ve amacını yazın (auth, doğrulama, hız sınırlama, tracing, hata yönetimi) ve isteğe hangi veriyi ekleyebileceğini belirtin.

Son olarak, kararlarınızı aldıkça bunları belgeleyin—kısa notlar bile yardımcı olur. Repoda bir “Architecture Decisions” sayfası tutun ve periyodik olarak gözden geçirin ki dünkü kestirme yollar bugünün kısıtlarına dönüşmesin.