Inleiding tot Spring Cloud OpenFeign

1. Overzicht

In deze tutorial gaan we Spring Cloud OpenFeign beschrijven - een declaratieve REST-client voor Spring Boot-apps.

Feign maakt het schrijven van webserviceclients eenvoudiger met ondersteuning voor pluggable annotaties, waaronder Feign-annotaties en JAX-RS-annotaties.

Spring Cloud voegt ook ondersteuning toe voor Spring MVC-annotaties en voor het gebruik ervan HttpMessageConverters zoals gebruikt in Spring Web.

Een groot voordeel van het gebruik van Feign is dat we geen code hoeven te schrijven om de service aan te roepen, behalve een interfacedefinitie.

2. Afhankelijkheden

Eerst beginnen we met het maken van een Spring Boot-webproject en het toevoegen van het spring-cloud-starter-openfeign afhankelijkheid van onze pom.xml het dossier:

 org.springframework.cloud spring-cloud-starter-openfeign 

We moeten ook het spring-cloud-afhankelijkheden:

    org.springframework.cloud spring-cloud-dependencies $ {spring-cloud.version} pom import 

We kunnen de nieuwste versies van spring-cloud-starter-openfeign en spring-cloud-afhankelijkheden op Maven Central.

3. Doe alsof je klant bent

Vervolgens moeten we toevoegen @EnableFeignClients naar onze hoofdklasse:

@SpringBootApplication @EnableFeignClients openbare klasse ExampleApplication {openbare statische leegte hoofd (String [] args) {SpringApplication.run (ExampleApplication.class, args); }}

Met deze annotatie maken we het scannen van componenten mogelijk voor interfaces die aangeven dat ze Feign-clients zijn.

Dan, we verklaren een Feign-client met behulp van de @Feyenoord annotatie:

@FeignClient (value = "jplaceholder", url = "//jsonplaceholder.typicode.com/") openbare interface JSONPlaceHolderClient {@RequestMapping (method = RequestMethod.GET, value = "/ posts") Lijst getPosts (); @RequestMapping (methode = RequestMethod.GET, value = "/ posts / {postId}", produceert = "application / json") Post getPostById (@PathVariable ("postId") Lange postId); }

In dit voorbeeld hebben we een client geconfigureerd om te lezen uit de JSONPlaceHolder API's.

De waarde argument doorgegeven in de @Feyenoord annotatie is een verplichte, willekeurige clientnaam, terwijl de url argument specificeren we de API-basis-URL.

Bovendien, aangezien deze interface een Feign-client is, kunnen we de Spring Web-annotaties gebruiken om de API's aan te geven die we willen bereiken.

4. Configuratie

Nu is het erg belangrijk om dat te begrijpen elke Feign-client is samengesteld uit een set aanpasbare componenten.

Spring Cloud maakt op aanvraag een nieuwe standaardset voor elke genoemde klant met behulp van de FeignClientsConfiguration klasse die we kunnen aanpassen zoals uitgelegd in de volgende sectie.

De bovenstaande klasse bevat deze bonen:

  • Decoder - ResponseEntityDecoder, die wraps SpringDecoder, gebruikt om de Reactie
  • Encoder - SpringEncoder, gebruikt om de RequestBody
  • Logger - Slf4jLogger is de standaard logger die door Feign wordt gebruikt
  • Contract - SpringMvcContract, die annotatieverwerking biedt
  • Feign-Builder - HystrixFeign.Builder gebruikt om de componenten te construeren
  • Klant - LoadBalancerFeignClient of standaard Feign-client

4.1. Aangepaste bonenconfiguratie

Als we een of meer van deze bonen willen aanpassen, we kunnen ze negeren met een @Configuratie class, die we vervolgens toevoegen aan de FeignClient annotatie:

@FeignClient (value = "jplaceholder", url = "//jsonplaceholder.typicode.com/", configuration = MyClientConfiguration.class)
@Configuration openbare klasse MyClientConfiguration {@Bean openbare OkHttpClient-client () {retourneer nieuwe OkHttpClient (); }}

In dit voorbeeld vertellen we Feign om te gebruiken OkHttpClient in plaats van de standaard die HTTP / 2 ondersteunt.

Feign ondersteunt meerdere clients voor verschillende gebruiksscenario's, waaronder de ApacheHttpClient, die meer headers met het verzoek verzendt, bijvoorbeeld Inhoud lengte, wat sommige servers verwachten.

Laten we, om deze clients te gebruiken, niet vergeten de vereiste afhankelijkheden toe te voegen aan onze pom.xml bestand, bijvoorbeeld:

 io.github.openfeign feign-okhttp io.github.openfeign feign-httpclient 

We kunnen de nieuwste versies van veinzen-okhttp en veinzen-httpclient op Maven Central.

4.2. Configuratie met behulp van eigenschappen

In plaats van een @Configuratie klasse, we kunnen applicatie-eigenschappen gebruiken om Feign-clients te configureren, zoals weergegeven in dit application.yaml voorbeeld:

feign: client: config: default: connectTimeout: 5000 readTimeout: 5000 loggerLevel: basic

Met deze configuratie stellen we de time-outs in op 5 seconden en het logger-niveau op basis voor elke aangegeven klant in de applicatie.

Ten slotte kunnen we de configuratie maken met standaard als de clientnaam om alles te configureren @Feyenoord objecten, of we kunnen de schijnbare klantnaam declareren voor een configuratie:

feign: client: config: jplaceholder:

Als we beide hebben @Configuratie bean en configuratie-eigenschappen, zullen de configuratie-eigenschappen voorrang krijgen @Configuratie waarden.

5. Onderscheppers

