Ocena zadłużenia w projektowaniu schematów GraphQL za pomocą LLM i mechanizmu CI Ratchet

Schemat GraphQL, który jest modyfikowany przez dziesiątki lub setki inżynierów w różnych obszarach produktowych, ulega dewiacjom, bez względu na to, jak dobry jest przewodnik stylu. Narzędzia do sprawdzania kodu wykrywają problemy mechaniczne, ale te najtrudniejsze wymagają osądu: String, który powinien być typem enum, lista, która rośnie bez ograniczeń, pole typu nullable, które w rzeczywistości nigdy nie zwraca wartości null. Ten artykuł opisuje dwuczęściowy system rozwiązujący takie problemy: narzędzie wspomagane przez LLM, które zapobiega powstawaniu nowych długów projektowych już na etapie zgłoszenia zmian, oraz system oceniania istniejącego schematu, który przekształca stare długi w uporządkowany, śledzalny zestaw zadań kontrolowany przez mechanizm CI.

Dlaczego jakość API staje się problemem systemowym

Z garstką inżynierów spójna API to przede wszystkim kwestia wspólnego gustu. Ludzie pracują blisko siebie, sprawdzają wzajemne zmiany w schematach i dochodzą do tych samych rozwiązań. Gdy organizacja rośnie, to przestaje działać. Ciągle wprowadzane są nowe funkcje, starsze konwencje współistnieją z nowszymi, a decyzje, które wydawały się oczywiste dla początkowego zespołu, są interpretowane inaczej przez zespoły, które ich nigdy nie spotkały.

W tym momencie trzy pytania wymagają odpowiedzi, które nie zależą od uwagi żadnego pojedynczego recenzenta:

• Jak utrzymać spójność projektu API, gdy wiele zespołów edytuje schemat równocześnie?
• Jak upewnić się, że nowe typy i pola spełniają aktualne najlepsze praktyki?
• Jak znaleźć te części API, które zostały zaprojektowane przed pojawieniem się tych praktyk?

Pierwsze dwa dotyczą profilaktyki. Trzeci dotyczy archeologii i to właśnie go najczęściej pomijają działania związane z zarządzaniem.

Gdzie kończą się reguły lintera, a zaczyna się osąd

Znaczna część standardów API ma charakter mechaniczny, a statyczna analiza radzi sobie z nimi dobrze. Konwencje nazewnicze, używanie przestarzałych pól, obowiązkowe opisy oraz spójna forma błędów to wszystko właściwości typu „tak” lub „nie” w schemacie: pole albo przestrzega reguły, albo nie, a linter może określić, które to jest.

Inne standardy nie da się sprowadzić do prostej reguły. Typowe przykłady:

• Czy ten String powinien być typem enum?
• Czy ta lista powinna być paginowana?
• Czy ten Int powinien być dostosowanym skalarem?
• Czy to pole typu nullable może bezpiecznie stać się nie-null?
• Czy ta forma odpowiada sposobowi modelowania podobnych koncepcji w innych częściach API?

Żaden z tych przypadków nie ma odpowiedzi wolnej od kontekstu. Zwrócenie String, a nawet nietypowanego bloku JSON, bywa czasami poprawne. Aby ustalić, czy jest to poprawne, należy razem rozważyć trzy elementy: deklarację schematu, implementację narzędzia do rozwiązywania problemów za nią stojącą oraz intencję ujawnienia tych danych klientom. Tylko biorąc pod uwagę wszystkie trzy elementy, można ocenić, jaka forma najlepiej służy klientom.

Organizacje zazwyczaj radzą sobie z tym poprzez przegląd kodu, spotkania z zespołem platformy oraz pisemne wytyczne. To działa, ale słabo skaluje się to w większych projektach. Presja czasu skraca czas przeglądów, zespół platformy nie może przeanalizować każdej zmiany w schemacie we wszystkich repozytoriach, a najlepsze praktyki rozwijają się szybciej, niż stare API są ponownie sprawdzane. Skutkuje to dwoma powiązanymi problemami: zapobieganiem nowym długom projektowym oraz wykrywaniu tych, które już istnieją.

