Dubbo 配置 on Apache Dubbo

配置概述

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

此文档已经不再维护。您当前查看的是快照版本。如果想要查看最新版本的文档，请参阅最新版本。

本文主要介绍Dubbo配置概况，包括配置组件、配置来源、配置方式及配置加载流程。

配置组件

Dubbo框架的配置项比较繁多，为了更好地管理各种配置，将其按照用途划分为不同的组件，最终所有配置项都会汇聚到URL中，传递给后续处理模块。

常用配置组件如下：

application: Dubbo应用配置
registry: 注册中心
protocol: 服务提供者RPC协议
config-center: 配置中心
metadata-report: 元数据中心
service: 服务提供者配置
reference: 远程服务引用配置
provider: service的默认配置或分组配置
consumer: reference的默认配置或分组配置
module: 模块配置
monitor: 监控配置
metrics: 指标配置
ssl: SSL/TLS配置

consumer 与 reference的关系

reference可以指定具体的consumer，如果没有指定consumer则会自动使用全局默认的consumer配置。

consumer的属性是reference属性的默认值，可以体现在两个地方：

在刷新属性(属性覆盖)时，先提取其consumer的属性，然后提取reference自身的属性覆盖上去，叠加后的属性集合作为配置来源之一。
在组装reference的URL参数时，先附加其consumer的属性，然后附加reference自身的属性。

可以将consumer组件理解为reference组件的虚拟分组，根据需要可以定义多个不同的consumer，不同的consumer设置特定的默认值，然后在reference中指定consumer或者将<dubbo:reference /> 标签嵌套在<dubbo:consumer />标签之中。

provider 与 service的关系

service可以指定具体的provider，如果没有指定则会自动使用全局默认的provider配置。 provider的属性是service属性的默认值，覆盖规则类似上面的consumer与reference，也可以将provider理解为service的虚拟分组。

配置来源

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

JVM System Properties，JVM -D 参数
System environment，JVM进程的环境变量
Externalized Configuration，外部化配置，从配置中心读取
Application Configuration，应用的属性配置，从Spring应用的Environment中提取"dubbo"打头的属性集
API / XML /注解等编程接口采集的配置可以被理解成配置来源的一种，是直接面向用户编程的配置采集方式
从classpath读取配置文件 dubbo.properties

覆盖关系

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

API 配置

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

此文档已经不再维护。您当前查看的是快照版本。如果想要查看最新版本的文档，请参阅最新版本。

通过API编码方式组装配置，启动Dubbo，发布及订阅服务。此方式可以支持动态创建ReferenceConfig/ServiceConfig，结合泛化调用可以满足API Gateway或测试平台的需要。

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

API使用范围说明：API 仅用于 OpenAPI, ESB, Test, Mock, Gateway 等系统集成，普通服务提供方或消费方，请采用XML 配置或注解配置或属性配置方式使用 Dubbo

参考API示例

服务提供者

通过ServiceConfig暴露服务接口，发布服务接口到注册中心。

注意：为了更好支持Dubbo3的应用级服务发现，推荐使用新的DubboBootstrap API。

import org.apache.dubbo.config.ApplicationConfig;
import org.apache.dubbo.config.RegistryConfig;
import org.apache.dubbo.config.ProviderConfig;
import org.apache.dubbo.config.ServiceConfig;
import com.xxx.DemoService;
import com.xxx.DemoServiceImpl;

public class DemoProvider {
 public static void main(String[] args) {
 // 服务实现
 DemoService demoService = new DemoServiceImpl();

 // 当前应用配置
 ApplicationConfig application = new ApplicationConfig();
 application.setName("demo-provider");

 // 连接注册中心配置
 RegistryConfig registry = new RegistryConfig();
 registry.setAddress("zookeeper://10.20.130.230:2181");

 // 服务提供者协议配置
 ProtocolConfig protocol = new ProtocolConfig();
 protocol.setName("dubbo");
 protocol.setPort(12345);
 protocol.setThreads(200);

 // 注意：ServiceConfig为重对象，内部封装了与注册中心的连接，以及开启服务端口
 // 服务提供者暴露服务配置
 ServiceConfig<DemoService> service = new ServiceConfig<DemoService>(); // 此实例很重，封装了与注册中心的连接，请自行缓存，否则可能造成内存和连接泄漏
 service.setApplication(application);
 service.setRegistry(registry); // 多个注册中心可以用setRegistries()
 service.setProtocol(protocol); // 多个协议可以用setProtocols()
 service.setInterface(DemoService.class);
 service.setRef(demoService);
 service.setVersion("1.0.0");

 // 暴露及注册服务
 service.export();
 
 // 挂起等待(防止进程退出）
 System.in.read();
 }
}

