LianjiaTech retrofit-spring-boot-starter for Java HTTP APIs

Why retrofit-spring-boot-starter Exists in a Spring Boot Service

Retrofit represents an HTTP endpoint as a Java interface. Without Spring Boot integration, an application still has to arrange client construction, converter selection, and sharing of the resulting Retrofit service. LianjiaTech/retrofit-spring-boot-starter fills that application-level gap: it discovers interfaces marked with `@RetrofitClient`, registers them through Spring, and allows other Spring services to inject them.

The intended audience is developers building Java HTTP clients inside Spring Boot applications. The project is not a general HTTP client library and it does not replace Retrofit. It preserves Retrofit annotations such as `@GET`, `@POST`, `@Body`, and `@Query`, while adding Spring-oriented registration and configuration. Its feature list also covers operational concerns that normally require separate integration code, including method-level timeouts, logging, retries, interceptors, circuit-breaking and fallback behavior, error decoding, Micrometer metrics, and an Actuator endpoint.

This makes the starter most relevant when several application services consume HTTP APIs and should share a consistent setup. Its value is narrower for an application with one manually managed Retrofit instance. In that case, direct Retrofit may involve fewer moving parts. The decision is not simply Retrofit versus no HTTP library. It is whether Spring should own client discovery and configuration as part of the application context.

How @RetrofitClient Interfaces Become Spring Beans

The visible data path begins with Spring component scanning. By default, the starter uses the Spring Boot scan path to locate interfaces carrying `@RetrofitClient`. Applications that need a different boundary can place `@RetrofitScan` on a configuration class and specify the scan path there. This gives the starter a registration point independent of the package in which an individual consumer service happens to live.

After discovery, the interface remains the declaration of the HTTP contract. A method such as `@POST("getName") String getName(@Query("id") Long id);` asks Retrofit to construct an HTTP request, while the starter makes the interface available to Spring injection. A separate `@Service` class receives it through `@Autowired` and invokes it like another injected dependency.

Request construction remains Retrofit's responsibility. The method annotation chooses the HTTP operation, `@Query` places an argument in the query string, and the return type is handled through the configured Retrofit converter behavior. The starter additionally documents automatic HTTP response adaptation and configurable converter factories. Its OkHttp customization and `Call.Factory` SPI indicate that client transport is also part of the integration layer rather than being fixed by the starter.

One path detail is easy to misread. Retrofit resolves a relative method path against `baseUrl`, but a method path beginning with `/` produces an absolute path. For example, with a base URL ending in `/api/test/`, `person` resolves below that base path, while `/person` resolves from the host root. That behavior comes from Retrofit's URL construction rules and remains visible through the starter.

Installing 4.2.1 and Injecting the First Retrofit Interface

The README directs Spring Boot 3.x and 4.x users to version 4.x and gives `4.2.1` as the dependency version. Add this Maven dependency to the Spring Boot project:

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

The README states that the dependency can be used after it is introduced. It does not provide a separate starter-specific initialization command.

Define the HTTP interface and mark it with the required `@RetrofitClient` annotation:

@RetrofitClient(baseUrl = "http://localhost:8080/api/user/")
public interface UserService {

    /**
     * 根据id查询用户姓名
     */
    @POST("getName")
    String getName(@Query("id") Long id);
}

The `baseUrl` supplies the service root, while `getName` supplies the relative endpoint and `@Query("id")` names the query parameter. Do not begin a method request path with `/` unless replacing the entire path below the host is intentional.

Inject the interface into a Spring service using normal field injection:

@Service
public class BusinessService {

    @Autowired
    private UserService userService;

    public void doBusiness() {
        // 调用 userService
    }
}

If the default scan path does not find `UserService`, the documented alternative is to add `@RetrofitScan` to a configuration class and specify the relevant package. This is the first integration boundary to inspect when a correctly annotated interface cannot be injected.

Response Handling, Transport Customization, and Operational Extensions

The starter does not stop at bean creation. Its documented response-adaptation layer can adapt HTTP results for application code, and its converter documentation permits custom data converters. That matters when endpoint return types do not match a single default serialization policy or when an application needs a specific converter factory.

