Kodo ir karkasų migracijos
Šiame puslapyje
Saugiai migruok su Codex
Karkasų, bibliotekų ir pagrindinių versijų migracijos yra vienos rizikingiausių užduočių kuriant programinę įrangą: jos vienu metu paveikia visą projektą, jų negalima atlikti tik iš dalies, ir jos visada nutinka blogiausiu ketvirčio momentu. Codex sutraukia kelių dienų migraciją iki kelių valandų, sistemiškai tvarkydamas API pokyčius ir nesuderinamumus – būtent ten, kur žmogaus dėmesys pradeda blėsti ties trisdešimtu failu.
Karkasų migracijos
Karkaso keitimas yra ambicingiausias scenarijus ir dažniausiai tas, kuris baigiasi kaip apleistas projektas prieš dvejus metus sukurtame užsakyme.
"Migrate the application from Express.js to Fastify.
The project uses Express with:
- 15 routes in src/routes/
- JWT authentication middleware
- Morgan logging middleware
- CORS middleware
- Centralized error handling
Migrate route by route, preserving existing tests."
Inventorius prompto viršuje nėra papuošimas: jis garantuoja, kad jokia tarpinė programinė įranga (middleware) nebus pamiršta. Tada Codex eina nuosekliai – analizuoja esamą Express konfigūraciją, sukuria ekvivalenčią Fastify konfigūraciją, migruoja kiekvieną maršrutą pritaikydamas sintaksę, pakeičia tarpines programas jų ekvivalentais, atnaujina testus ir patikrina, ar viskas veikia. Instrukcija „maršrutas po maršruto“ suteikia papildomą naudą – lengvai skaitomą skirtumą (diff), kur kiekvieną maršrutą galima peržiūrėti atskirai neslankiojant per kitus keturiolika.
Pagrindinių versijų migracijos
Dažnesnės pagrindinių versijų naujinimo užduotys yra ne mažiau sudėtingos, nes suderinamumą nutraukiantys pokyčiai yra išsibarstę, o ne sutelkti vienoje vietoje.
"Migrate the project from React 18 to React 19.
Key points:
- Replace forwardRef with native ref props
- Migrate useContext usage to the new pattern
- Update TypeScript types (@types/react)
- Verify third-party library compatibility"
Codex remiasi oficialiomis migracijos pastabomis savo kontekste ir taiko pokyčius sistemiškai. Skirk laiko šiems pagrindiniams punktams suformuluoti pats: jie nukreipia jo paiešką vykdymo metu ir tarnauja kaip tavo kontrolinis sąrašas peržiūros metu, taip dvigubindami naudą.
Duomenų bazių migracijos
Keičiant schemą, sunkumas slypi ne pačioje SQL migracijoje, o visame programos kode, kuris nuo jos priklauso.
"The User model needs restructuring:
- Separate address into an Address model (1-N relationship)
- Rename email to primaryEmail
- Add an optional phone field
- Create the Prisma migration
- Update all services and routes using User
- Update tests"
Codex vienoje užduotyje tvarko visus tris sluoksnius: Prisma schemą, SQL migraciją ir visas programos nuorodas. Paprastas pervadinimas iš email į primaryEmail paprastai paliečia apie trisdešimt failų, įskaitant kelis, kurių nerastum naivu teksto paieška – dinamiškai sukurtą lauką, serializacijos raktą, rūšiavimo atitikmenį.
Bibliotekų migracijos
Vienos bibliotekos keitimas kita reikalauja aiškiai įvardyti, kas turi likti nepakitus.
"Replace moment.js with date-fns throughout the project.
Ensure that:
- All date formats are preserved
- Duration calculations remain correct
- Date comparisons work properly
- Time zones are handled the same way"
Laiko juostų punktas yra tas, kuris išgelbsti datų migracijas: dvi bibliotekos gali tavo kompiuteryje generuoti identišką išvestį, bet UTC serveryje skirtumas gali siekti vieną valandą. Dirbant tokio pobūdžio darbus, naudos mastas atsiskleidžia žemiau pateiktoje lentelėje.
| Dažna migracija | Rankinis laikas | Laikas su Codex |
|---|---|---|
| JavaScript į TypeScript | 1–2 sav. | 2–4 val. |
| REST į GraphQL | 2–3 sav. | 1–2 d. |
| Webpack į Vite | 2–5 d. | 2–4 val. |
| moment.js į date-fns | 1–3 d. | 30 min. – 2 val. |
Progresyvi migracijos strategija
Šie laikai daro prielaidą, kad vykdomas vienas etapas, kas pagrįsta tik nedideliems projektams. Visur kitur suskirstyk darbus į dalis. Sąmoningai apibrėžtas pirmasis etapas nustato konvencijas, kurių laikysis vėlesni etapai:
"Phase 1: Migrate only src/lib/ from JavaScript to
strict TypeScript. Do not touch React components or
API routes. Add necessary types and fix typing errors."
Kai šis etapas patvirtintas ir sujungtas, kitas etapas aiškiai remiasi juo:
"Phase 2: Migrate src/components/ from JavaScript to
strict TypeScript. Use the same typing patterns as
src/lib/ (phase 1 already migrated)."
Nauda dviguba. Rizika lieka ribota, nes nepavykusį etapą galima atšaukti neatšaukiant likusio darbo. Be to, kiekvienas etapas sukuria „pull request“, kurį žmogus realiai gali peržiūrėti – tai lemiamas kriterijus, nes migracija, pateikta kaip vienas šešių šimtų failų skirtumas, nėra peržiūrima; ji patvirtinama iš išsekimo, o tai panaikina didžiąją dalį tikėtos naudos.
Svarbiausi punktai
- Migracijos yra užduotys, kuriose Codex suteikia didžiausią produktyvumo prieaugį
- Savo instrukcijose išvardink konkrečius tavo projektui svarbius pagrindinius punktus
- Didelėms migracijoms judėk progresyviais etapais
- Codex vienoje užduotyje atnaujina kodą, testus ir priklausomybes
- Po migracijos visada patikrink atlikdamas pilną kompiliavimą ir testus