HTTP客戶端框架之Retrofit

上善若泪發表於2024-06-09
HTTP客戶端框架

目錄
  • 1 HTTP客戶端框架Retrofit
    • 1.1 引言
    • 1.2 簡介
    • 1.3 簡單使用
      • 1.3.1 引入依賴
      • 1.3.2 定義http介面
      • 1.3.3 注入使用
    • 1.4 HTTP請求相關注解
    • 1.5 配置項
      • 1.5.1 配置講解
      • 1.5.2 配置示例
    • 1.6 高階功能
      • 1.6.1 自定義注入OkHttpClient
      • 1.6.2 註解式攔截器
        • 1.6.2.1 繼承BasePathMatchInterceptor編寫攔截處理器
        • 1.6.2.2 介面上使用@Intercept進行標註
      • 1.6.3 擴充套件註解式攔截器
        • 1.6.3.1 自定義@Sign註解
        • 1.6.3.2 實現SignInterceptor
        • 1.6.3.3 介面上使用@Sign
      • 1.6.4 連線池管理
      • 1.6.5 日誌列印
      • 1.6.6 請求重試
      • 1.6.7 錯誤解碼器
    • 1.7 全域性攔截器
      • 1.7.1 全域性應用攔截器
      • 1.7.2 全域性網路攔截器
      • 1.7.3 熔斷降級
        • 1.7.3.1 開啟熔斷降級功能
        • 1.7.3.2 配置降級規則（可選）
        • 1.7.3.3 @RetrofitClient設定fallback或者fallbackFactory (可選)
        • 1.7.3.4 微服務之間的HTTP呼叫
    • 1.8 呼叫介面卡和資料轉碼器
      • 1.8.1 呼叫介面卡
      • 1.8.2 資料轉碼器

1 HTTP客戶端框架Retrofit

1.1 引言

在SpringBoot專案直接使用okhttp、httpClient或者RestTemplate發起HTTP請求，既繁瑣又不方便統一管理。因此，在這裡推薦一個適用於SpringBoot專案的輕量級HTTP客戶端框架retrofit-spring-boot-starter，使用非常簡單方便，同時又提供諸多功能增強

1.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呼叫
  • 呼叫介面卡
  • 資料轉換器

1.3 簡單使用

1.3.1 引入依賴

<dependency>
    <groupId>com.github.lianjiatech</groupId>
    <artifactId>retrofit-spring-boot-starter</artifactId>
    <version>2.2.2</version>
</dependency>

1.3.2 定義http介面

介面必須使用@RetrofitClient註解標記

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

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

1.3.3 注入使用

將介面注入到其它Service中即可使用！

@Service
public class TestService {

    @Autowired
    private HttpApi httpApi;

    public void test() {
        // 透過httpApi發起http請求
    }
}

1.4 HTTP請求相關注解

HTTP請求相關注解，全部使用了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

1.5 配置項

1.5.1 配置講解

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 熔斷資源名稱解析器，用於解析資源名稱

1.5.2 配置示例

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

1.6 高階功能

1.6.1 自定義注入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註解標記

1.6.2 註解式攔截器

很多時候，我們希望某個介面下的某些http請求執行統一的攔截處理邏輯。為了支援這個功能，retrofit-spring-boot-starter提供了註解式攔截器 ，做到了基於url路徑的匹配攔截 。使用的步驟主要分為2步：

  • 繼承BasePathMatchInterceptor編寫攔截處理器；
  • 介面上使用@Intercept進行標註。如需配置多個攔截器，在介面上標註多個@Intercept註解即可

下面以給指定請求的url後面拼接timestamp時間戳為例，介紹下如何使用註解式攔截器。

1.6.2.1 繼承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);
    }
}

1.6.2.2 介面上使用@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。

1.6.3 擴充套件註解式攔截器

有的時候，我們需要在攔截註解動態傳入一些引數，然後再執行攔截的時候需要使用這個引數。這種時候，我們可以擴充套件實現自定義攔截註解 。自定義攔截註解必須使用@InterceptMark標記，並且註解中必須包括include()、exclude()、handler()屬性資訊 。
使用的步驟主要分為3步：

  • 自定義攔截註解，且必須使用@InterceptMark標記
  • 繼承BasePathMatchInterceptor編寫攔截處理器
  • 介面上使用自定義攔截註解；

例如我們需要在請求頭裡面動態加入accessKeyId、accessKeySecret簽名資訊才能正常發起http請求 ，這個時候可以自定義一個加簽攔截器註解@Sign來實現 。下面以自定義@Sign攔截註解為例進行說明。

1.6.3.1 自定義@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()屬性資訊。

1.6.3.2 實現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方法 。

1.6.3.3 介面上使用@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的請求上，自動加上簽名資訊了。

1.6.4 連線池管理

