streamalism.org

1. Oversikt

I denne veiledningen introduserer vi Feign - en deklarativ HTTP-klient utviklet av Netflix.

Feign har som mål å forenkle HTTP API-klienter. Enkelt sagt, utvikleren trenger bare å erklære og kommentere et grensesnitt mens den faktiske implementeringen klargjøres ved kjøretid.

2. Eksempel

Gjennom denne opplæringen bruker vi et eksempel på en bokhandelapplikasjon som avslører REST API-endepunktet.

Vi kan enkelt klone prosjektet og kjøre det lokalt:

mvn installer spring-boot: run

3. Oppsett

La oss først legge til de nødvendige avhengighetene:

 io.github.openfeign feign-okhttp 10.11 io.github.openfeign feign-gson 10.11 io.github.openfeign feign-slf4j 10.11 

I tillegg til feign-core avhengighet (som også trekkes inn), bruker vi noen få plugins, spesielt: feign-okhttp for internt bruk av Square's OkHttp-klient for å komme med forespørsler, feign-gson for bruk av Googles GSON som JSON-prosessor og feign- slf4j for bruk av Enkel loggfasade for å logge forespørsler.

For å faktisk få litt loggutgang, trenger vi vår favoritt, SLF4J-støttede loggerimplementering på klassestien.

Før vi fortsetter å lage vårt klientgrensesnitt, setter vi først opp en Bok modell for å oppbevare dataene:

public class Book {private String isbn; privat strengforfatter; privat strengetittel; privat String synopsis; private String språk; // standard konstruktør, getters og setters}

MERK: I det minste trengs en “ingen argumenter-konstruktør” av en JSON-prosessor.

Faktisk er vår REST-leverandør et hypermedia-drevet API, så vi trenger i tillegg en enkel emballasjeklasse:

offentlig klasse BookResource {privat bokbok; // standard konstruktør, getters og setters}

Merk: Vi‘Jeg beholder BookResource enkelt fordi Feign-klienten vår ikke drar nytte av hypermedia-funksjoner!

4. Serversiden

For å forstå hvordan du definerer en Feign-klient, vil vi først se på noen av metodene og svarene som støttes av vår REST-leverandør.

La oss prøve det med en enkel curl shell-kommando for å liste opp alle bøkene. Vi må huske å føre alle samtalene foran / api, som er applikasjonens servlet-kontekst:

krøll // localhost: 8081 / api / bøker

Som et resultat får vi et komplett boklager representert som JSON:

[{"book": {"isbn": "1447264533", "author": "Margaret Mitchell", "title": "Gone with the Wind", "synopsis": null, "language": null}, "links ": [{" rel ":" self "," href ":" // localhost: 8081 / api / books / 1447264533 "}]}, ... {" book ": {" isbn ":" 0451524934 ", "author": "George Orwell", "title": "1984", "synopsis": null, "language": null}, "links": [{"rel": "self", "href": "/ / localhost: 8081 / api / books / 0451524934 "}]}]

Vi kan også spørre enkeltpersoner Bok ressurs, ved å legge ISBN til en get-forespørsel:

krøll // localhost: 8081 / api / books / 1447264533

5. Feign-klient

Til slutt, la oss definere vår Feign-klient.

Vi bruker @RequestLine kommentar for å spesifisere HTTP-verbet og en sti-del som et argument. Parametrene vil bli modellert ved hjelp av @Param kommentar:

offentlig grensesnitt BookClient {@RequestLine ("GET / {isbn}") BookResource findByIsbn (@Param ("isbn") Streng isbn); @RequestLine ("GET") Liste findAll (); @RequestLine ("POST") @Headers ("Content-Type: application / json") void create (Book book); }

MERK: Feign-klienter kan bare brukes til å konsumere tekstbaserte HTTP APIer, noe som betyr at de ikke kan håndtere binære data, f.eks. filopplastinger eller nedlastinger.

Det er alt! Nå skal vi bruke Feign.builder () for å konfigurere vår grensesnittbaserte klient. Den faktiske implementeringen vil bli klargjort ved kjøretid:

BookClient bookClient = Feign.builder () .client (ny OkHttpClient ()) .encoder (ny GsonEncoder ()). Dekoder (ny GsonDecoder ()) .logger (ny Slf4jLogger (BookClient.class)) .logLevel (Logger.Level. FULL) .target (BookClient.class, "// localhost: 8081 / api / books");

Feign støtter forskjellige plugins som JSON / XML-kodere og dekodere eller en underliggende HTTP-klient for å gjøre forespørslene.

6. Enhetstest

La oss lage tre testsaker for å teste klienten vår. Merk, vi bruker statisk import til org.hamcrest.CoreMatchers. * og org.junit.Assert. *:

@Test offentlig ugyldig gittBookClient_shouldRunSuccessfully () kaster unntak {List books = bookClient.findAll (). Stream () .map (BookResource :: getBook) .collect (Collectors.toList ()); assertTrue (books.size ()> 2); } @Test offentlig ugyldig gittBookClient_shouldFindOneBook () kaster unntak {Book book = bookClient.findByIsbn ("0151072558"). GetBook (); assertThat (book.getAuthor (), containString ("Orwell")); } @Test offentlig ugyldig gittBookClient_shouldPostBook () kaster unntak {String isbn = UUID.randomUUID (). ToString (); Bokbok = ny bok (isbn, "Me", "It's me!", Null, null); bookClient.create (bok); book = bookClient.findByIsbn (isbn) .getBook (); assertThat (book.getAuthor (), er ("meg")); } 

7. Videre lesing

Hvis vi trenger en slags tilbakeslag i tilfelle tjenestetilgjengelighet, kan vi legge HystrixFeign til klassestien og bygge vår klient med HystrixFeign.builder ().

Ta en titt på denne dedikerte veiledningsserien for å lære mer om Hystrix.

I tillegg, hvis vi vil integrere Spring Cloud Netflix Hystrix med Feign, er det en dedikert artikkel her.

Videre er det også mulig å legge til klient-side belastningsbalansering og / eller funn av tjenester til vår klient.

Vi kunne oppnå dette ved å legge Ribbon til klassestien vår og bruke byggherren slik:

BookClient bookClient = Feign.builder () .client (RibbonClient.create ()) .target (BookClient.class, "// localhost: 8081 / api / books");

For å oppdage tjenester må vi bygge opp vår tjeneste med Spring Cloud Netflix Eureka aktivert. Integrer deretter med Spring Cloud Netflix Feign. Som et resultat får vi gratis båndbalansering. Mer om dette finner du her.

8. Konklusjon

I denne artikkelen har vi forklart hvordan du bygger en deklarativ HTTP-klient ved hjelp av Feign til å konsumere tekstbaserte API-er.

Som vanlig er alle kodeeksempler vist i denne opplæringen tilgjengelig på GitHub.