Star Trek API trafiło w końcu do sieci!

Zmiana priorytetów

Ostatni miesiąc poświęciłem w dużej mierze na doprowadzanie do działania strony głównej STAPI. Musiałem napisać dokumentację API, dorobić zliczanie statystyk encji i statystyk użycia endpointów, napisać trochę tekstów na stronę i pozamykać TODO, które oczekiwały na lepsze czasy. Tym niemniej dziś, w dniu końca konkursu, strona jest gotowa do pokazania światu.

Serwer

STAPI zostało postawione na serwerze dedykowanym Kimsufi. Tutaj moje doświadczenie było słabe. Na stronie Kimsufi.pl widnieje przechwałka, że serwer zostanie uruchomiony w 120 sekund. Uruchomienie mojego zabrało prawie 3 dni. Zamówiłem go w piątek po 17:00. 20 minut później wysłałem maila ponaglającego do supportu, który pozostał bez odpowiedzi aż do 14:30 w niedzielę. Wtedy dostałem odpowiedź, że w 120 sekund stawiane są serwery dla powracających klientów, a od nowych zazwyczaj wymaga się dokumentów potwierdzających tożsamość. U mnie obyło się bez wysyłania dokumentów, ale weryfikacja płatności trwała do 16:15 w poniedziałek. Przez cały poniedziałek wysłałem 4 kolejne maile ponaglające, które pozostały bez odpowiedzi.

System

System operacyjny w Kimsufi instaluje się przez webowy panel administracyjny. Na system wybrałem Ubuntu, które znam stosunkowo najlepiej. Na początku zainstalowałem wersję 17.04 (Zesty Zapus), ale ponieważ tutoriale na blogach, z których korzystałem, nie były z nią kompatybilne, cofnąłem się do wersji 16.04 (Xenial Xerus), która jest LTS-em.

Java i Oracle

Po tym, jak zainstalował się system, trzeba było zainstalować Javę 8. To robi się trzema łatwymi do wygooglania poleceniami, więc nie będę się nad tym rozwodził.

Grubszy problem wystąpił z bazą danych Oracle XI 11g, która nie jest oficjalnie wspierana na Ubuntu. Ponieważ jednak wśród wspieranych przez Oracle’a dystrybucji Linuxa nie było żadnej, którą można było zainstalować z panelu Kimsufi, postanowiłem pójść za najlepiej widocznym w Google tutorialem na temat instalacji Oracle’a na Ubuntu, jaki znalazłem. Jedyne, co musiałem zmienić w całej procedurze (napisanej dla Ubuntu 12.04), to sposób zaktualizowania parametrów jądra. Zamiast polecenia sudo service procps start, które nie chciało działać, wykonałem polecenie sysctl --system.

Deployment

Następnie trzeba było zasilić bazę z gotowego dumpu, który wygenerowałem kilka dni temu, oraz wrzucić wygenerowany plik WAR na Tomcata. Na tym etapie życia projektu proces deploymentu jest jeszcze mocno ręczny, ale w przyszłości na pewno go sobie zautomatyzuję. Na tę chwilę z automatu podmieniam tylko propertisy i generuje dumpa z innym schematem, niż schemat źródłowy, ale paczkę i bazę wgrywam z palca.

Problemy

Nic nigdy nie działa od pierwszego strzału, i tak samo było tym razem. Po wrzuceniu WAR-a na Tomcata nie było widać dokumentacji, ponieważ kontrakty nie były kopiowane do paczki. Ponadto okazało się, że część endpointów nie odpowiada, ponieważ ich nazwy były krótsze, niż sześć znaków, i leciał wyjątek, bo nie zabezpieczyłem się przed trywialnym StringIndexOutOfBoundsException.

Podsumowanie

Cieszę się, że udało mi się postawić stronę w ostatniej chwili. Dzięki temu lepiej widać, ile udało mi się zrobić przez ostatnie miesiące, i ile jeszcze pracy przede mną. Dodatkowo mam nadzieję, że sprawdzi mi się podejście release early, release often, i fandom Star Treka zainteresuje się tym projektem, zanim przyjdzie mi skończyć go w pojedynkę. Chociaż wcale się przed tym nie uchylam.