預設情況下，所有透過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);
}

1.6.5 日誌列印

很多情況下，我們希望將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

1.6.6 請求重試

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

1.6.7 錯誤解碼器

在HTTP發生請求錯誤(包括髮生異常或者響應資料不符合預期)的時候，錯誤解碼器可將HTTP相關資訊解碼到自定義異常中。
在@RetrofitClient註解的errorDecoder()指定當前介面的錯誤解碼器，自定義錯誤解碼器需要實現ErrorDecoder介面：

/**
 * 錯誤解碼器。ErrorDecoder.
 * 當請求發生異常或者收到無效響應結果的時候，將HTTP相關資訊解碼到異常中，無效響應由業務自己判斷
 */
public interface ErrorDecoder {

    /**
     * 當無效響應的時候，將HTTP資訊解碼到異常中，無效響應由業務自行判斷。
     */
    default RuntimeException invalidRespDecode(Request request, Response response) {
        if (!response.isSuccessful()) {
            throw RetrofitException.errorStatus(request, response);
        }
        return null;
    }


    /**
     * 當請求發生IO異常時，將HTTP資訊解碼到異常中。
     */
    default RuntimeException ioExceptionDecode(Request request, IOException cause) {
        return RetrofitException.errorExecuting(request, cause);
    }

    /**
     * 當請求發生除IO異常之外的其它異常時，將HTTP資訊解碼到異常中。
     */
    default RuntimeException exceptionDecode(Request request, Exception cause) {
        return RetrofitException.errorUnknown(request, cause);
    }
}

1.7 全域性攔截器

1.7.1 全域性應用攔截器

如果我們需要對整個系統的的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);
    }
}

1.7.2 全域性網路攔截器

只需要實現NetworkInterceptor介面 並配置成spring容器中的bean就支援自動織入全域性網路攔截器。

1.7.3 熔斷降級

在分散式服務架構中，對不穩定的外部服務進行熔斷降級是保證服務高可用的重要措施之一。由於外部服務的穩定性是不能保證的，當外部服務不穩定時，響應時間會變長。相應地，呼叫方的響應時間也會變長，執行緒會產生堆積，最終可能耗盡呼叫方的執行緒池，導致整個服務不可用。因此我們需要對不穩定的弱依賴服務呼叫進行熔斷降級，暫時切斷不穩定呼叫，避免區域性不穩定導致整體服務雪崩。

retrofit-spring-boot-starter支援熔斷降級功能，底層基於Sentinel實現。具體來說，支援了熔斷資源自發現 和註解式降級規則配置 。如需使用熔斷降級，只需要進行以下操作即可：

1.7.3.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>

1.7.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.7.3.3 @RetrofitClient設定fallback或者fallbackFactory (可選)

如果@RetrofitClient不設定fallback或者fallbackFactory，當觸發熔斷時，會直接丟擲RetrofitBlockException異常。使用者可以透過設定fallback或者fallbackFactory來定製熔斷時的方法返回值 。fallback類必須是當前介面的實現類，fallbackFactory必須是FallbackFactory<T>實現類，泛型引數型別為當前介面型別。另外，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<HttpDegradeApi> {

    /**
     * @return 實現了retrofit介面的例項
     */
    @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;
            }
    }
}

1.7.3.4 微服務之間的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 {

}

1.8 呼叫介面卡和資料轉碼器

1.8.1 呼叫介面卡

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>物件
     */
    @GET("person")
    Call<Result<Person>> getPersonCall(@Query("id") Long id);

    /**
     *  CompletableFuture<T>
     *  將響應體內容適配成CompletableFuture<T>物件返回
     */
    @GET("person")
    CompletableFuture<Result<Person>> getPersonCompletableFuture(@Query("id") Long id);

    /**
     * Void
     * 不關注返回型別可以使用Void。如果http狀態碼不是2xx，直接拋錯！
     */
    @GET("person")
    Void getPersonVoid(@Query("id") Long id);

    /**
     *  Response<T>
     *  將響應內容適配成Response<T>物件返回
     */
    @GET("person")
    Response<Result<Person>> getPersonResponse(@Query("id") Long id);

    /**
     * 其他任意Java型別
     * 將響應體內容適配成一個對應的Java型別物件返回，如果http狀態碼不是2xx，直接拋錯！
     */
    @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物件

1.8.2 資料轉碼器

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序列化規則

retrofit:
  # 全域性轉換器工廠
  global-converter-factories:
    - retrofit2.converter.jackson.JacksonConverterFactory

針對每個Java介面，還可以透過@RetrofitClient註解的converterFactories()指定當前介面採用的Converter.Factory，指定的轉換器工廠例項依然優先從Spring容器獲取。

注意：如果Converter.Factory沒有public的無參構造器，請手動將其配置成Spring容器的Bean物件

相關文章