配置手册 on Apache Dubbo

XML 配置

Mon, 01 Jan 0001 00:00:00 +0000

有关 XML 的详细配置项，请参见：配置参考手册。如果不想使用 Spring 配置，而希望通过 API 的方式进行调用，请参见：API配置。想知道如何使用配置，请参见：快速启动。

请在此查看文档描述的完整示例

provider.xml 示例

<beans xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:dubbo="http://dubbo.apache.org/schema/dubbo"
 xmlns="http://www.springframework.org/schema/beans"
 xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
 http://dubbo.apache.org/schema/dubbo http://dubbo.apache.org/schema/dubbo/dubbo.xsd">
 <dubbo:application name="demo-provider"/>
 <dubbo:registry address="zookeeper://127.0.0.1:2181"/>
 <dubbo:protocol name="dubbo" port="20890"/>
 <bean id="demoService" class="org.apache.dubbo.samples.basic.impl.DemoServiceImpl"/>
 <dubbo:service interface="org.apache.dubbo.samples.basic.api.DemoService" ref="demoService"/>
</beans>

consumer.xml示例

<beans xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:dubbo="http://dubbo.apache.org/schema/dubbo"
 xmlns="http://www.springframework.org/schema/beans"
 xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
 http://dubbo.apache.org/schema/dubbo http://dubbo.apache.org/schema/dubbo/dubbo.xsd">
 <dubbo:application name="demo-consumer"/>
 <dubbo:registry group="aaa" address="zookeeper://127.0.0.1:2181"/>
 <dubbo:reference id="demoService" check="false" interface="org.apache.dubbo.samples.basic.api.DemoService"/>
</beans>

所有标签都支持自定义参数，用于不同扩展点实现的特殊配置，如：

<dubbo:protocol name="jms">
 <dubbo:parameter key="queue" value="your_queue" />
</dubbo:protocol>

或： ¹

<beans xmlns="http://www.springframework.org/schema/beans"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:dubbo="http://dubbo.apache.org/schema/dubbo"
 xmlns:p="http://www.springframework.org/schema/p"
 xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-4.3.xsd http://dubbo.apache.org/schema/dubbo http://dubbo.apache.org/schema/dubbo/dubbo.xsd"> 
 <dubbo:protocol name="jms" p:queue="your_queue" /> 
</beans>

配置之间的关系

动态配置中心

Mon, 01 Jan 0001 00:00:00 +0000

配置中心（v2.7.0）在 Dubbo 中承担两个职责：

外部化配置。启动配置的集中式存储（简单理解为 dubbo.properties 的外部化存储）。
服务治理。服务治理规则的存储与通知。

启用动态配置，以 Zookeeper 为例，可查看动态配置配置项详解

<dubbo:config-center address="zookeeper://127.0.0.1:2181"/>

或者

dubbo.config-center.address=zookeeper://127.0.0.1:2181

或者

ConfigCenterConfig configCenter = new ConfigCenterConfig();
configCenter.setAddress("zookeeper://127.0.0.1:2181");

为了兼容 2.6.x 版本配置，在使用 Zookeeper 作为注册中心，且没有显示配置配置中心的情况下，Dubbo 框架会默认将此 Zookeeper 用作配置中心，但将只作服务治理用途。

外部化配置

外部化配置目的之一是实现配置的集中式管理，这部分业界已经有很多成熟的专业配置系统如 Apollo, Nacos 等，Dubbo 所做的主要是保证能配合这些系统正常工作。

外部化配置和其他本地配置在内容和格式上并无区别，可以简单理解为 dubbo.properties 的外部化存储，配置中心更适合将一些公共配置如注册中心、元数据中心配置等抽取以便做集中管理。

# 将注册中心地址、元数据中心地址等配置集中管理，可以做到统一环境、减少开发侧感知。
dubbo.registry.address=zookeeper://127.0.0.1:2181
dubbo.registry.simplified=true

dubbo.metadata-report.address=zookeeper://127.0.0.1:2181

dubbo.protocol.name=dubbo
dubbo.protocol.port=20880

dubbo.application.qos.port=33333

优先级

外部化配置默认较本地配置有更高的优先级，因此这里配置的内容会覆盖本地配置值，关于各配置形式间的覆盖关系有单独一章说明，你也可通过以下选项调整配置中心的优先级：
```
-Ddubbo.config-center.highest-priority=false
```
作用域