Gdy zaczynałem pracę nad Star Trek API, naturalnym wydało mi się zastosowanie jakiegoś lintera do Javy. Wybór padł na popularny Chekstyle. To żadne zaskoczenie, ale ponad połowa kodu, który w tej chwili znajduje się w repozytorium projektu, to kod testów napisanych w Spocku, czyli w efekcie w Groovym. Udało mi się znaleźć tylko jeden linter do Grooviego, CodeNarc, który opiszę w tym poście.

Instalacja

Jeśli budujemy projekt za pośrednictwem Gradle’a, jak w moim przypadku, instalacja ogranicza się do dodania do Gradle’a pluginu:

apply plugin: 'codenarc'


I skonfigurowania:

codenarc {
configFile = "$rootDir/codenarc.groovy" as File
toolVersion = '0.26.0'
}


Następnie trzeba stworzyć plik codenarc.groovy w katalogu głównym projektu, lub w dowolnym innym, jeśli wskażemy go w konfiguracji. Gdy to zrobimy, mamy dostępne dwie nowe komendy:

gradle codenarcMain
gradle codenarcTest


Pierwsza komenda sprawdza, czy produkcyjny kod w Groovim jest zgodny z aktywowanymi w CodeNarcu regułami, a druga robi to samo dla kodu testów. Ponieważ w projekcie nie mam żadnego kodu produkcyjnego w Groovym, przy walidacji kodu posługuję się tylko tą drugą komendą.

Dodatkowo teraz, gdy wywołujemy komendę gradle check, wykonywane są też walidacje pochodzące z CodeNarcu.

Konfiguracja

Cała konfiguracja Codenarcu odbywa się we wspomnianym już pliku codenarc.groovy. Alternatywnie można skorzystać z konfiguracji przez plik z propertisami, ale ja wybrałem plik Groovy.

Postanowiłem zacząć od wrzucenia pliku ze wszystkimi regułami domyślnie włączonymi, i po kolei rezygnować z tych, które uznałem za bezcelowe lub niemające znaczenia. Mimo wszystko nie zrezygnowałem z dużej liczby reguł, ponieważ kod testów jest z natury prostszy, niż kod produkcyjny, a więc nie tak wiele rzeczy trzeba było poprawiać, żeby walidacje przechodziły.

Ostatecznie mój plik z regułami wygląda tak.

Wyłączone reguły

Oto wybrane reguły, które wyłączyłem w Star Trek API, wraz z powodami wyłączenia:

• NoTabCharacter – ponieważ w całym projekcie używam tabów.
• AbstractClassWithoutAbstractMethod – ponieważ czasami moje klasy abstrakcyjne mają tylko pola, których wartości używane są w testach.
• TrailingComma – w testach rzadko zmienia się kolejność w listach po ich utworzeniu.
• ClassJavadoc – zgodnie z regułami clean code’u, piszę bardzo mało dokumentacji do kodu. Jeszcze mniej sensu miałoby pisanie jej w testach, gdzie, IMO, dostateczną dokumentację stanowią nazwy metod testowych pisane językiem naturalnym.
• SpaceAroundMapEntryColon – wydawało mi się nienaturalne, by konstruktor mapy zapisywać jako [ : ], a nie [:]. CodeNarc jest pierwszym miejscem, gdzie spotkałem się z takim zapisem.
• MethodSize – domyślnie metoda może mieć sto linii. W przypadku metod testowych nie ma sensu robić wygibasów, by je podzielić, zwłaszcza że są już podzielone przez bloki given, when: i then:.
• AUnnecessaryObjectReferences – reguła zabrania odwoływania się do jednego obiektu więcej, niż domyślne 5 razy. Często natomiast w testach mam sytuację, gdy robię assercje nawet na kilkudziesięciu polach jednego obiektu. Jako alternatywę CodeNarc podaje zapis with. Ten zapis nie jest niestety wspierany przez moje IDE, więc automatyczny refaktor go nie obejmie, i nie można korzystać w bloku with z podpowiadania składni.

