Obiekt wartościowy w Pythonie - Uprość kod i uniknij błędów!

Wzorzec value object ma sens wtedy, gdy obiekt opisuje stan, a nie tożsamość. W praktyce chodzi o takie elementy modelu jak kwota, zakres dat, adres e-mail czy współrzędne, czyli rzeczy, które rozpoznajemy po ich atrybutach. W tym artykule pokazuję, jak rozpoznać ten typ obiektu, czym różni się od encji, jak sensownie zbudować go w Pythonie i jakie błędy najczęściej psują cały pomysł.

Czym jest obiekt oparty na wartościach

Najprościej: to taki element modelu, którego sens wynika z zestawu cech. Jeśli dwa obiekty mają te same istotne atrybuty, traktuję je jako równe, nawet jeśli technicznie są dwoma różnymi instancjami w pamięci. Dla czytelnika kodu ważniejsze jest więc „co ten obiekt oznacza”, niż „którą ma tożsamość”.

To podejście świetnie działa przy danych, które można opisać jako komplet właściwości: kwota i waluta, początek i koniec zakresu, szerokość i wysokość, nazwa i znormalizowany adres e-mail. Taki model zwykle ma mało metod, ale za to pilnuje własnych reguł bardzo konsekwentnie. I właśnie dlatego dobrze zaprojektowany obiekt tego typu porządkuje kod zamiast go komplikować.

W praktyce największa różnica nie polega na samej nazwie klasy, tylko na tym, jak myślisz o porównywaniu, zmianie stanu i odpowiedzialności. To prowadzi prosto do pytania, czym taki obiekt różni się od encji i zwykłej klasy.

Czym różni się od encji i zwykłej klasy

Jeśli potrzebujesz rozpoznać konkretny byt w czasie, śledzić jego historię albo odwoływać się do niego z wielu miejsc, zwykle mówisz o encji. Jeśli natomiast liczy się tylko to, z czego ten byt się składa, prawdopodobnie lepszy będzie model oparty na wartościach. Gdy już to widać, najłatwiej przejść do kodu i sprawdzić, jak zrobić to w Pythonie bez zbędnej ceremonii.

Jak zaprojektować taki obiekt w Pythonie

Python daje tu wygodne narzędzia, bo nie trzeba budować całego ceremonialnego szkieletonu klasy. Najczęściej wystarcza `dataclass` z włączonym trybem niemutowalnym, a potem jedna porządna walidacja reguł domenowych. Ja zwykle zaczynam od pytania: czy ten obiekt może zmienić się po utworzeniu? Jeśli odpowiedź brzmi „nie”, jestem bardzo blisko właściwego rozwiązania.

from dataclasses import dataclass

@dataclass(frozen=True)
class Money:
    amount: int
    currency: str

    def __post_init__(self):
        currency = self.currency.strip().upper()

        if self.amount < 0:
            raise ValueError("Kwota nie może być ujemna")
        if len(currency) != 3:
            raise ValueError("Kod waluty powinien mieć 3 znaki")

        object.__setattr__(self, "currency", currency)

    def add(self, other: "Money") -> "Money":
        if self.currency != other.currency:
            raise ValueError("Nie można dodawać różnych walut")
        return Money(self.amount + other.amount, self.currency)

Ten przykład pokazuje kilka ważnych rzeczy naraz. Po pierwsze, obiekt sam pilnuje swoich granic, więc nie rozrzucasz walidacji po całym projekcie. Po drugie, `frozen=True` sprawia, że instancja nie daje się swobodnie przepisać po utworzeniu, co bardzo dobrze pasuje do danych opartych na wartościach. Po trzecie, metoda `add()` nie zmienia istniejącego obiektu, tylko zwraca nowy, co jest dużo bezpieczniejsze w większym systemie.

Warto też pamiętać, że w Pythonie niemutowalność jest praktyczna, ale nie magiczna. Sam język pozwala obejść wiele rzeczy, więc sens tego wzorca wynika nie z dogmatów, tylko z dyscypliny projektowej. I właśnie dlatego trzeba wiedzieć, jakie cechy odróżniają dobrze zaprojektowany obiekt od zwykłej klasy z kilkoma polami.

Jakie cechy powinien mieć dobry obiekt wartościowy

Ja patrzę przede wszystkim na cztery rzeczy: spójność, równość, niemutowalność i jasne reguły. Jeśli któraś z nich nie działa, model szybko robi się nieczytelny albo zaczyna zachowywać się sprzecznie z intuicją domenową. Poniżej rozbijam to na praktyczne zasady.

Waliduje się sam

Jeśli obiekt ma reguły, powinien je sprawdzać w jednym miejscu, najlepiej przy tworzeniu. Dzięki temu nie da się stworzyć niepoprawnej instancji i przypadkiem przesłać jej dalej. To szczególnie ważne przy danych takich jak e-mail, numer telefonu, zakres dat czy kwota, bo niepoprawne wartości lubią rozlać się po systemie szybciej, niż człowiek zdąży zauważyć błąd.

Porównuje się po znaczeniu, nie po adresie w pamięci

Tu wchodzi najważniejsza zasada: dwa obiekty mają być uznane za równe wtedy, gdy ich istotne atrybuty są równe. W praktyce oznacza to, że jeśli kwota 100 PLN jest tworzona w dwóch różnych miejscach aplikacji, nadal pozostaje tą samą wartością domenową. To odróżnia ten model od encji, gdzie identyfikator ma pierwszeństwo.

