Gerçek hayat için Pratik Açısal mimari

Çoğu Açısal mimari dersi teoriyi öğretir. Bu değil.

Burada gerçek sorunları tespit etmeyi, yerinde kararlar almayı ve ekip büyüdüğünde, ürün değiştiğinde ve zaman geçtikçe dayanıklı sistemler kurmayı öğrenirsiniz.

Yirmi modül. Uygulama odaklı. Dolgu yok.

---

INDEX — Gerçek hayat için Pratik Açısal mimari

---

Modül 0 — Sistem Tabanı

Nokta 0 bir içerik modülü değildir. Yol haritası boyunca kullanacağınız görme şeklidir.

Angular'daki belirli sorunlardan bahsetmeden önce bir soruyu yanıtlamanız gerekir:

Bilmediğiniz bir uygulamaya nasıl bakarsınız ve onun iyi mi yoksa kötü mü olduğuna nasıl karar verirsiniz?

Bunun için dört temel beceri vardır.

---

1. Bir uygulamayı koda dokunmadan analiz edin

Bir uygulamanın ilk okunması editörde değildir. Yapıdadır. Tek bir dosyayı açmadan önce bilgileri çıkarabilirsiniz:

• Klasörlere ne denir? İsimler ne yaptıklarını söylüyor mu?
• Her şeyden daha ağır olan shared klasörü var mı?
• Yapının kaç yuvalama seviyesi var?
• Modüllerin veya özelliklerin alan adları veya teknik adları var mı?
• Hizmetler nerede? Gevşek mi yoksa özelliklerin içinde mi?

Bu, uygulamayı yapan kişinin iş açısından mı yoksa teknik katmanlar açısından mı düşündüğü hakkında zaten çok şey söylüyor.

---

2. Mimariyi pratik bir şekilde gözden geçirin

İnceleme, kodu yukarıdan aşağıya okumak değildir. Kriterleri olan sorular soruyor:

• İş mantığı nerede yaşıyor?
• Her katmanda ne olduğunu kim bilebilir?
• Yeni bir özellik eklemek için kaç siteyi değiştirmeniz gerekiyor?
• Yanlış yöne giden bağımlılıklar mı var?

Kıdemli bir mimar en karmaşık bileşenle başlamaz. En yüksek risk noktalarından başlayın: paylaşılan hizmetler, küresel durum ve veri erişim katmanı.

---

3. Programlamadan önce sorunları tespit edin

Çoğu mimari hasar, alakasız görünen erken kararlarda meydana gelir:

• "Bunu şimdilik paylaşılan bir hizmete koyuyorum"
• "Ana bileşen bu durumu yönetir, sonra onu taşırız"
• "Her şey için NgRx kullanıyoruz, dolayısıyla tutarlı"

Bu kararların gerçek sonuçları aylar sonra ortaya çıkıyor. Mimari kriter, her kararın neyi satın aldığını ve ne tür bir borç doğurduğunu bilmektir.

---

4. Teoriyi gerçek kontrol listesine dönüştürün

Bu yol haritasında göreceğimiz her kavram (akıllı/aptal bileşenler, durum yerleştirme, tanrı hizmetleri vb.) gerçek kodu incelerken kendinize sorabileceğiniz bir soruyla bitmelidir:

• Bu bileşen verilerin nereden geldiğini biliyor mu?
• Bu hizmetin değişmesinin birden fazla nedeni var mı?
• Bu durum iki farklı yerde mi var?

Bir kavramı tekrar sorusuna dönüştüremiyorsanız, onu henüz içselleştirmemişsiniz demektir.

---

Modül 1 — Angular uygulamasını koda dokunmadan analiz etme

İlk mimari inceleme editör açılmadan önce gerçekleşir. Yalnızca klasör yapısından ve dosya adlarından zaten net kalite sinyalleri elde edebilirsiniz. Kıdemli bir mimarın bilinmeyen bir uygulamayla ilk 10 dakikada yapacağı şey budur.

Neden önemli?

• Mimari sorunları tespit etmek uzun zaman alırsa, bunları düzeltmenin maliyeti katlanarak artar.
• İlk günden itibaren kötü tasarlanmış bir yapı, aylar sonra takımı bloke eden teknik bir borca ​​dönüşür.
• Hızlı görsel muhakeme yeteneği geliştirmek, tek bir kod satırı yazmadan önce daha iyi kararlar vermenizi sağlar.

