Resumen de los puntos de conocimiento de Spring Cloud OpenFeign

1. Cliente REST declarativo: Fingir

Fingir es un cliente de servicio web declarativo. Facilita la escritura de clientes de servicios web. Para usar Fingir, debe crear una interfaz y anotarla. Tiene soporte de anotación conectable, incluidas anotaciones de simulación y anotaciones JAX-RS. Fingir también es compatible con codificadores y decodificadores enchufables. Spring Cloud agrega compatibilidad con las anotaciones de Spring MVC y admite el uso de HttpMessageConverters que se usan de forma predeterminada en Spring Web. Spring Cloud integra Eureka, Spring Cloud CircuitBreaker y Spring Cloud LoadBalancer para proporcionar un cliente http con equilibrio de carga cuando se usa Feign.

1.1 Cómo "incluir" Fingir

Para incluir Fingir en su proyecto, use el iniciador con el grupo org.springframework.cloud y el id. de artefacto spring-cloud-starter-openfeign. Consulte la página del proyecto Spring Cloud para obtener detalles sobre cómo construir el sistema con la configuración actual de Spring Cloud Release Train.

Ejemplo: aplicación Spring Boot

@SpringBootApplication
@EnableFeignClients
public class Application {

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }

}

StoreClient.java

@FeignClient("stores")
public interface StoreClient {
    @RequestMapping(method = RequestMethod.GET, value = "/stores")
    List<Store> getStores();

    @RequestMapping(method = RequestMethod.GET, value = "/stores")
    Page<Store> getStores(Pageable pageable);

    @RequestMapping(method = RequestMethod.POST, value = "/stores/{storeId}", consumes = "application/json")
    Store update(@PathVariable("storeId") Long storeId, Store store);

    @RequestMapping(method = RequestMethod.DELETE, value = "/stores/{storeId:\\d+}")
    void delete(@PathVariable Long storeId);
}

En la anotación @FeignClient, el valor de la cadena ("tiendas" arriba) es un nombre de cliente arbitrario que se usa para crear un cliente Spring Cloud LoadBalancer. También puede especificar una URL (absoluta o simplemente un nombre de host) usando el atributo url. El nombre del bean en el contexto de la aplicación es el nombre completo de la interfaz. Para especificar sus propios valores de alias, puede usar el valor de los calificadores de la anotación @FeignClient.

El cliente del equilibrador de carga anterior querrá descubrir la dirección física del servicio de "tiendas". Si su aplicación es un cliente de Eureka, entonces resolverá el servicio en el registro de servicios de Eureka. Si no quiere usar Eureka, puede usar SimpleDiscoveryClient para configurar una lista de servicios en su configuración externa.

Spring Cloud OpenFeign admite todas las funciones del modo de bloqueo Spring Cloud LoadBalancer. Puede leer más sobre ellos en la documentación del proyecto.

Para usar la anotación @EnableFeignClients en una clase anotada @Configuration, asegúrese de especificar la ubicación de los clientes, por ejemplo: @EnableFeignClients(basePackages = "com.example.clients") o enumérelos explícitamente: @EnableFeignClients(clients = InventoryServiceFeignClient. clase)

1.1.1 Modo de resolución de atributos

Al crear un bean de cliente Feign, resolvemos el valor pasado a través de la anotación @FeignClient. A partir de 4.x, estos valores se analizan con entusiasmo. Esta es una buena solución para la mayoría de los casos de uso y también permite la compatibilidad con AOT.

Si necesita resolver los atributos de forma diferida, establezca el valor de la propiedad spring.cloud.openfeign.lazy-attributes-solution en verdadero.

Para las integraciones de prueba de Spring Cloud Contract, se debe usar la resolución de propiedad diferida.

1.2 Anulación de los valores predeterminados de Fingir

Un concepto central en el soporte de Fingir de Spring Cloud son los clientes con nombre. Cada cliente fingido es parte de una colección de componentes que funcionan juntos para comunicarse con servidores remotos bajo demanda, y esa colección tiene un nombre que usted, el desarrollador de la aplicación, le asigna con la anotación @FeignClient. Spring Cloud usa FeignClientsConfiguration para crear una nueva composición como ApplicationContext a pedido para cada cliente nombrado. Esto incluye (entre otras cosas) un fingido.Decodificador, un fingido.Codificador y un fingido.Contrato. El nombre de la colección se puede anular mediante el atributo contextId de la anotación @FeignClient.

Spring Cloud le brinda control total sobre el cliente fingido mediante el uso de @FeignClient para declarar una configuración adicional (además de FeignClientsConfiguration). ejemplo:

@FeignClient(name = "stores", configuration = FooConfiguration.class)
public interface StoreClient {
    //..
}

En este caso, el cliente consta de componentes que ya están en FeignClientsConfiguration y cualquier componente en FooConfiguration (este último anulará al primero).

FooConfiguration no necesita anotarse con @Configuration. Sin embargo, si es así, tenga cuidado de excluirlo de cualquier @ComponentScan que de lo contrario incluiría esta configuración, ya que será la fuente predeterminada para fingir.Decodificador, fingir.Encodificador, fingir.Contrato, etc. Esto se puede evitar colocándolo en un paquete separado que no se superponga de cualquier @ComponentScan o @SpringBootApplication, o excluyéndolo explícitamente en @ComponentScan.

