推荐一款 Spring Boot 的 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调用 调用适配器 数据转换器
引入依赖
<dependency>
<groupId>com.github.lianjiatech</groupId>
<artifactId>retrofit-spring-boot-starter</artifactId>
<version>
2.2.2</version>
</dependency>
定义http接口
@RetrofitClient
注解标记 !http相关注解可参考官方文档:retrofit官方文档。(baseUrl =
"${test.baseUrl}")
publicinterfaceHttpApi
{
@GET
(
"person")
Result<Person> getPerson(@Query("id") Long id)
;
}
注入使用
publicclassTestService
{
@Autowired
private
HttpApi httpApi;
publicvoidtest()
{
// 通过httpApi发起http请求
}
}
HTTP请求相关注解
HTTP
请求相关注解,全部使用了retrofit
原生注解。详细信息可参考官方文档:retrofit官方文档 ,以下是一个简单说明。 注解分类 | 支持的注解 |
@GET @HEAD @POST @PUT @DELETE @OPTIONS | |
@Header @HeaderMap @Headers | |
@Query @QueryMap @QueryName | |
@Path | |
@Field @FieldMap @FormUrlEncoded | |
@Multipart @Part @PartMap | |
@Url |
配置项说明
retrofit-spring-boot-starter
支持了多个可配置的属性,用来应对不同的业务场景。您可以视情况进行修改,具体说明如下: 配置 | 默认值 | 说明 |
yml
配置方式: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
的静态方法来实现。代码示例如下:(baseUrl =
"http://ke.com")
publicinterfaceHttpApi3
{
@OkHttpClientBuilder
static
OkHttpClient.
Builder okhttpClientBuilder(){
returnnew
OkHttpClient.Builder()
.connectTimeout(
1, TimeUnit.SECONDS)
.readTimeout(
1, TimeUnit.SECONDS)
.writeTimeout(
1, TimeUnit.SECONDS);
}
@GET
Result<Person> getPerson(@Url String url, @Query("id") Long id)
;
}
方法必须使用 @OkHttpClientBuilder
注解标记!
注解式拦截器
retrofit-spring-boot-starter
提供了注解式拦截器 ,做到了基于url路径的匹配拦截 。使用的步骤主要分为2步:1. 继承
BasePathMatchInterceptor
编写拦截处理器;2. 接口上使用
@Intercept
进行标注。如需配置多个拦截器,在接口上标注多个@Intercept
注解即可!BasePathMatchInterceptor
编写拦截处理器publicclassTimeStampInterceptorextendsBasePathMatchInterceptor
{
@Override
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
进行标注
(baseUrl =
"${test.baseUrl}")
@Intercept
(handler = TimeStampInterceptor
.class, include= {
"/api/**"}, exclude =
"/api/test/savePerson")
publicinterfaceHttpApi
{
@GET
(
"person")
Result<Person> getPerson(@Query("id") Long id)
;
@POST
(
"savePerson")
Result<Person> savePerson(@Body Person person)
;
}
上面的
@Intercept
配置表示:拦截HttpApi
接口下/api/**
路径下(排除/api/test/savePerson
)的请求,拦截处理器使用TimeStampInterceptor
。扩展注解式拦截器
自定义拦截注解
必须使用@InterceptMark
标记,并且注解中必须包括include()、exclude()、handler()
属性信息 。使用的步骤主要分为3步:1. 自定义拦截注解
2. 继承
BasePathMatchInterceptor
编写拦截处理器3. 接口上使用自定义拦截注解;
accessKeyId
、accessKeySecret
签名信息才能正常发起http请求 ,这个时候可以自定义一个加签拦截器注解@Sign
来实现 。下面以自定义@Sign
拦截注解为例进行说明。@Sign
注解(RetentionPolicy.RUNTIME)
@Target
(ElementType.TYPE)
@Documented
@InterceptMark
public@interface
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点需要注意:1.自定义拦截注解
必须使用@InterceptMark
标记。2. 注解中必须包括
include()、exclude()、handler()
属性信息。实现SignInterceptor
publicclassSignInterceptorextendsBasePathMatchInterceptor
{
private
String accessKeyId;
private
String accessKeySecret;
publicvoidsetAccessKeyId(String accessKeyId)
{
this
.accessKeyId = accessKeyId;
}
publicvoidsetAccessKeySecret(String accessKeySecret)
{
this
.accessKeySecret = accessKeySecret;
}
@Override
public Response doIntercept(Chain chain)throws IOException
{
Request request = chain.request();
Request newReq = request.newBuilder()
.addHeader(
"accessKeyId", accessKeyId)
.addHeader(
"accessKeySecret", accessKeySecret)
.build();
return
chain.proceed(newReq);
}
}
accessKeyId
和accessKeySecret
字段值会依据@Sign
注解的accessKeyId()
和accessKeySecret()
值自动注入,如果@Sign
指定的是占位符形式的字符串,则会取配置属性值进行注入 。另外,accessKeyId
和accessKeySecret
字段必须提供setter
方法 。@Sign
(baseUrl =
"${test.baseUrl}")
@Sign
(accessKeyId =
"${test.accessKeyId}", accessKeySecret =
"${test.accessKeySecret}", exclude = {
"/api/test/person"})
publicinterfaceHttpApi
{
@GET
(
"person")
Result<Person> getPerson(@Query("id") Long id)
;
@POST
(
"savePerson")
Result<Person> savePerson(@Body Person person)
;
}
Retrofit
发送的http请求都会使用max-idle-connections=5 keep-alive-second=300
的默认连接池。当然,我们也可以在配置文件中配置多个自定义的连接池,然后通过@RetrofitClient
的poolName
属性来指定使用。比如我们要让某个接口下的请求全部使用poolName=test1
的连接池,代码实现如下:配置连接池。
retrofit:
# 连接池配置
pool:
test1:
max-idle-connections:
3 keep-alive-second:
100 test2:
max-idle-connections:
5 keep-alive-second:
502. 通过
@RetrofitClient
的poolName
属性来指定使用的连接池。(baseUrl =
"${test.baseUrl}", poolName=
"test1")
publicinterfaceHttpApi
{
@GET
(
"person")
Result<Person> getPerson(@Query("id") 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种日志打印策略含义如下:1. NONE
:No logs.2. BASIC
:Logs request and response lines.3. HEADERS
:Logs request and response lines and their respective headers.4. BODY
:Logs request and response lines and their respective headers and bodies (if present).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
配置 。1. RESPONSE_STATUS_NOT_2XX
:响应状态码不是2xx
时执行重试;2. OCCUR_IO_EXCEPTION
:发生IO异常时执行重试;3. OCCUR_EXCEPTION
:发生任意异常时执行重试;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 陈添明
*/
publicinterfaceErrorDecoder
{
/**
* 当无效响应的时候,将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);
}
returnnull
;
}
/**
* 当请求发生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);
}
}
全局拦截器
全局应用拦截器
BaseGlobalInterceptor
, 并配置成spring
容器中的bean
!例如我们需要在整个系统发起的http请求,都带上来源信息。publicclassSourceInterceptorextendsBaseGlobalInterceptor
{
@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
类实现自己的资源名称解析器。<dependency>
<groupId>com.alibaba.csp</groupId>
<artifactId>sentinel-core</artifactId>
<version>
1.6.3</version>
</dependency>
2. 配置降级规则(可选)
retrofit-spring-boot-starter
支持注解式配置降级规则,通过@Degrade
注解来配置降级规则 。@Degrade
注解可以配置在接口或者方法上,配置在方法上的优先级更高。(RetentionPolicy.RUNTIME)
@Target
({ElementType.METHOD, ElementType.TYPE})
@Documented
public@interface
Degrade {
/**
* RT threshold or exception ratio threshold count.
*/
doublecount()
;
/**
* Degrade recover timeout (in seconds) when degradation occurs.
*/
inttimeWindow()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) 。参考示例如下:4j
@Service
publicclassHttpDegradeFallbackimplementsHttpDegradeApi
{
@Override
public Result<Integer> test()
{
Result<Integer> fallback =
new Result<>();
fallback.setCode(
100)
.setMsg(
"fallback")
.setBody(
1000000);
return
fallback;
}
}
@Slf
4j
@Service
publicclassHttpDegradeFallbackFactoryimplementsFallbackFactory<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);
returnnew
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
即可。@Autowired
public ServiceInstanceChooser serviceInstanceChooser(LoadBalancerClient loadBalancerClient)
{
returnnew
SpringCloudServiceInstanceChooser(loadBalancerClient);
}
使用@Retrofit
的serviceId
和path
属性,可以实现微服务之间的HTTP调用
(serviceId =
"${jy-helicarrier-api.serviceId}", path =
"/m/count", errorDecoder = HelicarrierErrorDecoder
.
class)
@
RetrypublicinterfaceApiCountService
{
}
调用适配器和数据转码器
调用适配器
Retrofit
可以通过调用适配器CallAdapterFactory
将Call<T>
对象适配成接口方法的返回值类型。retrofit-spring-boot-starter
扩展2种CallAdapterFactory
实现:默认启用,可通过配置 retrofit.enable-body-call-adapter=false
关闭同步执行http请求,将响应体内容适配成接口方法的返回值类型实例。 除了 Retrofit.Call<T>
、Retrofit.Response<T>
、java.util.concurrent.CompletableFuture<T>
之外,其它返回类型都可以使用该适配器。
默认启用,可通过配置 retrofit.enable-response-call-adapter=false
关闭同步执行http请求,将响应体内容适配成 Retrofit.Response<T>
返回。如果方法的返回值类型为 Retrofit.Response<T>
,则可以使用该适配器。
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]
!etrofit:
# 全局调用适配器工厂
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
客户端框架,已在线上稳定运行两年多,并且已经有多个外部公司也接入使用。来源:juejin.cn/post/6898485806587969544
关注公众号:Java后端编程,回复下面关键字
要Java学习完整路线,回复 路线
缺Java入门视频,回复: 视频
要Java面试经验,回复 面试
缺Java项目,回复: 项目
进Java粉丝群: 加群
PS:如果觉得我的分享不错,欢迎大家随手点赞、在看。
请备注:666,不然不通过~
最近好文
关键词
拦截器
属性
参数
类型
用户
最新评论
推荐文章
作者最新文章
你可能感兴趣的文章
Copyright Disclaimer: The copyright of contents (including texts, images, videos and audios) posted above belong to the User who shared or the third-party website which the User shared from. If you found your copyright have been infringed, please send a DMCA takedown notice to [email protected]. For more detail of the source, please click on the button "Read Original Post" below. For other communications, please send to [email protected].
版权声明:以上内容为用户推荐收藏至CareerEngine平台,其内容(含文字、图片、视频、音频等)及知识版权均属用户或用户转发自的第三方网站,如涉嫌侵权,请通知[email protected]进行信息删除。如需查看信息来源,请点击“查看原文”。如需洽谈其它事宜,请联系[email protected]。
版权声明:以上内容为用户推荐收藏至CareerEngine平台,其内容(含文字、图片、视频、音频等)及知识版权均属用户或用户转发自的第三方网站,如涉嫌侵权,请通知[email protected]进行信息删除。如需查看信息来源,请点击“查看原文”。如需洽谈其它事宜,请联系[email protected]。