0
# Apache Dubbo
1

2
Apache Dubbo is a powerful and user-friendly RPC framework that provides solutions for communication, service discovery, traffic management, observability, security, and tooling for building enterprise-grade microservices. It supports multiple protocols including Triple (gRPC-compatible), Dubbo2 (TCP), and REST, with comprehensive service discovery, load balancing, and fault tolerance capabilities.
3

4
## Package Information
5

6
- **Package Name**: org.apache.dubbo:dubbo
7
- **Package Type**: maven
8
- **Language**: Java
9
- **JDK Requirements**: Java 8 or higher
10
- **Installation**: Add dependency to your Maven or Gradle project
11
- **Documentation**: https://dubbo.apache.org/
12

13
## Core Imports
14

15
```java
16
// Core bootstrap and configuration
17
import org.apache.dubbo.config.bootstrap.DubboBootstrap;
18
import org.apache.dubbo.config.ApplicationConfig;
19
import org.apache.dubbo.config.ProtocolConfig;
20
import org.apache.dubbo.config.RegistryConfig;
21

22
// Service definition and consumption
23
import org.apache.dubbo.config.ServiceConfig;
24
import org.apache.dubbo.config.ReferenceConfig;
25

26
// Spring Boot integration
27
import org.apache.dubbo.config.spring.context.annotation.EnableDubbo;
28
import org.apache.dubbo.config.annotation.DubboService;
29
import org.apache.dubbo.config.annotation.DubboReference;
30

31
// Core RPC interfaces
32
import org.apache.dubbo.rpc.Invoker;
33
import org.apache.dubbo.rpc.RpcContext;
34
import org.apache.dubbo.rpc.service.GenericService;
35

36
// Extension system
37
import org.apache.dubbo.common.extension.ExtensionLoader;
38
import org.apache.dubbo.common.extension.SPI;
39
import org.apache.dubbo.common.extension.Adaptive;
40
import org.apache.dubbo.common.extension.Activate;
41

42
// Metadata management
43
import org.apache.dubbo.config.MetadataReportConfig;
44
import org.apache.dubbo.metadata.MetadataService;
45

46
// URL and parameters
47
import org.apache.dubbo.common.URL;
48
```
49

50
Maven dependency:
51
```xml
52
<dependency>
53
    <groupId>org.apache.dubbo</groupId>
54
    <artifactId>dubbo</artifactId>
55
    <version>3.3.5</version>
56
</dependency>
57
```
58

59
Spring Boot starter:
60
```xml
61
<dependency>
62
    <groupId>org.apache.dubbo</groupId>
63
    <artifactId>dubbo-spring-boot-starter</artifactId>
64
    <version>3.3.5</version>
65
</dependency>
66
```
67

68
## Basic Usage
69

70
### Programmatic Bootstrap
71

72
```java
73
import org.apache.dubbo.config.bootstrap.DubboBootstrap;
74
import org.apache.dubbo.config.*;
75

76
// Initialize Dubbo application
77
DubboBootstrap bootstrap = DubboBootstrap.getInstance();
78

79
// Configure application
80
ApplicationConfig application = new ApplicationConfig("my-app");
81
ProtocolConfig protocol = new ProtocolConfig("dubbo", 20880);
82
RegistryConfig registry = new RegistryConfig("zookeeper://127.0.0.1:2181");
83

84
// Bootstrap configuration
85
bootstrap.application(application)
86
         .protocol(protocol)
87
         .registry(registry);
88

89
// Export a service
90
ServiceConfig<GreeterService> service = new ServiceConfig<>();
91
service.setInterface(GreeterService.class);
92
service.setRef(new GreeterServiceImpl());
93
bootstrap.service(service);
94

95
// Reference a service
96
ReferenceConfig<GreeterService> reference = new ReferenceConfig<>();
97
reference.setInterface(GreeterService.class);
98
bootstrap.reference(reference);
99

100
// Start Dubbo
101
bootstrap.start();
102

103
// Use the service
104
GreeterService greeter = reference.get();
105
String greeting = greeter.sayHello("World");
106
```
107

108
### Spring Boot Integration
109

110
```java
111
@SpringBootApplication
112
@EnableDubbo
113
public class DubboApplication {
114
    public static void main(String[] args) {
115
        SpringApplication.run(DubboApplication.class, args);
116
    }
117
}
118

119
// Service provider
120
@DubboService
121
public class GreeterServiceImpl implements GreeterService {
122
    public String sayHello(String name) {
123
        return "Hello, " + name + "!";
124
    }
125
}
126

127
// Service consumer
128
@RestController
129
public class GreeterController {
130
    
131
    @DubboReference
132
    private GreeterService greeterService;
133
    
134
    @GetMapping("/greet/{name}")
135
    public String greet(@PathVariable String name) {
136
        return greeterService.sayHello(name);
137
    }
138
}
139
```
140

