Расчытак дэбта ў дзеянні падараджэння GraphQL схемы за дапамою LLM-ў і CI Ratchet

Схема GraphQL, яююююююю зміняюць дзесяткі чыста сотні інжынероў у разных направленнях продукта, становіцца хаотычной, незалежна ад таго, насколькі хорашы ўказвік стылю. Інструменты лінтингу выяўляюць тэхнічныя проблемы, але найболей значныя выкліканы суб’ектыўнай дагадкай: String, які мяў быць элементам enum, спіс, які продовжвае растаць без меж, абавязкова пустое поле, якое на самай працы ніколі не вяртае значэння null. У этай статыцы описваецца дваэтапная система для такіх случаяў: рэвізор, які апыраецца на LLM і запобегае новым задолжанням у процэсе падачы прашчапкі, а таксама система оцэнкі існуючай схемы, якая ператварае старыя задолжання на прыорітэтызаваны, адстежуемы список задач, які контролюецца за дапамогою інструмента CI ratchet.

Чаму якасць API становіцца проблемай системы

Калі є толькі калька інжынераў, стабільна API ў большай частцы залежыць ад спакойных праганаў усіх учаснікаў. Людзі сядзяць разам, пераглядаюць змены ў схемах і дасягаюць адносна едакіх рашэнняў. Калі організацыя расте, такі падход зьлучваецца. Новыя функцыі дадаюцца постаўна, старэея прыемы сусідзяць з новымі, а рашэнняя, якія здаваліся яснымі для пачатковай команды, прымаюцца інакша камандамі, якія ніколі зь імі не зустрэліся.

У такі момент трэба атрымаць адказы на тры пытанні, якія не залежаць ад увагі жаднага конкрэтнага пераглядача:

• Як падтрымаць стабільнае дизайнаванне API, калі многія команды адразу рэдагуюць схемы?
• Як пераканацца, што новыя типы і поля адпавядаюць сучасным стандартам?
• Як знайсці тыя часткі API, якія былі спроектаваны ўчора, калі такіх стандартоў яшчэ не існавала?

Першыя два пункты стосуюцца прытварання. Трэція частка — аб археалогіі, і самэй гэта тое, чаго зазвычай не прыдзельвае ўвага пад час рэгулювання.

Дзе заканчываюцца правіла перагляду і пачынаецца адгук

Значны частака стандатаў API ёсць механічнымі, і статычны аналіз лепа сабе з імі справляецца. Практыкі называння, выкарыстоўванне застарэлых поль, обавязковыя апісанні і аднообразны формат паказаець аберанняў ёсць якісціні типу «так» або «нет» для схемы: поль можа або выпалняць правіла, або няўыпалняць іх, і прыстрой для перагляду можа пазначыць, калі як.

Іншыя стандарты не можна спрыяжыць да простых правілаў. Тыповыя прыклады:

• Чы гэты String павінен быць enum?
• Чы гэты список павінен быць структураваны на сторункі?
• Чы гэты Int павінен быць спецыяльным скалярным значэнням?
• Чы гэтае поль з можлівасцю значэння null можа без апярозу стаць польм без null?
• Чы гэты формат адпавядае таму, як падобныя концэпты моделююцца ў іншых частках API?

Ні адна з гэтых задач не мае адказу без урахоўвання контэксту. Аддача String, або нават не типаванага JSON-об’екта, інодзе ёсць правільной. Лепт пра тое, чы робіцца гэта правільна, вымагае аналізу трохоў элементаў разам: заявы схемы, рэалізацыі механізма адпаведнага рашэння і меты выкладкі гэтых дадзеных для кліентаў. Толькі, врачываючы ўсе тры аспекты, можна выявіць, які формат будзе найкращы для кліентаў.

Арганізацыі зазвычай рашаюць гэтыя проблемы за дапамогою перагляду коду, абсарабоў з камандай платформы і пішаных рэкамендацый. Гэта працюе, але пагана падходзіць да масштабавання. Трыбуны выдання продукту скрацваюць час перагляду, каманда платформы не можа аналізаваць кожную змяну схемы ў кожным репазітарыі, а оптымальныя практыкі развіваюцца быстрей, чым старыя API практычна пераглядаюцца. Рэзультатам являюцься два скарыстаныя проблемы: запобежэнне новых «дзейнаў» у дизайне і выявленне тых, якія вже існуюць.

Перасунэнне налева: рэвізор LLM для змян схемы

Першая частка системы перакладвае кансэпты дизайна API у ўраджанага агента для перагляду коду. Мета не ў тым, каб заменіць людзяў-рэвізораў, а ў тым, каб дастаць ім другі погляд на тыя саме пытанні, якія застаюцца непазначанымі пад час звычайнага перагляду запросаў прыўязкі. Адзначэнне кожной змены GraphQL у всіх репазітарыях аддзелам платформы не є масштабаваннем; адзначэнне прабачальных стандартаў у AI-рэвізоры, які працуе всюды, такое ўсё ж масштабаванне.

