<h3id="netflix-feign-starter"><aclass="anchor"href="#netflix-feign-starter"></a><aclass="link"href="#netflix-feign-starter">1.1. How to Include Feign</a></h3>
<p>In the <code>@FeignClient</code> annotation the String value ("stores" above) is an arbitrary client name, which is used to create a <ahref="https://github.com/spring-cloud/spring-cloud-commons/blob/master/spring-cloud-loadbalancer/src/main/java/org/springframework/cloud/loadbalancer/blocking/client/BlockingLoadBalancerClient.java">Spring Cloud LoadBalancer client</a>.
in your external configuration using <ahref="https://cloud.spring.io/spring-cloud-static/spring-cloud-commons/current/reference/html/#simplediscoveryclient"><code>SimpleDiscoveryClient</code></a>.</p>
<p>A central concept in Spring Cloud’s Feign support is that of the named client. Each feign client is part of an ensemble of components that work together to contact a remote server on demand, and the ensemble has a name that you give it as an application developer using the <code>@FeignClient</code> annotation. Spring Cloud creates a new ensemble as an
<code>ApplicationContext</code> on demand for each named client using <code>FeignClientsConfiguration</code>. This contains (amongst other things) an <code>feign.Decoder</code>, a <code>feign.Encoder</code>, and a <code>feign.Contract</code>.
It is possible to override the name of that ensemble by using the <code>contextId</code>
attribute of the <code>@FeignClient</code> annotation.</p>
</div>
<divclass="paragraph">
<p>Spring Cloud lets you take full control of the feign client by declaring additional configuration (on top of the <code>FeignClientsConfiguration</code>) using <code>@FeignClient</code>. Example:</p>
<p>In this case the client is composed from the components already in <code>FeignClientsConfiguration</code> together with any in <code>FooConfiguration</code> (where the latter will override the former).</p>
</div>
<divclass="admonitionblock note">
<table>
<tr>
<tdclass="icon">
<iclass="fa icon-note"title="Note"></i>
</td>
<tdclass="content">
<code>FooConfiguration</code> does not need to be annotated with <code>@Configuration</code>. However, if it is, then take care to exclude it from any <code>@ComponentScan</code> that would otherwise include this configuration as it will become the default source for <code>feign.Decoder</code>, <code>feign.Encoder</code>, <code>feign.Contract</code>, etc., when specified. This can be avoided by putting it in a separate, non-overlapping package from any <code>@ComponentScan</code> or <code>@SpringBootApplication</code>, or it can be explicitly excluded in <code>@ComponentScan</code>.
</td>
</tr>
</table>
</div>
<divclass="admonitionblock note">
<table>
<tr>
<tdclass="icon">
<iclass="fa icon-note"title="Note"></i>
</td>
<tdclass="content">
The <code>serviceId</code> attribute is now deprecated in favor of the <code>name</code> attribute.
</td>
</tr>
</table>
</div>
<divclass="admonitionblock note">
<table>
<tr>
<tdclass="icon">
<iclass="fa icon-note"title="Note"></i>
</td>
<tdclass="content">
Using <code>contextId</code> attribute of the <code>@FeignClient</code> annotation in addition to changing the name of
the <code>ApplicationContext</code> ensemble, it will override the alias of the client name
and it will be used as part of the name of the configuration bean created for that client.
</td>
</tr>
</table>
</div>
<divclass="admonitionblock warning">
<table>
<tr>
<tdclass="icon">
<iclass="fa icon-warning"title="Warning"></i>
</td>
<tdclass="content">
Previously, using the <code>url</code> attribute, did not require the <code>name</code> attribute. Using <code>name</code> is now required.
</td>
</tr>
</table>
</div>
<divclass="paragraph">
<p>Placeholders are supported in the <code>name</code> and <code>url</code> attributes.</p>
<code>spring-cloud-starter-openfeign</code> supports <code>spring-cloud-starter-loadbalancer</code>. However, as is an optional dependency, you need to make sure it been added to your project if you want to use it.
<p>The OkHttpClient and ApacheHttpClient feign clients can be used by setting <code>feign.okhttp.enabled</code> or <code>feign.httpclient.enabled</code> to <code>true</code>, respectively, and having them on the classpath.
You can customize the HTTP client used by providing a bean of either <code>org.apache.http.impl.client.CloseableHttpClient</code> when using Apache or <code>okhttp3.OkHttpClient</code> when using OK HTTP.</p>
<p>Spring Cloud OpenFeign <em>does not</em> provide the following beans by default for feign, but still looks up beans of these types from the application context to create the feign client:</p>
<p>Creating a bean of one of those type and placing it in a <code>@FeignClient</code> configuration (such as <code>FooConfiguration</code> above) allows you to override each one of the beans described. Example:</p>
public BasicAuthRequestInterceptor basicAuthRequestInterceptor() {
return new BasicAuthRequestInterceptor("user", "password");
}
}</code></pre>
</div>
</div>
<divclass="paragraph">
<p>This replaces the <code>SpringMvcContract</code> with <code>feign.Contract.Default</code> and adds a <code>RequestInterceptor</code> to the collection of <code>RequestInterceptor</code>.</p>
</div>
<divclass="paragraph">
<p><code>@FeignClient</code> also can be configured using configuration properties.</p>
<p>Default configurations can be specified in the <code>@EnableFeignClients</code> attribute <code>defaultConfiguration</code> in a similar manner as described above. The difference is that this configuration will apply to <em>all</em> feign clients.</p>
</div>
<divclass="paragraph">
<p>If you prefer using configuration properties to configured all <code>@FeignClient</code>, you can create configuration properties with <code>default</code> feign name.</p>
<p>If Hystrix is on the classpath and <code>feign.hystrix.enabled=true</code>, Feign will wrap all methods with a circuit breaker. Returning a <code>com.netflix.hystrix.HystrixCommand</code> is also available. This lets you use reactive patterns (with a call to <code>.toObservable()</code> or <code>.observe()</code> or asynchronous use (with a call to <code>.queue()</code>).</p>
</div>
<divclass="paragraph">
<p>To disable Hystrix support on a per-client basis create a vanilla <code>Feign.Builder</code> with the "prototype" scope, e.g.:</p>
<p>Hystrix supports the notion of a fallback: a default code path that is executed when they circuit is open or there is an error. To enable fallbacks for a given <code>@FeignClient</code> set the <code>fallback</code> attribute to the class name that implements the fallback. You also need to declare your implementation as a Spring bean.</p>
@RequestMapping(method = RequestMethod.GET, value = "/hello")
Hello iFailSometimes();
}
static class HystrixClientFallback implements HystrixClient {
@Override
public Hello iFailSometimes() {
return new Hello("fallback");
}
}</code></pre>
</div>
</div>
<divclass="paragraph">
<p>If one needs access to the cause that made the fallback trigger, one can use the <code>fallbackFactory</code> attribute inside <code>@FeignClient</code>.</p>
There is a limitation with the implementation of fallbacks in Feign and how Hystrix fallbacks work. Fallbacks are currently not supported for methods that return <code>com.netflix.hystrix.HystrixCommand</code> and <code>rx.Observable</code>.
<h3id="feign-and-primary"><aclass="anchor"href="#feign-and-primary"></a><aclass="link"href="#feign-and-primary">1.6. Feign and <code>@Primary</code></a></h3>
<p>When using Feign with Hystrix fallbacks, there are multiple beans in the <code>ApplicationContext</code> of the same type. This will cause <code>@Autowired</code> to not work because there isn’t exactly one bean, or one marked as primary. To work around this, Spring Cloud Netflix marks all Feign instances as <code>@Primary</code>, so Spring Framework will know which bean to inject. In some cases, this may not be desirable. To turn off this behavior set the <code>primary</code> attribute of <code>@FeignClient</code> to false.</p>
<p>A logger is created for each Feign client created. By default the name of the logger is the full class name of the interface used to create the Feign client. Feign logging only responds to the <code>DEBUG</code> level.</p>
<p>Spring provides some APIs to create REST representations that follow the <ahref="https://en.wikipedia.org/wiki/HATEOAS">HATEOAS</a> principle, <ahref="https://spring.io/projects/spring-hateoas">Spring Hateoas</a> and <ahref="https://spring.io/projects/spring-data-rest">Spring Data REST</a>.</p>
</div>
<divclass="paragraph">
<p>If your project use the <code>org.springframework.boot:spring-boot-starter-hateoas</code> starter
or the <code>org.springframework.boot:spring-boot-starter-data-rest</code> starter, Feign HATEOAS support is enabled by default.</p>
</div>
<divclass="paragraph">
<p>When HATEOAS support is enabled, Feign clients are allowed to serialize
and deserialize HATEOAS representation models: <ahref="https://docs.spring.io/spring-hateoas/docs/1.0.0.M1/apidocs/org/springframework/hateoas/EntityModel.html">EntityModel</a>, <ahref="https://docs.spring.io/spring-hateoas/docs/1.0.0.M1/apidocs/org/springframework/hateoas/CollectionModel.html">CollectionModel</a> and <ahref="https://docs.spring.io/spring-hateoas/docs/1.0.0.M1/apidocs/org/springframework/hateoas/PagedModel.html">PagedModel</a>.</p>
<h3id="spring-matrixvariable-support"><aclass="anchor"href="#spring-matrixvariable-support"></a><aclass="link"href="#spring-matrixvariable-support">1.12. Spring @MatrixVariable Support</a></h3>
<divclass="paragraph">
<p>Spring Cloud OpenFeign provides support for the Spring <code>@MatrixVariable</code> annotation.</p>
</div>
<divclass="paragraph">
<p>If a map is passed as the method argument, the <code>@MatrixVariable</code> path segment is created by joining key-value pairs from the map with a <code>=</code>.</p>
</div>
<divclass="paragraph">
<p>If a different object is passed, either the <code>name</code> provided in the <code>@MatrixVariable</code> annotation (if defined) or the annotated variable name is
joined with the provided method argument using <code>=</code>.</p>
</div>
<divclass="dlist">
<dl>
<dtclass="hdlist1">IMPORTANT</dt>
<dd>
<p>Even though, on the server side, Spring does not require the users to name the path segment placeholder same as the matrix variable name, since it would be too ambiguous on the client side, Sprig Cloud OpenFeign requires that you add a path segment placeholder with a name matching either the <code>name</code> provided in the <code>@MatrixVariable</code> annotation (if defined) or the annotated variable name.</p>
<p>As the <ahref="https://github.com/OpenFeign/feign">OpenFeign project</a> does not currently support reactive clients, such as <ahref="https://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/web/reactive/function/client/WebClient.html">Spring WebClient</a>, neither does Spring Cloud OpenFeign. We will add support for it here as soon as it becomes available in the core project.</p>
</div>
<divclass="paragraph">
<p>Until that is done, we recommend using <ahref="https://github.com/Playtika/feign-reactive">feign-reactive</a> for Spring WebClient support.</p>
<h4id="early-initialization-errors"><aclass="anchor"href="#early-initialization-errors"></a><aclass="link"href="#early-initialization-errors">1.13.1. Early Initialization Errors</a></h4>