Przekonfigurowane reguły

Następujących reguł nie wyłączyłem, ale je przekonfigurowałem:

LineLength – dopuszczalna długość linii została ustawiona na 150 znaków, podobnie jak w Checkstyle’u.

BuilderMethodWithSideEffects – CodeNarc traktował wszystkie metody, które zaczynały się od create jako metody wytwórcze, które nie mogą mieć efektów ubocznych. Ja natomiast mam metody testowe, których opis w języku naturalnym zaczyna się od create, więc zmieniłem regułę tak, aby były brane pod uwagę tylko te metody, które zaczynają się od create, po którym następuje wielka litera.

PackageName – musiałem dopuścić camel case w nazwach paczek.

Najczęściej ignorowane reguły

Oto lista reguł, które najczęściej ignoruję w pojedynczych metodach lub klasach:

• LineLength – w niektórych miejscach lepiej nie łamać linii, gdy są za długie, bo czytelność jest gorsza. Używam też tego wykluczenia w przypadku testów z datatables.
• RuntimeException – w niektórych testach asercje wykonuję w pętlach, więc rzucam z nich wyjątki. Nie widziałem potrzeby tworzenia nowego typu wyjątku tylko na ten przypadek, więc dozwoliłem rzucanie wyjątków typu RuntimeException.
• BracesForMethod – czasami metoda ma długi opis, i wtedy jest zapisywana z trzema cudzysłowami, a nie z jednym. W tym przypadku trzeba wyłączyć regułę BraceForMethod.

Czego można się dowiedzieć

Podczas implementowania CodeNarcu dowiedzieć się można kilku ciekawy rzeczy. Ja dowiedziałem się następujących:

• Ostatnie domknięcie w ciągu metod może być zapisane bez nawiasów okrągłych. Czyli .do { it.stuff() } zamiast .do({ it.stuff() }).
• Nie powinno się zapisywać metod voidowych jako def something(), ponieważ def oznacza tyle, co Object, a metody voidowe, takie jak metody testowe, niczego nie zwracają.
• Nie ma sensu zapisywać stringów w podwójnych cudzysłowach, jeśli nie robimy w nich interpolacji. Także z powodów wydajnościowych.

Podsumowanie

Zastanawiam się, ile osób używa CodeNarcu w stosunku do produkcyjnego kodu w Groovim. Na GitHubie ma on zaledwie 120 gwiazdek, w porównaniu do 1985 gwiazdek, które ma Checkstyle.

CodeNarc na pewno poprawia jakość kodu, który piszemy. Pewnie miałbym z niego więcej użytku, gdybym w Groovim nie pisał tylko testów. Mimo wszystko pomaga, choćby w usuwaniu nieużywanych zmiennych i formatowaniu kodu.

Planuję doprowadzić development Star Trek API do końca. Będę przez jakiś czas, być może całkiem długi czas, jedyną osobą, która będzie płaciła za utrzymanie serwera, na którym API będzie działało. Nie planuję inwestować w taki serwer zbyt wielu środków, dlatego w moim interesie jest, by zrealizować wydajne cache’owanie. Przyda mi się ono na pewno, biorąc pod uwagę fakt, że do tej pory do Pokéapi zostało wykonane 175 milionów zapytań.

Wymagania

Wymagania dotyczące cache’u w Star Trek API są relatywnie proste, w porównaniu do innych systemów. Dane, które trafią do bazy, czeka jeden z dwóch scenariuszy. W pierwszym scenariuszu dane nie będą się zmieniać, gdy już trafią do bazy, ponieważ zasilenie dokona się poza serwerem aplikacyjnym, i serwerowi aplikacyjnemu zostanie tylko wskazana napełniona baza. Drugi scenariusz jest taki, że dane zmienią się co prawda, ale będę mógł kontrolować moment, gdy się to stanie, i wówczas będzie można wyczyścić cache. Problem inwalidacji cache’y w zasadzie nie będzie istniał.

