Hızlı tempolu yazılım geliştirme dünyasında bağlam genellikle ilk kaybedilen şeydir. Her gün kritik mimari seçimler yapıyoruz—bir veritabanı seçmek, bir çerçeve benimsemek veya bir API yapısı tasarlamak—ancak bu seçimleri neden yaptığımızı nadiren kaydediyoruz. Yeni bir ekip üyesi katıldığında veya altı ay sonra bir projeye geri döndüğünüzde, bu kararların arkasındaki orijinal niyet kaybolur. İşte Mimari Karar Kayıtlarının (ADR) devreye girdiği yer burasıdır.
ADRs, önemli mimari kararları belgelemenin hafif ve standartlaştırılmış bir yoludur. Kapsamlı tasarım belgeleri değildir; bunun yerine, bağlamı, yapılan kararı ve bu seçimin sonuçlarını yakalayan kısa, değiştirilemez (immutable) kayıtlardır. ADR'leri deponuza entegre ederek, sisteminizin evrimine denetlenebilir bir tarihçe oluşturur, tartışma yorgunluğunu azaltır ve gelecekteki bakımcılar için netlik sağlar.
Neden ADR Kullanılmalı?
ADR'lerin birincil faydası "karar borcunun" azaltılmasıdır. Dokümantasyon olmadan ekipler, aynı mimari soruları tekrar tekrar ele alarak tutarsız uygulamalara ve zaman kaybına yol açar. ADR'ler, geçmiş kararlar için tek bir doğruluk kaynağı sağlar. Bir ekip üyesi önceki bir kararı değiştirmek istiyorsa, önce ADR'ye atıfta bulunmalı, kısıtlamalarını kabul etmeli ve eski kararı geçersiz kılmak için yeni bir karar kaydı önermelidir. Bu, resmi değişiklik talep süreçlerinin yükü olmadan düşünceli bir değişiklik yönetimini teşvik eden doğal bir yönetim yapısı oluşturur.
Ayrıca, ADR'ler oryantasyon materyali olarak işlev görür. Yeni geliştiriciler, mevcut mimarinin arkasındaki mantığı anlamak için kararların sırasını okuyabilir ve bu da bir kara kutu olabilecek şeyi şeffaf bir sisteme dönüştürür.
ADR Yapısı
ADR'ler için tek bir zorunlu format olmasa da, yaygın olarak benimsenen bir yapı aşağıdaki bölümleri içerir:
- Başlık: Kararın kısa ve açık bir açıklaması.
- Durum: Önerilen, Kabul Edilen, Eski Teknolojiye Dönüştürülen (Deprecate) veya Geçersiz Kılınan.
- Bağlam: Sorun ifadesi ve kısıtlamalar. Bir karara yol açan güçler nelerdir?
- Karar: Yapacağımız değişiklik ve kararın detayları.
- Sonuçlar: Sonuçlanan bağlam, bunun şeyleri nasıl daha iyi veya daha kötü hale getirdiği ve gelecekte neden olabileceği sorunlar.
Deponuzdaki docs/adr/ klasöründe saklanan, Markdown'da yazılmış pratik bir ADR örneği aşağıdadır:
# 001 - Sipariş İşleme İçin Olay Tabanlı Mimariyi Benimseme
## Durum
Kabul Edildi
## Bağlam
Sipariş hacmimiz büyüdükçe, monolitik REST API'miz zirve yükleri sırasında bir darboğaza dönüştü. Ödeme ve envanter kontrollerinin senkron işlenmesi zaman aşımına neden oluyor. Yüksek eşzamanlılığı ele alabilecek ve servislerimizi ayrıştıracak bir çözüme ihtiyacımız var.
## Karar
Sipariş işleme akışını Kafka kullanarak olay tabanlı bir mimariye taşıyacağız. Bir `OrderCreated` olayı yayımlayacak ve ayrı tüketiciler ödeme doğrulamasını ve envanter rezervasyonunu ele alacaktır.
## Sonuçlar
**Pozitif:**
- Zirve yükleri sırasında ölçeklenebilirliğin iyileştirilmesi.
- Servislerin ayrıştırılması, bağımsız dağıtımı mümkün kılar.
**Negatif:**
- Kafka bakımı nedeniyle operasyonel karmaşıklığın artması.
- Veri tutarlılığı nihai tutarlıdır (eventually consistent), bu da tüketicilerde yeniden denemeleri ve idempotency'yi (tekrarlanabilirliği) ele almayı gerektirir.
Uygulama İçin En İyi Uygulamalar
ADR'lerinizin faydalı kalmasını sağlamak için bu en iyi uygulamaları izleyin:
- Değiştirilemez (immutable) tutun: Bir ADR kabul edildikten sonra düzenlemeyin. Bir karar değişirse, eski kararı geçersiz kılan yeni bir ADR oluşturun. Bu, tarihi korur.
- Kısa tutun: Bir ADR, iki dakikadan kısa sürede okunabilir olmalıdır. Çok uzun olursa, bu bir karar kaydı değil, bir tasarım belgesidir.
- Sürüm kontrolünde saklayın: ADR'leri Git deponuza yerleştirerek, kodla birlikte sürümleme sağlanır ve bir kararın kod değişikliklerine göre ne zaman alındığını görmeyi kolaylaştırır.
- Numaralı bir dizi kullanın: ADR'lerinizi numaralandırın (ör.
001-ilk-db-secimi.md,002-api-surumleme.md) ve net bir kronolojik sıra koruyun.
Sonuç
Mimari Karar Kayıtları, yüksek getiri sağlayan küçük bir yatırımdır. Gizli bilgiyi açık dokümantasyona dönüştürerek netlik ve hesap verebilirlik kültürünü teşvik eder. ADR'leri benimseyerek, ekibinizin bilgilendirilmiş kararlar almasını, gereksiz tartışmaları azaltmasını ve zamanla anlaşılması ve bakımı daha kolay yazılım oluşturmasını sağlarsınız. Küçük başlayın: Bir sonraki önemli mimari seçiminizi belgeleyin ve faydaların birikmesini izleyin.