Napisz swój pierwszy skrypt JavaScript GraalVM (2026)

Napisz swój pierwszy skrypt JavaScript GraalVM

Napisanie pierwszego skryptu JavaScript GraalVM wymaga trzech małych kroków: zarejestrowania skryptu w punkcie wejścia hosta, dołączenia go do zdarzenia lub modułu oraz zapisania go w folderze skryptów, aby silnik mógł go załadować. Silnik działa na podstawie GraalVM Polyglot API, dzięki czemu skrypt jest prawdziwym JavaScriptem i przeładowuje się bez rekompilacji żadnego kodu Java.

Co potrzebujesz na początek

Program hosta, który osadza silnik. Host zawiera GraalVM JavaScript, udostępnia zestaw obiektów, które skrypty mogą wywoływać, oraz monitoruje folder skryptów. Nie instalujesz GraalVM samodzielnie; host go dołącza. Piszesz zwykły JavaScript w oparciu o obiekty, które host udostępnia.

Znajomość tego, do czego te obiekty odpowiadają, jest pomocna, ale nie musisz pisać żadnego kodu Java, aby zacząć. Jeśli wcześniej pisałeś JavaScript, wzorzec będzie Ci znany: host działa jak biblioteka, którą importujesz, i używasz go, aby sięgnąć do wnętrza programu.

Trzy kroki

1. Znajdź folder skryptów

   Host ładuje skrypty z ustalonej lokalizacji podczas uruchamiania. Sprawdź dokumentację hosta, aby uzyskać dokładną ścieżkę. Zazwyczaj jest to folder scripts/ w katalogu instalacyjnym.

2. Utwórz plik skryptu

   Utwórz nowy plik .js w tym folderze. Serwer automatycznie go wykryje przy następnym ładowaniu skryptów, zarówno podczas uruchamiania, jak i po wykonaniu polecenia przeładowania, jeśli jest ono obsługiwane.

3. Zarejestruj i połącz

   Wewnątrz pliku zarejestruj skrypt z punktem wejścia hosta, a następnie przypisz zachowanie do zdarzenia lub zdefiniuj moduł rozpoznawany przez hosta.

To wszystko. Zapisz plik, przeładuj, a skrypt się uruchomi. Bez procesu budowania, bez kompilacji, bez czekania. Po prostu edytuj i przeładuj.

Minimalny przykład

Większość hostów udostępnia skryptowi jeden punkt wejścia do rejestracji oraz kilka obiektów proxy, które łączą JavaScript z programem. Dokładne nazwy zależą od hosta, ale struktura jest taka sama. Pierwszy skrypt zazwyczaj tylko ogłasza swoją obecność i reaguje na jedno zdarzenie:

// Register the script with the host.
script.register({
  name: "hello-world",
  version: "1.0.0",
});
 
// React to an event the host exposes.
script.on("enable", () => {
  client.print("Hello from my first script.");
});

Przeczytaj dokumentację API hosta, aby poznać rzeczywiste nazwy obiektów i metod. Sedno sprawy to wzorzec: zarejestruj, a następnie podłącz zdarzenie lub zdefiniuj moduł. Większość hostów udostępnia pętlę zdarzeń lub mechanizm podłączenia do cyklu życia, a większość skryptów zaczyna od nasłuchiwania jednego z nich.

Gorące przeładowywanie podczas pracy

Zapisz plik i przeładuj skrypty (lub uruchom ponownie hosta, jeśli nie obsługuje przeładowywania na żywo). Zmiana wchodzi w życie bez potrzeby przebudowy. Ten szybki cykl jest głównym powodem, dla którego warto skryptować zamiast kompilować mod: skrypt przeładowuje się w kilka sekund, podczas gdy skompilowany mod musi zostać przebudowany i uruchomiony ponownie.

Jeśli dodajesz prostą funkcję lub modyfikujesz zachowanie, skrypty są najlepszym rozwiązaniem. Jeśli potrzebujesz głęboko wchodzić w silnik lub udostępniać nowe elementy pierwotne, skompilowany mod może mieć sens.

Co mogą i czego nie mogą robić skrypty

Skrypt może wywoływać obiekty, które udostępnia host, i nic więcej. Host deklaruje, które klasy i metody skrypty mogą dotykać za pomocą białej listy dostępu hosta GraalVM Polyglot, a domyślnie jest to odmowa. To zapewnia bezpieczeństwo i przewidywalność skryptów. Jeśli żądany obiekt nie jest udostępniony, host musi go dodać; nie można wyjść poza białą listę po stronie skryptu.

To cecha, a nie błąd. Oznacza to, że skrypty nie mogą przypadkowo (ani złośliwie) uszkodzić hosta, wywołując metody wewnętrzne lub zaglądając do obiektów, do których nie powinny. Oznacza to również, że osoby utrzymujące host mają jasną kontrolę nad tym, co jest obsługiwane, a co nie.

FAQ