Instalacja i konfiguracja

A móc używać EhCache, po pierwsze trzeba dodać do projektu zależności. Ja dodałem dwie:

compile group: 'net.sf.ehcache', name: 'ehcache'
compile group: 'org.hibernate', name: 'hibernate-ehcache'

Po drugie, trzeba skonfigurować przynajmniej domyślny cache. EhCache pozwala na składowanie cache’owanych zasobów w wielu regionach, ale zdecydowałem na początek, że przynajmniej póki nie będę wiedział więcej o tym, jakie zasoby są najczęściej kwerendowane, nie chcę przekombinować z konfiguracją. Moja obecna konfiguracja wygląda więc tak, i jest najbardziej podstawową wersją, jaka może być.

Integracja z Hibernatem

EntityManagerFactory musi dostać kilka dodatkowy propertisów, widocznych tutaj. Trzeba więc między innymi włączyć cache drugiego poziomu, a także wskazać EhCache jako fabrykę regionów cache’u. Oznacza to klasę implementującą interfejs zdefiniowany przez Hibernate’a, który gwarantuje wytworzenie kilku kolejnych obiektów, odpowiedzialnych kolejno za cache’owanie między innymi kolekcji, wyników zapytań, i encji.

Strategia cache’owania

Wymyśliłem, że dodatkowo będę miał własną strategię cache’owania. Interfejs jest prosty i wygląda tak. Strategia dostanie QueryBuilder, czyli obiekt, w którym przed wykonaniem zapytania gromadzone są jego parametry (kryteria zawężające, sortowanie, relacje do pobrania). Strategię cache’owania można zdefiniować w propertisach aplikacji. Napisałem trzy strategie. Jedną, która zawsze zwraca prawdę, druga, która zawsze zwraca fałsz, i trzecią, najciekawszą, której chce domyślnie używać, i która zwraca prawdę warunkowo, gdy jedynym kryterium w zapytaniu jest UID, czyli unikalny identyfikator obiektu.

Cache’owanie encji

Gdy już mamy wszystko zintegrowane, trzeba wyznaczyć encje, które będą cache’owane. W moich przypadku są to wszystkie encje, które trafiają do REST-owego i SOAP-owego API. Do encji trzeba było dodać adnotację @Cache, tak jak zostało zrobione tutaj. Dodatkowo napisałem test, który z pomocą refleksji pilnuje, żeby wszystkie encje, poza jawnie określonymi, miały zawsze adnotację @Cache. Napisałem też drugi test, który to samo robi dla pól zawierających relacje jeden do wielu i wiele do wielu.

Testy

Pozostało mi przetestować ten setup. Testy manualne polegały na zapytaniu kilku endpointów i obserwowaniu, jakie zapytania odkładają się w logach za pierwszym i za kolejnymi razami. Za kolejnymi razami było tych zapytań zdecydowanie mniej, chociaż ciągle jeszcze jakieś się pojawiają i będę musiał wrócić do tematu, żeby maksymalnie wyżyłować EhCache. Prędkość odpowiedzi endpointów za kolejnymi zapytaniami znacząco wzrosła.

Podsumowanie

Przewiduję, ze klienty będą wykonywać relatywnie mało zapytań przeszukujących bazę, w których zestaw kryteriów zapytania jest słabo powtarzalny, a relatywnie dużo zapytań, które pytają o konkretny zasób za pośrednictwem UID. To założenie może z łatwością okazać się nieprawdziwe, a wtedy trzeba będzie przestrajać cache. Ale to może być temat na kolejny post, za kilka miesięcy.