Nie zmienia się po utworzeniu

Niemutowalność, czyli brak swobodnej zmiany stanu, bardzo upraszcza myślenie o kodzie. Taki obiekt można bezpieczniej przekazywać między warstwami, przechowywać w kolekcjach i używać w równoległych procesach bez obawy, że ktoś go po cichu przepisał. W Pythonie nie chodzi o absolutną blokadę wszystkiego, tylko o sensowną ochronę stanu domenowego.

Przeczytaj również: REST API w praktyce - Jak budować przewidywalne integracje?

Ma tylko tyle odpowiedzialności, ile trzeba

To nie jest mini-serwis ani miejsce na całą logikę biznesową świata. Dobra zasada brzmi: obiekt oparty na wartościach powinien znać swoje reguły i ewentualnie kilka operacji na własnych danych, ale nie powinien przejmować roli całej warstwy aplikacyjnej. Gdy zaczyna robić za dużo, traci czytelność i łatwo zamienia się w ciężki, trudny do testowania twór.

Gdy te zasady są spełnione, model zaczyna działać naturalnie. Najłatwiej zobaczyć to na przykładach, bo dopiero tam widać, jak bardzo taki model potrafi odchudzić kod.

Przykłady, które naprawdę upraszczają kod

Najlepsze zastosowania są zwykle mniej spektakularne, niż ludzie się spodziewają. To nie muszą być wielkie konstrukcje złożone z dziesiątek metod. Często największy zysk przynosi dopiero wyrzucenie z kodu „gołych” stringów i liczb, które niby działają, ale niczego nie opisują.

• Kwota pieniędzy - zamiast trzymać samo `amount`, lepiej mieć obiekt, który łączy kwotę i walutę. Dzięki temu nie pomylisz złotówek z euro i nie dodasz do siebie wartości z różnych walut bez świadomej decyzji.
• Adres e-mail - taki obiekt może od razu usuwać spacje, wymuszać małe litery i sprawdzać podstawową poprawność. To zmniejsza liczbę drobnych błędów, które zwykle wychodzą dopiero w produkcji.
• Zakres dat - zamiast przekazywać dwa osobne pola w każdym miejscu, kod dostaje jeden spójny byt z jasną regułą, że koniec nie może być wcześniejszy niż początek.
• Współrzędne albo wymiary - przydają się tam, gdzie liczy się para lub trójka powiązanych wartości i nie chcesz ich rozrywać na osobne argumenty funkcji.
• Jednostki domenowe - temperatura, procent, odległość czy liczba sztuk to dobry przykład na walkę z tak zwaną primitive obsession, czyli nadmiernym używaniem prostych typów tam, gdzie potrzebny jest sens biznesowy.

W tych przypadkach korzyść jest bardzo konkretna: mniej parametrów w funkcjach, mniej powtarzalnej walidacji, mniej niejasnych nazw i mniej błędów wynikających z pomieszania podobnych danych. Z czasem taki model zaczyna też lepiej opowiadać domenę, bo kod mówi wprost, czym dana rzecz jest. Nie wszystko jednak nadaje się do takiego ujęcia, więc trzeba też znać ograniczenia.

Najczęstsze błędy i ograniczenia

Największy problem nie polega na tym, że ktoś użyje tego wzorca źle w jednym miejscu. Problem zaczyna się wtedy, gdy przez nadgorliwość próbujesz nim objąć wszystko. Wtedy zamiast prostszego modelu dostajesz nadmiar abstrakcji i więcej kosztów niż korzyści.

Jest jeszcze jedna granica, o której łatwo zapomnieć: jeśli obiekt musi być śledzony w czasie, mieć historię zmian albo być jednoznacznie rozpoznawalny niezależnie od treści, wtedy lepsza będzie encja. Obiekt oparty na wartościach nie jest uniwersalną odpowiedzią na każdy problem modelowania, tylko narzędziem do bardzo konkretnych sytuacji. Jeśli jednak wybierzesz właściwy moment, zyskasz czytelniejszy model i mniej powtarzalnych błędów.

Kiedy ten wzorzec najbardziej upraszcza model domeny

Największy zwrot dostajesz wtedy, gdy w projekcie pojawiają się dane, które często się powtarzają, wymagają walidacji i mają jednoznaczne znaczenie biznesowe. Właśnie tam taki model działa najlepiej: odcina przypadkowość, zmniejsza liczbę argumentów w funkcjach i sprawia, że nazwy klas zaczynają naprawdę coś znaczyć. W praktyce szczególnie dobrze wypada to przy pieniądzach, datach, adresach, jednostkach miary i wszystkich tych fragmentach domeny, które łatwo pomylić, jeśli zostawić je jako zwykłe typy proste.

Ja zwykle zaczynam od jednego miejsca, w którym powtarza się walidacja albo rośnie bałagan z parametrami, i dopiero potem rozwijam model dalej. To bezpieczniejsze niż przepisywanie całej aplikacji na nowy sposób myślenia. Jeśli taki obiekt od razu poprawia czytelność, testowalność i spójność reguł, to znak, że jest użyty dokładnie tam, gdzie powinien.