Usando el atributo contextId de la anotación @FeignClient, además de cambiar el nombre de la colección ApplicationContext, también anulará el alias del nombre del cliente, que se usará como parte del nombre del bean de configuración creado por el cliente.

Anteriormente, al utilizar el atributo url, no era necesario utilizar el atributo de nombre. Ahora, usar el nombre es obligatorio.

Se admiten marcadores de posición en los atributos de nombre y URL.

@FeignClient(name = "${feign.name}", url = "${feign.url}")
public interface StoreClient {
    //..
}

Spring Cloud OpenFeign proporciona las siguientes clases de beans para fingir de forma predeterminada (BeanType beanName: ClassName):

• Decodificador feignDecoder: ResponseEntityDecoder (encapsula un SpringDecoder)
• Codificador fingirEncoder: SpringEncoder
• Registrador feignLogger: Slf4jLogger
• MicrometerObservationCapability micrometerObservationCapability: si fingir-micrómetro está en el classpath y ObservationRegistry está disponible
• MicrometerCapability micrometerCapability: si fingir-micrómetro está en el classpath, MeterRegistry está disponible y ObservationRegistry no está disponible
• CachingCapability cachingCapability: si se usa la anotación @EnableCaching, spring.cloud.openfeign.cache.enabled puede desactivarla.
• Contrato fingirContrato: SpringMvcContract
• Fingir.Constructor fingirConstructor: FingirCircuitBreaker.Constructor
• Cliente feignClient: se usará FeignBlockingLoadBalancerClient si Spring Cloud LoadBalancer está en el classpath. Si ninguno está en el classpath, se usa el cliente fingido predeterminado.

spring-cloud-starter-openfeign es compatible con spring-cloud-starter-loadbalancer. Sin embargo, dado que es una dependencia opcional, deberá asegurarse de que se agregue a su proyecto si desea usarla.

Los clientes OkHttpClient y Apache HttpClient 5 Feign se pueden usar configurando spring.cloud.openfeign.okhttp.enabled o spring.cloud.openfeign.httpclient.hc5.enabled respectivamente en verdadero y colocándolos en el classpath. Al utilizar Apache HC5, puede personalizar el cliente HTTP utilizado proporcionando un bean de org.apache.hc.client5.http.impl.classic.CloseableHttpClient.

Puede personalizar aún más el cliente http configurando valores en las propiedades spring.cloud.openfeign.httpclient.xxx. Solo las propiedades con el prefijo httpclient se aplicarán a todos los clientes, las propiedades con el prefijo httpclient.hc5 se aplicarán a Apache HttpClient 5 y las propiedades con el prefijo httpclient.okhttp se aplicarán a OkHttpClient. Puede encontrar una lista completa de propiedades que puede personalizar en el apéndice.

A partir de Spring Cloud OpenFeign 4, Feign Apache HttpClient 4 ya no es compatible. Recomendamos usar Apache HttpClient 5 en su lugar.

Spring Cloud OpenFeign no proporciona simulación con los siguientes beans de forma predeterminada, pero aún encuentra estos tipos de beans en el contexto de la aplicación para crear clientes de simulación:

• Registrador.Nivel
• reintentador
• ErrorDecodificador
• Solicitud.Opciones
• Colección<RequestInterceptor>
• SetterFábrica
• QueryMapEncoder
• Capacidad (MicrometerObservationCapability y CachingCapability proporcionadas de forma predeterminada) De forma predeterminada, se crea un bean Retryer de tipo Retryer.NEVER_RETRY, que desactiva los reintentos. Tenga en cuenta que este comportamiento de reintento difiere del comportamiento predeterminado de Feign, que volverá a intentar automáticamente las IOExceptions, tratándolas como excepciones transitorias relacionadas con la red, así como cualquier RetryableException lanzada desde ErrorDecoder.

Crear un bean de estos tipos y colocarlo en una configuración de @FeignClient (como FooConfiguration arriba) le permite anular cada bean como se describe. ejemplo:

@Configuration
public class FooConfiguration {
    @Bean
    public Contract feignContract() {
        return new feign.Contract.Default();
    }

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

Esto reemplaza SpringMvcContract con fingir.Contract.Default y agrega un RequestInterceptor a la colección de RequestInterceptors.

@FeignClient también se puede configurar mediante las propiedades de configuración.

aplicación.yml

spring:
    cloud:
        openfeign:
            client:
                config:
                    feignName:
                        url: http://remote-service.com
                        connectTimeout: 5000
                        readTimeout: 5000
                        loggerLevel: full
                        errorDecoder: com.example.SimpleErrorDecoder
                        retryer: com.example.SimpleRetryer
                        defaultQueryParameters:
                            query: queryValue
                        defaultRequestHeaders:
                            header: headerValue
                        requestInterceptors:
                            - com.example.FooRequestInterceptor
                            - com.example.BarRequestInterceptor
                        responseInterceptor: com.example.BazResponseInterceptor
                        dismiss404: false
                        encoder: com.example.SimpleEncoder
                        decoder: com.example.SimpleDecoder
                        contract: com.example.SimpleContract
                        capabilities:
                            - com.example.FooCapability
                            - com.example.BarCapability
                        queryMapEncoder: com.example.SimpleQueryMapEncoder
                        micrometer.enabled: false

El feignName en este ejemplo se refiere al valor @FeignClient, que también tiene un alias para el nombre @FeignClient y @FeignClient contextId. En el caso del equilibrio de carga, también corresponde al serviceId de la aplicación del servidor que se usará para recuperar la instancia.

Se puede especificar una configuración predeterminada en el atributo @EnableFeignClients defaultConfiguration de manera similar a la descrita anteriormente. La diferencia es que esta configuración se aplicará a todos los clientes falsos.

Si prefiere configurar todo @FeignClient con propiedades de configuración, puede crear propiedades de configuración con el nombre falso predeterminado.

Puede usar spring.cloud.openfeign.client.config.feignName.defaultQueryParameters y spring.cloud.openfeign.client.config.feignName.defaultRequestHeaders para especificar los parámetros de consulta y la información del encabezado, que se asociará con cada solicitud del cliente denominado feignName. enviar juntos.

aplicación.yml

spring:
    cloud:
        openfeign:
            client:
                config:
                    default:
                        connectTimeout: 5000
                        readTimeout: 5000
                        loggerLevel: basic

Si creamos beans @Configuration y propiedades de configuración, las propiedades de configuración ganan. Anulará el valor de @Configuration. Pero si desea cambiar la prioridad de @Configuration, puede cambiar spring.cloud.openfeign.client.default-to-properties a false.

Si queremos crear varios clientes falsos con el mismo nombre o URL que apunten al mismo servidor, pero cada uno con una configuración personalizada diferente, debemos usar el atributo contextId de @FeignClient para evitar el conflicto de nombres.

@FeignClient(contextId = "fooClient", name = "stores", configuration = FooConfiguration.class)
public interface FooClient {
    //..
}

@FeignClient(contextId = "barClient", name = "stores", configuration = BarConfiguration.class)
public interface BarClient {
    //..
}

También es posible configurar FeignClient para que no herede beans del entorno principal. Puede hacer esto anulando heritageParentConfiguration() en FeignClientConfigurer Bean para devolver falso:

@Configuration
public class CustomConfiguration{

@Bean
public FeignClientConfigurer feignClientConfigurer() {
            return new FeignClientConfigurer() {

                @Override
                public boolean inheritParentConfiguration() {
                    return false;
                }
            };

        }
}

De forma predeterminada, el cliente de Fingir no codifica barras/caracteres. Puede cambiar este comportamiento estableciendo el valor de spring.cloud.openfeign.client.decodeSlash en falso.

1.2.1 Configuración del codificador de resorte

En el SpringEncoder que proporcionamos, configuramos el juego de caracteres nulo para los tipos de contenido binario y UTF-8 para todos los demás tipos.

Puede modificar este comportamiento configurando el valor de spring.cloud.openfeign.encoder.charset-from-content-type en true para que el conjunto de caracteres se deduzca de los caracteres en el encabezado Content-Type.

1.3 Gestión del tiempo de espera

Podemos configurar tiempos de espera en clientes predeterminados y con nombre. OpenFeign utiliza dos parámetros de tiempo de espera:

• connectTimeout evita que la persona que llama se bloquee debido a que el procesamiento del servidor lleva demasiado tiempo.
• El readTimeout se aplica desde el establecimiento de la conexión y se activa cuando se tarda demasiado en devolver una respuesta.

Si el servidor no se está ejecutando o no está disponible, el paquete hace que se rechace la conexión. La comunicación finaliza con un mensaje de error o una reserva. Esto puede suceder antes si connectTimeout se establece bajo. Una parte significativa de este retraso se debe al tiempo que lleva realizar la búsqueda y recibir dicho paquete. Puede cambiar según el host remoto involucrado en la consulta de DNS.

1.4 Crear manualmente Fingir cliente

En algunos casos, puede ser necesario realizar personalizaciones en su cliente de Feign que no son posibles con los métodos descritos anteriormente. En este caso, puede usar la API de Feign Builder para crear el cliente. Este es un ejemplo que crea dos clientes de Fingir con la misma interfaz, pero cada uno configurado con un interceptor de solicitudes independiente.

@Import(FeignClientsConfiguration.class)
class FooController {

    private FooClient fooClient;

    private FooClient adminClient;