Het toevoegen van interceptors is een andere handige functie van Feign.

De interceptors kunnen een verscheidenheid aan impliciete taken uitvoeren, van authenticatie tot logboekregistratie, voor elk HTTP-verzoek / antwoord.

In deze sectie zullen we onze eigen interceptor implementeren, evenals degene die wordt geleverd door de Spring Cloud OpenFeign out-of-the-box. Beiden zullen voeg een basisverificatieheader toe aan elk verzoek.

5.1. Implementeren RequestInterceptor

Laten we dus in het onderstaande fragment onze aangepaste verzoek-interceptor implementeren:

@Bean openbaar RequestInterceptor requestInterceptor () {return requestTemplate -> {requestTemplate.header ("gebruiker", gebruikersnaam); requestTemplate.header ("wachtwoord", wachtwoord); requestTemplate.header ("Accepteren", ContentType.APPLICATION_JSON.getMimeType ()); }; }

Om de interceptor aan de verzoekketen toe te voegen, hoeven we alleen deze bean toe te voegen aan onze @Configuratie class, of zoals we eerder zagen, declareer het in het eigenschappenbestand:

feign: client: config: standaard: requestInterceptors: com.baeldung.cloud.openfeign.JSONPlaceHolderInterceptor

5.2. Gebruik makend van BasicAuthRequestInterceptor

Als alternatief kunnen we de BasicAuthRequestInterceptor klasse die de Spring Cloud OpenFeign biedt:

@Bean openbare BasicAuthRequestInterceptor basicAuthRequestInterceptor () {retourneer nieuwe BasicAuthRequestInterceptor ("gebruikersnaam", "wachtwoord"); }

Zo simpel is het! Nu zullen alle verzoeken de basisverificatieheader bevatten.

6. Hystrix-ondersteuning

Feign ondersteunt Hystrix, dus als we het hebben ingeschakeld, we kunnen het fallback-patroon implementeren.

Met het fallback-patroon zal de servicegebruiker een alternatief codepad uitvoeren om te proberen de actie op een andere manier uit te voeren, wanneer een serviceaanroep op afstand mislukt, in plaats van een uitzondering te genereren.

Om het doel te bereiken, moeten we Hystrix-toevoeging inschakelen feign.hystrix.enabled = waar in het eigenschappenbestand.

Dit stelt ons in staat om fallback-methoden te implementeren die worden aangeroepen wanneer de service mislukt:

@Component openbare klasse JSONPlaceHolderFallback implementeert JSONPlaceHolderClient {@Override openbare lijst getPosts () {return Collections.emptyList (); } @Override public Post getPostById (Long postId) {return null; }}

Om Feign te laten weten dat er fallback-methoden beschikbaar zijn, moeten we ook onze fallback-klasse instellen in de @Feyenoord annotatie:

@FeignClient (value = "jplaceholder", url = "//jsonplaceholder.typicode.com/", fallback = JSONPlaceHolderFallback.class) openbare interface JSONPlaceHolderClient {// API's}

7. Logboekregistratie

Voor elke Feign-klant wordt standaard een logger aangemaakt.

Om logboekregistratie mogelijk te maken, moeten we dit aangeven in het application.properties-bestand met behulp van de pakketnaam van de clientinterfaces:

logging.level.com.baeldung.cloud.openfeign.client: DEBUG

Of, als we logboekregistratie alleen voor één bepaalde client in een pakket willen inschakelen, kunnen we de volledige klassenaam gebruiken:

logging.level.com.baeldung.cloud.openfeign.client.JSONPlaceHolderClient: DEBUG

Merk op dat Feign-logboekregistratie alleen reageert op de DEBUG niveau.

De Logger.Level die we per klant kunnen configureren, geeft aan hoeveel er moet worden geregistreerd:

@Configuration openbare klasse ClientConfiguration {@Bean Logger.Level feignLoggerLevel () {terug Logger.Level.BASIC; }}

Er zijn vier logboekregistratieniveaus om uit te kiezen:

  • GEEN - geen logboekregistratie, wat de standaard is
  • BASIS - log alleen de verzoekmethode, URL en antwoordstatus in
  • HEADERS - log de basisinformatie samen met verzoek- en antwoordheaders
  • VOLLEDIG - log de body, headers en metadata voor zowel verzoek als antwoord

8. Foutafhandeling

Feign's standaard foutafhandelaar, ErrorDecoder.default, gooit altijd een FeignException.

Dit gedrag is niet altijd het meest bruikbare. Zo, om de gegenereerde uitzondering aan te passen, kunnen we een CustomErrorDecoder:

public class CustomErrorDecoder implementeert ErrorDecoder {@Override public Exception decode (String methodKey, Response response) {switch (response.status ()) {case 400: return new BadRequestException (); case 404: retourneer nieuwe NotFoundException (); default: return new Exception ("Algemene fout"); }}}

Vervolgens, zoals we eerder hebben gedaan, moeten we de standaard vervangen ErrorDecoder door een boon aan de @Configuratie klasse:

@Configuration openbare klasse ClientConfiguration {@Bean openbare ErrorDecoder errorDecoder () {retourneer nieuwe CustomErrorDecoder (); }}

9. Conclusie

In dit artikel hebben we Spring Cloud OpenFeign en de implementatie ervan in een eenvoudige voorbeeldtoepassing besproken.

Bovendien hebben we gezien hoe u een client configureert, hoe u interceptors aan onze verzoeken toevoegt en hoe u fouten afhandelt met Hystrix en ErrorDecoder.

Zoals gewoonlijk zijn alle codevoorbeelden die in deze tutorial worden getoond, beschikbaar op GitHub.