Postgraphile- graphql api w minute

Pracując w zespole gdzie prace są od początku do końca dokładnie zaplanowane, a każde kolejne funkcjonalności dodawane są według ustalonego harmonogramu problem rozjazdu prac frontowych z backendowymi nie powinien występować, a przynajmniej nie powinien powodować istotnych przestojów w pracy. Niestety, niewiele jest idealnych projektów i życie szybko weryfikuje plany przygotowane na starcie projektu. Trudne, a często niemożliwe jest budowanie widoków bez dobrze działającego API. Na ratunek może przyjść Postgraphile, który opisuję poniżej.

Charakterystyka

W kilku słowach o charakterystyce. Jak wspomniałem, Postgraphile to narzędzie służące do generowania API dla Graphql napisane w Node.js. Współpracuje z bazą Postgresql.

Wymagania

• npm
• Node 8.4+ (LTS)
• Postgresql (Latest), oficjalne wsparcie od 9.6,

Zalety:

• wydajność
• możliwość rozbudowy przez pluginy
• automatyczne generowanie mutacji CRUD
• możliwość użycia jako niezależna aplikacja lub plugin do istniejącej
• wsparcie dla JWT
• solidna dokumentacja
• wbudowane CLI

Po co ?

Słysząc o postgraphile pierwszy raz, nieco się zdziwiłem, w jaki sposób takowy generator API jest w stanie rozwiązać problemy, z którymi przyszło się zmierzyć. Zdziwienie wynikało oczywiście z nieznajomości narzędzia i jego możliwości. Kilka testów pokazało, że warto rozważyć Postgraphile przynajmniej w wersji MVP. Odpowiadając na pytanie "po co?" przychodzą mi do głowy 3 powody:

• gdy backend nie jest w stanie dotrzymać tępa frontowi w dostarczaniu api,
• gdy API ogranicza się w większości do CRUD'ów i nie ma sensu pisania 100x tego samego dla kolejnych modeli w bazie,
• gdy budżet lub czas jest mocno ograniczony.

O pierwszym powodzie wspomniałem we wstępie, drugi powód znam z życia. Oczywiście nieco upraszczam sprawę, jednakże wyobraźmy sobie, że backend musi wystawić tylko prosty interfejs np. dla 30 modeli, które są modyfikowane i w pewien sposób zależne od siebie, może okazać się szkoda czasu na pisanie CRUD'ów. Oczywiście są biblioteki czy frameworki, które robią to co Postgraphile, czyli generują API na podstawie modelu, ale postgraphile ma jeszcze co najmniej kilka funkcji, o których piszę, w kolejnej części artykułu.

Z trzecim powodem borykał się chyba każdy.. Nikt nie jest w stanie wyczarować więcej czasu i żadne pieniądze nie wydłużą nam miesiąca.

Możliwości

Przechodząc do najistotniejszej części wpisu, przestawię kilka funkcjonalności, które okazały się bardzo pomocne.

Zakładam, że Node jest zainstalowany oraz serwer Postgres'owy został uruchomiony na standardowym porcie.

Uruchomienie

Zacznijmy od instalacji i uruchomienia serwera.

$ npm install -g postgraphile

$ postgraphile -c "postgres:///mydb"

W wyniku uruchomienia powyższych komend powinniśmy otrzymać 2 endpointy:

http://localhost:5000/graphql - api graphql'owe

http://localhost:5000/graphiql - graphiql do testowania zapytań

Paginacja

Domyślnie istnieje możliwość uzyskania dostępu do pól PageInfo.startCursor oraz PageInfo.endCursor, które są bardzo przydatne do tworzenia paginacji w stylu frameworka Relay. Poniżej przykład z użyciem parametru after.

{
  myTestQuery(after: "NODE_ID") {
    edges {
      pageInfo {
        endCursor
      }
      
      node {
        id
        updated
        created
        name
      }
    }
  }
}

Filtry

W podstawowej wersji istnieje możliwość filtrowania queries po wybranych polach (np. name: "Jon"). Jeśli takie filtrowanie jest niewystarczające, można w łatwy sposób rozszerzyć api przez dodanie pluginu do zaawansowanego filtrowania, który dodaje argument filter do queries oraz dostarcza kolejne warunki np. większe, mniejsze, w przedziale itp.. Poniższy przykład pokazuje użycie połączonych warunków:

query myTest {
  myTest(filter: {
    or: [
      { name: { includesInsensitive: "Jon" } }
      { type: { equalTo: "ARTICLE" } }
    ]
  	}) {
    	edges {
          node {
            name
            type
            id
         }
      }
    }
  }
}

Więcej informacji można znaleźć tutaj.

Pluginy

Pluginy służą dodaniu do podstawowej wersji nowych możliwości, jak wspomniany wcześniej plugin do filtrowania.

Pełną listę pluginów można znaleźć na poniższych stronach:

https://www.graphile.org/postgraphile/plugin-gallery/ https://www.graphile.org/postgraphile/community-plugins/

Zakończenie

Na podsumowanie zwrócę uwagę na kilka rzeczy.

1. Podejście do takiego sposobu implementacji API może być "mieczem obusiecznym", więc warto planować kolejne etapy rozwoju. Z jednej strony dostajemy naprawdę wydajne i kompleksowe narzędzie, lecz z drugiej strony niesie to za sobą pewne ograniczenia, które mogą się okazać problematyczne np. konieczność wykonania jakieś customowej akcji w po mutacji.
2. Warto zwrócić uwagę na liczbę zagnieżdżeń w queries oraz limit elementów, które mogą zostać wrócone przez serwer. Nie jest sztuką zabić serwer. Jest to ogólna uwaga do pracy z graphql.