Adım 1 — Klasör yapısını harita olarak okuyun

Klasör yapısı ilk görünür mimari karardır. Size ekibin zihinsel dünyasını nasıl organize ettiğini anlatır: teknoloji açısından mı yoksa iş açısından mı düşünüyorlar?

Özellik nedir?

Bir özellik, eksiksiz bir iş işlevidir. Bir dosya türü değil. Teknik bir katman değil.

Bir e-ticaret uygulamasını düşünün. Özellikleri şunlardır:

• Ürün kataloğu
• Alışveriş sepeti
• Ödeme işlemi
• Kullanıcı profili
• Sipariş yönetimi

Bunların her biri kendi başına anlam taşıyan bir iş parçasıdır. Bir kullanıcı kataloğa girer, kataloğa göz atar, sepete ekler, ödeme yapar. Bunlar özellikler.

Model 1 — Teknik katmanlara göre organizasyon (büyük ölçekte sorunlu)

Düzgün göründüğü için hemen hemen herkes başladığında bunu yapar:

src/app/
  components/
    product-card.component.ts
    product-list.component.ts
    cart-item.component.ts
    checkout-form.component.ts
    user-profile.component.ts
  services/
    product.service.ts
    cart.service.ts
    checkout.service.ts
    user.service.ts
  models/
    product.model.ts
    cart.model.ts
    user.model.ts

Asıl sorun: ödeme akışını değiştirmeniz gerekiyor. Nelerin dahil olduğunu anlamak için üç farklı klasör arasında gezinirsiniz; components/ içinde bileşeni, services/ içinde hizmeti, models/ içinde modeli ararsınız. Belirli bir ödeme kanalı varsa bu, diğer özelliklerden gelen kanallarla karıştırılmış pipes/ konumundadır.

Tek bir özelliği değiştirmek için uygulamanın tamamında gezinebilirsiniz. Bu, yapıya göre birleşmedir. Ekip büyüdüğünde, farklı özellikler üzerinde çalışan iki kişi sürekli olarak aynı klasörlere dokunur → git'te çakışmalar olur, kimin neye sahip olduğunu bilmede zorluk yaşanır.

Model 2 — Özelliklere göre organizasyon (hangi ölçeklerde)

src/app/
  features/
    catalog/
      components/
        product-card.component.ts
        product-list.component.ts
      services/
        product.service.ts
      models/
        product.model.ts
      catalog.routes.ts
    cart/
      components/
        cart-item.component.ts
        cart-summary.component.ts
      services/
        cart.service.ts
      cart.routes.ts
    checkout/
      components/
        checkout-form.component.ts
        order-confirmation.component.ts
      services/
        checkout.service.ts
      checkout.routes.ts
  shared/
  core/

Bu neden işe yarıyor: Ödeme işlemine dokunduğunuzda ödeme işlemindeki her şey bir aradadır. Yeni bir geliştirici tam olarak nereye bakacağını bilir. Bir kişi bir özelliğin tamamına sahip olabilir. Yalnızca klasörünü silerek bir özelliğin tamamını silebilirsiniz. Git'in farklı özellikler arasındaki çatışmaları neredeyse tamamen ortadan kalkar.

Temel kural: Bir özelliği silerseniz, başka hiçbir şeye dokunmadan ilgili klasörün tamamını silebilir misiniz? Cevap evet ise özellik iyi yalıtılmıştır. Uygulama boyunca parça aramanız gerekiyorsa, öyle değil.

Adım 2 — İsimleri okuyun

İsimler belgelerdir. Kötü bir ad, amacı gizler ve kodu okuyan her kişiye bilişsel yük ekler.

shared/ — neleri içermeli ve neleri içermemelidir

shared/, birden fazla özelliğin kullandığı ve kendi iş mantığına sahip OLMAYAN şeyler içindir.

shared/'da doğru:

shared/
  components/
    button/
    modal/
    spinner/
    avatar/
  pipes/
    date-format.pipe.ts
    truncate.pipe.ts
  directives/
    click-outside.directive.ts
  validators/
    email-validator.ts

Bunlar yeniden kullanılabilir kullanıcı arayüzü parçaları veya saf yardımcı programlardır. İş hakkında hiçbir şey bilmiyorlar. ButtonComponent bunun bir ödeme düğmesi mi yoksa kullanıcı profili düğmesi mi olduğunu bilmiyor. Sadece nasıl düğme olunacağını biliyor.

