Een gids voor Google-Http-Client

1. Overzicht

In dit artikel zullen we de Google HTTP-clientbibliotheek voor Java bekijken, een snelle, goed samengestelde bibliotheek voor toegang tot alle bronnen via het HTTP-verbindingsprotocol.

De belangrijkste kenmerken van de klant zijn:

  • een HTTP-abstractielaag waarmee u elke bibliotheek op laag niveau kunt ontkoppelen
  • snelle, efficiënte en flexibele JSON- en XML-parseermodellen van de HTTP-respons en verzoekinhoud
  • eenvoudig te gebruiken annotaties en abstracties voor HTTP-resourcetoewijzingen

De bibliotheek kan ook worden gebruikt in Java 5 en hoger, waardoor het een aanzienlijke keuze is voor legacy (SE en EE) projecten.

In dit artikel gaan we een eenvoudige applicatie ontwikkelen die zal verbinding maken met de GitHub API en gebruikers ophalen, terwijl enkele van de meest interessante functies van de bibliotheek worden behandeld.

2. Maven afhankelijkheden

Om de bibliotheek te gebruiken hebben we het google-http-client afhankelijkheid:

 com.google.http-client google-http-client 1.23.0 

De nieuwste versie is te vinden op Maven Central.

3. Een eenvoudig verzoek doen

Laten we beginnen met het maken van een eenvoudig GET-verzoek naar de GitHub-pagina om te laten zien hoe de Google Http-client uit de doos werkt:

HttpRequestFactory requestFactory = nieuwe NetHttpTransport (). CreateRequestFactory (); HttpRequest request = requestFactory.buildGetRequest (nieuwe GenericUrl ("// github.com")); Tekenreeks rawResponse = request.execute (). ParseAsString ()

Om het eenvoudigste verzoek te doen, hebben we ten minste het volgende nodig:

  • HttpRequestFactory dit wordt gebruikt om onze verzoeken op te bouwen
  • HttpTransport een abstractie van de low-level HTTP-transportlaag
  • GenericUrl een klasse die de URL verpakt
  • HttpRequest behandelt de daadwerkelijke uitvoering van het verzoek

We zullen al deze en een meer complex voorbeeld doornemen met een daadwerkelijke API die een JSON-indeling retourneert in de volgende secties.

4. Pluggable HTTP-transport

De bibliotheek heeft een goed geabstraheerd HttpTransport klasse waarmee we erop kunnen bouwen en wijzigen in de onderliggende low-level HTTP-transportbibliotheek naar keuze:

openbare klasse GitHubExample {statische HttpTransport HTTP_TRANSPORT = nieuwe NetHttpTransport (); }

In dit voorbeeld gebruiken we de NetHttpTransport, die is gebaseerd op de HttpURLConnection dat is te vinden in alle Java SDK's. Dit is een goede startkeuze omdat het bekend en betrouwbaar is.

Het kan natuurlijk voorkomen dat we wat geavanceerde aanpassingen nodig hebben, en dus de vereiste van een complexere bibliotheek op laag niveau.

Voor dit soort gevallen is er de ApacheHttp Transport:

openbare klasse GitHubExample {statische HttpTransport HTTP_TRANSPORT = nieuwe ApacheHttpTransport (); }

De ApacheHttpTransport is gebaseerd op de populaire Apache HttpClient die een breed scala aan keuzes bevat om verbindingen te configureren.

Bovendien biedt de bibliotheek de mogelijkheid om uw implementatie op laag niveau te bouwen, waardoor deze zeer flexibel is.

5. JSON-parsering

De Google Http-client bevat nog een abstractie voor JSON-parsing. Een groot voordeel hiervan is dat de keuze voor een low-level parsing-bibliotheek is uitwisselbaar.

Er zijn drie ingebouwde keuzes, die allemaal kunnen worden uitgebreid JsonFactory, en het omvat ook de mogelijkheid om onze eigen te implementeren.

5.1. Verwisselbare parseerbibliotheek

In ons voorbeeld gaan we de Jackson2-implementatie gebruiken, waarvoor de google-http-client-jackson2 afhankelijkheid:

 com.google.http-client google-http-client-jackson2 1.23.0 

