Usługa

Za pomocą Netuno można tworzyć usługi sieciowe i budować dowolnego rodzaju złożone API REST do integracji danych między systemami.

Czym jest usługa sieciowa?

Usługa sieciowa pozwala systemom wymieniać informacje online w ustandaryzowany sposób. W Netuno każdy plik w server/services/ automatycznie staje się punktem końcowym dostępnym przez HTTP.

Dlaczego warto używać usług sieciowych?

Korzystanie z asynchronicznych usług przynosi wyraźne korzyści dla doświadczenia użytkownika:

• Szybsze ładowanie: serwer natychmiast dostarcza strukturę wizualną strony, nie czekając na przetworzenie wszystkich danych.
• Dane dynamiczne na żądanie: frontend żąda tylko potrzebnych danych, gdy są potrzebne.
• Integracja między systemami: usługa utworzona w Netuno może być używana przez dowolną aplikację zewnętrzną (mobilną, inny system webowy itp.).
• Lepsze doświadczenie użytkownika: użytkownik nie musi czekać na pełne przetworzenie strony, zanim zobaczy cokolwiek na ekranie.

Wymagania wstępne

Przed rozpoczęciem upewnij się, że:

• Netuno jest zainstalowane i uruchomione lokalnie.
• Aplikacja demo została utworzona zgodnie z opisem w Tworzenie aplikacji.
• W Zadaniach i powiązanych Rejestrach są zapisane dane (potrzebne, aby odpowiedź nie była pusta).

Konfiguracja edytora kodu

Aby tworzyć i edytować usługi w Netuno, użyj edytora kodu według własnych preferencji. Polecamy Visual Studio Code, ponieważ jest darmowy, lekki i bardzo intuicyjny, ale każdy edytor zgodny z JavaScript/Python/Groovy będzie działał normalnie.

Otwieranie aplikacji demo

1. Otwórz Visual Studio Code.
2. Kliknij ikonę Pliki w lewym panelu bocznym.
3. Wybierz Otwórz folder (menu Plik > Otwórz folder).
4. Przejdź do folderu instalacyjnego Netuno.
5. Wybierz katalog: apps/demo
6. Kliknij Otwórz.

Struktura folderów aplikacji demo zostanie wczytana w lewym panelu.

Tworzenie usługi

Usługi są przetwarzane po stronie serwera. Aby utworzyć nową usługę:

1. W panelu plików rozwiń strukturę, aż znajdziesz folder server/services/.
2. Kliknij prawym przyciskiem myszy na folderze services.
3. Wybierz Nowy plik New File.
4. Nazwij plik zgodnie z językiem, którego chcesz użyć:

JavaScript

• server/services/pracownicy.js

TypeScript

• server/services/pracownicy.ts

Python

• server/services/pracownicy.py

Ruby

• server/services/pracownicy.rb

Kotlin

• server/services/pracownicy.kts

Groovy

• server/services/pracownicy.groovy

JavaScript

server/services/pracownicy.js

/**
*** Przekształca dane zapytania w wynik JSON.
*/
const dbRejestry = _db.query(`
    SELECT DISTINCT
        pracownik.imie, SUM(DATEDIFF(HOUR, rejestr.poczatek, rejestr.koniec)) AS suma
    FROM pracownik INNER JOIN rejestr
        ON pracownik.id = rejestr.pracownik_id
    WHERE pracownik.aktywny = true AND rejestr.aktywny = true
    GROUP BY pracownik.imie
    ORDER BY suma ASC
`);

const lista = _val.list();

for (const dbRejestr of dbRejestry) {
    lista.add(
        _val.map()
            .set("imie", dbRejestr.getString("imie"))
            .set("suma", dbRejestr.getInt("suma"))
    );
}

_out.json(lista);

TypeScript

server/services/pracownicy.ts

/**
*** Przekształca dane zapytania w wynik JSON.
*/
const dbRejestry = _db.query(`
    SELECT DISTINCT
        pracownik.imie, SUM(DATEDIFF(HOUR, rejestr.poczatek, rejestr.koniec)) AS suma
    FROM pracownik INNER JOIN rejestr
        ON pracownik.id = rejestr.pracownik_id
    WHERE pracownik.aktywny = true AND rejestr.aktywny = true
    GROUP BY pracownik.imie
    ORDER BY suma ASC
`);

const lista = _val.list();

for (const dbRejestr of dbRejestry) {
    lista.add(
        _val.map()
            .set("imie", dbRejestr.getString("imie"))
            .set("suma", dbRejestr.getInt("suma"))
    );
}

_out.json(lista);

Python

server/services/pracownicy.py

#
# Przekształca dane zapytania w wynik JSON.
#
dbRejestry = _db.query(
    """SELECT DISTINCT
        pracownik.imie, SUM(DATEDIFF(HOUR, rejestr.poczatek, rejestr.koniec)) AS suma
    FROM pracownik INNER JOIN rejestr
        ON pracownik.id = rejestr.pracownik_id
    WHERE pracownik.aktywny = true AND rejestr.aktywny = true
    GROUP BY pracownik.imie
    ORDER BY suma ASC"""
)

