在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://image.uc.cn/s/wemedia/s/upload/2024/38850f9e513e2c3df6506bcff07222c9.png)
接口必須使用@RetrofitClient注解標記 !http相關注解可參考官方文檔:retrofit官方文檔。Spring Boot 學習筆記,學習下吧。
![](http://image.uc.cn/s/wemedia/s/upload/2024/38b2cfc436d847c5109750c99de4133d.png)
將接口注入到其它Service中即可使用!
![](http://image.uc.cn/s/wemedia/s/upload/2024/2d8423dec4713b54809c20fb2761cc20.png)
HTTP請求相關注解,全部使用了retrofit原生注解。詳細信息可參考官方文檔:retrofit官方文檔 ,以下是一個簡單說明。
![](http://image.uc.cn/s/wemedia/s/upload/2024/e113d2b74c95f3f6d48fb65f9e8e2d9f.png)
retrofit-spring-boot-starter支持了多個可配置的屬性,用來應對不同的業務場景。您可以視情況進行修改,具體說明如下:
![](http://image.uc.cn/s/wemedia/s/upload/2024/26d0edc19982d252bcb93607ccc33b63.png)
yml配置方式:
![](http://image.uc.cn/s/wemedia/s/upload/2024/a74d78b512bd1e659132d3a76881257d.png)
通常情況下,通過@RetrofitClient注解屬性動態創建OkHttpClient對象能夠滿足大部分使用場景。但是在某些情況下,用戶可能需要自定義OkHttpClient,這個時候,可以在接口上定義返回類型是OkHttpClient.Builder的靜態方法來實現。
插播一條:如果你近期准備面試跳槽,點擊Java面試庫小程序刷題吧,共 2500+ 道,幾乎覆蓋了所有主流 Java 技術面試題。
代碼示例如下:
![](http://image.uc.cn/s/wemedia/s/upload/2024/d54d14821d5581d7278831f64d8bbc2d.png)
方法必須使用@OkHttpClientBuilder注解標記!
注解式攔截器很多時候,我們希望某個接口下的某些http請求執行統一的攔截處理邏輯。爲了支持這個功能,retrofit-spring-boot-starter提供了注解式攔截器 ,做到了基于url路徑的匹配攔截 。
使用的步驟主要分爲2步:
繼承BasePathMatchInterceptor編寫攔截處理器;接口上使用@Intercept進行標注。如需配置多個攔截器,在接口上標注多個@Intercept注解即可!下面以給指定請求的url後面拼接timestamp時間戳爲例,介紹下如何使用注解式攔截器。Spring Boot 學習筆記,分享學習下。
繼承BasePathMatchInterceptor編寫攔截處理器![](http://image.uc.cn/s/wemedia/s/upload/2024/f7fa25e081390db7dc8270b1a5ea6c61.png)
![](http://image.uc.cn/s/wemedia/s/upload/2024/c93990a1e3ded639f2fe23d8ed854e4e.png)
上面的@Intercept配置表示:攔截HttpApi接口下/api/**路徑下(排除/api/test/savePerson)的請求,攔截處理器使用TimeStampInterceptor。
擴展注解式攔截器有的時候,我們需要在攔截注解 動態傳入一些參數,然後再執行攔截的時候需要使用這個參數。這種時候,我們可以擴展實現自定義攔截注解 。自定義攔截注解必須使用@InterceptMark標記,並且注解中必須包括include()、exclude()、handler()屬性信息 。使用的步驟主要分爲3步:
自定義攔截注解繼承BasePathMatchInterceptor編寫攔截處理器接口上使用自定義攔截注解;例如我們需要在請求頭裏面動態加入accessKeyId、accessKeySecret簽名信息才能正常發起http請求 ,這個時候可以自定義一個加簽攔截器注解@Sign來實現 。
插播一條:如果你近期准備面試跳槽,點擊Java面試庫小程序刷題吧,共 2500+ 道,幾乎覆蓋了所有主流 Java 技術面試題。
下面以自定義@Sign攔截注解爲例進行說明。
自定義@Sign注解![](http://image.uc.cn/s/wemedia/s/upload/2024/c2c45fcb99b2d09cce12d0230077d38f.png)
擴展自定義攔截注解有以下2點需要注意:
自定義攔截注解必須使用@InterceptMark標記。注解中必須包括include()、exclude()、handler()屬性信息。實現SignInterceptor![](http://image.uc.cn/s/wemedia/s/upload/2024/fccf7739fabdd8a3ffb8c02d69e6350d.png)
上述accessKeyId和accessKeySecret字段值會依據@Sign注解的accessKeyId()和accessKeySecret()值自動注入,如果@Sign指定的是占位符形式的字符串,則會取配置屬性值進行注入 。另外,accessKeyId和accessKeySecret字段必須提供setter方法 。
接口上使用@Sign![](http://image.uc.cn/s/wemedia/s/upload/2024/f62477f1adf6e98a8c22986da4f26b8c.png)
這樣就能在指定url的請求上,自動加上簽名信息了。
連接池管理默認情況下,所有通過Retrofit發送的http請求都會使用max-idle-connections=5 keep-alive-second=300的默認連接池。當然,我們也可以在配置文件中配置多個自定義的連接池,然後通過@RetrofitClient的poolName屬性來指定使用。比如我們要讓某個接口下的請求全部使用poolName=test1的連接池,代碼實現如下:
配置連接池。![](http://image.uc.cn/s/wemedia/s/upload/2024/2f61842d06ac588787f422ce064662d9.png)
![](http://image.uc.cn/s/wemedia/s/upload/2024/885e42b29bba9d00bc9cf2a6f3da12a3.png)
很多情況下,我們希望將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請求,都帶上來源信息。
![](http://image.uc.cn/s/wemedia/s/upload/2024/5c8b32bfd0e589c0a108d1a55e1f028d.png)
只需要實現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依賴 :
<dependency> <groupId>com.alibaba.csp</groupId> <artifactId>sentinel-core</artifactId> <version>1.6.3</version></dependency>2. 配置降級規則(可選)retrofit-spring-boot-starter支持注解式配置降級規則,通過@Degrade注解來配置降級規則 。@Degrade注解可以配置在接口或者方法上,配置在方法上的優先級更高。
![](http://image.uc.cn/s/wemedia/s/upload/2024/00a55096427dba4ce81fbb30550de855.png)
如果應用項目已支持通過配置中心配置降級規則,可忽略注解式配置方式 。
3. @RetrofitClient設置fallback或者fallbackFactory (可選)如果@RetrofitClient不設置fallback或者fallbackFactory,當觸發熔斷時,會直接抛出RetrofitBlockException異常。用戶可以通過設置fallback或者fallbackFactory來定制熔斷時的方法返回值 。fallback類必須是當前接口的實現類,fallbackFactory必須是FallbackFactory<T>實現類,泛型參數類型爲當前接口類型。另外,fallback和fallbackFactory實例必須配置成Spring容器的Bean。
fallbackFactory相對于fallback,主要差別在于能夠感知每次熔斷的異常原因(cause) 。參考示例如下:
@Slf4j@Servicepublic HttpDegradeFallback implements HttpDegradeApi { @Override public Result<Integer> test() { Result<Integer> fallback = new Result<>(); fallback.setCode(100) .setMsg("fallback") .setBody(1000000); return fallback; }}@Slf4j@Servicepublic 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<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即可。
![](http://image.uc.cn/s/wemedia/s/upload/2024/dbee6bb693444ed2cf3ca57a19661ef3.png)
Retrofit可以通過調用適配器CallAdapterFactory將Call<T>對象適配成接口方法的返回值類型。retrofit-spring-boot-starter擴展2種CallAdapterFactory實現:
BodyCallAdapterFactory默認啓用,可通過配置retrofit.enable-body-call-adapter=false關閉同步執行http請求,將響應體內容適配成接口方法的返回值類型實例。除了Retrofit.Call<T>、Retrofit.Response<T>、java.util.concurrent.CompletableFuture<T>之外,其它返回類型都可以使用該適配器。 ResponseCallAdapterFactory默認啓用,可通過配置retrofit.enable-response-call-adapter=false關閉同步執行http請求,將響應體內容適配成Retrofit.Response<T>返回。如果方法的返回值類型爲Retrofit.Response<T>,則可以使用該適配器。Retrofit自動根據方法返回值類型選用對應的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 !
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-gsonJackson: com.squareup.Retrofit:converter-jacksonMoshi: com.squareup.Retrofit:converter-moshiProtobuf: com.squareup.Retrofit:converter-protobufWire: com.squareup.Retrofit:converter-wireSimple XML: com.squareup.Retrofit:converter-simplexmlJAXB: com.squareup.retrofit2:converter-jaxbretrofit-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客戶端框架,已在線上穩定運行兩年多,並且已經有多個外部公司也接入使用。
來源:https://juejin.cn/post/6898485806587969544