Tema 5 · Kodo rašymo standartai

Kur rašote kodą, JavaScript vs TypeScript ir kaip tvarkyti scenarijų failą

Po ERP UI ir aplinkos sutariame redagavimo darbo eigą ir kalbas (vykdymas visada remiasi JavaScript), tada — tą pačią struktūrą ir vardų tvarką, kurią jau naudosite repo JSON ir produkcijoje.

1. Kur redaguojate automatizavimo kodą

  • Rivile ERP — įmontuotas scenarijų redaktorius (juodraštis, bandymas, istorija tame pačiame kontekste).
  • IDE (pvz. Cursor, VS Code) — tas pats kodas repozitorijoje kaip values.scriptContent eksporte; patogu diff, paieška, komandos peržiūra.
  • Šaltiniai — API žinynas ir pavyzdžiai: Tema 3, Tema 7, docs · automatizavimo API.

2. JavaScript vykdyme ir TypeScript kaip pagalbininkas

Automatizavimo runtime vykdo JavaScript (žr. JSON eksporte values.scriptContent). Tai reiškia: scenarijuje galite naudoti async/await, const/let, šablonines eilutes ir standartinę asinchroninę logiką pagal API žinyną.

TypeScript pats platformos variklis tiesiogiai nevykdo — TS naudingas komandoje kaip: atskiras .ts šaltinis su transpiliacija į JS prieš įkėlimą; arba JSDoc komentarai virš funkcijų IDE inteleisui; arba išorinis linteris. Pradedantiesiems užtenka tvirtų JS pagrindų ir griežtos sutarties su API.

3. Naudingos išorinės nuorodos (nemokama medžiaga)

Tema Kam Nuoroda
JavaScript (modernus) async/await, masyvai, klaidos, fetch idėja MDN · JavaScript
TypeScript Tipai, sąsajos, generikai — jei komanda nusprendžia TS naudoti ruošiant kodą TypeScript · Documentation
GraphQL sąvoka Užklausos ir mutacijos skaitymas šalia SDL GraphQL · Learn
„JavaScript“ moduliai Kai žinynas mini importus — suprasti paketų ekosistemą bendrai MDN · JavaScript modules

4. Struktūra ir eiliškumas faile

  1. Konstantos ir konfigūracija viršuje (const MAX_ROWS = 500).
  2. Validacija (initial, UserError) iškart po įžangos.
  3. Pagrindinis srautas (ciklai, partijos).
  4. Pagalbinės funkcijos faile apačioje (arba atskiruose blokuose su aiškiais vardais).
  5. output — paskutinė aiški priskyrimo eilutė (vengti ankstyvo return be žinutės, jei UI tikisi rezultato).

5. Naming conventions (JavaScript scenarijuje)

Sritis Rekomendacija
Kintamieji / funkcijos camelCase — purchaseOrderId, processRow
Konstantos UPPER_SNAKE_CASE — MAX_CONCURRENCY, DEFAULT_PAGE_SIZE
Įvykio klaidos kintamasis Vienodai: error arba exception — ne maišyti su rašybos klaidomis (execption sugadina catch)
Asinchroninės funkcijos async function fetchClients() — aiškūs veiksmažodžiai
RQL eilutės Įterpti ID tik per toString() / parametrus iš platformos — vengti rankinio sujungimo nefiltruotų tekstų iš vartotojo

6. Gerosios praktikos

  • Viena atsakomybė vienoje funkcijoje — ilgas monolitas skaidyti.
  • Žurnalas prieš sunkią operaciją — trumpas log.info su raktu (dok. Nr., eilutės ID).
  • Klaidos su kontekstu — JSON.stringify({ docRef, operation, payloadSummary }), ne tik error.message.
  • Partijos — riboti lygiagretumą (maxConcurrency), ypač prie mutate.
  • Užkomentuotas kodas — arba pašalinti, arba pažymėti WHY komentaru (ne „laikinai“ metams).
  • Testiniai duomenys — laikyti exampleData JSON eksporte, kad būtų galima paleisti be rankinio rinkimo.

7. Anti-pattern’ai iš praktikos

  • catch (execption) — skirtingas vardas nei throw exception → klaidos paslėptos.
  • output = { wholeArrayOf500Mb } — viršija prasmę ir atmintį.
  • log.trace(bigObject) gamyboje be ribų.

Pabaigoje parodysiu kelis realius JSON eksportus iš projekto scripts/ katalogo.

Teorijos santrauka

  • Žinote, kur rašote (ERP + IDE) ir kad vykdoma kalba yra JavaScript.
  • Struktūra faile: konstantos → validacija → srautas → pagalbinės funkcijos → output.
  • Vardai: camelCase, konstantos UPPER_SNAKE, nuoseklūs catch kintamųjų vardai.
  • Anti-pattern’ai: didžiulis output, log.trace su milžinišku objektu gamyboje.

Praktika salėje

Peržvelkite vieną blogą ir vieną gerą fragmentą iš apibrėžimų žinyno — komentuokite tik struktūrą ir vardus, ne verslo logiką.

Savarankiškas darbas

  1. Pasirinkite savo ar komandos scenarijaus ištrauką ir užrašykite penkių punktų refaktoriaus planą (be pilno perrašymo).
  2. Raskite vieną vietą, kur trūksta log.info prieš sunkią operaciją — pasiūlykite konkrečią žinutę (be PII).