乐趣区

关于java:springboot项目整合Retrofit最佳实践最优雅的HTTP客户端工具

jiezi

大家都晓得 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 申请有多简略。

<!–more–>

retrofit官网并没有提供与 spring-boot 疾速整合的 starter。retrofit-spring-boot-starter 是笔者封装的，已在生产环境应用，十分稳固。造轮子不易，跪求各位大佬 star。

我的项目源码：retrofit-spring-boot-starter

引入依赖

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

配置 @RetrofitScan 注解

你能够给带有 @Configuration 的类配置 @RetrofitScan，或者间接配置到spring-boot 的启动类上，如下：

@SpringBootApplication
@RetrofitScan("com.github.lianjiatech.retrofit.spring.boot.test")
public class RetrofitTestApplication {public static void main(String[] args) {SpringApplication.run(RetrofitTestApplication.class, args);
    }
}

定义 http 接口

接口必须应用 @RetrofitClient 注解标记！http 相干注解可参考官网文档：retrofit 官网文档。

@RetrofitClient(baseUrl = "${test.baseUrl}")
public interface HttpApi {@GET("person")
    Result<Person> getPerson(@Query("id") Long id);
}

注入应用

将接口注入到其它 Service 中即可应用。

@Service
public class TestService {

    @Autowired
    private HttpApi httpApi;

    public void test() {// 通过 httpApi 发动 http 申请}
}

只有通过上述几个步骤，就能实现通过接口发送 http 申请了，真的很简略。如果你在 spring-boot 我的项目外面应用过 mybatis，置信你对这种应用形式会更加相熟。接下来咱们持续介绍一下retrofit-spring-boot-starter 更高级一点的性能。

注解式拦截器

很多时候，咱们心愿某个接口下的某些 http 申请执行对立的拦挡解决逻辑。这个时候能够应用 注解式拦截器。应用的步骤次要分为 2 步：

  1. 继承 BasePathMatchInterceptor 编写拦挡处理器；
  2. 接口上应用 @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 步：

  1. 自定义拦挡注解
  2. 继承 BasePathMatchInterceptor 编写拦挡处理器
  3. 接口上应用自定义拦挡注解；

例如咱们须要 在申请头外面动静退出 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 点须要留神：

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

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

这样就能在指定 url 的申请上，主动加上签名信息了。

连接池治理

默认状况下，所有通过 Retrofit 发送的 http 申请都会应用 max-idle-connections=5 keep-alive-second=300 的默认连接池。当然，咱们也能够在配置文件中配置多个自定义的连接池，而后通过 @RetrofitClient 的poolName属性来指定应用。比方咱们要让某个接口下的申请全副应用 poolName=test1 的连接池，代码实现如下：

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

日志打印

很多状况下，咱们心愿将 http 申请日志记录下来。通过 @RetrofitClient 的logLevel和 logStrategy 属性，您能够指定每个接口的日志打印级别以及日志打印策略。retrofit-spring-boot-starter反对了 5 种日志打印级别(ERROR, WARN, INFO, DEBUG, TRACE)，默认INFO；反对了 4 种日志打印策略（NONE, BASIC, HEADERS, BODY），默认BASIC。4 种日志打印策略含意如下：

  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-spring-boot-starter默认应用了 DefaultLoggingInterceptor 执行真正的日志打印性能，其底层就是 okhttp 原生的 HttpLoggingInterceptor。当然，你也能够自定义实现本人的日志打印拦截器，只须要继承BaseLoggingInterceptor（具体能够参考DefaultLoggingInterceptor 的实现），而后在配置文件中进行相干配置即可。

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

Http 异样信息格式化器

当呈现 http 申请异样时，原始的异样信息可能浏览起来并不敌对，因而 retrofit-spring-boot-starter 提供了 Http 异样信息格式化器，用来丑化输入 http 申请参数，默认应用DefaultHttpExceptionMessageFormatter 进行申请数据格式化。你也能够进行自定义，只须要继承BaseHttpExceptionMessageFormatter，再进行相干配置即可。

retrofit:
  # Http 异样信息格式化器
  http-exception-message-formatter: com.github.lianjiatech.retrofit.spring.boot.interceptor.DefaultHttpExceptionMessageFormatter

调用适配器 CallAdapter

Retrofit能够通过调用适配器 CallAdapterFactory 将Call<T>对象适配成接口办法的返回值类型。retrofit-spring-boot-starter扩大 2 种 CallAdapterFactory 实现：

  1. BodyCallAdapterFactory

    • 默认启用，可通过配置 retrofit.enable-body-call-adapter=false 敞开
    • 同步执行 http 申请，将响应体内容适配成接口办法的返回值类型实例。
    • 除了 Retrofit.Call<T>、Retrofit.Response<T>、java.util.concurrent.CompletableFuture<T> 之外，其它返回类型都能够应用该适配器。

  2. 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；而后将自定义的CallAdapterFactory 配置成 spring 的bean！

自定义配置的 CallAdapter.Factory 优先级更高！

数据转码器 Converter

Retrofi应用 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

retrofit-spring-boot-starter默认应用的是 jackson 进行序列化转换！如果须要应用其它序列化形式，在我的项目中引入对应的依赖，再把对应的 ConverterFactory 配置成 spring 的 bean 即可。

咱们也能够通过继承 Converter.Factory 扩大实现本人的 Converter；而后将自定义的Converter.Factory 配置成 spring 的bean！

自定义配置的 Converter.Factory 优先级更高！

全局拦截器 BaseGlobalInterceptor

如果咱们须要对整个零碎的的 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);
    }
}

结语

至此，spring-boot 我的项目下最优雅的 http 客户端工具介绍就完结了，更多详细信息能够参考官网文档：retrofit 以及 retrofit-spring-boot-starter。

原创不易，感觉文章写得不错的小伙伴，点个赞???? 激励一下吧~

退出移动版