放弃okhttp、httpClient，抉择了这个牛逼的神仙工具！贼爽

在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调用
调用适配器
数据转换器
疾速应用
引入依赖

com.github.lianjiatech
retrofit-spring-boot-starter
2.2.2

定义http接口
接口必须应用@RetrofitClient注解标记！http相干注解可参考官网文档：retrofit官网文档。

@RetrofitClient(baseUrl = "${test.baseUrl}")
public interface HttpApi {

@GET("person")Result<Person> getPerson(@Query("id") Long id);

}
注入应用
将接口注入到其它Service中即可应用！

@Service
public class TestService {

@Autowiredprivate HttpApi httpApi;public void test() {    // 通过httpApi发动http申请}

}
HTTP申请相干注解
HTTP申请相干注解，全副应用了retrofit原生注解。详细信息可参考官网文档：retrofit官网文档，以下是一个简略阐明。

注解分类 反对的注解
你已选中了增加链接的内容申请形式 @GET @HEAD @POST @PUT @DELETE @OPTIONS
申请头 @Header @HeaderMap @Headers
Query参数 @Query @QueryMap @QueryName
path参数 @Path
form-encoded参数 @Field @FieldMap @FormUrlEncoded
文件上传 @Multipart @Part @PartMap
url参数 @Url
配置项阐明
retrofit-spring-boot-starter反对了多个可配置的属性，用来应答不同的业务场景。您能够视状况进行批改，具体阐明如下：

配置 默认值 阐明
enable-log true 启用日志打印
logging-interceptor DefaultLoggingInterceptor 日志打印拦截器
pool
连接池配置
disable-void-return-type false 禁用java.lang.Void返回类型
retry-interceptor DefaultRetryInterceptor 申请重试拦截器
global-converter-factories JacksonConverterFactory 全局转换器工厂
global-call-adapter-factories BodyCallAdapterFactory,ResponseCallAdapterFactory 全局调用适配器工厂
enable-degrade false 是否启用熔断降级
degrade-type sentinel 熔断降级实现形式(目前仅反对Sentinel)
resource-name-parser DefaultResourceNameParser 熔断资源名称解析器，用于解析资源名称

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的静态方法来实现。代码示例如下：

@RetrofitClient(baseUrl = "http://ke.com")
public interface HttpApi3 {

@OkHttpClientBuilderstatic OkHttpClient.Builder okhttpClientBuilder() {    return new OkHttpClient.Builder()            .connectTimeout(1, TimeUnit.SECONDS)            .readTimeout(1, TimeUnit.SECONDS)            .writeTimeout(1, TimeUnit.SECONDS);}@GETResult<Person> getPerson(@Url String url, @Query("id") Long id);

}
办法必须应用@OkHttpClientBuilder注解标记！

注解式拦截器
很多时候，咱们心愿某个接口下的某些http申请执行对立的拦挡解决逻辑。为了反对这个性能，retrofit-spring-boot-starter提供了注解式拦截器，做到了基于url门路的匹配拦挡。应用的步骤次要分为2步：

继承BasePathMatchInterceptor编写拦挡处理器；
接口上应用@Intercept进行标注。如需配置多个拦截器，在接口上标注多个@Intercept注解即可！
上面以给指定申请的url前面拼接timestamp工夫戳为例，介绍下如何应用注解式拦截器。

继承BasePathMatchInterceptor编写拦挡处理器
@Component
public class TimeStampInterceptor extends BasePathMatchInterceptor {

@Overridepublic 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进行标注
@RetrofitClient(baseUrl = "${test.baseUrl}")
@Intercept(handler = TimeStampInterceptor.class, include = {"/api/**"}, exclude = "/api/test/savePerson")
public interface HttpApi {

@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步：

自定义拦挡注解
继承BasePathMatchInterceptor编写拦挡处理器
接口上应用自定义拦挡注解；
例如咱们须要在申请头外面动静退出accessKeyId、accessKeySecret签名信息能力失常发动http申请，这个时候能够自定义一个加签拦截器注解@Sign来实现。上面以自定义@Sign拦挡注解为例进行阐明。

自定义@Sign注解
@Retention(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点须要留神：

自定义拦挡注解必须应用@InterceptMark标记。
注解中必须包含include()、exclude()、handler()属性信息。
实现SignInterceptor
@Component
public class SignInterceptor extends BasePathMatchInterceptor {

private String accessKeyId;private String accessKeySecret;public void setAccessKeyId(String accessKeyId) {    this.accessKeyId = accessKeyId;}public void setAccessKeySecret(String accessKeySecret) {    this.accessKeySecret = accessKeySecret;}@Overridepublic 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
@RetrofitClient(baseUrl = "${test.baseUrl}")
@Sign(accessKeyId = "${test.accessKeyId}", accessKeySecret = "${test.accessKeySecret}", exclude = {"/api/test/person"})
public interface HttpApi {

@GET("person")Result<Person> getPerson(@Query("id") Long id);@POST("savePerson")Result<Person> savePerson(@Body Person person);

}
这样就能在指定url的申请上，主动加上签名信息了。

连接池治理
默认状况下，所有通过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: 50
通过@RetrofitClient的poolName属性来指定应用的连接池。
@RetrofitClient(baseUrl = "${test.baseUrl}", poolName="test1")
public interface HttpApi {

   @GET("person")   Result<Person> getPerson(@Query("id") Long id);

}
日志打印
很多状况下，咱们心愿将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种日志打印策略含意如下：

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:

日志打印拦截器

logging-interceptor: com.github.lianjiatech.retrofit.spring.boot.interceptor.DefaultLoggingInterceptor
申请重试
retrofit-spring-boot-starter反对申请重试性能，只须要在接口或者办法上加上@Retry注解即可。@Retry反对重试次数maxRetries、重试工夫距离intervalMs以及重试规定retryRules配置。重试规定反对三种配置：

RESPONSE_STATUS_NOT_2XX：响应状态码不是2xx时执行重试；
OCCUR_IO_EXCEPTION：产生IO异样时执行重试；
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 陈添明
  */
  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实现。具体来说，反对了熔断资源自发现和注解式降级规定配置。如需应用熔断降级，只须要进行以下操作即可：

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依赖：

com.alibaba.csp sentinel-core 1.6.3

\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;

}
如果利用我的项目已反对通过配置核心配置降级规定，可疏忽注解式配置形式。

1. @RetrofitClient设置fallback或者fallbackFactory (可选)
   如果@RetrofitClient不设置fallback或者fallbackFactory，当触发熔断时，会间接抛出RetrofitBlockException异样。用户能够通过设置fallback或者fallbackFactory来定制熔断时的办法返回值。fallback类必须是以后接口的实现类，fallbackFactory必须是FallbackFactory实现类，泛型参数类型为以后接口类型。另外，fallback和fallbackFactory实例必须配置成Spring容器的Bean。

fallbackFactory绝对于fallback，次要差异在于可能感知每次熔断的异样起因(cause)。参考示例如下：

@Slf4j
@Service
public class HttpDegradeFallback implements HttpDegradeApi {

@Overridepublic Result<Integer> test() {    Result<Integer> fallback = new Result<>();    fallback.setCode(100)            .setMsg("fallback")            .setBody(1000000);    return fallback;}

}
@Slf4j
@Service
public class HttpDegradeFallbackFactory implements FallbackFactory {

/** * Returns an instance of the fallback appropriate for the given cause * * @param cause fallback cause * @return 实现了retrofit接口的实例。an instance that implements the retrofit interface. */@Overridepublic 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对象适配成接口办法的返回值类型。retrofit-spring-boot-starter扩大2种CallAdapterFactory实现：

BodyCallAdapterFactory
默认启用，可通过配置retrofit.enable-body-call-adapter=false敞开
同步执行http申请，将响应体内容适配成接口办法的返回值类型实例。
除了Retrofit.Call、Retrofit.Response、java.util.concurrent.CompletableFuture之外，其它返回类型都能够应用该适配器。
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，间接抛错！
/**
* Call
* 不执行适配解决，间接返回Call对象
* @param id
* @return
*/
@GET("person")
Call<Result> 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客户端框架，已在线上稳固运行一年多，并且曾经有多个内部公司也接入应用。