141
Application properties:
142
```properties
143
dubbo.application.name=my-dubbo-app
144
dubbo.protocol.name=dubbo
145
dubbo.protocol.port=20880
146
dubbo.registry.address=zookeeper://127.0.0.1:2181
147
```
148

149
## Architecture
150

151
Apache Dubbo follows a layered architecture with these key components:
152

153
- **Configuration Layer**: Provides programmatic and declarative configuration options through various config classes and Spring Boot integration
154
- **RPC Layer**: Core remote procedure call abstraction with protocol-independent service invocation
155
- **Registry Layer**: Service discovery and registration with support for multiple backends (ZooKeeper, Nacos, Consul, etc.)
156
- **Cluster Layer**: Load balancing, fault tolerance, and routing with multiple strategies
157
- **Remoting Layer**: Network communication abstraction supporting various protocols and transports
158
- **Serialization Layer**: Pluggable serialization with multiple protocol support (Protocol Buffers, Hessian, JSON)
159
- **Extension System**: SPI-based architecture for customizing all major components
160

161
## Capabilities
162

163
### Application Bootstrap and Configuration
164

165
Core application lifecycle management and configuration system supporting both programmatic and declarative approaches.
166

167
```java { .api }
168
// Main bootstrap entry point
169
public class DubboBootstrap {
170
    public static DubboBootstrap getInstance();
171
    public DubboBootstrap application(ApplicationConfig application);
172
    public DubboBootstrap protocol(ProtocolConfig protocol);
173
    public DubboBootstrap registry(RegistryConfig registry);
174
    public DubboBootstrap service(ServiceConfig<?> service);
175
    public DubboBootstrap reference(ReferenceConfig<?> reference);
176
    public DubboBootstrap start();
177
    public DubboBootstrap stop();
178
}
179

180
// Application configuration
181
public class ApplicationConfig extends AbstractConfig {
182
    public ApplicationConfig(String name);
183
    public void setName(String name);
184
    public void setVersion(String version);
185
    public void setOwner(String owner);
186
}
187
```
188

189
[Configuration and Bootstrap](./configuration.md)
190

191
### RPC Core System
192

193
Foundation RPC abstractions for service invocation, proxy creation, and request/response processing.
194

195
```java { .api }
196
// Core service invoker
197
public interface Invoker<T> {
198
    Result invoke(Invocation invocation) throws RpcException;
199
    Class<T> getInterface();
200
    URL getUrl();
201
    boolean isAvailable();
202
    void destroy();
203
}
204

205
// RPC invocation context
206
public class RpcContext {
207
    public static RpcContext getContext();
208
    public RpcContext setAttachment(String key, String value);
209
    public String getAttachment(String key);
210
    public boolean isProviderSide();
211
    public boolean isConsumerSide();
212
}
213

214
// Generic service invocation
215
public interface GenericService {
216
    Object $invoke(String method, String[] parameterTypes, Object[] args) 
217
        throws GenericException;
218
    CompletableFuture<Object> $invokeAsync(String method, String[] parameterTypes, Object[] args);
219
}
220
```
221

222
[RPC Core](./rpc-core.md)
223

224
### Service Discovery and Registry
225

226
Service registration and discovery with support for multiple registry backends and dynamic service management.
227

228
```java { .api }
229
// Registry interface
230
public interface Registry {
231
    void register(URL url);
232
    void unregister(URL url);
233
    void subscribe(URL url, NotifyListener listener);
234
    void unsubscribe(URL url, NotifyListener listener);
235
    List<URL> lookup(URL url);
236
}
237

238
// Registry factory
239
public interface RegistryFactory {
240
    Registry getRegistry(URL url);
241
}
242

243
// Configuration
244
public class RegistryConfig extends AbstractConfig {
245
    public void setAddress(String address);
246
    public void setProtocol(String protocol);
247
    public void setUsername(String username);
248
    public void setPassword(String password);
249
}
250
```
251

252
[Service Discovery](./registry.md)
253

254
### Clustering and Load Balancing
255

256
Advanced clustering strategies for fault tolerance, load balancing, and traffic management across multiple service providers.
257