shared/'da yanlış:

shared/
  services/
    cart.service.ts           ← lógica de negocio aquí
    user-auth.service.ts      ← pertenece a auth/core
    product-filter.service.ts ← pertenece a catalog
    report-generator.service.ts ← pertenece a reporting

shared/ içinde iş mantığına sahip hizmetler gördüğünüzde, bu, birisinin onları nereye koyacağını ve oraya koyacağını bilmediği anlamına gelir. Zamanla shared/ uygulamanın tamamını kapsayan bir hale gelir.

core/ — nedir ve ne değildir

core/ uygulamanın tamamına bir kez ihtiyaç duyan tekil altyapı içindir.

core/'da doğru:

core/
  services/
    auth.service.ts
    logger.service.ts
    error-handler.service.ts
  interceptors/
    auth.interceptor.ts
    error.interceptor.ts
  guards/
    auth.guard.ts
  models/
    user-session.model.ts

core/'da yanlış:

core/
  components/
    dashboard.component.ts  ← eso es una feature
    home.component.ts       ← igual
  services/
    product.service.ts      ← pertenece a catalog
    report-generator.service.ts ← pertenece a reporting

Bunlar bir kez başlatılan ve uygulamanın tamamını etkileyen şeylerdir. Kimlik doğrulama önleyicisi, uygulamanın tamamına ilişkin tüm HTTP isteklerini engeller; bu nedenle core/'da bulunur.

Belirsiz adlar — tehlike işaretleri

Belirsiz bir isim, ertelenmiş bir karardır. Birisi data.service.ts oluşturduğunda, hizmetin hangi verilerden bahsettiğine karar vermemiştir.

ne görüyorsun	Bu ne anlama gelebilir?
shared/ çok büyük	Başka hiçbir yere sığmayan her şey. Karışık bir çanta haline geliyor.
common/	shared/ ile aynı, ancak adı daha kötü. İçeriye ne gireceğine dair kriterler olmadan.
utils/ hizmetlerle birlikte	Yardımcı program olarak gizlenen iş mantığı. Ciddi kırmızı bayrak.
helpers/	utils/ ile aynı. İsim sorumluluk hakkında hiçbir şey söylemiyor.
Kökte components/	Etki alanına göre organizasyon yok. Tüm bileşenler bir arada.
core/ 40 dosyayla	Kötü tanımlanmış çekirdek. shared/ ikinci olarak kullanıldı.
app.service.ts	Büyümeyi bekleyen bir tanrı hizmeti. Maksimum alarm sinyali.
data.service.ts	Neye dair veriler? İsimden süresiz sorumluluk.
helper.service.ts	İlgisiz yöntemlerle bir hizmet haline gelir.
main.component.ts	"Ana" nedir? Gerçek sorumluluğu gizleyen genel ad.

Ad kuralı: Dosya adı size tam olarak ne yaptığını söylemiyorsa, dosya muhtemelen çok fazla şey yapıyordur veya konumu kötüdür.

Belirsiz isimler ve gizlediklerine dair somut örnekler:

• 800 satırlı utils/format.ts: tarih biçimlendirmesi + form doğrulama + API dönüşümünün karışımı.
• helper.service.ts: alakasız yöntemlerle tanrısal bir hizmet haline gelir.
• app.service.ts: Uygulamanın tamamına ilişkin sorumlulukları olan, uygulamanın tamamı olarak adlandırılan bir hizmet.

Adım 3 — Dosyaları açmadan sayın ve ölçün

Kodu okumadan önce şu gözlemleri doğrudan yapıdan yapabilirsiniz:

İşaret olarak bileşen boyutu

İmza	Bu neyi gösteriyor?
Tek bileşende +300-400 satır	Neredeyse her zaman çok fazla şey yapıyorsun. Bu mutlak bir kural değil ama araştırılmaya değer.
+10 giriş ve çıkış	Çok karmaşık API. Aday birkaç bileşene bölünecek.
Bileşendeki doğrudan HTTP çağrıları	Sunumu veri erişimiyle birleştirin. Hizmet katmanı eksik.
Özellik başına 1-2 bileşen	Muhtemelen çok fazla şey yapıyorlar. İç bölünme eksikliği.
+20 küresel sağlayıcı	Çok fazla durum ve merkezi mantık. Her şeyin küresel olması gerekmiyor.

