Java Spring Boot #1 - postawienie prostego RESTowego endpointa

Cześć,
dzisiaj chciałbym przedstawić wam jak wystawić prosty serwis webowy, który będzie przyjmował pewien argument przez zapytanie http typu GET i zwracał pewne dane, za pomocą frameworku Spring Boot.

W tym przykładzie stworzymy pseudo bazę danych (w pamięci) i będziemy uzyskiwać z niej pewne informacje, a następnie zwracać je w postaci JSONa. Na szczęście pakiet Spring Boota zawiera wiele użytecznych bibliotek ułatwiający te zadanie.

Zanim zaczniemy pisać endpoint, warto zapoznać się z metodami http. Krótki opis znajdziecie na wikipedii. Jeżeli znasz te metody, to możesz pominąć ten krok.

Jak przeczytaliśmy powyżej, metoda GET służy nam generalnie do czytania informacji z serwera, a metoda POST wykorzystywana jest raczej do przesyłania danych na serwer. Czasem w celu ułatwienia testowania, niektórzy używają metody GET do wstawiania informacji, gdyż łatwo je przekazać przez przeglądarkę. Metoda POST przekazuje parametry w body zapytania.

W naszym przykładzie zastosujemy także system zależności maven, o którym możecie przeczytać tutaj. Ułatwi on nam pobieranie bibliotek z repozytoriów i pozwoli na łatwą kompilację i deploy do postaci .jar.

Będę także wykorzystywał środowisko programistyczne IntelliJ IDEA Community, które jest darmowe dla komercyjnych i niekomercyjnych projektów. Można je pobrać na stronie producenta

Załóżmy, że będziemy przechowywali informację na temat różnych języków programowania i kluczem będzie nazwa języka.

W celu ułatwienia swojego życia wykorzystam generator tworzenia projektów dla Springa na stronie https://start.spring.io/

Pierwsze trzy rozwijane listy to ustawienie, że projekt wykorzystuje maven, będzie pisany w Javie i będziemy wykorzystywali Spring Boota w wersji 2.0.1.

Zakładam, że wiecie co to jest package i jak się go definiuje, więc tylko powiem, że używamy go w polu Group. Ja wpisałem odwróconą domenę mojej strony, a na końcu unikalny identyfikator projektu.

W polu Artifact wpisujemy pełną nazwę projektu, a w Dependencies wpisujemy pakiet web, który będzie miał serwer http tomcat i wszystkie podstawowe narzędzia potrzebne do stworzenia endpointu.

Po ustawieniu tych opcji klikamy Generate Project. Powinniśmy otrzymać plik .zip z plikami projektu.

Wypakujmy teraz folder z projektem w dogodnym przez nas miejscu, pamiętajmy gdzie go wypakowujemy, gdyż będzie on potrzebny do importu projektu w Intelijj IDEA.

Nasz folder po wypakowaniu powinien wyglądać tak

Zajmiemy się teraz importem projektu mavenowego do naszego IDE. Ja używam i proponuję Intelijj IDEA. Zaimportuję teraz projekt z poziomu "ekranu powitalnego" Intelijja, żeby ułatwić krok osobom co zainstalowały IDE po raz pierwszy.

Następnie mamy zaznaczyć, gdzie znajduje się nasz wypakowany projekt. Zaznaczamy folder z projektem i klikamy OK

W następnym ekranie powinno nam zaproponować maven project. Jeżeli tego nie robi, upewnij się, że wskazałeś odpowiedni folder. Jeżeli jest jak na screenie, to klikamy na Next

Następny krok możemy przejść bez żadnych zmian. Jeżeli jesteś bardziej zaawansowany, to możesz zmodyfikować te ustawienia pod twoje potrzeby. Klikamy po prostu Next

Jak zrobiliśmy wszystko dobrze, to IDE rozpozna projekt mavenowy i wyświetli coś podobnego do tego co poniżej. Klikamy na Next

Następny krok to ustawienie, żeby IDE wykorzystywał biblioteki Javy zwane JDK. Jeżeli nie macie JDK, to pobieracie je tutaj i za pomocą znaczka + wybierasz JDK i wskazujesz ścieżkę. Polecam używać JDK 32 bitowego.

Po upewnieniu się, że mamy JDK, powinniśmy zobaczyć coś takiego. Jak mamy podobnie, to klikamy Next

Ostatnim krokiem jest ustawienie nazwy projektu na potrzeby IDE i jego lokalizacji. Powinno to wyglądać tak:

Na końcu klikamy Finish

Naszym oczom powinno pojawić się coś w tym stylu

Jak przeszliśmy całą konfigurację, to jesteśmy gotowi na napisanie tego czego potrzebujemy.

