0
# Service Discovery
1

2
Service discovery enables applications to register with and discover services from various service registries without hardcoding service locations. Spring Cloud Commons provides abstractions for both blocking and reactive discovery clients.
3

4
## Capabilities
5

6
### Enable Discovery Client
7

8
Enables service discovery functionality in your Spring Boot application.
9

10
```java { .api }
11
/**
12
 * Enables discovery client functionality
13
 * @param autoRegister - Whether to automatically register with service registry
14
 */
15
@EnableDiscoveryClient
16
public @interface EnableDiscoveryClient {
17
    boolean autoRegister() default true;
18
}
19
```
20

21
**Usage Example:**
22

23
```java
24
@SpringBootApplication
25
@EnableDiscoveryClient(autoRegister = true)
26
public class MyApplication {
27
    public static void main(String[] args) {
28
        SpringApplication.run(MyApplication.class, args);
29
    }
30
}
31
```
32

33
### Discovery Client Interface
34

35
Main interface for service discovery operations.
36

37
```java { .api }
38
/**
39
 * Main interface for service discovery operations
40
 */
41
public interface DiscoveryClient extends Ordered {
42
    /**
43
     * @return A human readable description of the implementation
44
     */
45
    String description();
46
    
47
    /**
48
     * Get all ServiceInstances associated with a particular serviceId
49
     * @param serviceId The serviceId to query
50
     * @return A List of ServiceInstance
51
     */
52
    List<ServiceInstance> getInstances(String serviceId);
53
    
54
    /**
55
     * @return All known service ids
56
     */
57
    List<String> getServices();
58
    
59
    /**
60
     * Can be used to test the status of the discovery client
61
     */
62
    default void probe() {}
63
    
64
    int DEFAULT_ORDER = 0;
65
}
66
```
67

68
**Usage Examples:**
69

70
```java
71
@Autowired
72
private DiscoveryClient discoveryClient;
73

74
public void discoverServices() {
75
    // Get all services
76
    List<String> services = discoveryClient.getServices();
77
    
78
    // Get instances of a specific service
79
    List<ServiceInstance> instances = discoveryClient.getInstances("user-service");
80
    
81
    // Check first available instance
82
    if (!instances.isEmpty()) {
83
        ServiceInstance instance = instances.get(0);
84
        String url = instance.getUri().toString();
85
        // Use the service URL
86
    }
87
}
88
```
89

90
### Reactive Discovery Client
91

92
Reactive interface for service discovery operations using Project Reactor.
93

94
```java { .api }
95
/**
96
 * Reactive interface for service discovery operations
97
 */
98
public interface ReactiveDiscoveryClient {
99
    /**
100
     * @return A human readable description of the implementation
101
     */
102
    String description();
103
    
104
    /**
105
     * Get all ServiceInstances associated with a particular serviceId
106
     * @param serviceId The serviceId to query
107
     * @return A Flux that will emit all ServiceInstance that are registered under the given ID
108
     */
109
    Flux<ServiceInstance> getInstances(String serviceId);
110
    
111
    /**
112
     * @return A Flux that will emit all known service ids
113
     */
114
    Flux<String> getServices();
115
    
116
    /**
117
     * Can be used to test the status of the discovery client
118
     * @return Empty Mono on success, error Mono on failure
119
     */
120
    default Mono<Void> reactiveProbe() {
121
        return Mono.empty();
122
    }
123
    
124
    /**
125
     * @deprecated Use reactiveProbe() instead
126
     */
127
    @Deprecated
128
    default void probe() {}
129
}
130
```
131

132
**Usage Examples:**
133

134
```java
135
@Autowired
136
private ReactiveDiscoveryClient reactiveDiscoveryClient;
137

138
public Mono<String> discoverServiceReactively() {
139
    return reactiveDiscoveryClient
140
        .getInstances("user-service")
141
        .next() // Get first instance
142
        .map(ServiceInstance::getUri)
143
        .map(URI::toString);
144
}
145

146
public Flux<String> getAllServicesReactively() {
147
    return reactiveDiscoveryClient.getServices();
148
}
149
```
150

