Praktyczna architektura kątowa do prawdziwego życia

Większość kursów architektury Angular uczy teorii. Nie ten.

Tutaj uczysz się wykrywać rzeczywiste problemy, podejmować umiejscowione decyzje i budować systemy, które przetrwają wraz z rozwojem zespołu, zmianami produktu i upływem czasu.

Dwadzieścia modułów. Zorientowany na praktykę. Brak wyściółki.

---

INDEX — Praktyczna architektura Angular w prawdziwym życiu

---

Moduł 0 — Baza systemu

Punkt 0 nie jest modułem treści. Jest to sposób widzenia, który będziesz stosować w całym planie działania.

Zanim zaczniesz mówić o konkretnych problemach w Angularze, musisz odpowiedzieć sobie na pytanie:

Jak spojrzeć na aplikację, której nie znasz i ocenić, czy jest dobra, czy zła?

Służą do tego cztery podstawowe umiejętności.

---

1. Analizuj aplikację bez dotykania kodu

Pierwszego czytania aplikacji nie ma w edytorze. To jest w strukturze. Przed otwarciem pojedynczego pliku możesz wyodrębnić informacje:

• Jak nazywają się te foldery? Czy nazwy mówią, co robią?
• Czy istnieje folder shared, który waży więcej niż wszystko inne?
• Ile poziomów zagnieżdżenia ma konstrukcja?
• Czy moduły lub funkcje mają nazwy domenowe lub techniczne?
• Gdzie są służby? Luźno czy w ramach funkcji?

To już wiele mówi o tym, czy twórca aplikacji myślał w kategoriach biznesowych, czy technicznych.

---

2. Przejrzyj architekturę w praktyczny sposób

Przeglądanie nie polega na czytaniu kodu od góry do dołu. Polega na zadawaniu pytań według kryteriów:

• Gdzie mieszka logika biznesowa?
• Kto wie, co jest w każdej warstwie?
• Ile witryn musisz zmienić, aby dodać nową funkcję?
• Czy istnieją zależności zmierzające w złym kierunku?

Starszy architekt nie zaczyna od najbardziej złożonego elementu. Zacznij od punktów najwyższego ryzyka: usług wspólnych, stanu globalnego i warstwy dostępu do danych.

---

3. Wykryj problemy przed programowaniem

Większość uszkodzeń architektonicznych ma miejsce we wczesnych decyzjach, które wydają się nieistotne:

• „Na razie umieszczam to w usłudze udostępnionej”
• „Komponent nadrzędny obsługuje ten stan, następnie go przenosimy”
• „Do wszystkiego używamy NgRx, więc jest to spójne”

Decyzje te mają realne konsekwencje kilka miesięcy później. Kryterium architektonicznym jest wiedzieć, co kupuje każda decyzja i jakie zadłużenie zaciąga.

---

4. Zamień teorię na rzeczywistą listę kontrolną

Każda koncepcja, którą zobaczymy w tym planie działania — inteligentne/głupie komponenty, rozmieszczenie stanów, usługi boskie itp. — musi kończyć się pytaniem, które możesz sobie zadać podczas przeglądania prawdziwego kodu:

• Czy ten komponent wie, skąd pochodzą dane?
• Czy ta usługa ma więcej niż jeden powód do zmiany?
• Czy ten stan występuje w dwóch różnych miejscach?

Jeśli nie możesz zamienić koncepcji w pytanie kontrolne, oznacza to, że jeszcze jej nie zinternalizowałeś.

---

Moduł 1 — Jak analizować aplikację Angular bez dotykania kodu

Pierwszy przegląd architektoniczny następuje przed otwarciem edytora. Już na podstawie struktury folderów i nazw plików można wydobyć wyraźne sygnały jakości. Tak zrobiłby starszy architekt przez pierwsze 10 minut z nieznaną aplikacją.

Dlaczego to ma znaczenie?

• Jeśli wykrycie problemów architektonicznych zajmuje dużo czasu, koszt ich usunięcia rośnie wykładniczo.
• Źle zaprojektowana konstrukcja od pierwszego dnia staje się długiem technicznym, który blokuje zespół kilka miesięcy później.
• Opracowanie szybkiej oceny wizualnej pozwala podejmować lepsze decyzje przed napisaniem choćby jednej linii kodu.

Krok 1 — Przeczytaj strukturę folderów w formie mapy

Struktura folderów jest pierwszą widoczną decyzją architektoniczną. Mówi ci, jak zespół zorganizował swój świat mentalny: czy myśli w kategoriach technologii, czy biznesu?