W trakcie pracy nad Star Trek API spotykam dwa rodzaje modeli. Jedne to modele dotyczące uniwersum Star Treka, a drugie to modele dotyczące prawdziwego świata. Do modeli dotyczących uniwersum zaliczyć można lokalizacje, obiekty astronomiczne, jedzenie czy statki kosmiczne, a do modeli z prawdziwego świata – filmy, aktorów, komiksy czy firmy pracujące nad produkcją. Istnieją między nimi różnice, które opiszę w tym poście.

Ilość

Pierwsza różnica to różnica w ilości modeli. Tych z prawdziwego świata jest trochę mniej. Obecnie mam ich zrealizowanych 13, a zaplanowanych kolejne 6. W przypadku modeli z uniwersum zrealizowanych jest 6, a zaplanowanych do realizacji – kolejne 17. Postęp moich prac można śledzić tutaj. Także ilość krotek w modelach różni się. Osób pracujących nad Star Trekiem jest ponad 6000, a aktorów, kaskaderów i innych wykonawców widocznych na ekranie – ponad 5000. Jeśli chodzi o modele z uniwersum, najwięcej, około 5000, jest postaci, a potem są już obiekty astronomiczne i miejsca, jedne i drugie z wynikiem poniżej 2000 krotek.

Relacje

Modele z prawdziwego świata mają znacznie więcej relacji, niż modele z uniwersum, i są one znacznie lepiej uporządkowane. Przykładowo, ksiązki mają aż 11 relacji wiele do wielu: serie książek, autorów, artystów, edytorów, narratorów audiobooków, wydawców, wydawców audiobooków, postacie, identyfikatory wydań książek (ISBN, ASIN) i identyfikatory wydań audiobooków, oraz kolekcje książek. Modele z uniwersum, które mają najwięcej relacji, to obiekt astronomiczny, seria książek i seria komiksów. Mają one relacje do nadrzędnego elementu i do podrzędnych elementów tego samego typu. Większość modeli z uniwersum nie ma żadnych relacji.

Modele z uniwersum mają jednak na ogół więcej flag booleanowych. Każda kategoria, np. dotyczące lokalizacji, może być przetłumaczona na jedną flagę w modelu. I tak w encji Localization znajdujemy takie flagi, jak bodyOfWater, colony czy school. Większość flag dla większości krotek będzie naturalnie ustawiona na fałsz.

Kompletność

Model z prawdziwego świata ma zazwyczaj więcej danych, niż model z uniwersum, z oczywistego powodu: wydarzenia muszą mieć daty, ludzie nazwiska, a książki zawsze określoną ilość stron. W przypadku modeli z uniwersum wiemy tylko tyle, ile powiedziano w kanonicznych produkcjach. Najczęściej jest tak, że jakiś byt dający się ująć w model występuje w serialu przez chwilę, jest wspomniany raz, i nigdy więcej nie zostaje potem użyty. Przykładem niech będzie ten kawior, o którym wiemy tylko tyle, że był słony, ale nawet ta informacja jest zbyt egzotyczna, by ująć ją w model.

Model z prawdziwego świata można próbować uzupełniać w innych źródłach. Można spróbować zgadnąć płeć aktora na podstawie płci jego imienia lub znaleźć jego datę urodzenia w IMDb. W przypadku modelu z uniwersum, który nie ma kompletnych danych, można tylko liczyć, że dany byt zostanie jeszcze w przyszłości wspomniany w jakimś medium.

Podsumowanie

Mogąc wybierać między modelami z prawdziwego świata i tymi z uniwersum, wolę pisać kod parsujący te drugie. Jest to łatwiejsze, szybsze i odkrywam wówczas model, który jakoś nakłada się na moje wspomnienia z oglądania kolejnych sezonów Star Treka. Ale żeby API było kompletne, nic nie może zostać potraktowane po macoszemu. Z drugiej strony, przez ostatnie miesiące częściej brałem się za modele z prawdziwego świata, niż za modele z uniwersum. Robiłem tak dlatego, żeby nie stracić zainteresowania projektem i najlepsze zostawić sobie na koniec.