258
```java { .api }
259
// Cluster fault tolerance strategies
260
public interface Cluster {
261
    <T> Invoker<T> join(Directory<T> directory) throws RpcException;
262
}
263

264
// Load balancing algorithms
265
public interface LoadBalance {
266
    <T> Invoker<T> select(List<Invoker<T>> invokers, URL url, Invocation invocation) 
267
        throws RpcException;
268
}
269

270
// Provider directory management
271
public interface Directory<T> {
272
    Class<T> getInterface();
273
    List<Invoker<T>> list(Invocation invocation) throws RpcException;
274
    List<Invoker<T>> getAllInvokers();
275
    URL getUrl();
276
    boolean isDestroyed();
277
}
278
```
279

280
[Clustering and Load Balancing](./clustering.md)
281

282
### Spring Boot Integration
283

284
Comprehensive Spring Boot integration with auto-configuration, annotations, and properties-based configuration.
285

286
```java { .api }
287
// Enable Dubbo in Spring applications
288
@Target(ElementType.TYPE)
289
@Retention(RetentionPolicy.RUNTIME)
290
@Import(DubboComponentScanRegistrar.class)
291
public @interface EnableDubbo {
292
    String[] scanBasePackages() default {};
293
    Class<?>[] scanBasePackageClasses() default {};
294
}
295

296
// Service provider annotation
297
@Target(ElementType.TYPE)
298
@Retention(RetentionPolicy.RUNTIME)
299
public @interface DubboService {
300
    String version() default "";
301
    String group() default "";
302
    String protocol() default "";
303
    int timeout() default -1;
304
    int retries() default -1;
305
}
306

307
// Service consumer annotation
308
@Target({ElementType.FIELD, ElementType.METHOD, ElementType.ANNOTATION_TYPE})
309
@Retention(RetentionPolicy.RUNTIME)
310
public @interface DubboReference {
311
    String version() default "";
312
    String group() default "";
313
    int timeout() default -1;
314
    boolean async() default false;
315
}
316
```
317

318
[Spring Boot Integration](./spring-boot.md)
319

320
### Extension System
321

322
SPI-based extension system enabling customization of all major Dubbo components including protocols, load balancers, and registries.
323

324
```java { .api }
325
// Extension point marker
326
@Target(ElementType.TYPE)
327
@Retention(RetentionPolicy.RUNTIME)
328
public @interface SPI {
329
    String value() default "";
330
    ExtensionScope scope() default ExtensionScope.FRAMEWORK;
331
}
332

333
// Extension loading and management
334
public class ExtensionLoader<T> {
335
    public static <T> ExtensionLoader<T> getExtensionLoader(Class<T> type);
336
    public T getExtension(String name);
337
    public T getAdaptiveExtension();
338
    public T getDefaultExtension();
339
    public List<T> getActivateExtensions(URL url, String[] values, String group);
340
    public Set<String> getSupportedExtensions();
341
    public boolean hasExtension(String name);
342
}
343

344
// Adaptive extension selection
345
@Target({ElementType.METHOD, ElementType.TYPE})
346
@Retention(RetentionPolicy.RUNTIME)  
347
public @interface Adaptive {
348
    String[] value() default {};
349
}
350

351
// Extension activation
352
@Target(ElementType.TYPE)
353
@Retention(RetentionPolicy.RUNTIME)
354
public @interface Activate {
355
    String[] group() default {};
356
    String[] value() default {};
357
    String[] before() default {};
358
    String[] after() default {};
359
    int order() default 0;
360
}
361
```
362

363
[Extension System](./extensions.md)
364

365
### Metadata Management
366

367
Comprehensive service metadata collection, storage, and retrieval for service discovery optimization and contract management.
368

369
```java { .api }
370
// Metadata report configuration
371
public class MetadataReportConfig extends AbstractConfig {
372
    public void setAddress(String address);
373
    public void setUsername(String username);
374
    public void setPassword(String password);
375
    public void setTimeout(Integer timeout);
376
    public void setRetryTimes(Integer retryTimes);
377
    public void setCycleReport(Boolean cycleReport);
378
    public void setSyncReport(Boolean syncReport);
379
}
380

381
// Metadata service for runtime operations
382
public interface MetadataService {
383
    String getServiceDefinition(String interfaceName, String version, String group);
384
    SortedSet<String> getExportedURLs(String serviceInterface, String group, String version, String protocol);
385
    SortedSet<String> getSubscribedURLs();
386
    String getMetadataVersion();
387
    MetadataInfo getMetadataInfo(String revision);
388
}
389

390
// Metadata report interface
391
@SPI("zookeeper")
392
public interface MetadataReport {
393
    void storeProviderMetadata(MetadataIdentifier providerMetaDataIdentifier, String serviceDefinition);
394
    void storeConsumerMetadata(MetadataIdentifier consumerMetadataIdentifier, String serviceParameterString);
395
    String getServiceDefinition(MetadataIdentifier metadataIdentifier);
396
}
397
```
398

