Drabina dostosowań
Potrzebujesz, żeby platforma działała inaczej. Można to zrobić na sześć sposobów; są uporządkowane, a każdy kosztuje więcej niż poprzedni. Zacznij od najniższego stopnia.
Autor, który nie zna tej listy, sięga po najsilniejszy dostępny punkt rozszerzenia. To nie
przypuszczenie o ludziach — dokładnie tak się tu stało i dlatego istnieje ForeignDecorationError.
Trzy rzeczy sprawiają, że ta lista naprawdę obowiązuje, a nie tylko dobrze wygląda:
- Każda rozbieżność, którą wprowadzasz, ma przypisany stopień we własnym, generowanym raporcie
wdrożenia (
backend/src/apps/<deployment>/divergence.generated.md), więc to, że ktoś wielokrotnie ląduje na wysokim stopniu, da się zmierzyć, a nie tylko opowiedzieć. Ścieżki na tej stronie dotyczą tego repozytorium; w instancji utworzonej przeznpx create-endora-commercete same pliki leżą wapps/<deployment>/w katalogu głównym instancji, a raport generujepnpm run generate. - Każda odmowa wskazuje niższy stopień, który zadziała, więc jeśli sięgniesz za wysoko, platforma w tej samej chwili powie ci, po co sięgnąć zamiast tego.
- Stopień, z którego nie możesz skorzystać, mówi to wprost. Stopień 3 nie jest dostępny dla wdrożenia, które chce podstawić własną implementację, i ta strona to mówi, zamiast wymieniać go jako opcję, o której zamknięciu przekonasz się dopiero przy próbie.
Dwa pytania, a nie jedno
„Ile to kosztuje?” i „czy wolno mi to zrobić?” to dwa różne pytania. Pomieszanie ich sprawiło, że poprzednia wersja tej listy była błędna.
| moduł rdzenia | moduł nakładkowy twojego wdrożenia | zainstalowany pakiet | |
|---|---|---|---|
| działanie we własnym obszarze | tak | tak | tak |
| działanie w obszarze innego modułu, na jego zaproszenie | tak | tak | tak |
| działanie w obszarze innego modułu bez zaproszenia | nie | tak, bez ograniczeń | nie |
Środkowy wiersz to stopnie 1–3: punkt rozszerzenia opublikowany przez właściciela, w którym jesteś gościem. Dolny wiersz to stopień 4 i ma go wyłącznie wdrożenie — bo wdrożenie jest jedynym właścicielem swojej instancji: zmienia własne drzewo, buduje obraz i nie odpowiada przed nikim poza sobą.
Każdą odpowiedź na pytanie „kto może” na tej stronie egzekwuje istniejące zabezpieczenie
(ForeignDecorationError, PackageDecorationNotOfferedError, DuplicateRegistrationError,
ForeignRegistrationError), a nie ta tabela.
Stopień 0 — konfiguracja
Mechanizm. Ustawienie zadeklarowane przez moduł, na ekranie /settings. Pola niestandardowe
definiowane w czasie działania — gdy trzeba „dodać pole”. Graf statusów zamówienia. Aktywacja
przez operatora na /platform/modules.
Koszt. Żaden. Przetrwa każdą aktualizację, bo to dane.
Co się traci. Nic.
Kto. Każdy, także operator bez programisty.
Kiedy to jest odpowiedź. Zawsze, gdy wymaganie brzmi „ta wartość ma być tu inna” albo „dodaj pole”. Większość próśb, które przychodzą jako „zmień kod”, kończy się właśnie tutaj, a autor, który najpierw nie sprawdził stopnia 0, jeszcze nie zaczął pracy.
Stopień 1 — subskrypcja zdarzeń, które właściciel już emituje
Mechanizm. ctx.subscribe('<event>', handler), rejestrowane w backend.ts twojego modułu —
nigdy w treści pluginu.
Koszt. Sam punkt rozszerzenia nic nie kosztuje. Subskrypcja zależy od faktycznego stanu twojego modułu, więc wyłączenie modułu ją zatrzymuje.
Co się traci. Nic. Obserwujesz; nie zmieniasz tego, co zrobił właściciel.
Kto. Każdy.
Kiedy to jest odpowiedź. Dodatkowa praca wywołana czymś, co już się wydarzyło: powiadomienie, kopia danych, wzbogacenie systemu dalej w łańcuchu, zapis własnego wiersza.
Platforma emituje zdarzenia w 46 miejscach i żaden manifest modułu ich nie deklaruje, więc na
pytanie „co mogę subskrybować?” można dziś odpowiedzieć tylko czytając kod źródłowy platformy —
czego klient instalujący pakiety zrobić nie może. Naprawą jest blok events w manifeście modułu, w
takiej samej postaci, jaką mają już permissions i actions; to zmiana obejmująca wszystkie moduły
i nie została jeszcze zbudowana. Ten stopień istnieje, ale trudno go odkryć — i ta strona mówi
to wprost, zamiast zostawiać to do samodzielnego odkrycia.
Subskrybent działa po zatwierdzeniu transakcji i nie może zmienić ani odrzucić tego, co zostało zapisane. Aby działać wewnątrz zapisu właściciela — dodać własny wiersz w tej samej transakcji albo zapis odrzucić — użyj hooka polecenia, czyli stopnia 2 (2b poniżej).
Stopień 2 — kod przed tym, co właściciel już obsługuje, albo po tym
Dwa mechanizmy, jeden stopień: wokół endpointu (2a) albo wewnątrz zapisu (2b). Oba są opublikowanym identyfikatorem, który właściciel wersjonuje, i oba mogą odmówić.
2a — interceptor API
Mechanizm. ctx.interceptors([{ id, target, phase, order, handler }]). Celem jest stały
identyfikator endpointu "<METHOD> <route pattern>" — wzorzec dokładnie taki, jaki rejestruje
właściciel (/api/v1/orders/:id, nigdy konkretne id).
Koszt. Powiązanie z identyfikatorem endpointu, który jest publicznym API i podlega
wersjonowaniu. order ma udokumentowaną regułę rozstrzygania remisów; rejestracja po gotowości
serwera jest odrzucana; wykonanie zależy od tego, czy twój moduł jest włączony; rejestr potrafi
wypisać cały plan wykonania.
Co się traci. Nic strukturalnie. Interceptor pre może zablokować żądanie, rzucając
zarejestrowany błąd; interceptor post nie może niczego zapisywać, bo własny zapis endpointu mógł
już zostać zatwierdzony.
Kto. Każdy, również wobec cudzych modułów. To najsilniejszy punkt rozszerzenia, jaki ma ktoś z zewnątrz — i po niego warto sięgnąć, zanim poprosi się właściciela o cokolwiek.
Kiedy to jest odpowiedź. Gdy trzeba zmienić to, co trafia do istniejącego endpointu albo z niego wychodzi; dodać pole do odpowiedzi; odrzucić żądanie według własnej reguły.
Rejestr przyjmuje taki cel bez słowa. W czasie działania nic cię o tym nie poinformuje. Kontrola
rozbieżności twojego wdrożenia porównuje każdy cel z tabelą tras i przerywa build błędem
unmatched-interceptor-target — i tylko ona to wychwyci.
2b — hook polecenia
Mechanizm. ctx.commandHooks([{ id, on, phase: 'beforeCommit', handler }]), gdzie on to
referencja, którą właściciel publikuje w @endora-commerce/contracts dla polecenia zadeklarowanego
jako dostępne dla hooków (ORGANIZATION_HOOKABLE_ACTIONS.register). Hook działa wewnątrz transakcji
właściciela, po jego zapisie i przed jego wpisem audytu. Szczegóły są na stronie
Command Bus.
Koszt. Powiązanie z akcją dostępną dla hooków i kształtem jej danych — to publiczne API, które właściciel wersjonuje — oraz zależność od właściciela w twoim manifeście. Hook trzyma otwartą transakcję właściciela przez cały czas działania, więc nie wywołuje usług zdalnych.
Co się traci. Nic strukturalnie. Zapis właściciela, jego jedyny wpis audytu i sama szyna
poleceń pozostają właściciela: hook może dodać własne wiersze (we własnych tabelach albo przez
polecenie uruchomione ctx.run) i odrzucić cały zapis — nic więcej.
Kto. Każdy, również wobec cudzych modułów — moduły rdzenia, moduły nakładki twojego wdrożenia i
zainstalowane pakiety — ale tylko na akcjach, które właściciel zadeklarował. Hook na niezadeklarowanej
akcji, dwa nieuporządkowane moduły z hookami na jednej akcji albo moduł z hookiem, który nie zależy od
właściciela, przerywają kompozycję przy starcie. Kolejność dwóch niezależnych modułów z hookami
ustala twoje wdrożenie w divergence.ts (commandHookOrder).
Kiedy to jest odpowiedź. Własna reguła, która musi obowiązywać przy każdym zapisie rekordu, niezależnie od endpointu czy portu, przez który przyszedł; własne dane, które muszą zostać zatwierdzone razem z wierszem rdzenia albo wcale.
Stopień 3 — port strategii opublikowany przez właściciela
Mechanizm. Właściciel publikuje nazwany port przez ctx.di.providePort, a jeśli celem jest
możliwość podstawienia implementacji, publikuje też interfejs w ścieżce ./ports swojego pakietu,
zawierającej wyłącznie typy. Ty pobierasz port przez lazyPort<T>(ctx, '<literal>') i deklarujesz
zależność w swoim manifeście.
Koszt. Krawędź zależności w manifeście — i właśnie dzięki niej ta zależność istnieje dla cyklu życia, dla kolejności migracji i dla operatora, który wyłącza właściciela.
Co się traci. Nic. Właściciel zachowuje punkt rozszerzenia i dalej go poprawia za ciebie.
Kto — przeczytaj to, zanim cokolwiek na tym zaplanujesz.
Wdrożenie nie może dostarczyć strategii na tym stopniu.
ctx.di.providePort zajmuje nazwę, a próba jej zajęcia jest odrzucana, gdy właścicielem jest już
inny moduł — i nie ma tu wyjątku dla nakładki. Nie ma też opublikowanych, a
niezaimplementowanych portów, które czekałyby na implementację. Ten stopień działa więc tylko w
jedną stronę: konsument może pobrać dowolny opublikowany port, a twój raport zapisuje to jako
port-consumed. Wdrożenie, które chce podstawić implementację, nie ma tu żadnego mechanizmu i
musi skorzystać ze stopnia 4.
Co to dla ciebie oznacza. Poproś właściciela o port. Powtarzające się lądowanie na stopniu 4 z tym samym problemem to informacja zwrotna dla produktu, że ten punkt rozszerzenia powinien trafić do rdzenia jako port stopnia 3 — i właśnie oznaczenia stopni w raporcie czynią to mierzalnym.
Kształt opublikowanego portu jest typem kontraktu, nigdy twoją własną klasą; nazwa w kontenerze podana w jego bloku dokumentacji jest częścią kontraktu i pilnuje jej kontrola; a opcjonalna metoda w opublikowanym porcie jest odrzucana, bo proxy rozwiązujące port odpowiada funkcją na każdą właściwość i wykrywanie funkcji przez nie jest z założenia niemożliwe.
Stopień 4 — zmiana tego, co wydaje kontener
Dwa mechanizmy na jednym stopniu; drugi ma szerszy zasięg.
4a — dekoracja
Mechanizm. ctx.di.decorate<T>('<name>', (inner) => …) z własnego modułu nakładkowego
wdrożenia. Opakuj i deleguj; nie zastępuj.
Koszt. Powiązanie z wersją kontraktu, którego kształtu nikt za ciebie nie sprawdza.
ctx.di.decorate<T> przyjmuje T jako założenie w miejscu wywołania i z niczym go nie porównuje,
więc kształt opakowywanego obiektu deklaruje się strukturalnie, a rozjazd interfejsu jest
niespodzianką w czasie działania, a nie błędem budowania. Najtańszy sposób na odzyskanie kontroli
to opublikowanie interfejsu przez właściciela w ścieżce ./ports i importowanie go stamtąd przez
twoją nakładkę.
Co się traci. Automatycznie nic, o ile delegujesz — poprawka rdzenia w opakowanej metodzie nadal do ciebie dociera. Wszystko, jeśli zastępujesz: zastąpienie na stałe przecina delegację.
Kto. Wyłącznie moduł nakładkowy wdrożenia, za to bez ograniczeń: może opakować wszystko, co
jest w kontenerze, łącznie z nazwami, których właścicielem nie jest żaden moduł (commandBus,
auditLogService, eventBus, emFactory). Moduł rdzenia, który opakowuje rejestrację innego
modułu, zostaje odrzucony. Zainstalowany pakiet zostaje odrzucony — a nie tylko odnotowany w
raporcie — bo stawką jest integralność ścieżki audytu.
Dwa twoje moduły nakładkowe opakowujące tę samą nazwę zostaną odrzucone, chyba że wdrożenie zadeklaruje kolejność, od najbardziej wewnętrznego:
// backend/src/apps/<deployment>/divergence.ts
export const divergence: DeploymentDivergenceDeclaration = {
omittedModules: [],
decorationOrder: {
// acme_overlay wraps core; beta_overlay wraps acme_overlay
pricingService: ['acme_overlay', 'beta_overlay'],
},
reasons: { /* … */ },
};
Ta deklaracja jest sprawdzana, nigdy stosowana: composer nadal generuje dekoracje we własnej kolejności, a deklaracja potwierdza, że była to kolejność zamierzona. Deklaracja, która przestaje się zgadzać, powoduje więc odmowę przy kompozycji, zamiast po cichu cokolwiek przestawiać. Jeden moduł dekorujący tę samą nazwę dwa razy nie jest niejednoznaczny — sam napisał oba opakowania, w kolejności, w jakiej je napisał.
4b — plugin główny
Mechanizm. ctx.rootPlugin(reason, plugin) — plugin Fastify montowany na poziomie głównym
serwera, z uzasadnieniem podawanym w wywołaniu.
Koszt i co się traci. Więcej niż w 4a i dlatego dzieli z nim stopień, zamiast leżeć niżej: plugin główny może dodać hooki, które widzą każde żądanie każdego modułu, co jest zasięgiem ściśle szerszym niż opakowanie jednej rejestracji, i jest powiązany z API pluginów Fastify, a nie z kształtem jednej usługi.
Kto. Może go wywołać każdy moduł. Użycie go przez twoje wdrożenie pojawia się w raporcie rozbieżności; użycia przez moduł rdzenia dziś nic nie ocenia — to znana luka, a nie przyzwolenie.
Stopień 5 — fork
Mechanizm. Skopiuj pakiet modułu i utrzymuj go samodzielnie.
Koszt. Wszystko.
Co się traci. Na zawsze wszystkie aktualizacje tego modułu, łącznie z poprawkami bezpieczeństwa. Nie ma delegacji ani drogi powrotnej.
Kto. Każdy, i nie potrzebuje do tego naszej zgody — właśnie dlatego zostało to zapisane. Autor, który robi fork, nie wiedząc o stopniach 0–4, zapłacił najwyższą cenę z tej listy za coś, co załatwiłby stopień 2.
Drabina danych: gdzie trafiają nowe dane
Stopnie powyżej zmieniają zachowanie. Nowe dane mają własną drabinę, uporządkowaną tak samo: zacznij od dołu.
| Stopień | Mechanizm | Kto | Przetrwa aktualizacje, bo |
|---|---|---|---|
| D0 | Pola niestandardowe definiowane w czasie działania — operator definiuje pole encji gospodarza w panelu administracyjnym | operator, w czasie działania | to dane: wiersz definicji i wartość we własnym zbiorze wartości gospodarza |
| D1 | Tabela poboczna, której właścicielem jest twój moduł, kluczowana identyfikatorem wiersza rdzenia i odczytywana przez port twojego modułu | dowolny twój moduł, zainstalowany pakiet | tabela jest twoja; rdzeń jej nie dotyka |
| D2 | Zadeklarowane kolumny rozszerzeń — addytywne kolumny x_<moduleId>_* w rozszerzalnej tabeli rdzenia, deklarowane przez defineColumnExtension | zainstalowany pakiet modułu zależny od gospodarza | platforma generuje DDL, zapisuje je w rejestrze, weryfikuje przy każdej migracji i każdym starcie, a CI rdzenia pilnuje, by każda otwarta rozszerzalna tabela je zachowała |
| D3 | Wariant zapewniany przez moduł-właściciela — typ, status, konfigurowalny kształt, który właściciel już modeluje | decyduje właściciel; ty konfigurujesz | to własny schemat właściciela |
D2 jest celowo wąski. Rozszerzalne tabele to dokładnie tabele gospodarzy pól
niestandardowych — wyprowadzane z rejestru powiązań pól niestandardowych, nigdy z drugiej listy —
a w tym wydaniu otwarta jest tylko organizations (pozostałe osiem dojdzie w późniejszym
wydaniu). Moduł deklarujący jest właścicielem swoich kolumn x_<moduleId>_* i tylko jego kod je
zapisuje, przez akcesor platformy, wewnątrz polecenia (Command) albo hooka polecenia; gospodarz
zachowuje tabelę, jej ograniczenia i wszystkie niezadeklarowane kolumny. Odinstalowanie modułu
pozostawia kolumny (rejestr oznacza je jako osierocone), dopóki operator nie usunie ich
audytowanym poleceniem. Przykład i wszystkie reguły są na stronie
Zadeklarowane kolumny rozszerzeń.
Nigdy nie jest stopniem: nadpisywanie schematu rdzenia. Kolumny, ograniczenia, indeksu ani
klasy encji rdzenia nigdy nie zmienia się spoza ich modułu, a migracja pakietu zapisująca tabelę
innego modułu jest odrzucana przy migrate — przez platformę, nie przez przegląd kodu. Moduł
nakładkowy wdrożenia nie zawiera ani klas encji, ani migracji, a generator odrzuca jedno i drugie:
utwórz tabelę we własnym module (D1) i odczytuj ją z nakładki przez port tego modułu.
Powodem nie jest kolejność migracji — ten argument sprawdzono pomiarem, okazał się fałszywy i został wycofany. Powód jest taki, że wspólny schemat rdzenia to jedyne, co w ogóle umożliwia aktualizacje: D1 i D2 to dwa sposoby dodania schematu, których aktualizacja rdzenia ma obowiązek — sprawdzany — nie zepsuć.
Zarezerwowane i celowo bez numeru: nadpisywanie wkładów modułów
Włączanie i zmiana kolejności wkładów modułu — pozycji w strefie panelu administracyjnego, wpisu
nawigacji, akcji palety poleceń — byłoby osobnym stopniem, poniżej stopnia 2, bo nie zmienia
niczyjego zachowania, tylko to, co jest oferowane. Taki stopień nie istnieje: wkład w strefę ma
wagę, ale nie ma flagi enabled, a wdrożenie nie może zmienić żadnej z tych wartości. Strefa z
czterema wkładami jest uporządkowana wyłącznie według wag wybranych przez ich autorów.
Ten stopień jest tu zarezerwowany i nienumerowany, a nie wymieniony na liście, bo numerowanie nieistniejącego stopnia to dokładnie ten błąd, którego dotyczy powyższa korekta stopnia 3.
Co zmieniłeś i gdzie to przeczytać
Każda rozbieżność wprowadzona przez twoje wdrożenie trafia do dwóch generowanych plików w twoim repozytorium, generowanych ponownie z twojego drzewa i porównywanych bajt po bajcie w CI:
| Plik | Odbiorca |
|---|---|
backend/src/apps/<deployment>/divergence.generated.md | ty, recenzent, osoba aktualizująca platformę, nasze wsparcie |
backend/src/apps/<deployment>/divergence.generated.ts | program i kontrola deterministyczności |
Obok nich jest jedyny plik, który piszesz ręcznie, backend/src/apps/<deployment>/divergence.ts.
Zawiera to, czego nie da się wyprowadzić z drzewa plików: moduły, których nie dostarczasz,
kolejność opakowywania, gdy dwa twoje moduły nakładkowe dekorują tę samą nazwę, kolejność dwóch
modułów z hookami poleceń, których nie porządkuje żadna zależność, oraz po jednym zdaniu
uzasadnienia dla każdej rozbieżności.
Oba zestawy są porównywane w obie strony. Build kończy się błędem zarówno przy rozbieżności bez uzasadnienia, jak i przy uzasadnieniu rozbieżności, której już nie ma — bo właśnie tak wdrożenie po cichu odzyskuje ryzyko, które kiedyś zadeklarowało.
Uzasadnienie, które będzie warto przeczytać za półtora roku, mówi, co robi rdzeń i co zamiast tego robi twoje wdrożenie. Uzasadnienie podające tylko to drugie to pół zdania, a „nie potrzebujemy tego” w ogóle nie jest uzasadnieniem.
Zobacz też: Wzorzec nakładki.