Podczas tworzenia Star Trek API szybko doszedłem do wniosku, że nie mogę ujawniać klientom API ID-ków bazodanowych. Powodem było to, że ID-ki te nieustannie się zmieniały. Ilekroć robiłem zasilenie od nowa, było niemal pewne, że dostanę nieco inne zestaw stron, które zostaną przetworzone w innej, niż poprzednio, kolejności. Wydało mi się oczywiste, że gdybym sam chciał skorzystać z danych tego typu, jak udostępniane przez moje API, oczekiwałbym, że ID będą stałe. Chciałbym je gdzieś zapisywać i posługiwać się nimi w przyszłej komunikacji z API.

Zadanie

Trzeba było wymyślić sposób na to, aby generować stałe, lub przynajmniej w ogromnej większości przypadków stałe identyfikatory dla wszystkich encji. Dodatkowym bonusem byłoby to, aby identyfikatory były unikalne w obrębie całego API.

Wykonanie

Memory Alpha i Memory Beta mają własną numerację stron, którą na szczęście ujawniają. Każda strona ma ID, który nie zmienia się przez cały cykl jej życia, nawet wówczas, gdy strona zostanie przeniesiona pod inną nazwę. Identyfikatory stron z z wiki mogły więc zostać pierwszą ważną częścią identyfikatora, który już wówczas zacząłem nazywać GUID-em, a któremu ostatnio zmieniłem nazwę na UID, by nie było wątpliwości, że to co innego, niż GUID.

Od razu było jasne, że potrzebuję jeszcze czegoś, co identyfikowałoby encję w unikalny sposób. ID-ki z Memory Alpha i Memory Beta mogły się powtarzać. Do UID-ów dołączyłem więc 2 znaki, które reprezentowały encję, oraz 2 znaki, które reprezentowały źródło. W ten sposób powstał na przykład UID, który wyglądał tak: CLMA0000108985. Dwa pierwsze znaki, CL, oznaczały encję ComicCollection, dwa kolejne, MA, oznaczały, że źródłem jest Memory Alpha. Natomiast 10 cyfr to ID z wiki. Razem zawsze 14 znaków, co wydało mi się wystarczające na API tej wielkości.

Pierwsze, i na razie jedyne, kłopoty

Pierwszy i na razie jedyny problem, który napotkałem, dotyczył bytów, które nie mapowały się na dokładnie jedną stronę z wiki. Chodziło o encje reprezentujące numery ISBN i ASIN. Na jednej stronie mogło występować kilka takich numerów.

Na szczęście numery ISBN mają 10 lub 13 znaków, a numery ASIN – 10 znaków. Łatwo było z nich wygenerować 14-znakowe UID-y. 10-znakowym numer ISBN mają po prostu format ISBN160010603X, 13-znakowe ISBN-y format I9781566199094, a 10-znakowe numery ASIN-y – format ASINB008L4YH4W. Można więc w dalszym ciągu zagwarantować unikalność UID-u w systemie.

Implementacja

Ostatecznie wszystkie te wymagania zostały zaimplementowany w klasie UidGenerator. Klasa jest wołana zawsze, zanim encja zostanie pierwszy raz zapisana, i w ten sposób UID zawsze jest obecny.

UID-y zastępują w API bazodanowe identyfikatory. To nimi pyta się o pojedyncze REST-owe i SOAP-owe obiekty. UID-y też, wraz z nazwami lub tytułami, trafiają do encji nagłówkowych, takich jak MovieHeader. Na ich podstawie, gdy ktoś będzie chciał, będzie mógł pobrać więcej danych na temat interesującej encji.

UidGenerator podczas inicjowania aplikacji sprawdza, czy będzie potrafił wygenerować unikalne identyfikatory dla wszystkich encji. Jeśli nie, trzeba dodatkowo dodać identyfikator skrócony identyfikator encji w statycznej mapie. W nieprawdopodobnym przypadku, gdy ID strony z Memory Alpha lub Memory Beta będzie większy, niż 9999999999, zostanie rzucony wyjątek, którym będzie trzeba się zająć. Ale to temat na odległą przyszłość.