Introduktion til Spring Cloud OpenFeign

1. Oversigt

I denne vejledning beskriver vi Spring Cloud OpenFeign - en erklærende REST-klient til Spring Boot-apps.

Feign gør det lettere at skrive webserviceklienter med plugbar annoteringssupport, som inkluderer Feign-annoteringer og JAX-RS-annoteringer.

Spring Cloud tilføjer også understøttelse af Spring MVC-kommentarer og brug af det samme HttpMessageConverters som brugt i Spring Web.

En god ting ved at bruge Feign er, at vi ikke behøver at skrive nogen kode for at ringe til tjenesten, bortset fra en definition af grænsefladen.

2. Afhængigheder

Først starter vi med at oprette et Spring Boot-webprojekt og tilføje spring-cloud-starter-openfeign afhængighed af vores pom.xml fil:

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

Vi bliver også nødt til at tilføje forår-sky-afhængigheder:

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

Vi kan finde de nyeste versioner af spring-cloud-starter-openfeign og forår-sky-afhængigheder på Maven Central.

3. Feign-klient

Dernæst skal vi tilføje @EnableFeignClients til vores hovedklasse:

@SpringBootApplication @EnableFeignClients public class EksempelApplication {public static void main (String [] args) {SpringApplication.run (ExampleApplication.class, args); }}

Med denne kommentar aktiverer vi komponentscanning efter grænseflader, der erklærer, at de er Feign-klienter.

Derefter, vi erklærer en Feign-klient ved hjælp af @FeignClient kommentar:

@FeignClient (værdi = "jplaceholder", url = "//jsonplaceholder.typicode.com/") offentlig grænseflade JSONPlaceHolderClient {@RequestMapping (method = RequestMethod.GET, value = "/ posts") Liste getPosts (); @RequestMapping (metode = RequestMethod.GET, værdi = "/ indlæg / {postId}", producerer = "applikation / json") Indlæg getPostById (@PathVariable ("postId") Lang postId); }

I dette eksempel har vi konfigureret en klient til at læse fra JSONPlaceHolder API'erne.

Det værdi argument bestået i @FeignClient kommentar er et obligatorisk, vilkårligt klientnavn, mens det med url argument, vi specificerer API-base URL.

Da denne grænseflade er en Feign-klient, kan vi desuden bruge Spring Web-kommentarerne til at erklære de API'er, som vi vil nå ud til.

4. Konfiguration

Nu er det meget vigtigt at forstå det hver Feign-klient består af et sæt komponenter, der kan tilpasses.

Spring Cloud opretter et nyt standardsæt efter behov for hver navngivet klient ved hjælp af FeignClientsConfiguration klasse, som vi kan tilpasse som forklaret i det næste afsnit.

Ovenstående klasse indeholder disse bønner:

  • Dekoder - ResponseEntityDecoder, der indpakker SpringDecoder, bruges til at afkode Respons
  • Encoder - SpringEncoder, bruges til at kode RequestBody
  • Logger - Slf4jLogger er standardloggeren, der bruges af Feign
  • Kontrakt - SpringMvcContract, som giver behandling af annoteringer
  • Feign-Builder - HystrixFeign.Builder brugt til at konstruere komponenterne
  • Klient - LoadBalancerFeignClient eller standard Feign-klient

4.1. Konfiguration af brugerdefinerede bønner

Hvis vi vil tilpasse en eller flere af disse bønner, vi kan tilsidesætte dem ved hjælp af en @Konfiguration klasse, som vi derefter tilføjer til FeignClient kommentar:

@FeignClient (værdi = "jplaceholder", url = "//jsonplaceholder.typicode.com/", konfiguration = MyClientConfiguration.class)
@Configuration public class MyClientConfiguration {@Bean public OkHttpClient client () {return new OkHttpClient (); }}

I dette eksempel beder vi Feign om at bruge OkHttpClient i stedet for standard en til at understøtte HTTP / 2.

Feign understøtter flere klienter til forskellige brugssager, herunder ApacheHttpClient, der sender flere overskrifter med anmodningen - for eksempel Indholdslængde, som nogle servere forventer.

Lad os ikke glemme at tilføje de krævede afhængigheder til vores for at bruge disse klienter pom.xml fil, for eksempel:

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

Vi kan finde de nyeste versioner af feign-okhttp og feign-httpclient på Maven Central.

4.2. Konfiguration ved hjælp af egenskaber

I stedet for at bruge en @Konfiguration klasse, vi kan bruge applikationsegenskaber til at konfigurere Feign-klientersom vist i dette ansøgning.yaml eksempel:

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

Med denne konfiguration indstiller vi timeouts til 5 sekunder og loggerniveauet til grundlæggende for hver erklæret klient i applikationen.

Endelig kan vi oprette konfigurationen med Standard som klientnavn for at konfigurere alle @FeignClient objekter, eller vi kan erklære feign-klientnavnet for en konfiguration:

feign: klient: config: jplaceholder:

Hvis vi har begge dele @Konfiguration bønne- og konfigurationsegenskaber, konfigurationsegenskaber tilsidesætter @Konfiguration værdier.