Co to jest funkcja?

Funkcja to pełna funkcjonalność biznesowa. To nie jest typ pliku. Nie warstwa techniczna.

Pomyśl o aplikacji e-commerce. Funkcje to:

• Katalog produktów
• Koszyk
• Proces realizacji transakcji
• Profil użytkownika
• Zarządzanie zamówieniami

Każdy z nich jest biznesem, który ma sens sam w sobie. Użytkownik wchodzi, przegląda katalog, dodaje do koszyka, dokonuje kasy. To są cechy.

Model 1 – Organizacja według warstw technicznych (problematyczny w skali)

Prawie wszyscy tak robią, kiedy zaczynają, ponieważ wydaje się to schludne:

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

Prawdziwy problem: musisz zmodyfikować przepływ transakcji. Aby zrozumieć, o co chodzi, poruszasz się pomiędzy trzema różnymi folderami — szukasz komponentu w components/, usługi w services/, modelu w models/. Jeśli istnieje konkretna rura kasowa, jest ona w pipes/ zmieszana z rurami z innych obiektów.

Aby zmienić pojedynczą funkcję, poruszasz się po całej aplikacji. To łączenie według struktury. Kiedy zespół się powiększa, dwie osoby pracujące nad różnymi funkcjami stale dotykają tych samych folderów → konflikty w git, trudności w ustaleniu, kto jest właścicielem czego.

Model 2 — Organizacja według cech (w jakiej skali)

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/

Dlaczego to działa: gdy klikniesz przycisk „Zapłać”, wszystko w kasie jest razem. Nowy programista wie dokładnie, gdzie szukać. Jedna osoba może posiadać całą funkcję. Możesz usunąć cały obiekt, usuwając tylko jego folder. Konflikty Git pomiędzy różnymi funkcjami prawie całkowicie znikają.

Kluczowa zasada: jeśli usuniesz obiekt, czy możesz usunąć cały jego folder, nie dotykając niczego innego? Jeśli odpowiedź brzmi „tak”, funkcja jest dobrze izolowana. Jeśli musisz szukać elementów w całej aplikacji, tak nie jest.

Krok 2 — Przeczytaj nazwiska

Nazwy są dokumentacją. Zła nazwa ukrywa zamiary i zwiększa obciążenie poznawcze każdej osoby czytającej kod.

shared/ — co powinien zawierać, a czego nie

shared/ dotyczy rzeczy, które korzystają z wielu funkcji i które NIE mają własnej logiki biznesowej.

Popraw w shared/:

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

Są to elementy interfejsu użytkownika wielokrotnego użytku lub czyste narzędzia. Nie mają pojęcia o biznesie. ButtonComponent nie wie, czy jest to przycisk kasy, czy profilu użytkownika. On wie tylko, jak być guzikiem.

Niepoprawne w shared/:

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

Kiedy widzisz usługi z logiką biznesową wewnątrz shared/, oznacza to, że ktoś nie wiedział, gdzie je umieścić i tam je umieścić. Z biegiem czasu shared/ staje się aplikacją obejmującą wszystkie elementy.

core/ — czym jest, a czym nie jest

core/ dotyczy infrastruktury singleton, która wymaga jednorazowej całej aplikacji.

Popraw w core/:

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

Niepoprawne w core/:

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

Są to rzeczy, które są tworzone raz i wpływają na całą aplikację. Przechwytywacz uwierzytelniania przechwytuje wszystkie żądania HTTP dla całej aplikacji, dlatego znajduje się w core/.

Niejasne nazwy — sygnały ostrzegawcze

Niejasna nazwa to decyzja odroczona. Kiedy ktoś tworzy data.service.ts, nie zdecydował, o jakich danych mówi ta usługa.

co widzisz	Co to może oznaczać
shared/ bardzo duży	Wszystko, co nie pasowało nigdzie indziej. Staje się mieszanką.
common/	Taki sam jak shared/, ale z gorszą nazwą. Bez kryteriów tego, co wchodzi.
utils/ z usługami	Logika biznesowa w przebraniu użyteczności. Poważna czerwona flaga.
helpers/	To samo co utils/. Nazwa nie mówi nic o odpowiedzialności.
components/ w katalogu głównym	Brak organizacji według domeny. Wszystkie komponenty razem.
core/ z 40 plikami	Słabo zdefiniowany rdzeń. shared/ został użyty jako drugi.
app.service.ts	Służba Boża, która czeka na rozwój. Maksymalny sygnał alarmowy.
data.service.ts	Dane o czym? Odpowiedzialność nieokreślona z nazwy.
helper.service.ts	Ostatecznie staje się usługą z niepowiązanymi metodami.
main.component.ts	Co to jest „główne”? Ogólna nazwa, która kryje w sobie prawdziwą odpowiedzialność.