Hierna kunnen we nu de JsonFactory:

openbare klasse GitHubExample {statische HttpTransport HTTP_TRANSPORT = nieuwe NetHttpTransport (); staticJsonFactory JSON_FACTORY = nieuwe JacksonFactory (); }

De JacksonFactory is de snelste en meest populaire bibliotheek voor parsing / serialisatiebewerkingen.

Dit gaat ten koste van de omvang van de bibliotheek (wat in bepaalde situaties een probleem kan zijn). Om deze reden biedt Google ook de GsonFactory, een implementatie van de Google GSON-bibliotheek, een lichtgewicht JSON-parseerbibliotheek.

Er is ook de mogelijkheid om onze low-level parser-implementatie te schrijven.

5.2. De @Sleutel Annotatie

We kunnen de @Sleutel annotatie om velden aan te geven die moeten worden geparseerd van of geserialiseerd naar JSON:

openbare klasse Gebruiker {@Key privé String-login; @Key privé lange id; @Key ("email") privé String e-mail; // standaard getters en setters}

Hier maken we een Gebruiker abstractie, die we in batch ontvangen van de GitHub API (we zullen later in dit artikel naar de daadwerkelijke parsering gaan).

Houd er rekening mee dat velden die niet de @Sleutel annotaties worden als intern beschouwd en worden niet geparseerd van of geserialiseerd naar JSON. Ook de zichtbaarheid van de velden doet er niet toe, noch het bestaan ​​van de getter- of setter-methoden.

We kunnen de waarde van de @Sleutel annotatie, om deze toe te wijzen aan de juiste JSON-sleutel.

5.3. GenericJson

Alleen de velden die we aangeven en markeren als @Sleutel worden ontleed.

Om de andere inhoud te behouden, kunnen we verklaren dat onze klas moet worden uitgebreid GenericJson:

openbare klasse Gebruiker breidt GenericJson {// ...} uit

GenericJson implementeert het Kaart interface, wat betekent dat we de methoden get en put kunnen gebruiken om JSON-inhoud in het verzoek / antwoord in te stellen / op te halen.

6. De oproep plaatsen

Om verbinding te maken met een eindpunt met de Google Http-client, hebben we een HttpRequestFactory, die zal worden geconfigureerd met onze vorige abstracties HttpTransport en JsonFactory:

openbare klasse GitHubExample {statische HttpTransport HTTP_TRANSPORT = nieuwe NetHttpTransport (); statische JsonFactory JSON_FACTORY = nieuwe JacksonFactory (); private static void run () gooit uitzondering {HttpRequestFactory requestFactory = HTTP_TRANSPORT.createRequestFactory ((HttpRequest request) -> {request.setParser (nieuwe JsonObjectParser (JSON_FACTORY));}); }}

Het volgende dat we nodig hebben, is een URL om verbinding mee te maken. De bibliotheek behandelt dit als een uitbreiding van de klasse GenericUrl waarop elk gedeclareerd veld wordt behandeld als een queryparameter:

openbare klasse GitHubUrl breidt GenericUrl uit {openbare GitHubUrl (String encodedUrl) {super (encodedUrl); } @Key openbare int per_page; }

Hier in onze GitHubUrl, we verklaren het per pagina eigenschap om aan te geven hoeveel gebruikers we willen in een enkele aanroep naar de GitHub API.

Laten we doorgaan met het bouwen van onze oproep met behulp van de GitHubUrl:

private static void run () gooit uitzondering {HttpRequestFactory requestFactory = HTTP_TRANSPORT.createRequestFactory ((HttpRequest request) -> {request.setParser (nieuwe JsonObjectParser (JSON_FACTORY));}); GitHubUrl url = nieuwe GitHubUrl ("// api.github.com/users"); url.per_page = 10; HttpRequest request = requestFactory.buildGetRequest (url); Typ type = nieuw TypeToken() {} .getType (); Lijst gebruikers = (Lijst) verzoek .execute () .parseAs (type); }

Merk op hoe we specificeren hoeveel gebruikers we nodig hebben voor de API-aanroep, en dan bouwen we het verzoek met de HttpRequestFactory.

Hierna, aangezien het antwoord van de GitHub API een lijst met gebruikers bevat, moeten we een complex Type, wat een is Lijst.

Vervolgens voeren we op de laatste regel de oproep uit en analyseren we het antwoord op een lijst met onze Gebruiker klasse.

7. Aangepaste kopteksten

Een ding dat we meestal doen bij het maken van een API-verzoek, is een soort aangepaste koptekst of zelfs een aangepaste koptekst opnemen:

HttpHeaders headers = request.getHeaders (); headers.setUserAgent ("Baeldung-client"); headers.set ("Tijdzone", "Europa / Amsterdam");

We doen dit door het HttpHeaders nadat we ons verzoek hebben gemaakt, maar voordat we het uitvoeren en de nodige waarden toevoegen.

Houd er rekening mee dat de Google Http Client bevat enkele kopteksten als speciale methoden. De User-Agent header, als we het bijvoorbeeld proberen op te nemen met alleen de set-methode, zou dit een fout veroorzaken.

8. Exponentiële terugval

Een ander belangrijk kenmerk van de Google Http Client is de mogelijkheid om verzoeken opnieuw te proberen op basis van bepaalde statuscodes en drempels.

We kunnen onze exponentiële backoff-instellingen opnemen direct nadat we ons verzoekobject hebben gemaakt:

ExponentialBackOff backoff = nieuwe ExponentialBackOff.Builder () .setInitialIntervalMillis (500) .setMaxElapsedTimeMillis (900000) .setMaxIntervalMillis (6000) .setMultiplier (1.5) .setRandomizationFactor (0.5) .build (); request.setUnsuccessfulResponseHandler (nieuwe HttpBackOffUnsuccessfulResponseHandler (backoff));

Exponential Backoff is standaard uitgeschakeld in HttpRequest, dus we moeten een exemplaar van HttpUnsuccessfulResponseHandler naar de HttpRequest om het te activeren.

9. Logboekregistratie

De Google Http-client gebruikt java.util.logging.Logger voor het loggen van HTTP-verzoek- en responsdetails, inclusief URL, kopteksten en inhoud.

Gewoonlijk wordt logboekregistratie beheerd met behulp van een logging.properties het dossier:

handlers = java.util.logging.ConsoleHandler java.util.logging.ConsoleHandler.level = ALLES com.google.api.client.http.level = ALL

In ons voorbeeld gebruiken we ConsoleHandler, maar het is ook mogelijk om de FileHandler.

Het eigenschappenbestand configureert de werking van de JDK-logboekregistratie. Dit configuratiebestand kan worden gespecificeerd als een systeemeigenschap:

-Djava.util.logging.config.file = logging.properties

Dus na het instellen van de bestands- en systeemeigenschappen, zal de bibliotheek een logboek produceren zoals het volgende:

-------------- AANVRAAG -------------- GET //api.github.com/users?page=1&per_page=10 Accept-codering: gzip User-Agent: Google-HTTP-Java-Client / 1.23.0 (gzip) 12 november 2017 18:43:15 com.google.api.client.http.HttpRequest curl -v --compressed -H 'Accepteren -Encoding: gzip '-H' User-Agent: Google-HTTP-Java-Client / 1.23.0 (gzip) '-' //api.github.com/users?page=1&per_page=10 '12 november 2017 18:43:16 com.google.api.client.http.HttpResponse -------------- REACTIE -------------- HTTP / 1.1 200 OK Status: 200 OK Overdrachtcodering: chunked Server: GitHub.com Access-Control-Allow-Origin: * ... Link:; rel = "volgende",; rel = "first" X-GitHub-Request-Id: 8D6A: 1B54F: 3377D97: 3E37B36: 5A08DC93 Inhoudstype: application / json; charset = utf-8 ...

10. Conclusie

In deze zelfstudie hebben we de Google HTTP-clientbibliotheek voor Java en de meer handige functies laten zien. Hun Github bevat meer informatie erover, evenals de broncode van de bibliotheek.

Zoals altijd is de volledige broncode van deze tutorial beschikbaar op GitHub.