Monorepo kontra polyrepo: jak trzymać web, mobile i backend w synchronizacji

Rzeczywisty problem: wdrażanie zmian w trzech bazach kodu

Zespoły nie spierają się o monorepo kontra polyrepo z powodu filozofii Gita. Kłócą się, bo mała zmiana produktowa zamienia się w trzy oddzielne zmiany w web, mobile i backendzie, i coś po drodze się psuje.

To, co psuje się pierwsze, rzadko jest UI. Zwykle to niewidoczny klej: zmieniony kontrakt API bez odpowiadającej aktualizacji, współdzielona biblioteka podbita w jednym miejscu, ale nie w innych, albo pipeline budowania nagle potrzebuje dodatkowego kroku. Gdy jedna część wypłynie wcześniej niż pozostałe, użytkownicy odczuwają to jako błędy typu „przycisk jest na webie, ale aplikacja mobilna mówi, że nieobsługiwane” albo „aplikacja ładuje się wiecznie, bo odpowiedź backendu się zmieniła”.

Web, mobile i backend też działają w różnych tempach wydań. Web może wypuszczać wiele razy dziennie. Backend często też może, ale potrzebuje ostrożnego rolloutu. Mobile jest najwolniejsze ze względu na review w sklepie i czas potrzebny użytkownikom na aktualizację. „Prosta” zmiana, jak przemianowanie pola, może zmusić do planowania wokół najsłabszego ogniwa, nawet jeśli tylko jeden ekran tego potrzebuje.

Płacisz podatek koordynacyjny repozytorium, jeśli to się zdarza często:

• Zmiany łamiące API odkrywane są po mergu.
• Uzgadnianie wersji zależy od ręcznych przypomnień i arkuszy kalkulacyjnych.
• Jedna funkcja wymaga wielu skoordynowanych pull requestów, które czekają na siebie nawzajem.
• CI jest wolne, bo buduje i testuje znacznie więcej niż obejmuje zmiana.
• Rollbacki są ryzykowne, bo nie jest jasne, który commit pasuje do którego wydania.

Wielkość zespołu i dojrzałość produktu zmieniają właściwą odpowiedź. Na początku większość zespołów wygrywa, gdy koordynacja jest tania i widoczność wysoka, nawet jeśli jest trochę bałaganu. W miarę wzrostu znaczenia mają granice odpowiedzialności, ale tylko jeśli interfejsy są stabilne, a właściciele jasni.

Jeśli każda istotna zmiana musi wylądować w trzech miejscach, i tak za to zapłacisz. Strategia repozytorium to głównie decyzja, jak chcesz ten koszt ponosić.

Monorepo i polyrepo bez żargonu

Repozytorium to po prostu miejsce, gdzie trzymasz kod i jego historię. Gdy masz web, mobile i backend, wybór jest prosty: trzymaj wszystko razem albo podziel.

Monorepo to jedno repozytorium, które zawiera wiele aplikacji i często także kod współdzielony. Web, iOS/Android, usługi backendowe i biblioteki współdzielone siedzą obok siebie.

Polyrepo to odwrotność: każda aplikacja (a czasem każda usługa) ma własne repo. Kod współdzielony zwykle staje się oddzielnym pakietem albo zespoły kopiują małe kawałki, gdy trzeba.

Na co dzień monorepo zwykle daje takie odczucia: dzielenie się kodem jest proste, zmiany między aplikacjami mogą być jednym pull requestem, a zasady są spójne. W zamian pojawia się aspekt społeczny: granice własności mogą być niejasne, jeśli ich nie ustalisz, a checki na poziomie całego repo mogą wydawać się surowe.

Polyrepo daje inaczej: każdy zespół może działać niezależnie, repozytoria są bardziej skupione, a kontrola dostępu może być prostsza. W zamian koordynacja jest cięższa: dzielenie się kodem wymaga planowania, a zmiany przekrojowe często stają się wieloma PR-ami z dokładnym timingiem.

Wiele zespołów kończy z hybrydą: aplikacje w osobnych repozytoriach, kontrakty współdzielone w jednym miejscu; albo jedno monorepo z wyraźnymi granicami, tak żeby każdy zespół działał głównie we własnym obszarze.