Przesunięcie na lewo: narzędzie LLM do przeglądania zmian w schematach

Pierwsza połowa systemu przekształca wytyczne projektowe API w automatycznego agenta do przeglądania kodu. Celem nie jest zastąpienie ludzkich recenzentów, lecz dostarczenie im dodatkowej pary oczu do sprawdzania dokładnie tych kwestii, które umykają podczas standardowej oceny pull requestów. Osobiste zatwierdzanie każdej zmiany w GraphQL przez zespół platformy we wszystkich repozytoriach nie jest skalowalne; natomiast wdrożenie preferowanych standardów do agenta AI działającego wszędzie takie rozwiązanie jest.

Ponieważ agent widzi coś więcej niż tylko różnice w schemacie, może analizować kontekst, a nie tylko składnię. Czyta deklarację, implementację odpowiadającą za dane pole oraz odpowiedni tekst zasad, a następnie formułuje konkretne pytania. Dwa przykładowe komentarze:

• Pole o nazwie updatedAt jest deklarowane jako String. Jeśli narzędzie rozwiązywania zwraca datę w formacie ISO 8601, powinno raczej użyć dedykowanego skalaru ISO8601DateTime.
• Company.employees zwraca zwykłą listę. Zatrudnienie firmy nie ma naturalnego górnego ograniczenia, więc to pole powinno zwracać dane paginowane.

Żadne z tych przypadków nie może zostać pewnie wykryte przez narzędzie do sprawdzania kodu. Zasada mówiąca, że „pole kończące się na At musi być skalarem daty”, generuje fałszywie pozytywne wyniki i pomija pole lastModified; zasada mówiąca, że „wszystkie listy muszą być paginowane”, jest błędna w przypadku pola zwracającego trzy obsługiwane waluty. Sztuczna inteligencja może sprawdzić, co faktycznie robi narzędzie rozwiązywania.

Kluczem jest odpowiedni moment. Wykrycie takich problemów, gdy API jest jeszcze w fazie projektowania, nie kosztuje wiele. Ich wykrycie po tym, jak klienci już przyjęli jego strukturę, oznacza konieczność cyklu wycofywania i migracji.

Spogląd wstecz: ocena istniejącego schematu

Zapobieganie nic nie daje w przypadku już istniejącej powierzchni funkcjonalności, a w dojrzałym API ta powierzchnia jest duża. Część z niej pochodzi sprzed obecnych standardów. Niektóre elementy zawierają kompromisy, które były sensowne w momencie ich wprowadzenia. A inne są po prostu nierówne, ponieważ różne zespoły modelowały ten sam rodzaj koncepcji na swój własny sposób. Potrzebujesz sposobu, by spojrzeć wstecz.

Druga część systemu to proces partijowy, który uzupełnia narzędzia analizy statycznej już przetwarzające schemat. Jego proces obejmuje:

1. Przejrzenie schematu domenę po domenie oraz wybranie pól lub typów, w których wymagana jest subiektywna ocena projektowa.

Zebierz deklarację schematu wraz z odpowiednim kodem implementacji.

Wyślij ten kontekst do modelu LLM w promptzie, który zawiera pisemne zasady projektowania API.

Zapytaj model, czy dane pole wydaje się naruszać jedną z tych subiektywnych zasad.

Zapisz wynik w postaci oceny wraz z pisemnym wyjaśnieniem.

Zagrupuj wyniki według domeny produktu lub zespołu odpowiedzialnego.

Krok 1 ma znaczenie pod względem kosztów i ilości niepotrzebnych informacji. Nie ma powodu, by pytać model o pola, które zostały już sklasyfikowane przez deterministyczną weryfikację; model LLM powinien analizować tylko te kandydaty, w przypadku których rzeczywiście potrzebna jest ocena.

Dlaczego ocena od 1 do 5 jest lepsza niż „przejdzie/nie przejdzie”

