/spring-cloud-square

Spring Cloud auto-configuration of Retrofit and OkHttp (with Spring Cloud LoadBalancer).

Primary LanguageJavaApache License 2.0Apache-2.0

Spring Cloud Square

Build

Quick Start

This quick start walks through using SC LoadBalancer OkHttpClient integration, load-balanced OkHttpClient-based Retrofit clients, and load-balanced WebClient-based Retrofit clients.

OkHttpClient with Spring Cloud LoadBalancer

First, add the spring-cloud-square-okhttp dependency to your project:

<dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-square-okhttp</artifactId>
        <version>0.4.0</version>
</dependency>

Then create a @LoadBalanced-annotated OkHttpClient.Builder bean:

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

Now you can use the serviceId or virtual hostname rather than an actual host:port in your requests — SC LoadBalancer resolves it by selecting one of the available service instances.

Request request = new Request.Builder()
                        .url("http://serviceId/hello").build();
Response response = builder.build().newCall(request).execute();

Retrofit with OkHttpClient and Spring Cloud LoadBalancer

First, add the spring-cloud-square-retrofit and spring-cloud-square-okhttp dependencies to your project:

<dependencies>
    <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-square-retrofit</artifactId>
        <version>0.4.0</version>
    </dependency>
    <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-square-okhttp</artifactId>
        <version>0.4.0</version>
    </dependency>
</dependencies>

Use the @EnableRetrofitClients annotation to let us automatically instantiate and inject Retrofit clients for you. Then create a @LoadBalanced-annotated OkHttpClient.Builder bean to be used under the hood:

@Configuration
@EnableRetrofitClients
class OkHttpClientConfig {

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

Create a Retrofit client and annotate it with @RetrofitClient, passing the serviceId of your service as argument (the annotation can also be used to pass a custom configuration that contains user-crated interceptors for the Retrofit client):

@RetrofitClient("serviceId")
interface HelloClient {
    @GET("/")
    Call<String> hello();
}

Make sure to use Retrofit method annotations, such as @GET("/"). You can now inject the Retrofit client and use it to run load-balanced calls (by using serviceId instead of actual host:port):

class AService {

    @Autowired
    HelloClient client;

    public String hello() throws IOException {
        return client.hello().execute().body();
    }
}

Retrofit with WebClient and Spring Cloud LoadBalancer

First, add the spring-cloud-square-retrofit and spring-boot-starter-webflux starter dependencies to your project:

<dependencies>
    <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-square-retrofit</artifactId>
        <version>0.4.0</version>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-webflux</artifactId>
    </dependency>
</dependencies>

Use the @EnableRetrofitClients annotation to let us automatically instantiate and inject Retrofit clients for you. Then create a @LoadBalanced-annotated WebClient.Builder bean to be used under the hood:

@Configuration
@EnableRetrofitClients
class OkHttpClientConfig {

@Bean
@LoadBalanced
public WebClient.Builder webClientBuilder() {
    return WebClient.builder();
    }
}

Create a Retrofit client and annotate it with @RetrofitClient, passing the serviceId of your service as argument:

@RetrofitClient("serviceId")
interface HelloClient {
    @GET("/")
    Mono<String> hello();
}

Make sure to use Retrofit method annotations, such as @GET("/"). You can now inject the Retrofit client and use it to run load-balanced calls (by using serviceId instead of actual host:port):

class AService {

    @Autowired
    HelloClient client;

    public String hello() throws IOException {
        return client.hello();
    }
}
Tip
 As the currently available release is a milestone, you need to add the Spring Milestone repository link to your projects for all the examples presented in this blog entry: 
<repositories>
    <repository>
        <id>spring-milestones</id>
        <url>https://repo.spring.io/milestone</url>
    </repository>
</repositories>

We recommend using dependency management for other Spring Cloud dependencies:

<dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework.cloud</groupId>
                <artifactId>spring-cloud-dependencies</artifactId>
                <version>${spring-cloud.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
</dependencyManagement>

OkHttpClient integration with Spring Cloud

This module supplies integration with Square’s [OkHttpClient](https://square.github.io/okhttp/) and [Spring Cloud LoadBalancer](https://github.com/spring-cloud/spring-cloud-commons/spring-cloud-loadbalancer).

An application interceptor is added to the OkHttpClient created by auto-configuration which resolves the scheme, host, and port from Spring Cloud LoadBalancer and rewrites the URL.

By supporting OkHttpClient, it enables Square’s [Retrofit](https://square.github.io/retrofit/) to use Spring Cloud LoadBalancer as well.

Spring WebClient

Support was also added for Spring WebClient. This implements an okhttp3.Call.Factory that uses WebClient under the covers. This provides a fully non-blocking shim instead of using okhttp3.