扔掉okhttp、httpClient，來試試這款輕量級 HTTP 客戶端框架，吹爆！
在SpringBoot項(xiàng)目直接使用okhttp、httpClient或者RestTemplate發(fā)起HTTP請求，既繁瑣又不方便統(tǒng)一管理。
因此，在這里推薦一個(gè)適用于SpringBoot項(xiàng)目的輕量級HTTP客戶端框架retrofit-spring-boot-starter，使用非常簡單方便，同時(shí)又提供諸多功能增強(qiáng)。
適用于retrofit的spring-boot-starter，支持快速集成和功能增強(qiáng)。
- Spring Boot 3.x 項(xiàng)目，請使用retrofit-spring-boot-starter 3.x。
- Spring Boot 1.x/2.x 項(xiàng)目，請使用retrofit-spring-boot-starter 2.x。
github項(xiàng)目地址：https://github.com/LianjiaTech/retrofit-spring-boot-starter
gitee項(xiàng)目地址：https://gitee.com/lianjiatech/retrofit-spring-boot-starter
功能特性
- 自定義OkHttpClient
- 注解式攔截器
- 日志打印
- 請求重試
- 熔斷降級
- 錯(cuò)誤解碼器
- 微服務(wù)之間的HTTP調(diào)用
- 全局?jǐn)r截器
- 調(diào)用適配器
- 數(shù)據(jù)轉(zhuǎn)換器
- 元注解
- 其他功能示例
快速開始
引入依賴
<dependency>
<groupId>com.github.lianjiatech</groupId>
<artifactId>retrofit-spring-boot-starter</artifactId>
<version>3.0.2</version>
</dependency>如果啟動(dòng)失敗，大概率是依賴沖突，煩請引入或者排除相關(guān)依賴。
定義HTTP接口
接口必須使用@RetrofitClient注解標(biāo)記！
@RetrofitClient(baseUrl = "${test.baseUrl}")
public interface HttpApi {
@GET("person")
Result<Person> getPerson(@Query("id") Long id);
}注意：方法請求路徑慎用/開頭。對于Retrofit而言，如果baseUrl=http://localhost:8080/api/test/，方法請求路徑如果是person，則該方法完整的請求路徑是：http://localhost:8080/api/test/person。而方法請求路徑如果是/person，則該方法完整的請求路徑是：http://localhost:8080/person。
注入使用
將接口注入到其它Service中即可使用！
@Service
public class TestService {
@Autowired
private HttpApi httpApi;
public void test() {
// 使用`httpApi`發(fā)起HTTP請求
}
}默認(rèn)情況下，自動(dòng)使用SpringBoot掃描路徑進(jìn)行RetrofitClient注冊。你也可以在配置類加上@RetrofitScan手工指定掃描路徑。
HTTP請求相關(guān)注解
HTTP請求相關(guān)注解，全部使用了Retrofit原生注解，以下是一個(gè)簡單說明：
注解分類 | 支持的注解 |
請求方式 |
|
請求頭 |
|
Query參數(shù) |
|
path參數(shù) |
|
form-encoded參數(shù) |
|
請求體 |
|
文件上傳 |
|
url參數(shù) |
|
配置屬性
組件支持了多個(gè)可配置的屬性，用來應(yīng)對不同的業(yè)務(wù)場景，具體可支持的配置屬性及默認(rèn)值如下：
注意：應(yīng)用只需要配置要更改的配置項(xiàng)!
retrofit:
# 全局轉(zhuǎn)換器工廠
global-converter-factories:
-com.github.lianjiatech.retrofit.spring.boot.core.BasicTypeConverterFactory
-retrofit2.converter.jackson.JacksonConverterFactory
# 全局調(diào)用適配器工廠(組件擴(kuò)展的調(diào)用適配器工廠已經(jīng)內(nèi)置，這里請勿重復(fù)配置)
global-call-adapter-factories:
# 全局日志打印配置
global-log:
# 啟用日志打印
enable:true
# 全局日志打印級別
log-level:info
# 全局日志打印策略
log-strategy:basic
# 全局重試配置
global-retry:
# 是否啟用全局重試
enable:false
# 全局重試間隔時(shí)間
interval-ms:100
# 全局最大重試次數(shù)
max-retries:2
# 全局重試規(guī)則
retry-rules:
-response_status_not_2xx
-occur_io_exception
# 全局超時(shí)時(shí)間配置
global-timeout:
# 全局讀取超時(shí)時(shí)間
read-timeout-ms:10000
# 全局寫入超時(shí)時(shí)間
write-timeout-ms:10000
# 全局連接超時(shí)時(shí)間
connect-timeout-ms:10000
# 全局完整調(diào)用超時(shí)時(shí)間
call-timeout-ms:0
# 熔斷降級配置
degrade:
# 熔斷降級類型。默認(rèn)none，表示不啟用熔斷降級
degrade-type:none
# 全局sentinel降級配置
global-sentinel-degrade:
# 是否開啟
enable:false
# 各降級策略對應(yīng)的閾值。平均響應(yīng)時(shí)間(ms)，異常比例(0-1)，異常數(shù)量(1-N)
count:1000
# 熔斷時(shí)長，單位為 s
time-window:5
# 降級策略（0：平均響應(yīng)時(shí)間；1：異常比例；2：異常數(shù)量）
grade:0
# 全局resilience4j降級配置
global-resilience4j-degrade:
# 是否開啟
enable:false
# 根據(jù)該名稱從#{@link CircuitBreakerConfigRegistry}獲取CircuitBreakerConfig，作為全局熔斷配置
circuit-breaker-config-name:defaultCircuitBreakerConfig
# 自動(dòng)設(shè)置PathMathInterceptor的scope為prototype
auto-set-prototype-scope-for-path-math-interceptor:true高級功能
超時(shí)時(shí)間配置
如果僅僅需要修改OkHttpClient的超時(shí)時(shí)間，可以通過@RetrofitClient相關(guān)字段修改，或者全局超時(shí)配置修改。
自定義OkHttpClient
如果需要修改OkHttpClient其它配置，可以通過自定義OkHttpClient來實(shí)現(xiàn)，步驟如下：
1.實(shí)現(xiàn)SourceOkHttpClientRegistrar接口，調(diào)用SourceOkHttpClientRegistry#register()方法注冊O(shè)kHttpClient。
@Slf4j
@Component
publicclass CustomSourceOkHttpClientRegistrar implements SourceOkHttpClientRegistrar {
@Override
public void register(SourceOkHttpClientRegistry registry) {
// 添加testSourceOkHttpClient
registry.register("testSourceOkHttpClient", new OkHttpClient.Builder()
.connectTimeout(Duration.ofSeconds(3))
.writeTimeout(Duration.ofSeconds(3))
.readTimeout(Duration.ofSeconds(3))
.addInterceptor(chain -> {
log.info("============use testSourceOkHttpClient=============");
return chain.proceed(chain.request());
})
.build());
}
}2.通過@RetrofitClient.sourceOkHttpClient指定當(dāng)前接口要使用的OkHttpClient。
@RetrofitClient(baseUrl = "${test.baseUrl}", sourceOkHttpClient = "testSourceOkHttpClient")
public interface CustomOkHttpTestApi {
@GET("person")
Result<Person> getPerson(@Query("id") Long id);
}注意：組件不會直接使用指定的OkHttpClient，而是基于該OkHttpClient創(chuàng)建一個(gè)新的。
注解式攔截器
組件提供了注解式攔截器，支持基于url路徑匹配攔截，使用的步驟如下：
- 繼承BasePathMatchInterceptor
- 使用@Intercept注解指定要使用的攔截器
如果需要使用多個(gè)攔截器，在接口上標(biāo)注多個(gè)@Intercept注解即可。
下面以"給指定請求的url后面拼接timestamp時(shí)間戳"為例，介紹下如何使用注解式攔截器。
繼承BasePathMatchInterceptor編寫攔截處理器
@Component
publicclass 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);
}
}默認(rèn)情況下，組件會自動(dòng)將BasePathMatchInterceptor的scope設(shè)置為prototype。
可通過retrofit.auto-set-prototype-scope-for-path-math-interceptor=false關(guān)閉該功能。關(guān)閉之后，需要手動(dòng)將scope設(shè)置為prototype。
@Component
@Scope("prototype")
public class TimeStampInterceptor extends BasePathMatchInterceptor {
@Override
public Response doIntercept(Chain chain) throws IOException {
// ...
}
}接口上使用@Intercept進(jìn)行標(biāo)注
@RetrofitClient(baseUrl = "${test.baseUrl}")
@Intercept(handler = TimeStampInterceptor.class, include = {"/api/**"}, exclude = "/api/test/savePerson")
@Intercept(handler = TimeStamp2Interceptor.class) // 需要多個(gè)，直接添加即可
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。
自定義攔截注解
有的時(shí)候，我們需要在"攔截注解"動(dòng)態(tài)傳入一些參數(shù)，然后在攔截的時(shí)候使用這些參數(shù)。這時(shí)候，我們可以使用"自定義攔截注解"，步驟如下：
- 自定義注解。必須使用@InterceptMark標(biāo)記，并且注解中必須包括include、exclude、handler字段。
- 繼承BasePathMatchInterceptor編寫攔截處理器
- 接口上使用自定義注解
例如，我們需要"在請求頭里面動(dòng)態(tài)加入accessKeyId、accessKeySecret簽名信息才能再發(fā)起HTTP請求"，這時(shí)候可以自定義@Sign注解來實(shí)現(xiàn)。
自定義@Sign注解
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@Documented
@InterceptMark
public@interface Sign {
String accessKeyId();
String accessKeySecret();
String[] include() default {"/**"};
String[] exclude() default {};
Class<? extends BasePathMatchInterceptor> handler() default SignInterceptor.class;
}在@Sign注解中指定了使用的攔截器是SignInterceptor。
實(shí)現(xiàn)SignInterceptor
@Component
publicclass 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字段必須提供setter方法。
攔截器的accessKeyId和accessKeySecret字段值會依據(jù)@Sign注解的accessKeyId()和accessKeySecret()值自動(dòng)注入，如果@Sign指定的是占位符形式的字符串，則會取配置屬性值進(jìn)行注入。
接口上使用@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);
}日志打印
組件支持支持全局日志打印和聲明式日志打印。
全局日志打印
默認(rèn)情況下，全局日志打印是開啟的，默認(rèn)配置如下：
retrofit:
# 全局日志打印配置
global-log:
# 啟用日志打印
enable: true
# 全局日志打印級別
log-level: info
# 全局日志打印策略
log-strategy: basic四種日志打印策略含義如下：
- 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).
聲明式日志打印
如果只需要部分請求才打印日志，可以在相關(guān)接口或者方法上使用@Logging注解。
日志打印自定義擴(kuò)展
如果需要修改日志打印行為，可以繼承LoggingInterceptor，并將其配置成Spring bean。
聚合日志打印
如果需要將同一個(gè)請求的日志聚合在一起打印，可配置AggregateLoggingInterceptor。
@Bean
public LoggingInterceptor loggingInterceptor(RetrofitProperties retrofitProperties){
return new AggregateLoggingInterceptor(retrofitProperties.getGlobalLog());
}請求重試
組件支持支持全局重試和聲明式重試。
全局重試
全局重試默認(rèn)關(guān)閉，默認(rèn)配置項(xiàng)如下：
retrofit:
# 全局重試配置
global-retry:
# 是否啟用全局重試
enable: false
# 全局重試間隔時(shí)間
interval-ms: 100
# 全局最大重試次數(shù)
max-retries: 2
# 全局重試規(guī)則
retry-rules:
- response_status_not_2xx
- occur_io_exception重試規(guī)則支持三種配置：
- RESPONSE_STATUS_NOT_2XX：響應(yīng)狀態(tài)碼不是2xx時(shí)執(zhí)行重試
- OCCUR_IO_EXCEPTION：發(fā)生IO異常時(shí)執(zhí)行重試
- OCCUR_EXCEPTION：發(fā)生任意異常時(shí)執(zhí)行重試
聲明式重試
如果只有一部分請求需要重試，可以在相應(yīng)的接口或者方法上使用@Retry注解。
請求重試自定義擴(kuò)展
如果需要修改請求重試行為，可以繼承RetryInterceptor，并將其配置成Spring bean。
熔斷降級
熔斷降級默認(rèn)關(guān)閉，當(dāng)前支持sentinel和resilience4j兩種實(shí)現(xiàn)。
retrofit:
# 熔斷降級配置
degrade:
# 熔斷降級類型。默認(rèn)none，表示不啟用熔斷降級
degrade-type: sentinelSentinel
配置degrade-type=sentinel開啟，然后在相關(guān)接口或者方法上聲明@SentinelDegrade注解即可。
記得手動(dòng)引入Sentinel依賴：
<dependency>
<groupId>com.alibaba.csp</groupId>
<artifactId>sentinel-core</artifactId>
<version>1.6.3</version>
</dependency>此外，還支持全局Sentinel熔斷降級：
retrofit:
# 熔斷降級配置
degrade:
# 熔斷降級類型。默認(rèn)none，表示不啟用熔斷降級
degrade-type: sentinel
# 全局sentinel降級配置
global-sentinel-degrade:
# 是否開啟
enable: true
# ...其他sentinel全局配置Resilience4j
配置degrade-type=resilience4j開啟。然后在相關(guān)接口或者方法上聲明@Resilience4jDegrade即可。
記得手動(dòng)引入Resilience4j依賴：
<dependency>
<groupId>io.github.resilience4j</groupId>
<artifactId>resilience4j-circuitbreaker</artifactId>
<version>1.7.1</version>
</dependency>通過以下配置可開啟全局resilience4j熔斷降級：
retrofit:
# 熔斷降級配置
degrade:
# 熔斷降級類型。默認(rèn)none，表示不啟用熔斷降級
degrade-type: resilience4j
# 全局resilience4j降級配置
global-resilience4j-degrade:
# 是否開啟
enable: true
# 根據(jù)該名稱從#{@link CircuitBreakerConfigRegistry}獲取CircuitBreakerConfig，作為全局熔斷配置
circuit-breaker-config-name: defaultCircuitBreakerConfig熔斷配置管理：
1.實(shí)現(xiàn)CircuitBreakerConfigRegistrar接口，注冊CircuitBreakerConfig。
@Component
publicclass CustomCircuitBreakerConfigRegistrar implements CircuitBreakerConfigRegistrar {
@Override
public void register(CircuitBreakerConfigRegistry registry) {
// 替換默認(rèn)的CircuitBreakerConfig
registry.register(Constants.DEFAULT_CIRCUIT_BREAKER_CONFIG, CircuitBreakerConfig.ofDefaults());
// 注冊其它的CircuitBreakerConfig
registry.register("testCircuitBreakerConfig", CircuitBreakerConfig.custom()
.slidingWindowType(CircuitBreakerConfig.SlidingWindowType.TIME_BASED)
.failureRateThreshold(20)
.minimumNumberOfCalls(5)
.permittedNumberOfCallsInHalfOpenState(5)
.build());
}
}2.通過circuitBreakerConfigName指定CircuitBreakerConfig。包括retrofit.degrade.global-resilience4j-degrade.circuit-breaker-config-name或者@Resilience4jDegrade.circuitBreakerConfigName
擴(kuò)展熔斷降級
如果用戶需要使用其他的熔斷降級實(shí)現(xiàn)，繼承BaseRetrofitDegrade，并將其配置Spring Bean。
配置fallback或者fallbackFactory (可選)
如果@RetrofitClient不設(shè)置fallback或者fallbackFactory，當(dāng)觸發(fā)熔斷時(shí)，會直接拋出RetrofitBlockException異常。用戶可以通過設(shè)置fallback或者fallbackFactory來定制熔斷時(shí)的方法返回值。
注意：fallback類必須是當(dāng)前接口的實(shí)現(xiàn)類，fallbackFactory必須是FallbackFactory<T>實(shí)現(xiàn)類，泛型參數(shù)類型為當(dāng)前接口類型。另外，fallback和fallbackFactory實(shí)例必須配置成Spring Bean。
fallbackFactory相對于fallback，主要差別在于能夠感知每次熔斷的異常原因(cause)，參考示例如下：
@Slf4j
@Service
publicclass HttpDegradeFallback implements HttpDegradeApi {
@Override
public Result<Integer> test() {
Result<Integer> fallback = new Result<>();
fallback.setCode(100)
.setMsg("fallback")
.setBody(1000000);
return fallback;
}
}
@Slf4j
@Service
publicclass HttpDegradeFallbackFactory implements FallbackFactory<HttpDegradeApi> {
@Override
public HttpDegradeApi create(Throwable cause) {
log.error("觸發(fā)熔斷了! ", cause.getMessage(), cause);
returnnew HttpDegradeApi() {
@Override
public Result<Integer> test() {
Result<Integer> fallback = new Result<>();
fallback.setCode(100)
.setMsg("fallback")
.setBody(1000000);
return fallback;
}
};
}
}錯(cuò)誤解碼器
在HTTP發(fā)生請求錯(cuò)誤(包括發(fā)生異?；蛘唔憫?yīng)數(shù)據(jù)不符合預(yù)期)的時(shí)候，錯(cuò)誤解碼器可將HTTP相關(guān)信息解碼到自定義異常中。你可以在@RetrofitClient注解的errorDecoder()指定當(dāng)前接口的錯(cuò)誤解碼器，自定義錯(cuò)誤解碼器需要實(shí)現(xiàn)ErrorDecoder接口：
微服務(wù)之間的HTTP調(diào)用
繼承ServiceInstanceChooser
用戶可以自行實(shí)現(xiàn)ServiceInstanceChooser接口，完成服務(wù)實(shí)例的選取邏輯，并將其配置成Spring Bean。對于Spring Cloud應(yīng)用，可以使用如下實(shí)現(xiàn)。
@Service
publicclass SpringCloudServiceInstanceChooser implements ServiceInstanceChooser {
private LoadBalancerClient loadBalancerClient;
@Autowired
public SpringCloudServiceInstanceChooser(LoadBalancerClient loadBalancerClient) {
this.loadBalancerClient = loadBalancerClient;
}
/**
* Chooses a ServiceInstance URI from the LoadBalancer for the specified service.
*
* @param serviceId The service ID to look up the LoadBalancer.
* @return Return the uri of ServiceInstance
*/
@Override
public URI choose(String serviceId) {
ServiceInstance serviceInstance = loadBalancerClient.choose(serviceId);
Assert.notNull(serviceInstance, "can not found service instance! serviceId=" + serviceId);
return serviceInstance.getUri();
}
}指定serviceId和path
@RetrofitClient(serviceId = "${jy-helicarrier-api.serviceId}", path = "/m/count")
public interface ApiCountService {}全局?jǐn)r截器
全局應(yīng)用攔截器
如果我們需要對整個(gè)系統(tǒng)的的HTTP請求執(zhí)行統(tǒng)一的攔截處理，可以實(shí)現(xiàn)全局?jǐn)r截器GlobalInterceptor, 并配置成spring Bean。
@Component
publicclass SourceGlobalInterceptor implements GlobalInterceptor {
@Autowired
private TestService testService;
@Override
public Response intercept(Chain chain) throws IOException {
Request request = chain.request();
Request newReq = request.newBuilder()
.addHeader("source", "test")
.build();
testService.test();
return chain.proceed(newReq);
}
}全局網(wǎng)絡(luò)攔截器
實(shí)現(xiàn)NetworkInterceptor接口，并配置成spring Bean。
調(diào)用適配器
Retrofit可以通過CallAdapterFactory將Call<T>對象適配成接口方法的返回值類型。組件擴(kuò)展了一些CallAdapterFactory實(shí)現(xiàn)：
- BodyCallAdapterFactory
- 同步執(zhí)行HTTP請求，將響應(yīng)體內(nèi)容適配成方法的返回值類型。
任意方法返回值類型都可以使用BodyCallAdapterFactory，優(yōu)先級最低。
- ResponseCallAdapterFactory
- 同步執(zhí)行HTTP請求，將響應(yīng)體內(nèi)容適配成Retrofit.Response<T>返回。
- 只有方法返回值類型為Retrofit.Response<T>，才可以使用ResponseCallAdapterFactory。
- 響應(yīng)式編程相關(guān)CallAdapterFactory
Retrofit會根據(jù)方法返回值類型選擇對應(yīng)的CallAdapterFactory執(zhí)行適配處理，目前支持的返回值類型如下：
- String：將Response Body適配成String返回。
- 基礎(chǔ)類型(Long/Integer/Boolean/Float/Double)：將Response Body適配成上述基礎(chǔ)類型
- 任意Java類型：將Response Body適配成對應(yīng)的Java對象返回
- CompletableFuture<T>: 將Response Body適配成CompletableFuture<T>對象返回
- Void: 不關(guān)注返回類型可以使用Void
- Response<T>: 將Response適配成Response<T>對象返回
- Call<T>: 不執(zhí)行適配處理，直接返回Call<T>對象
- Mono<T>: Project Reactor響應(yīng)式返回類型
- Single<T>：Rxjava響應(yīng)式返回類型（支持Rxjava2/Rxjava3）
- Completable：Rxjava響應(yīng)式返回類型，HTTP請求沒有響應(yīng)體（支持Rxjava2/Rxjava3）
@RetrofitClient(baseUrl = "${test.baseUrl}")
publicinterface HttpApi {
@POST("getString")
String getString(@Body Person person);
@GET("person")
Result<Person> getPerson(@Query("id") Long id);
@GET("person")
CompletableFuture<Result<Person>> getPersonCompletableFuture(@Query("id") Long id);
@POST("savePerson")
Void savePersonVoid(@Body Person person);
@GET("person")
Response<Result<Person>> getPersonResponse(@Query("id") Long id);
@GET("person")
Call<Result<Person>> getPersonCall(@Query("id") Long id);
@GET("person")
Mono<Result<Person>> monoPerson(@Query("id") Long id);
@GET("person")
Single<Result<Person>> singlePerson(@Query("id") Long id);
@GET("ping")
Completable ping();
}可以通過繼承CallAdapter.Factory擴(kuò)展CallAdapter。
組件支持通過retrofit.global-call-adapter-factories配置全局調(diào)用適配器工廠：
retrofit:
# 全局轉(zhuǎn)換器工廠(組件擴(kuò)展的`CallAdaptorFactory`工廠已經(jīng)內(nèi)置，這里請勿重復(fù)配置)
global-call-adapter-factories:
# ...針對每個(gè)Java接口，還可以通過@RetrofitClient.callAdapterFactories指定當(dāng)前接口采用的CallAdapter.Factory。
建議：將CallAdapter.Factory配置成Spring Bean
數(shù)據(jù)轉(zhuǎn)碼器
Retrofit使用Converter將@Body注解的對象轉(zhuǎn)換成Request Body，將Response Body轉(zhuǎn)換成一個(gè)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
- fastJson：com.alibaba.fastjson.support.retrofit.Retrofit2ConverterFactory
組件支持通過retrofit.global-converter-factories配置全局Converter.Factory，默認(rèn)的是retrofit2.converter.jackson.JacksonConverterFactory。
如果需要修改Jackson配置，自行覆蓋JacksonConverterFactory的bean配置即可。
retrofit:
# 全局轉(zhuǎn)換器工廠
global-converter-factories:
- com.github.lianjiatech.retrofit.spring.boot.core.BasicTypeConverterFactory
- retrofit2.converter.jackson.JacksonConverterFactory針對每個(gè)Java接口，還可以通過@RetrofitClient.converterFactories指定當(dāng)前接口采用的Converter.Factory。
建議：將Converter.Factory配置成Spring Bean。
元注解
@RetrofitClient、@Retry、@Logging、@Resilience4jDegrade等注解支持元注解、繼承以及@AliasFor。
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@Documented
@Inherited
@RetrofitClient(baseUrl = "${test.baseUrl}")
@Logging(logLevel = LogLevel.WARN)
@Retry(intervalMs = 200)
public@interface MyRetrofitClient {
@AliasFor(annotation = RetrofitClient.class, attribute = "converterFactories")
Class<? extends Converter.Factory>[] converterFactories() default {GsonConverterFactory.class};
@AliasFor(annotation = Logging.class, attribute = "logStrategy")
LogStrategy logStrategy() default LogStrategy.BODY;
}其他功能示例
form參數(shù)
@FormUrlEncoded
@POST("token/verify")
Object tokenVerify(@Field("source") String source,@Field("signature") String signature,@Field("token") String token);
@FormUrlEncoded
@POST("message")
CompletableFuture<Object> sendMessage(@FieldMap Map<String, Object> param);文件上傳
創(chuàng)建MultipartBody.Part
// 對文件名使用URLEncoder進(jìn)行編碼
public ResponseEntity importTerminology(MultipartFile file){
String fileName=URLEncoder.encode(Objects.requireNonNull(file.getOriginalFilename()),"utf-8");
okhttp3.RequestBody requestBody=okhttp3.RequestBody.create(MediaType.parse("multipart/form-data"),file.getBytes());
MultipartBody.Part part=MultipartBody.Part.createFormData("file",fileName,requestBody);
apiService.upload(part);
return ok().build();
}HTTP上傳接口
@POST("upload")
@Multipart
Void upload(@Part MultipartBody.Part file);文件下載
HTTP下載接口
@RetrofitClient(baseUrl = "https://.ljcdn.com/hc-picture/")
public interface DownloadApi {
@GET("{fileKey}")
Response<ResponseBody> download(@Path("fileKey") String fileKey);
}HTTP下載使用
@SpringBootTest(classes = RetrofitTestApplication.class)
@RunWith(SpringRunner.class)
public class DownloadTest {
@Autowired
DownloadApi downLoadApi;
@Test
public void download() throws Exception {
String fileKey = "6302d742-ebc8-4649-95cf-62ccf57a1add";
Response<ResponseBody> response = downLoadApi.download(fileKey);
ResponseBody responseBody = response.body();
// 二進(jìn)制流
InputStream is = responseBody.byteStream();
// 具體如何處理二進(jìn)制流，由業(yè)務(wù)自行控制。這里以寫入文件為例
File tempDirectory = new File("temp");
if (!tempDirectory.exists()) {
tempDirectory.mkdir();
}
File file = new File(tempDirectory, UUID.randomUUID().toString());
if (!file.exists()) {
file.createNewFile();
}
FileOutputStream fos = new FileOutputStream(file);
byte[] b = newbyte[1024];
int length;
while ((length = is.read(b)) > 0) {
fos.write(b, 0, length);
}
is.close();
fos.close();
}
}動(dòng)態(tài)URL
使用@url注解可實(shí)現(xiàn)動(dòng)態(tài)URL。此時(shí)，baseUrl配置任意合法url即可。例如：http://github.com/ 。運(yùn)行時(shí)只會根據(jù)@Url地址發(fā)起請求。
注意：@url必須放在方法參數(shù)的第一個(gè)位置，另外，@GET、@POST等注解上，不需要定義端點(diǎn)路徑。
@GET
Map<String, Object> test3(@Url String url,@Query("name") String name);DELETE請求添加請求體
@HTTP(method = "DELETE", path = "/user/delete", hasBody = true)GET請求添加請求體
okhttp3自身不支持GET請求添加請求體，源碼如下：
圖片
圖片
作者給出了具體原因，可以參考:https://github.com/square/okhttp/issues/3154
但是，如果實(shí)在需要這么做，可以使用：@HTTP(method = "get", path = "/user/get", hasBody = true)，使用小寫get繞過上述限制。