外部化配置有全局和应用两个级别，全局配置是所有应用共享的，应用级配置是由每个应用自己维护且只对自身可见的。当前已支持的扩展实现有Zookeeper、Apollo。

Zookeeper

<dubbo:config-center address="zookeeper://127.0.0.1:2181"/>

默认所有的配置都存储在 /dubbo/config 节点，具体节点结构图如下：

namespace，用于不同配置的环境隔离。
config，Dubbo约定的固定节点，不可更改，所有配置和服务治理规则都存储在此节点下。
dubbo/application，分别用来隔离全局配置、应用级别配置：dubbo是默认group值，application对应应用名
dubbo.properties，此节点的node value存储具体配置内容

Apollo

<dubbo:config-center protocol="apollo" address="127.0.0.1:2181"/>

Apollo中的一个核心概念是命名空间 - namespace（和上面zookeeper的namespace概念不同），在这里全局和应用级别配置就是通过命名空间来区分的。

属性配置

Mon, 01 Jan 0001 00:00:00 +0000

如果你的应用足够简单，例如，不需要多注册中心或多协议，并且需要在spring容器中共享配置，那么，我们可以直接使用 dubbo.properties 作为默认配置。

Dubbo 可以自动加载 classpath 根目录下的 dubbo.properties，但是你同样可以使用 JVM 参数来指定路径：-Ddubbo.properties.file=xxx.properties。

映射规则

可以将 xml 的 tag 名和属性名组合起来，用 ‘.’ 分隔。每行一个属性。

dubbo.application.name=foo 相当于 <dubbo:application name="foo" />
dubbo.registry.address=10.20.153.10:9090 相当于 <dubbo:registry address="10.20.153.10:9090" />

如果在 xml 配置中有超过一个的 tag，那么你可以使用 ‘id’ 进行区分。如果你不指定 id，它将作用于所有 tag。

dubbo.protocol.rmi.port=1099 相当于 <dubbo:protocol id="rmi" name="rmi" port="1099" />
dubbo.registry.china.address=10.20.153.10:9090 相当于 <dubbo:registry id="china" address="10.20.153.10:9090" />

如下，是一个典型的 dubbo.properties 配置样例。

dubbo.application.name=foo
dubbo.application.owner=bar
dubbo.registry.address=10.20.153.10:9090

重写与优先级

优先级从高到低：

JVM -D 参数：当你部署或者启动应用时，它可以轻易地重写配置，比如，改变 dubbo 协议端口；
XML：XML 中的当前配置会重写 dubbo.properties 中的；
Properties：默认配置，仅仅作用于以上两者没有配置时。

如果在 classpath 下有超过一个 dubbo.properties 文件，比如，两个 jar 包都各自包含了 dubbo.properties，dubbo 将随机选择一个加载，并且打印错误日志。
如果 id 没有在 protocol 中配置，将使用 name 作为默认属性。

自动加载环境变量

Mon, 01 Jan 0001 00:00:00 +0000

从 2.7.3 版本开始，Dubbo 会自动从约定 key 中读取配置，并将配置以 Key-Value 的形式写入到URL中。

支持的 key 有以下两个：

dubbo.labels，指定一些列配置到 URL 中的键值对，通常通过 JVM -D 或系统环境变量指定。

增加以下配置：
```
# JVM
-Ddubbo.labels = "tag1=value1; tag2=value2"
# 环境变量
DUBBO_LABELS = "tag1=value1; tag2=value2"
```
最终生成的 URL 会包含 tag1、tag2 两个 key: dubbo://xxx?tag1=value1&tag2=value2
dubbo.env.keys，指定环境变量 key 值，Dubbo 会尝试从环境变量加载每个 key
```
# JVM
-Ddubbo.env.keys = "DUBBO_TAG1, DUBBO_TAG2"
# 环境变量
DUBBO_ENV_KEYS = "DUBBO_TAG1, DUBBO_TAG2"
```
最终生成的 URL 会包含 DUBBO_TAG1、DUBBO_TAG2 两个 key: dubbo://xxx?DUBBO_TAG1=value1&DUBBO_TAG2=value2

API 配置

Mon, 01 Jan 0001 00:00:00 +0000

API 属性与配置项一对一，各属性含义，请参见：配置参考手册，比如：ApplicationConfig.setName("xxx") 对应 <dubbo:application name="xxx" /> ¹

服务提供者

import org.apache.dubbo.rpc.config.ApplicationConfig;
import org.apache.dubbo.rpc.config.RegistryConfig;
import org.apache.dubbo.rpc.config.ProviderConfig;
import org.apache.dubbo.rpc.config.ServiceConfig;
import com.xxx.XxxService;
import com.xxx.XxxServiceImpl;
 