    @Autowired
    public FooController(Client client, Encoder encoder, Decoder decoder, Contract contract, MicrometerObservationCapability micrometerObservationCapability) {
        this.fooClient = Feign.builder().client(client)
                .encoder(encoder)
                .decoder(decoder)
                .contract(contract)
                .addCapability(micrometerObservationCapability)
                .requestInterceptor(new BasicAuthRequestInterceptor("user", "user"))
                .target(FooClient.class, "https://PROD-SVC");

        this.adminClient = Feign.builder().client(client)
                .encoder(encoder)
                .decoder(decoder)
                .contract(contract)
                .addCapability(micrometerObservationCapability)
                .requestInterceptor(new BasicAuthRequestInterceptor("admin", "admin"))
                .target(FooClient.class, "https://PROD-SVC");
    }
}

En el ejemplo anterior, FeignClientsConfiguration.class es la configuración predeterminada proporcionada por Spring Cloud OpenFeign.

PROD-SVC es el nombre del servicio al que el cliente realizará la solicitud.

El objeto Fingir contrato define qué anotaciones y valores son válidos para la interfaz. El Contract Bean inyectado automáticamente brinda soporte para anotaciones SpringMVC en lugar de las anotaciones nativas predeterminadas de Feign.

También puede usar Builder para configurar FeignClient para que no herede beans del contexto principal. Puede hacer esto anulando la llamada a heritageParentContext(false) de Builder.

1.5 Compatibilidad con el disyuntor de fingir Spring Cloud

Si Spring Cloud CircuitBreaker está en classpath y spring.cloud.openfeign.circuitbreaker.enabled=true, Feign envolverá todos los métodos con el interruptor de circuito.

Para deshabilitar la compatibilidad con Spring Cloud CircuitBreaker por cliente, cree un Vanilla Feign.Builder con un alcance de "prototipo", por ejemplo:

@Configuration
public class FooConfiguration {
    @Bean
    @Scope("prototype")
    public Feign.Builder feignBuilder() {
        return Feign.builder();
    }
}

Los nombres de los interruptores automáticos siguen el patrón <feignClientClassName>#<calledMethod>(<parameterTypes>). Al llamar a un @FeignClient con una interfaz FooClient y la barra de métodos de la interfaz llamada no tiene parámetros, el nombre del disyuntor será FooClient#bar().

A partir de 2020.0.2, el patrón de nombre del disyuntor cambió de <feignClientName>_< namedMethod>. Con el CircuitBreakerNameResolver introducido en 2020.0.4, los nombres de los interruptores automáticos pueden permanecer en el esquema anterior.

Al proporcionar un bean CircuitBreakerNameResolver, puede cambiar el patrón de nombre del interruptor automático.

@Configuration
public class FooConfiguration {
    @Bean
    public CircuitBreakerNameResolver circuitBreakerNameResolver() {
        return (String feignClientName, Target<?> target, Method method) -> feignClientName + "_" + method.getName();
    }
}

Para habilitar un grupo Spring Cloud CircuitBreaker, establezca la propiedad spring.cloud.openfeign.circuitbreaker.group.enabled en verdadero (el valor predeterminado es falso).

1.6 Configuración de CircuitBreaker usando las propiedades de configuración

Puede configurar CircuitBreaker a través de las propiedades de configuración.

Por ejemplo, si tiene este cliente de Fingir

@FeignClient(url = "http://localhost:8080")
public interface DemoClient {

    @GetMapping("demo")
    String getDemo();
}

Puede configurarlo usando las propiedades de configuración de la siguiente manera

spring:
  cloud:
    openfeign:
      circuitbreaker:
        enabled: true
        alphanumeric-ids:
          enabled: true
resilience4j:
  circuitbreaker:
    instances:
      DemoClientgetDemo:
        minimumNumberOfCalls: 69
  timelimiter:
    instances:
      DemoClientgetDemo:
        timeoutDuration: 10s

Si desea volver al nombre del disyuntor utilizado antes de Spring Cloud 2022.0.0, puede establecer spring.cloud.openfeign.circuitbreaker.alphanumeric-ids.enabled en false.

1.7. Fingir Spring Cloud Circuit Breaker Fallback

Spring Cloud CircuitBreaker admite el concepto de respaldo: una ruta de código predeterminada que se ejecuta cuando se abre el circuito o se produce un error. Para habilitar el respaldo para un @FeignClient determinado, establezca el atributo de respaldo en el nombre de la clase que implementa el respaldo. También debe declarar su implementación como Spring Bean.

@FeignClient(name = "test", url = "http://localhost:${server.port}/", fallback = Fallback.class)
    protected interface TestClient {

        @RequestMapping(method = RequestMethod.GET, value = "/hello")
        Hello getHello();

        @RequestMapping(method = RequestMethod.GET, value = "/hellonotfound")
        String getException();

    }

    @Component
    static class Fallback implements TestClient {

        @Override
        public Hello getHello() {
            throw new NoFallbackAvailableException("Boom!", new RuntimeException());
        }

        @Override
        public String getException() {
            return "Fixed response";
        }

    }

Si necesita acceder a lo que provocó que se disparara el respaldo, puede usar el atributo fallbackFactory en @FeignClient.

@FeignClient(name = "testClientWithFactory", url = "http://localhost:${server.port}/",
            fallbackFactory = TestFallbackFactory.class)
    protected interface TestClientWithFactory {

        @RequestMapping(method = RequestMethod.GET, value = "/hello")
        Hello getHello();

        @RequestMapping(method = RequestMethod.GET, value = "/hellonotfound")
        String getException();

    }

    @Component
    static class TestFallbackFactory implements FallbackFactory<FallbackWithFactory> {

        @Override
        public FallbackWithFactory create(Throwable cause) {
            return new FallbackWithFactory();
        }

    }

    static class FallbackWithFactory implements TestClientWithFactory {

        @Override
        public Hello getHello() {
            throw new NoFallbackAvailableException("Boom!", new RuntimeException());
        }

