[Oat++] Tworzenie Webservice'ów w C++ z wygenerowaną dokumentacją

Wprowadzenie

Coraz popularniejsze są web-service'y, które powstają niezależnie, a mogą się komunikować przy pomocy pewnego interfejsu np. REST API. C++ również jest językiem umożliwiającym utworzenie serwera/klienta do komunikacji przez REST API, a dzięki jego szybkości jest to bardzo dobra technologia do tego celu.

Biblioteki do web service'ów w C++

Pisząc ten artykuł, zrobiłem przegląd dostępnych bibliotek do tego celu. Listę bibliotek znalazłem na Stack Overflow, oraz przeszukując internet. Szukałem czegoś open-source o licencji pozwalającej na swobodne wykorzystanie (nie GPL). Biblioteka powinna mieć stosunkowo dużą liczbę commitów, zawierać stosunkowo niedawne commity oraz być w pełni funkcjonalna w C++ (czyli może być napisana w C, byleby miała wrapper w C++ udostępniający wszystkie funkcje). Po przeanalizowaniu zdecydowałem się na bibliotekę Oat++, która poza powyższymi wymaganiami wspiera web service'y (różne adresy URL w ramach tego samego hosta), zawiera moduły do ORM (Object Relational Mapping), a także wspiera generowanie dokumentacji REST przy pomocy Swagger UI.

Analizowane biblioteki, które odrzuciłem

• Pistache - nie mają jeszcze wersji produkcyjnej (na czas pisania artykułu)
• cpprestsdk (dawniej Casablanca) - Microsoft zaprzestał rozwijania i napisali, aby go nie używać w nowych projektach
• RESTinio - ostatni commit sprzed 5 miesięcy, oraz bazuje na C++17 (a mamy kilka standardów do przodu)
• Crow - już nie utrzymywany
• ffead-cpp - mało commitów w stosunku do innych
• Boost.beast - jest to framework bazujący na boost.asio, obecny na wielu konferencjach poświęconych C++, ale wg opisu nie ma jeszcze release'u i interfejs biblioteki może się zmienić
• Webcc - oparty na Boost.Asio, więc lepiej użyć Boost.beast, który jest oficjalnie wspierany przez społeczność Boost
• CivetWeb - jest to biblioteka napisana w C, która posiada wrapper do C++, ale nie implementujący wszystkich funkcjonalności
• libhv - wydaje się obsługiwać różne rodzaje gniazd, ale nie wspiera robienia web-service'ów
• Restbed - ostatni commit 2 lata temu
• nghttp2 - biblioteka w C
• Drogon - biblioteka, wg mnie II wyboru, ale ma mniej commitów niż Oat++
• userver - biblioteka III wyboru - olbrzymie możliwości, wiele baz danych, brak możliwości wygenerowania dokumentacji

Biblioteka Oat++

Funkcjonalności biblioteki

Wg strony domowej biblioteka ma być wysoce skalowalna oraz efektywna pod względem zasobów, bez dodatkowych zależności (chyba, że podmoduły np. do bazy danych), zawierająca:

• Zaawansowany framework do obsługi REST wraz z mapowaniem argumentów oraz adnotacjami Swagger-UI
• Framework do obsługi baz danych przez mechanizm ORM (Object-Relational Mapping)
• Framework do WebSocket (udostępnili na stronie wynik benchmarku dla 5 milionów połączeń)
• Obiekty transferu danych (ang. Data Transfer Object (DTO)) - obiekty umożliwiające łatwą serializację i deserializację
• Wstrzykiwanie zależności (ang. "dependency injection") - mechanizm używany w frameworku
• Moduł do Swagger-UI
• i inne

Obsługiwane systemy operacyjne

• Linux
• BSD
• MacOS
• Windows
• OpenWRT
• i inne

Wyjaśnienie o co chodzi w web-service'ach (dla osób, które nie pisały takich aplikacji)

Web service'y to aplikacje sieciowe, które umożliwiają komunikację między różnymi systemami poprzez standardowe protokoły internetowe. Najczęściej używanym protokołem jest HTTP, a interfejsy tych usług są zazwyczaj oparte na standardzie REST (Representational State Transfer). Web service'y pozwalają na wymianę danych i funkcjonalności między aplikacjami w sposób niezależny od platformy i języka programowania.

Podstawowe operacje w web service'ach REST opierają się na metodach protokołu HTTP, takich jak:

• GET - Pobieranie zasobów z serwera, np. pobieranie listy użytkowników lub szczegółów konkretnej książki
• POST - Tworzenie nowych zasobów na serwerze, np. dodawanie nowego użytkownika lub książki
• PUT - Aktualizacja istniejących zasobów na serwerze, np. edytowanie danych użytkownika lub książki
• DELETE - Usuwanie zasobów z serwera, np. usuwanie użytkownika lub książki