// 服务实现
XxxService xxxService = new XxxServiceImpl();
 
// 当前应用配置
ApplicationConfig application = new ApplicationConfig();
application.setName("xxx");
 
// 连接注册中心配置
RegistryConfig registry = new RegistryConfig();
registry.setAddress("10.20.130.230:9090");
registry.setUsername("aaa");
registry.setPassword("bbb");
 
// 服务提供者协议配置
ProtocolConfig protocol = new ProtocolConfig();
protocol.setName("dubbo");
protocol.setPort(12345);
protocol.setThreads(200);
 
// 注意：ServiceConfig为重对象，内部封装了与注册中心的连接，以及开启服务端口
 
// 服务提供者暴露服务配置
ServiceConfig<XxxService> service = new ServiceConfig<XxxService>(); // 此实例很重，封装了与注册中心的连接，请自行缓存，否则可能造成内存和连接泄漏
service.setApplication(application);
service.setRegistry(registry); // 多个注册中心可以用setRegistries()
service.setProtocol(protocol); // 多个协议可以用setProtocols()
service.setInterface(XxxService.class);
service.setRef(xxxService);
service.setVersion("1.0.0");
 
// 暴露及注册服务
service.export();

服务消费者

import org.apache.dubbo.rpc.config.ApplicationConfig;
import org.apache.dubbo.rpc.config.RegistryConfig;
import org.apache.dubbo.rpc.config.ConsumerConfig;
import org.apache.dubbo.rpc.config.ReferenceConfig;
import com.xxx.XxxService;
 
// 当前应用配置
ApplicationConfig application = new ApplicationConfig();
application.setName("yyy");
 
// 连接注册中心配置
RegistryConfig registry = new RegistryConfig();
registry.setAddress("10.20.130.230:9090");
registry.setUsername("aaa");
registry.setPassword("bbb");
 
// 注意：ReferenceConfig为重对象，内部封装了与注册中心的连接，以及与服务提供方的连接
 
// 引用远程服务
ReferenceConfig<XxxService> reference = new ReferenceConfig<XxxService>(); // 此实例很重，封装了与注册中心的连接以及与提供者的连接，请自行缓存，否则可能造成内存和连接泄漏
reference.setApplication(application);
reference.setRegistry(registry); // 多个注册中心可以用setRegistries()
reference.setInterface(XxxService.class);
reference.setVersion("1.0.0");
 
// 和本地bean一样使用xxxService
XxxService xxxService = reference.get(); // 注意：此代理对象内部封装了所有通讯细节，对象较重，请缓存复用

特殊场景

下面只列出不同的地方，其它参见上面的写法

注解配置

Mon, 01 Jan 0001 00:00:00 +0000

提示

需要 2.6.3 及以上版本支持。点此查看完整示例

服务提供方

`Service`注解暴露服务

@Service
public class AnnotationServiceImpl implements AnnotationService {
 @Override
 public String sayHello(String name) {
 return "annotation: hello, " + name;
 }
}

增加应用共享配置

# dubbo-provider.properties
dubbo.application.name=annotation-provider
dubbo.registry.address=zookeeper://127.0.0.1:2181
dubbo.protocol.name=dubbo
dubbo.protocol.port=20880

指定Spring扫描路径

@Configuration
@EnableDubbo(scanBasePackages = "org.apache.dubbo.samples.simple.annotation.impl")
@PropertySource("classpath:/spring/dubbo-provider.properties")
static public class ProviderConfiguration {
 
}

服务消费方

`Reference`注解引用服务

@Component("annotationAction")
public class AnnotationAction {

 @Reference
 private AnnotationService annotationService;
 
 public String doSayHello(String name) {
 return annotationService.sayHello(name);
 }
}

增加应用共享配置

# dubbo-consumer.properties
dubbo.application.name=annotation-consumer
dubbo.registry.address=zookeeper://127.0.0.1:2181
dubbo.consumer.timeout=3000

指定Spring扫描路径

@Configuration
@EnableDubbo(scanBasePackages = "org.apache.dubbo.samples.simple.annotation.action")
@PropertySource("classpath:/spring/dubbo-consumer.properties")
@ComponentScan(value = {"org.apache.dubbo.samples.simple.annotation.action"})
static public class ConsumerConfiguration {

}

调用服务