Jeśli używasz platformy, która generuje backend, web i mobile z jednego źródła prawdy, zmniejszasz dryf, bo kontrakty i logika żyją razem. AppMaster (appmaster.io), na przykład, generuje produkcyjne backendy, weby i natywne aplikacje mobilne z jednego modelu. To nie usuwa realiów wydania (mobile nadal wypuszcza wolniej), ale może wyeliminować dużo „czy zaktualizowaliśmy wszystkie trzy miejsca?” pracy.

Zarządzanie zależnościami: jak chronić kod współdzielony

Kod współdzielony to miejsce, gdzie zespoły tracą czas, niezależnie od układu repo. Mała zmiana w bibliotece współdzielonej lub kontrakcie API może popsuć buildy web, wydania mobilne i deploye backendu na różne sposoby.

Gdy dzielisz biblioteki (komponenty UI, reguły walidacji, helpery auth), wybierasz między jedną wersją dla wszystkich a wieloma wersjami w czasie.

• Jedna wersja jest prostsza i unika niespodzianek typu „działa na moim branchu”.
• Wielo wersji pozwalają zespołom iść własnym tempem, ale generują bałagan i utrudniają szybkie poprawki bezpieczeństwa.

Klienci API i schematy zasługują na szczególną uwagę. Ręczne aktualizacje są powolne i podatne na błędy. Lepszy wzorzec to traktować schemat API jako źródło prawdy i generować klientów z niego, potem albo commitować je do repo, albo generować w CI. Celem jest szybkie wykrycie błędów: jeśli backend doda wymagane pole, klient mobilny powinien się złamać przy buildzie, a nie trzy dni później w QA.

Zmiany łamiące kompatybilność rozprzestrzeniają się, gdy zachowanie się zmieni bez bezpiecznej drogi naprzód. Preferuj najpierw zmiany addytywne (nowe pola, nowe endpointy), potem deprecjuj. Jeśli musisz coś złamać, użyj wersjonowanych endpointów albo krótkiego okna zgodności.

Konkretny przykład: backend zmienia nazwę status na state. Jeśli web zaktualizuje dziś, ale mobile nie może wypłynąć przez tydzień, backend musi akceptować oba pola przez ten tydzień albo wystawić adapter mapujący stare pole na nowe.

Kilka zasad, które sprawiają, że aktualizacje zależności są nudne (w pozytywnym sensie):

• Aktualizuj według rytmu. Małe, cotygodniowe aktualizacje są lepsze niż wielkie kwartalne.
• Wymagaj wyraźnej zgody na zmiany łamiące oraz krótkiej notki migracyjnej.
• Automatyzuj checki: podbicia zależności, regenerację klientów i podstawowe testy kontraktów.
• Definiuj „ukończone” jako „web, mobile i backend buildują się poprawnie”, nie tylko „moje repo przechodzi”.

Generowany kod może zmniejszyć dryf, ale nie zastąpi dyscypliny. Nadal potrzebujesz jednego kontraktu, jasnych zasad deprecjonowania i przewidywalnych aktualizacji.

Koordynacja wydań: dopasowanie web, mobile i backend

Koordynacja wydań to miejsce, gdzie strategia repo przestaje być teoretyczna. Jeśli backend zmieni nazwę pola API, aplikacja web zwykle może zaktualizować i wypuścić tego samego dnia. Aplikacje mobilne są inne: review w sklepie i czas potrzebny użytkownikom na aktualizację mogą zamienić drobną niespójność w tydzień zgłoszeń do supportu.

Praktyczny cel jest prosty: akcja użytkownika powinna działać bez względu na to, która część się zaktualizowała pierwsza. To znaczy planować na mieszane wersje, a nie zakładać idealnej synchronizacji.

Wzorce wersjonowania, które zespoły rzeczywiście stosują

Większość zespołów przyjmie jeden z tych modeli:

1. Wspólny pociąg wydań: web, mobile i backend wypuszczane jako jedna wersjonowana jednostka.