5. Interceptorer

Tilføjelse af interceptors er en anden nyttig funktion leveret af Feign.

Interceptors kan udføre en række implicitte opgaver, fra godkendelse til logning, for hver HTTP-anmodning / -svar.

I dette afsnit implementerer vi vores egen interceptor samt bruger den, der leveres af Spring Cloud OpenFeign out-of-the-box. Begge vil tilføj en grundlæggende godkendelsesoverskrift til hver anmodning.

5.1. Implementerer RequestInterceptor

Så lad os implementere vores tilpassede anmodningsinterceptor i uddraget nedenfor:

@Bean public RequestInterceptor requestInterceptor () {return requestTemplate -> {requestTemplate.header ("bruger", brugernavn); requestTemplate.header ("adgangskode", adgangskode); requestTemplate.header ("Accepter", ContentType.APPLICATION_JSON.getMimeType ()); }; }

For at tilføje interceptor til anmodningskæden skal vi bare tilføje denne bønne til vores @Konfiguration klasse, eller som vi så tidligere, erklær det i egenskabsfilen:

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

5.2. Ved brug af BasicAuthRequestInterceptor

Alternativt kan vi bruge BasicAuthRequestInterceptor klasse, som Spring Cloud OpenFeign giver:

@Bean offentlig BasicAuthRequestInterceptor basicAuthRequestInterceptor () {returner ny BasicAuthRequestInterceptor ("brugernavn", "adgangskode"); }

Det er simpelt som det! Nu indeholder alle anmodningerne den grundlæggende godkendelsesoverskrift.

6. Hystrix Support

Feign understøtter Hystrix, så hvis vi har aktiveret det, vi kan implementere reservemønsteret.

Når reservemønstret mislykkes, i stedet for at generere en undtagelse, udfører serviceforbrugeren en alternativ kodesti for at forsøge at udføre handlingen på en anden måde.

For at nå målet er vi nødt til at aktivere Hystrix-tilføjelse feign.hystrix.enabled = sand i egenskabsfilen.

Dette giver os mulighed for at implementere reservemetoder, der kaldes, når tjenesten mislykkes:

@Komponent offentlig klasse JSONPlaceHolderFallback implementerer JSONPlaceHolderClient {@ Override public List getPosts () {return Collections.emptyList (); } @Override public Post getPostById (Long postId) {return null; }}

For at lade Feign vide, at der er tilvejebragt tilbagefaldsmetoder, skal vi også indstille vores tilbagefaldsklasse i @FeignClient kommentar:

@FeignClient (værdi = "jplaceholder", url = "//jsonplaceholder.typicode.com/", fallback = JSONPlaceHolderFallback.class) offentlig grænseflade JSONPlaceHolderClient {// API'er}

7. Logning

For hver Feign-klient oprettes en logger som standard.

For at aktivere logning skal vi erklære det i application.properties-fil ved hjælp af pakkenavnet på klientinterfaces:

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

Eller hvis vi kun vil aktivere logning for en bestemt klient i en pakke, kan vi bruge det fulde klassenavn:

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

Bemærk, at Feign-logning kun reagerer på FEJLFINDE niveau.

Det Logger. Niveau at vi kan konfigurere pr. klient angiver, hvor meget vi skal logge:

@Configuration offentlig klasse ClientConfiguration {@Bean Logger.Level feignLoggerLevel () {returner Logger.Level.BASIC; }}

Der er fire logningsniveauer at vælge imellem:

  • INGEN - ingen logning, hvilket er standard
  • GRUNDLÆGGENDE - log kun anmodningsmetoden, URL og svarstatus
  • HOVEDE - logge de grundlæggende oplysninger sammen med anmodnings- og svaroverskrifter
  • FULD - log kroppen, overskrifterne og metadataene for både anmodning og svar

8. Fejlhåndtering

Feign's standardfejlbehandler, ErrorDecoder.default, kaster altid en FeignException.

Nu er denne opførsel ikke altid den mest nyttige. Så, for at tilpasse undtagelsen, der kastes, kan vi bruge en CustomErrorDecoder:

offentlig klasse CustomErrorDecoder implementerer ErrorDecoder {@Override public Exception decode (String methodKey, Response response) {switch (response.status ()) {case 400: return new BadRequestException (); sag 404: returner ny NotFoundException (); standard: returner ny undtagelse ("Generisk fejl"); }}}

Derefter, som vi har gjort tidligere, er vi nødt til at erstatte standard ErrorDecoder ved at tilføje en bønne til @Konfiguration klasse:

@Configuration offentlig klasse ClientConfiguration {@Bean public ErrorDecoder errorDecoder () {returner ny CustomErrorDecoder (); }}

9. Konklusion

I denne artikel diskuterede vi Spring Cloud OpenFeign og dens implementering i en simpel prøveapplikation.

Desuden har vi set, hvordan man konfigurerer en klient, hvordan man tilføjer interceptors til vores anmodninger, og hvordan man håndterer fejl ved hjælp af Hystrix og ErrorDecoder.

Som normalt er alle kodeeksempler vist i denne vejledning tilgængelige på GitHub.