Przykłady użycia tych komend w kontekście konkretnego przykładu, opisywanego w ramach tego artykułu - aplikacji do zarządzania książkami:

• GET /books
   - Pobieranie listy wszystkich książek
• GET /books/{id}
  - Pobieranie szczegółów książki o danym ID
• POST /books
  - Dodawanie nowej książki (wymaga danych książki w formacie JSON)
• PUT /books/{id}
  - Aktualizacja danych książki o danym ID (wymaga danych książki w formacie JSON)
• DELETE /books/{id}
  - Usuwanie książki o danym ID

W ten sposób, web service'y pozwalają na tworzenie elastycznych i skalowalnych aplikacji, które mogą być łatwo integrowane z innymi systemami.

Cel artykułu

W niniejszym artykule wprowadzam bibliotekę Oat++ wraz z wybranymi modułami, aby przedstawić zrozumiały (i, niestety, lepszy niż w oficjalnych materiałach) tutorial krok po kroku, od instalacji biblioteki do serwera z prostą funkcjonalnością. Obejmuje on obsługę różnych endpointów (ścieżek w adresie URL), obsługujących różne metody protokołu HTTP, na przykładzie bazy danych do przechowywania różnych książek. W dalszych etapach zaprezentowana jest również autoryzacja oraz szyfrowanie. Mając serwer, nie zapominam o kliencie do komunikacji z serwerem przy pomocy protokołów HTTP lub HTTPS. Oczywiście, nasz serwer posiada automatycznie wygenerowaną dokumentację, dostępną w ramach popularnego frameworka webowego Swagger UI.

Instalacja

Według instrukcji na oficjalnej stronie, należy przy pomocy CMake zbudować bibliotekę. Jednakże, preferuję instalację przez menedżer pakietów VCPKG. Aby zainstalować, wystarczy zastosować analogiczne kroki jak w artykule o instalacji zależności przez VCPKG.
Dzięki instalacji przez VCPKG mamy możliwość zainstalowania wielu modułów z zależnościami niemalże jedną komendą, niezależnie od systemu operacyjnego.
Przykładowo, aby zainstalować samo :
W rezultacie powyższego pojawia się automatycznie wygenerowany tekst do dodania do naszego pliku :
Aby podlinkować powyższe, należy wywołać:

Jeśli korzystamy z systemu Windows, to po zawołaniu powyższej komendy mamy już wszystko podlinkowane w środowisku Visual Studio. W innych systemach operacyjnych pojawi się dodatkowy argument do wywołania CMake'a zawierający: .
Możemy utworzyć plik :
Mając ten plik, należy pamiętać, aby poza systemem Windows użyć opcji  przy generowaniu konfiguracji.

Inne możliwości instalacji przez VCPKG

Zasadniczo sprowadzają się one do wyboru innej konfiguracji dla oat++ przez VCPKG. Możemy wyświetlić możliwe konfiguracje:

Przykłady użycia biblioteki

Przykłady zaczynają się od krótkiego opisu, następnie przedstawiam efekt końcowy, a dopiero potem kod i opis trudniejszych miejsc w kodzie. Efekt końcowy to często wywołanie udostępnionego API przez komendę curl wraz z odpowiedzią.

Komenda Witaj Świecie

Przykład ten sprowadza się do tego, że tworzymy aplikację, która po uruchomieniu jest serwerem HTTP, nasłuchującym na konkretnym porcie, oraz udostępnia endpoint . Pierwszy przykład bazuje na oficjalnym startowym przykładzie (pełny kod przykładu).

Oczekiwany efekt: Kiedy wejdziemy przy pomocy przeglądarki na adres: http://localhost:8000/hello, zobaczymy tekst:
Z kolei, jeśli spróbujemy wejść na inny endpoint, np. http://localhost:8000/user, pojawi się:

Kod dający taki efekt

Czas na wyjaśnienie kilku miejsc w programie:
1. Utworzenie handlera, handler powinien zawierać metodę .
2. Utworzenie endpointa , który nasłuchuje na metodzie  protokołu HTTP i wywołuje wyżej wymieniony handler.
3. Konfiguracja serwera - jaki adres i jaki port.

Efekt uruchomienia programu znajduje się powyżej kodu, natomiast serwer wydrukuje coś na kształt poniższego (dla nazwy programu "OatTest"):

Obsługa JSONów