2. Wersje per-usługa z regułami kompatybilności: każda aplikacja/usługa ma własną wersję, a backend wspiera zdefiniowany zakres wersji klientów.

Wspólny pociąg wygląda estetycznie, ale często zawodzi przy opóźnieniach mobilnych. Wersje per-usługa są na papierze bardziej chaotyczne, ale lepiej odzwierciedlają rzeczywistość. Jeśli idziesz w per-usługa, zapisz jedną regułę i jej przestrzegaj: które wersje backendu muszą wspierać które wersje mobilne i przez jaki czas.

Opóźnienia mobilne też zmieniają sposób obsługi hotfixów. Hotfixy backendu możesz wypuścić szybko; hotfixy mobilne mogą nie dotrzeć do użytkowników przez dni. Preferuj poprawki po stronie serwera, które utrzymują działanie starych buildów mobilnych. Gdy musisz zmieniać klienta, używaj flag funkcji i unikaj usuwania starych pól, dopóki nie wiesz, że większość użytkowników zaktualizowała.

Przykład: dodajesz „instrukcje dostawy” do toku zamówienia. Backend dodaje nowe opcjonalne pole, web od razu je pokazuje, mobile zrobi to w następnym sprincie. Jeśli backend akceptuje stare żądania i pole jest opcjonalne, wszystko działa, a mobile nadąża.

Kto zarządza kalendarzem wydań

Koordynacja zawodzi, gdy „wszyscy to mają”, czyli nikt. Właścicielem może być tech lead, menedżer wydań lub product manager z silnym wsparciem inżynieryjnym. Ich zadaniem jest unikanie niespodzianek przez utrzymanie oczekiwań dotyczących wydań widocznych i spójnych.

Nie potrzebują skomplikowanego procesu. Potrzebują kilku powtarzalnych nawyków: prosty kalendarz wydań z cutoffami i oknami freeze, szybkie cross-teamowe sprawdzenie przed wypuszczeniem zmian w API i jasny plan na wypadek opóźnienia mobile (wstrzymać backend vs zachować kompatybilność).

Jeśli Twój workflow generuje web, mobile i backend razem z jednego modelu, nadal potrzebujesz właściciela wydań. Będziesz zwykle miał mniej „czy zaktualizowaliśmy wszystkie trzy miejsca?” momentów, ale nie uciekniesz przed timingiem mobilnym.

Jak trzymać CI w ryzach

CI spowalnia z tych samych powodów w obu podejściach: przebudowujesz za dużo, wielokrotnie instalujesz zależności i uruchamiasz wszystkie testy przy każdej zmianie.

Typowe pożeracze czasu to pełne buildy przy drobnych zmianach, brak cache’y, zestawy testów uruchamiające wszystko oraz zadania uruchamiane sekwencyjnie, które mogłyby iść równolegle.

Zacznij od usprawnień, które pomagają wszędzie:

• Cache’uj pobrane zależności i wyniki budowania.
• Uruchamiaj lint, testy jednostkowe i buildy równolegle, gdzie to możliwe.
• Oddziel szybkie checki (każdy commit) od wolniejszych (gałąź główna, nocne lub przed wydaniem).

Taktyki monorepo, które pomagają

Monorepo zaczyna być uciążliwe, gdy każdy commit uruchamia pipeline „przebuduj wszystko”. Rozwiązanie to budować i testować tylko to, czego dotyczy zmiana.

Użyj filtrów ścieżek i podejścia „tylko dotknięte”: jeśli zmieniłeś kod UI mobilnego, nie buduj obrazów backendu. Jeśli ruszyła biblioteka współdzielona, zbuduj i przetestuj tylko aplikacje, które od niej zależą. Wiele zespołów formalizuje to prostym grafem zależności, żeby CI mogło podejmować decyzję zamiast zgadywać.

Taktyki polyrepo, które zapobiegają dryfowi

Polyrepo mogą być szybkie, bo każde repo jest mniejsze, ale często marnują czas przez duplikację i niespójne narzędzia.