lista = _val.list()

for dbRejestr in dbRejestry:
    lista.add(
        _val.map()
            .set("imie", dbRejestr.getString("imie"))
            .set("suma", dbRejestr.getInt("suma"))
    )

_out.json(lista)

Ruby

server/services/pracownicy.rb

#
# Przekształca dane zapytania w wynik JSON.
#
dbRejestry = _db.query(%{
    SELECT DISTINCT
        pracownik.imie, SUM(DATEDIFF(HOUR, rejestr.poczatek, rejestr.koniec)) AS suma
    FROM pracownik INNER JOIN rejestr
        ON pracownik.id = rejestr.pracownik_id
    WHERE pracownik.aktywny = true AND rejestr.aktywny = true
    GROUP BY pracownik.imie
    ORDER BY suma ASC
})

lista = _val.list()

dbRejestry.each do |dbRejestr|
    lista.add(
        _val.map()
            .set("imie", dbRejestr.getString("imie"))
            .set("suma", dbRejestr.getInt("suma"))
    )
end

_out.json(lista)

Kotlin

server/services/pracownicy.kts

/**
*** Przekształca dane zapytania w wynik JSON.
*/
val dbRejestry = _db.query(
    """SELECT DISTINCT
        pracownik.imie, SUM(DATEDIFF(HOUR, rejestr.poczatek, rejestr.koniec)) AS suma
    FROM pracownik INNER JOIN rejestr
        ON pracownik.id = rejestr.pracownik_id
    WHERE pracownik.aktywny = true AND rejestr.aktywny = true
    GROUP BY pracownik.imie
    ORDER BY suma ASC"""
)

val lista = _val.list()

dbRejestry.forEach {
    lista.add(
        _val.map()
            .set("imie", it.getString("imie"))
            .set("suma", it.getInt("suma"))
    )
}

_out.json(lista)

Groovy

server/services/pracownicy.groovy

/**
*** Przekształca dane zapytania w wynik JSON.
*/
def dbRejestry = _db.query("""\
    SELECT DISTINCT
        pracownik.imie, SUM(DATEDIFF(HOUR, rejestr.poczatek, rejestr.koniec)) AS suma
    FROM pracownik INNER JOIN rejestr
        ON pracownik.id = rejestr.pracownik_id
    WHERE pracownik.aktywny = true AND rejestr.aktywny = true
    GROUP BY pracownik.imie
    ORDER BY suma ASC
""")

def lista = _val.list()

for (dbRejestr in dbRejestry) {
    lista.add(
        _val.map()
            .set("imie", dbRejestr.getString("imie"))
            .set("suma", dbRejestr.getInt("suma"))
    )
}

_out.json(lista)

Zaimplementuj usługę, dodając poniższy kod do utworzonego pliku. Ta usługa odpytuje bazę danych i zwraca listę pracowników z łączną liczbą zarejestrowanych godzin w formacie JSON.

Zrozumienie kodu

Obiekt/Metoda	Opis
_db.query()	Wykonuje zapytanie SQL i zwraca listę obiektów w formacie klucz-wartość (kolumna → dana).
_val.list()	Tworzy mutowalną listę do gromadzenia wyników.
_val.map()	Tworzy obiekt mapowania (klucz-wartość) dla każdego wiersza wyniku.
_out.json()	Serializuje obiekt do JSON i wysyła odpowiedź na żądania HTTP.

Wymagane dane

Upewnij się, że w Zadaniach i powiązanych Rejestrach są zapisane dane. W przeciwnym razie punkt końcowy zwróci pustą listę [].

Uruchamianie i testowanie usługi

Gdy Netuno jest uruchomione, otwórz punkt końcowy w przeglądarce:

Wskazówka dotycząca wyświetlania JSON

Polecamy Firefox do testowania punktów końcowych bezpośrednio w przeglądarce, ponieważ formatuje i wyświetla odpowiedź JSON w czytelny sposób z podświetlaniem składni. Alternatywnie użyj rozszerzeń takich jak JSON Viewer w Chrome lub narzędzi takich jak Postman do bardziej zaawansowanych testów.

Oczekiwany wynik będzie podobny do poniższego JSON:

[
  { "imie": "Anna Kowalska", "suma": 12 },
  { "imie": "Karol Nowak", "suma": 28 },
  { "imie": "Jan Kowalski", "suma": 45 }
]

Następne kroki

Teraz, gdy Twoja usługa działa, możesz:

• 📄 Interfejs i design — zintegrować tę usługę z frontendem aplikacji.
• 📚 Biblioteka usług — poznać obiekty _db, _val, _out i inne dostępne w Netuno.
• 🔗 Dodać uwierzytelnianie i kontrolę dostępu do swojej usługi.

---