Dobre praktyki ScriptCode

Kontekst

Reguły dotyczące pisania ScriptCode na platformie Eximee pozwolą zapewnić spójność, czytelność oraz bezpieczeństwo kodu, a także ułatwią wdrożenie nowych pracowników.

Twórz ScriptCode zgodnie z regułami opisanymi poniżej.

Obszar
Reguła

Spójna konwencja nazewnicza

  • Pisz kod w języku angielskim - stosuj angielskie nazwy zmiennych, funkcji itp.

Wyjątki: odgórne ustalenia biznesowe dotyczące nazewnictwa lub duży poziom skomplikowania skryptu (tu decyzja należy do low-code developera). Jeśli decydujesz się na konwencję nazw po polsku - bądź spójny w obrębie jednego skryptu.

  • Stałe literalne wpisane na sztywno w kodzie nazywaj w formacie UPPER_SNAKE_CASE, np. const MOBILE_CHANNEL = "mobile"

  • Pozostałe zmienne i funkcje nazywaj w formacie camelCase, np. const correlationId = context.getFirstParameter('correlationId'), let motherBranchNumber, function generateBranch()

Kolejność w strukturze kodu

Kod organizuj zgodnie z poniższą kolejnością:

  1. Stałe literalne- deklaruj na początku skryptu

  2. Zmienne - następnie deklaruj zmienne, które będą używane w logice głównej

  3. Logika główna - główny ciąg operacji, które kod wykonuje (np. przetwarzanie danych, wywoływanie funkcji)

  4. Funkcje pomocnicze - umieszczaj na końcu

Logowanie

  • Nie duplikuj logów platformowych - jeśli jakieś parametry są automatycznie generowane przez platformę nie loguj ich ponownie w skrypcie

  • Używaj loggera sensytywnego do logowania danych wrażliwych, wzór: Logger.info("Pesel klienta wypełniony na formularzu: {}", pesel)

Dowiedz się więcej: Logowanie w ScriptCode

Deklaracja zmiennych

  • Nie używaj varów

  • Typy prymitywne: używaj let tylko gdy zmieniasz w skrypcie wartość zmiennej. W pozostałych przypadkach używaj const

  • Typy złożone: nie używaj let jeśli modyfikujesz tylko zawartość obiektu - w tym tablic (Array), setów (Set), map (Map).

Nie ma potrzeby używania let przy deklarowaniu obiektów - w tym tablic (Array), setów (Set), map (Map) - o ile referencja (czyli odwołanie do konkretnego obiektu lub tablicy) nie będzie zmieniana. W większości przypadków powinno się stosować const do deklarowania tablic i innych obiektów, nawet jeśli ich zawartość będzie modyfikowana.

Przykład z użyciem const:

const array = [1, 2, 3]; array.push(4); // Działa poprawnie, modyfikujemy zawartość tablicy

const obj = { name: "Alice" }; obj.age = 30; // Działa poprawnie, modyfikujemy właściwości obiektu

Uwaga: Dopóki silnik rhino nie wspiera poprawnie zakresu blokowego dla const należy wewnątrz pętli "for" deklarować zmienne z wykorzystaniem let. Więcej o błędzie można przeczytać w materiale podlinkowanym poniżej.

Dowiedz się więcej: Typy danych w Javascript,

Referencja, mutowalność, typy prymitywne - powtórka Javascript!

Skrypty(ScriptService)

Tabela z wykazem które funkcjonalności nie są obecnie poprawnie wspierane przez silnik rhino Rhino: błąd przy deklaracji const wewnątrz pętli for

Obsługa błędów

  • Używaj bloków try-catch w miejscach, gdzie mogą wystąpić wyjątki. W razie wystąpienia błędu, loguj go z użyciem loggera, aby umożliwić łatwe śledzenie problemu.

Czytelność kodu

  • Kliknij prawy przycisk myszy → wybierz Format Document. Dzięki temu kod będzie bardziej przejrzysty i czytelny

  • Usuwaj kod, który jest zakomentowany i już niepotrzebny

  • Pisz komentarze w sposób zwięzły i jasny, wyjaśniając trudniejsze fragmenty kodu, intencje i nietypowe rozwiązania. Unikaj oczywistych komentarzy, które jedynie powtarzają to, co jest już czytelne w kodzie.

Powtarzalność kodu

  • Jeśli powtarzasz kilka razy fragment kodu - stwórz funkcję pomocniczą

Opis skryptu

  • Tworząc nowy skrypt/walidator - dodaj opis

Testy

  • Twórz testy jednostkowe zawsze gdy jest to możliwe, uwzględniaj warunki brzegowe.

Bezpieczeństwo

  • Wszelkie parametry wchodzące do ScriptCode'u traktuj jako niezaufane przy wysyłaniu do usług

Przykładowy kod:

Źle:

const url = "/api/form/" + context.getFirstParameter( "form_id" ) + "/data" ; const response = api.rest.v1.get( "host" , {pathParams: url.split( "/" )});

Dobrze:

const pathParams = [ "api" , "form" , context.getFirstParameter( "form_id" ), "data" ]; const response = api.rest.v1.get( "host" , {pathParams: pathParms});

  • Nie używaj danych autoryzacyjnych bezpośrendio w ScriptCode

  • Pobieraj zdalne zasoby (obrazki, dokumenty, wizerunki kart itd. ) z zaufanego źródła (np. platforma eximee, zasób bankowy)

  • Jeżeli musisz użyć w aplikacji jakikolwiek link upewnij się, że jest zaufany a jego użycie wynika wprost z wymagań

  • Jeżeli jakiejś funkcjonalności nie ma w platformie to zgłoś zapotrzebowanie - nie korzystaj z zewnętrznych narzędzi

Dowiedz się więcej: OWASP_Application_Security_Verification_Standard_4.0 - scriptCode

Operacje matematyczne z BigDecimal

  • Operacje matematyczne przeprowadzaj z wykorzystaniem z BigDecimal

Dowiedz się więcej: Operacje matematyczne w ScriptCode

Obsługa wartości falsy

  • Przed użyciem właściwości lub metod sprawdź, czy wartość zmiennej nie jest null ani undefined, aby zapobiec błędom związanym z brakiem wartości. W sytuacjach, gdy chcesz wychwycić również 0, pusty string lub NaN, możesz stosować ogólny warunek if(value).

Review

  • Jeśli nie jesteś jedynym low-code developerem w zespole - poproś kogoś z teamu o review kodu.

Materiały

PreviousPlatformowy nagłówek z identyfikatorem tenantaNextOWASP_Application_Security_Verification_Standard_4.0 - scriptCode

Last updated

Was this helpful?