Trzymaj jeden zestaw szablonów CI (te same kroki, te same cache’e, te same konwencje), żeby każde repo nie wymyślało pipeline’u od nowa. Przypinaj toolchainy (wersje runtime, narzędzia budowania, linters), żeby unikać „działa w jednym repo” niespodzianek. Jeśli pobieranie zależności jest wąskim gardłem, skonfiguruj współdzielone cache’e lub wewnętrzne mirror’y, żeby każde repo nie ściągało świata od zera.

Konkretny przykład: funkcja dodaje nowe pole „status”. Backend zmienia się, web go pokazuje, mobile też. W monorepo CI powinien uruchomić testy backendu oraz tylko te części web i mobile, które zależą od klienta API. W polyrepo każde repo powinno uruchomić swoje szybkie checki, a osobny pipeline integracyjny może zweryfikować, czy trzy wydania nadal się zgadzają.

Jeśli eksportujesz kod źródłowy i uruchamiasz własne CI, ta sama zasada: buduj tylko to, co się zmieniło, agresywnie reuse’uj cache’e i rezerwuj wolne checki na momenty, gdy naprawdę wnoszą wartość.

Krok po kroku: wybierz strategię repo, która pasuje do zespołu

Decyzja jest prostsza, gdy zaczynasz od codziennej pracy, a nie ideologii.

1) Zapisz, co musi zmieniać się razem

Wybierz 5–10 ostatnich funkcji i zanotuj, co musiało iść synchronicznie. Zaznacz, czy każde dotyczyło ekranów UI, endpointów API, tabel danych, reguł uwierzytelniania czy współdzielonej walidacji. Jeśli większość funkcji wymaga koordynowanych zmian we wszystkich trzech obszarach, rozdzielenie repo będzie bolesne, chyba że proces wydań jest bardzo zdyscyplinowany.

2) Prześledź kod i decyzje współdzielone

Kod współdzielony to nie tylko biblioteki. To też kontrakty (schematy API), wzorce UI i reguły biznesowe. Zanotuj, gdzie one dziś żyją, kto je edytuje i jak zatwierdzane są zmiany. Jeśli kawałki są kopiowane między repo, to sygnał, że potrzebujesz większej kontroli—albo przez monorepo, albo przez ścisłe reguły wersjonowania.

3) Zdefiniuj granice i właścicieli

Zdecyduj, jakie są jednostki (aplikacje, serwisy, biblioteki), a potem przypisz właściciela do każdej. Granice są ważniejsze niż układ repo. Bez właścicieli monorepo staje się hałaśliwe. Bez właścicieli polyrepo odpada spójność.

Jeśli chcesz prostą checklistę, dąż do: jedno repo lub folder na każdy deployowalny serwis/aplikację, jedno miejsce na kontrakty współdzielone, jedno miejsce na naprawdę współdzielone komponenty UI, jasna zasada gdzie żyje logika biznesowa i udokumentowany właściciel dla każdej z części.

4) Wybierz model wydań, którego będziecie przestrzegać

Jeśli wydania mobilne odstają, potrzebujesz planu kompatybilności (wersjonowane API, pola kompatybilne wstecz albo zdefiniowane okno wsparcia). Jeśli wszystko musi pójść razem, pociąg wydań może działać, ale zwiększa koordynację.

Trzymaj zasady branchowania proste: krótkotrwałe branche, małe merge’e i jasna ścieżka hotfixów.

5) Projektuj CI wokół częstych zmian

Nie projektuj CI pod najgorszy przypadek od razu. Projektuj go pod to, co ludzie robią na co dzień.

Jeśli większość commitów rusza tylko web UI, domyślnie uruchamiaj lint i testy jednostkowe webu, a pełne testy end-to-end odpalaj według harmonogramu lub przed wydaniem. Jeśli najwięcej incydentów wynika z dryfu API, zainwestuj najpierw w testy kontraktów i generację klientów.

Przykład: jedna funkcja dotykająca web, mobile i backend

Wyobraź sobie mały zespół budujący trzy rzeczy naraz: portal klienta (web), aplikację terenową (mobile) i API (backend). Przychodzi prośba: dodaj nowe pole „Service status” do zleceń i pokaż je wszędzie.

