Pengenalan kepada Spring Cloud OpenFeign

1. Gambaran keseluruhan

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

Feign menjadikan penulisan pelanggan perkhidmatan web lebih mudah dengan sokongan anotasi yang dapat dipasang, yang merangkumi anotasi Feign dan anotasi JAX-RS.

Juga, Spring Cloud menambah sokongan untuk anotasi Spring MVC dan untuk menggunakan HttpMessageConverters yang sama seperti yang digunakan di Spring Web.

Perkara yang hebat mengenai penggunaan Feign ialah kita tidak perlu menulis kod untuk memanggil perkhidmatan, selain daripada definisi antara muka.

2. Kebergantungan

Pertama, kita akan mulakan dengan membuat projek web Spring Boot dan menambahkan pergantungan spring-cloud-starter-openfeign ke fail pom.xml kami :

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

Kita juga perlu menambahkan pergantungan awan-musim bunga :

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

Kami dapat mencari versi terkini pergantungan spring-cloud-starter-openfeign dan spring-cloud di Maven Central.

3. Pelanggan Feign

Seterusnya, kita perlu menambahkan @EnableFeignClients ke kelas utama kami:

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

Dengan penjelasan ini, kami membolehkan pengimbasan komponen untuk antara muka yang menyatakan bahawa mereka adalah pelanggan 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 mengkonfigurasi klien untuk membaca dari API JSONPlaceHolder.

Yang nilai hujah diluluskan di @FeignClient anotasi ialah, nama pelanggan sewenang-wenangnya wajib, manakala dengan url hujah, kita menentukan URL asas API.

Tambahan pula, kerana antara muka ini adalah klien Feign, kami dapat menggunakan anotasi Spring Web untuk menyatakan API yang ingin kami jangkau.

4. Konfigurasi

Sekarang, sangat penting untuk memahami bahawa setiap pelanggan Feign terdiri daripada satu set komponen yang dapat disesuaikan.

Spring Cloud membuat set permintaan lalai baru untuk setiap klien bernama menggunakan kelas FeignClientsConfiguration yang dapat kami sesuaikan seperti yang dijelaskan di bahagian berikutnya.

Kelas di atas mengandungi kacang ini:

  • Decoder - ResponseEntityDecoder , yang membungkus SpringDecoder, digunakan untuk menyahkod Respons
  • Encoder - SpringEncoder , digunakan untuk mengekod RequestBody
  • Logger - Slf4jLogger adalah logger lalai yang digunakan oleh Feign
  • Kontrak - SpringMvcContract , yang menyediakan pemprosesan anotasi
  • Feign-Builder - HystrixFeign.Builder digunakan untuk membina komponen
  • Pelanggan - LoadBalancerFeignClient atau klien Feign lalai

4.1. Konfigurasi Kacang Adat

Sekiranya kita ingin menyesuaikan satu atau lebih biji ini, kita boleh 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 menyuruh Feign menggunakan OkHttpClient dan bukan yang lalai untuk menyokong HTTP / 2.

Feign menyokong beberapa klien untuk kes penggunaan yang berbeza, termasuk ApacheHttpClient , yang mengirimkan lebih banyak tajuk dengan permintaan - misalnya, Panjang Kandungan, yang diharapkan oleh beberapa pelayan.

Untuk menggunakan klien ini, jangan lupa untuk menambahkan kebergantungan yang diperlukan ke fail pom.xml kami , misalnya:

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

Kita boleh mendapatkan versi terbaru feign-okhttp dan feign-httpclient di Maven Central.

4.2. Konfigurasi Menggunakan Properties

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

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

Dengan konfigurasi ini, kami menetapkan batas waktu hingga 5 saat dan tahap logger menjadi asas bagi setiap klien yang dinyatakan dalam aplikasi.

Akhirnya, kita dapat membuat konfigurasi dengan lalai sebagai nama klien untuk mengkonfigurasi semua objek @FeignClient , atau kita dapat menyatakan nama klien pura-pura untuk konfigurasi:

feign: client: config: jplaceholder:

Sekiranya kita mempunyai sifat @Configuration bean dan konfigurasi, sifat konfigurasi akan mengatasi nilai @Configuration .

5. Pemintas

Menambah pemintas adalah satu lagi ciri berguna yang disediakan oleh Feign.

Pemintas boleh melakukan pelbagai tugas tersirat, dari pengesahan hingga pembalakan, untuk setiap permintaan / respons HTTP.

Di bahagian ini, kami akan melaksanakan pemintas kami sendiri, dan juga menggunakan yang disediakan oleh Spring Cloud OpenFeign out-of-the-box. Kedua-duanya akan menambahkan tajuk pengesahan asas untuk setiap permintaan .

5.1. Melaksanakan RequestInterceptor

Jadi, dalam coretan di bawah, mari kita laksanakan pemintas permintaan khusus kami:

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

Juga, untuk menambahkan pemintas ke rantai permintaan, kita hanya perlu menambahkan kacang ini ke kelas @Konfigurasi , atau seperti yang kita lihat sebelumnya, menyatakannya dalam fail sifat:

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

5.2. Menggunakan BasicAuthRequestInterceptor

Sebagai alternatif, kita boleh menggunakan kelas BasicAuthRequestInterceptor yang disediakan oleh Spring Cloud OpenFeign:

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

Ia semudah itu! Sekarang semua permintaan akan mengandungi tajuk pengesahan asas.

6. Sokongan Hystrix

Feign menyokong Hystrix, jadi jika kita mengaktifkannya, kita dapat menerapkan pola fallback.

Dengan corak penggantian, apabila panggilan perkhidmatan jarak jauh gagal, dan bukannya menghasilkan pengecualian, pengguna perkhidmatan akan melaksanakan jalan kod alternatif untuk berusaha melakukan tindakan tersebut dengan 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 lalai dengan menambahkan kacang ke kelas @Configuration :

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

9. Kesimpulannya

Dalam artikel ini, kami membincangkan Spring Cloud OpenFeign dan pelaksanaannya dalam contoh aplikasi sederhana.

Lebih-lebih lagi, kami telah melihat bagaimana mengkonfigurasi klien, cara menambahkan pemintas pada permintaan kami, dan bagaimana menangani ralat menggunakan Hystrix dan ErrorDecoder.

Seperti biasa, semua sampel kod yang ditunjukkan dalam tutorial ini terdapat di GitHub.