Reguła dotycząca nazw: Jeśli nazwa pliku nie mówi dokładnie, do czego służy, prawdopodobnie plik wykonuje zbyt wiele lub jest źle zlokalizowany.

Konkretne przykłady niejasnych nazw i tego, co kryją:

• utils/format.ts z 800 liniami: połączenie formatowania daty + walidacja formularza + transformacja API.
• helper.service.ts: kończy się na służbie bożej z niepowiązanymi metodami.
• app.service.ts: usługa nazywana całą aplikacją, która odpowiada za całą aplikację.

Krok 3 — Licz i mierz bez otwierania plików

Przed przeczytaniem kodu możesz dokonać następujących obserwacji bezpośrednio ze struktury:

Wielkość elementu jako znak

Podpisać	Co to oznacza?
+300-400 linii w jednym komponencie	Prawie zawsze robisz za dużo. Nie jest to absolutna reguła, ale warto to sprawdzić.
+10 wejść i wyjść	Zbyt skomplikowane API. Kandydat należy podzielić na kilka części.
Bezpośrednie wywołania HTTP w komponencie	Połącz prezentację z dostępem do danych. Brak warstwy usług.
1-2 komponenty na funkcję	Pewnie robią za dużo. Brak wewnętrznego podziału.
+20 globalnych dostawców	Za dużo państwa i scentralizowanej logiki. Nie wszystko musi mieć charakter globalny.

Usługi globalne — niebezpieczeństwo providedIn: 'root'

Usługa globalna oznacza, że ​​dowolny komponent dowolnej funkcji może ją wstrzyknąć i wykorzystać. Tworzy to niewidoczne zależności pomiędzy cechami, które powinny być niezależne.

// 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.

Krok 4 — app.module.ts lub app.config.ts: na co zwrócić uwagę

W aplikacjach z modułami (Angular < 17 lub starsze)

@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,
  ]
})

Moduły funkcji powinny być ładowane leniwie (na żądanie), a nie importowane bezpośrednio do modułu głównego. Jeśli wszystkie są tutaj, wszystkie są ładowane przy uruchomieniu, nawet jeśli użytkownik ich nigdy nie potrzebuje.

W samodzielnych aplikacjach (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
  ]
}

Zasada konfiguracji globalnej: Konfiguracja globalna powinna mieć tylko infrastrukturę wpływającą na całą aplikację: router z leniwym ładowaniem, HttpClient z globalnymi przechwytywaczami, animacje, usługi singletonowe infrastruktury (auth, logger, obsługa błędów). Jeśli widzisz usługi fabularne w konfiguracji globalnej, ktoś rejestruje rzeczy globalnie dla wygody, a nie konieczności.

Kompletna lista kontrolna — pierwsze czytanie aplikacji Angular

Struktura

• Czy struktura jest zorganizowana według cech (domena biznesowa) czy według warstw technicznych?
• Czy mogę usunąć cały obiekt, usuwając tylko jego folder, nie dotykając niczego innego?
• Czy funkcje mają nazwy domen biznesowych (checkout, catalog) lub nazwy techniczne (list, form, detail)?
• Czy istnieją foldery o niejasnych nazwach: utils, helpers, common, misc, data?

shared/ i core/

• Czy shared/ zawiera tylko komponenty interfejsu użytkownika i narzędzia bez logiki biznesowej?
• Czy core/ zawiera tylko infrastrukturę singleton (przechwytywacze, strażnicy, usługa autoryzacji)?
• Czy w shared/ istnieją usługi z logiką biznesową?
• Czy core/ ma komponenty funkcyjne lub usługi domenowe?

Usługi i dostawcy

• Czy usługi biznesowe są dostępne w ramach Twoich funkcji, czy są dostępne globalnie?
• Czy jest więcej niż 20 globalnych dostawców?
• Czy moduł główny lub app.config.ts importuje moduły funkcji bezpośrednio (bez lenistwa)?
• Czy istnieją usługi z providedIn: 'root', które powinny być lokalne dla danej funkcji?

Imiona