Zmiana brzmi niewinnie, ale to test koordynacji. Backend dodaje pole i aktualizuje walidację oraz odpowiedzi. Web je wyświetla i poprawia filtry. Mobile musi je pokazać offline, zsynchronizować i obsłużyć krawędziowe przypadki.

Prawdziwy problem: zmiana API jest łamiąca. Nazwa pola zmienia się z status na service_status, a stare klienty padają, jeśli tego nie obsłużą.

Co zmienia monorepo

W tym miejscu monorepo często wydaje się spokojniejsze. Aktualizacje backendu, webu i mobile mogą wylądować w jednym pull requeście (albo jednym zestawie skoordynowanych commitów). CI może uruchomić dotknięte testy i możesz oznaczyć jedno wydanie, które zawiera wszystkie trzy aktualizacje.

Główne ryzyko jest społeczne, nie techniczne: jedno repo ułatwia szybkie merge’owanie zmian łamiących, więc zasady przeglądu muszą być mocne.

Co zmienia polyrepo

W repozytoriach oddzielnych każda aplikacja żyje na własnym harmonogramie. Backend może wypłynąć pierwszy, a web i mobile będą się śpieszyć, żeby nadążyć. Jeśli wydania mobilne wymagają review w sklepie, „naprawa” może zająć dni, nawet gdy zmiana kodu jest drobna.

Zespoły zwykle rozwiązują to bardziej formalnie: wersjonowane endpointy, odpowiedzi kompatybilne wstecz, dłuższe okna deprecjacji i klarowne kroki rolloutu. Działa, ale wymaga stałej pracy.

Jeśli decyzję chcesz podejmować na podstawie dowodów, sprawdź ostatnie miesiące:

• Jeśli incydenty często wynikają z niedopasowanych wersji, postaw na ścisłą koordynację.
• Jeśli wydania są częste i krytyczne (zwłaszcza mobile), unikaj zmian łamiących albo je centralizuj.
• Jeśli zespoły są niezależne i rzadko dotykają tych samych funkcji, koszty polyrepo mogą być do przyjęcia.

Typowe pułapki i błędy do uniknięcia

Większość zespołów nie zawodzi, bo wybrała „złą” strukturę repo. Zawodzi, bo codzienne nawyki stopniowo dodają tarcie, aż każda zmiana wydaje się ryzykowna.

Kod współdzielony staje się składzikiem

Biblioteka współdzielona kusi: helpery, typy, elementy UI, „tymczasowe” obejścia. Wkrótce staje się miejscem, gdzie stare rzeczy się chowają i nikt nie wie, co bezpiecznie zmieniać.

Trzymaj kod współdzielony mały i rygorystyczny. „Współdzielone” powinno znaczyć: używane przez wiele zespołów, przeglądane ostrożnie i zmieniane świadomie.

Ścisłe powiązania przez ukryte założenia

Nawet w oddzielnych repo systemy mogą być silnie sprzężone. Sprzężenie po prostu przenosi się w założenia: format daty, wartości enumów, reguły uprawnień, „to pole zawsze jest obecne”.

Przykład: mobile traktuje status = 2 jako „Zatwierdzony”, web jako „Potwierdzony”, backend zmienia kolejność enumów i wszystko psuje się w sposób wyglądający na losowy.

Zapobiegaj temu przez dokumentowanie kontraktów (co pola znaczą, jakie wartości są dozwolone) i traktowanie ich jak reguły produktowe, a nie drobiazgi.

Niejasna własność

Gdy każdy może zmieniać wszystko, przeglądy stają się płytkie i błędy przechodzą. Gdy nikt nie jest właścicielem, bugi zalegają tygodniami.

Zdefiniuj właścicieli dla web, mobile, backend i modułów współdzielonych. Własność nie blokuje wkładu—zapewnia właściwe spojrzenie na zmiany.

CI rośnie bez przycinania

CI często zaczyna mały, potem każdy incydent dodaje nowe zadanie „na wszelki wypadek”. Po miesiącach jest wolne i kosztowne, a ludzie go unikają.

Prosta zasada pomaga: każde zadanie CI musi mieć jasny cel i właściciela, a powinno być usunięte, gdy przestaje łapać realne problemy.

