全局拦截器
全局应用拦截器
如果我们需要对整个系统的的http请求执行统一的拦截处理,可以自定义实现全局拦截器BaseGlobalInterceptor
, 并配置成spring
容器中的bean
!例如我们需要在整个系统发起的http请求,都带上来源信息。
@Component public class SourceInterceptor extends BaseGlobalInterceptor { @Override public Response doIntercept(Chain chain) throws IOException { Request request = chain.request(); Request newReq = request.newBuilder() .addHeader("source", "test") .build(); return chain.proceed(newReq); } }
全局网络拦截器
只需要实现NetworkInterceptor
接口 并配置成spring
容器中的bean
就支持自动织入全局网络拦截器。
熔断降级
在分布式服务架构中,对不稳定的外部服务进行熔断降级是保证服务高可用的重要措施之一。由于外部服务的稳定性是不能保证的,当外部服务不稳定时,响应时间会变长。相应地,调用方的响应时间也会变长,线程会产生堆积,最终可能耗尽调用方的线程池,导致整个服务不可用。因此我们需要对不稳定的弱依赖服务调用进行熔断降级,暂时切断不稳定调用,避免局部不稳定导致整体服务雪崩。
retrofit-spring-boot-starter
支持熔断降级功能,底层基于Sentinel实现。具体来说,支持了熔断资源自发现 和注解式降级规则配置 。如需使用熔断降级,只需要进行以下操作即可:
1. 开启熔断降级功能
默认情况下,熔断降级功能是关闭的,需要设置相应的配置项来开启熔断降级功能 :
retrofit: # 是否启用熔断降级 enable-degrade: true # 熔断降级实现方式(目前仅支持Sentinel) degrade-type: sentinel # 资源名称解析器 resource-name-parser: com.github.lianjiatech.retrofit.spring.boot.degrade.DefaultResourceNameParser
资源名称解析器用于实现用户自定义资源名称,默认配置是DefaultResourceNameParser
,对应的资源名称格式为HTTP_OUT:GET:http://localhost:8080/api/degrade/test
。用户可以继承BaseResourceNameParser
类实现自己的资源名称解析器。
另外,由于熔断降级功能是可选的,因此启用熔断降级需要用户自行引入Sentinel依赖 :
<dependency> <groupId>com.alibaba.csp</groupId> <artifactId>sentinel-core</artifactId> <version>1.6.3</version> </dependency>
2. 配置降级规则(可选)
retrofit-spring-boot-starter
支持注解式配置降级规则,通过@Degrade
注解来配置降级规则 。@Degrade
注解可以配置在接口或者方法上,配置在方法上的优先级更高。
@Retention(RetentionPolicy.RUNTIME) @Target({ElementType.METHOD, ElementType.TYPE}) @Documented public @interface Degrade { /** * RT threshold or exception ratio threshold count. */ double count(); /** * Degrade recover timeout (in seconds) when degradation occurs. */ int timeWindow() default 5; /** * Degrade strategy (0: average RT, 1: exception ratio). */ DegradeStrategy degradeStrategy() default DegradeStrategy.AVERAGE_RT; }
如果应用项目已支持通过配置中心配置降级规则,可忽略注解式配置方式 。
3. @RetrofitClient设置fallback或者fallbackFactory (可选)
如果@RetrofitClient
不设置fallback
或者fallbackFactory
,当触发熔断时,会直接抛出RetrofitBlockException
异常。用户可以通过设置fallback
或者fallbackFactory
来定制熔断时的方法返回值 。fallback
类必须是当前接口的实现类,fallbackFactory
必须是FallbackFactory<T>
实现类,泛型参数类型为当前接口类型。另外,fallback
和fallbackFactory
实例必须配置成Spring
容器的Bean
。
fallbackFactory
相对于fallback
,主要差别在于能够感知每次熔断的异常原因(cause) 。参考示例如下:
@Slf4j @Service public class HttpDegradeFallback implements HttpDegradeApi { @Override public Result<Integer> test() { Result<Integer> fallback = new Result<>(); fallback.setCode(100) .setMsg("fallback") .setBody(1000000); return fallback; } } @Slf4j @Service public class HttpDegradeFallbackFactory implements FallbackFactory<HttpDegradeApi> { /** * Returns an instance of the fallback appropriate for the given cause * * @param cause fallback cause * @return 实现了retrofit接口的实例。an instance that implements the retrofit interface. */ @Override public HttpDegradeApi create(Throwable cause) { log.error("触发熔断了! ", cause.getMessage(), cause); return new HttpDegradeApi() { @Override public Result<Integer> test() { Result<Integer> fallback = new Result<>(); fallback.setCode(100) .setMsg("fallback") .setBody(1000000); return fallback; } } }
微服务之间的HTTP调用
为了能够使用微服务调用,需要进行如下配置:
配置ServiceInstanceChooser
为Spring
容器Bean
用户可以自行实现ServiceInstanceChooser
接口,完成服务实例的选取逻辑,并将其配置成Spring
容器的Bean
。对于Spring Cloud
应用,retrofit-spring-boot-starter
提供了SpringCloudServiceInstanceChooser
实现,用户只需将其配置成Spring
的Bean
即可。
@Bean @Autowired public ServiceInstanceChooser serviceInstanceChooser(LoadBalancerClient loadBalancerClient) { return new SpringCloudServiceInstanceChooser(loadBalancerClient); }
使用@Retrofit
的serviceId
和path
属性,可以实现微服务之间的HTTP调用
@RetrofitClient(serviceId = "${jy-helicarrier-api.serviceId}", path = "/m/count", errorDecoder = HelicarrierErrorDecoder.class) @Retry public interface ApiCountService { }
调用适配器和数据转码器
调用适配器
Retrofit
可以通过调用适配器CallAdapterFactory
将Call<T>
对象适配成接口方法的返回值类型。retrofit-spring-boot-starter
扩展2种CallAdapterFactory
实现:
BodyCallAdapterFactory
- 默认启用,可通过配置
retrofit.enable-body-call-adapter=false
关闭 - 同步执行http请求,将响应体内容适配成接口方法的返回值类型实例。
- 除了
Retrofit.Call<T>
、Retrofit.Response<T>
、java.util.concurrent.CompletableFuture<T>
之外,其它返回类型都可以使用该适配器。
ResponseCallAdapterFactory
- 默认启用,可通过配置
retrofit.enable-response-call-adapter=false
关闭 - 同步执行http请求,将响应体内容适配成
Retrofit.Response<T>
返回。 - 如果方法的返回值类型为
Retrofit.Response<T>
,则可以使用该适配器。
Retrofit自动根据方法返回值类型选用对应的CallAdapterFactory
执行适配处理!加上Retrofit默认的CallAdapterFactory
,可支持多种形式的方法返回值类型:
Call<T>
: 不执行适配处理,直接返回Call<T>
对象CompletableFuture<T>
: 将响应体内容适配成CompletableFuture<T>
对象返回Void
: 不关注返回类型可以使用Void
。如果http状态码不是2xx,直接抛错!Response<T>
: 将响应内容适配成Response<T>
对象返回- 其他任意Java类型:将响应体内容适配成一个对应的Java类型对象返回,如果http状态码不是2xx,直接抛错!
/** * Call<T> * 不执行适配处理,直接返回Call<T>对象 * @param id * @return */ @GET("person") Call<Result<Person>> getPersonCall(@Query("id") Long id); /** * CompletableFuture<T> * 将响应体内容适配成CompletableFuture<T>对象返回 * @param id * @return */ @GET("person") CompletableFuture<Result<Person>> getPersonCompletableFuture(@Query("id") Long id); /** * Void * 不关注返回类型可以使用Void。如果http状态码不是2xx,直接抛错! * @param id * @return */ @GET("person") Void getPersonVoid(@Query("id") Long id); /** * Response<T> * 将响应内容适配成Response<T>对象返回 * @param id * @return */ @GET("person") Response<Result<Person>> getPersonResponse(@Query("id") Long id); /** * 其他任意Java类型 * 将响应体内容适配成一个对应的Java类型对象返回,如果http状态码不是2xx,直接抛错! * @param id * @return */ @GET("person") Result<Person> getPerson(@Query("id") Long id);
我们也可以通过继承CallAdapter.Factory
扩展实现自己的CallAdapter
!
retrofit-spring-boot-starter
支持通过retrofit.global-call-adapter-factories
配置全局调用适配器工厂,工厂实例优先从Spring容器获取,如果没有获取到,则反射创建。默认的全局调用适配器工厂是[BodyCallAdapterFactory, ResponseCallAdapterFactory]
!
retrofit: # 全局调用适配器工厂 global-call-adapter-factories: - com.github.lianjiatech.retrofit.spring.boot.core.BodyCallAdapterFactory - com.github.lianjiatech.retrofit.spring.boot.core.ResponseCallAdapterFactory
针对每个Java接口,还可以通过@RetrofitClient
注解的callAdapterFactories()
指定当前接口采用的CallAdapter.Factory
,指定的工厂实例依然优先从Spring容器获取。
注意:如果CallAdapter.Factory
没有public
的无参构造器,请手动将其配置成Spring
容器的Bean
对象 !
数据转码器
Retrofit
使用Converter
将@Body
注解标注的对象转换成请求体,将响应体数据转换成一个Java
对象,可以选用以下几种Converter
:
- Gson: com.squareup.Retrofit:converter-gson
- Jackson: com.squareup.Retrofit:converter-jackson
- Moshi: com.squareup.Retrofit:converter-moshi
- Protobuf: com.squareup.Retrofit:converter-protobuf
- Wire: com.squareup.Retrofit:converter-wire
- Simple XML: com.squareup.Retrofit:converter-simplexml
- JAXB: com.squareup.retrofit2:converter-jaxb
retrofit-spring-boot-starter
支持通过retrofit.global-converter-factories
配置全局数据转换器工厂,转换器工厂实例优先从Spring容器获取,如果没有获取到,则反射创建。默认的全局数据转换器工厂是retrofit2.converter.jackson.JacksonConverterFactory
,你可以直接通过spring.jackson.*
配置jackson
序列化规则,配置可参考Customize the Jackson ObjectMapper!
retrofit: # 全局转换器工厂 global-converter-factories: - retrofit2.converter.jackson.JacksonConverterFactory
针对每个Java接口,还可以通过@RetrofitClient
注解的converterFactories()
指定当前接口采用的Converter.Factory
,指定的转换器工厂实例依然优先从Spring容器获取。
注意:如果Converter.Factory
没有public
的无参构造器,请手动将其配置成Spring
容器的Bean
对象 !
总结
retrofit-spring-boot-starter
一个适用于SpringBoot
项目的轻量级HTTP
客户端框架,已在线上稳定运行一年多,并且已经有多个外部公司也接入使用。
- END -