在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調用
調用適配器
數據轉換器
快速使用
引入依賴
定義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 {
@Autowired
private 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 {
@OkHttpClientBuilder
static OkHttpClient.Builder okhttpClientBuilder() {
return new 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注解標記！
注解式攔截器
很多時候，我們希望某個接口下的某些http請求執行統一的攔截處理邏輯。為了支持這個功能，retrofit-spring-boot-starter提供了注解式攔截器，做到了基於url路徑的匹配攔截。使用的步驟主要分為2步：
繼承BasePathMatchInterceptor編寫攔截處理器；
接口上使用@Intercept進行標注。如需配置多個攔截器，在接口上標注多個@Intercept注解即可！
下面以給指定請求的url后面拼接timestamp時間戳為例，介紹下如何使用注解式攔截器。
繼承BasePathMatchInterceptor編寫攔截處理器
@Component
public 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進行標注
@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;
}
@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
@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實現。具體來說，支持了熔斷資源自發現和注解式降級規則配置。如需使用熔斷降級，只需要進行以下操作即可：
- 開啟熔斷降級功能
默認情況下，熔斷降級功能是關閉的，需要設置相應的配置項來開啟熔斷降級功能：
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依賴：
@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;
}
如果應用項目已支持通過配置中心配置降級規則，可忽略注解式配置方式。
- @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 {
@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
/**
* 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;
}
}
}
微服務之間的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
BodyCallAdapterFactory
默認啟用，可通過配置retrofit.enable-body-call-adapter=false關閉
同步執行http請求，將響應體內容適配成接口方法的返回值類型實例。
除了Retrofit.Call
ResponseCallAdapterFactory
默認啟用，可通過配置retrofit.enable-response-call-adapter=false關閉
同步執行http請求，將響應體內容適配成Retrofit.Response
如果方法的返回值類型為Retrofit.Response
Retrofit自動根據方法返回值類型選用對應的CallAdapterFactory執行適配處理！加上Retrofit默認的CallAdapterFactory，可支持多種形式的方法返回值類型：
Call
CompletableFuture
Void: 不關注返回類型可以使用Void。如果http狀態碼不是2xx，直接拋錯！
Response
其他任意Java類型：將響應體內容適配成一個對應的Java類型對象返回，如果http狀態碼不是2xx，直接拋錯！
/**
* Call
* 不執行適配處理，直接返回Call
* @param id
* @return
*/
@GET("person")
Call<Result
/**
* 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客戶端框架，已在線上穩定運行一年多，並且已經有多個外部公司也接入使用。