W webservice'ach na ogół nie operuje się na czystym tekście, ale używa się formatu JSON, z którego łatwo i szybko można wyjąć pewne informacje. Wygodnie jest też, zamiast samodzielnie operować na parsowaniu JSONów, skorzystać z obiektów transferu danych (DTO, ang. Data Transfer Object), które "automatycznie" zamienią reprezentacje z JSONa na obiekt w kodzie C++.
Oczekiwany efekt: jak wejdziemy przy pomocy przeglądarki na adres: http://localhost:8000/hello, to tym razem dostaniemy odpowiedź w formie JSONa (przeglądarka ładniej to zaprezentuje):

Kod z poprzedniego przykładu po modyfikacjach

Czas na wyjaśnienie kilku miejsc w programie (pomijam wyjaśnione wcześniej fragmenty w poprzednim programie):
1. Włączamy nagłówek odpowiedzialny za generację obiektów DTO.
2. Jest to klasa, wewnątrz której zostaną wygenerowane pewne pola, proszę zobaczyć, że jest ona otoczona  i . Oczywiście takie klasy DTO powinny być w oddzielnych plikach.
3. Tworzymy obiekt mapujący obiekty do JSONów, który to potem jest przekazywany w konstruktorze naszego Handlera.

Komponenty w jednym miejscu + makra preprocesora

Wg opisu w pierwszym tutorialu na stronie domowej zamiast tworzyć pewne rzeczy na piechotę, zalecane jest stosowanie makr, które wiele kroków zrobią automatycznie skracając zapis. A także, wg twórców, wszystkie główne komponenty są inicjalizowane w jednym miejscu, co daje większą łatwość w konfiguracji aplikacji. Poza tym wszystkie praktyczne przykłady później bazują na tych makrach.

Takimi makrami są:
, które rozwija się na postać:
oraz

które tak prawdę powiedziawszy ma formę: , a ostatni argument jest opcjonalny. Jest on konieczny, gdy zarejestrowanych jest wiele komponentów tego samego typu, wtedy potrzebujemy nazwę.

Poza tym mamy jeszcze makro:

a dokładniej:  (ostatni argument jest opcjonalny), ono generuje metodę zwracającą .

Możemy tworzyć endpointy na różne metody HTTP, metody HTTP to m.in.:

• GET
• POST
• PUT
• DELETE

Powyższego makra możemy użyć, jak zamiast dziedziczyć po , będziemy dziedziczyć po . Będziemy tego sposobu używali w dalszych przykładach.

Oczekiwany efekt: Działanie kodu analogiczne jak wcześniejszego, jedynie zastosowane mechanizmy są bardziej zalecane przez producentów biblioteki. Z różnic widocznych na zewnątrz dodałem drugi endpoint: http://localhost:8000/bye

Kody używane w tym przykładzie

W oparciu o zastosowanie makr tworzy się klasę w pliku  np.:

Cały pozostały kod:

Komentarz do pewnych miejsc w kodzie:
1. Używam ApiController, który zarządza endpointami. Na uwagę zasługuje fakt, że przed tą klasą i po niej musimy aktywować i deaktywować odpowiednie makra preprocesora, odpowiednio  i .
2. Teraz w wygodny sposób można tworzyć endpointy.
3. Tutaj zamiast tworzyć endpoint w funkcji  tworzy się jedynie kontroler.

Baza książek: dodawanie, pobieranie, usuwanie

Teraz wiemy już wystarczająco dużo, aby zrobić coś konkretniejszego - bazę książek, do której można dodawać, pobierać informacje, poprawiać czy usuwać. Co prawda, dla uproszczenia będę korzystał ze zwykłej  zamiast z bazy danych.

Oczekiwany efekt:

• Dodanie książki (dodałem więcej książek przez wielokrotne wywołanie tej komendy):
  
  curl -X POST "http://localhost:8000/books" -H "Content-Type: application/json" -d '{
  "title": "Piec jezykow milosci", "author": "Gary Chapman"
  }'
  {"id":0,"title":"Piec jezykow milosci","author":"Gary Chapman"}
• Pobranie konkretnej książki:
  
  curl -X GET "http://localhost:8000/books/0"
  {"id":0,"title":"Piec jezykow milosci","author":"Gary Chapman"}
  curl -X GET "http://localhost:8000/books/1000"
  Book not found
• Pobranie wszystkich książek:
  
  curl -X GET "http://localhost:8000/books"
  [{"id":0,"title":"Piec jezykow milosci","author":"Gary Chapman"},{"id":0,"title":"4 funkcje mezczyzny","author":"Jacek Pulikowski"},{"id":0,"title":"Krotki przewodnik po rodzinie","author":"Piotr Pawlukiewicz"}]
• Usunięcie książki:
  
  curl -X DELETE "http://localhost:8000/books/0"
  Book successfully deleted
  curl -X DELETE "http://localhost:8000/books/0"
  server=oatpp/1.3.0
  code=404
  description=Not Found
  message=Book not deleted. Perhaps no such Book in the Database