Ponieważ chodzi tu o oceny subiektywne, przymuszanie każdego wyniku do binarnej decyzji prowadzi do utraty informacji. Zamiast tego każde pole otrzymuje ocenę od 1 do 5:

• 1: pole wygląda odpowiednio zgodnie z projektem.
• 2: sygnał jest słaby, ale prawdopodobnie nie ma problemu.
• 3: osoba ludzka powinna to sprawdzić.
• 4: pole prawdopodobnie narusza zasady.
• 5: pole to klasyczny przykład wzorca, którego należy unikać.

Aby to uściślić: pole typu String, które przechowuje dowolny tekst napisany przez użytkownika, powinno znajdować się w okolicy wartości 1. Pole typu String o nazwie errorCode, którego mechanizm rozwiązywania może zwracać tylko jedną z trzech ustalonych a priori wartości, powinno znajdować się w okolicy wartości 5, ponieważ jest to w rzeczywistości enum w przebraniu.

Ocena z gradacją dostarcza znacznie bardziej przydatnych informacji niż prosta lista naruszeń. Zespoły mogą zacząć od wyników o wysokim poziomie pewności, takich jak 4 i 5, a jednocześnie zauważyć obszary o niższej pewności, które wymagają dokładniejszego sprawdzenia. Środkowa część skali ma drugie zastosowanie: grupa wyników 3 wskazuje zespołowi platformy, gdzie sformułowanie zasady lub prompt jest niejednoznaczne, co stanowi informację pomocną w udoskonalaniu promptów oceniających, aby dostarczały one bardziej pewnych wyników.

Jeśli tworzysz coś podobnego, poproś model o strukturyzowany wynik (ocenę i wyjaśnienie w oddzielnych polach), aby można było przechowywać i agregować wyniki bez konieczności analizy tekstu, a także utrzymuj wersjonowane teksty zasad oraz kryteria oceny obok promptów, dzięki czemu zmiany w ocenach można będzie powiązać z zmianami w regułach.

Przekształcanie ustaleń w działania

Wartości w bazie danych same z siebie nic nie zmieniają. Ich agregacja według domen w panelu kontrolnym daje każdemu zespołowi odpowiedni obraz zadłużenia projektowego API w jego obszarze: nie są to rozproszone anegdoty czy jednorazowe komentarze z ocen, lecz uporządkowana lista pól i typów, które mogą wymagać migracji.

To same dane umożliwiają postęp w kontekście ciągłej integracji. Celem nie jest naprawa wszystkiego naraz, co jest nierealne w przypadku dużego API obsługującego wiele klientów produkcyjnych. Chodzi o to, by sytuacja nigdy się nie pogorszyła, podczas gdy istniejące problemy są stopniowo eliminowane:

• Nowe zmiany w schemacie muszą odpowiadać obecnym standardom.
• Istniejące problemy są rejestrowane jako znane zadłużenia, zamiast być po cichu ignorowane.
• Gdy zespoły migrują lub odrzucają stare wzorce, dopuszczalny próg zostaje zaostrzony, dzięki czemu ustalone problemy nie mogą powrócić.

Raczety to dobrze znany wzorzec stosowany podczas migracji: rejestruje się aktualną liczbę naruszeń w poszczególnych obszarach, budowa zawodzi się, jeśli jakaś zmiana tę liczbę zwiększa, a zapisana wartość bazowa jest obniżana, gdy ktoś naprawia dany przypadek.

Ten podejście ma największe znaczenie w przypadku publicznych lub szeroko używanych API, gdzie czyszczenie z nieprawidłowości jest uzależnione od migracji po stronie klienta. Wynikiem nie są instrukcje dotyczące usuwania każdego błędnego pola, lecz uporządkowana mapa pokazująca, w których miejscach API już nie spełnia aktualnych standardów, co umożliwia zespołom planowanie działań.

Dlaczego LLM jest odpowiednim narzędziem do tego zadań

