Bezpieczny refaktoring modułów: zachowuj zachowanie | Praktyki IT

# Refaktoryzacja bez ryzyka: jak wydzielać moduły, zachowując zachowanie

Przy przenoszeniu modułu z monolitu do osobnego serwisu główne zadanie to zachować zachowanie dosłownie, włącznie z znanymi błędami i niedokumentowanymi cechami. Próby „upiększenia” kodu na tym etapie często prowadzą do regresji. Opowiadamy, jak uniknąć pułapek, stosując strategię minimalnych zmian.

Dlaczego „nudne” podejście chroni przed regresjami

W systemach produkcyjnych istnieje niejawny kontrakt ukształtowany latami pracy: integracje klienckie, obsługa błędów, opóźnienia czasowe, adaptacja do cudzych API. Ten kontrakt nie jest opisany w dokumentacji — jest zakodowany w logach, commitach i doświadczeniu zespołu. Refaktoryzacja nie powinna zmieniać zachowania, nawet jeśli zawiera błędy. Na przykład, jeśli stary kod zwraca pusty ciąg zamiast null, zmiana tego zachowania zepsuje klientów, którzy już się do tej logiki dostosowali. Kluczowa zasada: zadanie wydzielenia to zmiana formy, ale zachowanie semantyki. Jakiekolwiek odchylenie od oryginalnego zachowania zamienia refaktoryzację w wydanie z nieznanymi konsekwencjami.

Jeden typ zmian na raz: granice przed wewnętrzną strukturą

Podziel zadania na etapy:

• Etap A: wydzielenie modułu z zachowaniem kontraktu (HTTP, kolejka, szyna) i wdrożenie feature flag.
• Etap B: aktualizacja stosu, bibliotek lub stylu kodu.
• Etap C: naprawa błędów.
• Etap D: optymalizacja wydajności.

Mieszanie etapów w jednym PR to prosta droga do nieczytelnego diffu, problemów z rollbackiem i sporów „to błąd czy nowa funkcja?”. Na pierwszym etapie użyj wrappera wokół starego kodu: nowa granica serwisu, stara logika w środku. Na przykład, przy wydzielaniu modułu routingu zostaw oryginalną funkcję route(), ale owiń ją w HTTP-endpoint. To gwarantuje, że zachowanie pozostanie identyczne, nawet jeśli kod wygląda „brzydko”.

Feature flag: twój awaryjny wyłącznik

Równoległe istnienie starego i nowego kodu w produkcji wymaga przełącznika sterowanego przez konfigurację lub zmienne środowiskowe. To daje:

• Możliwość natychmiastowego rollbacku bez dep loyu w razie incydentu.
• Stopniowe wdrażanie na część ruchu (canary release).
• Długotrwałe zachowanie starej implementacji do porównania zachowania.

Krytycznie ważne, by przełącznik działał bez restarty serwisu. Inaczej incydent w godzinach nocnych zamieni się w pilną wideokonferencję zamiast prostego zmiany konfiguracji. Zaimplementuj flagę na poziomie logiki biznesowej, a nie infrastruktury — tak unikniesz skomplikowanych zależności od orkiestratorów.

Kopiuj zachowanie, a nie przepisuj

Instrukcja do bezpiecznego przeniesienia: kopiuj pliki „jak jest”, zmieniając tylko to, co niezbędne do kompilacji. Przykład z praktyki — przeniesienie routingu z aktora do czystej funkcji:

object UpdateRouting {
  def route(update: Update): Either[RoutingError, RouteTarget] =
    if (update.message.exists(_.chat.isGroupOrSupergroup)) Right(GroupFlow)
    else if (update.callbackQuery.isDefined) Right(CallbackFlow)
    else Right(PrivateFlow)
}

Przy mapowaniu modeli zachowaj nawet nieoczywiste detale. Jeśli stary kod przekształcał brakujący channelId na pusty ciąg, rób to samo:

def toBusMessage(in: PlatformInMessage): BusIncoming =
  BusIncoming(
    correlationId = newCorrelationId(),
    channelId = in.channelId.getOrElse("")
  )

Jakikolwiek zmiana semantyki (np. zamiana pustego ciągu na null) naruszy kontrakt z innymi serwisami. Twoim celem jest zachowanie identyczne bit w bit, nawet jeśli kod wygląda przestarzały.

Czego absolutnie nie robić na etapie wydzielania

Dopóki aktywny jest feature flag, unikaj:

• Nowych bibliotek. Każda dodaje zależności tranzytywne i powierzchnię ataku. Aktualizacja stosu to osobne zadanie.
• Zmiany stylu kodu. Mieszanka starego domeny i nowej otoczki to tymczasowa cena za bezpieczeństwo.
• Naprawiania znalezionych błędów. Załóż ticket i rozwiąż po ustabilizowaniu. Inaczej każdy incydent przypiszą do refaktoryzacji.
• Optymalizacji „skoro już otworzyliśmy plik”. Profilerowanie i przyspieszanie to osobny cykl prac.

Te ograniczenia wydają się nadmierne, ale po pół roku w git blame zobaczysz klarowną historię: „wydzieliliśmy moduł, podłączyliśmy szynę”, a nie „przepisaliśmy wszystko po kolei”.

Testy: utrwalenie kontraktu, a nie KPI

Unit testy na czystych funkcjach (routing, mapowanie) powinny utrwalać zachowanie przed przeniesieniem. Zielony test po wydzieleniu gwarantuje, że logika się nie zmieniła. Dla scenariuszy integracyjnych (sieć, kolejki, BD) używaj testów E2E, ale pamiętaj o ich ograniczeniach:

• Moki zewnętrznych systemów mogą odtwarzać błędne założenia z kodu.
• Rzeczywisty API czasem zawiera nieoczywiste niuanse (np. prefiks /api/), których nie uwzględniają testy.

Obowiązkowo dodaj ręczny przebieg na środowisku zbliżonym do produkcyjnego. Automatyzacja nie zastąpi sprawdzeń w warunkach maksymalnie zbliżonych do rzeczywistych.

Wzrost kodu to nie błąd, a etap procesu

Po pierwszym etapie objętość kodu często rośnie: pojawiają się adaptery, feature flagi, duplikaty z monolitem. To normalne — płacisz za bezpieczeństwo rollbacku i etapowego wdrożenia. Kompresja i czyszczenie przychodzą na drugim etapie, gdy granica jest ustabilizowana, stary kod usunięty, a testy potwierdzają poprawność. Nie próbuj optymalizować od razu — najpierw zapewnij działanie.

Co ważne

• Cel wydzielenia — przeniesienie zachowania „as is”, a nie kompleksowa poprawa.
• Feature flag obowiązkowy do bezpiecznego rollbacku bez dep loyu.
• Testy utrwalają kontrakt przed rozpoczęciem przeniesienia, a nie po.
• Zakaz równoległych zmian stosu, poprawek błędów i optymalizacji.
• Kod może rosnąć — to część strategii, a nie błąd.

Refaktoryzacja legacy kodu to nie miejsce na eksperymenty. Im nudniejszy proces, tym mniejsze szanse, że o 3 w nocy obudzą cię z powodu awarii produkcji. Stosując te zasady, zamienisz ryzykowny transfer w przewidywalną operację.

— Editorial Team