Паколькі агент бачыць больш, чым толькі разніцу схем, ён можа аналізаваць контэкст, а не сынтаксіс. Ён чытае декларацыю, рэалізацыю, якая падтрымвае поле, і адпаведны текст правілаў, а пасля задае конкрэтныя пытанні. Два прыкладныя каментары:

• Поле пад назвай updatedAt адзначаецца як String. Якщо рэзалвер вяртае таймстамп у формате ISO 8601, яго жа трэба быць викорыстоўваць як спецыяльны скаляр ISO8601DateTime.
• Company.employees вяртае звычны список. Колькісць працавальнікаў у компаніи няма прадзефінаванага верхньего ліміту, таму гэтае поле жа трэба вяртаваць пагінацыйную структуру дадзеных.

Ні адна з гэтых проблем не можа быць надзеямо выявлена лінтаром. Правіла лінта, якія ставяць умову "полы, якія заканчваюцца на At, павінны быць датовымі скалярамі", даюць ложныя пазитыўныя рэзультаты і не беруць у расчыт lastModified; правіла, якія ставяць умову "усе спискі павінны быць пагінацыйнымі", не паслужаюць для поля, якое вяртае тры падтрымваныя валюты. LLM можа аналізаваць, што на самай працэ робіць рэзалвер.

Ключовым фактарам являецца час. З’яўленне такіх проблем, калі API яшчэ проектуецца, не карае вялікіх затрат. Адкрыць іх пасля таго, як кліенты вжыліся з дакументацыяй, значыць перабудаваць ўсю структуру і перанаслаўвацы данні.

Аналіз усёго, што ўжо існуе: оцэнка застаўленага схемы

Прыведчэнне проблем не дапамагае ў рашэнні праблем, якія выжылі ў застаўленай структуре, а ў вырашэнай API такая площа вельмі вяліка. Частка з яе існуе ўжо ранейш, чым былі створеныя сучасныя стандарты. Іншая частка ўключае компрэсіі, якія здаваліся разумнымі на момент стварэння. А ўсё інша проста неўзраўнае, таму што разныя каманды моделіравалі аднаковыя концэпцыі сваімі способамі. Патрэбны спосаб аналізу таго, што ўжо існуе.

Другая частка системы — цэ хвілевы процес, які дапамагае статычным інструментам аналізу, якія вже парсуюць схему. Його алгорытм:

1. Аналізаваць схему па домэнах і выбіраць поля або типы, дзе патрэбны суб’ектывныя рашэнні з боку дизайнера.

Зберыце адзякаванне шэмы разам з актуальным кодам рэалізацыі.

Адправьце гэты контекст да LLM у запросе, які включае напісаныя правілы дизайна API.

Запытайце модель, чы не выглядае, што данэць нарушае адну з гэтых суб’екtyўных практык.

Зберыце рэзультат у вачынку з балам і письмовым адказам.

Агрэгуйце нараджэнні па домену продукту або команде, якая яго керуе.

Першы крок мае значэнне для костоў і зайвага информацыя. Не ёсць прычыны запытваць модель пра данэцы, якія ўжо класіфікаваны дэтэрміністычным пераконтрам; LLM павінен бачыць толькі тыя кандыдаты, дзе насправды патрэбна оценка.

Чаму бал 1-5 кращы за «прымітнае/непрымітнае»

Паколькі гэта суджэння, прымусовая класыфікацыя кожнага нараджэння ў бінарны вердыкт ведае працяг частковай інформацыі. У замен кожны данэць атрымвае бал за перагляд з 1 да 5:

• 1: поле выглядае належным чынам, як і было спроектавана.
• 2: сігнал слабкі, але, верагацейна, все гаразд.
• 3: трэба, каб чалавек заглянуў.
• 4: пале, верагацейна, наражае на адхыленне ад правіл.
• 5: пале — это класычны прыклад моделі, якой трэба ухіліцца.

Ёсць конкрэтны прыклад: пале String, яке мае ў сабе будзь-які текст, напісаны корыстнікам, должна знаходзіцца блізу значэння 1. Пале String пад назвай errorCode, чыя функція разв’язкі можа вярнуць толькі адна з трох закодаваных значэнняў, должна знаходзіцца блізу значэння 5, адтуды што яна є enum пад маскай.

Рангаваныя ацэнкі даюць значна болей корыстны сигнал, чым просты список нарушэнняў. Команды можаць пачаць з рэзультатаў 4 і 5 з высокай доверымасцю, адночасна бачачы рэгіоны з нижэйшай доверымасцю, якія можаць патрабаваць болей дакладнага аналізу. Середняя частка шкалы мае другое застосоўанне: група значэнняў 3 паведамляе команду платформы, дзе формулюванні правілаў або запитаў є неяснымі, што являецца адзорам для доўнелення запитаў да выдачы болей надзеяных рэзультатаў.

Якща вы ствараеце ўльотнае рашэнне, пытайце модель пра структураваны выхід (ацэнку і адказ як околачныя полья), каб рэзультаты можна было зберагчы і агрэгаваць без парсінгу прозы, і трывайце текст правілаў і версіі шкалы ацэнкі разам з запитам, каб змяны ацэнак можна было прыязначыць да змян у правілах.

