Wyobraź sobie jedno pole formularza — powiedzmy adres e-mail przy rejestracji. W typowym backendzie musisz opisać je trzy razy: raz, żeby program wiedział, że to tekst; drugi raz, żeby sprawdzał, czy to faktycznie e-mail; trzeci raz, żeby w dokumentacji dla innych było napisane, co to za pole.
Trzy opisy tej samej rzeczy. A teraz zmień wymagania — i pamiętaj, żeby poprawić wszystkie trzy. Zapomnisz o jednym, i dokumentacja zaczyna kłamać.
Dlaczego trzy razy to problem
Sama w sobie ta potrójność nie jest błędem — to wygodny domyślny sposób pracy w popularnym frameworku. Problem zaczyna się przy skali jednej osoby utrzymującej kilkadziesiąt różnych „okienek” API. Każda zmiana wymagań to trzy poprawki w trzech miejscach. Prędzej czy później któreś zostaje w tyle — najczęściej dokumentacja, bo nikt jej nie testuje.
A zła dokumentacja API jest gorsza niż jej brak. Partner, który integruje się z moim systemem (np. urząd albo firma), czyta, że pole działa tak, a ono działa inaczej. Tracę zaufanie, zanim cokolwiek wspólnie uruchomimy.
Co wybrałem zamiast tego
Zdecydowałem się opisywać każde pole raz, w jednym miejscu, w taki sposób, że z tego jednego opisu „wypadają” automatycznie trzy rzeczy: informacja dla programu o typie danych, reguła sprawdzania poprawności na wejściu oraz wpis w dokumentacji. Zmieniam opis w jednym miejscu — reszta nadąża sama, bo to dosłownie ten sam zapis.
Nie wymyśliłem tego. Podpatrzyłem podejście w świetnym projekcie open-source (Teable) i przeniosłem pomysł do siebie. To moja ogólna zasada: zanim napiszę coś od zera, sprawdzam, jak rozwiązały to dobre, otwarte projekty.
Gdzie postawiłem granicę
Jedno źródło prawdy pilnuje formatu — czy e-mail wygląda jak e-mail, czy pole nie jest puste. Ale to nie to samo co reguły biznesowe: czy ten e-mail nie jest już zajęty, czy ktoś ma prawo działać w danej okolicy. To dwie różne warstwy i celowo ich nie mieszam — sprawdzanie formatu na wejściu, reguły firmy głębiej, osobno.
Tę zasadę („format osobno, reguły biznesowe osobno”) uważam dziś za jedną z ważniejszych dla porządku w całym systemie.
Dla kogo to ma sens
To dobry wybór, jeśli budujesz API z dokumentacją dla zewnętrznych partnerów i utrzymujesz je małym zespołem (albo w pojedynkę). Jeśli klepiesz szybki prototyp, którego nikt z zewnątrz nie dotknie — to nadmiar.