Stwórzmy teraz bazę danych w pamięci, którą wykorzystamy do przechowywania danych. Jak zawsze, zaczynijmy od stworzenia struktur danych tabeli. Zacznijmy od klasy Language, który będzie przechowywał informacje o języku. Wykorzystamy tę klasę, do wygenerowania JSONa. Jeżeli chcemy mieć inaczej wyglądającego JSONa, to musimy użyć pojęcia Data transfer object, który jest niczym innym jak klasą zawierającą wszystkie potrzebne nam przy przetwarzaniu wyniku z bazy danych do naszego endpointa. Innymi słowy, jest to miejsce, które przechowuje tylko potrzebne dane odczytane z bazy danych, a nie wszystko co zwróci baza danych.

Moja klasa wygląda tak

Teraz Utwórzmy miejsce, gdzie będziemy przechowywać nasze dane

Dodałem annotację @Service, żeby zarejestrować naszą bazę pod springa i móc używać annotacji @Autowired, która podaje nam instancję potrzebnej przez nas klasy. Jak widać na powyższym zrzucie, zasymulowałem dodawanie rekordów oraz pobieranie rekordów traktując name jako klucz.

Stwórzmy teraz pseudo interfejs, który będzie przetwarzał dane z bazy danych i zwracał gotową strukturę dla naszego endpointa

Tutaj także zarejestrowałem tę klasę, żeby można było ją podłączać w różnych miejscach projektu. Można to zrobić też inaczej, ale wybrałem prosty sposób.

Dodajmy teraz klasę, gdzie zaprojektujemy nasz endpoint

Jak widzimy, oznaczyliśmy nasz kontroler adnotacją @RestController, który mówi, że tu będą endpointy.

Mamy nasz serwis przetwarzający dane z bazy danych i podpięty poprzez adnotację @Autowired, którą możemy użyć dzięki adnotacji @Service.

Następnie mamy @RequestMapping("/languages/{name}"), która jest ścieżką prowadzącą do naszego zasobu. name jest zmienną w naszym adresie, żeby móc wpisać odpowiedni klucz - w naszym wypadku nazwę języka.

Mamy jeszcze adnotację @PathVariable("name"), która mówi, że ze ścieżki ma wziąć dane wpisane w miejscu {name} i przekazać je do metody. My bierzemy ten parametr i przekazujemy do serwisu, który pobiera odpowiedni rekord z bazy danych i mapuje nam rekord, żeby ładnie się wyświetlał JSON.

Ostatnia rzecz jaka nam pozostała, to wprowadzenie przykładowych danych. Aby to zrobić dodajmy nasłuchiwanie na rozpoczęcie aplikacji i prześlijmy przez serwis jakieś informacje

Jak widzimy, musimy oznaczyć klasę jako @Component i wykorzystać interfejs ApplicationRunner zwierający wymaganą metodę run. Metoda przekazuje parametry startowe aplikacji, które czasem się mogą przydać.

Gdy to wszystko mamy, możemy przetestować nasz endpoint. Aby uruchomić aplikację, możemy kliknąć na zielony trójkąt w głównej klasie

Powinniśmy uruchomić to poprzez opcję run i zobaczyć po chwili na dole coś takiego

To znaczy, że udało się nam uruchomić serwer.

Po wpisaniu w przeglądarce naszej ścieżki i odpowiedniego klucza w miejscu {name}, powiniśmy zobaczyć coś takiego

Oczywiście ja tu mam to ładnie sparsowane, ale generalnie powinny się tu znaleźć wszystkie te informacje, które zawarliśmy w obiektach naszej klasy Language.

Możecie zamiast Python wpisać inny dowolny klucz. Jak wpiszemy nieistniejący, to dostaniemy pustego JSONa.

Ostatnim przydatnym krokiem będzie eksport projektu do postaci .jar. Żeby to zrobić, musimy wykonać komendę mavenową clean install. clean oznacza wyczyść pliki kompilacyjne, a install wywoła kompilację i eksport do jara.

Komendę możemy wpisać klikając

i wybierając opcję edit configuration

Następnie wyświetli się nam okienko

klikamy na + i wybieramy maven

Wpisujemy komendę tak jak na zrzucie ekranu i klikamy OK

Na końcu klikamy na zielony przycisk obok naszej konfiguracji mavena

Po kompilacji powinniśmy mieć na liście po lewej stronie coś takiego

To oznacza, że możecie wziąć plik z rozszerzeniem .jar i uruchomić je w konsoli za pomocą komendy

java -jar NazwaPlikuKtórySięWygenerował.jar

Celem dopełnienia wiedzy, JSON generuje się dzięki bibliotece Jackson .

Przydatne linki:

tutorial spring boot REST service
annotacje @Service, @Component, @Controller

Podsumowując, po przejściu przez artykuł powinniście umieć stworzyć projekt z mavenowy z Spring Bootem. Powinen wam działać endpoint ze zmienną przekazywaną przez adres URL i endpoint powinnen zwrócić wam pewne dane zgodne ze strukturą przygotowaną przez was.