Transport configuration is also extensible. The project documents custom `OkHttpClient` construction and a `Call.Factory` SPI. These are separate control points: `OkHttpClient` is the documented OkHttp integration, while `Call.Factory` allows Retrofit's transport dependency to be supplied through its factory abstraction. The README does not provide enough detail here to claim that either mechanism changes retry or timeout behavior by itself.

Method-level timeout configuration addresses requests that need different limits within one client. Logging, request retries, and interceptors address diagnostics and request processing. Degradation support adds circuit-breaking and fallback behavior, while error decoders address non-success response bodies. These extensions are listed as supported features with separate documentation files under `docs/cn/`; the short README does not specify their complete defaults.

Monitoring support includes Micrometer metrics and an Actuator endpoint. Microservice HTTP calls and GraalVM Native Image or AOT support are also documented. These are relevant to a service architecture rather than a one-file demonstration. Still, the feature list establishes availability, not a guarantee that every module is enabled without configuration. The project has separate reference files for metrics, Actuator, AOT, retry, degradation, and full configuration, so those are the sources to consult before assuming a feature is active.

Spring Boot and Jackson Compatibility Boundaries

The clearest adoption constraint is the version split. Spring Boot 3.x and 4.x projects use `retrofit-spring-boot-starter` 4.x. Spring Boot 1.x and 2.x projects use the separate 2.x branch, which the README says supports Spring Boot 1.4.2 and later. Applying the documented dependency choice to the wrong Boot generation can produce a compatibility problem before application code is considered.

Spring Boot 4 adds another specific boundary. The README states that Spring Boot 4 uses Jackson 3 by default, while the starter's default Converter uses Jackson 2. It recommends setting the global Converter to the Jackson 3 factory for 4.x applications. The documented property and value are:

retrofit.global-converter-factories=com.github.lianjiatech.retrofit.spring.boot.core.jackson3.Jackson3ConverterFactory

This is a real migration issue for applications that need Jackson 3 behavior. Omitting the setting may leave Spring Boot 4 applications with a converter based on Jackson 2 rather than the version expected by the wider application.

There are other documented limits. HTTP request annotations come from Retrofit rather than a starter-specific set. The README does not document rollback, binary compatibility across every `4.x` release, or the upgrade procedure between releases, so those points cannot be assumed. The latest listed releases are `4.2.1` from 2026-08-08 and `4.2.0` from 2026-06-05, while `2.6.0` was also listed on 2026-06-05. The last push was on 2026-09-14, so the repository is not archived and has recent development activity, but the README still does not provide a migration guide.

Direct Retrofit Compared with Starter-Managed Retrofit

Plain Retrofit is the direct alternative. Both approaches let developers declare endpoints with a Java interface and Retrofit annotations. The difference is who assembles and exposes those clients. The starter builds that relationship into Spring Boot scanning and dependency injection.

This trade-off favors the starter when an application already relies on Spring configuration and several services consume Retrofit interfaces. Shared timeout, logging, interceptor, retry, degradation, metrics, or Actuator behavior also makes the integration more relevant. The starter's separate documentation files indicate that these features have dedicated configuration rather than being a single opaque setup.

Direct Retrofit remains the better fit when Spring Boot owns little of the application, only one client is needed, or minimizing framework dependencies is a primary constraint. The starter does not improve every Retrofit application equally. Its cost is that bean discovery, converter selection, scan boundaries, and Boot-version compatibility become part of the integration contract.

The project is licensed under Apache-2.0. That identifier defines the license governing the distributed source, but choosing a branch does not remove the need to review its license text and compatibility with the rest of the application's dependencies. The README also links to the Apache License 2.0.

Editorial conclusion

Adopt this starter when a Spring Boot service needs injectable Retrofit clients plus response adaptation, timeouts, interceptors, retries, metrics, or degradation support. Do not choose it merely to avoid adding a Retrofit dependency, and do not use its 4.x line with Spring Boot 1.x or 2.x. Verify first that your Spring Boot generation and Jackson version match the documented branch and converter configuration, then confirm the requested operational features against your application's current infrastructure.

Frequently asked questions

Official sources

1. Issues
2. LianjiaTech/retrofit-spring-boot-starter on GitHub
3. License: Apache-2.0
4. README
5. Releases