服务消费者

通过ReferenceConfig引用远程服务，从注册中心订阅服务接口。

XML 配置

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

此文档已经不再维护。您当前查看的是快照版本。如果想要查看最新版本的文档，请参阅最新版本。

有关 XML 的详细配置项，请参见：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

此文档已经不再维护。您当前查看的是快照版本。如果想要查看最新版本的文档，请参阅最新版本。

提示

需要 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属性配置有两个职责：

定义配置：根据属性创建配置组件实例，类似SpringBoot的@ConfigurationProperties的作用。
属性覆盖：覆盖已存在的配置组件实例的属性值，类似Spring PropertyOverrideConfigurer 的作用。

一个属性配置的例子 dubbo-spring-boot-samples

 ## application.properties
 
 # Spring boot application
 spring.application.name=dubbo-externalized-configuration-provider-sample
 
 # Base packages to scan Dubbo Component: @com.alibaba.dubbo.config.annotation.Service
 dubbo.scan.base-packages=com.alibaba.boot.dubbo.demo.provider.service
 
 # Dubbo Application
 ## The default value of dubbo.application.name is ${spring.application.name}
 ## dubbo.application.name=${spring.application.name}
 
 # Dubbo Protocol
 dubbo.protocol.name=dubbo
 dubbo.protocol.port=12345
 
 ## Dubbo Registry
 dubbo.registry.address=N/A
 
 ## service default version
 dubbo.provider.version=1.0.0

配置来源

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

JVM System Properties，JVM -D 参数
System environment，JVM进程的环境变量
Externalized Configuration，外部化配置，从配置中心读取
Application Configuration，应用的属性配置，从Spring应用的Environment中提取"dubbo"打头的属性集
API / XML /注解等编程接口采集的配置可以被理解成配置来源的一种，是直接面向用户编程的配置采集方式
从classpath读取配置文件 dubbo.properties

关于dubbo.properties属性：

外部化配置

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

此文档已经不再维护。您当前查看的是快照版本。如果想要查看最新版本的文档，请参阅最新版本。

外部化配置

外部化配置目的之一是实现配置的集中式管理，这部分业界已经有很多成熟的专业配置系统如 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

优先级

外部化配置默认较本地配置有更高的优先级，因此这里配置的内容会覆盖本地配置值，关于各配置形式间的覆盖关系有单独一章说明。
作用域

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

配置中心

从配置中心读取外部化配置，可以按照下面的方法指定配置中心：

<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");

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概念不同），在这里全局和应用级别配置就是通过命名空间来区分的。

默认情况下，Dubbo会从名叫dubbo（由于 Apollo 不支持特殊后缀 .properties ）的命名空间中读取全局配置（<dubbo:config-center namespace="your namespace">）

由于 Apollo 也默认将会在 dubbo namespace 中存储服务治理规则（如路由规则），建议通过单独配置 group 将服务治理和配置文件托管分离开，以 XML 配置方式为例：

自动加载环境变量

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

Dubbo 配置 on Apache Dubbo

配置概述

配置组件

consumer 与 reference的关系

provider 与 service的关系

配置来源

覆盖关系

API 配置

服务提供者

服务消费者

XML 配置

provider.xml 示例

consumer.xml示例

配置之间的关系

注解配置

提示

服务提供方

Service注解暴露服务

增加应用共享配置

指定Spring扫描路径

服务消费方

Reference注解引用服务

增加应用共享配置

指定Spring扫描路径

调用服务

属性配置

配置来源

外部化配置

外部化配置

配置中心

Zookeeper

Apollo

自动加载环境变量

`Service`注解暴露服务

`Reference`注解引用服务