很多情况下,我们希望将http请求日志记录下来。通过retrofit.enableLog配置可以全局控制日志是否开启。针对每个接口,可以通过@RetrofitClient的enableLog控制是否开启,通过logLevel和logStrategy,可以指定每个接口的日志打印级别以及日志打印策略。retrofit-spring-boot-starter支持了5种日志打印级别(ERROR,WARN,INFO,DEBUG,TRACE),默认INFO;支持了4种日志打印策略(NONE,BASIC,HEADERS,BODY),默认BASIC。4种日志打印策略含义如下:
retrofit-spring-boot-starter默认使用了DefaultLoggingInterceptor执行真正的日志打印功能,其底层就是okhttp原生的HttpLoggingInterceptor。当然,你也可以自定义实现自己的日志打印拦截器,只需要继承BaseLoggingInterceptor(具体可以参考DefaultLoggingInterceptor的实现),然后在配置文件中进行相关配置即可。
retrofit:
#日志打印拦截器
logging-interceptor: com.github.lianjiatech.retrofit.spring.boot.interceptor.DefaultLoggingInterceptor
retrofit-spring-boot-starter支持请求重试功能,只需要在接口或者方法上加上@Retry注解即可。@Retry支持重试次数maxRetries、重试时间间隔intervalMs以及重试规则retryRules配置。重试规则支持三种配置:
默认响应状态码不是2xx或者发生IO异常时自动进行重试。需要的话,你也可以继承BaseRetryInterceptor实现自己的请求重试拦截器,然后将其配置上去。
retrofit:
# 请求重试拦截器
retry-interceptor: com.github.lianjiatech.retrofit.spring.boot.retry.DefaultRetryInterceptor
在HTTP发生请求错误(包括发生异常或者响应数据不符合预期)的时候,错误解码器可将HTTP相关信息解码到自定义异常中。你可以在@RetrofitClient注解的errorDecoder()指定当前接口的错误解码器,自定义错误解码器需要实现ErrorDecoder接口:
/**
* 错误解码器。ErrorDecoder.
* 当请求发生异常或者收到无效响应结果的时候,将HTTP相关信息解码到异常中,无效响应由业务自己判断
*
* When an exception occurs in the request or an invalid response result is received, the HTTP related information is decoded into the exception,
* and the invalid response is determined by the business itself.
*
* @author 陈添明
*/
public interface ErrorDecoder {
/**
* 当无效响应的时候,将HTTP信息解码到异常中,无效响应由业务自行判断。
* When the response is invalid, decode the HTTP information into the exception, invalid response is determined by business.
*
* @param request request
* @param response response
* @return If it returns null, the processing is ignored and the processing continues with the original response.
*/
default RuntimeException invalidRespDecode(Request request, Response response) {
if (!response.isSuccessful()) {
throw RetrofitException.errorStatus(request, response);
}
return null;
}
/**
* 当请求发生IO异常时,将HTTP信息解码到异常中。
* When an IO exception occurs in the request, the HTTP information is decoded into the exception.
*
* @param request request
* @param cause IOException
* @return RuntimeException
*/
default RuntimeException ioExceptionDecode(Request request, IOException cause) {
return RetrofitException.errorExecuting(request, cause);
}
/**
* 当请求发生除IO异常之外的其它异常时,将HTTP信息解码到异常中。
* When the request has an exception other than the IO exception, the HTTP information is decoded into the exception.
*
* @param request request
* @param cause Exception
* @return RuntimeException
*/
default RuntimeException exceptionDecode(Request request, Exception cause) {
return RetrofitException.errorUnknown(request, cause);
}
}
如果我们需要对整个系统的的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实现。具体来说,支持了熔断资源自发现和注解式降级规则配置。如需使用熔断降级,只需要进行以下操作即可:
默认情况下,熔断降级功能是关闭的,需要设置相应的配置项来开启熔断降级功能:
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>
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;
}
[quote color="primary"]如果应用项目已支持通过配置中心配置降级规则,可忽略注解式配置方式。[/quote]
如果@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;
}
}
}
为了能够使用微服务调用,需要进行如下配置:
用户可以自行实现ServiceInstanceChooser接口,完成服务实例的选取逻辑,并将其配置成Spring容器的Bean。对于Spring Cloud应用,retrofit-spring-boot-starter提供了SpringCloudServiceInstanceChooser实现,用户只需将其配置成Spring的Bean即可。
@Bean
@Autowired
public ServiceInstanceChooser serviceInstanceChooser(LoadBalancerClient loadBalancerClient) {
return new SpringCloudServiceInstanceChooser(loadBalancerClient);
}
@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实现:
Retrofit自动根据方法返回值类型选用对应的CallAdapterFactory执行适配处理!加上Retrofit默认的CallAdapterFactory,可支持多种形式的方法返回值类型:
* 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:
retrofit-spring-boot-starter支持通过retrofit.global-converter-factories配置全局数据转换器工厂,转换器工厂实例优先从Spring容器获取,如果没有获取到,则反射创建。 默认的全局数据转换器工厂是retrofit2.converter.jackson.JacksonConverterFactory,你可以直接通过spring.jackson.*配置jackson序列化规则,配置可参考:Customize the Jackson ObjectMapper。 [quote color="primary"]https://docs.spring.io/spring-boot/docs/2.1.5.RELEASE/reference/htmlsingle/#howto-customize-the-jackson-objectmapper[/quote]
retrofit:
# 全局调用适配器工厂
global-call-adapter-factories:
- com.github.lianjiatech.retrofit.spring.boot.core.BodyCallAdapterFactory
- com.github.lianjiatech.retrofit.spring.boot.core.ResponseCallAdapterFactory
针对每个Java接口,还可以通过@RetrofitClient注解的converterFactories()指定当前接口采用的Converter.Factory,指定的转换器工厂实例依然优先从Spring容器获取。
注意:如果Converter.Factory没有public的无参构造器,请手动将其配置成Spring容器的Bean对象!
retrofit-spring-boot-starter一个适用于SpringBoot项目的轻量级HTTP客户端框架,已在线上稳定运行一年多,并且已经有多个外部公司也接入使用。有兴趣的朋友可以尝试一下