162 lines
8.3 KiB
Markdown
162 lines
8.3 KiB
Markdown
- [Spring Cloud OpenFeign](#spring-cloud-openfeign)
|
||
- [Feign](#feign)
|
||
- [引入Feign](#引入feign)
|
||
- [@FeignClient注解的属性解析模式](#feignclient注解的属性解析模式)
|
||
- [覆盖Feign的默认属性](#覆盖feign的默认属性)
|
||
- [重试](#重试)
|
||
- [通过Configuration类或配置文件来修改Feign Client的默认行为](#通过configuration类或配置文件来修改feign-client的默认行为)
|
||
- [超时处理](#超时处理)
|
||
- [Feign Caching](#feign-caching)
|
||
|
||
|
||
# Spring Cloud OpenFeign
|
||
## Feign
|
||
Feign是一个声明式的web service client，其能够让编写web service client的过程更加简单。在使用Feign时，只需要创建一个接口并且为其添加注解。
|
||
在使用Feign时，Spring Cloud集成了Eureka、Spring Cloud CircuitBreaker和Spring Cloud LoadBalancer来向使用者提供一个负载均衡的http client。
|
||
### 引入Feign
|
||
如果要在项目中引入Feign，可以添加如下启动器依赖：
|
||
```xml
|
||
<groupId>org.springframework.cloud</groupId>
|
||
<artifactId>spring-cloud-starter-openfeign</artifactId>
|
||
```
|
||
在使用Feign时，需要为启动类添加`@EnableFeignClients`注解，示例如下所示：
|
||
```java
|
||
@SpringBootApplication
|
||
@EnableFeignClients
|
||
public class Application {
|
||
|
||
public static void main(String[] args) {
|
||
SpringApplication.run(Application.class, args);
|
||
}
|
||
|
||
}
|
||
```
|
||
使用Feign时，定义接口并添加注解的示例如下所示：
|
||
```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);
|
||
}
|
||
```
|
||
上述示例中，@FeignClient中指定的字符串是一个任意的client name，用于创建spring cloud loadbalancer client，对于该注解还可以指定一个`url`属性。在spring context中，该bean对象的name即是接口的全类名，bean name也可以通过@FeignClient注解中的`qualifiers`属性来替换。
|
||
上述的loadbalancer client会取发现"stores" service对应的物理地址，如果你的应用是一个Eureka client，那么loadbalancer client会从Eureka注册中心中进行解析。
|
||
#### @FeignClient注解的属性解析模式
|
||
当创建Feign client bean对象时，会解析传递给@FeignClient注解的属性值。这些值默认是立即解析的。
|
||
如果如果需要延迟这些属性值的解析时机，可以配置`spring.cloud.openfeign.lazy-attributes-resolution`的值为true。
|
||
### 覆盖Feign的默认属性
|
||
Spring Cloud Feign的核心理念是命名客户端（named client）。每个Feign client都是组件集合一部分，组件集合协同工作，并且在需要时连接远程的server。该组件集合有一个名称，该值通过@FeignClient的value属性赋值。对于每个named client，Spring Cloud使用`FeignClientsConfiguration`来创建一个新的集合作为Application Client。
|
||
组件集合中包含有一个`feign.Decoder`，一个`feign.Encoder`和`feign.Contract`。可以通过@FeignClient注解中的`contextId`属性来覆盖集合name。
|
||
Spring Cloud允许通过声明额外的configuration来完全掌控feign client，示例如下：
|
||
```java
|
||
@FeignClient(name = "stores", configuration = FooConfiguration.class)
|
||
public interface StoreClient {
|
||
//..
|
||
}
|
||
```
|
||
在这种情况下，client由`FeignClientsConfiguration`中已经存在的组件和`FooConfiguration`中的组件共同组成，并且后者会覆盖前者。
|
||
> FooConfiguration类在声明时不要为其添加@Configuration注解，否则其会成为feign.Decoder, feign.Encoder, feign.Contract的默认来源。
|
||
|
||
对于`name`和`url`属性，赋值支持占位符：
|
||
```java
|
||
@FeignClient(name = "${feign.name}", url = "${feign.url}")
|
||
public interface StoreClient {
|
||
//..
|
||
}
|
||
```
|
||
#### 重试
|
||
一个`Retryer.NEVER_RETRY`的bean对象会被默认创建，其会禁止重试操作。但是，其会自动重试IOException，将IOException看作暂时性地网络异常，并且在ErrorDecoder中抛出RetryableException。
|
||
在@FeignClient注解`configuration`属性指定的配置类中创建Bean对象可以允许覆盖默认的bean对象，示例如下：
|
||
```java
|
||
@Configuration
|
||
public class FooConfiguration {
|
||
@Bean
|
||
public Contract feignContract() {
|
||
return new feign.Contract.Default();
|
||
}
|
||
|
||
@Bean
|
||
public BasicAuthRequestInterceptor basicAuthRequestInterceptor() {
|
||
return new BasicAuthRequestInterceptor("user", "password");
|
||
}
|
||
}
|
||
```
|
||
#### 通过Configuration类或配置文件来修改Feign Client的默认行为
|
||
@FeignClient也可以通过配置文件来进行配置：
|
||
```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
|
||
```
|
||
feignName在上述配置文件中代表@FeignClient注解中的value值。
|
||
> 若feignName的值为default，可以将配置应用于所有的feign client。
|
||
|
||
可以在`@EnableFeignClients`注解中指定defaultConfiguration属性，其可以指定一个自定义的默认配置类，覆盖的行为会作用于所有的Feign Client。
|
||
可以使用`spring.cloud.openfeign.client.config.feignName.defaultQueryParameters`和`spring.cloud.openfeign.client.config.feignName.defaultRequestHeaders`来指定client每次请求都会发送的请求参数和请求header。
|
||
|
||
如果在创建Configuration类的同时也指定了配置文件，那么配置文件的优先级更高，配置文件的值会覆盖Configuration类中的值。
|
||
如果想要多个feign client拥有相同的name和url，以使它们指向同一个server，但不同feign client拥有不同的配置。可以为它们指定不同的`contextId`。
|
||
```java
|
||
@FeignClient(contextId = "fooClient", name = "stores", configuration = FooConfiguration.class)
|
||
public interface FooClient {
|
||
//..
|
||
}
|
||
@FeignClient(contextId = "barClient", name = "stores", configuration = BarConfiguration.class)
|
||
public interface BarClient {
|
||
//..
|
||
}
|
||
```
|
||
### 超时处理
|
||
可以为named client或所有client指定超时处理。OpenFeign使用两个timeout参数：
|
||
- connectTimeout：该属性避免server长时间处理造成的调用方阻塞
|
||
- readTimeout：该属性从连接建立时开始应用，并且当返回响应过慢时被触发（该参数衡量的是从建立连接到返回响应的过程）
|
||
|
||
### Feign Caching
|
||
当使用@EnableCaching之后，一个`CachingCapability`的bean对象将会被配置，Feign client将会识别接口上的`@Cache*`注解。
|
||
```java
|
||
public interface DemoClient {
|
||
|
||
@GetMapping("/demo/{filterParam}")
|
||
@Cacheable(cacheNames = "demo-cache", key = "#keyParam")
|
||
String demoEndpoint(String keyParam, @PathVariable String filterParam);
|
||
}
|
||
```
|
||
|
||
|
||
|