        @Override
        public String getException() {
            return "Fixed response";
        }

    }

1.8 Fingir y @Primario

Cuando se usa Fingir con el respaldo de Spring Cloud CircuitBreaker, hay varios beans del mismo tipo en ApplicationContext. Esto hará que @Autowired no funcione porque no hay exactamente un bean o uno marcado como primario. Para resolver esto, Spring Cloud OpenFeign marca todas las instancias de Feign como @Primary, por lo que Spring Framework sabrá qué bean inyectar. En algunos casos, esto puede no ser deseable. Para desactivar este comportamiento, establezca el atributo principal de @FeignClient en falso.

@FeignClient(name = "hello", primary = false)
public interface HelloClient {
    // methods here
}

1.9 Soporte para Fingir herencia

Fingir admite API de estilo de plantilla a través de interfaces de herencia única. Esto permite agrupar operaciones comunes en una interfaz base conveniente.

UserService.java

public interface UserService {

    @RequestMapping(method = RequestMethod.GET, value ="/users/{id}")
    User getUser(@PathVariable("id") long id);
}

UserResource.java

@RestController
public class UserResource implements UserService {

}

UsuarioCliente.java

package project.user;

@FeignClient("users")
public interface UserClient extends UserService {

}

Las interfaces de @FeignClient no deben compartirse entre el servidor y el cliente, y ya no se admiten las anotaciones de las interfaces de @FeignClient con @RequestMapping a nivel de clase.

1.10 Fingir compresión de solicitud/respuesta

Podría considerar habilitar la compresión GZIP de solicitudes o respuestas para sus solicitudes de Fingir. Puede hacerlo habilitando una de estas propiedades:

spring.cloud.openfeign.compression.request.enabled=true
spring.cloud.openfeign.compression.response.enabled=true

La compresión de solicitud fingida le brinda configuraciones similares a las que podría tener para su servidor web:

spring.cloud.openfeign.compression.request.enabled=true
spring.cloud.openfeign.compression.request.mime-types=text/xml,application/xml,application/json
spring.cloud.openfeign.compression.request.min-request-size=2048

Estas propiedades le permiten elegir entre tipos de medios comprimidos y longitudes mínimas de umbral de solicitud.

Dado que OkHttpClient usa compresión "transparente", que está deshabilitada en presencia de encabezados de codificación de contenido o de aceptación de codificación, cuando feign.okhttp.OkHttpClient está presente en el classpath y spring.cloud.openfeign.okhttp.enabled está configurado Cuando es verdadero, no habilitamos la compresión.

1.11 Fingir registros

Se crea un registrador para cada cliente de Fingir creado. De forma predeterminada, el nombre del registrador es el nombre de clase completo de la interfaz utilizada para crear el cliente de Fingir. El registro de Fingir solo responde al nivel DEBUG.

aplicación.yml

logging.level.project.user.UserClient: DEBUG

Puede configurar un objeto Logger.Level por cliente para decirle a Feign cuánto registrar. Las opciones son:

• NINGUNO, sin registro ( predeterminado ).
• BASIC, solo registra el método de solicitud y la URL junto con el código de estado de respuesta y el tiempo de ejecución.
• HEADERS, registra información básica y encabezados de solicitud y respuesta.
• COMPLETO, registros de encabezados de solicitud y respuesta, cuerpo y metadatos.

Por ejemplo, lo siguiente establecerá Logger.Level en FULL:

@Configuration
public class FooConfiguration {
    @Bean
    Logger.Level feignLoggerLevel() {
        return Logger.Level.FULL;
    }
}

1.12 Compatibilidad con la capacidad de fingir

Fingir la capacidad expone los componentes principales de Fingir para que puedan ser modificados. Por ejemplo, estas funciones pueden aceptar un cliente, decorarlo y devolver la instancia decorada a Fingir. El soporte para Micrómetro es un buen ejemplo de la vida real. Ver [micrómetro-soporte].

Crear uno o más Capability Beans y colocarlos en una configuración de @FeignClient le permite registrarlos y modificar el comportamiento del cliente asociado.

@Configuration
public class FooConfiguration {
    @Bean
    Capability customCapability() {
        return new CustomCapability();
    }
}

1.13 Soporte de micrómetros

Se crea y registra un Bean MicrometerObservationCapability para que Micrometer pueda observar su cliente Feign si se cumplen todas las condiciones siguientes:

• fingir-micrómetro está en el classpath.
• El bean ObservationRegistry está disponible.
• Fingir propiedad de micrómetro establecida en verdadero (predeterminado)
  • spring.cloud.openfeign.micrometer.enabled=true (para todos los clientes)
  • spring.cloud.openfeign.client.config.feignName.micrometer.enabled=true (para un solo cliente)

Si su aplicación ya usa Micrometer, habilitar esta característica es tan simple como poner fingir-micrómetro en su classpath.

También puede deshabilitar esta característica de dos maneras:

• Excluya fingir-micrómetro de su classpath.
• Establezca la propiedad fingir micrómetro en falso
  • spring.cloud.openfeign.micrómetro.habilitado=falso
  • spring.cloud.openfeign.client.config.feignName.micrometer.enabled=false

spring.cloud.openfeign.micrometer.enabled=false desactiva la compatibilidad con Micrometer para todos los clientes de Feign, independientemente del valor de la marca de nivel de cliente: spring.cloud.openfeign.client.config.feignName.micrometer.enabled. Si desea habilitar o deshabilitar la compatibilidad con Micrometer por cliente, no configure spring.cloud.openfeign.micrometer.enabled y use spring.cloud.openfeign.client.config.feignName.micrometer.enabled.

También puede personalizar MicrometerObservationCapability registrando su propio bean:

@Configuration
public class FooConfiguration {
    @Bean
    public MicrometerObservationCapability micrometerObservationCapability(ObservationRegistry registry) {
        return new MicrometerObservationCapability(registry);
    }
}

Todavía es posible usar MicrometerCapability en Fingir (solo se admiten métricas), debe deshabilitar la compatibilidad con Micrometer (spring.cloud.openfeign.micrometer.enabled=false) y crear un MicrometerCapability Bean:

@Configuration
public class FooConfiguration {
    @Bean
    public MicrometerCapability micrometerCapability(MeterRegistry meterRegistry) {
        return new MicrometerCapability(meterRegistry);
    }
}

1.14 Fingir almacenamiento en caché

Si se utiliza la anotación @EnableCaching, se creará y registrará un bean CachingCapability para que su cliente Feign reconozca la anotación @Cache* en su interfaz:

public interface DemoClient {

