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
```