**Küresel hizmetler — providedIn: 'root' tehlikesi

Küresel hizmet, herhangi bir özelliğin herhangi bir bileşeninin onu enjekte edip kullanabileceği anlamına gelir. Bu, bağımsız olması gereken özellikler arasında görünmez bağımlılıklar yaratır.

// Servicio que DEBERÍA ser local a la feature de catalog:
@Injectable({ providedIn: 'root' })  // ← señal de problema
export class ProductFilterService { ... }

// Ahora cualquier componente de cualquier feature puede usarlo.
// Si catalog cambia su lógica de filtrado, puede romper
// algo en una feature aparentemente no relacionada.

Adım 4 — app.module.ts veya app.config.ts: nelere dikkat edilmeli

Modülleri olan uygulamalarda (Angular < 17 veya eski)

@NgModule({
  imports: [
    BrowserModule,
    HttpClientModule,
    RouterModule,
    AuthModule,       // ← bien, infraestructura singleton

    ProductModule,    // ← señal de problema
    CartModule,       // ← señal de problema
    CheckoutModule,   // ← señal de problema
    UserModule,       // ← señal de problema
    DashboardModule,  // ← señal de problema
    // Si hay 15+ módulos de features aquí,
    // el lazy loading no está funcionando.
  ],
  providers: [
    ProductService,   // ← si hay 20+ providers aquí,
    CartService,      // hay demasiada centralización
    UserService,
    AuthService,
  ]
})

Özellik modülleri tembel olarak (talep üzerine) yüklenmeli, doğrudan kök modüle aktarılmamalıdır. Bunların hepsi buradaysa, kullanıcı bunlara hiç ihtiyaç duymasa bile başlangıçta hepsi yüklenir.

Bağımsız uygulamalarda (Angular 17+)

// app.config.ts
export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(routes, withLazyLoading()),   // ← correcto
    provideHttpClient(withInterceptors([authInterceptor])),
    provideAnimations(),

    ProductService,   // ← esto NO debería estar aquí
    CartService,      // ← pertenece a la feature de cart
  ]
}

Genel yapılandırma kuralı: Genel yapılandırma yalnızca uygulamanın tamamını etkileyen bir altyapıya sahip olmalıdır: geç yüklemeli yönlendirici, küresel önleyiciler, animasyonlar, altyapı tekli hizmetleri (kimlik doğrulama, günlükçü, hata işleyici) ile HttpClient. Genel yapılandırmada özellik hizmetleri görürseniz, birisi gerekliliği değil kolaylık sağlamak için işleri küresel olarak kaydediyor demektir.

Tam kontrol listesi — Angular uygulamasının ilk okunması

Yapı

• Yapı, özelliklere (iş alanı) göre mi yoksa teknik katmanlara göre mi organize ediliyor?
• Başka hiçbir şeye dokunmadan yalnızca klasörünü silerek bir özelliğin tamamını silebilir miyim?
• Özelliklerin ticari alan adları (checkout, catalog) veya teknik adları (list, form, detail) var mı?
• Belirsiz adlara sahip klasörler var mı: utils, helpers, common, misc, data?

shared/ ve core/

• shared/ yalnızca iş mantığı olmayan kullanıcı arayüzü bileşenlerini ve yardımcı programlarını mı içeriyor?
• core/ yalnızca tekil altyapı (durdurucular, korumalar, kimlik doğrulama hizmeti) içeriyor mu?
• shared/ içinde iş mantığına sahip hizmetler var mı?
• core/'nin özellik bileşenleri veya etki alanı hizmetleri var mı?

Hizmetler ve sağlayıcılar

• Ticari hizmetler özellikleriniz dahilinde mi yoksa genel olarak gevşek mi?
• 20'den fazla küresel sağlayıcı var mı?
• Kök modül veya app.config.ts özellik modüllerini doğrudan (tembellik yapmadan) içe aktarıyor mu?
• Bir özellik için yerel olması gereken providedIn: 'root' değerine sahip hizmetler var mı?

İsimler

• Dosya adları tam olarak ne işe yaradığını söylüyor mu?
• Adı uygulamanın herhangi bir bölümüne uygulanabilecek dosyalar var mı?
• app.service.ts, data.service.ts veya helper.service.ts adında bir dosya var mı?
• shared/ herhangi bir özellikten daha mı ağır?