• Czy nazwy plików mówią dokładnie, do czego służą?
• Czy istnieją pliki, których nazwa może odnosić się do dowolnej części aplikacji?
• Czy istnieje plik o nazwie app.service.ts, data.service.ts lub helper.service.ts?
• Czy shared/ waży więcej niż jakakolwiek pojedyncza cecha?

Ćwiczenia

Wyszukaj dowolny publiczny projekt Angular na GitHub — może to być Twój własny lub projekt open source. Bez otwierania żadnych plików, wystarczy spojrzeć na strukturę folderów i nazwy:

1. Jaki model organizacji stosujesz: funkcje czy warstwy techniczne?
2. Jakie nazwy budzą Twoje wątpliwości lub podejrzenia?
3. Gdzie, jak podejrzewasz, leży logika biznesowa?
4. Jak myślisz, który folder ma najwięcej różnorodnych obowiązków?
5. Czy możesz usunąć funkcję bez dotykania czegokolwiek innego?

Podziel się tym, co zaobserwowałeś podczas sesji, a my wspólnie to sprawdzimy, tak jak zrobiłby to starszy architekt.

---

Podpowiedź: przeanalizuj swój projekt za pomocą 4 punktów

Skopiuj ten monit i użyj go z dowolną sztuczną inteligencją (ChatGPT, Claude, Copilot), przekazując mu drzewo folderów swojego projektu:

---

Przeanalizuj architekturę projektu stosując te 4 punkty Filaru 1 i wygeneruj raport.

PUNKT 1 — Struktura folderów

Przeanalizuj apps/ i libs/ i odpowiedz:

• Czy organizacja opiera się na funkcjach (domena biznesowa), czy na warstwach technicznych?
• Czy można usunąć cały obiekt, usuwając tylko jego folder?
• Czy funkcje mają nazwy domenowe (checkout, catalog) lub nazwy techniczne (list, form, detail)?
• Czy istnieją foldery o niejasnych nazwach: utils, helpers, common, misc, data?
• Pokazuje rzeczywiste drzewo znalezionych folderów.

PUNKT 2 — Nazwy plików i folderów

Przeszukaj cały projekt i listę:

• Pliki o niejasnych nazwach: data.service.ts, helper.service.ts, app.service.ts, main.component.ts, utils z usługami w środku.
• Usługi z logiką biznesową w obrębie shared/.
• Komponenty lub usługi domenowe w core/.
• Czy shared/ waży więcej niż jakakolwiek pojedyncza funkcja? Liczba plików.

PUNKT 3 – Usługi globalne

Przeszukaj cały projekt:

• Wszystkie usługi z providedIn: 'root' — lista, które to są i czy powinny być lokalne dla danej funkcji.
• Liczy, ilu jest łącznie globalnych dostawców.
• Identyfikuje globalnie zarejestrowane usługi biznesowe, kiedy powinny być dostępne w Twojej funkcji.
• Wyszukaj usługi w libs/services/, które wyraźnie należą do określonej domeny.

PUNKT 4 — Konfiguracja globalna (app.config.ts lub app.module.ts)

Znajdź główny plik konfiguracyjny każdej aplikacji i przeanalizuj:

• Co jest rejestrowane na całym świecie, a czego nie powinno?
• Czy moduły funkcji są ładowane z opóźnieniem, czy też są importowane bezpośrednio?
• Czy w konfiguracji globalnej znajdują się usługi biznesowe?
• Ilu dostawców jest łącznie zarejestrowanych na całym świecie?

FORMAT RAPORTU

Dla każdego punktu użyj tej dokładnej struktury:

✅Co dobrego

(konkretna lista z prawdziwymi przykładami kodu)

⚠️ Znaki do sprawdzenia

(konkretna lista ze ścieżką pliku i dlaczego jest to znak)

❌ Usuń problemy

(konkretna lista ze ścieżką pliku, problemem i rzeczywistym wpływem)

Ostatecznie zawiera:

Podsumowanie wykonawcze

Tabela z 4 punktami, emoji stanu (✅ ⚠️ ❌) i linią wniosków na każdy punkt.

Ustalono priorytety kolejnych kroków

Lista maksymalnie 5 określonych działań uporządkowanych według wpływu, z dokładną ścieżką pliku lub folderu, którego należy dotknąć.

Bądź bezpośredni. Nie wyjaśniaj, czym jest cecha lub teoria. Wystarczy przeanalizować ten konkretny projekt i przedstawić realne wnioski.