配置手册 on Apache Dubbo

Dubbo Maven Plugin 的配置方式

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

本文主要讲解 Dubbo Maven Plugin 的配置方式。

当前 Dubbo Maven Plugin 支持以下功能：

Dubbo Maven Plugin For Protobuf：生成 Dubbo 服务接口的 Stub 代码
Dubbo Maven Plugin For Native Image：基于 AOT 机制，生成 Native Image 必要的 Metadata 信息

Dubbo Maven Plugin For Protobuf

如何使用 Dubbo Maven Plugin 生成 Protobuf Stub 代码

1. 编写 .proto 文件

greeter.proto

syntax = "proto3";

option java_multiple_files = true;
option java_package = "org.apache.dubbo.demo";
option java_outer_classname = "DemoServiceProto";
option objc_class_prefix = "DEMOSRV";

package demoservice;

// The demo service definition.
service DemoService {
 rpc SayHello (HelloRequest) returns (HelloReply) {}
}

// The request message containing the user's name.
message HelloRequest {
 string name = 1;
}

// The response message containing the greetings
message HelloReply {
 string message = 1;
}

2. 引入 dubbo-maven-plugin 依赖


<plugin>
 <groupId>org.apache.dubbo</groupId>
 <artifactId>dubbo-maven-plugin</artifactId>
 <version>${dubbo.version}</version>
 <executions>
 <execution>
 <goals>
 <goal>compile</goal>
 </goals>
 </execution>
 </executions>
</plugin>

3. 生成文件示例

/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements. See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License. You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.apache.dubbo.demo;

import java.util.concurrent.CompletableFuture;
import java.util.concurrent.atomic.AtomicBoolean;

public final class DemoServiceDubbo {
 private static final AtomicBoolean registered = new AtomicBoolean();

 private static Class<?> init() {
 Class<?> clazz = null;
 try {
 clazz = Class.forName(DemoServiceDubbo.class.getName());
 if (registered.compareAndSet(false, true)) {
 org.apache.dubbo.common.serialize.protobuf.support.ProtobufUtils.marshaller(
 org.apache.dubbo.demo.HelloReply.getDefaultInstance());
 org.apache.dubbo.common.serialize.protobuf.support.ProtobufUtils.marshaller(
 org.apache.dubbo.demo.HelloRequest.getDefaultInstance());
 }
 } catch (ClassNotFoundException e) {
// ignore
 }
 return clazz;
 }

 private DemoServiceDubbo() {
 }

 public static final String SERVICE_NAME = "org.apache.dubbo.demo.DemoService";

 /**
 * Code generated for Dubbo
 */
 public interface IDemoService extends org.apache.dubbo.rpc.model.DubboStub {

 static Class<?> clazz = init();

 org.apache.dubbo.demo.HelloReply sayHello(org.apache.dubbo.demo.HelloRequest request);

 CompletableFuture<org.apache.dubbo.demo.HelloReply> sayHelloAsync(org.apache.dubbo.demo.HelloRequest request);


 }

}

配置列表

Dubbo Maven Plugin For Protobuf 支持以下配置：

配置工作原理

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

本文主要讲解 Dubbo 配置相关的 API 与工作原理，学习 Dubbo 的多种配置源、每种配置源的具体配置方式、不同配置源之间的优先级与覆盖关系。

实现原理

为了更好地管理各种配置，Dubbo 抽象了一套结构化的配置组件，各组件总体以用途划分，分别控制不同作用域的行为。

组件名称	描述	范围	是否必须配置
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的子配置	可选

从实现原理层面，最终 Dubbo 所有的配置项都会被组装到 URL 中，以 URL 为载体在后续的启动、RPC 调用过程中传递，进而控制框架行为。如想了解更多，请参照 Dubbo 源码解析系列文档或 Blog。

配置项参考手册

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

JVM(-D) 参数

