Pengantar Spring Cloud OpenFeign

1. Ikhtisar

Dalam tutorial ini, kami akan menjelaskan Spring Cloud OpenFeign - klien REST deklaratif untuk aplikasi Spring Boot.

Feign membuat penulisan klien layanan web lebih mudah dengan dukungan anotasi yang dapat dicolokkan, yang mencakup anotasi Feign dan anotasi JAX-RS.

Selain itu, Spring Cloud menambahkan dukungan untuk anotasi MVC Spring dan untuk menggunakan HttpMessageConverters yang sama seperti yang digunakan di Spring Web.

Hal yang hebat tentang menggunakan Feign adalah kita tidak perlu menulis kode apa pun untuk memanggil layanan, selain definisi antarmuka.

2. Dependensi

Pertama, kita akan mulai dengan membuat proyek web Spring Boot dan menambahkan ketergantungan spring-cloud-starter-openfeign ke file pom.xml kita :

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

Juga, kita perlu menambahkan dependensi spring-cloud :

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

Kami dapat menemukan versi terbaru dependensi spring-cloud-starter-openfeign dan spring-cloud di Maven Central.

3. Berpura-pura Klien

Selanjutnya, kita perlu menambahkan @EnableFeignClients ke kelas utama kita:

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

Dengan anotasi ini, kami mengaktifkan pemindaian komponen untuk antarmuka yang menyatakan bahwa mereka adalah klien Feign.

Kemudian, kami menyatakan klien Feign menggunakan anotasi @FeignClient :

@FeignClient(value = "jplaceholder", url = "//jsonplaceholder.typicode.com/") public interface JSONPlaceHolderClient { @RequestMapping(method = RequestMethod.GET, value = "/posts") List getPosts(); @RequestMapping(method = RequestMethod.GET, value = "/posts/{postId}", produces = "application/json") Post getPostById(@PathVariable("postId") Long postId); }

Dalam contoh ini, kami telah mengonfigurasi klien untuk membaca dari API JSONPlaceHolder.

The nilai argumen berlalu dalam @FeignClient penjelasan adalah wajib, sewenang-wenang nama klien, sedangkan dengan url argumen, kita tentukan URL dasar API.

Lebih lanjut, karena antarmuka ini adalah klien Feign, kita dapat menggunakan penjelasan Spring Web untuk menyatakan API yang ingin kita jangkau.

4. Konfigurasi

Sekarang, sangat penting untuk memahami bahwa setiap klien Feign terdiri dari sekumpulan komponen yang dapat disesuaikan.

Spring Cloud membuat set default baru sesuai permintaan untuk setiap klien bernama menggunakan kelas FeignClientsConfiguration yang dapat kita sesuaikan seperti yang dijelaskan di bagian selanjutnya.

Kelas di atas berisi kacang-kacangan ini:

  • Decoder - ResponseEntityDecoder , yang membungkus SpringDecoder, digunakan untuk memecahkan kode Respon
  • Encoder - SpringEncoder , digunakan untuk menyandikan RequestBody
  • Logger - Slf4jLogger adalah logger default yang digunakan oleh Feign
  • Kontrak - SpringMvcContract , yang menyediakan pemrosesan anotasi
  • Feign-Builder - HystrixFeign.Builder digunakan untuk membuat komponen
  • Klien - LoadBalancerFeignClient atau klien pura-pura default

4.1. Konfigurasi Kacang Kustom

Jika kita ingin menyesuaikan satu atau lebih dari kacang ini, kita bisa menimpanya menggunakan kelas @Configuration , yang kemudian kita tambahkan ke anotasi FeignClient :

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

Dalam contoh ini, kami memberi tahu Feign untuk menggunakan OkHttpClient alih-alih yang default untuk mendukung HTTP / 2.

Feign mendukung banyak klien untuk kasus penggunaan yang berbeda, termasuk ApacheHttpClient , yang mengirimkan lebih banyak header dengan permintaan - misalnya, Panjang Konten, yang diharapkan beberapa server.

Untuk menggunakan klien ini, jangan lupa untuk menambahkan dependensi yang diperlukan ke file pom.xml kita , misalnya:

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

Kami dapat menemukan versi terbaru dari feign-okhttp dan feign-httpclient di Maven Central.

4.2. Konfigurasi Menggunakan Properti

Daripada menggunakan kelas @Configuration , kita dapat menggunakan properti aplikasi untuk mengkonfigurasi klien Feign , seperti yang ditunjukkan dalam contoh application.yaml ini :

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

Dengan konfigurasi ini, kami menyetel waktu tunggu menjadi 5 detik dan tingkat pencatat ke dasar untuk setiap klien yang dideklarasikan dalam aplikasi.

Terakhir, kita dapat membuat konfigurasi dengan default sebagai nama klien untuk mengkonfigurasi semua objek @FeignClient , atau kita dapat mendeklarasikan nama klien pura-pura untuk konfigurasi:

feign: client: config: jplaceholder:

Jika kita memiliki @Configuration bean dan properti konfigurasi, properti konfigurasi akan mengganti nilai @Configuration .

5. Pencegat

Menambahkan interseptor adalah fitur berguna lainnya yang disediakan oleh Feign.

Interceptor dapat melakukan berbagai tugas implisit, mulai dari otentikasi hingga logging, untuk setiap permintaan / respons HTTP.

Di bagian ini, kami akan menerapkan pencegat kami sendiri, serta menggunakan yang disediakan oleh Spring Cloud OpenFeign out-of-the-box. Keduanya akan menambahkan header otentikasi dasar untuk setiap permintaan .

5.1. Menerapkan RequestInterceptor

Jadi, dalam cuplikan di bawah, mari terapkan pencegat permintaan khusus kita:

@Bean public RequestInterceptor requestInterceptor() { return requestTemplate -> { requestTemplate.header("user", username); requestTemplate.header("password", password); requestTemplate.header("Accept", ContentType.APPLICATION_JSON.getMimeType()); }; }

Juga, untuk menambahkan interseptor ke rantai permintaan, kita hanya perlu menambahkan kacang ini ke kelas @Configuration kita , atau seperti yang kita lihat sebelumnya, mendeklarasikannya di file properti:

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

5.2. Menggunakan BasicAuthRequestInterceptor

Atau, kita dapat menggunakan kelas BasicAuthRequestInterceptor yang disediakan oleh Spring Cloud OpenFeign:

@Bean public BasicAuthRequestInterceptor basicAuthRequestInterceptor() { return new BasicAuthRequestInterceptor("username", "password"); }

Sesederhana itu! Sekarang semua permintaan akan berisi header otentikasi dasar.

6. Dukungan Hystrix

Feign mendukung Hystrix, jadi jika kita telah mengaktifkannya, kita dapat mengimplementasikan pola fallback.

Dengan pola fallback, ketika panggilan layanan jarak jauh gagal, daripada menghasilkan pengecualian, konsumen layanan akan menjalankan jalur kode alternatif untuk mencoba melakukan tindakan melalui cara lain.

To achieve the goal, we need to enable Hystrix adding feign.hystrix.enabled=true in the properties file.

This allows us to implement fallback methods that are called when the service fails:

@Component public class JSONPlaceHolderFallback implements JSONPlaceHolderClient { @Override public List getPosts() { return Collections.emptyList(); } @Override public Post getPostById(Long postId) { return null; } }

To let Feign know that fallback methods have been provided, we also need to set our fallback class in the @FeignClient annotation:

@FeignClient(value = "jplaceholder", url = "//jsonplaceholder.typicode.com/", fallback = JSONPlaceHolderFallback.class) public interface JSONPlaceHolderClient { // APIs }

7. Logging

For each Feign client, a logger is created by default.

To enable logging, we should declare it in the application.properties file using the package name of the client interfaces:

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

Or, if we want to enable logging only for one particular client in a package, we can use the full class name:

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

Note that Feign logging responds only to the DEBUG level.

The Logger.Level that we may configure per client indicates how much to log:

@Configuration public class ClientConfiguration { @Bean Logger.Level feignLoggerLevel() { return Logger.Level.BASIC; } }

There are four logging levels to choose from:

  • NONE – no logging, which is the default
  • BASIC – log only the request method, URL, and response status
  • HEADERS – log the basic information together with request and response headers
  • FULL – log the body, headers, and metadata for both request and response

8. Error Handling

Feign's default error handler, ErrorDecoder.default, always throws a FeignException.

Now, this behavior isn't always the most useful. So, to customize the Exception thrown, we can use a CustomErrorDecoder:

public class CustomErrorDecoder implements ErrorDecoder { @Override public Exception decode(String methodKey, Response response) { switch (response.status()){ case 400: return new BadRequestException(); case 404: return new NotFoundException(); default: return new Exception("Generic error"); } } }

Kemudian, seperti yang telah kita lakukan sebelumnya, kita harus mengganti ErrorDecoder default dengan menambahkan kacang ke kelas @Configuration :

@Configuration public class ClientConfiguration { @Bean public ErrorDecoder errorDecoder() { return new CustomErrorDecoder(); } }

9. Kesimpulan

Pada artikel ini, kita membahas Spring Cloud OpenFeign dan implementasinya dalam aplikasi sampel sederhana.

Selain itu, kami telah melihat cara mengonfigurasi klien, cara menambahkan interseptor ke permintaan kami, dan cara menangani kesalahan menggunakan Hystrix dan ErrorDecoder.

Seperti biasa, semua contoh kode yang ditampilkan dalam tutorial ini tersedia di GitHub.