你們都知道okhttp
是一款由square公司開源的java
版本http
客戶端工具。實際上,square公司還開源了基於okhttp
進一步封裝的retrofit工具,用來支持經過接口
的方式發起http
請求。若是你的項目中還在直接使用RestTemplate
或者okhttp
,或者基於它們封裝的HttpUtils
,那麼你能夠嘗試使用Retrofit
。retrofit-spring-boot-starter
實現了Retrofit
與spring-boot
框架快速整合,而且支持了部分功能加強,從而極大的簡化spring-boot
項目下http
接口調用開發。接下來咱們直接經過retrofit-spring-boot-starter
,來看看spring-boot
項目發送http
請求有多簡單。java
retrofit
官方並無提供與spring-boot
快速整合的starter
。retrofit-spring-boot-starter
是筆者封裝的,已在生產環境使用,很是穩定。
項目源碼:retrofit-spring-boot-startergit
<dependency> <groupId>com.github.lianjiatech</groupId> <artifactId>retrofit-spring-boot-starter</artifactId> <version>2.0.2</version> </dependency>
@RetrofitScan
註解你能夠給帶有@Configuration
的類配置@RetrofitScan
,或者直接配置到spring-boot
的啓動類上,以下:github
@SpringBootApplication @RetrofitScan("com.github.lianjiatech.retrofit.spring.boot.test") public class RetrofitTestApplication { public static void main(String[] args) { SpringApplication.run(RetrofitTestApplication.class, args); } }
定義http接口spring
接口必須使用@RetrofitClient
註解標記!http相關注解可參考官方文檔:retrofit官方文檔。api
@RetrofitClient(baseUrl = "${test.baseUrl}") public interface HttpApi { @GET("person") Result<Person> getPerson(@Query("id") Long id); }
注入使用mybatis
將接口注入到其它Service中便可使用。框架
@Service public class TestService { @Autowired private HttpApi httpApi; public void test() { } }
只要經過上述幾個步驟,就能實現經過接口發送http
請求了,真的很簡單。若是你在spring-boot
項目裏面使用過mybatis
,相信你對這種使用方式會更加熟悉。接下來咱們繼續介紹一下retrofit-spring-boot-starter
更高級一點的功能。ide
不少時候,咱們但願某個接口下的某些http請求執行統一的攔截處理邏輯。這個時候可使用註解式攔截器。使用的步驟主要分爲2步:spring-boot
BasePathMatchInterceptor
編寫攔截處理器;@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); }
默認狀況下,全部經過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
2. 經過@RetrofitClient
的poolName
屬性來指定使用的鏈接池。
@RetrofitClient(baseUrl = "${test.baseUrl}", poolName="test1") public interface HttpApi { @GET("person") Result<Person> getPerson(@Query("id") Long id); }
不少狀況下,咱們但願將http請求日誌記錄下來。經過@RetrofitClient
的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
當出現http請求異常時,原始的異常信息可能閱讀起來並不友好,所以retrofit-spring-boot-starter
提供了Http異常信息格式化器
,用來美化輸出http請求參數,默認使用DefaultHttpExceptionMessageFormatter
進行請求數據格式化。你也能夠進行自定義,只須要繼承BaseHttpExceptionMessageFormatter
,再進行相關配置便可。
retrofit:
# Http異常信息格式化器
http-exception-message-formatter: com.github.lianjiatech.retrofit.spring.boot.interceptor.DefaultHttpExceptionMessageFormatter
Retrofit
能夠經過調用適配器CallAdapterFactory
將Call<T>
對象適配成接口方法的返回值類型。retrofit-spring-boot-starter
擴展2種CallAdapterFactory
實現:BodyCallAdapterFactory
retrofit.enable-body-call-adapter=false
關閉Retrofit.Call<T>
、Retrofit.Response<T>
、java.util.concurrent.CompletableFuture<T>
以外,其它返回類型均可以使用該適配器。ResponseCallAdapterFactory
retrofit.enable-response-call-adapter=false
關閉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
;而後將自定義的CallAdapterFactory
配置成spring
的bean
!
CallAdapter.Factory
優先級更高! Retrofi
使用Converter
將@Body
註解標註的對象轉換成請求體,將響應體數據轉換成一個Java
對象,能夠選用如下幾種Converter
:
retrofit-spring-boot-starter
默認使用的是jackson進行序列化轉換!若是須要使用其它序列化方式,在項目中引入對應的依賴,再把對應的ConverterFactory
配置成spring的bean便可。咱們也能夠經過繼承Converter.Factory
擴展實現本身的Converter
;而後將自定義的Converter.Factory
配置成spring
的bean
!
自定義配置的
Converter.Factory
優先級更高!
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); } }
至此,spring-boot項目下最優雅的http客戶端工具介紹就結束了,更多詳細信息能夠參考官方文檔:retrofit以及retrofit-spring-boot-starter。實現原理解讀可查看基於Retrofit實現本身的輕量級http調用工具