399
[Metadata Management](./metadata.md)
400

401
### Serialization
402

403
Pluggable serialization framework supporting multiple protocols including Hessian2, Protobuf, JSON, and Java native serialization.
404

405
```java { .api }
406
// Serialization interface
407
@SPI("hessian2")
408
public interface Serialization {
409
    byte getContentTypeId();
410
    String getContentType();
411
    ObjectOutput serialize(URL url, OutputStream output) throws IOException;
412
    ObjectInput deserialize(URL url, InputStream input) throws IOException;
413
}
414

415
// Object output for writing serialized data
416
public interface ObjectOutput extends DataOutput {
417
    void writeObject(Object obj) throws IOException;
418
    void writeUTF(String s) throws IOException;
419
    void writeBytes(byte[] b) throws IOException;
420
    void flushBuffer() throws IOException;
421
}
422

423
// Object input for reading serialized data
424
public interface ObjectInput extends DataInput {
425
    Object readObject() throws IOException, ClassNotFoundException;
426
    <T> T readObject(Class<T> cls) throws IOException, ClassNotFoundException;
427
    String readUTF() throws IOException;
428
    byte[] readBytes() throws IOException;
429
}
430
```
431

432
[Serialization](./serialization.md)
433

434
## Key Constants and Enums
435

436
```java { .api }
437
// Common constants
438
public class CommonConstants {
439
    public static final String DEFAULT_TIMEOUT = "1000";
440
    public static final String DEFAULT_RETRIES = "2";
441
    public static final String GENERIC_SERIALIZATION_NATIVE_JAVA = "nativejava";
442
    public static final String GENERIC_SERIALIZATION_DEFAULT = "true";
443
    public static final String HEARTBEAT_KEY = "heartbeat";
444
    public static final String HEARTBEAT_TIMEOUT_KEY = "heartbeat.timeout";
445
}
446

447
// Registry constants
448
public class RegistryConstants {
449
    public static final String REGISTRY_KEY = "registry";
450
    public static final String REGISTRY_PROTOCOL = "registry";
451
    public static final String DYNAMIC_KEY = "dynamic";
452
    public static final String CATEGORY_KEY = "category";
453
    public static final String PROVIDERS_CATEGORY = "providers";
454
    public static final String CONSUMERS_CATEGORY = "consumers";
455
}
456

457
// RPC constants
458
public class RpcConstants {
459
    public static final String TOKEN_KEY = "token";
460
    public static final String ASYNC_KEY = "async";
461
    public static final String RETURN_KEY = "return";
462
    public static final String THROW_EXCEPTION_KEY = "throw.exception";
463
}
464
```
465

466
## Types and Interfaces
467

468
```java { .api }
469
// Core URL type for configuration and addressing
470
public class URL implements Serializable {
471
    public URL(String protocol, String host, int port, String path, Map<String, String> parameters);
472
    public String getProtocol();
473
    public String getHost();
474
    public int getPort();
475
    public String getPath();
476
    public String getParameter(String key);
477
    public String getParameter(String key, String defaultValue);
478
    public Map<String, String> getParameters();
479
    public URL addParameter(String key, String value);
480
    public URL removeParameter(String key);
481
}
482

483
// RPC invocation representation
484
public interface Invocation {
485
    String getTargetServiceUniqueName();
486
    String getMethodName();
487
    String getServiceName();
488
    Class<?>[] getParameterTypes();
489
    Object[] getArguments();
490
    Map<String, String> getAttachments();
491
    String getAttachment(String key);
492
    String getAttachment(String key, String defaultValue);
493
}
494

495
// RPC result container
496
public interface Result {
497
    Object getValue();
498
    void setValue(Object value);
499
    Throwable getException();
500
    void setException(Throwable t);
501
    boolean hasException();
502
    Map<String, String> getAttachments();
503
    String getAttachment(String key);
504
}
505

506
// RPC exception with error codes
507
public class RpcException extends RuntimeException {
508
    public static final int UNKNOWN_EXCEPTION = 0;
509
    public static final int NETWORK_EXCEPTION = 1;
510
    public static final int TIMEOUT_EXCEPTION = 2;
511
    public static final int BIZ_EXCEPTION = 3;
512
    public static final int FORBIDDEN_EXCEPTION = 4;
513
    public static final int SERIALIZATION_EXCEPTION = 5;
514
    
515
    public RpcException(int code, String message);
516
    public int getCode();
517
}
518
```