You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@dubbo.apache.org by al...@apache.org on 2022/07/13 09:40:50 UTC
[dubbo-website] branch master updated: [fix] 优化配置指南 (#1225)
This is an automated email from the ASF dual-hosted git repository.
albumenj pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/dubbo-website.git
The following commit(s) were added to refs/heads/master by this push:
new 73468dfb1e [fix] 优化配置指南 (#1225)
73468dfb1e is described below
commit 73468dfb1e6940388421d8e78e86ba47c99ffa46
Author: JIAN ZHONG <11...@qq.com>
AuthorDate: Wed Jul 13 17:40:45 2022 +0800
[fix] 优化配置指南 (#1225)
* [fix] 优化配置指南
* [fix]
---
.../reference-manual/config/overview/_index.md | 214 ++++++++++++---------
1 file changed, 122 insertions(+), 92 deletions(-)
diff --git a/content/zh/docs3-building/java-sdk/reference-manual/config/overview/_index.md b/content/zh/docs3-building/java-sdk/reference-manual/config/overview/_index.md
index 3a2de84a42..ce2cbf9561 100644
--- a/content/zh/docs3-building/java-sdk/reference-manual/config/overview/_index.md
+++ b/content/zh/docs3-building/java-sdk/reference-manual/config/overview/_index.md
@@ -1,100 +1,143 @@
---
type: docs
-title: "配置概述"
-linkTitle: "配置概述"
+title: "配置指南"
+linkTitle: "配置指南"
weight: 1
-description: "对 Dubbo 配置总体设计与工作原理进行了总体概述，包括配置组件、配置来源、配置方式及配置加载流程等。"
+description: "Dubbo配置介绍"
---
-通过以下链接快速跳转到关心的内容：
-* [使用 Spring Boot 快速开发 Dubbo 应用](../../../quick-start/)
-* [配置项参考手册](../properties)
-* [配置加载及覆盖原理](../principle)
-* [运行态地址 URL 及优先级规则](../blog)
+本文主要介绍 Dubbo 配置概况，包括配置组件、配置来源、配置方式及配置加载流程。
## 配置组件
-为了更好地管理各种配置，Dubbo 抽象了一套结构化的配置组件，各组件总体以用途划分，分别控制不同作用域的行为。
+Dubbo 框架的配置项比较繁多，为了更好地管理各种配置，将其按照用途划分为不同的组件，最终所有配置项都会汇聚到URL中，传递给后续处理模块。
-
+常用配置组件如下：
+- application: Dubbo应用配置
+- registry: 注册中心
+- protocol: 服务提供者RPC协议
+- config-center: 配置中心
+- metadata-report: 元数据中心
+- service: 服务提供者配置
+- reference: 远程服务引用配置
+- provider: service的默认配置或分组配置
+- consumer: reference的默认配置或分组配置
+- module: 模块配置
+- monitor: 监控配置
+- metrics: 指标配置
+- ssl: SSL/TLS配置
-组件名称 | 描述 | 范围 | 是否必须配置
------- | ------ | ------ | ------
-application | 指定应用名等应用级别相关信息 | 一个应用内只允许出现一个 | 必选
-service | 声明普通接口或实现类为 Dubbo 服务 | 一个应用内可以有 0 到多个 service | service/reference 至少一种
-reference | 声明普通接口为 Dubbo 服务 | 一个应用内可以有 0 到多个 reference | service/reference 至少一种
-protocol | 要暴露的 RPC 协议及相关配置如端口号等 | 一个应用可配置多个，一个 protocol 可作用于一组 service&reference | 可选，默认 dubbo
-registry | 注册中心类型、地址及相关配置 | 一个应用内可配置多个，一个 registry 可作用于一组 service&reference| 必选
-config-center | 配置中心类型、地址及相关配置 | 一个应用内可配置多个，所有服务共享 | 可选
-metadata-report | 元数据中心类型、地址及相关配置 | 一个应用内可配置多个，所有服务共享 | 可选
-consumer | reference 间共享的默认配置 | 一个应用内可配置多个，一个 consumer 可作用于一组 reference | 可选
-provider | service 间共享的默认配置 | 一个应用内可配置多个，一个 provider 可作用于一组 service | 可选
-monitor | 监控系统类型及地址 | 一个应用内只允许配置一个 | 可选
-metrics | 数据采集模块相关配置 | 一个应用内只允许配置一个 | 可选
-ssl | ssl/tls 安全链接相关的证书等配置 | 一个应用内只允许配置一个 | 可选
-method | 指定方法级的配置 | service 和 reference 的子配置 | 可选
-argument | 某个方法的参数配置 | method的子配置 | 可选
+#### consumer 与 reference的关系
+reference可以指定具体的consumer，如果没有指定consumer则会自动使用全局默认的consumer配置。
-> 1. 从实现原理层面，最终 Dubbo 所有的配置项都会被组装到 URL 中，以 URL 为载体在后续的启动、RPC 调用过程中传递，进而控制框架行为。如想了解更多，请参照 Dubbo 源码解析系列文档或 [Blog](/blog/java/codeanalysis/introduction-to-dubbo-url#rpc调用)。
-> 2. 各组件支持的具体配置项及含义请参考 [配置项手册](../properties)
+consumer的属性是reference属性的默认值，可以体现在两个地方：
-### service 与 reference
-`service` 与 `reference` 是 Dubbo 最基础的两个配置项，它们用来将某个指定的接口或实现类注册为 Dubbo 服务，并通过配置项控制服务的行为。
-* `service` 用于服务提供者端，通过 `service` 配置的接口和实现类将被定义为标准的 Dubbo 服务，从而实现对外提供 RPC 请求服务。
-* `reference` 用于服务消费者端，通过 `reference` 配置的接口将被定义为标准的 Dubbo 服务，生成的 proxy 可发起对远端的 RPC 请求。
+1. 在刷新属性(属性覆盖)时，先提取其consumer的属性，然后提取reference自身的属性覆盖上去，叠加后的属性集合作为配置来源之一。
+2. 在组装reference的URL参数时，先附加其consumer的属性，然后附加reference自身的属性。
-一个应用中可以配置任意多个 `service` 与 `reference`。
+> 可以将consumer组件理解为reference组件的虚拟分组，根据需要可以定义多个不同的consumer，不同的consumer设置特定的默认值，
+然后在reference中指定consumer或者将<dubbo:reference /> 标签嵌套在<dubbo:consumer />标签之中。
-### consumer 与 provider
-* 当应用内有多个 `reference` 配置时，`consumer` 指定了这些 `reference` 共享的默认值，如共享的超时时间等以简化繁琐的配置，如某个 `reference` 中单独设置了配置项值则该 `reference` 中的配置优先级更高。
-* 当应用内有多个 `service` 配置时，`provider` 指定了这些 `service` 共享的默认值，如某个 `service` 中单独设置了配置项值则该 `service` 中的配置优先级更高。
+#### 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
+
+#### 覆盖关系
+
+下图展示了配置覆盖关系的优先级，从上到下优先级依次降低：
+
+
+
+请参考相关内容：[属性覆盖](../properties#属性覆盖)。
-> consumer 组件还可以对 reference 进行虚拟分组，不通分组下的 reference 可有不同的 consumer 默认值设定；如在 XML 格式配置中，<dubbo:reference /> 标签可通过嵌套在 <dubbo:consumer /> 标签之中实现分组。provider 与 service 之间也可以实现相同的效果。
## 配置方式
-按照驱动方式可以分为以下五种方式：
+按照驱动方式可以分为以下四种方式：
-### API配置
+- API 配置
+- XML 配置
+- Annotation 配置
+- 属性配置
+#### API配置
以Java编码的方式组织配置，包括Raw API和Bootstrap API，具体请参考[API配置](../api)。
-```java
-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://224.5.6.7:1234"));
- service.setInterface(GreetingsService.class);
- service.setRef(new GreetingsServiceImpl());
- service.export();
- System.out.println("first-dubbo-provider is running.");
- System.in.read();
-}
-```
-
-### XML配置
+#### XML配置
以XML方式配置各种组件，支持与Spring无缝集成，具体请参考[XML配置](../xml)。
+#### Annotation配置
+以注解方式暴露服务和引用服务接口，支持与Spring无缝集成，具体请参考[Annotation配置](../annotation)。
+
+#### 属性配置
+根据属性Key-value生成配置组件，类似SpringBoot的ConfigurationProperties，具体请参考[属性配置](../properties)。
+
+属性配置的另外一个重要的功能特性是[属性覆盖](../properties#属性覆盖)，使用外部属性的值覆盖已创建的配置组件属性。
+
+如果要将属性配置放到外部的配置中心，请参考[外部化配置](../external-config)。
+
+除了外围驱动方式上的差异，Dubbo的配置读取总体上遵循了以下几个原则：
+
+1. Dubbo 支持了多层级的配置，并按预定优先级自动实现配置间的覆盖，最终所有配置汇总到数据总线URL后驱动后续的服务暴露、引用等流程。
+2. 配置格式以 Properties 为主，在配置内容上遵循约定的 `path-based` 的[命名规范](../properties#配置格式)
+
+
+#### 配置加载流程
+
+
+
+从上图可以看出，配置加载大概分为两个阶段：
+
+* 第一阶段为DubboBootstrap初始化之前，在Spring context启动时解析处理XML配置/注解配置/Java-config 或者是执行API配置代码，创建config bean并且加入到ConfigManager中。
+* 第二阶段为DubboBootstrap初始化过程，从配置中心读取外部配置，依次处理实例级属性配置和应用级属性配置，最后刷新所有配置实例的属性，也就是[属性覆盖](../properties#属性覆盖)。
+
+
+## 编程配置方式
+
+接下来，我们看一下选择不同的开发方式时，对应到 ServiceConfig、ReferenceConfig 等编程接口采集的配置的变化。
+
+- Spring XML
+- Spring Annotation
+- Spring Boot
+- API
+#### Spring XML
+
+> [示例](https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-basic)
+
```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"/>
```
-### Annotation 配置
-以注解方式暴露服务和引用服务接口，支持与Spring无缝集成，具体请参考[Annotation配置](../annotation)。
+#### Spring Annotation
+
+> [示例](https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-annotation)
```java
// AnnotationService服务实现
-
- @DubboService
+
+ @Service
public class AnnotationServiceImpl implements AnnotationService {
@Override
public String sayHello(String name) {
@@ -105,7 +148,7 @@ public static void main(String[] args) throws IOException {
```
```properties
-## dubbo.properties
+ ## dubbo.properties
dubbo.application.name=annotation-provider
dubbo.registry.address=zookeeper://127.0.0.1:2181
@@ -113,11 +156,12 @@ dubbo.protocol.name=dubbo
dubbo.protocol.port=20880
```
-### Spring Boot
-使用 Spring Boot 减少非必要配置，结合 Annotation 与 application.properties/application.yml 开发 Dubbo 应用，具体请参考[Annotation 配置](../annotation)。
+#### Spring Boot
+
+> [示例](https://github.com/apache/dubbo-spring-boot-project/tree/master/dubbo-spring-boot-samples)
```properties
-## application.properties
+ ## application.properties
# Spring boot application
spring.application.name=dubbo-externalized-configuration-provider-sample
@@ -140,33 +184,19 @@ dubbo.registry.address=N/A
demo.service.version=1.0.0
```
-### 属性配置
-根据属性Key-value生成配置组件，类似SpringBoot的ConfigurationProperties，具体请参考[属性配置](../properties)。
-
-属性配置的另外一个重要的功能特性是[属性覆盖](../properties#属性覆盖)，使用外部属性的值覆盖已创建的配置组件属性。
-
-如果要将属性配置放到外部的配置中心，请参考[外部化配置](../external-config)。
-
-除了外围驱动方式上的差异，Dubbo 的配置读取总体上遵循了以下几个原则：
-
-1. Dubbo 支持了多层级的配置，并按预定优先级自动实现配置间的覆盖，最终所有配置汇总到数据总线URL后驱动后续的服务暴露、引用等流程。
-2. 配置格式以 Properties 为主，在配置内容上遵循约定的 `path-based` 的[命名规范](../properties#配置格式)
-
-
-## 配置加载流程
-
-### 配置规范与来源
-
-Dubbo 遵循一种 [path-based 的配置规范](../principle/)，每一个配置组件都可以通过这种方式进行表达。而在配置的来源上，总共支持 6 种配置来源，即 Dubbo 会分别尝试从以下几个位置尝试加载配置数据：
-
-- JVM System Properties，JVM -D 参数
-- System environment，JVM进程的环境变量
-- Externalized Configuration，[外部化配置](../properties#3.3-外部化配置)，从配置中心读取
-- Application Configuration，应用的属性配置，从Spring应用的Environment中提取"dubbo"打头的属性集
-- API / XML /注解等编程接口采集的配置可以被理解成配置来源的一种，是直接面向用户编程的配置采集方式
-- 从classpath读取配置文件 dubbo.properties
-
-### 覆盖关系
-不通配置来源之间的属性会互相覆盖，它们的覆盖关系或优先级如下(从上到下优先级依次降低)：
+#### API
+> [示例](https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-api)
+```java
+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://224.5.6.7:1234"));
+ service.setInterface(GreetingsService.class);
+ service.setRef(new GreetingsServiceImpl());
+ service.export();
+ System.out.println("first-dubbo-provider is running.");
+ System.in.read();
+ }
+```