• Modyfikacja istniejącej książki:
  
  curl -X PUT "http://localhost:8000/books/1" -d '{ "title": "Cztery funkcje mezczyzny"}'
  {"id":1,"title":"Cztery funkcje mezczyzny","author":"Jacek Pulikowski"}

Kod bazy książek v1

A oto kod, który daje takie możliwości (natomiast plik  jest dokładnie ten sam co ostatnio, dlatego nie ponawiam):

Wyjaśnienie trudniejszych fragmentów powyższego programu:
1. Teraz obiektem transferu danych jest książka, która posiada tytuł i autora.
2. Oprócz obiektu transferu danych jest potrzebna struktura trzymająca te dane w systemie. Oczywiście jeśli byśmy skorzystali z mechanizmu mapowania obiektowo-relacyjnego (ORM) z bazą danych to nie musieli byśmy tworzyć zduplikowanych obiektów w kodzie C++.
3. W tym miejscu tworzę bazę książek, która jest globalną mapą. Poniżej jest atomowy licznik IDków, aby przy równoczesnym dodawaniu wielu książek licznik zadziałał poprawnie.
4. Wewnątrz makra  używam również makra , które podaną wartość JSONa zamieni na obiekt, bez konieczności robienia tego przez nas ręcznie.
Poniżej jest makro , które w razie niespełnienia warunku zwróci informacje o błędnej odpowiedzi (w naszym przypadku przy niepodaniu tytułu).
5. Kolejne makro  umożliwia parsowanie fragmentu wyjmując z niego zmienną odpowiedniego typu, dzięki temu my nie musimy tego robić ręcznie.
6. Mimo iż  zachowuje się niby jak  to są pewne różnice, choćby taka, że trzeba zmienną zainicjalizować specjalnie.

Automatyczna dokumentacja Swagger UI do bazy książek

W powyższym kodzie utworzyliśmy service do przechowywania książek, brakuje nam w nim jeszcze dokumentacji, która może być wygenerowana automatycznie, po dodaniu pewnych drobiazgów w kodzie. Dokumentacja ta jest używana w ramach mechanizmu Swagger UI, gdzie możemy nie tylko podpatrzyć dostępne komendy, ale jeszcze je wykonać z poziomu przeglądarki widząc podgląd wysłanych komend i otrzymanej odpowiedzi. Poniższy kod bazuje na oficjalnym przykładzie Oatpp-CRUD, jednakże bez mechanizmu bazy danych, oraz na oficjalnym opisie modułu oatpp-swagger.
Oczekiwany efekt:
Po wejściu na stronę: http://localhost:8000/swagger/ui (gdy wszystko mamy dobrze skonfigurowane) powinniśmy zobaczyć ekran podobny do:
Jak klikniemy "Try it out", to pojawi się nam możliwość wysłania tej komendy z podaniem argumentów, oraz po wysłaniu otrzymamy odpowiedź, czyli zobaczymy coś takiego jak:
Poza tym na samym dole mamy możliwość podejrzenia, jakie pola zawierają nasze obiekty transferu danych DTO.

Zademonstrowałem również statyczną stronę HTML, która jest dostępna pod endpointem-rootem: http://localhost:8000/, wyświetlona strona HTML to:

Kod potrzebny do osiągnięcia powyższego celu

Zasadniczo większość kodu jest taka, jak do tej pory, jednakże występują pewne rozbieżności. Po pierwsze musimy mieć zainstalowany oatpp-swagger, który musimy dołączyć w pliku . Przykładowy plik:

Teraz czas na zmiany w kodzie. Jedną z nich jest stworzenie klasy zawierającej globalne informacje o API, plik nazywa się , a oto jego zawartość:
W powyższym kodzie na uwagę zasługuje jedynie ścieżka do zasobów  oraz linijka wyżej. Jest to ścieżka, gdzie znajdują się zasoby Swagger, który przypomnę - jest frameworkiem webowym, dlatego potrzebuje pliki CSS, JavaScript i HTML. W oficjalnych przykładach stałą  ustawiają w CMake'u w następujący sposób:
, ale dużo zależy od tego gdzie znajduje się ten katalog w naszym projekcie.

Również plik  musimy lekko zmienić:

W powyższym kodzie musimy włączyć wcześniej wspomniany plik konfiguracyjny Swaggera , oraz utworzyć instancję tej klasy w klasie  .

Wreszcie czas na resztę kodu (która też powinna być podzielona na pliki):

