0
# Spring Cloud Commons
1

2
Spring Cloud Commons provides foundational abstractions and utilities for building cloud-native applications with Spring. It offers essential components for service discovery, client-side load balancing, circuit breakers, service registration, and HTTP client management. This library serves as the foundation for various Spring Cloud implementations including Netflix, Consul, and other service discovery solutions.
3

4
## Package Information
5

6
- **Package Name**: spring-cloud-commons
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Add to your Maven `pom.xml`:
10

11
```xml
12
<dependency>
13
    <groupId>org.springframework.cloud</groupId>
14
    <artifactId>spring-cloud-commons</artifactId>
15
    <version>3.1.9</version>
16
</dependency>
17
```
18

19
For Gradle:
20

21
```gradle
22
implementation 'org.springframework.cloud:spring-cloud-commons:3.1.9'
23
```
24

25
## Core Imports
26

27
```java
28
// Service Discovery
29
import org.springframework.cloud.client.discovery.DiscoveryClient;
30
import org.springframework.cloud.client.discovery.ReactiveDiscoveryClient;
31
import org.springframework.cloud.client.discovery.EnableDiscoveryClient;
32

33
// Load Balancing
34
import org.springframework.cloud.client.loadbalancer.LoadBalanced;
35
import org.springframework.cloud.client.loadbalancer.LoadBalancerClient;
36

37
// Circuit Breakers
38
import org.springframework.cloud.client.circuitbreaker.CircuitBreaker;
39
import org.springframework.cloud.client.circuitbreaker.ReactiveCircuitBreaker;
40

41
// Service Registration
42
import org.springframework.cloud.client.serviceregistry.ServiceRegistry;
43
import org.springframework.cloud.client.serviceregistry.Registration;
44
```
45

46
## Basic Usage
47

48
```java
49
@SpringBootApplication
50
@EnableDiscoveryClient
51
public class MyCloudApplication {
52

53
    @Bean
54
    @LoadBalanced
55
    public RestTemplate restTemplate() {
56
        return new RestTemplate();
57
    }
58

59
    @Autowired
60
    private DiscoveryClient discoveryClient;
61
    
62
    @Autowired
63
    private LoadBalancerClient loadBalancer;
64

65
    public void makeServiceCall() {
66
        // Use service discovery
67
        List<ServiceInstance> instances = discoveryClient.getInstances("user-service");
68
        
69
        // Use load balancing
70
        ServiceInstance instance = loadBalancer.choose("user-service");
71
        
72
        // Make load-balanced HTTP calls
73
        String result = restTemplate().getForObject("http://user-service/users", String.class);
74
    }
75
}
76
```
77

78
## Architecture
79

80
Spring Cloud Commons is organized around several key abstractions:
81

82
- **Service Discovery**: Abstractions for registering, discovering, and monitoring services
83
- **Load Balancing**: Client-side load balancing with multiple algorithms and health checking
84
- **Circuit Breakers**: Resilience patterns for handling service failures
85
- **Service Registry**: Automatic service registration and health monitoring
86
- **HTTP Client Factories**: Configurable factories for Apache HttpClient and OkHttp
87
- **Reactive Support**: Full reactive programming model support for all components
88
- **Auto-Configuration**: Extensive Spring Boot auto-configuration for zero-config setup
89

90
## Capabilities
91

92
### Service Discovery
93

94
Core service discovery abstractions enabling applications to register with and discover services from various service registries.
95

96
```java { .api }
97
@EnableDiscoveryClient
98
public @interface EnableDiscoveryClient {
99
    boolean autoRegister() default true;
100
}
101

102
public interface DiscoveryClient extends Ordered {
103
    String description();
104
    List<ServiceInstance> getInstances(String serviceId);
105
    List<String> getServices();
106
    default void probe() {}
107
    int DEFAULT_ORDER = 0;
108
}
109

110
public interface ReactiveDiscoveryClient {
111
    String description();
112
    Flux<ServiceInstance> getInstances(String serviceId);
113
    Flux<String> getServices();
114
    default Mono<Void> reactiveProbe() { return Mono.empty(); }
115
}
116
```
117

118
[Service Discovery](./service-discovery.md)
119

120
### Load Balancing
121

122
Client-side load balancing with support for multiple algorithms, health checking, and retry mechanisms.
123

