Configuration Overview

A general overview of the overall design and working principle of Dubbo configuration, including configuration components, configuration sources, configuration methods, and configuration loading processes.

Quickly jump to the content you care about through the following links:

Configuration components

In order to better manage various configurations, Dubbo abstracts a set of structured configuration components. Each component is generally divided by purpose and controls the behavior of different scopes.


Component NameDescriptionScopeRequired
applicationSpecify the application-level information such as the application nameOnly one application is allowed in an applicationRequired
serviceDeclare a common interface or implementation class as a Dubbo serviceThere can be 0 or more services in an applicationAt least one service/reference
referenceDeclare a common interface as a Dubbo serviceThere can be 0 or more references in an applicationAt least one service/reference
protocolThe RPC protocol to be exposed and related configurations such as port numbers, etc.One application can be configured with multiple, one protocol can be used for a set of service&referenceoptional, default dubbo
registryRegistry type, address and related configurationMultiple configurations can be made in one application, and one registry can be applied to a group of service&referencesMandatory
config-centerconfiguration center type, address and related configurationsmultiple configurations in one application, shared by all servicesoptional
metadata-reportmetadata center type, address and related configurationmultiple configurations in one application, shared by all servicesoptional
ConsumerThe default configuration shared between referencesMultiple configurations can be configured in one application, and one consumer can act on a group of referencesOptional
ProviderThe default configuration shared between servicesMultiple configurations can be configured in one application, and one provider can be used for a group of servicesOptional
monitormonitoring system type and addressonly one can be configured in an applicationoptional
metricsrelated configuration of the data acquisition moduleonly one configuration is allowed in an applicationoptional
sslssl/tls security link-related certificate configurationOnly one configuration is allowed in an applicationoptional
methodspecifies method-level configurationsubconfigurations for service and referenceoptional
argumentparameter configuration of a methodsubconfiguration of methodoptional
  1. From the perspective of implementation principle, all configuration items of Dubbo will be assembled into the URL in the end, and the URL will be used as the carrier to pass during subsequent startup and RPC calls, thereby controlling the behavior of the framework. For more information, please refer to the Dubbo source code analysis series of documents or [Blog](/zh/blog/2019/10/17/dubbo-in-url-unified model/#rpc call).
  2. For the specific configuration items supported by each component and their meanings, please refer to Configuration Item Manual

service and reference

service and reference are the two most basic configuration items of Dubbo, they are used to register a specified interface or implementation class as a Dubbo service, and control the behavior of the service through configuration items.

  • service is used on the service provider side, the interface and implementation class configured by service will be defined as a standard Dubbo service, so as to provide external RPC request services.
  • reference is used for service consumers, the interface configured by reference will be defined as a standard Dubbo service, and the generated proxy can initiate an RPC request to the remote end.

Any number of service and reference can be configured in an application.

consumer and provider

  • When there are multiple reference configurations in the application, consumer specifies the default values shared by these references, such as shared timeouts, etc. to simplify cumbersome configurations, such as setting configurations separately in a reference Item value, the configuration in this reference takes precedence.
  • When there are multiple service configurations in the application, provider specifies the default value shared by these service, if a configuration item value is set separately in a service, the configuration priority in the service higher.

The consumer component can also carry out virtual grouping of references, and references under different groups can have different consumer default value settings; for example, in XML format configuration, the <dubbo:reference /> tag can be nested in <dubbo:consumer / > Implement grouping within tags. The same effect can also be achieved between provider and service.

configuration method

According to the driving mode, it can be divided into the following five modes:

API configuration

The configuration is organized in the form of Java coding, including Raw API and Bootstrap API. For details, please refer to API configuration.

public static void main(String[] args) throws IOException {
        ServiceConfig<GreetingsService> service = new ServiceConfig<>();
        service.setApplication(new ApplicationConfig("first-dubbo-provider"));
        service.setRegistry(new RegistryConfig("multicast://"));
        service.setRef(new GreetingsServiceImpl());
        service. export();
        System.out.println("first-dubbo-provider is running.");;

XML configuration

Configure various components in XML and support seamless integration with Spring. For details, please refer to XML Configuration.

  <!-- dubbo-provier.xml -->

  <dubbo:application name="demo-provider"/>
  <dubbo:config-center address="zookeeper://"/>

  <dubbo:registry address="zookeeper://" simplified="true"/>
  <dubbo:metadata-report address="redis://"/>
  <dubbo:protocol name="dubbo" port="20880"/>

  <bean id="demoService" class="org.apache.dubbo.samples.basic.impl.DemoServiceImpl"/>
  <dubbo:service interface="org.apache.dubbo.samples.basic.api.DemoService" ref="demoService"/>

Annotation configuration

Expose services and reference service interfaces in the form of annotations, and support seamless integration with Spring. For details, please refer to Annotation Configuration.

  // AnnotationService service implementation

  public class AnnotationServiceImpl implements AnnotationService {
      public String sayHello(String name) {
          System.out.println("async provider received: " + name);
          return "annotation: hello, " + name;

Spring Boot

Use Spring Boot to reduce unnecessary configuration, and combine Annotation and to develop Dubbo applications. For details, please refer to Annotation Configuration.


# Spring boot application

# Base packages to scan Dubbo Component:

# Dubbo Application
## The default value of is ${}

#Dubbo Protocol

## Dubbo Registry

## DemoService version

Property configuration

Generate configuration components according to the attribute Key-value, similar to SpringBoot’s ConfigurationProperties, please refer to property configuration for details.

Another important feature of property configuration is [property override](../principle/#32-property override), which overrides the created configuration component property with the value of an external property.

If you want to put the attribute configuration in an external configuration center, please refer to [Externalized Configuration](../principle/#33-Externalized Configuration).

In addition to the differences in peripheral drive methods, Dubbo’s configuration reading generally follows the following principles:

  1. Dubbo supports multi-level configuration, and automatically realizes the coverage between configurations according to the predetermined priority. Finally, all configurations are summarized into the data bus URL to drive subsequent service exposure, reference and other processes.
  2. The configuration format is mainly Properties, and the configuration content follows the agreed path-based[naming convention](../principle/#1-configuration format)

Configure the loading process

Configuration specifications and sources

Dubbo follows a path-based configuration specification, and each configuration component can be expressed in this way. In terms of configuration sources, a total of 6 configuration sources are supported, that is, Dubbo will try to load configuration data from the following locations:

  • JVM System Properties, JVM -D parameter
  • System environment, the environment variable of the JVM process
  • Externalized Configuration, [externalized configuration] (../principle/#33-externalized configuration), read from the configuration center
  • Application Configuration, application attribute configuration, extract the attribute set starting with “dubbo” from the Spring application Environment
  • The configuration collected by programming interfaces such as API/XML/annotation can be understood as a kind of configuration source, which is a configuration collection method directly oriented to user programming
  • Read configuration file from classpath

Last modified January 2, 2023: Enhance en docs (#1798) (95a9f4f6c1)