dev{ops}: Różnice między wersjami protokołu HTTP

w dniu
0

dev{tools} Architecture Decision Record

w dniu

    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.



Co to jest ADL i ADR?

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.

Główne atrybuty ADR

ADR charakteryzują się kilkoma kluczowymi atrybutami, które zapewniają ich użyteczność i efektywność:

  1. Niemutowalność rekordu - Po zatwierdzeniu, ADR nie powinien być modyfikowany. Zapewnia to, że historia decyzji jest stała i przejrzysta.

  2. Rekord zawiera czas podjęcia decyzji - Data i czas decyzji są kluczowe dla zrozumienia kontekstu, w którym została ona podjęta.

  3. Opisuje dokładnie jedną decyzję - Każdy ADR powinien dotyczyć tylko jednej konkretnej decyzji, co zapobiega konfuzji i sprawia, że dokumentacja jest czytelniejsza.

  4. Zawiera obecną sytuację i kontekst - Opisuje aktualne warunki, które wpływają na projekt lub system, podkreślając znaczenie decyzji.

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

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

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

Implementacja ADR

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

Instalacja adr-tools

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

Inicjowanie repozytorium ADR

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.

Tworzenie nowego ADR

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.

Przeglądanie i zarządzanie ADR-ami

adr-tools oferuje również możliwości przeglądania istniejących ADR-ów i zarządzania nimi:

  • Wylistowanie wszystkich ADR-ów: adr list
  • Pokaż szczegóły ADR: adr view NUMER
  • Ustalenie, że jeden ADR zastępuje inny: 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.

Podsumowanie

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