LLM nie są doskonałymi oceniaczami projektu API, a system również ich takimi nie traktuje. Ich moc polega tu na innym aspekcie: czytaniu kodu i schematu razem, porównywaniu ich z zasadami sformułowanymi w prostym języku oraz tworzeniu ustrukturyzowanej oceny w przypadkach, których nie da się opisać za pomocą statycznych reguł.

Zasada statyczna może wskazać, że pole zwraca listę. Nie może jednak powiedzieć, czy ta lista rozszerza się wraz z danymi wprowadzanymi przez użytkownika i dlatego wymaga paginacji. Model może odczytać rozwiązanie problemu, porównać je z przykładami w polityce i wyjaśnić, dlaczego pole pasuje lub nie do określonego wzorca.

To wyjaśnienie jest cenniejsze niż liczba do niego przypisana. Gdy pole zostanie oznaczone, zespół odpowiedzialny musi wiedzieć dlaczego, aby szybko ocenić, czy problem jest rzeczywisty, a jeśli tak, jak zaplanować migrację. Ocena bez uzasadnienia tworzy jedynie kolejkę do dalszej analizy.

Ograniczenia, które należy uwzględnić

Przegląd przez LLM nie zastępuje odpowiedzialności za API ani ludzkiej oceny projektu, dlatego warto jasno określić, co pozostaje:

• Nadal występują fałszywie pozytywne wyniki.

Czasami sama implementacja nie ujawnia pełnego obrazu, na przykład gdy ograniczenie znajduje się w innym serwisie.

Ograniczenia produktowe mogą sprawić, że nieidealny kształt stanie się mimo wszystko właściwym kompromisem.

System nie migruje klientów ani nie czyni zmian rozrywających bezpiecznymi. Wykrywa długi technologiczne; zespoły nadal muszą starannie planować i przeprowadzać migracje.

To, co faktycznie oferuje, to skalowalny sposób na ujawnianie wzorców, które wcześniej były ograniczone ilością dostępnej ludzkiej oceny. Wytyczne są kodowane raz, stosowane spójnie we wszystkich repozytoriach, a uzyskane wyniki dostarczają zespołom rzeczowych punktów wyjścia do rozmów projektowych.

Zakończenie

System składa się z dwóch części, które realizują tę samą ideę. Podczas składania prośby o integrację recenzent wykorzystujący model językowy stosuje wytyczne projektowe do nowych zmian w schemacie, zanim klienci od nich będą zależeć. W trybie zbiorczym ten sam system ocenia istniejący schemat od 1 do 5 punktów, wyniki te są agregowane w panelach kontrolnych dla poszczególnych zespołów, a mechanizm CI zapobiega wzrostowi całkowitej liczby punktów w miarę coraz bardziej restrykcyjnych progów. Nie jest to w pełni zautomatyzowane zarządzanie, ani też takie nie jest zamierzone. Umożliwia ono widoczność jakości API w stopniu wystarczającym, aby zespoły mogły podjąć odpowiednie działania, a także dostarcza zespołowi platformy pętli zwrotnej do udoskonalania własnych zasad w miarę rozszerzania tej metody na coraz większe części schematu.

Literatura pokrewna

• Wykorzystanie Qwen3.8-27B na One RTX 3090 z poprawionym vLLM i DFlash2 — Jak wersja vLLM 0.28.0 z dodatkowymi modyfikacjami, użycie requantyzowanych embeddingów oraz technologia DFlash2 umożliwiają uruchomienie modelu hybrydowego o wielkości 27B na karcie pamięci o pojemności 24 GB, oraz dlaczego długi kontekst spowalnia jego działanie.
• Stworzenie osobistego narzędzia do dopracowywania i generowania promptów z użyciem Claude Artifacts — Jak przekształcić jedną rozmowę w Claude w narzędzie do promptów, które można wielokrotnie używać, aby udoskonalić słabe prompty i rozwijać surowe pomysły do wersji podstawowych, zaawansowanych i ekspertowych.