推荐一款 Spring Boot 的 HTTP 客户端框架

• 自定义注入OkHttpClient
  
• 注解式拦截器
  
• 连接池管理
  
• 日志打印
  
• 请求重试
  
• 错误解码器
  
• 全局拦截器
  
• 熔断降级
  
• 微服务之间的HTTP调用
  
• 调用适配器
  
• 数据转换器
  

引入依赖

    
    
    

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

    
    
    

定义http接口

    
    
    

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

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

    
    
    

注入使用

    
    
    

 
     
     
     @Service
public class TestService {

    @Autowired
    private HttpApi httpApi;

    public void test() {
        // 通过httpApi发起http请求
    }
}

    
    
    

HTTP请求相关注解

HTTP请求相关注解，全部使用了retrofit原生注解。详细信息可参考官方文档：retrofit官方文档 ，以下是一个简单说明。

配置项说明

retrofit-spring-boot-starter支持了多个可配置的属性，用来应对不同的业务场景。您可以视情况进行修改，具体说明如下：

    
    
    

 
     
     
     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(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. 继承BasePathMatchInterceptor编写拦截处理器；

2. 接口上使用@Intercept进行标注。如需配置多个拦截器，在接口上标注多个@Intercept注解即可！

    
    
    

 
     
     
     @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。

扩展注解式拦截器

1. 自定义拦截注解

2. 继承BasePathMatchInterceptor编写拦截处理器

3. 接口上使用自定义拦截注解；

    
    
    

 
     
     
     @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;
}

    
    
    

1.自定义拦截注解必须使用@InterceptMark标记。

2. 注解中必须包括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);
    }
}

    
    
    

    
    
    

 
     
     
     @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);
}

    
    
    

1. 配置连接池。
   

    
    
    

 
     
     
     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);
}

    
    
    

日志打印

1. NONE：No logs.

2. BASIC：Logs request and response lines.

3. HEADERS：Logs request and response lines and their respective headers.

4. BODY：Logs request and response lines and their respective headers and bodies (if present).

    
    
    

 
     
     
     retrofit:
  # 日志打印拦截器
  logging-interceptor: com.github.lianjiatech.retrofit.spring.boot.interceptor.DefaultLoggingInterceptor

    
    
    

请求重试

1. RESPONSE_STATUS_NOT_2XX：响应状态码不是2xx时执行重试；

2. OCCUR_IO_EXCEPTION：发生IO异常时执行重试；

3. OCCUR_EXCEPTION：发生任意异常时执行重试；

    
    
    

 
     
     
     retrofit:
  # 请求重试拦截器
  retry-interceptor: com.github.lianjiatech.retrofit.spring.boot.retry.DefaultRetryInterceptor

    
    
    

错误解码器

    
    
    

 
     
     
     /**
 * 错误解码器。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);
    }

}

    
    
    

全局拦截器

全局应用拦截器

    
    
    

 
     
     
     @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. 开启熔断降级功能

    
    
    

 
     
     
     retrofit:
  # 是否启用熔断降级
  enable-degrade: true
  # 熔断降级实现方式(目前仅支持Sentinel)
  degrade-type: sentinel
  # 资源名称解析器
  resource-name-parser: com.github.lianjiatech.retrofit.spring.boot.degrade.DefaultResourceNameParser

    
    
    

    
    
    

 
     
     
     <dependency>
    <groupId>com.alibaba.csp</groupId>
    <artifactId>sentinel-core</artifactId>
    <version>1.6.3</version>
</dependency>

    
    
    

2. 配置降级规则（可选）

    
    
    

 
     
     
     @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;
}

    
    
    

如果应用项目已支持通过配置中心配置降级规则，可忽略注解式配置方式 。

3. @RetrofitClient设置fallback或者fallbackFactory (可选)

    
    
    

 
     
     
     @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> {

    /**
     * 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调用

    
    
    

 
     
     
     @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 {

}

    
    
    

调用适配器和数据转码器

调用适配器

    
    
    

 
     
     
     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>
  ，则可以使用该适配器。
  

• 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);

    
    
    

    
    
    

 
     
     
     r
 
     
     
     etrofit:
  # 全局调用适配器工厂
  global-call-adapter-factories:
    - com.github.lianjiatech.retrofit.spring.boot.core.BodyCallAdapterFactory
    - com.github.lianjiatech.retrofit.spring.boot.core.ResponseCallAdapterFactory

    
    
    

• 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:
  # 全局转换器工厂
  global-converter-factories:
    - retrofit2.converter.jackson.JacksonConverterFactory

    
    
    

来源：juejin.cn/post/6898485806587969544