151
### Service Instance
152

153
Represents a service instance in the discovery system.
154

155
```java { .api }
156
/**
157
 * Represents a service instance
158
 */
159
public interface ServiceInstance {
160
    /**
161
     * @return The unique instance ID as registered
162
     */
163
    default String getInstanceId() {
164
        return null;
165
    }
166
    
167
    /**
168
     * @return The service ID as registered
169
     */
170
    String getServiceId();
171
    
172
    /**
173
     * @return The hostname of the registered ServiceInstance
174
     */
175
    String getHost();
176
    
177
    /**
178
     * @return The port of the registered ServiceInstance
179
     */
180
    int getPort();
181
    
182
    /**
183
     * @return Whether the port of the registered ServiceInstance is secure/https
184
     */
185
    boolean isSecure();
186
    
187
    /**
188
     * @return The service URI address
189
     */
190
    URI getUri();
191
    
192
    /**
193
     * @return The key/value pair metadata associated with the ServiceInstance
194
     */
195
    Map<String, String> getMetadata();
196
    
197
    /**
198
     * @return The scheme of the ServiceInstance
199
     */
200
    default String getScheme() {
201
        return null;
202
    }
203
}
204
```
205

206
### Default Service Instance
207

208
Default implementation of ServiceInstance.
209

210
```java { .api }
211
/**
212
 * Default implementation of ServiceInstance
213
 */
214
public class DefaultServiceInstance implements ServiceInstance {
215
    /**
216
     * Create a new DefaultServiceInstance
217
     */
218
    public DefaultServiceInstance(String instanceId, String serviceId, 
219
                                 String host, int port, boolean secure);
220
                                 
221
    /**
222
     * Create a new DefaultServiceInstance with metadata
223
     */
224
    public DefaultServiceInstance(String instanceId, String serviceId, 
225
                                 String host, int port, boolean secure, 
226
                                 Map<String, String> metadata);
227
    
228
    /**
229
     * Utility method to get URI from ServiceInstance
230
     * @param instance The service instance
231
     * @return URI for the instance
232
     */
233
    public static URI getUri(ServiceInstance instance);
234
}
235
```
236

237
### Discovery Events
238

239
Events fired during discovery operations.
240

241
```java { .api }
242
/**
243
 * Event published when heartbeat is received from discovery server
244
 */
245
public class HeartbeatEvent extends ApplicationEvent {
246
    public HeartbeatEvent(Object source, Object value);
247
    public Object getValue();
248
}
249

250
/**
251
 * Event published when a service instance is registered
252
 */
253
public class InstanceRegisteredEvent<T> extends ApplicationEvent {
254
    public InstanceRegisteredEvent(Object source, T config);
255
    public T getConfig();
256
}
257

258
/**
259
 * Event published before a service instance is registered
260
 */  
261
public class InstancePreRegisteredEvent extends ApplicationEvent {
262
    public InstancePreRegisteredEvent(Object source, Registration registration);
263
    public Registration getRegistration();
264
}
265

266
/**
267
 * Heartbeat event from parent context
268
 */
269
public class ParentHeartbeatEvent extends ApplicationEvent {
270
    public ParentHeartbeatEvent(Object source, Object value);
271
    public Object getValue();
272
}
273
```
274

275
### Heartbeat Monitor  
276

277
Utility for monitoring heartbeat state changes.
278

279
```java { .api }
280
/**
281
 * Utility for monitoring heartbeat state changes
282
 */
283
public class HeartbeatMonitor {
284
    public HeartbeatMonitor();
285
    
286
    /**
287
     * Update with new heartbeat value
288
     * @param value New heartbeat value
289
     * @return Heartbeat state
290
     */
291
    public HeartbeatState update(Object value);
292
    
293
    /**
294
     * Get current heartbeat state
295
     * @return Current state
296
     */
297
    public HeartbeatState getState();
298
    
299
    public enum HeartbeatState {
300
        UNCHANGED, CHANGED
301
    }
302
}
303
```
304