    @GetMapping("/demo/{filterParam}")
    @Cacheable(cacheNames = "demo-cache", key = "#keyParam")
    String demoEndpoint(String keyParam, @PathVariable String filterParam);
}

También puede deshabilitar esta característica con la propiedad spring.cloud.openfeign.cache.enabled=false.

1.15 Fingir el soporte de @QueryMap

Spring Cloud OpenFeign proporciona una anotación @SpringQueryMap equivalente para anotar parámetros POJO o Map como mapas de parámetros de consulta.

Por ejemplo, la clase Params define los parámetros param1 y param2:

// Params.java
public class Params {
    private String param1;
    private String param2;

    // [Getters and setters omitted for brevity]
}

El siguiente cliente falso usa la clase Params usando la anotación @SpringQueryMap:

@FeignClient("demo")
public interface DemoTemplate {

    @GetMapping(path = "/demo")
    String demoEndpoint(@SpringQueryMap Params params);
}

Si necesita más control sobre el mapa de parámetros de consulta generado, puede implementar un QueryMapEncoder Bean personalizado.

1.16 Soporte HATEOAS

Spring proporciona API para crear representaciones REST siguiendo los principios HATEOAS, Spring Hateoas y Spring Data REST.

La compatibilidad con Fingir HATEOAS está habilitada de manera predeterminada si su proyecto usa el iniciador org.springframework.boot:spring-boot-starter-hateoas o el iniciador org.springframework.boot:spring-boot-starter-data-rest.

Cuando la compatibilidad con HATEOAS está habilitada, los clientes de Feign pueden serializar y deserializar modelos de representación de HATEOAS: EntityModel, CollectionModel y PagedModel.

@FeignClient("demo")
public interface DemoTemplate {

    @GetMapping(path = "/stores")
    CollectionModel<Store> getStores();
}

1.17 Compatibilidad con Spring @MatrixVariable

Spring Cloud OpenFeign brinda soporte para la anotación Spring @MatrixVariable.

Si se pasa un mapa como parámetro de método, el segmento de ruta @MatrixVariable se crea concatenando los pares clave-valor en el mapa con =.

Si se pasa un objeto diferente, el nombre proporcionado en la anotación @MatrixVariable (si está definida) o el nombre de la variable anotada se combinará usando = con el parámetro de método proporcionado.

IMPORTANTE

Aunque en el lado del servidor, Spring no requiere que el usuario nombre el marcador de posición del segmento de ruta del mismo modo que la variable de matriz, ya que esto sería demasiado ambiguo en el lado del cliente, Spring Cloud OpenFeign requiere que agregue un marcador de posición de segmento de ruta con el nombre Coincide con el nombre proporcionado en la anotación @MatrixVariable (si está definida) o el nombre de la variable anotada.

Por ejemplo:

@GetMapping("/objects/links/{matrixVars}")
Map<String, List<String>> getObjects(@MatrixVariable Map<String, List<String>> matrixVars);

Tenga en cuenta que tanto los nombres de las variables como los marcadores de posición del segmento de la ruta se denominan matrixVars.

@FeignClient("demo")
public interface DemoTemplate {

    @GetMapping(path = "/stores")
    CollectionModel<Store> getStores();
}

1.18 Compatibilidad con el formato FeignCollection

Admitimos fingir.CollectionFormat al proporcionar la anotación @CollectionFormat. Puede anotar un método de cliente de Fingir (o una clase completa para afectar a todos los métodos) con él pasando el fingir.CollectionFormat deseado como el valor de la anotación.

En el siguiente ejemplo, se usa el formato CSV en lugar del predeterminado EXPLODED para este método.

@FeignClient(name = "demo")
protected interface DemoFeignClient {