Ператварэнне нараджэнняў у дзеянні

Рэкорды ў базе дадзеных самі па сабе нічога не змянююць. Їх агрэгатаванне па доменах у панелі керування дае кожнай команде-власніку чыткую картыну проблем з дизайном API ў яе сферы: не розрозненыя прыклады чы адзінокія коментары пасля перагледу, а прыватарызаваны список полей і типаў, якія можа знадобіцца мігруаваць.

Тыя ж даныя дапамагаюць прагрэсаваць у процесе стацыонарнай інтеграціі. Мета не ў тым, каб усё відразу вылечыць, што ў разы нерэалістычна для большога API з многама кліентамі. Мета — стараннасць, каб ситуацыя ніколі не пагорэла, пакуль існуючы стан з часам павышаецца:

• Новыя змены схемы павінны адпавядаць чынным стандартам.
• Існуючыя проблемы фіксуюцца як вядомыя боргі, а не ігнаруюцца.
• Коли команды мігруюць чы відмовляюцца ад старых патэранаў, дазволеныя ліміты падыходзяць стрэлкой, таму ўжо вылечаныя боргі не можа зноў з’явіцца.

Рачэты ўжо давно выкорыстоўваюцца падчас міграцый коду: фіксуецца ныякія колькасць нарушэнняў па абласцях, будова праекту збіваецца, якщо змяны яе паднімаюць, а зафіксаваны базовы рэвэлю знижваецца, калі хтось усуне адпаведнае нарушэння.

Гэты падход ўсё бол важны для гасударвеных чы абшырна выкарыстоўваных API, дзе чышчэнне залежыць ад міграцый кліентаў. Результатам не ёсць інструкцыя пра выдаленне кожнага несправныга поля. Це ўпорядкованая карта тых месцаў, дзе API больш не адпавядае сучасным стандартам, якая можа служыць падставай для планавання з боку команд.

Чаму LLM — гэта правы інструмент для гэтага завдання

LLM-ы не ўсега бездоганныя суддзія дизайна API, і система таксама не спрыймае іх як такія. Їхня сіла тут ў болей вузкай сфере: чытанне коду і схемы разам, ўпорэнне іх на правілы, напісаныя простай мовай, і стварэнне структураванага адгукі ў тых случаях, калі статычныя правілы не можуць даўаць адпаведнага адгукі.

Статычная правіла можу сказаць вам, што полье вяртае список. Але яны не можу сказаць, чы расте гэты список праз данні, які вводзі корыстувачы, і чы таму патрэбна пагінацыя. Модель можа прачытаць рашэраблер, паравараваць яго з прыкладамі ў правілах і поясніць, чыму полье падходзіць або не падходзіць па шаблону.

Такое поясненне цэнюецца больш, чым число, якое даўся ў зв’язку з яным. Калі полье пазначаецца як проблемнае, каманда, якая яго адпаведальная, павінна знать прычыну, ўпрымкі што яна могла б быстра адначыць, чы ўсё справжняе, і, якщо так, як планаваць міграцыю. Бал без прычыны проста стварае ўтрохтвенную чергу.

Ліміты, якія трэба узгадаць

Перагляд за дапамою LLM не заменяе адпаведальнасці за API чы суджэння людзя-дизайнераў, і корыстна чытка адзначыць, што застаецца:

• Хоць і так існуюць хыбныя позытыўныя рэзультаты.

Інодзе сама рэалізацыя не паказвае цэлага картынкі, напрыклад, калі якая-небудзь абмежэння знаходзіцца ў іншай службе.

Абмежэння продукту можу зробіць недосконалую форму правым компромісам у будзь-якім случае.

Система не мігруе кліентав і не робіць змян, якія можу спрычыніць проблемы, безпечнымі. Яна выявляе наяўныя прычыны проблем; каманды все рава должны рэтельна планаваць і адкладаць міграцыі.

Але яна дае можлівасць масштабавання для выяўлення патэранаў, якія раней былі обмежаны колькасцю людскага адгляду. Рэкамендаціі кодуюцца раз, прыменяюцца адносова да кожнага рэпазітарыю, і яны ствараюць для каманд фактычную падставу для дыялогаў пра дизайн.

Заключэнне

Система складаецца з двух частей, які разам выражаюць адну ідею. Калі надходзіць запрос на змяну, адміністратар LLM прыкладае правіла дизайна да новых змян схемы, перш чым кліенты пачнуць аднойчы на яе спакоўвацца. У режыме пакетных змян той жа механізм оцэнюе існуючую схему з 1 по 5 балоў; этыя балы агрэгуюцца ў панелі керавання для кожнай команды, а механізм CI контролюе, каб загальная колькасць балоў не зрасла, праз постаўленне строгіяшых крэтароў з часам. Це не ўсё автоматызаванае кераванне, і так і мала б быть. Цей механізм робіць якасць API достатна відчутной, каб команды моглі прымкнуць дзеяння, а таксама стварае для команды платформы цікл зворачнай свярзанасці для удосконалення саеў правілаў, калі падход запрацоўвае ўсё больш часті схемы.