305
### Health Indicators
306

307
Health check integration for discovery clients.
308

309
```java { .api }
310
/**
311
 * Health indicator interface for discovery clients
312
 */
313
public interface DiscoveryHealthIndicator {
314
    /**
315
     * @return Description of the discovery client
316
     */
317
    String getName();
318
    
319
    /**
320
     * @return Health check result
321
     */
322
    Health health();
323
}
324

325
/**
326
 * Health indicator implementation for discovery clients
327
 */
328
public class DiscoveryClientHealthIndicator implements DiscoveryHealthIndicator, HealthIndicator {
329
    public DiscoveryClientHealthIndicator(DiscoveryClient discoveryClient, 
330
                                        DiscoveryClientHealthIndicatorProperties properties);
331
}
332

333
/**
334
 * Reactive health indicator for discovery clients
335
 */
336
public interface ReactiveDiscoveryHealthIndicator {
337
    String getName();
338
    Mono<Health> health();
339
}
340

341
/**
342
 * Configuration properties for discovery health indicators
343
 */
344
@ConfigurationProperties(prefix = "spring.cloud.discovery.client.health-indicator")
345
public class DiscoveryClientHealthIndicatorProperties {
346
    private boolean enabled = true;
347
    private boolean includeDescription = false;
348
    // getters and setters
349
}
350
```
351

352
### Simple Discovery Implementation
353

354
Simple in-memory discovery client for development and testing.
355

356
```java { .api }
357
/**
358
 * Simple in-memory discovery client
359
 */
360
public class SimpleDiscoveryClient implements DiscoveryClient {
361
    public SimpleDiscoveryClient(SimpleDiscoveryProperties properties);
362
}
363

364
/**
365
 * Configuration properties for simple discovery client
366
 */
367
@ConfigurationProperties(prefix = "spring.cloud.discovery.client.simple")
368
public class SimpleDiscoveryProperties {
369
    private Map<String, List<DefaultServiceInstance>> instances = new HashMap<>();
370
    private boolean local = true;
371
    // getters and setters
372
}
373

374
/**
375
 * Reactive simple discovery client
376
 */
377
public class SimpleReactiveDiscoveryClient implements ReactiveDiscoveryClient {
378
    public SimpleReactiveDiscoveryClient(SimpleReactiveDiscoveryProperties properties);
379
}
380
```
381

382
### Composite Discovery
383

384
Combines multiple discovery clients into a single interface.
385

386
```java { .api }
387
/**
388
 * Combines multiple discovery clients
389
 */
390
public class CompositeDiscoveryClient implements DiscoveryClient {
391
    public CompositeDiscoveryClient(List<DiscoveryClient> discoveryClients);
392
}
393

394
/**
395
 * Reactive composite discovery client
396
 */
397
public class ReactiveCompositeDiscoveryClient implements ReactiveDiscoveryClient {
398
    public ReactiveCompositeDiscoveryClient(List<ReactiveDiscoveryClient> discoveryClients);
399
}
400
```
401

402
## Configuration Properties
403

404
```properties
405
# Enable/disable discovery client
406
spring.cloud.discovery.enabled=true
407

408
# Simple discovery client configuration  
409
spring.cloud.discovery.client.simple.local=true
410
spring.cloud.discovery.client.simple.instances.service1[0].uri=http://localhost:8081
411
spring.cloud.discovery.client.simple.instances.service2[0].uri=http://localhost:8082
412

413
# Health indicator configuration
414
spring.cloud.discovery.client.health-indicator.enabled=true
415
spring.cloud.discovery.client.health-indicator.include-description=false
416
```