Znaki ostrzegawcze, że trzeba posprzątać: duplikujące się testy w zadaniach, zadania, które są czerwone przez dni, „szybkie zmiany” trwają dłużej niż budowanie i pipeline’y, które uruchamiają mobile build dla zmian tylko w backendzie.

Koordynacja wydań oparta na wiedzy plemiennej

Jeśli wydania zależą od jednej osoby pamiętającej kolejność i ukryte pułapki, będziesz wypuszczać wolniej i częściej łamać rzeczy.

Zapisz kroki wydania, uczynij je powtarzalnymi i zautomatyzuj nudne checki. Nawet jeśli narzędzia generują spójne backendy i klientów, nadal potrzebujesz jasnych reguł wydań.

Szybkie kontrole zanim zmienisz strukturę repo

Zanim zreorganizujesz repo, sprawdź, jak zespół rzeczywiście wysyła zmiany. Cel nie jest w doskonałej strukturze. To mniej niespodzianek, gdy jedna zmiana dotyka web, mobile i backend.

Zadaj pięć pytań:

• Niezależne wydania: Czy możesz wypuścić poprawkę backendu bez przymuszania do aktualizacji aplikacji mobilnej tego samego dnia?
• Zasady zmian API: Czy macie zapisane reguły dla deprecjacji i jak długo stare zachowanie będzie wspierane?
• Dyscyplina kodu współdzielonego: Czy biblioteki współdzielone są przeglądane i wersjonowane spójnie?
• CI, które uruchamia to, co ważne: Czy CI potrafi określić, co się zmieniło i uruchomić buildy/testy tylko dla dotkniętych części?
• Jedno widzenie wydań: Czy jest jedno miejsce, gdzie widać, co trafia na produkcję w web, mobile i backend, z właścicielami i terminami?

Prosty przykład: dodanie nowego pola „address” do checkoutu. Jeśli backend wypłynie pierwszy, stara aplikacja mobilna powinna nadal działać. Zazwyczaj oznacza to, że API akceptuje oba kształty payloadu przez pewien czas, a aktualizacje klienta są opcjonalne, nie obowiązkowe.

Następne kroki: zmniejsz koszty koordynacji i wypuszczaj z pewnością

Celem nie jest „właściwa” struktura repo. Celem jest mniej przekazań, mniej niespodzianek i mniej „czekaj, która wersja jest live?” momentów.

Zapisz krótką decyzję: dlaczego wybraliście obecną drogę, co chcecie poprawić i jakie kompromisy akceptujecie. Przeglądaj ją co 6–12 miesięcy albo szybciej, jeśli zmienia się rozmiar zespołu lub rytm wydań.

Zanim przeniesiesz pliki, wybierz najmniejszą zmianę, która usuwa realny ból:

• Dodaj i stosuj zasady wersjonowania dla współdzielonych pakietów.
• Zdefiniuj kontrakty API i wymuś ich testy kontraktowe w CI.
• Uzgodnij jedną checklistę wydania dla web, mobile i backend.
• Używaj środowisk podglądowych dla zmian przekrojowych.
• Ustal budżet czasu CI (np. checki PR poniżej 15 minut).

Jeśli sprzężenie między bazami kodu jest prawdziwym wąskim gardłem, zmniejszenie liczby miejsc, które trzeba zmieniać, może być ważniejsze niż układ repo. Niektóre zespoły robią to, przenosząc więcej logiki i modelowania danych do jednego źródła prawdy.

Jeśli chcesz to sprawdzić, AppMaster (appmaster.io) jest zbudowany tak, by generować usługi backendowe, aplikacje web i natywne aplikacje mobilne ze współdzielonymi modelami danych i logiką biznesową. Niskoryzykowny sposób oceny to zbudować jedno małe narzędzie wewnętrzne najpierw, a potem zdecydować na podstawie tego, ile pracy koordynacyjnej to usunie.

Pewna ścieżka jest celowo nudna: udokumentuj decyzję, zmniejsz sprzężenia, zautomatyzuj checki i zmieniaj strukturę repo tylko wtedy, gdy liczby pokażą, że to pomoże.