public static void main(String[] args) throws Exception {
 AnnotationConfigApplicationContext context = new AnnotationConfigApplicationContext(ConsumerConfiguration.class);
 context.start();
 final AnnotationAction annotationAction = (AnnotationAction) context.getBean("annotationAction");
 String hello = annotationAction.doSayHello("world");
}

配置加载流程

Mon, 01 Jan 0001 00:00:00 +0000

此篇文档主要讲在应用启动阶段，Dubbo框架如何将所需要的配置采集起来（包括应用配置、注册中心配置、服务配置等），以完成服务的暴露和引用流程。

根据驱动方式的不同（比如Spring或裸API编程）配置形式上肯定会有所差异，具体请参考XML配置、Annotation配置、API配置三篇文档。除了外围驱动方式上的差异，Dubbo的配置读取总体上遵循了以下几个原则：

Dubbo 支持了多层级的配置，并按预定优先级自动实现配置间的覆盖，最终所有配置汇总到数据总线URL后驱动后续的服务暴露、引用等流程。
ApplicationConfig、ServiceConfig、ReferenceConfig 可以被理解成配置来源的一种，是直接面向用户编程的配置采集方式。
配置格式以 Properties 为主，在配置内容上遵循约定的 path-based 的命名规范

配置来源

首先，从Dubbo支持的配置来源说起，默认有四种配置来源：

JVM System Properties，-D 参数
Externalized Configuration，外部化配置
ServiceConfig、ReferenceConfig 等编程接口采集的配置
本地配置文件 dubbo.properties

覆盖关系

下图展示了配置覆盖关系的优先级，从上到下优先级依次降低：

点此查看外部化配置详情

配置格式

目前Dubbo支持的所有配置都是.properties格式的，包括-D、Externalized Configuration等，.properties中的所有配置项遵循一种path-based的配置格式：

# 应用级别
dubbo.{config-type}[.{config-id}].{config-item}={config-item-value}
# 服务级别
dubbo.service.{interface-name}[.{method-name}].{config-item}={config-item-value}
dubbo.reference.{interface-name}[.{method-name}].{config-item}={config-item-value}
# 多配置项
dubbo.{config-type}s.{config-id}.{config-item}={config-item-value}

应用级别

dubbo.application.name=demo-provider
dubbo.registry.address=zookeeper://127.0.0.1:2181
dubbo.protocol.port=-1

服务级别

dubbo.service.org.apache.dubbo.samples.api.DemoService.timeout=5000
dubbo.reference.org.apache.dubbo.samples.api.DemoService.timeout=6000
dubbo.reference.org.apache.dubbo.samples.api.DemoService.sayHello.timeout=7000

多配置项

dubbo.registries.unit1.address=zookeeper://127.0.0.1:2181
dubbo.registries.unit2.address=zookeeper://127.0.0.1:2182

dubbo.protocols.dubbo.name=dubbo
dubbo.protocols.dubbo.port=20880
dubbo.protocols.hessian.name=hessian
dubbo.protocols.hessian.port=8089

扩展配置

dubbo.application.parameters=[{item1:value1},{item2:value2}]
dubbo.reference.org.apache.dubbo.samples.api.DemoService.parameters=[{item3:value3}]

几种编程配置方式

接下来，我们看一下选择不同的开发方式时，对应到 ServiceConfig、ReferenceConfig 等编程接口采集的配置的变化。

Spring XML

参见示例

 <!-- dubbo-provier.xml -->
 
 <dubbo:application name="demo-provider"/>
 <dubbo:config-center address="zookeeper://127.0.0.1:2181"/>
 
 <dubbo:registry address="zookeeper://127.0.0.1:2181" simplified="true"/>
 <dubbo:metadata-report address="redis://127.0.0.1:6379"/>
 <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"/>

Spring Annotation

参见示例

配置手册 on Apache Dubbo

XML 配置

provider.xml 示例

consumer.xml示例

配置之间的关系

动态配置中心

外部化配置

Zookeeper

Apollo

属性配置

映射规则

重写与优先级

自动加载环境变量

API 配置

服务提供者

服务消费者

特殊场景

注解配置

提示

服务提供方

Service注解暴露服务

增加应用共享配置

指定Spring扫描路径

服务消费方

Reference注解引用服务

增加应用共享配置

指定Spring扫描路径

调用服务

配置加载流程

配置来源

覆盖关系

配置格式

几种编程配置方式

Spring XML

Spring Annotation

`Service`注解暴露服务

`Reference`注解引用服务