w dniu
clean_code
dev
productivity
programming
team
tools
- Pobierz link
- Inne aplikacje
W dzisiejszym świecie rozwoju oprogramowania, gdzie złożoność systemów stale rośnie, kluczowe znaczenie ma skuteczna dokumentacja decyzji architektonicznych. Dzięki temu podejściu zespoły mogą nie tylko utrzymywać spójność projektu, ale także łatwiej zarządzać zmianami. W tym kontekście pojęcia takie jak Architecture Decision Log (ADL) i Architecture Decision Record (ADR) odgrywają fundamentalną rolę. Artykuł ten wprowadzi w koncepcję ADL i ADR, omówi ich główne atrybuty oraz zasugeruje sposoby implementacji.
Architecture Decision Log (ADL) jest zbiorczym dokumentem lub repozytorium, które zawiera wszystkie Architecture Decision Records (ADR) dotyczące projektu. Jest to miejsce, gdzie zespoły mogą śledzić i zarządzać kluczowymi decyzjami architektonicznymi.
Architecture Decision Record (ADR), z kolei, to dokument skupiający się na pojedynczej, istotnej decyzji architektonicznej wraz z kontekstem i konsekwencjami tej decyzji. ADR pomaga w dokumentowaniu kluczowych decyzji, które wpływają na strukturę i działanie systemu.
ADR charakteryzują się kilkoma kluczowymi atrybutami, które zapewniają ich użyteczność i efektywność:
Niemutowalność rekordu - Po zatwierdzeniu, ADR nie powinien być modyfikowany. Zapewnia to, że historia decyzji jest stała i przejrzysta.
Rekord zawiera czas podjęcia decyzji - Data i czas decyzji są kluczowe dla zrozumienia kontekstu, w którym została ona podjęta.
Opisuje dokładnie jedną decyzję - Każdy ADR powinien dotyczyć tylko jednej konkretnej decyzji, co zapobiega konfuzji i sprawia, że dokumentacja jest czytelniejsza.
Zawiera obecną sytuację i kontekst - Opisuje aktualne warunki, które wpływają na projekt lub system, podkreślając znaczenie decyzji.
Zawiera porównanie kilku opcji - ADR powinien opisywać alternatywne rozwiązania, które były rozważane przed podjęciem ostatecznej decyzji, wraz z uzasadnieniem wyboru.
Zawiera wpływ driverów architektonicznych na decyzję - Kluczowe motywacje czy wymagania, które miały wpływ na decyzję, są istotne dla zrozumienia wyborów projektowych.
Zawiera konsekwencje podjętej decyzji - Konsekwencje, zarówno pozytywne, jak i negatywne, powinny być dokładnie opisane, aby zrozumieć długoterminowy wpływ decyzji na projekt.
Przykład z życia: Załóżmy, że zespół projektowy stoi przed wyborem technologii do obsługi bazy danych. Możliwe opcje to SQL i NoSQL. Po analizie wymagań projektu, zespołowych preferencji, możliwości skalowania i zarządzania danymi, zespół decyduje się na SQL. Decyzja ta jest dokumentowana jako ADR, gdzie opisano dlaczego odrzucono NoSQL (np. z powodu braku potrzebnych transakcji), jakie są przewidywane korzyści z wybranej technologii oraz jakie są potencjalne ryzyka i ograniczenia.
Wdrażanie jako kod:
Do tworzenia i zarządzania ADR można użyć narzędzi takich jak adr-tools
aby wygenerować szablony decyzji. Dzięki temu ADR mogą być wersjonowane razem z kodem źródłowym i łatwo dostępne dla całego zespołu.
# ADR 1: Wybór systemu zarządzania bazą danych ## Status Przyjęte
## Data akceptacji
2024-08-05 ## Kontekst Nasza aplikacja wymaga solidnego systemu zarządzania bazą danych,
który wspiera transakcje, zapytania złożone i zapewnia wysoką dostępność.
Ze względu na wymagania dotyczące integralności danych i obsługi złożonych zapytań, rozważaliśmy wybór między relacyjną bazą danych a systemami NoSQL. ## Decyzja Zdecydowaliśmy się na użycie PostgreSQL jako naszego systemu zarządzania bazą danych. ## Alternatywy 1. **MongoDB** - baza danych NoSQL, która jest elastyczna i dobrze radzi sobie z dużymi ilościami danych nierelacyjnych. Jednak brak wsparcia dla transakcji między dokumentami mógłby komplikować niektóre z naszych kluczowych przypadków użycia. 2. **MySQL** - popularna baza danych relacyjna, ale ma mniej zaawansowane funkcje w zakresie obsługi zapytań i wydajności w porównaniu do PostgreSQL. ## Motywacje Wybraliśmy PostgreSQL z następujących powodów: - **Wsparcie dla transakcji**: PostgreSQL oferuje kompleksowe wsparcie dla transakcji ACID, co jest kluczowe dla naszych wymagań dotyczących integralności danych. - **Zaawansowane zapytania**: PostgreSQL obsługuje zaawansowane zapytania SQL, które są potrzebne do naszych złożonych operacji danych. - **Wydajność i niezawodność**: PostgreSQL jest znany z wysokiej wydajności i niezawodności, co jest decydujące dla naszej potrzeby zapewnienia ciągłej dostępności usług. ## Konsekwencje Wybór PostgreSQL jako naszej bazy danych wiąże się z potrzebą szkolenia naszego zespołu w zakresie specyfikacji tego systemu oraz potencjalnie wyższych kosztów utrzymania ze względu na bardziej złożone wymagania operacyjne w porównaniu do prostszych systemów NoSQL. Jednakże, korzyści wynikające z używania technologii, która lepiej spełnia nasze krytyczne wymagania biznesowe, przewyższają te wyzwania.
przykład pliku markdown z opisaną decyzją
Narzędzie adr-tools
jest popularnym środkiem do zarządzania Architecture Decision Records (ADR) w projektach programistycznych. Umożliwia ono szybkie tworzenie, zarządzanie i przeglądanie ADR-ów w formie tekstowej, co jest szczególnie przydatne w środowiskach, gdzie dokumentacja i przejrzystość decyzji są kluczowe.
Najpierw musisz zainstalować adr-tools
. Narzędzie to jest dostępne na GitHubie i można je zainstalować na systemach Unix i podobnych (takich jak macOS czy Linux) za pomocą prostego skryptu instalacyjnego. Oto jak to zrobić:
git clone https://github.com/npryce/adr-tools.git
cd adr-tools
sudo make install
Po zainstalowaniu narzędzia, przejdź do głównego katalogu swojego projektu i zainicjuj repozytorium ADR:
adr init doc/architecture/decisions
To polecenie utworzy katalog doc/architecture/decisions
, gdzie będą przechowywane wszystkie ADR-y. W tym katalogu zostanie również utworzony pierwszy ADR, który dokumentuje decyzję o używaniu ADR-ów.
Aby utworzyć nowy ADR, użyj polecenia adr new
. Na przykład, aby utworzyć ADR dotyczący wyboru frameworka do testów, możesz użyć:
adr new Użyj frameworka XYZ do testów jednostkowych
To polecenie stworzy nowy plik ADR w katalogu decyzji, z przydzielonym kolejnym numerem i podanym tytułem. Plik ten będzie zawierał szablon, który możesz wypełnić, opisując kontekst, decyzję, konsekwencje i inne kluczowe aspekty.
adr-tools
oferuje również możliwości przeglądania istniejących ADR-ów i zarządzania nimi:
adr list
adr view NUMER
adr link NUMER supercedes INNY_NUMER
Ciekawostka - Confluence: Atlassian Confluence oferuje szablon "Decision" w ramach swojej funkcjonalności, co pozwala zespołom na tworzenie i zarządzanie ADR w bardziej zintegrowanym środowisku korporacyjnym.
Dokumentacja decyzji architektonicznych za pomocą ADL i ADR jest nie tylko praktyką wzmacniającą procesy decyzyjne, ale również sposobem na budowanie bardziej przewidywalnych i zarządzalnych systemów informatycznych. Przez odpowiednie dokumentowanie kluczowych decyzji, zespoły mogą lepiej przewidywać skutki swoich wyborów, co w długoterminowej perspektywie przekłada się na większą efektywność i skuteczność projektów.
Komentarze
Prześlij komentarz