124
```java { .api }
125
@LoadBalanced
126
public @interface LoadBalanced {}
127

128
public interface LoadBalancerClient extends ServiceInstanceChooser {
129
    <T> T execute(String serviceId, LoadBalancerRequest<T> request) throws IOException;
130
    <T> T execute(String serviceId, ServiceInstance serviceInstance, LoadBalancerRequest<T> request) throws IOException;
131
    URI reconstructURI(ServiceInstance instance, URI original);
132
}
133

134
public interface ServiceInstanceChooser {
135
    ServiceInstance choose(String serviceId);
136
    <T> ServiceInstance choose(String serviceId, Request<T> request);
137
}
138
```
139

140
[Load Balancing](./load-balancing.md)
141

142
### Circuit Breakers
143

144
Resilience patterns for handling service failures with support for both synchronous and reactive programming models.
145

146
```java { .api }
147
public interface CircuitBreaker {
148
    <T> T run(Supplier<T> toRun);
149
    <T> T run(Supplier<T> toRun, Function<Throwable, T> fallback);
150
}
151

152
public interface ReactiveCircuitBreaker {
153
    <T> Mono<T> run(Mono<T> toRun);
154
    <T> Mono<T> run(Mono<T> toRun, Function<Throwable, Mono<T>> fallback);
155
    <T> Flux<T> run(Flux<T> toRun);
156
    <T> Flux<T> run(Flux<T> toRun, Function<Throwable, Flux<T>> fallback);
157
}
158
```
159

160
[Circuit Breakers](./circuit-breakers.md)
161

162
### Service Registration
163

164
Automatic service registration and health monitoring with support for various service registries.
165

166
```java { .api }
167
public interface ServiceRegistry<R extends Registration> {
168
    void register(R registration);
169
    void deregister(R registration);
170
    void close();
171
    void setStatus(R registration, String status);
172
    <T> T getStatus(R registration);
173
}
174

175
public interface Registration extends ServiceInstance {}
176

177
public interface AutoServiceRegistration {
178
    void start();
179
    void stop();
180
    boolean isRunning();
181
}
182
```
183

184
[Service Registration](./service-registration.md)
185

186
### HTTP Client Management
187

188
Configurable factories for HTTP clients with support for Apache HttpClient and OkHttp.
189

190
```java { .api }
191
public interface ApacheHttpClientFactory {
192
    HttpClientBuilder createBuilder();
193
    CloseableHttpClient createHttpClient();
194
}
195

196
public interface OkHttpClientFactory {
197
    OkHttpClient.Builder createBuilder(boolean disableSslValidation);
198
    OkHttpClient createHttpClient();
199
}
200
```
201

202
[HTTP Client Management](./http-clients.md)
203

204
### Reactive Programming Support
205

206
Enhanced reactive utilities and operators for cloud-native applications.
207

208
```java { .api }
209
public abstract class CloudFlux<T> extends Flux<T> {
210
    public static <I> Flux<I> firstNonEmpty(Publisher<? extends I>... publishers);
211
    public static <I> Flux<I> firstNonEmpty(Iterable<? extends Publisher<? extends I>> publishers);
212
}
213
```
214

215
[Reactive Support](./reactive-support.md)
216

217
## Configuration Properties
218

219
Key configuration properties for customizing Spring Cloud Commons behavior:
220

221
```properties
222
# Discovery
223
spring.cloud.discovery.enabled=true
224
spring.cloud.discovery.client.health-indicator.enabled=true
225

226
# Load Balancer
227
spring.cloud.loadbalancer.retry.enabled=true
228
spring.cloud.loadbalancer.health-check.enabled=true
229

230
# Service Registry
231
spring.cloud.service-registry.auto-registration.enabled=true
232
spring.cloud.service-registry.auto-registration.fail-fast=false
233

234
# Network Utilities
235
spring.cloud.inetutils.preferred-networks=192.168.
236
spring.cloud.inetutils.ignored-interfaces=docker0,veth.*
237
```
238

239
## Common Types
240

241
```java { .api }
242
public interface ServiceInstance {
243
    default String getInstanceId() { return null; }
244
    String getServiceId();
245
    String getHost();
246
    int getPort();
247
    boolean isSecure();
248
    URI getUri();
249
    Map<String, String> getMetadata();
250
    default String getScheme() { return null; }
251
}
252

253
public class DefaultServiceInstance implements ServiceInstance {
254
    public DefaultServiceInstance(String instanceId, String serviceId, 
255
                                 String host, int port, boolean secure);
256
    public DefaultServiceInstance(String instanceId, String serviceId, 
257
                                 String host, int port, boolean secure, 
258
                                 Map<String, String> metadata);
259
    public static URI getUri(ServiceInstance instance);
260
}
261

262
public interface LoadBalancerRequest<T> {
263
    T apply(ServiceInstance instance) throws Exception;
264
}
265

266
public interface Request<C> {
267
    default C getContext() { return null; }
268
}
269
```