JVM 参数	示例值	说明
dubbo.{config-name}.{property}	-Ddubbo.application.name=“dubbo-demo” -Ddubbo.registry.address=“nacos://host:port” -Ddubbo.protocol.port=“20880” ……	Dubbo支持 `所有的配置项` 以JVM参数格式指定。其中`config` 是指如 application、registry、protocol 等配置项，而`property`则是指每个配置项中的具体属性。
dubbo.resolve.file	-Ddubbo.resolve.file=/home/ken/…/dubbo-resolve.properties	在文件中指定每个接口的直连地址url，如：org.apache.dubbo.demo.DemoService=tri://127.0.0.1:50051/org.apache.dubbo.demo.DemoService?xxx=xxx
org.graalvm.nativeimage.imagecode		https://github.com/oracle/graal/blob/master/sdk/src/org.graalvm.nativeimage/src/org/graalvm/nativeimage/ImageInfo.java
dubbo.properties.file	-Ddubbo.properties.file=foo.properties	指定 properties 配置文件地址，可以是绝对路径或者classpath相对路径。默认值为 dubbo.properties
dubbo.jstack-dump.max-line	-Ddubbo.jstack-dump.max-line=20	Dubbo 支持自动打印调用堆栈，这个参数可以控制堆栈行数，如示例中只会打印前20行堆栈
dubbo.json-framework.prefer	-Ddubbo.json-framework.prefer=gson	设置框架中 json 序列化的具体实现，目前可选实现有 `fastjson2`、`fastjson`、`gson`、`jackson`。默认情况，框架会自动查找可用实现，以上按顺序优先级依次降低
dubbo.network.interface.ignored	-Ddubbo.network.interface.ignored=eth1,eth2	在多网卡环境下，当需要手动控制注册到注册中心的网卡地址时使用。用于排除某些网卡
dubbo.network.interface.preferred	-Ddubbo.network.interface.preferred=eth0	在多网卡环境下，当需要手动控制注册到注册中心的网卡地址时使用。用于指定一个特定网卡
sun.rmi.transport.tcp.responseTimeout	-Dsun.rmi.transport.tcp.responseTimeout=5000	用于设置 RMI 协议下的超时时间，单位ms
env		Apollo 配置中心特有参数
app.id		Apollo 配置中心特有参数
apollo.cluster		Apollo 配置中心特有参数
apollo.meta		Apollo 配置中心特有参数
dubbo.mapping.cache.filePath	-Ddubbo.mapping.cache.filePath=~/.dubbo/mapping/	用于设置`接口-应用`映射关系缓存文件，通常用于服务发现。文件绝对路径地址
dubbo.mapping.cache.fileName	-Ddubbo.mapping.cache.fileName=dubbo-mapping	用于设置`接口-应用`映射关系缓存文件，通常用于服务发现。文件名，如此示例最终会读取和存储在文件 dubbo-mapping.dubbo.cache
dubbo.mapping.cache.entrySize	-Ddubbo.mapping.cache.maxFileSize=300	用于设置`接口-应用`映射关系缓存文件，通常用于服务发现。文件名中内容最大条目数限制
dubbo.mapping.cache.maxFileSize	-Ddubbo.mapping.cache.maxFileSize=104857600	用于设置`接口-应用`映射关系缓存文件，通常用于服务发现。文件最大占用空间限制，单位byte
dubbo.meta.cache.filePath	-Ddubbo.meta.cache.filePath=~/.dubbo/meta/	用于设置`metadata元数据`缓存文件，通常用于服务发现。文件绝对路径地址
dubbo.meta.cache.fileName	-Ddubbo.meta.cache.fileName=dubbo-meta	用于设置`metadata元数据`缓存文件，通常用于服务发现。文件名，如此示例最终会读取和存储在文件 dubbo-meta.dubbo.cache
dubbo.meta.cache.entrySize	-Ddubbo.meta.cache.maxFileSize=300	用于设置`metadata元数据`缓存文件，通常用于服务发现。文件名中内容最大条目数限制
dubbo.meta.cache.maxFileSize	-Ddubbo.meta.cache.maxFileSize=104857600	用于设置`metadata元数据`缓存文件，通常用于服务发现。文件最大占用空间限制，单位byte
dubbo.application.use-secure-random-request-id	-Ddubbo.application.use-secure-random-request-id=true	设置每次 rpc 调用 request id 的生成规则，是不是用随机值。如不设置则使用递增值。
dubbo.protocol.default-close-timeout	-Ddubbo.protocol.default-close-timeout=10000	设置 tcp server 关闭等待时间，单位毫秒ms
dubbo.protocol.default-heartbeat	-Ddubbo.protocol.default-heartbeat=10000	设置发起心跳 heartbeat 的间隔，单位毫秒ms
dubbo.hessian.allowNonSerializable		是否允许对没有实现 Serializable 接口的类进行序列化，对hessian序列化有效
dubbo.application.hessian2.whitelist	-Ddubbo.application.hessian2.whitelist=true	设置是否启用白名单机制，对hessian序列化有效。如果设置 true，则继续配置下面的 allow 规则；否则，配置 deny 规则
dubbo.application.hessian2.allow	-Ddubbo.application.hessian2.allow=org.apache.dubbo.;com.company.	如果设置 true，则继续配置配置 allow 规则，参见文档说明
dubbo.application.hessian2.deny	-Ddubbo.application.hessian2.deny=org.apache.dubbo.;io.commons.	如果设置 false，则继续配置配置 deny 规则，参见文档说明
dubbo.application.manual-register	-Ddubbo.application.manual-register=true	设置之后，所有服务都不会被自动注册到注册中心，直到用户调用 online 等命令手动完成注册
dubbo.compact.enable
dubbo.migration-file.enable	-Ddubbo.migration-file.enable=true	在往应用级地址发现迁移时，是否启用规则文件读取
dubbo.migration.file	-Ddubbo.migration.file=dubbo-migration.yaml	指定往应用级地址发现迁移的规则文件路径，可以是绝对路径或者classpath相对路径。默认值为 dubbo-migration.yaml
dubbo.application.logger	-Ddubbo.application.logger=slf4j	设置dubbo框架使用的日志组件，设置后，dubbo框架自身的日志将打印到这里（不影响应用自身）；目前支持的 slf4j、log4j、log4j2 等，设置之后须确保相应的组件依赖已经加入应用。
dubbo.properties.file	-Ddubbo.properties.file=foo.properties	指定 properties 配置文件地址，可以是绝对路径或者classpath相对路径。默认值为 dubbo.properties

