Getting Started with Spring Cloud Square: A Retrofit‑Based Alternative to Feign

What is Spring Cloud Square

When talking about the Spring Cloud ecosystem, most developers are familiar with Feign. Feign hides the underlying HTTP client (OkHttp, HttpClient) and lets you call remote services as if they were local Spring MVC controllers, eliminating manual URL construction and JSON handling.

Spring Cloud Square aims to replace Spring Cloud Feign by wrapping Retrofit to implement cross‑service calls. The project is currently incubating in spring‑cloud‑incubator, similar to how spring‑cloud‑loadbalancer succeeded Ribbon.

Before using Spring Cloud Square, you should understand the following components:

OkHttp is a third‑party library that provides low‑level HTTP GET, POST, etc., and is one of the most popular networking frameworks.

Retrofit is a RESTful HTTP client built on top of OkHttp. It uses annotations to configure network parameters and supports various data formats (Gson, JSON, XML) and RxJava.

The service call architecture based on Spring Cloud Square looks like the diagram below.

Quick Start

Add Dependencies

Since spring‑cloud‑square is not officially released, you need to configure the Spring Maven repository.

<repositories>
  <repository>
    <id>spring-milestones</id>
    <url>https://repo.spring.io/milestone</url>
  </repository>
</repositories>

Maven dependencies

<dependency>
  <groupId>org.springframework.cloud</groupId>
  <artifactId>spring-cloud-square-okhttp</artifactId>
  <version>${square.version}</version>
</dependency>
<dependency>
  <groupId>com.squareup.okhttp3</groupId>
  <artifactId>okhttp</artifactId>
  <version>${okhttp.version}</version>
</dependency>
<!-- Add load‑balancer support -->
<dependency>
  <groupId>org.springframework.cloud</groupId>
  <artifactId>spring-cloud-starter-loadbalancer</artifactId>
</dependency>

Bean Configuration

@Bean
@LoadBalanced
public OkHttpClient.Builder okHttpClientBuilder() {
    return new OkHttpClient.Builder();
}

Code Invocation

Similar to the original Ribbon call, very simple.

@Autowired
OkHttpClient.Builder builder;

@GetMapping
public String req() {
    Request request = new Request.Builder()
        .url("http://square-provider/req").build();
    Response response = builder.build().newCall(request).execute();
    return response.body().string();
}

Advanced Usage

As a replacement for Spring Cloud Feign, Square also supports declarative clients. The code feels similar to Feign.

Add Dependency

<dependency>
  <groupId>org.springframework.cloud</groupId>
  <artifactId>spring-cloud-square-retrofit</artifactId>
  <version>${square.version}</version>
</dependency>

Declare Client Interface

@RetrofitClient("square-provider")
public interface DemoService {
    @GET("/req")
    Call<String> req();
}

Enable Client Scanning

@EnableRetrofitClients

Code Invocation

@Autowired
DemoService demoService;

@SneakyThrows
@GetMapping("/retrofit")
public String retrofit() {
    return demoService.req().execute().body();
}

Simplify

Retrofit can be extended to handle raw type returns, removing the default Call wrapper.

/**
 * Adapter that unwraps Call<T> and returns the raw type.
 */
@Configuration(proxyBeanMethods = false)
public class ApiCallAdapterFactory extends CallAdapter.Factory {
    @Override
    public CallAdapter<?, ?> get(@Nonnull Type returnType,
                                 @Nonnull Annotation[] annotations,
                                 @Nonnull Retrofit retrofit) {
        return new CallAdapter<>() {
            @Override
            public Type responseType() {
                return returnType;
            }
            @Override
            public Object adapt(@Nonnull Call<Object> call) {
                try {
                    return call.execute().body();
                } catch (IOException e) {
                    // custom fallback or rethrow
                    return null;
                }
            }
        };
    }
}

After adding the adapter, the client can be simplified to:

@RetrofitClient("square-provider")
public interface DemoService {
    @GET("/req")
    String req();
}

@Autowired
DemoService demoService;

@SneakyThrows
@GetMapping("/retrofit")
public String retrofit() {
    return demoService.req();
}

Summary

Spring Cloud Square is built directly on Retrofit, making the source code simple and worth reading.

The current version does not implement fallback functionality.

Source code: https://github.com/lltx/spring-cloud-square-demo