Wyjaśnienie pewnych nowych aspektów kodu:
3. Przy pomocy makra  tworzę dokumentację dla poszczególnych komend/zapytań do API. Dla każdego z parametrów mamy możliwość konfiguracyjną. W pierwszym przykładzie  zawarłem wszystkie dostępne opcje.
4. Utworzyłem dodatkowy kontroler, który dla endpointa root (czyli w tym przypadku: http://localhost:8000) wyświetla stronę o statycznej treści.
5. Aby dodać nasze endpointy (czyli podścieżki URL) do wygenerowanej dokumentacji, musimy najpierw stworzyć instancję BookController i dodać ją do routera przy pomocy metody . Następnie pobieramy listę endpointów z naszego kontrolera za pomocą metody . Te endpointy są następnie dodawane do obiektu , który przechowuje wszystkie endpointy, które mają być udokumentowane.
6. Aby wygenerować dokumentację Swagger dla naszego API, dodajemy kontroler  do routera. Kontroler ten generuje i udostępnia dokumentację Swagger na podstawie dostarczonych endpointów. W naszym przypadku przekazujemy do niego , które zawierają endpointy z .
7. Dodatkowo dodajemy do routera , który obsługuje endpoint root ("/") i zwraca stronę HTML o statycznej treści. Jest to przydatne, aby użytkownicy mogli łatwo znaleźć link do dokumentacji Swagger UI bezpośrednio z głównej strony naszej aplikacji.

Autoryzacja/logowanie użytkowników (bazowa identyfikacja, ang. "basic")

W poprzednim przykładzie udostępniliśmy funkcje API do zarządzania książkami. Nie wszystkie operacje powinny być jednak dostępne publicznie. Pewne funkcje, takie jak dodawanie, edytowanie czy usuwanie książek, wymagają zalogowania się za pomocą loginu i hasła, podczas gdy podgląd wszystkich książek nie wymaga logowania.

Oczekiwany efekt:
Jeśli spróbujemy dodać książkę bez zalogowania, operacja zostanie odrzucona:
Logowanie odbywa się poprzez podanie loginu i hasła zakodowanych w base64:
Czyli komendę dodawania książki należy wywołać w następujący sposób:
Pobranie książki nie wymaga logowania:
Pozostałe komendy działają analogicznie jak wcześniej, z tym że część z nich teraz wymaga logowania.

Strona z dokumentacją również ulegnie lekkim zmianom:
Pozostałe obrazy wyglądają analogicznie, z tym że podczas próby wysłania komendy wymagającej logowania, przeglądarka zapyta o login i hasło.

Kod potrzebny do osiągnięcia tego efektu

Pliki  i  pozostają takie same jak poprzednio, natomiast występują różnice w klasie . Oto pełny kod:
Komentarz do pewnych fragmentów programu:
1. Ustawienie domyślnego handlera autoryzacji dla kontrolera .  jest używany do implementacji podstawowej autoryzacji HTTP (Basic Auth). Handler ten sprawdza nagłówek  w żądaniach HTTP. Argument:  to identyfikator realm, który pojawia się w oknie dialogowym przeglądarki przy żądaniu danych logowania.
2. Dodanie wymogu autoryzacji do endpointa: ta linia kodu informuje, że endpoint wymaga autoryzacji typu .
3. Deklaracja endpointa z autoryzacją.
4. Sprawdzenie autoryzacji użytkownika w endpoincie: funkcja  sprawdza, czy podane dane logowania są poprawne. Jeśli nie, zwracany jest status HTTP 401 ("Unauthorized").

Autoryzacja przy użyciu tokena: authorization - Bearer

Oat++ wspiera również możliwość autoryzacji przy pomocy tokenu (ang. "bearer authorization"). Możemy się zalogować, korzystając z dodatkowego endpointa:

W odpowiedzi otrzymamy token, do którego wygenerowania i zweryfikowania możemy użyć biblioteki jwt-cpp.
Następnie używamy tokenu w następujący sposób:
Więcej informacji na temat autoryzacji można znaleźć na oficjalnej stronie.[/div]

Klient do naszej aplikacji

Napisaliśmy aplikację, którą mogą używać użytkownicy, ale warto również umożliwić komunikację z naszym serwerem przez klienta napisanego w C++. Oat++ umożliwia takie rozwiązania. Dużym udogodnieniem jest nie tylko możliwość wysyłania i odbierania danych, ale także możliwość użycia obiektów transferu danych (DTO). Poniższy przykład bazuje na oficjalnym przykładzie API Client.

Oczekiwany efekt: Program kliencki w C++, który dodaje kilka książek, pobiera książki, edytuje i usuwa, stosując mechanizm autoryzacji.

Pełny kod klienta korzystającego z autoryzacji

W ramach wyjaśnienia trudniejszych miejsc w kodzie:
Na uwagę zasługuje klasa , która ma zdefiniowane dokładnie te same metody, co nasze API. Istotne jest ustawienie autoryzacji - przez dodatkowy nagłówek. Dzięki temu możemy wywoływać metody API jak zwykłe metody, podając odpowiednie argumenty (w tym nagłówek odpowiedzialny za autoryzację). Oprócz możliwości parsowania odpowiedzi do obiektu DTO, można również pobrać odpowiedź w formie tekstowej.

Więcej informacji na temat modułu API Client w dokumentacji. Znajdziesz tam informacje o tym, jak ustawić automatyczne wznawianie połączeń.

Szyfrowane połączenie

W dzisiejszych czasach szyfrowanie połączeń HTTP jest powszechne. Bez obsługi szyfrowania framework byłby mniej przydatny. Co ciekawe, Oat++ zawiera dwa moduły do szyfrowania: oatpp-libressl i oatpp-mbedtls. Ze względu na popularność i szerokie zastosowanie skupimy się na module korzystającym z libressl. Użyty w tym kroku kod bazuje na kodzie serwera z poprzedniego przykładu, ale został wzbogacony o konstrukcje z oficjalnego przykładu używającego libressl.

Oczekiwany efekt:
Zamiast komunikować się z serwerem jak dotychczas (port 8443 zamiast 8000, zwróć uwagę gdzie jest http a gdzie https):
Musimy używać połączenia HTTPS. Możemy to zrobić, pomijając weryfikację certyfikatu (stosując flagę  lub ):
Lepszą wersją jest wskazanie certyfikatu:

Wygenerowana dokumentacja (Swagger UI) będzie dostępna przez przeglądarkę jak dotychczas, z tym że będzie to połączenie szyfrowane (zależnie od sposobu pozyskania certyfikatu, jeśli wygenerujemy go sami, pojawi się ostrzeżenie przeglądarki o połączeniu szyfrowanym z niezweryfikowanym certyfikatem).

Kod potrzebny do osiągnięcia tego efektu

Pierwszą rzeczą jest zainstalowanie odpowiedniego modułu. Można to zrobić za pomocą menedżera pakietów VCPKG w następujący sposób:

Po zainstalowaniu zależności należy zaktualizować plik  o moduł  oraz jego zależności:
Pełna wersja pliku :

Teraz możemy zająć się zmianami w kodzie, który, mimo pozorów, się znacząco nie zmienia. Należy jedynie zaktualizować pliki  w przykładowy sposób:

Oraz należy dokonać drobnych zmian w pliku , zasadniczo sprowadzających się do zmiany jednej linijki (http na https oraz inny port):

Oto pełny kod tego pliku:

Klient do komunikacji z aplikacją przy użyciu szyfrowania

Nasz dotychczasowy klient nie będzie już w stanie połączyć się z szyfrowanym serwerem, dlatego musimy wprowadzić pewne zmiany. Według opisu dotyczącego przykładu z szyfrowaniem, konieczne jest dodanie kilku linijek kodu, jednak wymaga to również innych zmian. Poniżej znajduje się pełny kod klienta:
W powyższym kodzie znajdują się dwa fragmenty specyficzne dla połączenia HTTPS:
1. Utworzenie klasy ClientComponent, która zarządza połączeniem szyfrowanym.
2. Inny sposób połączenia, z użyciem .

Obsługa baz danych przez mechanizm ORM biblioteki Oat++ oraz użycie typu wyliczeniowego

Ciekawą funkcjonalnością tej biblioteki jest moduł do mapowania obiektowo-relacyjnego (ORM) między bazą danych a obiektami C++. Na ten moment wspierane są następujące bazy danych: MongoDB, PostgreSQL oraz SQLite. Wsparcie to polega na możliwości łatwego przenoszenia obiektów transferu danych (DTO) do i z bazy danych, bez konieczności tworzenia dodatkowych obiektów pośrednich.

W niniejszej sekcji zademonstruję przykład bardzo podobny do poprzedniego, jednak zamiast używania  wykorzystam bazę danych SQLite, obudowaną przez moduł oatpp-sqlite. Różnica z perspektywy klienta polega na dodaniu, aczkolwiek opcjonalnego, pola wyliczeniowego zawierającego informacje o typie książki. Przykład ten jest inspirowany oficjalnym przykładem CRUD, jednak jest od niego prostszy: nie zawiera testów ani mechanizmu paginacji odpowiedzi.

Oczekiwany efekt (z perspektywy klienta) - dodatkowe pole :
Natomiast użycie niepoprawnego wyliczenia spowoduje błąd:
Pozostałe komendy działają analogicznie.

Pełny kod korzystający z bazy danych SQLite oraz używający typu wyliczeniowego

Jest to ostatni przykład, dlatego został on rozbity na pliki w sposób sugerowany przez oficjalne poradniki biblioteki Oat++:

Aby kod działał, należy zainstalować oatpp-sqlite komendą np.:

Plik CMakeLists.txt

Zacznijmy od pliku . Tym razem ścieżki do pewnych zasobów są umieszczone jako definicje kompilacji, analogicznie jak w oficjalnych przykładach:

Plik z główną funkcją programu: main.cpp

Tym razem jest on krótki:

Plik zawierający reprezentacje DTO oraz enum: dto/BookDto.hpp

Poniżej plik transferu danych do obsługi książek, wraz z enumem odpowiadającym typowi książek:

Kontroler API operacji związanych z książkami: controller/BookController.h

Jest on krótszy niż wcześniej, gdyż logikę związaną z operacjami deleguje do innej klasy:
Wyjaśnienie kilku miejsc w programie:
1. Utworzenie instancji , która zajmuje się wykonywaniem operacji CRUD na bazie danych i obsługą błędów.
2. Tutaj jest obsługa opcjonalnego typu wyliczeniowego - w razie niepodania ustawiamy wartość domyślną.
3. Nasz obiekt z 1. zajmuje się generowaniem odpowiedzi (zwraca obiekt DTO, który jest konwertowalny na reprezentacje tekstową).
Kolejną różnicą jest to, że login i hasło użytkownika są ustawiane w konstruktorze.

Plik odpowiadający za operacje CRUD na bazie danych: db/BookDb.hpp

W tym pliku jest zaprezentowany mechanizm ORM dostarczany przez bibliotekę, schowany za makrami preprocesora. Na uwagę zasługuje też konstruktor, który automatycznie tworzy bazę danych (ewentualnie aktualizuje do innej wersji).
Alternatywnie można dodawać kolejną wersję w formie tekstowej zamiast z pliku.

Plik tworzący schemat bazy danych: sql/001_init.sql

Jest to plik dla bazy danych SQLite3

Klasa odpowiadająca za logikę biznesową operacji na książkach: BookService

Są to dwa pliki: :
oraz :

Plik zawierający komponent bazy danych, odpowiedzialny za zarządzanie połączeniami z bazą danych: DatabaseComponent.hpp

W tym pliku należałoby dokonać zmian, gdybyśmy chcieli zmienić typ bazy danych np. na PostgreSQL:

Klasa zawierająca komponenty aplikacji: AppComponent.hpp

Jedyną różnicą w stosunku do poprzedniej wersji jest dodanie komponentu bazy danych:

Pliki bez zmian: SwaggerComponent.hpp (konfiguracja dokumentacji) i controller/StaticController.h (strona główna HTML)

i

Kod klienta

Kod klienta jest niemalże identyczny, trzeba zastosować zaktualizowane typy DTO, oraz wpisać wartości, jedynie trzeba pokombinować aby wyświetlić wartość wyliczenia w formie tekstowej:

Inne możliwości biblioteki Oat++

Biblioteka Oat++ jest naprawdę rozbudowana, o jej możliwościach można by napisać wiele artykułów. Postaram się jednak wymienić najważniejsze funkcjonalności, z odpowiednimi odnośnikami:

Testowanie aplikacji

Oat++ posiada funkcjonalności umożliwiające pisanie testów, które są częściowo opisane w sekcji poradnika Start krok po kroku. Testy są również obecne w oficjalnych przykładach, na przykład w przykładzie CRUD. Aby napisać testy, tworzy się klienckie API, które zostało opisane w ramach tego artykułu.

Obsługa plików binarnych

Oat++ wspiera również ładowanie plików. Oficjalny poradnik na ten temat znajduje się tutaj.

Obsługa CORS

Obsługa CORS (Cross-Origin Resource Sharing) w Oat++ realizowana jest za pomocą makr, które pozwalają na definiowanie polityki CORS dla poszczególnych endpointów. Dzięki temu aplikacje webowe mogą bezpiecznie komunikować się z serwerem Oat++ z różnych domen. Dokumentacja dotycząca konfiguracji CORS znajduje się na stronie CORS w Oat++. Poniżej znajduje się przykładowy kod, który dodaje obsługę CORS do endpointu:

W powyższym przykładzie makro `ADD_CORS(putUser)` dodaje obsługę CORS do endpointu `putUser`, co umożliwia przeglądarkom wykonywanie żądań typu PUT z innych domen. Dzięki temu mechanizmowi Oat++ pozwala na tworzenie bardziej elastycznych i bezpiecznych aplikacji webowych, które mogą komunikować się z serwerem bez ograniczeń związanych z polityką CORS.

Inne moduły

Oat++ zawiera wiele modułów, które umożliwiają integrację z różnymi usługami. W artykule używałem modułów: oatpp-libressl, oatpp-swagger i oatpp-sqlite, ale jest ich więcej:

• oatpp-consul - Moduł integrujący Oat++ z HashiCorp Consul, narzędziem do rejestracji i odkrywania usług w sieci. Dzięki temu modułowi aplikacje Oat++ mogą automatycznie rejestrować swoje usługi w Consul, co pozwala innym usługom na łatwe ich odnalezienie i wykorzystanie. Dodatkowo, oatpp-consul umożliwia monitorowanie stanu zdrowia zarejestrowanych usług, co zwiększa niezawodność i skalowalność całego systemu.
• oatpp-curl - Moduł umożliwiający wykonywanie zapytań HTTP przy użyciu libcurl.
• oatpp-libressl - Moduł dodający wsparcie dla SSL/TLS za pomocą biblioteki LibreSSL.
• oatpp-mbedtls - Moduł zapewniający wsparcie dla SSL/TLS przy użyciu biblioteki mbedTLS.
• oatpp-mongo - Adapter dla MongoDB, umożliwiający integrację z bazą danych NoSQL MongoDB.
• oatpp-postgresql - Adapter dla PostgreSQL, umożliwiający integrację z relacyjną bazą danych PostgreSQL.
• oatpp-sqlite - Adapter SQLite dla Oat++, umożliwiający korzystanie z lekkiej, wbudowanej bazy danych SQLite.
• oatpp-ssdp - Moduł do implementacji Simple Service Discovery Protocol (SSDP), używanego do odkrywania urządzeń w sieciach lokalnych. SSDP jest częścią standardu UPnP (Universal Plug and Play) i umożliwia urządzeniom takim jak drukarki, kamery czy inne urządzenia IoT ogłaszanie swojej obecności w sieci. Dzięki oatpp-ssdp aplikacje Oat++ mogą łatwo odnajdywać i komunikować się z innymi urządzeniami w tej samej sieci lokalnej, co jest szczególnie użyteczne w środowiskach IoT i smart home.
• oatpp-swagger - Moduł integrujący Swagger UI z Oat++, umożliwiający generowanie i prezentowanie dokumentacji API.
• oatpp-websocket - Moduł dodający wsparcie dla WebSocket, umożliwiający dwukierunkową komunikację w czasie rzeczywistym.
• oatpp-zlib - Moduł dodający wsparcie dla kompresji i dekompresji danych przy użyciu biblioteki zlib.

Dostępne przykłady zastosowań biblioteki

Oat++ ma dokumentacje jaką ma, tutorial ma jeden, najwięcej można zgłębić bibliotekę analizując oficjalne przykłady (wymieniam te, których wcześniej nie wymieniałem):

• Asynchroniczne API
• Integracja z Consul
• Streaming wideo
• Internet-of-Things Hue - demonstruje, jak używać Oat++ do odkrywania inteligentnych urządzeń oświetleniowych Philips Hue w sieci lokalnej za pomocą protokołu Simple Service Discovery Protocol (SSDP).
• Mikroserwis - łączący wiele usług w jedną aplikację (tworzy monolit)
• WebSocket
• YUV WebSocket Stream - pokazuje, jak używać Oat++ do przesyłania strumieniowego wideo YUV przez WebSocket z serwera na klienta w czasie rzeczywistym.
• CanChat - chat dla dziesiątek tysięcy użytkowników (zgodnie z opisem na GitHubie)

Podsumowanie

Biblioteka Oat++ w wersji 1.3.0 to potężne narzędzie do tworzenia usług webowych w C++. Mimo swojej złożoności, oferuje wiele funkcji ułatwiających tworzenie skalowalnych i wydajnych aplikacji webowych. Mam nadzieję, że dzięki temu artykułowi zrozumiesz podstawy korzystania z tej biblioteki i będziesz mógł/mogła stworzyć własny serwis REST w C++.

Bibliografia

• Strona domowa - zawiera instrukcje i dokumentację
• Dokumentacja API Index wszystkich plików nagłówkowych (najnowsza wersja)
• Artykuł/tutorial o tworzeniu prostych endpointów i generowaniu dokumentacji (niestety przestarzały)
• Główne repozytorium projektu
• Oficjalny opis modułu oatpp-swagger
• Moduł API Client w dokumentacji
• Tutorial wprowadzający (nieoficjalny) (dla wersji 1.1.0)
• Wysokopoziomowy przegląd biblioteki (na oficjalnej stronie)
• Artykuł wprowadzający w REST API w C++ (przy użyciu alternatywnego frameworka), część 2

Autorzy artykułu

Autor	Zakres zmian	Data	Afiliacja
Bazior Grzegorz	Utworzenie artykułu	sierpień 2024	Pracownik AGH w Krakowie