Egzersiz yapmak

GitHub'da herkese açık herhangi bir Angular projesini arayın; bu sizin kendinize ait veya açık kaynaklı bir proje olabilir. Hiçbir dosyayı açmadan sadece klasör yapısına ve adlarına bakarak:

1. Hangi organizasyon modelini kullanıyorsunuz: özellikler mi yoksa teknik katmanlar mı?
2. Hangi isimler size şüphe veya şüphe uyandırıyor?
3. İş mantığının nerede olduğundan şüpheleniyorsunuz?
4. Sizce en fazla sorumluluk karışımına sahip klasör hangisidir?
5. Başka hiçbir şeye dokunmadan bir özelliği silebilir misiniz?

Oturumda gözlemlediklerinizi paylaşın, biz de kıdemli bir mimarın yapacağı gibi birlikte gözden geçirelim.

---

Bilgi istemi: projenizi 4 noktayla analiz edin

Bu istemi kopyalayın ve projenizin klasör ağacına ileterek herhangi bir AI (ChatGPT, Claude, Copilot) ile kullanın:

---

Sütun 1'in bu 4 maddesini uygulayarak proje mimarisini analiz edin ve bir rapor oluşturun.

NOKTA 1 — Klasör yapısı

apps/ ve libs/'yi analiz edin ve yanıtlayın:

• Organizasyon özelliklere (iş alanına) göre mi yoksa teknik katmanlara göre mi yapılıyor?
• Bir özelliğin yalnızca klasörünü silerek tamamını silebilir misiniz?
• Özelliklerin alan adları (checkout, catalog) veya teknik adları (list, form, detail) var mı?
• Belirsiz adlara sahip klasörler var mı: utils, helpers, common, misc, data?
• Bulduğunuz gerçek klasör ağacını gösterir.

NOKTA 2 — Dosya ve klasör adları

Tüm projeyi arayın ve listeleyin:

• Belirsiz adlara sahip dosyalar: data.service.ts, helper.service.ts, app.service.ts, main.component.ts, utils içinde hizmet bulunan dosyalar.
• shared/ dahilinde iş mantığına sahip hizmetler.
• core/ içindeki bileşenler veya etki alanı hizmetleri.
• shared/ herhangi bir özellikten daha mı ağır? Dosya sayısı.

3. NOKTA – Küresel hizmetler

Projenin tamamını arayın:

• providedIn: 'root' içeren tüm hizmetler — bunların hangileri olduğunu ve bir özelliğe göre yerel olup olmadıklarını listeler.
• Toplamda kaç tane global sağlayıcının bulunduğunu sayar.
• Özelliğiniz dahilinde olması gerektiğinde küresel olarak kayıtlı ticari hizmetleri tanımlar.
• libs/services/ bölgesinde açıkça belirli bir alana ait olan hizmetleri arayın.

NOKTA 4 — Genel yapılandırma (app.config.ts veya app.module.ts)

Her uygulamanın kök yapılandırma dosyasını bulun ve analiz edin:

• Küresel ölçekte kayıtlı olmaması gereken ne var?
• Özellik modülleri yavaş yüklemeyle mi yükleniyor yoksa doğrudan içe aktarılıyor mu?
• Global yapılandırmada iş hizmetleri var mı?
• Dünya çapında toplam kaç sağlayıcı kayıtlıdır?

RAPOR FORMATI

Her nokta için tam olarak bu yapıyı kullanın:

✅ İyi olan ne

(gerçek kod örnekleri içeren somut liste)

⚠️ Kontrol edilecek işaretler

(dosya yolunu ve bunun neden bir işaret olduğunu içeren somut liste)

❌ Sorunları temizleyin

(dosya yolu, sorun ve fiili etkiyi içeren somut liste)

Sonunda şunları içerir:

Yönetici Özeti

4 noktalı bir tablo, bir durum emojisi (✅ ⚠️ ❌) ve nokta başına bir sonuç satırı.

Öncelikli sonraki adımlar

Dokunulacak dosya veya klasörün tam yolu ile birlikte, etkiye göre sıralanmış maksimum 5 belirli eylemin listesi.

Doğrudan olun. Bir özelliğin veya teorinin ne olduğunu açıklamayın. Sadece bu spesifik projeyi analiz edin ve gerçek bulgular verin.