我终于决定要放弃 okhttp、httpClient,选择了这个牛逼的神仙工具!贼爽

程序员的成长之路

共 3126字,需浏览 7分钟

 ·

2020-12-17 06:40

程序员的成长之路
互联网/程序员/技术/资料共享 
关注


阅读本文大概需要 8 分钟。

SpringBoot项目直接使用okhttphttpClient或者RestTemplate发起HTTP请求,既繁琐又不方便统一管理。因此,在这里推荐一个适用于SpringBoot项目的轻量级HTTP客户端框架retrofit-spring-boot-starter,使用非常简单方便,同时又提供诸多功能增强。目前项目已经更新至2.2.2版本,并且会持续进行迭代优化。

前言

Retrofit是适用于AndroidJava且类型安全的HTTP客户端,其最大的特性的是支持通过接口的方式发起HTTP请求。而spring-boot是使用最广泛的Java开发框架,但是Retrofit官方没有支持与spring-boot框架快速整合,因此我们开发了retrofit-spring-boot-starter
retrofit-spring-boot-starter实现了Retrofitspring-boot框架快速整合,并且支持了诸多功能增强,极大简化开发
?项目持续优化迭代。

功能特性

  • 自定义注入OkHttpClient
  • 注解式拦截器
  • 连接池管理
  • 日志打印
  • 请求重试
  • 错误解码器
  • 全局拦截器
  • 熔断降级
  • 微服务之间的HTTP调用
  • 调用适配器
  • 数据转换器

快速使用

引入依赖

@RetrofitClient(baseUrl = "${test.baseUrl}")public interface HttpApi {
@GET("person") Result getPerson(@Query("id") Long id);}

注入使用

将接口注入到其它Service中即可使用!
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的静态方法来实现。代码示例如下:
@Componentpublic class TimeStampInterceptor extends BasePathMatchInterceptor {
@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进行标注
@Retention(RetentionPolicy.RUNTIME)@Target(ElementType.TYPE)@Documented@InterceptMarkpublic @interface Sign {    /**     * 密钥key     * 支持占位符形式配置。     *     * @return     */    String accessKeyId();
/** * 密钥 * 支持占位符形式配置。 * * @return */ String accessKeySecret();
/** * 拦截器匹配路径 * * @return */ String[] include() default {"/**"};
/** * 拦截器排除匹配,排除指定路径拦截 * * @return */ String[] exclude() default {};
/** * 处理该注解的拦截器类 * 优先从spring容器获取对应的Bean,如果获取不到,则使用反射创建一个! * * @return */ Classextends BasePathMatchInterceptor> handler() default SignInterceptor.class;}
扩展自定义拦截注解有以下2点需要注意:
  1. 自定义拦截注解必须使用 @InterceptMark标记。
  2. 注解中必须包括 include()、exclude()、handler()属性信息。
实现SignInterceptor
@RetrofitClient(baseUrl = "${test.baseUrl}")@Sign(accessKeyId = "${test.accessKeyId}", accessKeySecret = "${test.accessKeySecret}", exclude = {"/api/test/person"})public interface HttpApi {
@GET("person") Result getPerson(@Query("id") Long id);
@POST("savePerson") Result savePerson(@Body Person person);}
这样就能在指定url的请求上,自动加上签名信息了。

连接池管理

默认情况下,所有通过Retrofit发送的http请求都会使用max-idle-connections=5 keep-alive-second=300的默认连接池。当然,我们也可以在配置文件中配置多个自定义的连接池,然后通过@RetrofitClientpoolName属性来指定使用。比如我们要让某个接口下的请求全部使用poolName=test1的连接池,代码实现如下:
  1. 配置连接池。
   @RetrofitClient(baseUrl = "${test.baseUrl}", poolName="test1")   public interface HttpApi {          @GET("person")       Result getPerson(@Query("id") Long id);   }

日志打印

很多情况下,我们希望将http请求日志记录下来。通过retrofit.enableLog配置可以全局控制日志是否开启。针对每个接口,可以通过@RetrofitClientenableLog控制是否开启,通过logLevellogStrategy,可以指定每个接口的日志打印级别以及日志打印策略。retrofit-spring-boot-starter支持了5种日志打印级别(ERRORWARNINFODEBUGTRACE),默认INFO;支持了4种日志打印策略(NONEBASICHEADERSBODY),默认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:  # 请求重试拦截器  retry-interceptor: com.github.lianjiatech.retrofit.spring.boot.retry.DefaultRetryInterceptor

错误解码器

HTTP发生请求错误(包括发生异常或者响应数据不符合预期)的时候,错误解码器可将HTTP相关信息解码到自定义异常中。你可以在@RetrofitClient注解的errorDecoder()指定当前接口的错误解码器,自定义错误解码器需要实现ErrorDecoder接口:
@Componentpublic 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. 开启熔断降级功能
默认情况下,熔断降级功能是关闭的,需要设置相应的配置项来开启熔断降级功能
<dependency>    <groupId>com.alibaba.cspgroupId>    <artifactId>sentinel-coreartifactId>    <version>1.6.3version>dependency>
2. 配置降级规则(可选)
retrofit-spring-boot-starter支持注解式配置降级规则,通过@Degrade注解来配置降级规则@Degrade注解可以配置在接口或者方法上,配置在方法上的优先级更高。
@Slf4j@Servicepublic class HttpDegradeFallback implements HttpDegradeApi {
@Override public Result test() { Result fallback = new Result<>(); fallback.setCode(100) .setMsg("fallback") .setBody(1000000); return fallback; }}@Slf4j@Servicepublic 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 test() { Result fallback = new Result<>(); fallback.setCode(100) .setMsg("fallback") .setBody(1000000); return fallback; } }}

微服务之间的HTTP调用

为了能够使用微服务调用,需要进行如下配置:
配置ServiceInstanceChooserSpring容器Bean
用户可以自行实现ServiceInstanceChooser接口,完成服务实例的选取逻辑,并将其配置成Spring容器的Bean。对于Spring Cloud应用,retrofit-spring-boot-starter提供了SpringCloudServiceInstanceChooser实现,用户只需将其配置成SpringBean即可。
@RetrofitClient(serviceId = "${jy-helicarrier-api.serviceId}", path = "/m/count", errorDecoder = HelicarrierErrorDecoder.class)@Retrypublic interface ApiCountService {
}

调用适配器和数据转码器

调用适配器

Retrofit可以通过调用适配器CallAdapterFactoryCall对象适配成接口方法的返回值类型。retrofit-spring-boot-starter扩展2种CallAdapterFactory实现:
 ResponseCallAdapterFactory
  • 默认启用,可通过配置 retrofit.enable-response-call-adapter=false关闭
  • 同步执行http请求,将响应体内容适配成 Retrofit.Response返回。
  • 如果方法的返回值类型为 Retrofit.Response,则可以使用该适配器。
Retrofit自动根据方法返回值类型选用对应的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复制代码
针对每个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客户端框架,已在线上稳定运行一年多,并且已经有多个外部公司也接入使用。

推荐阅读:

干掉 RESTful API !

IDEA 上位?不!Eclipse Theia 1.0 发布!

5T技术资源大放送!包括但不限于:C/C++,Linux,Python,Java,PHP,人工智能,单片机,树莓派,等等。在公众号内回复「2048」,即可免费获取!!

微信扫描二维码,关注我的公众号

朕已阅 

浏览 17
点赞
评论
收藏
分享

手机扫一扫分享

分享
举报
评论
图片
表情
推荐
点赞
评论
收藏
分享

手机扫一扫分享

分享
举报