Introducing retrofit-spring-boot-starter: A Lightweight HTTP Client Framework for Spring Boot

When using SpringBoot, developers often resort to okhttp , httpClient or RestTemplate for HTTP calls, which leads to scattered code and difficult management. The retrofit-spring-boot-starter project provides a lightweight solution that integrates Retrofit—a type‑safe HTTP client—directly with Spring Boot.

The starter simplifies HTTP requests by allowing interfaces to be annotated with @RetrofitClient . It supports custom OkHttpClient injection, annotation‑based interceptors, connection‑pool management, logging, retry mechanisms, error decoders, global interceptors, circuit‑breaker (Sentinel) integration, and flexible YAML configuration.

Key Features

Custom OkHttpClient injection

Annotation‑based interceptors

Connection pool management

Log printing

Request retry

Error decoder

Global interceptors

Circuit‑breaker and degradation

Microservice HTTP calls

Call adapters and data converters

Quick Start

Dependency

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

Define HTTP Interface

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

Inject and Use

@Service
public class TestService {
    @Autowired
    private HttpApi httpApi;
    public void test() {
        // call httpApi methods
    }
}

Configuration

All features can be tuned via application.yml . Example:

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
  disable-void-return-type: false
  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

Advanced Features

Custom 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("person")
    Result
getPerson(@Query("id") Long id);
}

Annotation‑Based Interceptor

Implement a class extending BasePathMatchInterceptor and annotate the interface with @Intercept to apply it to specific URL patterns.

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

Circuit Breaker

Enable degradation with Sentinel by setting enable-degrade: true and configuring @Degrade or fallback classes on the Retrofit client.

Conclusion

The retrofit-spring-boot-starter offers a comprehensive, easy‑to‑use HTTP client solution for Spring Boot applications, combining Retrofit’s type‑safety with Spring’s configuration and bean management, and supporting advanced scenarios such as microservice calls, retry, logging, and circuit‑breaker handling.