环境变量

环境变量	示例值	说明
DUBBO_{CONFIG-NAME}.{PROPERTY}	DUBBO_APPLICATION_NAME=“dubbo-demo” DUBBO_REGISTRY_ADDRESS=“nacos://host:port” DUBBO_PROTOCOL_PORT=“20880” ……	Dubbo支持`所有的配置项`以环境变量格式指定。其中`CONFIG-NAME` 是指如 application、registry、protocol 等配置项，而 `PROPERTY`则是指每个配置项中的具体属性。
DUBBO_DEFAULT_SERIALIZATION	DUBBO_DEFAULT_SERIALIZATION=“hessan2”	设置框架的默认序列化方式，如hessian2、fastjson2、msgpack等
DUBBO2_COMPACT_ENABLE	DUBBO2_COMPAT_ENABLE=“true”
DUBBO_ENV_KEYS	DUBBO_LABELS=“tag1=value1; tag2=value2”	`tag1=value1`会作为附加参数上报到地址 URL，作为系统环境变量可用于为实例打标等。
DUBBO_LABELS	DUBBO_ENV_KEYS=“DUBBO_TAG1, DUBBO_TAG2”	Dubbo 会读取 `DUBBO_TAG1`、`DUBBO_TAG2`两个环境变量，并将读取的值 value `DUBBO_TAG1=value` 作为附加参数上报到地址 URL。
POD_NAMESPACE		用于 Kubernetes Service 场景，指定命名空间
CLUSTER_DOMAIN		用于 Kubernetes Service 场景，指定集群名称，默认 default
DUBBO_IP_TO_REGISTRY	DUBBO_IP_TO_REGISTRY=30.123.45.187	指定注册到注册中心 URL 中的 ip 地址
DUBBO_PORT_TO_REGISTRY	DUBBO_PORT_TO_REGISTRY=20880	指定注册到注册中心 URL 中的 port 端口号
DUBBO_{PROTOCOL}_PORT_TO_REGISTRY	DUBBO_DUBBO_IP_TO_REGISTRY=30.123.45.187 DUBBO_TRI_IP_TO_REGISTRY=30.123.45.187	指定注册到注册中心 URL 中的 ip 地址，可以为不同协议指定不同 ip
DUBBO_{PROTOCOL}_PORT_TO_REGISTRY	DUBBO_DUBBO_PORT_TO_REGISTRY=20880 DUBBO_TRI_PORT_TO_REGISTRY=50051	指定注册到注册中心 URL 中的 port 端口，可以为不同协议指定不同 port
DUBBO_IP_TO_BIND	DUBBO_IP_TO_BIND=30.123.45.187	指定 tcp 监听绑定的 ip 地址
DUBBO_PORT_TO_BIND	DUBBO_PORT_TO_BIND=20880	指定 tcp 监听绑定的 port 端口
DUBBO_{PROTOCOL}_IP_TO_BIND	DUBBO_DUBBO_IP_TO_BIND=30.123.45.187 DUBBO_TRI_IP_TO_BIND=30.123.45.187	指定 tcp 监听绑定的 ip 地址，可以为不同协议指定不同 ip
DUBBO_{PROTOCOL}_PORT_TO_BIND	DUBBO_DUBBO_PORT_TO_BIND=20880 DUBBO_TRI_PORT_TO_BIND=50051	指定 tcp 监听绑定的 port 端口，可以为不同协议指定不同 port
dubbo.properties.file	dubbo.properties.file=foo.properties	指定 properties 配置文件地址，可以是绝对路径或者classpath相对路径。默认值为 dubbo.properties
dubbo.migration.file	dubbo.migration.file=dubbo-migration.yaml	指定应用级地址发现的迁移规则的文件地址，可以是绝对路径或者classpath相对路径。默认值为 dubbo-migration.yaml

配置项手册

不论您是使用 Spring Boot、XML、注解还是 API 编写 Dubbo 应用，都可以通过以下表格参考每一项的具体含义。