    @CollectionFormat(feign.CollectionFormat.CSV)
    @GetMapping(path = "/test")
    ResponseEntity performRequest(String test);

}

1.19 Soporte reactivo

Dado que el proyecto OpenFeign actualmente no admite clientes reactivos como Spring WebClient, Spring Cloud OpenFeign tampoco. Agregaremos soporte aquí una vez que esté disponible en el proyecto principal.

Hasta entonces, recomendamos usar fingir reactivo para admitir Spring WebClient.

1.19.1 Errores de inicialización temprana

Dependiendo de cómo use el cliente de Feign, es posible que vea errores de inicialización al iniciar su aplicación. Para resolver este problema, puede usar un ObjectProvider al conectar clientes automáticamente.

@Autowired
ObjectProvider<TestFeignClient> testFeignClient;

1.20 Compatibilidad con Spring Data

Si Jackson Databind y Spring Data Commons están en el classpath, los convertidores para org.springframework.data.domain.Page y org.springframework.data.domain.Sort se agregarán automáticamente.

Para deshabilitar este comportamiento, configure:

spring.cloud.openfeign.autoconfiguration.jackson.enabled=false

详见 org.springframework.cloud.openfeign.FeignAutoConfiguration.FeignJacksonConfiguration。

1.21 Compatibilidad con Spring @RefreshScope

Si la actualización del cliente de Fingir está habilitada, cada creación de cliente de Fingir tiene:

• fingir.Request.Options como un bean de ámbito de actualización. Esto significa que las propiedades como connectTimeout y readTimeout se pueden actualizar para cualquier instancia de cliente de Feign.
• La URL envuelta en org.springframework.cloud.openfeign.RefreshableUrl. Esto significa que si define la URL del cliente de Feign con la propiedad spring.cloud.openfeign.client.config.{feignName}.url, puede actualizar cualquier instancia de cliente de Feign.

Puede actualizar estos atributos a través de POST /actuator/refresh.

De forma predeterminada, el comportamiento de actualización del cliente de Fingir está deshabilitado. Utilice las siguientes propiedades para habilitar el comportamiento de actualización:

spring.cloud.openfeign.client.refresh-enabled=true

No anote la interfaz @FeignClient con la anotación @RefreshScope.

1.22 Compatibilidad con OAuth2

La compatibilidad con OAuth2 se puede habilitar configurando el siguiente indicador:

spring.cloud.openfeign.oauth2.enabled=true

Cuando este indicador se establece en "true" y existe el detalle del recurso de contexto del cliente oauth2, se crea un bean de clase OAuth2AccessTokenInterceptor. Antes de cada solicitud, el interceptor analiza el token de acceso requerido y lo presenta como un encabezado. OAuth2AccessTokenInterceptor utiliza OAuth2AuthorizedClientManager para obtener OAuth2AuthorizedClient con OAuth2AccessToken. Si el usuario especifica un clientRegistrationId de OAuth2 mediante la propiedad spring.cloud.openfeign.oauth2.clientRegistrationId, se utilizará para recuperar el token. Si no se recupera ningún token o no se especifica clientRegistrationId, se utilizará el serviceId recuperado del segmento de host de URL.

CONSEJO

Usar el serviceId como el registrationId del cliente OAuth2 es conveniente para los clientes de Feign con equilibrio de carga. Para los clientes sin equilibrio de carga, el clientRegistrationId basado en propiedades es un enfoque apropiado.

CONSEJO

Si no desea utilizar el OAuth2AuthorizedClientManager predeterminado, puede crear una instancia de un bean de este tipo directamente en su configuración.

1.23 Transformar solicitudes HTTP con equilibrio de carga

Puede usar la ServiceInstance seleccionada para transformar solicitudes HTTP con equilibrio de carga.

Para Solicitud, debe implementar y definir LoadBalancerFeignRequestTransformer de la siguiente manera:

@Bean
public LoadBalancerFeignRequestTransformer transformer() {
    return new LoadBalancerFeignRequestTransformer() {

        @Override
        public Request transformRequest(Request request, ServiceInstance instance) {
            Map<String, Collection<String>> headers = new HashMap<>(request.headers());
            headers.put("X-ServiceId", Collections.singletonList(instance.getServiceId()));
            headers.put("X-InstanceId", Collections.singletonList(instance.getInstanceId()));
            return Request.create(request.httpMethod(), request.url(), headers, request.body(), request.charset(),
                    request.requestTemplate());
        }
    };
}

Si se definen varios convertidores, se aplicarán en el orden en que se definen los beans. Como alternativa, puede usar LoadBalancerFeignRequestTransformer.DEFAULT_ORDER para especificar este orden.

1.24 Soporte para encabezados reenviados por X

La compatibilidad con X-Forwarded-Host y X-Forwarded-Proto se puede habilitar configurando los siguientes indicadores:

spring.cloud.loadbalancer.x-forwarded.enabled=true

1.25 Métodos de soporte para proporcionar direcciones URL a clientes de Fingir

Puede proporcionar una URL al cliente de Fingir de cualquiera de las siguientes formas:

Escenas	ejemplo	detalle
La URL se proporciona en la anotación @FeignClient.	@FeignClient(name="testClient", url="http://localhost:8081")	La URL se analiza a partir del atributo url de la anotación, sin equilibrio de carga.
La URL se proporciona en las propiedades de configuración y anotación de @FeignClient.	@FeignClient(name="testClient", url="http://localhost:8081") y la propiedad spring.cloud.openfeign.client.config.testClient.url=http://localhost: 8081	La URL se analiza a partir del atributo url de la anotación, sin equilibrio de carga. La URL proporcionada en la propiedad de configuración todavía no se usa.
URL没有在 @FeignClient 注解中提供，而是在配置属性中提供。	@FeignClient(name="testClient") 和定义在 application.yml 中的属性 spring.cloud.openfeign.client.config.testClient.url=http://localhost:8081	URL 从配置属性中解析，没有负载均衡。如果 spring.cloud.openfeign.client.refresh-enabled=true，那么配置属性中定义的 URL 可以被刷新，如 Spring RefreshScope 的支持 中所述。
在 @FeignClient 注解中和配置属性中都没有提供这个URL。	@FeignClient(name="testClient")	URL是从注解的 name 属性中解析出来的，具有负载均衡性。

1.26. AOT 和原生镜像的支持

Spring Cloud OpenFeign 支持 Spring AOT 转换和原生镜像，但是，只有在禁用刷新模式、禁用Feign客户端刷新（默认设置）和禁用 延迟的 @FeignClient 属性解析（默认设置）的情况下，才能支持。

如果你想在AOT或原生镜像模式下运行 Spring Cloud OpenFeign 客户端，请确保将 spring.cloud.refresh.enabled 设置为 false。

如果你想在AOT或原生镜像模式下运行 Spring Cloud OpenFeign 客户端，请确保 spring.cloud.openfeign.client.refresh-enabled 没有被设置为 true。

如果你想在AOT或原生镜像模式下运行Spring Cloud OpenFeign客户端，请确保 spring.cloud.openfeign.lazy-attributes-resolution 没有被设置为 true。

然而，如果你通过属性设置了 url 值，那么通过运行带有 -Dspring.cloud.openfeign.client.config.[clientId].url=[url] 标志的镜像，就有可能覆盖 @FeignClient 的 url 值。为了实现覆盖，在构建时也必须通过属性而不是 @FeignClient 属性来设置一个 url 值。

2. 配置属性

各种属性可以在 application.properties 文件、application.yml 文件中指定，也可以作为命令行开关。本附录提供了一个常见的 Spring Cloud OpenFeign 属性列表，以及对消费这些属性的底层类的引用。

属性贡献可以来自你classpath上的其他jar文件，所以你不应该认为这是一个详尽的列表。另外，你可以定义你自己的属性。

Name	Default	Description
spring.cloud.openfeign.autoconfiguration.jackson.enabled	false	If true, PageJacksonModule and SortJacksonModule bean will be provided for Jackson page decoding.
spring.cloud.openfeign.circuitbreaker.enabled	false	If true, an OpenFeign client will be wrapped with a Spring Cloud CircuitBreaker circuit breaker.
spring.cloud.openfeign.circuitbreaker.group.enabled	false	If true, an OpenFeign client will be wrapped with a Spring Cloud CircuitBreaker circuit breaker with with group.
spring.cloud.openfeign.client.config
spring.cloud.openfeign.client.decode-slash	true	Feign clients do not encode slash / characters by default. To change this behavior, set the decodeSlash to false.
spring.cloud.openfeign.client.default-config	default
spring.cloud.openfeign.client.default-to-properties	true
spring.cloud.openfeign.client.refresh-enabled	false	Enables options value refresh capability for Feign.
spring.cloud.openfeign.compression.request.enabled	false	Enables the request sent by Feign to be compressed.
spring.cloud.openfeign.compression.request.mime-types	[text/xml, application/xml, application/json]	The list of supported mime types.
spring.cloud.openfeign.compression.request.min-request-size	2048	The minimum threshold content size.
spring.cloud.openfeign.compression.response.enabled	false	Enables the response from Feign to be compressed.
spring.cloud.openfeign.encoder.charset-from-content-type	false	Indicates whether the charset should be derived from the {@code Content-Type} header.
spring.cloud.openfeign.httpclient.connection-timeout	2000
spring.cloud.openfeign.httpclient.connection-timer-repeat	3000
spring.cloud.openfeign.httpclient.disable-ssl-validation	false
spring.cloud.openfeign.httpclient.enabled	true	Enables the use of the Apache HTTP Client by Feign.
spring.cloud.openfeign.httpclient.follow-redirects	true
spring.cloud.openfeign.httpclient.hc5.enabled	false	Enables the use of the Apache HTTP Client 5 by Feign.
spring.cloud.openfeign.httpclient.hc5.pool-concurrency-policy		Pool concurrency policies.
spring.cloud.openfeign.httpclient.hc5.pool-reuse-policy		Pool connection re-use policies.
spring.cloud.openfeign.httpclient.hc5.socket-timeout	5	Default value for socket timeout.
spring.cloud.openfeign.httpclient.hc5.socket-timeout-unit		Default value for socket timeout unit.
spring.cloud.openfeign.httpclient.max-connections	200
spring.cloud.openfeign.httpclient.max-connections-per-route	50
spring.cloud.openfeign.httpclient.ok-http.read-timeout	60s	{@link OkHttpClient} read timeout; defaults to 60 seconds.
spring.cloud.openfeign.httpclient.time-to-live	900
spring.cloud.openfeign.httpclient.time-to-live-unit
spring.cloud.openfeign.micrometer.enabled	true	Enables Micrometer capabilities for Feign.
spring.cloud.openfeign.oauth2.enabled	false	Enables feign interceptor for managing oauth2 access token.
spring.cloud.openfeign.oauth2.load-balanced	false	Enables load balancing for oauth2 access token provider.
spring.cloud.openfeign.okhttp.enabled	false	Enables the use of the OK HTTP Client by Feign.