我终于决定要放弃 okhttp、httpClient,选择了这个牛逼的神仙工具!贼爽
程序员的成长之路
共 3126字,需浏览 7分钟
·
2020-12-17 06:40
阅读本文大概需要 8 分钟。
SpringBoot
项目直接使用okhttp
、httpClient
或者RestTemplate
发起HTTP
请求,既繁琐又不方便统一管理。因此,在这里推荐一个适用于SpringBoot
项目的轻量级HTTP客户端框架retrofit-spring-boot-starter,使用非常简单方便,同时又提供诸多功能增强。目前项目已经更新至2.2.2
版本,并且会持续进行迭代优化。前言
Retrofit
是适用于Android
和Java
且类型安全的HTTP客户端,其最大的特性的是支持通过接口
的方式发起HTTP请求。而spring-boot
是使用最广泛的Java开发框架,但是Retrofit
官方没有支持与spring-boot
框架快速整合,因此我们开发了retrofit-spring-boot-starter
。retrofit-spring-boot-starter
实现了Retrofit
与spring-boot
框架快速整合,并且支持了诸多功能增强,极大简化开发。功能特性
自定义注入OkHttpClient 注解式拦截器 连接池管理 日志打印 请求重试 错误解码器 全局拦截器 熔断降级 微服务之间的HTTP调用 调用适配器 数据转换器
快速使用
引入依赖
public interface HttpApi {
Result
getPerson(Long id); }
注入使用
retrofit:
enable-response-call-adapter: true
# 启用日志打印
enable-log: true
# 连接池配置
pool:
test1:
max-idle-connections: 3
keep-alive-second: 100
test2:
max-idle-connections: 5
keep-alive-second: 50
# 禁用void返回值类型
disable-void-return-type: false
# 日志打印拦截器
logging-interceptor: com.github.lianjiatech.retrofit.spring.boot.interceptor.DefaultLoggingInterceptor
# 请求重试拦截器
retry-interceptor: com.github.lianjiatech.retrofit.spring.boot.retry.DefaultRetryInterceptor
# 全局转换器工厂
global-converter-factories:
- retrofit2.converter.jackson.JacksonConverterFactory
# 全局调用适配器工厂
global-call-adapter-factories:
- com.github.lianjiatech.retrofit.spring.boot.core.BodyCallAdapterFactory
- com.github.lianjiatech.retrofit.spring.boot.core.ResponseCallAdapterFactory
# 是否启用熔断降级
enable-degrade: true
# 熔断降级实现方式
degrade-type: sentinel
# 熔断资源名称解析器
resource-name-parser: com.github.lianjiatech.retrofit.spring.boot.degrade.DefaultResourceNameParser
高级功能
自定义注入OkHttpClient
@RetrofitClient
注解属性动态创建OkHttpClient
对象能够满足大部分使用场景。但是在某些情况下,用户可能需要自定义OkHttpClient
,这个时候,可以在接口上定义返回类型是OkHttpClient.Builder
的静态方法来实现。代码示例如下:public class TimeStampInterceptor extends BasePathMatchInterceptor {
public Response doIntercept(Chain chain) throws IOException {
Request request = chain.request();
HttpUrl url = request.url();
long timestamp = System.currentTimeMillis();
HttpUrl newUrl = url.newBuilder()
.addQueryParameter("timestamp", String.valueOf(timestamp))
.build();
Request newRequest = request.newBuilder()
.url(newUrl)
.build();
return chain.proceed(newRequest);
}
}
接口上使用@Intercept
进行标注
(RetentionPolicy.RUNTIME)
(ElementType.TYPE)
public Sign {
/**
* 密钥key
* 支持占位符形式配置。
*
* @return
*/
String accessKeyId();
/**
* 密钥
* 支持占位符形式配置。
*
* @return
*/
String accessKeySecret();
/**
* 拦截器匹配路径
*
* @return
*/
String[] include() default {"/**"};
/**
* 拦截器排除匹配,排除指定路径拦截
*
* @return
*/
String[] exclude() default {};
/**
* 处理该注解的拦截器类
* 优先从spring容器获取对应的Bean,如果获取不到,则使用反射创建一个!
*
* @return
*/
Class extends BasePathMatchInterceptor> handler() default SignInterceptor.class;
}
自定义拦截注解
有以下2点需要注意:自定义拦截注解
必须使用@InterceptMark
标记。注解中必须包括 include()、exclude()、handler()
属性信息。
实现SignInterceptor
public interface HttpApi {
Result
getPerson(Long id);
Result
savePerson( Person person);}
连接池管理
Retrofit
发送的http请求都会使用max-idle-connections=5 keep-alive-second=300
的默认连接池。当然,我们也可以在配置文件中配置多个自定义的连接池,然后通过@RetrofitClient
的poolName
属性来指定使用。比如我们要让某个接口下的请求全部使用poolName=test1
的连接池,代码实现如下:配置连接池。
public interface HttpApi {
Result
getPerson(Long id); }
日志打印
retrofit.enableLog
配置可以全局控制日志是否开启。针对每个接口,可以通过@RetrofitClient
的enableLog
控制是否开启,通过logLevel
和logStrategy
,可以指定每个接口的日志打印级别以及日志打印策略。retrofit-spring-boot-starter
支持了5种日志打印级别(ERROR
, WARN
, INFO
, DEBUG
, TRACE
),默认INFO
;支持了4种日志打印策略(NONE
, BASIC
, HEADERS
, BODY
),默认BASIC
。4种日志打印策略含义如下:NONE
:No logs.BASIC
:Logs request and response lines.HEADERS
:Logs request and response lines and their respective headers.BODY
:Logs request and response lines and their respective headers and bodies (if present).
retrofit-spring-boot-starter
默认使用了DefaultLoggingInterceptor
执行真正的日志打印功能,其底层就是okhttp
原生的HttpLoggingInterceptor
。当然,你也可以自定义实现自己的日志打印拦截器,只需要继承BaseLoggingInterceptor
(具体可以参考DefaultLoggingInterceptor
的实现),然后在配置文件中进行相关配置即可。retrofit:
# 请求重试拦截器
retry-interceptor: com.github.lianjiatech.retrofit.spring.boot.retry.DefaultRetryInterceptor
错误解码器
HTTP
发生请求错误(包括发生异常或者响应数据不符合预期)的时候,错误解码器可将HTTP
相关信息解码到自定义异常中。你可以在@RetrofitClient
注解的errorDecoder()
指定当前接口的错误解码器,自定义错误解码器需要实现ErrorDecoder
接口:public class SourceInterceptor extends BaseGlobalInterceptor {
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. 开启熔断降级功能
<dependency>
<groupId>com.alibaba.cspgroupId>
<artifactId>sentinel-coreartifactId>
<version>1.6.3version>
dependency>
2. 配置降级规则(可选)
retrofit-spring-boot-starter
支持注解式配置降级规则,通过@Degrade
注解来配置降级规则。@Degrade
注解可以配置在接口或者方法上,配置在方法上的优先级更高。4j
public class HttpDegradeFallback implements HttpDegradeApi {
public Result
test() {Result
fallback = new Result<>(); fallback.setCode(100)
.setMsg("fallback")
.setBody(1000000);
return fallback;
}
}
4j
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.
*/
public HttpDegradeApi create(Throwable cause) {
log.error("触发熔断了! ", cause.getMessage(), cause);
return new HttpDegradeApi() {
public Result
test() {Result
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
即可。public interface ApiCountService {
}
调用适配器和数据转码器
调用适配器
Retrofit
可以通过调用适配器CallAdapterFactory
将Call
对象适配成接口方法的返回值类型。retrofit-spring-boot-starter
扩展2种CallAdapterFactory
实现: ResponseCallAdapterFactory
默认启用,可通过配置 retrofit.enable-response-call-adapter=false
关闭同步执行http请求,将响应体内容适配成 Retrofit.Response
返回。如果方法的返回值类型为 Retrofit.Response
,则可以使用该适配器。
CallAdapterFactory
执行适配处理!加上Retrofit默认的CallAdapterFactory
,可支持多种形式的方法返回值类型:Call
: 不执行适配处理,直接返回Call
对象CompletableFuture
: 将响应体内容适配成CompletableFuture
对象返回Void
: 不关注返回类型可以使用Void
。如果http状态码不是2xx,直接抛错!Response
: 将响应内容适配成Response
对象返回其他任意Java类型:将响应体内容适配成一个对应的Java类型对象返回,如果http状态码不是2xx,直接抛错!
retrofit:
# 全局调用适配器工厂
global-call-adapter-factories:
- com.github.lianjiatech.retrofit.spring.boot.core.BodyCallAdapterFactory
- com.github.lianjiatech.retrofit.spring.boot.core.ResponseCallAdapterFactory
复制代码
@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
@RetrofitClient
注解的converterFactories()
指定当前接口采用的Converter.Factory
,指定的转换器工厂实例依然优先从Spring容器获取。Converter.Factory
没有public
的无参构造器,请手动将其配置成Spring
容器的Bean
对象!总结
retrofit-spring-boot-starter
一个适用于SpringBoot
项目的轻量级HTTP
客户端框架,已在线上稳定运行一年多,并且已经有多个外部公司也接入使用。推荐阅读:
IDEA 上位?不!Eclipse Theia 1.0 发布!
微信扫描二维码,关注我的公众号
朕已阅
评论