Apache Dubbo 中文 on Apache Dubbo

阿里巴巴升级 Dubbo3 全面取代 HSF2

Mon, 16 Jan 2023 00:00:00 +0000

继业务全面上云后，2022 双十一，阿里巴巴微服务技术栈全面迁移到以 Dubbo3 为代表的云上开源标准中间件体系。在业务上，基于 Dubbo3 首次实现了关键业务不停推、不降级的全面用户体验提升，从技术上，大幅提高研发与运维效率的同时地址推送等关键资源利用率提升超 40%，基于三位一体的 Dubbo3 开源中间件体系打造了阿里在云上的单元化最佳实践和统一标准，同时将规模化实践经验与技术创新贡献开源社区，成为微服务开源技术与标准发展的核心源泉与推动力。

1 阿里电商

……

整个电商体系的所有核心应用，包括交易相关、导购相关都都升级到了 Dubbo3 体系，用来升级原有的 HSF 框架，阿里电商是对 Dubbo3 实践最广泛、需求最强烈的体系，基于 Dubbo3 实现了以下关键目标。 2022 618大促、双11 大促期间超 2000+ 应用、40w 节点均跑在 Dubbo3 之上。

应用级服务发现，解决了大促期间地址推送降级的问题，部分关键链路提升单机资源利用率 40%，大促期间地址推送SLA保障、资源利用率。
Triple协议，解决跨网关高效互通的问题，同时部分业务线升级了 Streaming 编程和通信模式。
统一的流量治理规则，阿里电商场景的路由规则非常复杂，基于实现了云原生体系的结合。
Service Mesh 解决方案，Thin SDK + Proxyless 的解决方案
服务柔性，目前正在落地和探索自适应负载均衡、自适应限流等策略。

2 蚂蚁金服

阿里集团内与蚂蚁体系的互通，目前都跑在 Dubbo3 Triple 互通链路上，与原有基于 HSF 的互通方案对比，Triple 协议链路的 RT 降低了 50%。集团与蚂蚁东西向流量的核心链路，飞猪、手淘、口碑、饿了么、1688、部分导购应用、商品库、评价等业务都采用此方案。

3 本地生活

截止 2022 年初，Dubbo3 实现了在饿了么全量业务的生产上线，取代了之前自建的微服务体系，在过去的近一年时间内，饿了么线上有 2000 应用、15w 实例节点平稳跑在 Dubbo3 之上。

0-1 - 线程池资源枯竭

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

服务端的线程资源耗尽了。默认情况下，Dubbo 服务端的业务线程数是 200 个。如果多个并发请求量超过了 200，就会拒绝新的请求，抛出此错误。

可能的原因

Consumer 的并发请求量太大，导致 Provider 端创建的线程数量超限。
可能 Provider 端在执行业务的时候，由于业务调用外部应用接口，导致线程出现阻塞，从而导致线程池回收不了线程。

排查和解决步骤

开启 Dubbo 的访问日志功能，排查是否有短时间内大量调用 RPC 服务的情况。
通过 jps 和 jstack 指令检查线程池中各个线程的状态，看下是否有业务调用外部应用接口造成阻塞。
如果是 Consumer 的并发请求量太大，那么调整 Provider 端的 dubbo.provider.threads 参数，将 Dubbo 的线程池的数目调大。
如果 Provider 业务的 QPS 实在太大，目前的服务器数目处理不完，那么增加 Provider 端服务器的数量，让更多的服务器分担压力。

这个错误码的 FAQ 页面参考了空冥同学的《Dubbo 常见错误及解决方法》。所引文章通过 CC-BY-4.0 协议赋予了汇编的权利。在此向原作者表示感谢。

1-1 - 地址非法

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

此日志可以忽略，服务版本或分组不匹配。仅出现在 zookeeper 注册中心中，在 3.1.7 版本中已经取消此检查。

可能的原因

Provider 端配置的 service.group 和 Consumer 端配置的 reference.group （即服务分组的配置）不匹配。
Provider 端配置的 service.version 和 Consumer 端配置的 reference.version （即服务版本的配置）不匹配。

排查和解决步骤

可以忽略，在 3.1.7 版本中已经取消此检查。

2-1 - 路由选址执行失败

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

路由选址执行失败

2.x 升级至 3.x

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

升级到 Dubbo 3.X 的收益

Dubbo3 依旧保持了 2.x 的经典架构，以解决微服务进程间通信为主要职责，通过丰富的服务治理（如地址发现、流量管理等）能力来更好的管控微服务集群；Dubbo3 对原有框架的升级是全面的，体现在核心 Dubbo 特性的几乎每个环节，通过升级实现了稳定性、性能、伸缩性、易用性的全面提升。

通用的通信协议。 全新的 RPC 协议应摒弃私有协议栈，以更通用的 HTTP/2 协议为传输层载体，借助 HTTP 协议的标准化特性，解决流量通用性、穿透性等问题，让协议能更好的应对前后端对接、网关代理等场景；支持 Stream 通信模式，满足不同业务通信模型诉求的同时给集群带来更大的吞吐量。
面向百万集群实例，集群高度可伸缩。 随着微服务实践的推广，微服务集群实例的规模也在不停的扩展，这得益于微服务轻量化、易于水平扩容的特性，同时也给整个集群容量带来了负担，尤其是一些中心化的服务治理组件；Dubbo3 需要解决实例规模扩展带来的种种资源瓶颈问题，实现真正的无限水平扩容。
全面拥抱云原生。

Dubbo 3.0 新特性

Dubbo 3.0 提供的新特性包括：

新的地址发现模型（应用级服务发现）。
- 查看应用级服务发现迁移示例。
- 查看应用级服务发现的迁移步骤
- 查看应用级服务发现地址迁移规则说明
下一代基于 HTTP/2 的 Triple 协议。
- 查看Triple 协议迁移步骤
- 查看 Triple 协议使用方式
- 查看 Triple 协议设计与实现。
统一的路由规则。
- 查看统一路由规则设计与实现

升级前的兼容性检查

在跨版本升级的过程中，存在的风险点从大到小分别有：直接修改 Dubbo 源码 -> 基于 Dubbo SPI 扩展点进行扩展 -> 基于 API 或者 Spring 的使用方式。

1. 直接修改 Dubbo 源码

对于直接修改 Dubbo 源码这部分的需要修改方自行判断是否在高版本中正常工作，对于这种非标准行为，Dubbo 无法保证其先前的兼容性。此外，通过 javagent 或者 asm 等通过运行时对 Dubbo 的修改也在此范围内。此类修改大部分可以通过后文提供的扫描工具检测出来。

3-1 - 将地址转换成 Invoker 失败

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

可能的原因

客户端配置的协议与服务端配置的协议并不匹配。（如客户端配置的协议是 Dubbo 协议，但服务端只能提供 Rest 协议的服务）
注册中心（或配置中心）不可靠，推送了并不合法的数据。

排查和解决步骤

检查提供方和消费方双方的协议配置。
更新注册中心的版本。

4-1 - 不支持的协议

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

可能的原因

这种情况可能出现在自定义 Protocol 的场景下。Dubbo 的 SPI 机制找不到 URL 中所指定的 Protocol。

排查和解决步骤

确定 Consumer 中有服务端所用到的 Protocol 的依赖。
确定 Protocol 的依赖包的 SPI 配置文件的名字没有写错。

另请参阅 Dubbo SPI 概述
 协议扩展说明

5-1 - 配置中心连接失败

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

可能的原因

配置中心所在的服务器关机或宕机。
IP 或者端口号写错。
防火墙错误拦截了配置中心的端口。

排查和解决步骤

检查配置中心 IP 以及端口的配置。
检查服务器是否开机，是否正常工作。
检查防火墙等是否放行配置中心所用的端口。

6-1 - 服务端连接失败

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

网络通信层，在连接服务提供者服务时失败

可能的原因

服务提供者的网络异常断开或受防火墙及第三方工具的拦截，无法对外提供服务。

排查和解决步骤

如果为 rest 连接，检查请求的服务端配置是否正确。
检查网络通信是否正常，可使用一些简单的 cmd 命令进行检测，如 ping 等。

7-1 - QOS 已关闭

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

可能的原因

QOS 已关闭

排查和解决步骤

请参考QOS 操作手册。

81-1 - ZK 启动异常

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

可能的原因

zk 的服务端版本与客户端版本存在不兼容问题，无法进行连接。
zk 服务未正常启动或防火墙等原因不能对外提供服务。

排查和解决步骤

确认客户端版本与服务端版本一致。
zk 能够正常启动或对外能够提供正常服务。

可通过一些第三方的工具或者jstack [PID] > jstack.log 分析堆栈信息，进行定位。

99-0 - 内部未知错误

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

Dubbo 内部的未知错误。

可能的原因

未知错误

排查和解决步骤

保护现场。将日志文件保存下来，尽可能记录下发生故障当时的情况。（此时可通过一些第三方的工具或者 jstack [PID] > jstack.log 分析堆栈信息。）
如果在这个错误码之前有其它的错误码的日志记录，那么请先查看一下那个错误码的记录。
检查配置文件是否有误。
如果是修改了代码引入了这个错误，尝试回滚到上一个版本。
如果都没解决，请尽可能做出一个复现该问题的最小 Demo，之后到 GitHub Issue Tracker 下发 Issue。

另请参阅配置项手册

Dubbo SPI

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

1.简介

SPI 全称为 Service Provider Interface，是一种服务发现机制。SPI 的本质是将接口实现类的全限定名配置在文件中，并由服务加载器读取配置文件，加载实现类。这样可以在运行时，动态为接口替换实现类。正因此特性，我们可以很容易的通过 SPI 机制为我们的程序提供拓展功能。SPI 机制在第三方框架中也有所应用，比如 Dubbo 就是通过 SPI 机制加载所有的组件。不过，Dubbo 并未使用 Java 原生的 SPI 机制，而是对其进行了增强，使其能够更好的满足需求。在 Dubbo 中，SPI 是一个非常重要的模块。基于 SPI，我们可以很容易的对 Dubbo 进行拓展。如果大家想要学习 Dubbo 的源码，SPI 机制务必弄懂。接下来，我们先来了解一下 Java SPI 与 Dubbo SPI 的用法，然后再来分析 Dubbo SPI 的源码。

需要特别说明的是，本篇文章以及本系列其他文章所分析的源码版本均为 dubbo-2.6.4。因此大家在阅读文章的过程中，需注意将代码版本切换到 dubbo-2.6.4 tag 上。

2.SPI 示例

2.1 Java SPI 示例

前面简单介绍了 SPI 机制的原理，本节通过一个示例演示 Java SPI 的使用方法。首先，我们定义一个接口，名称为 Robot。

public interface Robot {
 void sayHello();
}

接下来定义两个实现类，分别为 OptimusPrime 和 Bumblebee。

public class OptimusPrime implements Robot {
 
 @Override
 public void sayHello() {
 System.out.println("Hello, I am Optimus Prime.");
 }
}

public class Bumblebee implements Robot {

 @Override
 public void sayHello() {
 System.out.println("Hello, I am Bumblebee.");
 }
}

接下来 META-INF/services 文件夹下创建一个文件，名称为 Robot 的全限定名 org.apache.spi.Robot。文件内容为实现类的全限定的类名，如下：

dubbo 协议

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

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

Dubbo 缺省协议采用单一长连接和 NIO 异步通讯，适合于小数据量大并发的服务调用，以及服务消费者机器数远大于服务提供者机器数的情况。

反之，Dubbo 缺省协议不适合传送大数据量的服务，比如传文件，传视频等，除非请求量很低。

Transporter: mina, netty, grizzy
Serialization: dubbo, hessian2, java, json
Dispatcher: all, direct, message, execution, connection
ThreadPool: fixed, cached

特性

缺省协议，使用基于 netty 3.2.5.Final 和 hessian2 3.2.1-fixed-2(Alibaba embed version) 的 tbremoting 交互。

连接个数：单连接
连接方式：长连接
传输协议：TCP
传输方式：NIO 异步传输
序列化：Hessian 二进制序列化
适用范围：传入传出参数数据包较小（建议小于100K），消费者比提供者个数多，单一消费者无法压满提供者，尽量不要用 dubbo 协议传输大文件或超大字符串。
适用场景：常规远程服务方法调用

约束

参数及返回值需实现 Serializable 接口
参数及返回值不能自定义实现 List, Map, Number, Date, Calendar 等接口，只能用 JDK 自带的实现，因为 hessian 会做特殊处理，自定义实现类中的属性值都会丢失。
Hessian 序列化，只传成员属性值和值的类型，不传方法或静态变量，兼容情况 ¹²：

数据通讯	情况	结果
A->B	类A多一种属性（或者说类B少一种属性）	不抛异常，A多的那个属性的值，B没有，其他正常
A->B	枚举A多一种枚举（或者说B少一种枚举），A使用多出来的枚举进行传输	抛异常
A->B	枚举A多一种枚举（或者说B少一种枚举），A不使用多出来的枚举进行传输	不抛异常，B正常接收数据
A->B	A和B的属性名相同，但类型不相同	抛异常
A->B	serialId 不相同	正常传输

接口增加方法，对客户端无影响，如果该方法不是客户端需要的，客户端不需要重新部署。输入参数和结果集中增加属性，对客户端无影响，如果客户端并不需要新属性，不用重新部署。

dubbo 协议

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

Dubbo 缺省协议采用单一长连接和 NIO 异步通讯，适合于小数据量大并发的服务调用，以及服务消费者机器数远大于服务提供者机器数的情况。

反之，Dubbo 缺省协议不适合传送大数据量的服务，比如传文件，传视频等，除非请求量很低。

Transporter: mina, netty, grizzy
Serialization: dubbo, hessian2, java, json
Dispatcher: all, direct, message, execution, connection
ThreadPool: fixed, cached

特性

缺省协议，使用基于 netty 3.2.5.Final 和 hessian2 3.2.1-fixed-2(Alibaba embed version) 的 tbremoting 交互。

连接个数：单连接
连接方式：长连接
传输协议：TCP
传输方式：NIO 异步传输
序列化：Hessian 二进制序列化
适用范围：传入传出参数数据包较小（建议小于100K），消费者比提供者个数多，单一消费者无法压满提供者，尽量不要用 dubbo 协议传输大文件或超大字符串。
适用场景：常规远程服务方法调用

约束

参数及返回值需实现 Serializable 接口
参数及返回值不能自定义实现 List, Map, Number, Date, Calendar 等接口，只能用 JDK 自带的实现，因为 hessian 会做特殊处理，自定义实现类中的属性值都会丢失。
Hessian 序列化，只传成员属性值和值的类型，不传方法或静态变量，兼容情况 ¹²：

数据通讯	情况	结果
A->B	类A多一种属性（或者说类B少一种属性）	不抛异常，A多的那个属性的值，B没有，其他正常
A->B	枚举A多一种枚举（或者说B少一种枚举），A使用多出来的枚举进行传输	抛异常
A->B	枚举A多一种枚举（或者说B少一种枚举），A不使用多出来的枚举进行传输	不抛异常，B正常接收数据
A->B	A和B的属性名相同，但类型不相同	抛异常
A->B	serialId 不相同	正常传输

dubbo:application

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

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

应用信息配置。对应的配置类：org.apache.dubbo.config.ApplicationConfig

属性	对应URL参数	类型	是否必填	缺省值	作用	描述	兼容性
name	application	string	必填		服务治理	当前应用名称，用于注册中心计算应用间依赖关系，注意：消费者和提供者应用名不要一样，此参数不是匹配条件，你当前项目叫什么名字就填什么，和提供者消费者角色无关，比如：kylin应用调用了morgan应用的服务，则kylin项目配成kylin，morgan项目配成morgan，可能kylin也提供其它服务给别人使用，但kylin项目永远配成kylin，这样注册中心将显示kylin依赖于morgan	1.0.16以上版本
version	application.version	string	可选		服务治理	当前应用的版本	2.2.0以上版本
owner	owner	string	可选		服务治理	应用负责人，用于服务治理，请填写负责人公司邮箱前缀	2.0.5以上版本
organization	organization	string	可选		服务治理	组织名称(BU或部门)，用于注册中心区分服务来源，此配置项建议不要使用autoconfig，直接写死在配置中，比如china,intl,itu,crm,asc,dw,aliexpress等	2.0.0以上版本
architecture	architecture	string	可选		服务治理	用于服务分层对应的架构。如，intl、china。不同的架构使用不同的分层。	2.0.7以上版本
environment	environment	string	可选		服务治理	应用环境，如：develop/test/product，不同环境使用不同的缺省值，以及作为只用于开发测试功能的限制条件	2.0.0以上版本
compiler	compiler	string	可选	javassist	性能优化	Java字节码编译器，用于动态类的生成，可选：jdk或javassist	2.1.0以上版本
logger	logger	string	可选	slf4j	性能优化	日志输出方式，可选：slf4j,jcl,log4j,log4j2,jdk	2.2.0以上版本
metadata-type	metadata-type	String	可选	local	服务治理	metadata 传递方式，是以 Provider 视角而言的，Consumer 侧配置无效，可选值有： remote - Provider 把 metadata 放到远端注册中心，Consumer 从注册中心获取 local - Provider 把 metadata 放在本地，Consumer 从 Provider 处直接获取	2.7.6以上版本

dubbo:application

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

应用信息配置。对应的配置类：org.apache.dubbo.config.ApplicationConfig

属性	对应URL参数	类型	是否必填	缺省值	作用	描述	兼容性
name	application	string	必填		服务治理	当前应用名称，用于注册中心计算应用间依赖关系，注意：消费者和提供者应用名不要一样，此参数不是匹配条件，你当前项目叫什么名字就填什么，和提供者消费者角色无关，比如：kylin应用调用了morgan应用的服务，则kylin项目配成kylin，morgan项目配成morgan，可能kylin也提供其它服务给别人使用，但kylin项目永远配成kylin，这样注册中心将显示kylin依赖于morgan	1.0.16以上版本
version	application.version	string	可选		服务治理	当前应用的版本	2.2.0以上版本
owner	owner	string	可选		服务治理	应用负责人，用于服务治理，请填写负责人公司邮箱前缀	2.0.5以上版本
organization	organization	string	可选		服务治理	组织名称(BU或部门)，用于注册中心区分服务来源，此配置项建议不要使用autoconfig，直接写死在配置中，比如china,intl,itu,crm,asc,dw,aliexpress等	2.0.0以上版本
architecture	architecture	string	可选		服务治理	用于服务分层对应的架构。如，intl、china。不同的架构使用不同的分层。	2.0.7以上版本
environment	environment	string	可选		服务治理	应用环境，如：develop/test/product，不同环境使用不同的缺省值，以及作为只用于开发测试功能的限制条件	2.0.0以上版本
compiler	compiler	string	可选	javassist	性能优化	Java字节码编译器，用于动态类的生成，可选：jdk或javassist	2.1.0以上版本
logger	logger	string	可选	slf4j	性能优化	日志输出方式，可选：slf4j,jcl,log4j,log4j2,jdk	2.2.0以上版本

dubbo:argument

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

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

方法参数配置。对应的配置类： org.apache.dubbo.config.ArgumentConfig。该标签为 <dubbo:method> 的子标签，用于方法参数的特征描述，比如：

<dubbo:method name="findXxx" timeout="3000" retries="2">
 <dubbo:argument index="0" callback="true" />
</dubbo:method>

属性	对应URL参数	类型	是否必填	作用	描述	兼容性
index		int	必填	标识	参数索引	2.0.6以上版本
type		String	与index二选一	标识	通过参数类型查找参数的index	2.0.6以上版本
callback	<metodName><index>.retries	boolean	可选	服务治理	参数是否为callback接口，如果为callback，服务提供方将生成反向代理，可以从服务提供方反向调用消费方，通常用于事件推送.	2.0.6以上版本

dubbo:argument

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

方法参数配置。对应的配置类： org.apache.dubbo.config.ArgumentConfig。该标签为 <dubbo:method> 的子标签，用于方法参数的特征描述，比如：

<dubbo:method name="findXxx" timeout="3000" retries="2">
 <dubbo:argument index="0" callback="true" />
</dubbo:method>

属性	对应URL参数	类型	是否必填	作用	描述	兼容性
index		int	必填	标识	参数索引	2.0.6以上版本
type		String	与index二选一	标识	通过参数类型查找参数的index	2.0.6以上版本
callback	<metodName><index>.retries	boolean	可选	服务治理	参数是否为callback接口，如果为callback，服务提供方将生成反向代理，可以从服务提供方反向调用消费方，通常用于事件推送.	2.0.6以上版本

dubbo:config-center

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

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

配置中心。对应的配置类：org.apache.dubbo.config.ConfigCenterConfig

属性	对应URL参数	类型	是否必填	缺省值	描述	兼容性
protocol	config.protocol	string	可选	zookeeper	使用哪个配置中心：apollo、zookeeper、nacos等。以zookeeper为例 1. 指定protocol，则address可以简化为`127.0.0.1:2181`； 2. 不指定protocol，则address取值为`zookeeper://127.0.0.1:2181`	2.7.0+
address	config.address	string	必填		配置中心地址。取值参见protocol说明	2.7.0+
highest-priority	config.highestPriority	boolean	可选	true	来自配置中心的配置项具有最高优先级，即会覆盖本地配置项。	2.7.0+
namespace	config.namespace	string	可选	dubbo	通常用于多租户隔离，实际含义视具体配置中心而不同。如： zookeeper - 环境隔离，默认值`dubbo`； apollo - 区分不同领域的配置集合，默认使用`dubbo`和`application`	2.7.0+
cluster	config.cluster	string	可选		含义视所选定的配置中心而不同。如Apollo中用来区分不同的配置集群	2.7.0+
group	config.group	string	可选	dubbo	含义视所选定的配置中心而不同。 nacos - 隔离不同配置集 zookeeper - 隔离不同配置集	2.7.0+
check	config.check	boolean	可选	true	当配置中心连接失败时，是否终止应用启动。	2.7.0+
config-file	config.configFile	string	可选	dubbo.properties	全局级配置文件所映射到的key zookeeper - 默认路径/dubbo/config/dubbo/dubbo.properties apollo - dubbo namespace中的dubbo.properties键	2.7.0+
timeout	config.timeout	integer		3000ms	获取配置的超时时间	2.7.0+
username		string			如果配置中心需要做校验，用户名 Apollo暂未启用	2.7.0+
password		string			如果配置中心需要做校验，密码 Apollo暂未启用	2.7.0+
parameters		Map<string, string>			扩展参数，用来支持不同配置中心的定制化配置参数	2.7.0+
include-spring-env		boolean	可选	false	使用Spring框架时支持，为true时，会自动从Spring Environment中读取配置。默认依次读取 key为dubbo.properties的配置 key为dubbo.properties的PropertySource	2.7.0+

dubbo:config-center

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

配置中心。对应的配置类：org.apache.dubbo.config.ConfigCenterConfig

属性	对应URL参数	类型	是否必填	缺省值	描述	兼容性
protocol	config.protocol	string	可选	zookeeper	使用哪个配置中心：apollo、zookeeper、nacos等。以zookeeper为例 1. 指定protocol，则address可以简化为`127.0.0.1:2181`； 2. 不指定protocol，则address取值为`zookeeper://127.0.0.1:2181`	2.7.0+
address	config.address	string	必填		配置中心地址。取值参见protocol说明	2.7.0+
highest-priority	config.highestPriority	boolean	可选	true	来自配置中心的配置项具有最高优先级，即会覆盖本地配置项。	2.7.0+
namespace	config.namespace	string	可选	dubbo	通常用于多租户隔离，实际含义视具体配置中心而不同。如： zookeeper - 环境隔离，默认值`dubbo`； apollo - 区分不同领域的配置集合，默认使用`dubbo`和`application`	2.7.0+
cluster	config.cluster	string	可选		含义视所选定的配置中心而不同。如Apollo中用来区分不同的配置集群	2.7.0+
group	config.group	string	可选	dubbo	含义视所选定的配置中心而不同。 nacos - 隔离不同配置集 zookeeper - 隔离不同配置集	2.7.0+
check	config.check	boolean	可选	true	当配置中心连接失败时，是否终止应用启动。	2.7.0+
config-file	config.configFile	string	可选	dubbo.properties	全局级配置文件所映射到的key zookeeper - 默认路径/dubbo/config/dubbo/dubbo.properties apollo - dubbo namespace中的dubbo.properties键	2.7.0+
timeout	config.timeout	integer		3000ms	获取配置的超时时间	2.7.0+
username		string			如果配置中心需要做校验，用户名 Apollo暂未启用	2.7.0+
password		string			如果配置中心需要做校验，密码 Apollo暂未启用	2.7.0+
parameters		Map<string, string>			扩展参数，用来支持不同配置中心的定制化配置参数	2.7.0+
include-spring-env		boolean	可选	false	使用Spring框架时支持，为true时，会自动从Spring Environment中读取配置。默认依次读取 key为dubbo.properties的配置 key为dubbo.properties的PropertySource	2.7.0+

dubbo:consumer

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

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

服务消费者缺省值配置。配置类： org.apache.dubbo.config.ConsumerConfig 。同时该标签为 <dubbo:reference> 标签的缺省值设置。

属性	对应URL参数	类型	是否必填	缺省值	作用	描述	兼容性
timeout	default.timeout	int	可选	1000	性能调优	远程服务调用超时时间(毫秒)	1.0.16以上版本
retries	default.retries	int	可选	2	性能调优	远程服务调用重试次数，不包括第一次调用，不需要重试请设为0,仅在cluster为failback/failover时有效	1.0.16以上版本
loadbalance	default.loadbalance	string	可选	random	性能调优	负载均衡策略，可选值：random,roundrobin,leastactive，分别表示：随机，轮询，最少活跃调用	1.0.16以上版本
async	default.async	boolean	可选	false	性能调优	是否缺省异步执行，不可靠异步，只是忽略返回值，不阻塞执行线程	2.0.0以上版本
connections	default.connections	int	可选	100	性能调优	每个服务对每个提供者的最大连接数，rmi、http、hessian等短连接协议支持此配置，dubbo协议长连接不支持此配置	1.0.16以上版本
generic	generic	boolean	可选	false	服务治理	是否缺省泛化接口，如果为泛化接口，将返回GenericService	2.0.0以上版本
check	check	boolean	可选	true	服务治理	启动时检查提供者是否存在，true报错，false忽略	1.0.16以上版本
proxy	proxy	string	可选	javassist	性能调优	生成动态代理方式，可选：jdk/javassist	2.0.5以上版本
owner	owner	string	可选		服务治理	调用服务负责人，用于服务治理，请填写负责人公司邮箱前缀	2.0.5以上版本
actives	default.actives	int	可选	0	性能调优	每服务消费者每服务每方法最大并发调用数	2.0.5以上版本
cluster	default.cluster	string	可选	failover	性能调优	集群方式，可选：failover/failfast/failsafe/failback/forking	2.0.5以上版本
filter	reference.filter	string	可选		性能调优	服务消费方远程调用过程拦截器名称，多个名称用逗号分隔	2.0.5以上版本
listener	invoker.listener	string	可选		性能调优	服务消费方引用服务监听器名称，多个名称用逗号分隔	2.0.5以上版本
registry		string	可选	缺省向所有registry注册	配置关联	向指定注册中心注册，在多个注册中心时使用，值为<dubbo:registry>的id属性，多个注册中心ID用逗号分隔，如果不想将该服务注册到任何registry，可将值设为N/A	2.0.5以上版本
layer	layer	string	可选		服务治理	服务调用者所在的分层。如：biz、dao、intl:web、china:acton。	2.0.7以上版本
init	init	boolean	可选	false	性能调优	是否在afterPropertiesSet()时饥饿初始化引用，否则等到有人注入或引用该实例时再初始化。	2.0.10以上版本
cache	cache	string/boolean	可选		服务治理	以调用参数为key，缓存返回结果，可选：lru, threadlocal, jcache等	Dubbo2.1.0及其以上版本支持
validation	validation	boolean	可选		服务治理	是否启用JSR303标准注解验证，如果启用，将对方法参数上的注解进行校验	Dubbo2.1.0及其以上版本支持
version	version	string	可选		服务治理	在 Dubbo 中为同一个服务配置多个版本	Dubbo2.2.0及其以上版本支持

dubbo:consumer

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

服务消费者缺省值配置。配置类： org.apache.dubbo.config.ConsumerConfig 。同时该标签为 <dubbo:reference> 标签的缺省值设置。

属性	对应URL参数	类型	是否必填	缺省值	作用	描述	兼容性
timeout	default.timeout	int	可选	1000	性能调优	远程服务调用超时时间(毫秒)	1.0.16以上版本
retries	default.retries	int	可选	2	性能调优	远程服务调用重试次数，不包括第一次调用，不需要重试请设为0,仅在cluster为failback/failover时有效	1.0.16以上版本
loadbalance	default.loadbalance	string	可选	random	性能调优	负载均衡策略，可选值：random,roundrobin,leastactive，分别表示：随机，轮询，最少活跃调用	1.0.16以上版本
async	default.async	boolean	可选	false	性能调优	是否缺省异步执行，不可靠异步，只是忽略返回值，不阻塞执行线程	2.0.0以上版本
connections	default.connections	int	可选	100	性能调优	每个服务对每个提供者的最大连接数，rmi、http、hessian等短连接协议支持此配置，dubbo协议长连接不支持此配置	1.0.16以上版本
generic	generic	boolean	可选	false	服务治理	是否缺省泛化接口，如果为泛化接口，将返回GenericService	2.0.0以上版本
check	check	boolean	可选	true	服务治理	启动时检查提供者是否存在，true报错，false忽略	1.0.16以上版本
proxy	proxy	string	可选	javassist	性能调优	生成动态代理方式，可选：jdk/javassist	2.0.5以上版本
owner	owner	string	可选		服务治理	调用服务负责人，用于服务治理，请填写负责人公司邮箱前缀	2.0.5以上版本
actives	default.actives	int	可选	0	性能调优	每服务消费者每服务每方法最大并发调用数	2.0.5以上版本
cluster	default.cluster	string	可选	failover	性能调优	集群方式，可选：failover/failfast/failsafe/failback/forking	2.0.5以上版本
filter	reference.filter	string	可选		性能调优	服务消费方远程调用过程拦截器名称，多个名称用逗号分隔	2.0.5以上版本
listener	invoker.listener	string	可选		性能调优	服务消费方引用服务监听器名称，多个名称用逗号分隔	2.0.5以上版本
registry		string	可选	缺省向所有registry注册	配置关联	向指定注册中心注册，在多个注册中心时使用，值为<dubbo:registry>的id属性，多个注册中心ID用逗号分隔，如果不想将该服务注册到任何registry，可将值设为N/A	2.0.5以上版本
layer	layer	string	可选		服务治理	服务调用者所在的分层。如：biz、dao、intl:web、china:acton。	2.0.7以上版本
init	init	boolean	可选	false	性能调优	是否在afterPropertiesSet()时饥饿初始化引用，否则等到有人注入或引用该实例时再初始化。	2.0.10以上版本
cache	cache	string/boolean	可选		服务治理	以调用参数为key，缓存返回结果，可选：lru, threadlocal, jcache等	Dubbo2.1.0及其以上版本支持
validation	validation	boolean	可选		服务治理	是否启用JSR303标准注解验证，如果启用，将对方法参数上的注解进行校验	Dubbo2.1.0及其以上版本支持

dubbo:method

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

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

方法级配置。对应的配置类： org.apache.dubbo.config.MethodConfig。同时该标签为 <dubbo:service> 或 <dubbo:reference> 的子标签，用于控制到方法级。

属性	对应URL参数	类型	是否必填	缺省值	作用	描述	兼容性
name		string	必填		标识	方法名	1.0.8以上版本
timeout	<methodName>.timeout	int	可选	缺省为的timeout	性能调优	方法调用超时时间(毫秒)	1.0.8以上版本
retries	<methodName>.retries	int	可选	缺省为<dubbo:reference>的retries	性能调优	远程服务调用重试次数，不包括第一次调用，不需要重试请设为0	2.0.0以上版本
loadbalance	<methodName>.loadbalance	string	可选	缺省为的loadbalance	性能调优	负载均衡策略，可选值：random,roundrobin,leastactive，分别表示：随机，轮询，最少活跃调用	2.0.0以上版本
async	<methodName>.async	boolean	可选	缺省为<dubbo:reference>的async	性能调优	是否异步执行，不可靠异步，只是忽略返回值，不阻塞执行线程	1.0.9以上版本
sent	<methodName>.sent	boolean	可选	true	性能调优	异步调用时，标记sent=true时，表示网络已发出数据	2.0.6以上版本
actives	<methodName>.actives	int	可选	0	性能调优	每服务消费者最大并发调用限制	2.0.5以上版本
executes	<methodName>.executes	int	可选	0	性能调优	每服务每方法最大使用线程数限制- -，此属性只在<dubbo:method>作为<dubbo:service>子标签时有效	2.0.5以上版本
deprecated	<methodName>.deprecated	boolean	可选	false	服务治理	服务方法是否过时，此属性只在<dubbo:method>作为<dubbo:service>子标签时有效	2.0.5以上版本
sticky	<methodName>.sticky	boolean	可选	false	服务治理	设置true 该接口上的所有方法使用同一个provider.如果需要更复杂的规则，请使用路由	2.0.6以上版本
return	<methodName>.return	boolean	可选	true	性能调优	方法调用是否需要返回值,async设置为true时才生效，如果设置为true，则返回future，或回调onreturn等方法，如果设置为false，则请求发送成功后直接返回Null	2.0.6以上版本
oninvoke	attribute属性，不在URL中体现	String	可选		性能调优	方法执行前拦截	2.0.6以上版本
onreturn	attribute属性，不在URL中体现	String	可选		性能调优	方法执行返回后拦截	2.0.6以上版本
onthrow	attribute属性，不在URL中体现	String	可选		性能调优	方法执行有异常拦截	2.0.6以上版本
cache	<methodName>.cache	string/boolean	可选		服务治理	以调用参数为key，缓存返回结果，可选：lru, threadlocal, jcache等	Dubbo2.1.0及其以上版本支持
validation	<methodName>.validation	boolean	可选		服务治理	是否启用JSR303标准注解验证，如果启用，将对方法参数上的注解进行校验	Dubbo2.1.0及其以上版本支持

比如:

dubbo:method

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

方法级配置。对应的配置类： org.apache.dubbo.config.MethodConfig。同时该标签为 <dubbo:service> 或 <dubbo:reference> 的子标签，用于控制到方法级。

属性	对应URL参数	类型	是否必填	缺省值	作用	描述	兼容性
name		string	必填		标识	方法名	1.0.8以上版本
timeout	<methodName>.timeout	int	可选	缺省为的timeout	性能调优	方法调用超时时间(毫秒)	1.0.8以上版本
retries	<methodName>.retries	int	可选	缺省为<dubbo:reference>的retries	性能调优	远程服务调用重试次数，不包括第一次调用，不需要重试请设为0	2.0.0以上版本
loadbalance	<methodName>.loadbalance	string	可选	缺省为的loadbalance	性能调优	负载均衡策略，可选值：random,roundrobin,leastactive，分别表示：随机，轮询，最少活跃调用	2.0.0以上版本
async	<methodName>.async	boolean	可选	缺省为<dubbo:reference>的async	性能调优	是否异步执行，不可靠异步，只是忽略返回值，不阻塞执行线程	1.0.9以上版本
sent	<methodName>.sent	boolean	可选	true	性能调优	异步调用时，标记sent=true时，表示网络已发出数据	2.0.6以上版本
actives	<methodName>.actives	int	可选	0	性能调优	每服务消费者最大并发调用限制	2.0.5以上版本
executes	<methodName>.executes	int	可选	0	性能调优	每服务每方法最大使用线程数限制- -，此属性只在<dubbo:method>作为<dubbo:service>子标签时有效	2.0.5以上版本
deprecated	<methodName>.deprecated	boolean	可选	false	服务治理	服务方法是否过时，此属性只在<dubbo:method>作为<dubbo:service>子标签时有效	2.0.5以上版本
sticky	<methodName>.sticky	boolean	可选	false	服务治理	设置true 该接口上的所有方法使用同一个provider.如果需要更复杂的规则，请使用路由	2.0.6以上版本
return	<methodName>.return	boolean	可选	true	性能调优	方法调用是否需要返回值,async设置为true时才生效，如果设置为true，则返回future，或回调onreturn等方法，如果设置为false，则请求发送成功后直接返回Null	2.0.6以上版本
oninvoke	attribute属性，不在URL中体现	String	可选		性能调优	方法执行前拦截	2.0.6以上版本
onreturn	attribute属性，不在URL中体现	String	可选		性能调优	方法执行返回后拦截	2.0.6以上版本
onthrow	attribute属性，不在URL中体现	String	可选		性能调优	方法执行有异常拦截	2.0.6以上版本
cache	<methodName>.cache	string/boolean	可选		服务治理	以调用参数为key，缓存返回结果，可选：lru, threadlocal, jcache等	Dubbo2.1.0及其以上版本支持
validation	<methodName>.validation	boolean	可选		服务治理	是否启用JSR303标准注解验证，如果启用，将对方法参数上的注解进行校验	Dubbo2.1.0及其以上版本支持

比如:

dubbo:module

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

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

模块信息配置。对应的配置类 org.apache.dubbo.config.ModuleConfig

属性	对应URL参数	类型	是否必填	作用	描述	兼容性
name	module	string	必填	服务治理	当前模块名称，用于注册中心计算模块间依赖关系	2.2.0以上版本
version	module.version	string	可选	服务治理	当前模块的版本	2.2.0以上版本
owner	owner	string	可选	服务治理	模块负责人，用于服务治理，请填写负责人公司邮箱前缀	2.2.0以上版本
organization	organization	string	可选	服务治理	组织名称(BU或部门)，用于注册中心区分服务来源，此配置项建议不要使用autoconfig，直接写死在配置中，比如china,intl,itu,crm,asc,dw,aliexpress等	2.2.0以上版本

dubbo:module

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

模块信息配置。对应的配置类 org.apache.dubbo.config.ModuleConfig

属性	对应URL参数	类型	是否必填	作用	描述	兼容性
name	module	string	必填	服务治理	当前模块名称，用于注册中心计算模块间依赖关系	2.2.0以上版本
version	module.version	string	可选	服务治理	当前模块的版本	2.2.0以上版本
owner	owner	string	可选	服务治理	模块负责人，用于服务治理，请填写负责人公司邮箱前缀	2.2.0以上版本
organization	organization	string	可选	服务治理	组织名称(BU或部门)，用于注册中心区分服务来源，此配置项建议不要使用autoconfig，直接写死在配置中，比如china,intl,itu,crm,asc,dw,aliexpress等	2.2.0以上版本

dubbo:monitor

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

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

监控中心配置。对应的配置类： org.apache.dubbo.config.MonitorConfig

属性	对应URL参数	类型	是否必填	缺省值	作用	描述	兼容性
protocol	protocol	string	可选	dubbo	服务治理	监控中心协议，如果为protocol=“registry”，表示从注册中心发现监控中心地址，否则直连监控中心。	2.0.9以上版本
address	<url>	string	可选	N/A	服务治理	直连监控中心服务器地址，address=“10.20.130.230:12080”	1.0.16以上版本

dubbo:monitor

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

监控中心配置。对应的配置类： org.apache.dubbo.config.MonitorConfig

属性	对应URL参数	类型	是否必填	缺省值	作用	描述	兼容性
protocol	protocol	string	可选	dubbo	服务治理	监控中心协议，如果为protocol=“registry”，表示从注册中心发现监控中心地址，否则直连监控中心。	2.0.9以上版本
address	<url>	string	可选	N/A	服务治理	直连监控中心服务器地址，address=“10.20.130.230:12080”	1.0.16以上版本

dubbo:parameter

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

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

选项参数配置。对应的配置类：java.util.Map。同时该标签为<dubbo:protocol>或<dubbo:service>或<dubbo:provider>或<dubbo:reference>或<dubbo:consumer>的子标签，用于配置自定义参数，该配置项将作为扩展点设置自定义参数使用。

属性	对应URL参数	类型	是否必填	缺省值	作用	描述	兼容性
key	key	string	必填		服务治理	路由参数键	2.0.0以上版本
value	value	string	必填		服务治理	路由参数值	2.0.0以上版本

比如：

<dubbo:protocol name="napoli">
 <dubbo:parameter key="http://10.20.160.198/wiki/display/dubbo/napoli.queue.name" value="xxx" />
</dubbo:protocol>

也可以：

<dubbo:protocol name="jms" p:queue="xxx" />

dubbo:parameter

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

属性	对应URL参数	类型	是否必填	缺省值	作用	描述	兼容性
key	key	string	必填		服务治理	路由参数键	2.0.0以上版本
value	value	string	必填		服务治理	路由参数值	2.0.0以上版本

比如：

<dubbo:protocol name="napoli">
 <dubbo:parameter key="http://10.20.160.198/wiki/display/dubbo/napoli.queue.name" value="xxx" />
</dubbo:protocol>

也可以：

<dubbo:protocol name="jms" p:queue="xxx" />

dubbo:protocol

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

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

服务提供者协议配置。对应的配置类： org.apache.dubbo.config.ProtocolConfig。同时，如果需要支持多协议，可以声明多个 <dubbo:protocol> 标签，并在 <dubbo:service> 中通过 protocol 属性指定使用的协议。

属性	对应URL参数	类型	是否必填	缺省值	作用	描述	兼容性
id		string	可选	dubbo	配置关联	协议BeanId，可以在<dubbo:service protocol="">中引用此ID，如果ID不填，缺省和name属性值一样，重复则在name后加序号。	2.0.5以上版本
name	<protocol>	string	必填	dubbo	性能调优	协议名称	2.0.5以上版本
port	<port>	int	可选	dubbo协议缺省端口为20880，rmi协议缺省端口为1099，http和hessian协议缺省端口为80；如果没有配置port，则自动采用默认端口，如果配置为-1，则会分配一个没有被占用的端口。Dubbo 2.4.0+，分配的端口在协议缺省端口的基础上增长，确保端口段可控。	服务发现	服务端口	2.0.5以上版本
host	<host>	string	可选	自动查找本机IP	服务发现	-服务主机名，多网卡选择或指定VIP及域名时使用，为空则自动查找本机IP，-建议不要配置，让Dubbo自动获取本机IP	2.0.5以上版本
threadpool	threadpool	string	可选	fixed	性能调优	线程池类型，可选：fixed/cached	2.0.5以上版本
threads	threads	int	可选	200	性能调优	服务线程池大小(固定大小)	2.0.5以上版本
iothreads	threads	int	可选	cpu个数+1	性能调优	io线程池大小(固定大小)	2.0.5以上版本
accepts	accepts	int	可选	0	性能调优	服务提供方最大可接受连接数	2.0.5以上版本
payload	payload	int	可选	8388608(=8M)	性能调优	请求及响应数据包大小限制，单位：字节	2.0.5以上版本
codec	codec	string	可选	dubbo	性能调优	协议编码方式	2.0.5以上版本
serialization	serialization	string	可选	dubbo协议缺省为hessian2，rmi协议缺省为java，http协议缺省为json	性能调优	协议序列化方式，当协议支持多种序列化方式时使用，比如：dubbo协议的dubbo,hessian2,java,compactedjava，以及http协议的json等	2.0.5以上版本
accesslog	accesslog	string/boolean	可选		服务治理	设为true，将向logger中输出访问日志，也可填写访问日志文件路径，直接把访问日志输出到指定文件	2.0.5以上版本
path	<path>	string	可选		服务发现	提供者上下文路径，为服务path的前缀	2.0.5以上版本
transporter	transporter	string	可选	dubbo协议缺省为netty	性能调优	协议的服务端和客户端实现类型，比如：dubbo协议的mina,netty等，可以分拆为server和client配置	2.0.5以上版本
server	server	string	可选	dubbo协议缺省为netty，http协议缺省为servlet	性能调优	协议的服务器端实现类型，比如：dubbo协议的mina,netty等，http协议的jetty,servlet等	2.0.5以上版本
client	client	string	可选	dubbo协议缺省为netty	性能调优	协议的客户端实现类型，比如：dubbo协议的mina,netty等	2.0.5以上版本
dispatcher	dispatcher	string	可选	dubbo协议缺省为all	性能调优	协议的消息派发方式，用于指定线程模型，比如：dubbo协议的all, direct, message, execution, connection等	2.1.0以上版本
queues	queues	int	可选	0	性能调优	线程池队列大小，当线程池满时，排队等待执行的队列大小，建议不要设置，当线程池满时应立即失败，重试其它服务提供机器，而不是排队，除非有特殊需求。	2.0.5以上版本
charset	charset	string	可选	UTF-8	性能调优	序列化编码	2.0.5以上版本
buffer	buffer	int	可选	8192	性能调优	网络读写缓冲区大小	2.0.5以上版本
heartbeat	heartbeat	int	可选	0	性能调优	心跳间隔，对于长连接，当物理层断开时，比如拔网线，TCP的FIN消息来不及发送，对方收不到断开事件，此时需要心跳来帮助检查连接是否已断开	2.0.10以上版本
telnet	telnet	string	可选		服务治理	所支持的telnet命令，多个命令用逗号分隔	2.0.5以上版本
register	register	boolean	可选	true	服务治理	该协议的服务是否注册到注册中心	2.0.8以上版本
contextpath	contextpath	String	可选	缺省为空串	服务治理		2.0.6以上版本

dubbo:protocol

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

属性	对应URL参数	类型	是否必填	缺省值	作用	描述	兼容性
id		string	可选	dubbo	配置关联	协议BeanId，可以在<dubbo:service protocol="">中引用此ID，如果ID不填，缺省和name属性值一样，重复则在name后加序号。	2.0.5以上版本
name	<protocol>	string	必填	dubbo	性能调优	协议名称	2.0.5以上版本
port	<port>	int	可选	dubbo协议缺省端口为20880，rmi协议缺省端口为1099，http和hessian协议缺省端口为80；如果没有配置port，则自动采用默认端口，如果配置为-1，则会分配一个没有被占用的端口。Dubbo 2.4.0+，分配的端口在协议缺省端口的基础上增长，确保端口段可控。	服务发现	服务端口	2.0.5以上版本
host	<host>	string	可选	自动查找本机IP	服务发现	-服务主机名，多网卡选择或指定VIP及域名时使用，为空则自动查找本机IP，-建议不要配置，让Dubbo自动获取本机IP	2.0.5以上版本
threadpool	threadpool	string	可选	fixed	性能调优	线程池类型，可选：fixed/cached	2.0.5以上版本
threads	threads	int	可选	200	性能调优	服务线程池大小(固定大小)	2.0.5以上版本
iothreads	threads	int	可选	cpu个数+1	性能调优	io线程池大小(固定大小)	2.0.5以上版本
accepts	accepts	int	可选	0	性能调优	服务提供方最大可接受连接数	2.0.5以上版本
payload	payload	int	可选	8388608(=8M)	性能调优	请求及响应数据包大小限制，单位：字节	2.0.5以上版本
codec	codec	string	可选	dubbo	性能调优	协议编码方式	2.0.5以上版本
serialization	serialization	string	可选	dubbo协议缺省为hessian2，rmi协议缺省为java，http协议缺省为json	性能调优	协议序列化方式，当协议支持多种序列化方式时使用，比如：dubbo协议的dubbo,hessian2,java,compactedjava，以及http协议的json等	2.0.5以上版本
accesslog	accesslog	string/boolean	可选		服务治理	设为true，将向logger中输出访问日志，也可填写访问日志文件路径，直接把访问日志输出到指定文件	2.0.5以上版本
path	<path>	string	可选		服务发现	提供者上下文路径，为服务path的前缀	2.0.5以上版本
transporter	transporter	string	可选	dubbo协议缺省为netty	性能调优	协议的服务端和客户端实现类型，比如：dubbo协议的mina,netty等，可以分拆为server和client配置	2.0.5以上版本
server	server	string	可选	dubbo协议缺省为netty，http协议缺省为servlet	性能调优	协议的服务器端实现类型，比如：dubbo协议的mina,netty等，http协议的jetty,servlet等	2.0.5以上版本
client	client	string	可选	dubbo协议缺省为netty	性能调优	协议的客户端实现类型，比如：dubbo协议的mina,netty等	2.0.5以上版本
dispatcher	dispatcher	string	可选	dubbo协议缺省为all	性能调优	协议的消息派发方式，用于指定线程模型，比如：dubbo协议的all, direct, message, execution, connection等	2.1.0以上版本
queues	queues	int	可选	0	性能调优	线程池队列大小，当线程池满时，排队等待执行的队列大小，建议不要设置，当线程池满时应立即失败，重试其它服务提供机器，而不是排队，除非有特殊需求。	2.0.5以上版本
charset	charset	string	可选	UTF-8	性能调优	序列化编码	2.0.5以上版本
buffer	buffer	int	可选	8192	性能调优	网络读写缓冲区大小	2.0.5以上版本
heartbeat	heartbeat	int	可选	0	性能调优	心跳间隔，对于长连接，当物理层断开时，比如拔网线，TCP的FIN消息来不及发送，对方收不到断开事件，此时需要心跳来帮助检查连接是否已断开	2.0.10以上版本
telnet	telnet	string	可选		服务治理	所支持的telnet命令，多个命令用逗号分隔	2.0.5以上版本
register	register	boolean	可选	true	服务治理	该协议的服务是否注册到注册中心	2.0.8以上版本
contextpath	contextpath	String	可选	缺省为空串	服务治理		2.0.6以上版本

dubbo:provider

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

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

服务提供者缺省值配置。对应的配置类： org.apache.dubbo.config.ProviderConfig。同时该标签为 <dubbo:service> 和 <dubbo:protocol> 标签的缺省值设置。

属性	对应URL参数	类型	是否必填	缺省值	作用	描述	兼容性
id		string	可选	dubbo	配置关联	协议BeanId，可以在<dubbo:service proivder="">中引用此ID	1.0.16以上版本
protocol	<protocol>	string	可选	dubbo	性能调优	协议名称	1.0.16以上版本
host	<host>	string	可选	自动查找本机IP	服务发现	服务主机名，多网卡选择或指定VIP及域名时使用，为空则自动查找本机IP，建议不要配置，让Dubbo自动获取本机IP	1.0.16以上版本
threads	threads	int	可选	200	性能调优	服务线程池大小(固定大小)	1.0.16以上版本
payload	payload	int	可选	8388608(=8M)	性能调优	请求及响应数据包大小限制，单位：字节	2.0.0以上版本
path	<path>	string	可选		服务发现	提供者上下文路径，为服务path的前缀	2.0.0以上版本
server	server	string	可选	dubbo协议缺省为netty，http协议缺省为servlet	性能调优	协议的服务器端实现类型，比如：dubbo协议的mina,netty等，http协议的jetty,servlet等	2.0.0以上版本
client	client	string	可选	dubbo协议缺省为netty	性能调优	协议的客户端实现类型，比如：dubbo协议的mina,netty等	2.0.0以上版本
codec	codec	string	可选	dubbo	性能调优	协议编码方式	2.0.0以上版本
serialization	serialization	string	可选	dubbo协议缺省为hessian2，rmi协议缺省为java，http协议缺省为json	性能调优	协议序列化方式，当协议支持多种序列化方式时使用，比如：dubbo协议的dubbo,hessian2,java,compactedjava，以及http协议的json,xml等	2.0.5以上版本
default		boolean	可选	false	配置关联	是否为缺省协议，用于多协议	1.0.16以上版本
filter	service.filter	string	可选		性能调优	服务提供方远程调用过程拦截器名称，多个名称用逗号分隔	2.0.5以上版本
listener	exporter.listener	string	可选		性能调优	服务提供方导出服务监听器名称，多个名称用逗号分隔	2.0.5以上版本
threadpool	threadpool	string	可选	fixed	性能调优	线程池类型，可选：fixed/cached/limit(2.5.3以上)/eager(2.6.x以上)	2.0.5以上版本
accepts	accepts	int	可选	0	性能调优	服务提供者最大可接受连接数	2.0.5以上版本
version	version	string	可选	0.0.0	服务发现	服务版本，建议使用两位数字版本，如：1.0，通常在接口不兼容时版本号才需要升级	2.0.5以上版本
group	group	string	可选		服务发现	服务分组，当一个接口有多个实现，可以用分组区分	2.0.5以上版本
delay	delay	int	可选	0	性能调优	延迟注册服务时间(毫秒)- ，设为-1时，表示延迟到Spring容器初始化完成时暴露服务	2.0.5以上版本
timeout	default.timeout	int	可选	1000	性能调优	远程服务调用超时时间(毫秒)	2.0.5以上版本
retries	default.retries	int	可选	2	性能调优	远程服务调用重试次数，不包括第一次调用，不需要重试请设为0	2.0.5以上版本
connections	default.connections	int	可选	0	性能调优	对每个提供者的最大连接数，rmi、http、hessian等短连接协议表示限制连接数，dubbo等长连接协表示建立的长连接个数	2.0.5以上版本
loadbalance	default.loadbalance	string	可选	random	性能调优	负载均衡策略，可选值：random,roundrobin,leastactive，分别表示：随机，轮询，最少活跃调用	2.0.5以上版本
async	default.async	boolean	可选	false	性能调优	是否缺省异步执行，不可靠异步，只是忽略返回值，不阻塞执行线程	2.0.5以上版本
stub	stub	boolean	可选	false	服务治理	设为true，表示使用缺省代理类名，即：接口名 + Local后缀。	2.0.5以上版本
mock	mock	boolean	可选	false	服务治理	设为true，表示使用缺省Mock类名，即：接口名 + Mock后缀。	2.0.5以上版本
token	token	boolean	可选	false	服务治理	令牌验证，为空表示不开启，如果为true，表示随机生成动态令牌	2.0.5以上版本
registry	registry	string	可选	缺省向所有registry注册	配置关联	向指定注册中心注册，在多个注册中心时使用，值为<dubbo:registry>的id属性，多个注册中心ID用逗号分隔，如果不想将该服务注册到任何registry，可将值设为N/A	2.0.5以上版本
dynamic	dynamic	boolean	可选	true	服务治理	服务是否动态注册，如果设为false，注册后将显示后disable状态，需人工启用，并且服务提供者停止时，也不会自动取消册，需人工禁用。	2.0.5以上版本
accesslog	accesslog	string/boolean	可选	false	服务治理	设为true，将向logger中输出访问日志，也可填写访问日志文件路径，直接把访问日志输出到指定文件	2.0.5以上版本
owner	owner	string	可选		服务治理	服务负责人，用于服务治理，请填写负责人公司邮箱前缀	2.0.5以上版本
document	document	string	可选		服务治理	服务文档URL	2.0.5以上版本
weight	weight	int	可选		性能调优	服务权重	2.0.5以上版本
executes	executes	int	可选	0	性能调优	服务提供者每服务每方法最大可并行执行请求数	2.0.5以上版本
actives	default.actives	int	可选	0	性能调优	每服务消费者每服务每方法最大并发调用数	2.0.5以上版本
proxy	proxy	string	可选	javassist	性能调优	生成动态代理方式，可选：jdk/javassist	2.0.5以上版本
cluster	default.cluster	string	可选	failover	性能调优	集群方式，可选：failover/failfast/failsafe/failback/forking	2.0.5以上版本
deprecated	deprecated	boolean	可选	false	服务治理	服务是否过时，如果设为true，消费方引用时将打印服务过时警告error日志	2.0.5以上版本
queues	queues	int	可选	0	性能调优	线程池队列大小，当线程池满时，排队等待执行的队列大小，建议不要设置，当线程池满时应立即失败，重试其它服务提供机器，而不是排队，除非有特殊需求。	2.0.5以上版本
charset	charset	string	可选	UTF-8	性能调优	序列化编码	2.0.5以上版本
buffer	buffer	int	可选	8192	性能调优	网络读写缓冲区大小	2.0.5以上版本
iothreads	iothreads	int	可选	CPU + 1	性能调优	IO线程池，接收网络读写中断，以及序列化和反序列化，不处理业务，业务线程池参见threads配置，此线程池和CPU相关，不建议配置。	2.0.5以上版本
telnet	telnet	string	可选		服务治理	所支持的telnet命令，多个命令用逗号分隔	2.0.5以上版本
<dubbo:service>	contextpath	contextpath	String	可选	缺省为空串	服务治理
layer	layer	string	可选		服务治理	服务提供者所在的分层。如：biz、dao、intl:web、china:acton。	2.0.7以上版本

dubbo:provider

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

服务提供者缺省值配置。对应的配置类： org.apache.dubbo.config.ProviderConfig。同时该标签为 <dubbo:service> 和 <dubbo:protocol> 标签的缺省值设置。

属性	对应URL参数	类型	是否必填	缺省值	作用	描述	兼容性
id		string	可选	dubbo	配置关联	协议BeanId，可以在<dubbo:service proivder="">中引用此ID	1.0.16以上版本
protocol	<protocol>	string	可选	dubbo	性能调优	协议名称	1.0.16以上版本
host	<host>	string	可选	自动查找本机IP	服务发现	服务主机名，多网卡选择或指定VIP及域名时使用，为空则自动查找本机IP，建议不要配置，让Dubbo自动获取本机IP	1.0.16以上版本
threads	threads	int	可选	200	性能调优	服务线程池大小(固定大小)	1.0.16以上版本
payload	payload	int	可选	8388608(=8M)	性能调优	请求及响应数据包大小限制，单位：字节	2.0.0以上版本
path	<path>	string	可选		服务发现	提供者上下文路径，为服务path的前缀	2.0.0以上版本
server	server	string	可选	dubbo协议缺省为netty，http协议缺省为servlet	性能调优	协议的服务器端实现类型，比如：dubbo协议的mina,netty等，http协议的jetty,servlet等	2.0.0以上版本
client	client	string	可选	dubbo协议缺省为netty	性能调优	协议的客户端实现类型，比如：dubbo协议的mina,netty等	2.0.0以上版本
codec	codec	string	可选	dubbo	性能调优	协议编码方式	2.0.0以上版本
serialization	serialization	string	可选	dubbo协议缺省为hessian2，rmi协议缺省为java，http协议缺省为json	性能调优	协议序列化方式，当协议支持多种序列化方式时使用，比如：dubbo协议的dubbo,hessian2,java,compactedjava，以及http协议的json,xml等	2.0.5以上版本
default		boolean	可选	false	配置关联	是否为缺省协议，用于多协议	1.0.16以上版本
filter	service.filter	string	可选		性能调优	服务提供方远程调用过程拦截器名称，多个名称用逗号分隔	2.0.5以上版本
listener	exporter.listener	string	可选		性能调优	服务提供方导出服务监听器名称，多个名称用逗号分隔	2.0.5以上版本
threadpool	threadpool	string	可选	fixed	性能调优	线程池类型，可选：fixed/cached/limit(2.5.3以上)/eager(2.6.x以上)	2.0.5以上版本
accepts	accepts	int	可选	0	性能调优	服务提供者最大可接受连接数	2.0.5以上版本
version	version	string	可选	0.0.0	服务发现	服务版本，建议使用两位数字版本，如：1.0，通常在接口不兼容时版本号才需要升级	2.0.5以上版本
group	group	string	可选		服务发现	服务分组，当一个接口有多个实现，可以用分组区分	2.0.5以上版本
delay	delay	int	可选	0	性能调优	延迟注册服务时间(毫秒)- ，设为-1时，表示延迟到Spring容器初始化完成时暴露服务	2.0.5以上版本
timeout	default.timeout	int	可选	1000	性能调优	远程服务调用超时时间(毫秒)	2.0.5以上版本
retries	default.retries	int	可选	2	性能调优	远程服务调用重试次数，不包括第一次调用，不需要重试请设为0	2.0.5以上版本
connections	default.connections	int	可选	0	性能调优	对每个提供者的最大连接数，rmi、http、hessian等短连接协议表示限制连接数，dubbo等长连接协表示建立的长连接个数	2.0.5以上版本
loadbalance	default.loadbalance	string	可选	random	性能调优	负载均衡策略，可选值：random,roundrobin,leastactive，分别表示：随机，轮询，最少活跃调用	2.0.5以上版本
async	default.async	boolean	可选	false	性能调优	是否缺省异步执行，不可靠异步，只是忽略返回值，不阻塞执行线程	2.0.5以上版本
stub	stub	boolean	可选	false	服务治理	设为true，表示使用缺省代理类名，即：接口名 + Local后缀。	2.0.5以上版本
mock	mock	boolean	可选	false	服务治理	设为true，表示使用缺省Mock类名，即：接口名 + Mock后缀。	2.0.5以上版本
token	token	boolean	可选	false	服务治理	令牌验证，为空表示不开启，如果为true，表示随机生成动态令牌	2.0.5以上版本
registry	registry	string	可选	缺省向所有registry注册	配置关联	向指定注册中心注册，在多个注册中心时使用，值为<dubbo:registry>的id属性，多个注册中心ID用逗号分隔，如果不想将该服务注册到任何registry，可将值设为N/A	2.0.5以上版本
dynamic	dynamic	boolean	可选	true	服务治理	服务是否动态注册，如果设为false，注册后将显示后disable状态，需人工启用，并且服务提供者停止时，也不会自动取消册，需人工禁用。	2.0.5以上版本
accesslog	accesslog	string/boolean	可选	false	服务治理	设为true，将向logger中输出访问日志，也可填写访问日志文件路径，直接把访问日志输出到指定文件	2.0.5以上版本
owner	owner	string	可选		服务治理	服务负责人，用于服务治理，请填写负责人公司邮箱前缀	2.0.5以上版本
document	document	string	可选		服务治理	服务文档URL	2.0.5以上版本
weight	weight	int	可选		性能调优	服务权重	2.0.5以上版本
executes	executes	int	可选	0	性能调优	服务提供者每服务每方法最大可并行执行请求数	2.0.5以上版本
actives	default.actives	int	可选	0	性能调优	每服务消费者每服务每方法最大并发调用数	2.0.5以上版本
proxy	proxy	string	可选	javassist	性能调优	生成动态代理方式，可选：jdk/javassist	2.0.5以上版本
cluster	default.cluster	string	可选	failover	性能调优	集群方式，可选：failover/failfast/failsafe/failback/forking	2.0.5以上版本
deprecated	deprecated	boolean	可选	false	服务治理	服务是否过时，如果设为true，消费方引用时将打印服务过时警告error日志	2.0.5以上版本
queues	queues	int	可选	0	性能调优	线程池队列大小，当线程池满时，排队等待执行的队列大小，建议不要设置，当线程池满时应立即失败，重试其它服务提供机器，而不是排队，除非有特殊需求。	2.0.5以上版本
charset	charset	string	可选	UTF-8	性能调优	序列化编码	2.0.5以上版本
buffer	buffer	int	可选	8192	性能调优	网络读写缓冲区大小	2.0.5以上版本
iothreads	iothreads	int	可选	CPU + 1	性能调优	IO线程池，接收网络读写中断，以及序列化和反序列化，不处理业务，业务线程池参见threads配置，此线程池和CPU相关，不建议配置。	2.0.5以上版本
telnet	telnet	string	可选		服务治理	所支持的telnet命令，多个命令用逗号分隔	2.0.5以上版本
<dubbo:service>	contextpath	contextpath	String	可选	缺省为空串	服务治理
layer	layer	string	可选		服务治理	服务提供者所在的分层。如：biz、dao、intl:web、china:acton。	2.0.7以上版本

dubbo:reference

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

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

服务消费者引用服务配置。对应的配置类： org.apache.dubbo.config.ReferenceConfig

属性	对应URL参数	类型	是否必填	缺省值	作用	描述	兼容性
id		string	必填		配置关联	服务引用BeanId	1.0.0以上版本
interface		class	必填		服务发现	服务接口名	1.0.0以上版本
version	version	string	可选		服务发现	服务版本，与服务提供者的版本一致	1.0.0以上版本
group	group	string	可选		服务发现	服务分组，当一个接口有多个实现，可以用分组区分，必需和服务提供方一致	1.0.7以上版本
timeout	timeout	long	可选	缺省使用<dubbo:consumer>的timeout	性能调优	服务方法调用超时时间(毫秒)	1.0.5以上版本
retries	retries	int	可选	缺省使用<dubbo:consumer>的retries	性能调优	远程服务调用重试次数，不包括第一次调用，不需要重试请设为0	2.0.0以上版本
connections	connections	int	可选	缺省使用<dubbo:consumer>的connections	性能调优	对每个提供者的最大连接数，rmi、http、hessian等短连接协议表示限制连接数，dubbo等长连接协表示建立的长连接个数	2.0.0以上版本
loadbalance	loadbalance	string	可选	缺省使用<dubbo:consumer>的loadbalance	性能调优	负载均衡策略，可选值：random,roundrobin,leastactive，分别表示：随机，轮询，最少活跃调用	2.0.0以上版本
async	async	boolean	可选	缺省使用<dubbo:consumer>的async	性能调优	是否异步执行，不可靠异步，只是忽略返回值，不阻塞执行线程	2.0.0以上版本
generic	generic	boolean	可选	缺省使用<dubbo:consumer>的generic	服务治理	是否缺省泛化接口，如果为泛化接口，将返回GenericService	2.0.0以上版本
check	check	boolean	可选	缺省使用<dubbo:consumer>的check	服务治理	启动时检查提供者是否存在，true报错，false忽略	2.0.0以上版本
url	url	string	可选		服务治理	点对点直连服务提供者地址，将绕过注册中心	1.0.6以上版本
stub	stub	class/boolean	可选		服务治理	服务接口客户端本地代理类名，用于在客户端执行本地逻辑，如本地缓存等，该本地代理类的构造函数必须允许传入远程代理对象，构造函数如：public XxxServiceLocal(XxxService xxxService)	2.0.0以上版本
mock	mock	class/boolean	可选		服务治理	服务接口调用失败Mock实现类名，该Mock类必须有一个无参构造函数，与Local的区别在于，Local总是被执行，而Mock只在出现非业务异常(比如超时，网络异常等)时执行，Local在远程调用之前执行，Mock在远程调用后执行。	Dubbo1.0.13及其以上版本支持
cache	cache	string/boolean	可选		服务治理	以调用参数为key，缓存返回结果，可选：lru, threadlocal, jcache等	Dubbo2.1.0及其以上版本支持
validation	validation	boolean	可选		服务治理	是否启用JSR303标准注解验证，如果启用，将对方法参数上的注解进行校验	Dubbo2.1.0及其以上版本支持
proxy	proxy	boolean	可选	javassist	性能调优	选择动态代理实现策略，可选：javassist, jdk	2.0.2以上版本
client	client	string	可选		性能调优	客户端传输类型设置，如Dubbo协议的netty或mina。	Dubbo2.0.0以上版本支持
registry		string	可选	缺省将从所有注册中心获服务列表后合并结果	配置关联	从指定注册中心注册获取服务列表，在多个注册中心时使用，值为<dubbo:registry>的id属性，多个注册中心ID用逗号分隔	2.0.0以上版本
owner	owner	string	可选		服务治理	调用服务负责人，用于服务治理，请填写负责人公司邮箱前缀	2.0.5以上版本
actives	actives	int	可选	0	性能调优	每服务消费者每服务每方法最大并发调用数	2.0.5以上版本
cluster	cluster	string	可选	failover	性能调优	集群方式，可选：failover/failfast/failsafe/failback/forking	2.0.5以上版本
filter	reference.filter	string	可选	default	性能调优	服务消费方远程调用过程拦截器名称，多个名称用逗号分隔	2.0.5以上版本
listener	invoker.listener	string	可选	default	性能调优	服务消费方引用服务监听器名称，多个名称用逗号分隔	2.0.5以上版本
layer	layer	string	可选		服务治理	服务调用者所在的分层。如：biz、dao、intl:web、china:acton。	2.0.7以上版本
init	init	boolean	可选	false	性能调优	是否在afterPropertiesSet()时饥饿初始化引用，否则等到有人注入或引用该实例时再初始化。	2.0.10以上版本
protocol	protocol	string	可选		服务治理	只调用指定协议的服务提供方，其它协议忽略。	2.2.0以上版本

dubbo:reference

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

服务消费者引用服务配置。对应的配置类： org.apache.dubbo.config.ReferenceConfig

属性	对应URL参数	类型	是否必填	缺省值	作用	描述	兼容性
id		string	必填		配置关联	服务引用BeanId	1.0.0以上版本
interface		class	必填		服务发现	服务接口名	1.0.0以上版本
version	version	string	可选		服务发现	服务版本，与服务提供者的版本一致	1.0.0以上版本
group	group	string	可选		服务发现	服务分组，当一个接口有多个实现，可以用分组区分，必需和服务提供方一致	1.0.7以上版本
timeout	timeout	long	可选	缺省使用<dubbo:consumer>的timeout	性能调优	服务方法调用超时时间(毫秒)	1.0.5以上版本
retries	retries	int	可选	缺省使用<dubbo:consumer>的retries	性能调优	远程服务调用重试次数，不包括第一次调用，不需要重试请设为0	2.0.0以上版本
connections	connections	int	可选	缺省使用<dubbo:consumer>的connections	性能调优	对每个提供者的最大连接数，rmi、http、hessian等短连接协议表示限制连接数，dubbo等长连接协表示建立的长连接个数	2.0.0以上版本
loadbalance	loadbalance	string	可选	缺省使用<dubbo:consumer>的loadbalance	性能调优	负载均衡策略，可选值：random,roundrobin,leastactive，分别表示：随机，轮询，最少活跃调用	2.0.0以上版本
async	async	boolean	可选	缺省使用<dubbo:consumer>的async	性能调优	是否异步执行，不可靠异步，只是忽略返回值，不阻塞执行线程	2.0.0以上版本
generic	generic	boolean	可选	缺省使用<dubbo:consumer>的generic	服务治理	是否缺省泛化接口，如果为泛化接口，将返回GenericService	2.0.0以上版本
check	check	boolean	可选	缺省使用<dubbo:consumer>的check	服务治理	启动时检查提供者是否存在，true报错，false忽略	2.0.0以上版本
url	url	string	可选		服务治理	点对点直连服务提供者地址，将绕过注册中心	1.0.6以上版本
stub	stub	class/boolean	可选		服务治理	服务接口客户端本地代理类名，用于在客户端执行本地逻辑，如本地缓存等，该本地代理类的构造函数必须允许传入远程代理对象，构造函数如：public XxxServiceLocal(XxxService xxxService)	2.0.0以上版本
mock	mock	class/boolean	可选		服务治理	服务接口调用失败Mock实现类名，该Mock类必须有一个无参构造函数，与Local的区别在于，Local总是被执行，而Mock只在出现非业务异常(比如超时，网络异常等)时执行，Local在远程调用之前执行，Mock在远程调用后执行。	Dubbo1.0.13及其以上版本支持
cache	cache	string/boolean	可选		服务治理	以调用参数为key，缓存返回结果，可选：lru, threadlocal, jcache等	Dubbo2.1.0及其以上版本支持
validation	validation	boolean	可选		服务治理	是否启用JSR303标准注解验证，如果启用，将对方法参数上的注解进行校验	Dubbo2.1.0及其以上版本支持
proxy	proxy	boolean	可选	javassist	性能调优	选择动态代理实现策略，可选：javassist, jdk	2.0.2以上版本
client	client	string	可选		性能调优	客户端传输类型设置，如Dubbo协议的netty或mina。	Dubbo2.0.0以上版本支持
registry		string	可选	缺省将从所有注册中心获服务列表后合并结果	配置关联	从指定注册中心注册获取服务列表，在多个注册中心时使用，值为<dubbo:registry>的id属性，多个注册中心ID用逗号分隔	2.0.0以上版本
owner	owner	string	可选		服务治理	调用服务负责人，用于服务治理，请填写负责人公司邮箱前缀	2.0.5以上版本
actives	actives	int	可选	0	性能调优	每服务消费者每服务每方法最大并发调用数	2.0.5以上版本
cluster	cluster	string	可选	failover	性能调优	集群方式，可选：failover/failfast/failsafe/failback/forking	2.0.5以上版本
filter	reference.filter	string	可选	default	性能调优	服务消费方远程调用过程拦截器名称，多个名称用逗号分隔	2.0.5以上版本
listener	invoker.listener	string	可选	default	性能调优	服务消费方引用服务监听器名称，多个名称用逗号分隔	2.0.5以上版本
layer	layer	string	可选		服务治理	服务调用者所在的分层。如：biz、dao、intl:web、china:acton。	2.0.7以上版本
init	init	boolean	可选	false	性能调优	是否在afterPropertiesSet()时饥饿初始化引用，否则等到有人注入或引用该实例时再初始化。	2.0.10以上版本
protocol	protocol	string	可选		服务治理	只调用指定协议的服务提供方，其它协议忽略。	2.2.0以上版本

dubbo:registry

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

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

注册中心配置。对应的配置类： org.apache.dubbo.config.RegistryConfig。同时如果有多个不同的注册中心，可以声明多个 <dubbo:registry> 标签，并在 <dubbo:service> 或 <dubbo:reference> 的 registry 属性指定使用的注册中心。

属性	对应URL参数	类型	是否必填	缺省值	作用	描述	兼容性
id		string	可选		配置关联	注册中心引用BeanId，可以在<dubbo:service registry="">或<dubbo:reference registry="">中引用此ID	1.0.16以上版本
address	<host:port>	string	必填		服务发现	注册中心服务器地址，如果地址没有端口缺省为9090，同一集群内的多个地址用逗号分隔，如：ip:port,ip:port，不同集群的注册中心，请配置多个<dubbo:registry>标签	1.0.16以上版本
protocol	<protocol>	string	可选	dubbo	服务发现	注册中心地址协议，支持`dubbo`, `multicast`, `zookeeper`, `redis`, `consul(2.7.1)`, `sofa(2.7.2)`, `etcd(2.7.2)`, `nacos(2.7.2)`等协议	2.0.0以上版本
port	<port>	int	可选	9090	服务发现	注册中心缺省端口，当address没有带端口时使用此端口做为缺省值	2.0.0以上版本
username	<username>	string	可选		服务治理	登录注册中心用户名，如果注册中心不需要验证可不填	2.0.0以上版本
password	<password>	string	可选		服务治理	登录注册中心密码，如果注册中心不需要验证可不填	2.0.0以上版本
transport	registry.transporter	string	可选	netty	性能调优	网络传输方式，可选mina,netty	2.0.0以上版本
timeout	registry.timeout	int	可选	5000	性能调优	注册中心请求超时时间(毫秒)	2.0.0以上版本
session	registry.session	int	可选	60000	性能调优	注册中心会话超时时间(毫秒)，用于检测提供者非正常断线后的脏数据，比如用心跳检测的实现，此时间就是心跳间隔，不同注册中心实现不一样。	2.1.0以上版本
file	registry.file	string	可选		服务治理	使用文件缓存注册中心地址列表及服务提供者列表，应用重启时将基于此文件恢复，注意：两个注册中心不能使用同一文件存储	2.0.0以上版本
wait	registry.wait	int	可选	0	性能调优	停止时等待通知完成时间(毫秒)	2.0.0以上版本
check	check	boolean	可选	true	服务治理	注册中心不存在时，是否报错	2.0.0以上版本
register	register	boolean	可选	true	服务治理	是否向此注册中心注册服务，如果设为false，将只订阅，不注册	2.0.5以上版本
subscribe	subscribe	boolean	可选	true	服务治理	是否向此注册中心订阅服务，如果设为false，将只注册，不订阅	2.0.5以上版本
dynamic	dynamic	boolean	可选	true	服务治理	服务是否动态注册，如果设为false，注册后将显示为disable状态，需人工启用，并且服务提供者停止时，也不会自动取消注册，需人工禁用。	2.0.5以上版本
group	group	string	可选	dubbo	服务治理	服务注册分组，跨组的服务不会相互影响，也无法相互调用，适用于环境隔离。	2.0.5以上版本
simplified	simplified	boolean	可选	false	服务治理	注册到注册中心的URL是否采用精简模式的（与低版本兼容）	2.7.0以上版本
extra-keys	extraKeys	string	可选		服务治理	在simplified=true时，extraKeys允许你在默认参数外将额外的key放到URL中，格式：“interface,key1,key2”。	2.7.0以上版本

dubbo:registry

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

属性	对应URL参数	类型	是否必填	缺省值	作用	描述	兼容性
id		string	可选		配置关联	注册中心引用BeanId，可以在<dubbo:service registry="">或<dubbo:reference registry="">中引用此ID	1.0.16以上版本
address	<host:port>	string	必填		服务发现	注册中心服务器地址，如果地址没有端口缺省为9090，同一集群内的多个地址用逗号分隔，如：ip:port,ip:port，不同集群的注册中心，请配置多个<dubbo:registry>标签	1.0.16以上版本
protocol	<protocol>	string	可选	dubbo	服务发现	注册中心地址协议，支持`dubbo`, `multicast`, `zookeeper`, `redis`, `consul(2.7.1)`, `sofa(2.7.2)`, `etcd(2.7.2)`, `nacos(2.7.2)`等协议	2.0.0以上版本
port	<port>	int	可选	9090	服务发现	注册中心缺省端口，当address没有带端口时使用此端口做为缺省值	2.0.0以上版本
username	<username>	string	可选		服务治理	登录注册中心用户名，如果注册中心不需要验证可不填	2.0.0以上版本
password	<password>	string	可选		服务治理	登录注册中心密码，如果注册中心不需要验证可不填	2.0.0以上版本
transport	registry.transporter	string	可选	netty	性能调优	网络传输方式，可选mina,netty	2.0.0以上版本
timeout	registry.timeout	int	可选	5000	性能调优	注册中心请求超时时间(毫秒)	2.0.0以上版本
session	registry.session	int	可选	60000	性能调优	注册中心会话超时时间(毫秒)，用于检测提供者非正常断线后的脏数据，比如用心跳检测的实现，此时间就是心跳间隔，不同注册中心实现不一样。	2.1.0以上版本
file	registry.file	string	可选		服务治理	使用文件缓存注册中心地址列表及服务提供者列表，应用重启时将基于此文件恢复，注意：两个注册中心不能使用同一文件存储	2.0.0以上版本
wait	registry.wait	int	可选	0	性能调优	停止时等待通知完成时间(毫秒)	2.0.0以上版本
check	check	boolean	可选	true	服务治理	注册中心不存在时，是否报错	2.0.0以上版本
register	register	boolean	可选	true	服务治理	是否向此注册中心注册服务，如果设为false，将只订阅，不注册	2.0.5以上版本
subscribe	subscribe	boolean	可选	true	服务治理	是否向此注册中心订阅服务，如果设为false，将只注册，不订阅	2.0.5以上版本
dynamic	dynamic	boolean	可选	true	服务治理	服务是否动态注册，如果设为false，注册后将显示为disable状态，需人工启用，并且服务提供者停止时，也不会自动取消注册，需人工禁用。	2.0.5以上版本
group	group	string	可选	dubbo	服务治理	服务注册分组，跨组的服务不会相互影响，也无法相互调用，适用于环境隔离。	2.0.5以上版本
simplified	simplified	boolean	可选	false	服务治理	注册到注册中心的URL是否采用精简模式的（与低版本兼容）	2.7.0以上版本
extra-keys	extraKeys	string	可选		服务治理	在simplified=true时，extraKeys允许你在默认参数外将额外的key放到URL中，格式：“interface,key1,key2”。	2.7.0以上版本

dubbo:service

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

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

服务提供者暴露服务配置。对应的配置类：org.apache.dubbo.config.ServiceConfig

属性	对应URL参数	类型	是否必填	缺省值	作用	描述	兼容性
interface		class	必填		服务发现	服务接口名	1.0.0以上版本
ref		object	必填		服务发现	服务对象实现引用	1.0.0以上版本
version	version	string	可选	0.0.0	服务发现	服务版本，建议使用两位数字版本，如：1.0，通常在接口不兼容时版本号才需要升级	1.0.0以上版本
group	group	string	可选		服务发现	服务分组，当一个接口有多个实现，可以用分组区分	1.0.7以上版本
path	<path>	string	可选	缺省为接口名	服务发现	服务路径 (注意：1.0不支持自定义路径，总是使用接口名，如果有1.0调2.0，配置服务路径可能不兼容)	1.0.12以上版本
delay	delay	int	可选	0	性能调优	延迟注册服务时间(毫秒) ，设为-1时，表示延迟到Spring容器初始化完成时暴露服务	1.0.14以上版本
timeout	timeout	int	可选	1000	性能调优	远程服务调用超时时间(毫秒)	2.0.0以上版本
retries	retries	int	可选	2	性能调优	远程服务调用重试次数，不包括第一次调用，不需要重试请设为0	2.0.0以上版本
connections	connections	int	可选	100	性能调优	对每个提供者的最大连接数，rmi、http、hessian等短连接协议表示限制连接数，dubbo等长连接协表示建立的长连接个数	2.0.0以上版本
loadbalance	loadbalance	string	可选	random	性能调优	负载均衡策略，可选值：random,roundrobin,leastactive，分别表示：随机，轮询，最少活跃调用	2.0.0以上版本
async	async	boolean	可选	false	性能调优	是否缺省异步执行，不可靠异步，只是忽略返回值，不阻塞执行线程	2.0.0以上版本
local	local	class/boolean	可选	false	服务治理	设为true，表示使用缺省代理类名，即：接口名 + Local后缀，已废弃，请使用stub	2.0.0以上版本
stub	stub	class/boolean	可选	false	服务治理	设为true，表示使用缺省代理类名，即：接口名 + Stub后缀，服务接口客户端本地代理类名，用于在客户端执行本地逻辑，如本地缓存等，该本地代理类的构造函数必须允许传入远程代理对象，构造函数如：public XxxServiceStub(XxxService xxxService)	2.0.0以上版本
mock	mock	class/boolean	可选	false	服务治理	设为true，表示使用缺省Mock类名，即：接口名 + Mock后缀，服务接口调用失败Mock实现类，该Mock类必须有一个无参构造函数，与Local的区别在于，Local总是被执行，而Mock只在出现非业务异常(比如超时，网络异常等)时执行，Local在远程调用之前执行，Mock在远程调用后执行。	2.0.0以上版本
token	token	string/boolean	可选	false	服务治理	令牌验证，为空表示不开启，如果为true，表示随机生成动态令牌，否则使用静态令牌，令牌的作用是防止消费者绕过注册中心直接访问，保证注册中心的授权功能有效，如果使用点对点调用，需关闭令牌功能	2.0.0以上版本
registry		string	可选	缺省向所有registry注册	配置关联	向指定注册中心注册，在多个注册中心时使用，值为<dubbo:registry>的id属性，多个注册中心ID用逗号分隔，如果不想将该服务注册到任何registry，可将值设为N/A	2.0.0以上版本
provider		string	可选	缺省使用第一个provider配置	配置关联	指定provider，值为<dubbo:provider>的id属性	2.0.0以上版本
deprecated	deprecated	boolean	可选	false	服务治理	服务是否过时，如果设为true，消费方引用时将打印服务过时警告error日志	2.0.5以上版本
dynamic	dynamic	boolean	可选	true	服务治理	服务是否动态注册，如果设为false，注册后将显示后disable状态，需人工启用，并且服务提供者停止时，也不会自动取消册，需人工禁用。	2.0.5以上版本
accesslog	accesslog	string/boolean	可选	false	服务治理	设为true，将向logger中输出访问日志，也可填写访问日志文件路径，直接把访问日志输出到指定文件	2.0.5以上版本
owner	owner	string	可选		服务治理	服务负责人，用于服务治理，请填写负责人公司邮箱前缀	2.0.5以上版本
document	document	string	可选		服务治理	服务文档URL	2.0.5以上版本
weight	weight	int	可选		性能调优	服务权重	2.0.5以上版本
executes	executes	int	可选	0	性能调优	服务提供者每服务每方法最大可并行执行请求数	2.0.5以上版本
proxy	proxy	string	可选	javassist	性能调优	生成动态代理方式，可选：jdk/javassist	2.0.5以上版本
cluster	cluster	string	可选	failover	性能调优	集群方式，可选：failover/failfast/failsafe/failback/forking	2.0.5以上版本
filter	service.filter	string	可选	default	性能调优	服务提供方远程调用过程拦截器名称，多个名称用逗号分隔	2.0.5以上版本
listener	exporter.listener	string	可选	default	性能调优	服务提供方导出服务监听器名称，多个名称用逗号分隔
protocol		string	可选		配置关联	使用指定的协议暴露服务，在多协议时使用，值为<dubbo:protocol>的id属性，多个协议ID用逗号分隔	2.0.5以上版本
layer	layer	string	可选		服务治理	服务提供者所在的分层。如：biz、dao、intl:web、china:acton。	2.0.7以上版本
register	register	boolean	可选	true	服务治理	该协议的服务是否注册到注册中心	2.0.8以上版本

dubbo:service

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

服务提供者暴露服务配置。对应的配置类：org.apache.dubbo.config.ServiceConfig

属性	对应URL参数	类型	是否必填	缺省值	作用	描述	兼容性
interface		class	必填		服务发现	服务接口名	1.0.0以上版本
ref		object	必填		服务发现	服务对象实现引用	1.0.0以上版本
version	version	string	可选	0.0.0	服务发现	服务版本，建议使用两位数字版本，如：1.0，通常在接口不兼容时版本号才需要升级	1.0.0以上版本
group	group	string	可选		服务发现	服务分组，当一个接口有多个实现，可以用分组区分	1.0.7以上版本
path	<path>	string	可选	缺省为接口名	服务发现	服务路径 (注意：1.0不支持自定义路径，总是使用接口名，如果有1.0调2.0，配置服务路径可能不兼容)	1.0.12以上版本
delay	delay	int	可选	0	性能调优	延迟注册服务时间(毫秒) ，设为-1时，表示延迟到Spring容器初始化完成时暴露服务	1.0.14以上版本
timeout	timeout	int	可选	1000	性能调优	远程服务调用超时时间(毫秒)	2.0.0以上版本
retries	retries	int	可选	2	性能调优	远程服务调用重试次数，不包括第一次调用，不需要重试请设为0	2.0.0以上版本
connections	connections	int	可选	100	性能调优	对每个提供者的最大连接数，rmi、http、hessian等短连接协议表示限制连接数，dubbo等长连接协表示建立的长连接个数	2.0.0以上版本
loadbalance	loadbalance	string	可选	random	性能调优	负载均衡策略，可选值：random,roundrobin,leastactive，分别表示：随机，轮询，最少活跃调用	2.0.0以上版本
async	async	boolean	可选	false	性能调优	是否缺省异步执行，不可靠异步，只是忽略返回值，不阻塞执行线程	2.0.0以上版本
local	local	class/boolean	可选	false	服务治理	设为true，表示使用缺省代理类名，即：接口名 + Local后缀，已废弃，请使用stub	2.0.0以上版本
stub	stub	class/boolean	可选	false	服务治理	设为true，表示使用缺省代理类名，即：接口名 + Stub后缀，服务接口客户端本地代理类名，用于在客户端执行本地逻辑，如本地缓存等，该本地代理类的构造函数必须允许传入远程代理对象，构造函数如：public XxxServiceStub(XxxService xxxService)	2.0.0以上版本
mock	mock	class/boolean	可选	false	服务治理	设为true，表示使用缺省Mock类名，即：接口名 + Mock后缀，服务接口调用失败Mock实现类，该Mock类必须有一个无参构造函数，与Local的区别在于，Local总是被执行，而Mock只在出现非业务异常(比如超时，网络异常等)时执行，Local在远程调用之前执行，Mock在远程调用后执行。	2.0.0以上版本
token	token	string/boolean	可选	false	服务治理	令牌验证，为空表示不开启，如果为true，表示随机生成动态令牌，否则使用静态令牌，令牌的作用是防止消费者绕过注册中心直接访问，保证注册中心的授权功能有效，如果使用点对点调用，需关闭令牌功能	2.0.0以上版本
registry		string	可选	缺省向所有registry注册	配置关联	向指定注册中心注册，在多个注册中心时使用，值为<dubbo:registry>的id属性，多个注册中心ID用逗号分隔，如果不想将该服务注册到任何registry，可将值设为N/A	2.0.0以上版本
provider		string	可选	缺省使用第一个provider配置	配置关联	指定provider，值为<dubbo:provider>的id属性	2.0.0以上版本
deprecated	deprecated	boolean	可选	false	服务治理	服务是否过时，如果设为true，消费方引用时将打印服务过时警告error日志	2.0.5以上版本
dynamic	dynamic	boolean	可选	true	服务治理	服务是否动态注册，如果设为false，注册后将显示后disable状态，需人工启用，并且服务提供者停止时，也不会自动取消册，需人工禁用。	2.0.5以上版本
accesslog	accesslog	string/boolean	可选	false	服务治理	设为true，将向logger中输出访问日志，也可填写访问日志文件路径，直接把访问日志输出到指定文件	2.0.5以上版本
owner	owner	string	可选		服务治理	服务负责人，用于服务治理，请填写负责人公司邮箱前缀	2.0.5以上版本
document	document	string	可选		服务治理	服务文档URL	2.0.5以上版本
weight	weight	int	可选		性能调优	服务权重	2.0.5以上版本
executes	executes	int	可选	0	性能调优	服务提供者每服务每方法最大可并行执行请求数	2.0.5以上版本
proxy	proxy	string	可选	javassist	性能调优	生成动态代理方式，可选：jdk/javassist	2.0.5以上版本
cluster	cluster	string	可选	failover	性能调优	集群方式，可选：failover/failfast/failsafe/failback/forking	2.0.5以上版本
filter	service.filter	string	可选	default	性能调优	服务提供方远程调用过程拦截器名称，多个名称用逗号分隔	2.0.5以上版本
listener	exporter.listener	string	可选	default	性能调优	服务提供方导出服务监听器名称，多个名称用逗号分隔
protocol		string	可选		配置关联	使用指定的协议暴露服务，在多协议时使用，值为<dubbo:protocol>的id属性，多个协议ID用逗号分隔	2.0.5以上版本
layer	layer	string	可选		服务治理	服务提供者所在的分层。如：biz、dao、intl:web、china:acton。	2.0.7以上版本
register	register	boolean	可选	true	服务治理	该协议的服务是否注册到注册中心	2.0.8以上版本

filter概述

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

Filter

Filter 提供请求处理抽象。用户可以将多个过滤器组合成过滤器链。当从监听器接收到请求时，过滤器将在其预处理或后处理阶段逐一处理它。因为 pixiu 想要提供网络协议转换功能，所以过滤器包含网络过滤器以及网络过滤器之下的过滤器，例如 http 过滤器。请求处理顺序如下。

client -> listner -> network filter such as httpconnectionmanager -> http filter chain

您可以在 pkg/filter 中找到所有过滤器。以下仅列出一些过滤器。

ratelimit 该过滤器使用 sentinel-go 提供速率限制功能；
timeout 该过滤器提供超时功能；
tracing 该过滤器使用 jaeger 提供追踪功能；
grpcproxy 该过滤器提供 http 到 grpc 代理功能；
httpproxy 该过滤器提供 http 到 http 代理功能；
proxywrite 该过滤器提供 http 请求路径或头部修改功能；
apiconfig 该过滤器提供 http 到 dubbo 转换映射功能，并与 remote 过滤器配合使用；
remote 该过滤器提供 http 到 dubbo 代理功能，并与 apiconfig 过滤器配合使用。

How to define custom http filter

step one

有两个抽象接口：plugin 和 filter。

HTTP

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

本示例演示了如何使用 Pixiu Gateway 作为 HTTP 代理网关，接收外部的 HTTP 请求并转发到后端的 Dubbo-go RPC 服务。示例基于 dubbo-go-samples/helloworld 中的 RPC 服务。

先决条件

已安装 Pixiu Gateway

创建 RPC 服务

创建服务

首先创建 helloworld 服务：

kubectl apply -f https://raw.githubusercontent.com/apache/dubbo-go-pixiu-samples/main/gateway/helloworld/deployment.yaml

验证服务

检查服务是否正常运行：

kubectl get pods -n helloworld
kubectl get svc -n helloworld

创建 HTTP 代理

kubectl apply -f https://raw.githubusercontent.com/apache/dubbo-go-pixiu-samples/main/gateway/http/http.yaml

验证 HTTP 代理

检查所有资源的状态：

kubectl get httproute -n default
kubectl get pixiuclusterpolicy -n default
kubectl get pixiufilterpolicy -n default
kubectl get gateway -n default

验证

获取网关地址

NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
pixiu-3465d618 LoadBalancer 10.108.197.9 <pending> 80:32547/TCP 86m
pixiu-gateway ClusterIP 10.105.156.54 <none> 8080/TCP,8081/TCP 86m

发送 HTTP 请求

使用 curl 发送 HTTP 请求到 RPC 服务：

使用 Java 接口方式开发 triple 通信服务

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

不同于谷歌官方 gRPC 实现，Dubbo 实现的 triple 协议易用性更好（不绑定 Protobuf），你可以继续使用 Java 接口 直接定义服务。对于期望平滑升级、没有多语言业务或者不熟悉 Protobuf 的用户而言，Java 接口方式是最简单的使用 triple 的方式。

以下是一个使用Java 接口开发 Dubbo 服务的基本示例，示例使用 triple 协议通信，可在此查看本示例的完整代码。

注意

本文使用的示例是基于原生 API 编码的，这里还有一个 Spring Boot 版本的示例供参考，同样是 Java接口+triple 的模式，此示例还额外加入了服务发现配置。

运行示例

首先，可通过以下命令下载示例源码

git clone --depth=1 https://github.com/apache/dubbo-samples.git

进入示例源码目录：

cd dubbo-samples/1-basic/dubbo-samples-api

启动Server

运行以下命令启动 server

mvn -Dexec.mainClass=org.apache.dubbo.samples.provider.Application exec:java

启动Client

有两种方式可以调用 server 发布的服务

使用标准的 http 工具，如 cURL
使用 Dubbo SDK 开发一个 client

cURL

curl \
 --header "Content-Type: application/json" \
 --data '["Dubbo"]' \
 http://localhost:50052/org.apache.dubbo.samples.api.GreetingsService/sayHi/

SDK Client

mvn -Dexec.mainClass=org.apache.dubbo.samples.client.Application exec:java

源码讲解

如果您是 Dubbo 老用户，你会发现以下内容与之前 Dubbo2 的开发模式基本一样，只是协议名称从 dubbo 换成了 tri。

Metrics

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

概述

Dubbo Metrics 的总体设计请参考可观测性 Metrics Proposal。

以下是 Dubbo Java 相关的具体实现与使用方式讲解。

使用方式

要为 Dubbo 进程开启指标采集，需要在项目中引入相关依赖并增加配置。以 Spring Boot 项目为例，增加以下 spring-boot-starter 依赖到项目中，即会自动开启指标采集。

<!-- https://mvnrepository.com/artifact/org.apache.dubbo/dubbo-metrics-prometheus -->
<dependency>
 <groupId>org.apache.dubbo</groupId>
 <artifactId>dubbo-spring-boot-observability-starter</artifactId>
 <version>3.2.0</version>
</dependency>

完整示例请参见 dubbo-samples-metrics-spring-boot
完整配置参数请参见 Metrics 配置项手册

实现原理解析

代码结构与工作流程

移除原来与 Metrics 相关的类
创建新模块 dubbo-metrics/dubbo-metrics-api、dubbo-metrics/dubbo-metrics-prometheus，MetricsConfig 作为该模块的配置类
使用micrometer，在Collector中使用基本类型代表指标，如Long、Double等，并在dubbo-metrics-api中引入micrometer，由micrometer对内部指标进行转换

以下是 Dubbo 实现中的关键组件及数据流转过程

指标上报接口

根据上图架构，指标接口是 Dubbo 对外暴露指标数据的出口，以下是指标接口的具体定义：

另外，该 Service 还作为一些智能自适应流量调度算法的数据来源

public interface MetricsService {

 /**
 * Default {@link MetricsService} extension name.
 */
 String DEFAULT_EXTENSION_NAME = "default";

 /**
 * The contract version of {@link MetricsService}, the future update must make sure compatible.
 */
 String VERSION = "1.0.0";

 /**
 * Get metrics by prefixes
 *
 * @param categories categories
 * @return metrics - key=MetricCategory value=MetricsEntityList
 */
 Map<MetricsCategory, List<MetricsEntity>> getMetricsByCategories(List<MetricsCategory> categories);

 /**
 * Get metrics by interface and prefixes
 *
 * @param serviceUniqueName serviceUniqueName (eg.group/interfaceName:version)
 * @param categories categories
 * @return metrics - key=MetricCategory value=MetricsEntityList
 */
 Map<MetricsCategory, List<MetricsEntity>> getMetricsByCategories(String serviceUniqueName, List<MetricsCategory> categories);

 /**
 * Get metrics by interface、method and prefixes
 *
 * @param serviceUniqueName serviceUniqueName (eg.group/interfaceName:version)
 * @param methodName methodName
 * @param parameterTypes method parameter types
 * @param categories categories
 * @return metrics - key=MetricCategory value=MetricsEntityList
 */
 Map<MetricsCategory, List<MetricsEntity>> getMetricsByCategories(String serviceUniqueName, String methodName, Class<?>[] parameterTypes, List<MetricsCategory> categories);
}

其中 MetricsCategory 设计如下:

Nacos 注册中心

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

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

Nacos 是 Dubbo 生态系统中重要的注册中心实现，其中 dubbo-registry-nacos 则是 Dubbo 融合 Nacos 注册中心的实现。

预备工作

当您将 dubbo-registry-nacos 整合到您的 Dubbo 工程之前，请确保后台已经启动 Nacos 服务。如果您尚且不熟悉 Nacos 的基本使用的话，可先行参考 Nacos 快速入门。建议使用 Nacos 1.0.0 及以上的版本。

快速上手

Dubbo 融合 Nacos 成为注册中心的操作步骤非常简单，大致步骤可分为“增加 Maven 依赖”以及“配置注册中心“。

增加 Maven 依赖

首先，您需要将 dubbo-registry-nacos 的 Maven 依赖添加到您的项目 pom.xml 文件中，并且强烈地推荐您使用 Dubbo 2.6.5：

<dependencies>

 ...
 
 <!-- Dubbo Nacos registry dependency -->
 <dependency>
 <groupId>com.alibaba</groupId>
 <artifactId>dubbo-registry-nacos</artifactId>
 <version>0.0.2</version>
 </dependency> 
 
 <!-- Keep latest Nacos client version -->
 <dependency>
 <groupId>com.alibaba.nacos</groupId>
 <artifactId>nacos-client</artifactId>
 <version>[0.6.1,)</version>
 </dependency>
 
 <!-- Dubbo dependency -->
 <dependency>
 <groupId>com.alibaba</groupId>
 <artifactId>dubbo</artifactId>
 <version>2.6.5</version>
 </dependency>
 
 <!-- Alibaba Spring Context extension -->
 <dependency>
 <groupId>com.alibaba.spring</groupId>
 <artifactId>spring-context-support</artifactId>
 <version>1.0.2</version>
 </dependency>

 ...
 
</dependencies>

当项目中添加 dubbo-registry-nacos 后，您无需显式地编程实现服务发现和注册逻辑，实际实现由该三方包提供，接下来配置 Naocs 注册中心。

Nacos 注册中心

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

Nacos 是 Dubbo 生态系统中重要的注册中心实现，其中 dubbo-registry-nacos 则是 Dubbo 融合 Nacos 注册中心的实现。

预备工作

快速上手

Dubbo 融合 Nacos 成为注册中心的操作步骤非常简单，大致步骤可分为“增加 Maven 依赖”以及“配置注册中心“。

增加 Maven 依赖

首先，您需要将 dubbo-registry-nacos 的 Maven 依赖添加到您的项目 pom.xml 文件中，并且强烈地推荐您使用 Dubbo 2.6.5：

<dependencies>

 ...
 
 <!-- Dubbo Nacos registry dependency -->
 <dependency>
 <groupId>com.alibaba</groupId>
 <artifactId>dubbo-registry-nacos</artifactId>
 <version>0.0.2</version>
 </dependency> 
 
 <!-- Keep latest Nacos client version -->
 <dependency>
 <groupId>com.alibaba.nacos</groupId>
 <artifactId>nacos-client</artifactId>
 <version>0.6.1</version>
 </dependency>
 
 <!-- Dubbo dependency -->
 <dependency>
 <groupId>com.alibaba</groupId>
 <artifactId>dubbo</artifactId>
 <version>2.6.5</version>
 </dependency>
 
 <!-- Alibaba Spring Context extension -->
 <dependency>
 <groupId>com.alibaba.spring</groupId>
 <artifactId>spring-context-support</artifactId>
 <version>1.0.2</version>
 </dependency>

 ...
 
</dependencies>

当项目中添加 dubbo-registry-nacos 后，您无需显式地编程实现服务发现和注册逻辑，实际实现由该三方包提供，接下来配置 Naocs 注册中心。

使用 GraalVM 打包 Native Image

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

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

dubbo3.0支持native-image文档

概述

本文档将介绍将dubbo3.0项目接入GraalVM，进行native-image编译为二进制的流程。

关于GraalVm的更多信息可以阅读 https://www.graalvm.org/docs/getting-started/container-images/ 此文档。

使用样例

在编译我们的dubbo项目之前，需要确保我们正基于graalVm的环境。

安装GraalVM

进入https://www.graalvm.org/ 官网根据自己的系统选取最新版本安装：

安装完成后，修改配置JAVA_HOME的路径，生效后查看本地jdk可以看到如下：

这里我们使用的基于jdk1.8版本的GraalVM。

安装native-image，只需执行gu install native-image即可。

拉取dubbo代码，切换到apache:3.0分支。
手动执行生成SPI代码。

由于目前编译native-image不支持代码动态生成编译，所以有关代码动态生成的部分需要我们手动先生成，这里提供了工具函数：

执行CodeGenerator即可在dubbo-native模块下生成SPI代码。

MacdeMacBook-pro-3:incubator-dubbo mac$ pwd

/Users/mac/Documents/Mi/project/incubator-dubbo

MacdeMacBook-pro-3:incubator-dubbo mac$ mvn clean package install -Dmaven.test.skip=true

编译demo项目

这里我们提供了可直接进行编译的示例项目，dubbo-demo/dubbo-demo-native。上面步骤install完成后，先到dubbo-demo-native的provider下，执行native-image编译：

 mvn clean package -P native -Dmaven.test.skip=true

这里由于我们在maven中引入了native-image插件，所以直接-P native即可执行该插件。

编译成功后可以在target下看到已经生成的二进制文件，本地启动一个zookeeper，直接执行该二进制，可见启动成功如下：

consumer端同样执行编译，在consumer的target下也会生成二进制文件：demo-native-consumer,执行该二进制可以看到调用结果如下：

具体步骤

实际上在这个demo下我们做了一些工作来确保项目可以编译执行，主要有以下几个步骤

引入dubbo-native依赖

<dependency>

 <groupId>org.apache.dubbo</groupId>

 <artifactId>dubbo-native</artifactId>

 <version>${project.version}</version>

</dependency>

该模块下有我们生成的SPI代码。

引入native-image插件

<plugin>

 <groupId>org.graalvm.nativeimage</groupId>

 <artifactId>native-image-maven-plugin</artifactId>

 <version>21.0.0.2</version>

 <executions>

 <execution>

 <goals>

 <goal>native-image</goal>

 </goals>

 <phase>package</phase>

 </execution>

 </executions>

 <configuration>

 <skip>false</skip>

 <imageName>demo-native-provider</imageName>

 <mainClass>org.apache.dubbo.demo.graalvm.provider.Application</mainClass>

 <buildArgs>

 --no-fallback

 --initialize-at-build-time=org.slf4j.MDC

 --initialize-at-build-time=org.slf4j.LoggerFactory

 --initialize-at-build-time=org.slf4j.impl.StaticLoggerBinder

 --initialize-at-build-time=org.apache.log4j.helpers.Loader

 --initialize-at-build-time=org.apache.log4j.Logger

 --initialize-at-build-time=org.apache.log4j.helpers.LogLog

 --initialize-at-build-time=org.apache.log4j.LogManager

 --initialize-at-build-time=org.apache.log4j.spi.LoggingEvent

 --initialize-at-build-time=org.slf4j.impl.Log4jLoggerFactory

 --initialize-at-build-time=org.slf4j.impl.Log4jLoggerAdapter

 --initialize-at-build-time=org.eclipse.collections.api.factory.Sets

 --initialize-at-run-time=io.netty.channel.epoll.Epoll

 --initialize-at-run-time=io.netty.channel.epoll.Native

 --initialize-at-run-time=io.netty.channel.epoll.EpollEventLoop

 --initialize-at-run-time=io.netty.channel.epoll.EpollEventArray

 --initialize-at-run-time=io.netty.channel.DefaultFileRegion

 --initialize-at-run-time=io.netty.channel.kqueue.KQueueEventArray

 --initialize-at-run-time=io.netty.channel.kqueue.KQueueEventLoop

 --initialize-at-run-time=io.netty.channel.kqueue.Native

 --initialize-at-run-time=io.netty.channel.unix.Errors

 --initialize-at-run-time=io.netty.channel.unix.IovArray

 --initialize-at-run-time=io.netty.channel.unix.Limits

 --initialize-at-run-time=io.netty.util.internal.logging.Log4JLogger

 --initialize-at-run-time=io.netty.channel.unix.Socket

 --initialize-at-run-time=io.netty.channel.ChannelHandlerMask



 --report-unsupported-elements-at-runtime

 --allow-incomplete-classpath

 --enable-url-protocols=http

 -H:+ReportExceptionStackTraces

 </buildArgs>

 </configuration>

</plugin>

其中定义了生成的镜像名以及一些构建镜像的参数。

Pixiu Filter体系介绍

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

怎样编写一个Filter

更详细的信息，请移步Blog《谈谈Pixiu的Filter》

我们来尝试写一个简单的Filter，这个Filter将会有简单的配置，在Decode阶段把请求的Body Log出来，并翻转后作为Mock的返回值。最后在Encode阶段根据配置把返回值Log出来。

1.首先创建一个Filter

type DemoFilter struct {
 logPrefix string
}

// Decode阶段，发生在调用Upstream之前
func (f *DemoFilter) Decode(ctx *contexthttp.HttpContext) filter.FilterStatus {
 body, _ := ioutil.ReadAll(ctx.Request.Body)
 logger.Infof("request body: %s", body)

 //reverse res str
 runes := []rune(string(body))
 for i := 0; i < len(runes)/2; i += 1 {
 runes[i], runes[len(runes)-1-i] = runes[len(runes)-1-i], runes[i]
 }
 reverse := string(runes)

 //mock response
 ctx.SendLocalReply(200, []byte(reverse))
 return filter.Stop
}

// Encode阶段，此时可以获取到Upstream的Response
func (f *DemoFilter) Encode(ctx *contexthttp.HttpContext) filter.FilterStatus {
 res := ctx.SourceResp.(string)
 logger.Infof("%s: %s", f.logPrefix, res)
 return filter.Continue
}

2.创建Filter Factory

PixiuClusterPolicy

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

概述

PixiuClusterPolicy 是一个自定义资源扩展，用于为 Pixiu Gateway 中的后端服务配置集群级别的策略。

用例

定义用于动态服务发现的注册中心配置（例如，Zookeeper、Nacos）
在不使用服务发现时定义静态端点配置
为后端服务配置负载均衡策略
设置健康检查机制以确保后端服务的可用性
在集群级别配置连接和请求超时

Pixiu Gateway 中的 PixiuClusterPolicy

使用注册中心（例如：Zookeeper、Nacos）配置服务发现

apiVersion: pixiu.apache.org/v1alpha1
kind: PixiuClusterPolicy
metadata:
 name: service-registry-policy
 namespace: default
spec:
 serviceRef:
 - name: dubbo-backend
 type: dynamic
 registries:
 zookeeper:
 protocol: zookeeper
 address: zookeeper:2181
 timeout: 3s
 nacos:
 protocol: nacos
 address: nacos:8848
 namespace: public
 group: DEFAULT_GROUP

在服务发现不可用时定义静态端点

apiVersion: pixiu.apache.org/v1alpha1
kind: PixiuClusterPolicy
metadata:
 name: static-endpoints-policy
 namespace: default
spec:
 serviceRef:
 - name: static-backend
 type: static
 endpoints:
 - address: 10.0.0.1
 port: 8080
 protocolType: http
 - address: 10.0.0.2
 port: 8080
 protocolType: http

为服务设置负载均衡策略

Prometheus

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

安装

你可以使用 Dubbo 社区提供的示例配置快速安装 Prometheus。

kubectl create -f https://raw.githubusercontent.com/apache/dubbo-kubernetes/master/deploy/kubernetes/prometheus.yaml

本安装仅适用于测试或体验使用，生产级别的安装请参考 Prometheus 官方安装文档。

执行端口映射 kubectl -n dubbo-system port-forward svc/prometheus-server 9090:9090，访问页面 http://localhost:9090，切换到 graph 视图。

Scrape 配置

Dubbo 的每个实例都会暴露一个 http 端口用于 Metrics 采集，Prometheus 通过 scraping 每个实例的 http 接口来采集统计数据。具体的 scraping 路径可以通过 Prometheus 配置文件进行调整，该文件控制 scraping 实例的端口、路径、TLS 设置等。

Kubernetes 注解约定

在 Kubernetes 部署模式下，使用官方社区维护的 Helm Charts 安装 Prometheus，Prometheus 服务可以自动识别包含 prometheus.io 注解的 Dubbo Pod 实例，并将它们列入 Scraping 实例列表。

Dubbo 官网给出的示例即是基于 prometheus.io 注解实现了 scraping target 地址的自动发现，具体注解配置可参见示例中的 Deployment 资源定义。

annotations:
 prometheus.io/scrape: "true"
 prometheus.io/path: /management/prometheus
 prometheus.io/port: "22222"

在此模式下，Dubbo 实例默认提供的 Prometheus Metrics 采集路径是：/management/prometheus。

如何在 triple 协议场景下使用 protobuf、json 序列化

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

1 介绍

Protobuf（Protocol Buffers）是由 Google 开发的一种轻量级、高效的数据交换格式，它被用于结构化数据的序列化、反序列化和传输。相比于XML 和JSON 等文本格式，Protobuf 具有更小的数据体积、更快的解析速度和更强的可扩展性。

2 使用方式

在使用 Protobuf(IDL) 开发 triple 通信服务的时候，dubbo server 将自动启用 protobuf、protobuf-json 序列化模式支持。

2.1 添加依赖

使用 triple + protobuf 模式，必须添加以下依赖：

<dependencies>
	<dependency>
		<groupId>com.google.protobuf</groupId>
		<artifactId>protobuf-java</artifactId>
		<version>3.19.6</version>
	</dependency>
	<!-- 提供 protobuf-json 格式请求支持 -->>
	<dependency>
		<groupId>com.google.protobuf</groupId>
		<artifactId>protobuf-java-util</artifactId>
		<version>3.19.6</version>
	</dependency>
</dependencies>

2.2 配置启用

只要是基于 Protobuf(IDL) 开发模式进行 triple 协议通信，就会使用 protobuf 序列化，只要定义 protobuf 文件并启用 triple 协议即可。

当使用 cURL 访问 triple 服务时，是会启用 protobuf-json 序列化模式

curl \
 --header "Content-Type: application/json" \
 --data '{"name":"Dubbo"}' \
 http://localhost:50052/org.apache.dubbo.samples.tri.unary.Greeter/greet/

protobuf 服务定义示例：

QOS 概述

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

如何使用

QoS 提供了一些启动参数，来对启动进行配置，他们主要包括：

参数	说明	默认值
qos-enable	是否启动QoS	true
qos-port	启动QoS绑定的端口	22222
qos-accept-foreign-ip	是否允许远程访问	false
qos-accept-foreign-ip-whitelist	支持的远端主机ip地址（段）	(无)
qos-anonymous-access-permission-level	支持的匿名访问的权限级别	PUBLIC(1)

注意，从2.6.4/2.7.0开始，qos-accept-foreign-ip默认配置改为false，如果qos-accept-foreign-ip设置为true，有可能带来安全风险，请仔细评估后再打开。

telnet 与 http 协议

telnet 模块现在同时支持 http 协议和 telnet 协议，方便各种情况的使用示例：

➜ ~ telnet localhost 22222
Trying ::1...
telnet: connect to address ::1: Connection refused
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
 ████████▄ ███ █▄ ▀█████████▄ ▀█████████▄ ▄██████▄
 ███ ▀███ ███ ███ ███ ███ ███ ███ ███ ███
 ███ ███ ███ ███ ███ ███ ███ ███ ███ ███
 ███ ███ ███ ███ ▄███▄▄▄██▀ ▄███▄▄▄██▀ ███ ███
 ███ ███ ███ ███ ▀▀███▀▀▀██▄ ▀▀███▀▀▀██▄ ███ ███
 ███ ███ ███ ███ ███ ██▄ ███ ██▄ ███ ███
 ███ ▄███ ███ ███ ███ ███ ███ ███ ███ ███
 ████████▀ ████████▀ ▄█████████▀ ▄█████████▀ ▀██████▀


dubbo>ls
As Provider side:
+----------------------------------+---+
| Provider Service Name |PUB|
+----------------------------------+---+
|org.apache.dubbo.demo.DemoService| N |
+----------------------------------+---+
As Consumer side:
+---------------------+---+
|Consumer Service Name|NUM|
+---------------------+---+

dubbo>

端口

新版本的 telnet 端口与 dubbo 协议的端口是不同的端口，默认为 22222

Request Routing

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

Before you begin Setup Istio by following the instructions in the Installation guide.

Deploy the Bookinfo sample application.

Review the Traffic Management concepts doc.

About this task The Istio Bookinfo sample consists of four separate microservices, each with multiple versions. Three different versions of one of the microservices, reviews, have been deployed and are running concurrently. To illustrate the problem this causes, access the Bookinfo app’s /productpage in a browser and refresh several times. The URL is http://$GATEWAY_URL/productpage, where $GATEWAY_URL is the External IP address of the ingress, as explained in the Bookinfo doc.

Request Routing

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

Before you begin Setup Istio by following the instructions in the Installation guide.

Deploy the Bookinfo sample application.

Review the Traffic Management concepts doc.

Request Routing

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

Before you begin Setup Istio by following the instructions in the Installation guide.

Deploy the Bookinfo sample application.

Review the Traffic Management concepts doc.

Request Routing

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

Before you begin Setup Istio by following the instructions in the Installation guide.

Deploy the Bookinfo sample application.

Review the Traffic Management concepts doc.

Rest 协议

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

本文将介绍 Dubbo 的 REST/HTTP 协议设计。

RestProtocol 设计

原版本dubbo rest

consumer

restClient支持依赖resteasy 不支持spring mvc

provider(较重)

依赖web container (tomcat,jetty，)servlet 模式，jaxrs netty server

新版本dubbo rest

更加轻量，具有dubbo风格的rest，微服务体系互通（Springcloud Alibaba）

1.注解解析

2.报文编解码

3.restClient

4.restServer(netty)

支持程度：

content-type text json xml form(后续会扩展)

注解

param,header,body,pathvaribale （spring mvc & resteasy）

Http 协议报文

POST /test/path? HTTP/1.1
Host: localhost:8080
Connection: keep-alive
Content-type: application/json


{"name":"dubbo","age":10,"address":"hangzhou"}

dubbo http(header)

// service key header
path: com.demo.TestInterface
group: demo
port: 80
version: 1.0.0

// 保证长连接
Keep-Alive,Connection: keep-alive
Keep-alive: 60

// RPCContext Attachment
userId: 123456

支持粒度

数据位置	content-type	spring注解	resteasy注解
body	无要求	ReuqestBody	无注解即为body
querystring(?test=demo)	无要求	RequestParam	QueryParam
header	无要求	RequestHeader	PathParam
form	application/x-www-form-urlencoded	RequestParam ReuqestBody	FormParam
path	无要求	PathVariable	PathParam
method	无要求	PostMapping GetMapping	GET POST
url		PostMapping GetMapping path属性	Path
content-type		PostMapping GetMapping consumers属性	Consumers
Accept		PostMapping GetMapping produces属性	Produces

rest注解解析

ServiceRestMetadataResolver

RPC 协议 Triple&Dubbo 基准测试

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

Dubbo3 的 _Dubbo协议 _实现与 Dubbo2 版本在性能上基本持平。
由于 Triple协议本身是基于 HTTP/2 构建，因此在单条链路上的 RPC 调用并未比基于 TCP 的 Dubbo2 有提升，反而在某些调用场景出现一定下降。但 _Triple协议 _更大的优势在于网关穿透性、通用性，以及 Stream 通信模型带来的总体吞吐量提升。
Triple 预期在网关代理场景下一定会有更好的性能表现，鉴于当前压测环境，本轮 benchmark 暂未提供。

1.1 环境

	描述
机器	4C8G Linux JDK 1.8（Provider）4C8G Linux JDK 1.8 （Consumer）
压测用例	RPC 方法类型包括：无参无返回值、普通pojo返回值、pojo列表返回值 2.7 版本 Dubbo 协议（Hessian2 序列化） 3.0 版本 Dubbo 协议（Hessian2 序列化） 3.0 版本 Dubbo 协议（Protobuf 序列化） 3.0 版本 Triple 协议（Protobuf 序列化） 3.0 版本 Triple 协议（Protobuf 套 Hessian2 序列化）
压测方法	单链接场景下，消费端起 32 并发线程（当前机器配置 qps rt 较均衡的并发数），持续压后采集压测数据压测数据通过 https://github.com/apache/dubbo-benchmark 得出

1.2 数据分析

	Dubbo + Hessian2 2.7	Dubbo + Hessian2 3.0	Dubbo + Protobuf 3.0	Triple + Protobuf 3.0	Triple + Protobuf(Hessian) 3.0
无参方法	30333 ops/s 2.5ms P99	30414 ops/s 2.4ms P99	24123 ops/s 3.2ms P99	7016 ops/s 8.7ms P99	6635 ops/s 9.1ms P99
pojo返回值	8984 ops/s 6.1 ms P99	12279 ops/s 5.7 ms P99	21479 ops/s 3.0 ms P99	6255 ops/s 8.9 ms P99	6491 ops/s 10 ms P99
pojo列表返回值	1916 ops/s 34 ms P99	2037 ops/s 34 ms P99	12722 ops/s 7.7 ms P99	6920 ops/s 9.6 ms P99	2833 ops/s 27 ms P99

1.2.1 Dubbo 协议不同版本实现对比

RPC 基准测试控制台

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

dubbo-benchmark

Seata分布式事务

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

先执行以下命令，启动 seata-server。

cd ../dockercompose
docker-compose -f docker-compose.yml up -d seata-server

再执行 triple/client/cmd 和 triple/server/cmd 目录下的 main()方法。

完整示例源码地址

使用 Sentinel 应对突发流量，保护您的应用

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

在复杂的生产环境下可能部署着成千上万的 Dubbo 服务实例，流量持续不断地进入，服务之间进行相互调用。但是分布式系统中可能会因流量激增、系统负载过高、网络延迟等一系列问题，导致某些服务不可用，如果不进行相应的控制可能导致级联故障，影响服务的可用性，因此如何对流量进行合理的控制，成为保障服务稳定性的关键。

Sentinel 是阿里中间件团队开源的，面向分布式服务架构的轻量级流量控制产品，主要以流量为切入点，从流量控制、熔断降级、系统负载保护等多个维度来帮助用户保护服务的稳定性。

本文提供 Dubbo 整合 Sentinel 限流降级的最佳实践。

快速接入 Sentinel

Sentinel 通过对服务提供方和服务消费方的限流提升服务在极端场景下的可用性，接下来我们看看 Sentinel 对服务提供方和服务消费方限流的技术实现方式。

使用时我们只需引入以下模块（以 Maven 为例）：

<dependency>
	<groupId>com.alibaba.csp</groupId>
	<artifactId>sentinel-apache-dubbo3-adapter</artifactId>
	<version>1.8.6</version>
</dependency>
<!-- optional -->
<dependency>
	<groupId>com.alibaba.csp</groupId>
	<artifactId>sentinel-transport-simple-http</artifactId>
	<version>1.8.6</version>
</dependency>

引入此依赖后，Dubbo 的服务接口和方法（包括调用端和服务端）就会成为 Sentinel 中的资源，在配置了规则后就可以自动享受到 Sentinel 的防护能力。

sentinel-apache-dubbo3-adapter 中包含 Sentinel Filter 实现，加入依赖之后会自动开启。如若不希望开启 Sentinel Dubbo Adapter 中的某个 Filter，可通过配置关闭，如 dubbo.provider.filter="-sentinel.dubbo.consumer.filter"。

示例详解

可在此查看以下示例的完整源码。

Provider 端限流

对服务提供方的流量控制可分为 服务提供方的自我保护能力 和 服务提供方对服务消费方的请求分配能力 两个维度。

基于 QPS 设定限流

为了保护 Provider 不被激增的流量拖垮影响稳定性，可以给 Provider 配置 QPS 模式 的限流，这样当每秒的请求量超过设定的阈值时会自动拒绝多出来的请求。

以下是示例中配置的 服务级别 的 QPS 限流配置，最大 QPS 设定为 10：

使用轻量的 Java SDK 开发 RPC Server 和 Client

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

本示例演示如何使用轻量 Dubbo SDK 开发 RPC Server 与 Client，示例使用 Java Interface 方式定义、发布和访问 RPC 服务，底层使用 Triple 协议通信。本示例完整代码请参见 dubbo-samples。

基于 Dubbo 定义的 Triple 协议，你可以轻松编写浏览器、gRPC 兼容的 RPC 服务，并让这些服务同时运行在 HTTP/1 和 HTTP/2 上。Dubbo Java SDK 支持使用 IDL 或编程语言特有的方式定义服务，并提供一套轻量的 API 来发布或调用这些服务。

Maven 依赖

在基于 Dubbo RPC 编码之前，您只需要在项目添加一个非常轻量的 dubbo依赖包即可，以 Maven 为例：

<dependency>
 <groupId>org.apache.dubbo</groupId>
 <artifactId>dubbo</artifactId>
 <version>3.3.0</version>
</dependency>

<!-- 为了避免 Netty 依赖冲突，您也可以是选择使用 dubbo-shaded 版本！-->
<!--
<dependency>
 <groupId>org.apache.dubbo</groupId>
 <artifactId>dubbo-shaded</artifactId>
 <version>3.3.0</version>
</dependency>
-->

定义服务

定义一个名为 DemoService的标准 Java 接口作为 Dubbo 服务（Dubbo 还支持基于 IDL 的服务定义模式）。

Dubbo SPI 概述

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

使用 IoC 容器帮助管理组件的生命周期、依赖关系注入等是很多开发框架的常用设计，Dubbo 中内置了一个轻量版本的 IoC 容器，用来管理框架内部的插件，实现包括插件实例化、生命周期、依赖关系自动注入等能力。

感兴趣的读者可以了解：

Dubbo 插件体系与 IoC 容器具有以下特点：

核心组件均被定义为插件，用户或二次开发者扩展非常简单。 在无需改造框架内核的情况下，用户可以基于自身需求扩展如负载均衡、注册中心、通信协议、路由等策略。
平等对待第三方扩展实现。 Dubbo 中所有内部实现和第三方实现都是平等的，用户可以基于自身业务需求替换 Dubbo 提供的原生实现。
插件依赖支持自动注入（IoC）。 如果插件实现依赖其他插件属性，则 Dubbo 框架会完成该依赖对象的自动注入，支持属性、构造函数等方式。
插件扩展实现支持 AOP 能力。 框架可以自动发现扩展类的包装类，通过包装器模式对插件进行 AOP 增强。
支持插件自动激活。 通过为插件实现指定激活条件（通过注解参数等），框架可在运行时自动根据当前上下文决策是否激活该插件实现。
支持插件扩展排序。

Spring Boot

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

Dubbo 提供了对 Spring 框架的完整支持，我们推荐使用官方提供的 dubbo-spring-boot-starter 高效开发 Dubbo 微服务应用。

创建项目

创建 Dubbo 应用最快捷的方式就是直接复制快速开始中的示例并进行定制化修改。

另一种更灵活的方式是使用官方项目脚手架工具 - start.dubbo.apache.org 在线服务。它可以帮助开发者创建 Spring Boot 结构应用，根据用户的选择自动管理 dubbo-spring-boot-starter 等依赖和必要配置。

注意

另外，Jetbrain 官方也提供了 Apache Dubbo 项目插件，可用于快速创建 Dubbo Spring Boot 项目，能力与 start.dubbo.apache.org 对等，具体安装使用请查看博客文章

dubbo-spring-boot-starter

在快速开始中，我们已经详细介绍了典型的 Dubbo Spring Boot 工程源码及其项目结构，不熟悉的开发者可以前往查看。

dubbo-spring-boot-starter 可为项目引入 dubbo 核心依赖，自动扫描 dubbo 相关配置与注解。

Maven 依赖

使用 Dubbo Spring Boot Starter，首先引入以下 Maven 依赖

 <dependencyManagement>
 <dependencies>
 <dependency>
 <groupId>org.apache.dubbo</groupId>
 <artifactId>dubbo-bom</artifactId>
 <version>3.3.0</version>
 <type>pom</type>
 <scope>import</scope>
 </dependency>
 </dependencies>
 </dependencyManagement>

然后，在相应模块的 pom 中增加必要的 starter 依赖：

Triple 协议设计理念与规范

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

1 协议设计理念

Triple 协议的设计参考了 gRPC、gRPC-Web、通用 HTTP 等多种协议模式，吸取每个协议各自的特性和优点，最终设计成为一个易于浏览器访问、完全兼容 gRPC 且支持 Streaming 通信的协议，Triple 支持同时运行在 HTTP/1、HTTP/2 协议之上。

Triple 协议的设计目标如下：

Triple 设计为对人类、开发调试友好的一款基于 HTTP 的协议，尤其是对 unary 类型的 RPC 请求。
完全兼容基于 HTTP/2 的 gRPC 协议，因此 Dubbo Triple 协议实现可以 100% 与 gRPC 体系互调互通。
仅依赖标准的、被广泛使用的 HTTP 特性，以便在实现层面可以直接依赖官方的标准 HTTP 网络库。

当与 Protocol Buffers 一起使用时（即使用 IDL 定义服务），Triple 协议可支持 unary、client-streaming、server-streaming 和 bi-streaming RPC 通信模式，支持二进制 Protobuf、JSON 两种数据格式 payload。 Triple 实现并不绑定 Protocol Buffers，比如你可以使用 Java 接口定义服务，Triple 协议有对这种模式的扩展 Content-type 支持。

2 示例

2.1 Unary 请求

以 HTTP/1 请求为例，目前 HTTP/1 协议仅支持 Unary RPC，支持使用 application/proto 和 application/json 编码类型，使用方式与 REST 风格请求保持一致，同时响应也包含常规的 HTTP 响应编码（如 200 OK）。

Triple 协议优势与目标

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

简介

Triple 协议是 Dubbo3 设计的基于 HTTP 的 RPC 通信协议规范，它完全兼容 gRPC 协议，支持 Request-Response、Streaming 流式等通信模型，可同时运行在 HTTP/1 和 HTTP/2 之上。

Dubbo 框架提供了 Triple 协议的多种语言实现，它们可以帮助你构建浏览器、gRPC 兼容的 HTTP API 接口：你只需要定义一个标准的 Protocol Buffer 格式的服务并实现业务逻辑，Dubbo 负责帮助生成语言相关的 Server Stub、Client Stub，并将整个调用流程无缝接入如路由、服务发现等 Dubbo 体系。Go、Java 等语言的 Triple 协议实现原生支持 HTTP/1 传输层通信，相比于 gRPC 官方实现，Dubbo 框架提供的协议实现更简单、更稳定，帮助你更容易的开发和治理微服务应用。

针对某些语言版本，Dubbo 框架还提供了更贴合语言特性的编程模式，即不绑定 IDL 的服务定义与开发模式，比如在 Dubbo Java 中，你可以选择使用 Java Interface 和 Pojo 类定义 Dubbo 服务，并将其发布为基于 Triple 协议通信的微服务。

协议规范(Specification)

基于 Triple 协议，你可以实现以下目标：

当 Dubbo 作为 Client 时

Dubbo Client 可以访问 Dubbo 服务端 (Server) 发布的 Triple 协议服务，同时还可以访问标准的 gRPC 服务端。

Web 浏览器访问 Dubbo 服务

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

基于 Dubbo3 定义的 Triple 协议，你可以轻松编写浏览器、gRPC 兼容的 RPC 服务，并让这些服务同时运行在 HTTP/1 和 HTTP/2 上。Dubbo TypeScript SDK 支持使用 IDL 或编程语言特有的方式定义服务，并提供一套轻量的 API 来发布或调用这些服务。

Dubbo-js 已于 9 月份发布支持 Dubbo3 协议的首个 alpha 版本，它的发布将有机会彻底改变微服务前后端的架构与通信模式，让你能直接在浏览器页面或web服务器中访问后端 Dubbo RPC 服务。

浏览器 Web 应用示例

本示例演示了如何使用 dubbo-js 开发运行在浏览器上的 web 应用程序，web 页面将调用 dubbo node.js 开发的后端服务并生成页面内容。本示例演示基于 IDL 和非 IDL 两种编码模式。

IDL 模式

前置条件

首先，我们将使用 Vite 来生成我们的前端项目模板，它内置了我们稍后需要的所有功能支持。

npm create vite@latest -- dubbo-web-example --template react-ts
cd dubbo-web-example
npm install

因为使用 Protocol Buffer 的原因，我们首先需要安装相关的代码生成工具，这包括 @bufbuild/protoc-gen-es、@bufbuild/protobuf、@apachedubbo/protoc-gen-apache-dubbo-es、@apachedubbo/dubbo。

npm install @bufbuild/protoc-gen-es @bufbuild/protobuf @apachedubbo/protoc-gen-apache-dubbo-es @apachedubbo/dubbo

使用 Proto 定义服务

现在，使用 Protocol Buffer (IDL) 来定义一个 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>

配置之间的关系

Zookeeper 注册中心

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

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

Zookeeper 是 Apache Hadoop 的子项目，是一个树型的目录服务，支持变更推送，适合作为 Dubbo 服务的注册中心，工业强度较高，可用于生产环境，并推荐使用 ¹。

流程说明：

服务提供者启动时: 向 /dubbo/com.foo.BarService/providers 目录下写入自己的 URL 地址
服务消费者启动时: 订阅 /dubbo/com.foo.BarService/providers 目录下的提供者 URL 地址。并向 /dubbo/com.foo.BarService/consumers 目录下写入自己的 URL 地址
监控中心启动时: 订阅 /dubbo/com.foo.BarService 目录下的所有提供者和消费者 URL 地址。

支持以下功能：

当提供者出现断电等异常停机时，注册中心能自动删除提供者信息
当注册中心重启时，能自动恢复注册数据，以及订阅请求
当会话过期时，能自动恢复注册数据，以及订阅请求
当设置 <dubbo:registry check="false" /> 时，记录失败注册和订阅请求，后台定时重试
可通过 <dubbo:registry username="admin" password="1234" /> 设置 zookeeper 登录信息
可通过 <dubbo:registry group="dubbo" /> 设置 zookeeper 的根节点，不配置将使用默认的根节点。
支持 * 号通配符 <dubbo:reference group="*" version="*" />，可订阅服务的所有分组和所有版本的提供者

使用

在 provider 和 consumer 中增加 zookeeper 客户端 jar 包依赖：

Zookeeper 注册中心

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

流程说明：

服务提供者启动时: 向 /dubbo/com.foo.BarService/providers 目录下写入自己的 URL 地址
服务消费者启动时: 订阅 /dubbo/com.foo.BarService/providers 目录下的提供者 URL 地址。并向 /dubbo/com.foo.BarService/consumers 目录下写入自己的 URL 地址
监控中心启动时: 订阅 /dubbo/com.foo.BarService 目录下的所有提供者和消费者 URL 地址。

支持以下功能：

当提供者出现断电等异常停机时，注册中心能自动删除提供者信息
当注册中心重启时，能自动恢复注册数据，以及订阅请求
当会话过期时，能自动恢复注册数据，以及订阅请求
当设置 <dubbo:registry check="false" /> 时，记录失败注册和订阅请求，后台定时重试
可通过 <dubbo:registry username="admin" password="1234" /> 设置 zookeeper 登录信息
可通过 <dubbo:registry group="dubbo" /> 设置 zookeeper 的根节点，不配置将使用默认的根节点。
支持 * 号通配符 <dubbo:reference group="*" version="*" />，可订阅服务的所有分组和所有版本的提供者

使用

在 provider 和 consumer 中增加 zookeeper 客户端 jar 包依赖：

版本信息

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

Go	Dubbo-go	protoc-gen-go-triple	说明
1.20	v3.2.0-rc1（当前文档）	v3.0.0	当前最新稳定版本，推荐使用

历史版本

3.x

查看 3.1.x 及之前版本文档：

Go	Dubbo-go	protoc-gen-go-triple	说明
1.16	v3.1.1	v3.0.0	请参考 README 说明，了解如何生成老版本兼容的服务 stub 代码
1.16	v3.1.0	v3.0.0	请参考 README 说明，了解如何生成老版本兼容的服务 stub 代码
1.16	v3.0.4	v3.0.0	请参考 README 说明，了解如何生成老版本兼容的服务 stub 代码
1.16	v3.0.3	v3.0.0	请参考 README 说明，了解如何生成老版本兼容的服务 stub 代码
1.16	v3.0.2	v3.0.0	请参考 README 说明，了解如何生成老版本兼容的服务 stub 代码
1.16	v3.0.1	v3.0.0	请参考 README 说明，了解如何生成老版本兼容的服务 stub 代码
1.16	v3.0.0	v1.0.5
1.16	v3.0.0-rc4-1	v1.0.2
1.16	v3.0.0-rc3	v1.0.0

1.x

Go	Dubbo-go	Triple	protoc-gen-go-triple	说明
	v1.5.0	v1.1.8	v1.0.8	停止维护，请升级到最新 3.x 版本

版本信息

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

我们提供了不同版本的 Dubbo Java 实现文档，您可以在下方版本列表中选择不同的版本文档，查看每个版本的维护情况、组件版本、升级注意事项等。

版本说明

Dubbo 分支	最新版本	JDK	Spring Boot	组件版本	详细说明
3.3.x (当前文档)	3.3.0	8, 17, 21	2.x、3.x	详情	- 版本变更记录 - 生产可用（推荐，长期维护）！最新Triple协议升级，内置Metrics、Tracing、GraalVM支持等
3.2.x	3.2.10	8, 17	2.x、3.x	详情	- 版本变更记录 - 生产可用（长期维护）！
3.1.x	3.1.11	8, 17	2.x、3.x	详情	- 版本变更记录 - 仅修复安全漏洞！
3.0.x	3.0.15	8	2.x	详情	- 版本变更记录 - 停止维护！
2.7.x	2.7.23	8	2.x	详情	- 了解如何升级到Dubbo3 - 停止维护！
2.6.x	2.6.20	6, 7	-	_	- 了解如何升级到Dubbo3 - 停止维护！
2.5.x	2.5.10	6, 7	-	-	- 了解如何升级到Dubbo3 - 停止维护！

背景

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

随着互联网的发展，网站应用的规模不断扩大，常规的垂直应用架构已无法应对，分布式服务架构以及流动计算架构势在必行，亟需一个治理系统确保架构有条不紊的演进。

单一应用架构

当网站流量很小时，只需一个应用，将所有功能都部署在一起，以减少部署节点和成本。此时，用于简化增删改查工作量的数据访问框架(ORM)是关键。

垂直应用架构

当访问量逐渐增大，单一应用增加机器带来的加速度越来越小，提升效率的方法之一是将应用拆成互不相干的几个应用，以提升效率。此时，用于加速前端页面开发的Web框架(MVC)是关键。

分布式服务架构

当垂直应用越来越多，应用之间交互不可避免，将核心业务抽取出来，作为独立的服务，逐渐形成稳定的服务中心，使前端应用能更快速的响应多变的市场需求。此时，用于提高业务复用及整合的分布式服务框架(RPC)是关键。

流动计算架构

当服务越来越多，容量的评估，小服务资源的浪费等问题逐渐显现，此时需增加一个调度中心基于访问压力实时管理集群容量，提高集群利用率。此时，用于提高机器利用率的资源调度和治理中心(SOA)是关键。

使用 dubbogo.yml 配置文件开发应用

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

1.介绍

本文档演示如何在框架中使用 yaml 配置文件进行微服务开发，是相比于 API 的另一种微服务开发模式。你可以完全使用 yml 配置文件进行开发，也可以将部分全局配置放到配置文件，而只在 API 中完成服务定义。

这种模式下，一定要通过 DUBBO_GO_CONFIG_PATH 指定配置文件路径：

export DUBBO_GO_CONFIG_PATH="../conf/dubbogo.yml"

2. 使用说明

可在此查看完整示例源码。

2.1 运行示例

.
├── go-client
│   ├── cmd
│   │   └── main.go
│   └── conf
│   └── dubbogo.yml
├── go-server
│   ├── cmd
│   │   └── main.go
│   └── conf
│   └── dubbogo.yml
└─── proto
    ├── greet.pb.go
    ├── greet.proto
    └── greet.triple.go

通过 IDL./proto/greet.proto 定义服务使用triple协议

build Proto

cd path_to_dubbogo-sample/config_yaml/proto
protoc --go_out=. --go-triple_out=. ./greet.proto

Server

export DUBBO_GO_CONFIG_PATH="../conf/dubbogo.yml"
cd path_to_dubbogo-sample/config_yaml/go-server/cmd
go run .

Client

export DUBBO_GO_CONFIG_PATH="../conf/dubbogo.yml"
cd path_to_dubbogo-sample/config_yaml/go-client/cmd
go run .

2.2 客户端使用说明

客户端定义的 yaml 文件：

标签路由

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

使用方法

前置准备

Docker 以及 Docker compose 环境来部署Nacos配置中心。
Nacos 2.x+
Go 1.23+

启动Nacos配置中心

参考这个教程来启动Nacos。

Tag router 介绍

Tag router可以通过标签对流量进行管控，以下为示例代码。

服务端部分：

ins, err := dubbo.NewInstance(
		dubbo.WithName("tag-server"),
		dubbo.WithTag("test-Tag"), // set application's tag
		dubbo.WithRegistry(
			registry.WithNacos(),
			registry.WithAddress(RegistryAddress),
		),
		dubbo.WithProtocol(
			protocol.WithTriple(),
			protocol.WithPort(20000),
		),
	)

参数：

dubbo.WithTag: 设置该实例携带的tag，用于标记该实例（例如为灰度环境等）。

客户端部分：

atta := map[string]string{
	constant.Tagkey: "test-tag",
	constant.ForceUseTag: "true", // 使用string类型
}
ctx := context.WithValue(context.Background(), constant.AttachmentKey, atta)
resp, err := svc.Greet(ctx, &greet.GreetRequest{Name: name})

参数:

constant.TagKey: 设置客户端发送请求时所携带的tag标签。
constant.ForceUseTag: 设置是否强制匹配标签。

未携带标签的流量只能打到未携带标签的服务，携带标签的流量则可以打到携带相应标签的服务以及不具有标签的服务（取决于是否配置force参数）。

Dubbo 框架标准监控指标

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

Dubbo 指标含义

Provider Metrics

Metrics Name	Description	说明
dubbo_provider_qps_total	The number of requests received by the provider per second	提供者每秒接收的请求数
dubbo_provider_requests_total	The total number of received requests by the provider	提供者总的接收请求数
dubbo_provider_requests_total_aggregate	The total number of received requests by the provider under the sliding window	滑动窗口下的提供者总的接收请求数
dubbo_provider_requests_processing	The number of received requests being processed by the provider	提供者正在处理的接收的请求数
dubbo_provider_requests_succeed_total	The number of requests successfully received by the provider	提供者请求成功接收的请求数
dubbo_provider_requests_succeed_aggregate	The number of successful requests received by the provider under the sliding window	滑动窗口下的提供者成功的接收请求数
dubbo_provider_rt_milliseconds_min	The minimum response time among all requests processed by the provider	提供者所有处理请求中最小的响应时间
dubbo_provider_rt_min_milliseconds_aggregate	The minimum response time of the provider under the sliding window	滑动窗口下的提供者最小响应时间
dubbo_provider_rt_milliseconds_avg	The average response time of all requests processed by the provider	提供者所有处理请求的平均响应时间
dubbo_provider_rt_avg_milliseconds_aggregate	The average response time of the provider under the sliding window	滑动窗口下的提供者平均响应时间
dubbo_provider_rt_milliseconds_sum	The total time taken by the provider to process all requests	提供者所有处理请求的时间总和
dubbo_provider_rt_milliseconds_max	The maximum response time among all requests from the provider	提供者所有请求中最大的响应时间
dubbo_provider_rt_max_milliseconds_aggregate	The maximum response time of the provider under the sliding window	滑动窗口下的提供者最大响应时间
dubbo_provider_rt_milliseconds_last	The current response time in the provider’s processing of requests	提供者处理请求中当前的响应时间
dubbo_provider_rt_milliseconds_p50	The total response time spent by providers processing 50% of requests	提供者处理请求中50%的请求耗费的总响应时间
dubbo_provider_rt_milliseconds_p90	The total response time spent by providers processing 90% of requests	提供者处理请求中90%的请求耗费的总响应时间
dubbo_provider_rt_milliseconds_p95	The total response time spent by providers processing 95% of requests	提供者处理请求中95%的请求耗费的总响应时间
dubbo_provider_rt_milliseconds_p99	The total response time spent by providers processing 99% of requests	提供者处理请求中99%的请求耗费的总响应时间
dubbo_provider_requests_processing_total	The number of received requests being processed by the provider	提供者正在处理的接收的请求数
dubbo_provider_rt_milliseconds_histogram_seconds_bucket	The histogram of response time of the provider under the sliding window	滑动窗口下的提供者响应时间直方图
dubbo_provider_rt_milliseconds_histogram_seconds_count	The count of histogram of response time of the provider under the sliding window	滑动窗口下的提供者响应时间直方图总数
dubbo_provider_rt_milliseconds_histogram_seconds_max	The max of histogram of response time of the provider under the sliding window	滑动窗口下的提供者响应时间直方图最大值
dubbo_provider_rt_milliseconds_histogram_seconds_sum	The sum of histogram of response time of the provider under the sliding window	滑动窗口下的提供者响应时间直方图总和
dubbo_provider_requests_business_failed_total	Total Failed Business Requests	当RPC请求异常状态码为 RpcException.BIZ_EXCEPTION
dubbo_provider_requests_timeout_total	Total Timeout Failed Requests	当RPC请求异常为超时异常状态码为 RpcException.TIMEOUT_EXCEPTION
dubbo_provider_requests_limit_total	Total Limit Failed Requests	RPC请求中一般为并发数超过了限制 max concurrent invoke 或者是超过了系统的上限出现了异常状态码为RpcException.LIMIT_EXCEEDED_EXCEPTION或者异常类型为LimitExceededException LimitExceededException
dubbo_provider_requests_unknown_failed_total	Total Unknown Failed Requests	暂为归类的其他类型的异常具体分析根据日志来看
dubbo_provider_requests_failed_total	Total Failed Requests	总的异常次数
dubbo_provider_requests_failed_total_aggregate	Total Failed Aggregate Requests	聚合请求失败次数，当聚合请求中有一个请求失败时候会触发此异常
dubbo_provider_requests_failed_network_total	Total network Failed Requests	一般发生在网络连接失败或者网络通信时候发生的异常，对应Java异常为RemotingException
dubbo_provider_requests_failed_service_unavailable_total	Total Service Unavailable Failed Requests	当不存在提供者或者调用了被禁止访问提的提供者时候会出现此异常，对应异常码FORBIDDEN_EXCEPTION
dubbo_provider_requests_failed_codec_total	Total codec failed	序列化相关的异常，异常码SERIALIZATION_EXCEPTION
dubbo_provider_requests_failed_aggregate	Total Failed Aggregate Requests	聚合请求失败次数，当聚合请求中有一个请求失败时候会触发此异常
dubbo_provider_requests_timeout_total	Total Timeout Failed Requests	当RPC请求异常为超时异常状态码为 RpcException.TIMEOUT_EXCEPTION
dubbo_provider_requests_limit_total	Total Limit Failed Requests	RPC请求中一般为并发数超过了限制 max concurrent invoke 或者是超过了系统的上限出现了异常状态码为RpcException_LIMIT_EXCEEDED_EXCEPTION或者异常类型为LimitExceededException LimitExceededException
dubbo_provider_requests_unknown_failed_total	Total Unknown Failed Requests	暂为归类的其他类型的异常具体分析根据日志来看
dubbo_provider_requests_failed_total	Total Failed Requests	总的异常次数
dubbo_provider_requests_failed_network_total	Total network Failed Requests	一般发生在网络连接失败或者网络通信时候发生的异常，对应Java异常为RemotingException
dubbo_provider_requests_failed_service_unavailable_total	Total Service Unavailable Failed Requests	当不存在提供者或者调用了被禁止访问提的提供者时候会出现此异常，对应异常码FORBIDDEN_EXCEPTION
dubbo_provider_requests_failed_codec_total	Total codec failed	序列化相关的异常，异常码SERIALIZATION_EXCEPTION

Consumer Metrics

Metrics Name	Description	说明
dubbo_consumer_qps_total	The number of requests sent by consumers per second	消费者每秒发送的请求数
dubbo_consumer_requests_total	Total number of sent requests by consumers	消费者总的发送请求数
dubbo_consumer_requests_total_aggregate	The total number of requests sent by consumers under the sliding window	滑动窗口下的消费者总的发送请求数
dubbo_consumer_requests_processing	The number of sent requests that consumers are currently processing	消费者正在处理的发送的请求数
dubbo_consumer_requests_succeed_total	The number of successful requests sent by consumers	消费者请求成功发送的请求数
dubbo_consumer_requests_succeed_aggregate	The number of successful requests sent by consumers under the sliding window	滑动窗口下的消费者成功的发送请求数
dubbo_consumer_rt_milliseconds_min	Minimum response time among all consumer requests	消费者所有请求中最小的响应时间
dubbo_consumer_rt_min_milliseconds_aggregate	The minimum response time of the consumer under the sliding window	滑动窗口下的消费者最小响应时间
dubbo_consumer_rt_milliseconds_avg	Average response time of all requests from consumers	消费者所有请求的平均响应时间
dubbo_consumer_rt_avg_milliseconds_aggregate	The average response time of the consumer under the sliding window	滑动窗口下的消费者平均响应时间
dubbo_consumer_rt_milliseconds_sum	The total time of all consumer requests	消费者所有请求的时间总和
dubbo_consumer_rt_milliseconds_max	Maximum response time among all requests from consumers	消费者所有请求中最大的响应时间
dubbo_consumer_rt_max_milliseconds_aggregate	The maximum response time of the consumer under the sliding window	滑动窗口下的消费者最大响应时间
dubbo_consumer_rt_milliseconds_last	The current response time in consumer processing requests	消费者处理请求中当前的响应时间
dubbo_consumer_rt_milliseconds_p50	The total response time spent by consumers processing 50% of requests	消费者处理请求中50%的请求耗费的总响应时间
dubbo_consumer_rt_milliseconds_p90	The total response time spent by consumers processing 90% of requests	消费者处理请求中90%的请求耗费的总响应时间
dubbo_consumer_rt_milliseconds_p95	The total response time spent by consumers processing 95% of requests	消费者处理请求中95%的请求耗费的总响应时间
dubbo_consumer_rt_milliseconds_p99	The total response time spent by consumers processing 99% of requests	消费者处理请求中99%的请求耗费的总响应时间
dubbo_consumer_rt_milliseconds_histogram_seconds_bucket	Histogram of response time of all requests from consumers	消费者所有请求的响应时间直方图
dubbo_consumer_rt_milliseconds_histogram_seconds_count	count of Histogram of all requests from consumers	消费者所有请求的响应时间直方图总数量
dubbo_consumer_rt_milliseconds_histogram_seconds_sum	sum of Histogram of all requests from consumers	消费者所有请求的响应时间直方图总和
dubbo_consumer_rt_milliseconds_histogram_seconds_max	max of Histogram of all requests from consumers	消费者所有请求的响应时间直方图最大值
dubbo_consumer_requests_business_failed_total	Total Failed Business Requests	当RPC请求异常状态码为RpcException.BIZ_EXCEPTION
dubbo_consumer_requests_timeout_total	Total Timeout Failed Requests	当RPC请求异常为超时异常状态码为RpcException.TIMEOUT_EXCEPTION
dubbo_consumer_requests_timeout_failed_aggregate	Total Timeout Failed Requests	滑动窗口内的聚合指标当RPC请求异常为超时异常状态码为RpcException.TIMEOUT_EXCEPTION
dubbo_consumer_requests_limit_total	Total Limit Failed Requests	RPC请求状态码为RpcException.LIMIT_EXCEEDED_EXCEPTION或者异常类型为LimitExceededException 一般为并发数超过了限制 max concurrent invoke 或者是超过了系统的上限出现了异常LimitExceededException
dubbo_consumer_requests_unknown_failed_total	Total Unknown Failed Requests	暂为归类的其他类型的异常具体分析根据日志来看
dubbo_consumer_requests_failed_total	Total Failed Requests	总的异常次数
dubbo_consumer_requests_failed_total_aggregate	Total Failed Requests	滑动窗口内的聚合指标总的异常次数
dubbo_consumer_requests_failed_network_total	Total network Failed Requests	一般发生在网络连接失败或者网络通信时候发生的异常，对应Java异常为RemotingException
dubbo_consumer_requests_failed_network_total_aggregate	Total network Failed Requests	滑动窗口内的聚合指标一般发生在网络连接失败或者网络通信时候发生的异常，对应Java异常为RemotingException
dubbo_consumer_requests_failed_service_unavailable_total	Total Service Unavailable Failed Requests	当不存在提供者或者调用了被禁止访问提的提供者时候会出现此异常，对应异常码FORBIDDEN_EXCEPTION
dubbo_consumer_requests_failed_codec_total	Total codec failed	序列化相关的异常，异常码SERIALIZATION_EXCEPTION

ThreadPool Metrics

Metrics Name	Description	说明
dubbo_thread_pool_max_size	Thread Pool Max Size	线程池最大大小
dubbo_thread_pool_largest_size	Thread Pool Largest Size	线程池最大大小
dubbo_thread_pool_thread_count	Thread Pool Thread Count	线程池线程计数
dubbo_thread_pool_queue_size	Thread Pool Queue Size	线程池队列大小
dubbo_thread_pool_active_size	Thread Pool Active Size	线程池活动大小
dubbo_thread_pool_core_size	Thread Pool Core Size	线程池核心大小
dubbo_thread_pool_reject_thread_count	Thread Pool Reject Count	线程池拒绝执行任务数量

Registration Center Metrics

Metrics Name	Description	说明
dubbo_register_service_rt_milliseconds_avg	Average Service Register Time	接口级服务接口注册平均时间
dubbo_register_service_rt_milliseconds_last	Last Service Register Time	接口级服务接口注册最新响应时间
dubbo_register_service_rt_milliseconds_max	Max Service Register Time	接口级服务接口注册总的最大时间
dubbo_register_service_rt_milliseconds_min	Min Service Register Time	接口级服务接口注册总的最小时间
dubbo_register_service_rt_milliseconds_sum	Sum Service Register Time	接口级服务接口注册总的注册时间
dubbo_registry_directory_num_all	Total Directory Num	接口级服务接口目录总数
dubbo_registry_directory_num_disable_total	Total Disable Directory Num	接口级服务接口目录禁用总数
dubbo_registry_directory_num_to_reconnect_total	Total Directory Num To Reconnect	接口级服务接口目录重连总数
dubbo_registry_directory_num_valid_total	Total Valid Directory Num	接口级服务接口目录有效总数
dubbo_registry_notify_num_last	Last Notify Num	接口级服务接口通知最新响应时间
dubbo_registry_notify_requests_total	Total Notify Requests	接口级服务接口通知总次数
dubbo_register_rt_milliseconds_max	Max Response Time	应用级实例注册总的最大时间
dubbo_register_rt_milliseconds_avg	Average Response Time	应用级实例注册总的平均时间
dubbo_register_rt_milliseconds_sum	Sum Response Time	应用级实例注册总的注册时间
dubbo_register_rt_milliseconds_min	Min Response Time	应用级实例注册总的最小时间
dubbo_registry_register_requests_succeed_total	Succeed Register Requests	应用级实例注册成功的次数
dubbo_registry_register_requests_total	Total Register Requests	应用级实例注册总次数包含成功与失败
dubbo_registry_register_requests_failed_total	Failed Register Requests	应用级实例注册失败次数
dubbo_register_rt_milliseconds_last	Last Response Time	应用级实例注册最新响应时间
dubbo_registry_register_service_total	Total Service-Level Register Requests	接口级服务接口注册总数
dubbo_registry_register_service_succeed_total	Succeed Service-Level Register Requests	接口级服务接口注册成功总数
dubbo_registry_register_service_failed_total	Failed Service-Level Register Requests	接口级服务接口注册失败总数
dubbo_registry_subscribe_num_failed_total	Failed Subscribe Num	应用级实例订阅失败总数
dubbo_registry_subscribe_num_succeed_total	Succeed Subscribe Num	应用级实例订阅成功总数
dubbo_registry_subscribe_num_total	Total Subscribe Num	应用级实例订阅总数
dubbo_registry_subscribe_service_num_total	Total Service-Level Subscribe Num	接口级服务接口订阅总数
dubbo_registry_subscribe_service_num_succeed_total	Succeed Service-Level Num	接口级服务接口订阅成功总数
dubbo_registry_subscribe_service_num_failed_total	Failed Service-Level Num	接口级服务接口订阅失败总数
dubbo_notify_rt_milliseconds_avg	Average Notify Time	接口级服务接口通知总的平均时间
dubbo_notify_rt_milliseconds_last	Last Notify Time	接口级服务接口通知最新响应时间
dubbo_notify_rt_milliseconds_max	Max Notify Time	接口级服务接口通知总的最大时间
dubbo_notify_rt_milliseconds_min	Min Notify Time	接口级服务接口通知总的最小时间
dubbo_notify_rt_milliseconds_sum	Sum Notify Time	接口级服务接口通知总的通知时间

Metadata Center Metrics

部分元数据指标生效范围：当元数据为集中式配置时（report-metadata为true或者metadataType为remote）

部署 Istio 环境

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

1. 准备工作

docker、helm、kubectl 环境已安装。
dubbo-go cli 工具和依赖工具已安装

2. 部署 Istio 环境

使用helm 安装 istio 基础 CRD 和 istiod 组件。也可以参考 Istio 文档使用 istioctl 安装。

$ helm repo add istio https://istio-release.storage.googleapis.com/charts
$ kubectl create namespace istio-system
$ helm install istio-base istio/base -n istio-system
$ helm install istiod istio/istiod --namespace istio-system

删除istio 水平扩展资源

*目前 dubbo-go 依赖单个 istiod 实例进行服务发现。

$ kubectl delete hpa istiod -n istio-system

安装完成后，可以在 istio-system 命名空间下看到一个 istiod pod 在正常运行。

如何成为 Dubbo Committer

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

每个人都可以成为 Apache 项目的贡献者。作为一个贡献者只是意味着你对项目感兴趣并以某种方式做出贡献，从提出合理的问题（这些问题记录了项目并向开发人员提供反馈）到提供新的特性作为补丁。

如果你成为对一个项目有价值的贡献者，你有可能被邀请成为一个 Committer。Committer 是 ASF（Apache 软件基金会）中用来表示提交特定项目的人的术语。它给你带来对项目仓库和资源写的权限。

在 Dubbo 社区，如果一个 Committer 获得大量的优秀成绩，就可以被邀请加入项目管理委员会（PMC）。

当您不熟悉ASF使用的开源的开发过程时，有时难以理解的一点，就是我们更重视社区而不是代码。一个强大而健康的社区将受到尊重，成为一个有趣和有益的地方。更重要的是，一个多元化和健康的社区可以长时间的持续支持代码，即使个别公司在这个领域来来往往，也是如此。

更多详细信息可以在这里找到。

我可以贡献什么？

请参阅新的贡献者指南。

传统基于 Zookeeper、Nacos 的注册中心部署架构，部署 Dubbo 应用到虚拟机环境

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

下图是使用 Nacos、Zookeeper 作为注册中心的典型 Dubbo 微服务部署架构。

安装 Nacos

请参考以下文档了解如何在本地 安装 Nacos。

部署应用

我们仍然以 快速开始 中的项目为例，演示应用打包部署的具体步骤。

克隆示例项目到本地：

$ git clone -b master --depth 1 https://github.com/apache/dubbo-samples

切换到示例目录：

$ cd dubbo-samples/11-quickstart

以下是两种打包部署模式：

方式一：本地进程

本地打包进程：

$ mvn clean package

启动 Dubbo 进程：

$ java -jar ./quickstart-service/target/quickstart-service-0.0.1-SNAPSHOT.jar

提示

为了程序正常运行，请确保 application.yml 文件中的注册中心地址已经正确指向你想要的注册中心。

方式二：docker容器

$ docker build -f ./Dockerfile -t quickstart

$ docker run quickstart -p port1:port2
# 对于一些端口或连接注册中心的细节要写清楚

提示

Docker 容器环境下，不同容器间用于网络通信的地址需要特别关注，因此你可能需要设置 Dubbo 进程监听或者注册到注册中心的地址，请参考以下链接了解更多内容。

单端口多协议实现原理解析

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

通过对protocol进行配置，dubbo3可以支持端口的协议复用。比如使用Triple协议启动端口复用后，可以在相同的端口上为服务增加 Dubbo协议支持，以及Qos协议支持。这些协议的识别都是由一个统一的端口复用服务器进行处理的，可以用于服务的协议迁移，并且可以节约端口以及相关的资源，减少运维的复杂性。

在服务的创建阶段，通过从Config层获取到服务导出的协议配置从而创建不同的Protocol对象进行导出。在导出的过程中，如果不是第一次创建端口复用的Server，那么Exchanger会将Protcol层传递的数据保存到Server，用于后续处理该协议类型的消息。
当客户端的消息传递过来后，首先会通过Server传递给ProtocolDetector，如果完成了识别，那么就会标记该客户端为对应的协议。并通过WireProtocol配置对应的处理逻辑，最后交给ChannelOperator完成底层的IO框架和对应的Dubbo框架的处理逻辑的绑定。
以上的协议识别完成之后，Channel已经确定了如何处理远程的客户端消息，通过对应的ServerPipeline进行处理即可（在处理的过程中也会根据配置信息决定消息的处理线程）。

使用场景

最常用的是用于服务发现。这允许应用程序通过网络发现服务，然后使用同一端口与它们通信，有助于降低网络通信的复杂性，并使其更易于管理。
可以用于负载平衡。这允许应用程序在多个远程服务或服务集群之间平衡负载，有助于提高服务的可扩展性、可靠性和可用性。
可以用于服务监控。这允许应用程序监视远程服务的运行状况，并在服务出现故障或变得不可用时发出警报，有助于确保服务的可用性并减少停机时间。

参考用例 https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-port-unification

使用方式

在同一主机上部署多个服务或需要通过负载均衡器访问多个服务。

关于Dubbo支持的配置方式配置说明

服务多协议导出

ext-protocol参数支持配置多个不同的协议，协议之间通过",“进行分隔。

xml 配置

<dubbo:protocol name="dubbo" port="-1" ext-protocol="tri,"/>

<bean id="greetingService" class="org.apache.dubbo.demo.provider.GreetingServiceImpl"/>

<dubbo:service delay="5000" version="1.0.0" group="greeting" timeout="5000" interface="org.apache.dubbo.demo.GreetingService" ref="greetingService" protocol="dubbo"/>

API 配置

ProtocolConfig config = new ProtocolConfig(CommonConstants.TRIPLE, -1);

config.setExtProtocol(CommonConstants.DUBBO+",");

yaml 配置

dubbo:
 application:
 name: dubbo-springboot-demo-provider
 protocol:
 name: tri
 port: -1
 ext-protocol: dubbo,

properties 配置

dubbo.protocol.name=tri
dubbo.protocol.ext-protocol=dubbo,
dubbo.protocol.port=20880

Qos接入

Qos模块导入

<dependency>
 <groupId>org.apache.dubbo</groupId>
 <artifactId>dubbo-qos</artifactId>
</dependency>

完成Qos模块的导入之后，相关的配置项可参考Qos操作手册进行配置。

地址同步

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

遵循以下步骤，可以轻松掌握如何开发符合 Service Mesh 架构的 Dubbo 服务，并将其部署到 Kubernetes 并接入 Istio 的流量治理体系。在此查看完整示例源码

1 总体目标

部署 Dubbo 应用到 Kubernetes
Istio 自动注入 Envoy 并实现流量拦截
基于 Istio 规则进行流量治理

2 基本流程与工作原理

这个示例演示了如何将 Dubbo 开发的应用部署在 Istio 体系下，以实现 Envoy 对 Dubbo 服务的自动代理，示例总体架构如下图所示。

完成示例将需要的步骤如下：

创建一个 Dubbo 应用( dubbo-samples-mesh-k8s )
构建容器镜像并推送到镜像仓库（本示例官方镜像）
分别部署 Dubbo Provider 与 Dubbo Consumer 到 Kubernetes 并验证 Envoy 代理注入成功
验证 Envoy 发现服务地址、正常拦截 RPC 流量并实现负载均衡
基于 Istio VirtualService 实现按比例流量转发

3 详细步骤

3.1 环境要求

请确保本地安装如下环境，以提供容器运行时、Kubernetes集群及访问工具

通过以下命令启动本地 Kubernetes 集群

多实例部署的设计理念

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

背景

Java 提供的静态变量（static field）能力可以将持有对象引用的行为绑定到类上面来，这给开发者提供了巨大的便利。注入单例模式、工厂模式等设计模式的实现方案都依赖了静态变量的功能。通过使用静态变量，开发者可以在任何时间、任何地点简单地获取到所需要的对象信息。

public class Test {
 public static Object obj;
}
Test.obj = xxx;

在一直以来的 Dubbo 框架开发中，静态变量受到了广泛地应用，诸如使用一个全局共享的 ConfigManager 来存储全局配置信息、ServiceRepository 来存储服务信息，不论从中心化管理配置或者是参数获取的便利性的角度来说，这种设计都是最佳的。在 Dubbo 2.7 以前的所有版本，Dubbo 所需要的运行时配置信息都通过全局静态变量获取，通过 RPC 服务三元组（interface + version + group）的方式进行唯一定位。

但是随着 Dubbo 用户基数的不断扩大以及在阿里集团内由 Dubbo 作为内核的 HSF3 框架都对原来的这种设计模式提出了挑战。

对于开源用户，社区收到的诉求主要包括以下几点：

在同一个应用内能够创建多个三元组一样的订阅。这个行为在 Dubbo 2.7 中虽然没有做强限制，但是由于 Dubbo 很多参数是取自全局的，而这个获取的索引使用的就是三元组。如果用户创建了两个三元组一样的订阅，他们的参数会被相互覆盖，地址推送等功能也会收到很大的影响。
Java 提供了自定义 ClassLoader 的机制可以自定义指定类的加载器来源，但是对于 Dubbo 来说并没有去支持多 ClassLoader 的场景，在动态代理生成和序列化场景下都不支持 ClassLoader 切换的行为。
Dubbo 众多的测试用例都共享了同一份配置信息，导致在进行单元测试的时候极为容易造成环境污染的问题。

对于阿里集团内大规模落地来说，我们遇到的问题主要有：

阿里集团内有众多的中间件框架，这些框架提供了各种各样的类加载方式，同时业务方期望在同一应用内的配置等信息是相互隔离的。
一些业务方的定制逻辑需要支持动态热部署的模式，具体体现在动态对某个虚拟环境进行销毁，这需要 Dubbo 内的生命周期管理更加完善。
集团内有多个对 Spring 容器进行定制化开发的框架，需要 Dubbo 能够支持多个 Spring Context 独立管理生命周期的场景。

基于众多的这些原因，在八月初的时候我们决定对 Dubbo 的生命周期进行重构，经过一个月的紧张开发，目前社区版本已经完整支持了多实例化的功能，Dubbo 的生命周期也变得更加清晰。

泛化实现

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

注意

请注意区分上一篇文档介绍的泛化调用，泛化调用是给消费端用的，而泛化实现是给提供端用的。

泛接口实现方式主要用于服务器端没有 API 接口及模型类元的情况，参数及返回值中的所有 POJO 均用 Map 表示，通常用于框架集成，比如：实现一个通用的远程服务 Mock 框架，可通过实现 GenericService 接口处理所有服务请求。

使用场景

注册服务: 服务提供者在服务注册表中注册服务，例如 Zookeeper，服务注册表存储有关服务的信息，例如其接口、实现类和地址。
部署服务: 服务提供商将服务部署在服务器并使其对消费者可用。
调用服务: 使用者使用服务注册表生成的代理调用服务，代理将请求转发给服务提供商，服务提供商执行服务并将响应发送回消费者。
监视服务：提供者和使用者可以使用 Dubbo 框架监视服务，允许他们查看服务的执行情况，并在必要时进行调整。

使用方式

本示例的完整源码请参考 dubbo-samples-generic-impl。

在 Java 代码中实现 GenericService 接口

package com.foo;
public class MyGenericService implements GenericService {

 public Object $invoke(String methodName, String[] parameterTypes, Object[] args) throws GenericException {
 if ("sayHello".equals(methodName)) {
 return "Welcome " + args[0];
 }
 }
}

通过 Spring 暴露泛化实现

在 Spring XML 配置申明服务的实现

<bean id="genericService" class="com.foo.MyGenericService" />
<dubbo:service interface="com.foo.BarService" ref="genericService" />

通过 API 方式暴露泛化实现

...
// 用org.apache.dubbo.rpc.service.GenericService可以替代所有接口实现
GenericService xxxService = new XxxGenericService();

// 该实例很重量，里面封装了所有与注册中心及服务提供方连接，请缓存
ServiceConfig<GenericService> service = new ServiceConfig<GenericService>();
// 弱类型接口名
service.setInterface("com.xxx.XxxService");
// if you need to set different version for service
service.setVersion("1.0.0");
// 指向一个通用服务实现
service.setRef(xxxService);

// 暴露及注册服务
service.export();

在设置 ServiceConfig 时，使用setGeneric("true")来开启泛化调用
在设置 ServiceConfig 时，使用 setRef 指定实现类时，要设置一个 GenericService 的对象。而不是真正的服务实现类对象
其他设置与正常 Api 服务启动一致即可

服务发现

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

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

服务发现，即消费端自动发现服务地址列表的能力，是微服务框架需要具备的关键能力，借助于自动化的服务发现，微服务之间可以在无需感知对端部署位置与 IP 地址的情况下实现通信。

实现服务发现的方式有很多种，Dubbo 提供的是一种 Client-Based 的服务发现机制，通常还需要部署额外的第三方注册中心组件来协调服务发现过程，如常用的 Nacos、Consul、Zookeeper 等，Dubbo 自身也提供了对多种注册中心组件的对接，用户可以灵活选择。

Dubbo 基于消费端的自动服务发现能力，其基本工作原理如下图：

服务发现的一个核心组件是注册中心，Provider 注册地址到注册中心，Consumer 从注册中心读取和订阅 Provider 地址列表。因此，要启用服务发现，需要为 Dubbo 增加注册中心配置：

以 dubbo-spring-boot-starter 使用方式为例，增加 registry 配置

# application.properties
dubbo
 registry
 address: zookeeper://127.0.0.1:2181

What’s New in Dubbo3

就使用方式上而言，Dubbo3 与 Dubbo2 的服务发现配置是完全一致的，不需要改动什么内容。但就实现原理上而言，Dubbo3 引入了全新的服务发现模型 - 应用级服务发现，在工作原理、数据格式上已完全不能兼容老版本服务发现。

Dubbo3 应用级服务发现，以应用粒度组织地址数据
Dubbo2 接口级服务发现，以接口粒度组织地址数据

Dubbo3 格式的 Provider 地址不能被 Dubbo2 的 Consumer 识别到，反之 Dubbo2 的消费者也不能订阅到 Dubbo3 Provider。

对于新用户，我们提倡直接启用 Dubbo3 的默认行为，即启用应用级服务发现，参见《应用级服务发现》；
对于老用户，要面临如何平滑迁移到应用级服务发现的问题，考虑到老用户的规模如此之大，Dubbo3 默认保持了接口级地址发现的行为，这保证了老用户可以直接无感升级到 Dubbo3。而如果要开启应用级服务发现，则需要通过配置显示开启（双注册、双订阅），具体开启与平滑迁移过程，可参见《地址发现迁移指南》。

应用级服务发现简介

概括来说，Dubbo3 引入的应用级服务发现主要有以下优势

服务发现的工作方式、基本使用方法与配置细节

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

Dubbo 支持基于注册中心的自动实例发现机制，即 Dubbo 提供者注册实例地址到注册中心，Dubbo 消费者通过订阅注册中心变更事件自动获取最新实例变化，从而确保流量始终转发到正确的节点之上。Dubbo 目前支持 Nacos、Zookeeper、Kubernetes Service 等多种注册中心接入。

注册中心

以下是 Dubbo 服务发现接入的一些主流注册中心实现，更多扩展实现与工作原理请查看注册中心参考手册：

注册中心	配置值	服务发现模型	是否支持鉴权	spring-boot-starter
Nacos	nacos	应用级、接口级	是	dubbo-nacos-spring-boot-starter
Zookeeper	zookeeper	应用级、接口级	是	- dubbo-zookeeper-spring-boot-starter - dubbo-zookeeper-curator5-spring-boot-starter
Kubernetes Service	参考独立使用文档	应用级	是	无

延迟注册

如果你的服务需要预热时间，比如初始化缓存、等待相关资源就位等，可以使用 delay 参数进行延迟注册。如果是在 Spring 应用中，则 delay = n(n > 0) 延迟的时间是 Spring 上下文初始化完成后开始算起。

@DubboService(delay = 5000)
public class DemoServiceImpl implements DemoService {
}

以上配置后，应用将延迟 5 秒暴露此服务（应用启动 5s 后发布该服务到注册中心）。或者可以配置全局默认值，让所有服务都延迟 5s 后注册：

dubbo:
 provider:
 delay: 5000

手动注册

通过配置 delay = -1，可以禁止框架自动发布服务到注册中心，直到用户通过调用 online 等命令手动完成发布，可以用这个特性配合部署系统实现服务的优雅上线，让用户对上线时机有更好的控制。具体配置如下：

服务路由

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

1. 简介

上一篇文章分析了集群容错的第一部分 — 服务目录 Directory。服务目录在刷新 Invoker 列表的过程中，会通过 Router 进行服务路由，筛选出符合路由规则的服务提供者。在详细分析服务路由的源码之前，先来介绍一下服务路由是什么。服务路由包含一条路由规则，路由规则决定了服务消费者的调用目标，即规定了服务消费者可调用哪些服务提供者。Dubbo 目前提供了三种服务路由实现，分别为条件路由 ConditionRouter、脚本路由 ScriptRouter 和标签路由 TagRouter。其中条件路由是我们最常使用的，标签路由是一个新的实现，暂时还未发布，该实现预计会在 2.7.x 版本中发布。本篇文章将分析条件路由相关源码，脚本路由和标签路由这里就不分析了。

2. 源码分析

条件路由规则由两个条件组成，分别用于对服务消费者和提供者进行匹配。比如有这样一条规则：

host = 10.20.153.10 => host = 10.20.153.11

该条规则表示 IP 为 10.20.153.10 的服务消费者只可调用 IP 为 10.20.153.11 机器上的服务，不可调用其他机器上的服务。条件路由规则的格式如下：

[服务消费者匹配条件] => [服务提供者匹配条件]

如果服务消费者匹配条件为空，表示不对服务消费者进行限制。如果服务提供者匹配条件为空，表示对某些服务消费者禁用服务。官方文档中对条件路由进行了比较详细的介绍，大家可以参考下，这里就不过多说明了。

条件路由实现类 ConditionRouter 在进行工作前，需要先对用户配置的路由规则进行解析，得到一系列的条件。然后再根据这些条件对服务进行路由。本章将分两节进行说明，2.1节介绍表达式解析过程。2.2 节介绍服务路由的过程。下面，我们先从表达式解析过程看起。

2.1 表达式解析

条件路由规则是一条字符串，对于 Dubbo 来说，它并不能直接理解字符串的意思，需要将其解析成内部格式才行。条件表达式的解析过程始于 ConditionRouter 的构造方法，下面一起看一下：

public ConditionRouter(URL url) {
 this.url = url;
 // 获取 priority 和 force 配置
 this.priority = url.getParameter(Constants.PRIORITY_KEY, 0);
 this.force = url.getParameter(Constants.FORCE_KEY, false);
 try {
 // 获取路由规则
 String rule = url.getParameterAndDecoded(Constants.RULE_KEY);
 if (rule == null || rule.trim().length() == 0) {
 throw new IllegalArgumentException("Illegal route rule!");
 }
 rule = rule.replace("consumer.", "").replace("provider.", "");
 // 定位 => 分隔符
 int i = rule.indexOf("=>");
 // 分别获取服务消费者和提供者匹配规则
 String whenRule = i < 0 ? null : rule.substring(0, i).trim();
 String thenRule = i < 0 ? rule.trim() : rule.substring(i + 2).trim();
 // 解析服务消费者匹配规则
 Map<String, MatchPair> when = 
 StringUtils.isBlank(whenRule) || "true".equals(whenRule) 
 ? new HashMap<String, MatchPair>() : parseRule(whenRule);
 // 解析服务提供者匹配规则
 Map<String, MatchPair> then = 
 StringUtils.isBlank(thenRule) || "false".equals(thenRule) 
 ? null : parseRule(thenRule);
 // 将解析出的匹配规则分别赋值给 whenCondition 和 thenCondition 成员变量
 this.whenCondition = when;
 this.thenCondition = then;
 } catch (ParseException e) {
 throw new IllegalStateException(e.getMessage(), e);
 }
}

如上，ConditionRouter 构造方法先是对路由规则做预处理，然后调用 parseRule 方法分别对服务提供者和消费者规则进行解析，最后将解析结果赋值给 whenCondition 和 thenCondition 成员变量。ConditionRouter 构造方法不是很复杂，这里就不多说了。下面我们把重点放在 parseRule 方法上，在详细介绍这个方法之前，我们先来看一个内部类。

服务重试

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

背景

Dubbo 服务在尝试调用一次之后，如出现非业务异常(服务突然不可用、超时等)，Dubbo 默认会进行额外的最多2次重试.

重试次数支持两种自定义配置: 1.通过注解/xml进行固定配置；2.通过上下文进行运行时动态配置

示例

通过注解/xml进行固定配置

<dubbo:consumer retries="2"></dubbo:consumer>

通过RpcContext进行运行时动态配置，优先级高于注解/xml进行的固定配置(两者都配置的情况下，以RpcContext配置为准).

// dubbo服务调用前，通过RpcContext动态设置本次调用的重试次数
RpcContext rpcContext = RpcContext.getContext();
rpcContext.setAttachment("retries", 5);

负载均衡策略与配置细节

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

Dubbo-go 内置了 client-based 负载均衡机制，如下是当前支持的负载均衡算法，结合上文提到的自动服务发现机制，消费端会自动使用 Weighted Random LoadBalance 加权随机负载均衡策略 选址调用。

如果要调整负载均衡算法，以下是 Dubbo 框架内置的负载均衡策略：

算法	特性	备注	配置值
Weighted Random LoadBalance	加权随机	默认算法，默认权重相同	random (默认)
RoundRobin LoadBalance	加权轮询	借鉴于 Nginx 的平滑加权轮询算法，默认权重相同	roundrobin
LeastActive LoadBalance	最少活跃优先 + 加权随机	背后是能者多劳的思想	leastactive
Consistent Hash LoadBalance	一致性哈希	确定的入参，确定的提供者，适用于有状态请求	consistenthashing
P2C LoadBalance	Power of Two Choice	随机选择两个节点后，继续选择“连接数”较小的那个节点。	p2c
Interleaved Weighted Round Robin	一种加权轮训算法	https://en.wikipedia.org/wiki/Weighted_round_robin#Interleaved_WRR	interleavedweightedroundrobin
Alias Method Round Robin		https://en.wikipedia.org/wiki/Alias_method	aliasmethod

全局配置

Dubbo 框架的默认策略是 random 加权随机负载均衡。如果要调整策略，只需要设置 loadbalance 相应取值即可，每种负载均衡策略取值请参见文档最上方表格。

负载均衡策略与配置细节

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

Dubbo 内置了 client-based 负载均衡机制，如下是当前支持的负载均衡算法，结合上文提到的自动服务发现机制，消费端会自动使用 Weighted Random LoadBalance 加权随机负载均衡策略 选址调用。

如果要调整负载均衡算法，以下是 Dubbo 框架内置的负载均衡策略：

算法	特性	备注	配置值
Weighted Random LoadBalance	加权随机	默认算法，默认权重相同	random (默认)
RoundRobin LoadBalance	加权轮询	借鉴于 Nginx 的平滑加权轮询算法，默认权重相同	roundrobin
LeastActive LoadBalance	最少活跃优先 + 加权随机	背后是能者多劳的思想	leastactive
Shortest-Response LoadBalance	最短响应优先 + 加权随机	更加关注响应速度	shortestresponse
ConsistentHash LoadBalance	一致性哈希	确定的入参，确定的提供者，适用于有状态请求	consistenthash
P2C LoadBalance	Power of Two Choice	随机选择两个节点后，继续选择“连接数”较小的那个节点。	p2c
Adaptive LoadBalance	自适应负载均衡	在 P2C 算法基础上，选择二者中 load 最小的那个节点	adaptive

全局配置

了解 Dubbo 核心概念和架构

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

以上是 Dubbo 的工作原理图，从抽象架构上分为两层：服务治理抽象控制面 和 Dubbo 数据面 。

服务治理控制面。服务治理控制面不是特指如注册中心类的单个具体组件，而是对 Dubbo 治理体系的抽象表达。控制面包含协调服务发现的注册中心、流量管控策略、Dubbo Admin 控制台等，如果采用了 Service Mesh 架构则还包含 Istio 等服务网格控制面。
Dubbo 数据面。数据面代表集群部署的所有 Dubbo 进程，进程之间通过 RPC 协议实现数据交换，Dubbo 定义了微服务应用开发与调用规范并负责完成数据传输的编解码工作。
- 服务消费者 (Dubbo Consumer)，发起业务调用或 RPC 通信的 Dubbo 进程
- 服务提供者 (Dubbo Provider)，接收业务调用或 RPC 通信的 Dubbo 进程

Dubbo 数据面

从数据面视角，Dubbo 帮助解决了微服务实践中的以下问题：

Dubbo 作为 服务开发框架 约束了微服务定义、开发与调用的规范，定义了服务治理流程及适配模式
Dubbo 作为 RPC 通信协议实现 解决服务间数据传输的编解码问题

服务开发框架

微服务的目标是构建足够小的、自包含的、独立演进的、可以随时部署运行的分布式应用程序，几乎每个语言都有类似的应用开发框架来帮助开发者快速构建此类微服务应用，比如 Java 微服务体系的 Spring Boot，它帮 Java 微服务开发者以最少的配置、最轻量的方式快速开发、打包、部署与运行应用。

微服务的分布式特性，使得应用间的依赖、网络交互、数据传输变得更频繁，因此不同的应用需要定义、暴露或调用 RPC 服务，那么这些 RPC 服务如何定义、如何与应用开发框架结合、服务调用行为如何控制？这就是 Dubbo 服务开发框架的含义，Dubbo 在微服务应用开发框架之上抽象了一套 RPC 服务定义、暴露、调用与治理的编程范式，比如 Dubbo Java 作为服务开发框架，当运行在 Spring 体系时就是构建在 Spring Boot 应用开发框架之上的微服务开发框架，并在此之上抽象了一套 RPC 服务定义、暴露、调用与治理的编程范式。

管理控制台安装

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

目前版本的管理控制台正在开发中，已经完成了服务查询和服务治理的功能，采用前后端分离的模式，具体的安装和使用步骤如下：

安装:

git clone https://github.com/apache/dubbo-admin.git /var/tmp/dubbo-admin
cd /var/tmp/dubbo-admin
mvn clean package

配置 ¹:

配置文件为：
dubbo-admin-server/src/main/resources/application.properties
主要的配置有：
admin.registry.address=zookeeper://127.0.0.1:2181
admin.config-center=zookeeper://127.0.0.1:2181
admin.metadata-report.address=zookeeper://127.0.0.1:2181

启动:

mvn --projects dubbo-admin-server spring-boot:run

其他配置请访问 github 中的文档:

https://github.com/apache/dubbo-admin

访问:

http://127.0.0.1:8080

当前版本中未实现登录功能，会在后续版本加上 ↩︎

管理控制台运维

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

搜索页面

当你需要管理 Dubbo 的服务时，首先要搜索到这个服务，然后打开它的管理页面

服务提供者页面

服务消费者页面

添加路由规则页面

添加动态配置页面

前端 http 流量接入 Dubbo 后端微服务体系的基础架构

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

不论你开发的是什么样的产品（电子商城、管理系统、手机 app 等），绝大多数下产品的流量入口都会是 http，用户可能通过浏览器、手机移动设备、桌面软件等来访问产品。在这种情况下，如何将后端开发的 Dubbo 微服务集群接入前端访问设备就成为一个需要解决的问题，其实也就是 http 与 rpc 之间的转换与连接问题。

总的来说，有中心化和去中心化两种架构模式。其中，中心化接入模式更具通用性，对后端 rpc 协议、前端网关没有太多特殊要求，但保证中心化应用的性能、稳定性是一个较大的挑战；去中心化模式由于不需要维护入口应用，因此可适应更大流量、更大规模的集群。

中心化接入方式

中心化接入方式的架构图如下：

在后端服务与前端设备之间有一层网关，负责流量过滤、路由、限流等流量管理工作
在后端集群中有一个连接 http 与 dubbo 服务的 “统一微服务入口应用”（通常也叫做 BFF，即Backend for Frontend）。

BFF 应用通常可以使用 Spring Web 等常用框架开发，应用发布一系列的 http 服务，接收网关或前端设备流量，同时负责按需发起 dubbo 调用。

注意

dubbo、triple 协议都支持这种接入架构。另外，在配置 BFF 应用调用 dubbo 服务时，可以使用普通的 dubbo 配置方式，也可以使用泛化调用等方式：

配置接入 dubbo 协议时，使用 泛化调用 的优势是可以避免对服务二进制包的依赖，实现配置动态生效的效果。
配置接入 triple 协议时，可以使用 http 调用方式，同样可避免对服务二进制包的依赖，实现配置动态生效的效果。

去中心化接入方式

与中心化架构相比，此方式并没有太大的差异，唯一的区别在于不需要额外的 BFF 应用，我们可以在网关直接调用后端 dubbo 服务。

但这种方式对网关有特别要求。如果后端是 dubbo 协议的话，则要求网关具备 http -> dubbo 协议转换的能力，但你会在接下来的文档中发现，我们可以通过多协议发布绕过协议转换，让网关直接通过 http 访问后端服务；如果后端是 triple 协议，就会更简单了，因为 triple 协议支持 application/json 格式的 http 请求。

基准测试

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

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

1 Benchmark 结论

对比 2.x 版本，Dubbo3 版本

服务发现资源利用率显著提升。
- 对比接口级服务发现，单机常驻内存下降 50%，地址变更期 GC 消耗下降一个数量级 (百次 -> 十次)
- 对比应用级服务发现，单机常驻内存下降 75%，GC 次数趋零
Dubbo 协议性能持平，Triple 协议在网关、Stream吞吐量方面更具优势。
- Dubbo协议（3.0 vs 2.x），3.0 实现较 2.x 总体 qps rt 持平，略有提升
- Triple协议 vs Dubbo协议，直连调用场景 Triple 性能并无优势，其优势在网关、Stream调用场景。

以下是详细压测过程与数据

2 应用级服务发现（地址推送链路）

此部分压测数据是由工商银行 Dubbo 团队基于内部生产数据给出，压测过程模拟了“生产环境地址+zookeeper”的服务发现架构。

2.1 环境

	描述
压测数据	提供者 500运行实例✖️8interface✖️5protocol，即每个提供者向注册中心注册40个URL，总计20000个URL，每个URL字符长度约1k。注册中心 2个独立zookeeper注册中心，服务提供者消费者采用并行配置。消费者配置1c2g，xmx=768，开启GC，从2个注册中心订阅，每5秒调用一次服务。运行20小时。
压测环境	Java version “1.8.0” Java(TM) SE Runtime Enviroment (build pxa6480sr3fp12-20160919_01(SR3 FP12)) IBM J9 VM (Build 2.8, JRE 1.8.0 Linux amd64-64 Compressed References 20160915_318796, JIT enabled, AOT enabled)

2.2 数据分析

Admin 整体架构与安装步骤

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

回顾 Dubbo 服务治理体系的总体架构，Admin 是服务治理控制面中的一个核心组件，负责微服务集群的服务治理、可视化展示等。

Admin 部署架构

总体上来说，Admin 部署架构分为以下几个部分：

Admin 主进程，包括服务发现元数据管理、可视化控制台、安全认证策略管控、其他定制化服务治理能力等组件。
强依赖组件，包括 Mysql 数据库、注册/配置/元数据中心（可以是 Kubernetes、Nacos、Zookeeper 等）
可选依赖组件，包括 Prometheus、Grafana、Zipkin 等

安装 Admin

Dubboctl 安装

Download

当前Dubboctl未正式发行，可按以下方式进行尝试。拉取Dubbo Admin并编译Dubboctl

git clone https://github.com/apache/dubbo-admin.git
cd dubbo-admin/cmd/dubboctl
go build -o dubboctl .

将 dubboctl 放入可执行路径

ln -s dubbo-admin/cmd/dubboctl/dubboctl /usr/local/bin/dubboctl

Install

安装过程会依次：

将用户自定义的配置profile以及set参数覆盖于默认profile，得到最终的profile

# default profile
apiVersion: dubbo.apache.org/v1alpha1
kind: DubboOperator
metadata:
 namespace: dubbo-system
spec:
 profile: default
 namespace: dubbo-system
 componentsMeta:
 admin:
 enabled: true
 grafana:
 enabled: true
 repoURL: https://grafana.github.io/helm-charts
 version: 6.52.4
 nacos:
 enabled: true
 zookeeper:
 enabled: true
 repoURL: https://charts.bitnami.com/bitnami
 version: 11.1.6
 prometheus:
 enabled: true
 repoURL: https://prometheus-community.github.io/helm-charts
 version: 20.0.2
 skywalking:
 enabled: true
 repoURL: https://apache.jfrog.io/artifactory/skywalking-helm
 version: 4.3.0
 zipkin:
 enabled: true
 repoURL: https://openzipkin.github.io/zipkin
 version: 0.3.0

建议使用自定义profile进行配置，在componentsMeta中开启或关闭组件，在components下配置各组件。其中components下各组件的配置值都是helm chart的values，各组件的具体配置请参考： Grafana: https://github.com/grafana/helm-charts/blob/main/charts/grafana/README.md Zookeeper: https://github.com/bitnami/charts/tree/main/bitnami/zookeeper/#installing-the-chart Prometheus: https://github.com/prometheus-community/helm-charts/tree/main/charts Skywalking: https://github.com/apache/skywalking-kubernetes/blob/master/chart/skywalking/README.md Zipkin: https://github.com/openzipkin/zipkin-helm

Dubbo3 简介

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

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

Apache Dubbo 是一款微服务开发框架，它提供了 RPC通信与微服务治理两大关键能力。这意味着，使用 Dubbo 开发的微服务，将具备相互之间的远程发现与通信能力，同时利用 Dubbo 提供的丰富服务治理能力，可以实现诸如服务发现、负载均衡、流量调度等服务治理诉求。同时 Dubbo 是高度可扩展的，用户几乎可以在任意功能点去定制自己的实现，以改变框架的默认行为来满足自己的业务需求。

Dubbo3 基于 Dubbo2 演进而来，在保持原有核心功能特性的同时， Dubbo3 在易用性、超大规模微服务实践、云原生基础设施适配、安全设计等几大方向上进行了全面升级。以下文档都将基于 Dubbo3 展开。

What Dubbo3 is

如开篇所述，Dubbo 提供了构建云原生微服务业务的一站式解决方案，可以使用 Dubbo 快速定义并发布微服务组件，同时基于 Dubbo 开箱即用的丰富特性及超强的扩展能力，构建运维整个微服务体系所需的各项服务治理能力，如 Tracing、Transaction 等，Dubbo 提供的基础能力包括：

服务发现
流式通信
负载均衡
流量治理
…..

Dubbo 计划提供丰富的多语言客户端实现，其中 Java、Golang 版本是当前稳定性、活跃度最好的版本，其他多语言客户端正在持续建设中。

自开源以来，Dubbo 就被一众大规模互联网、IT公司选型，经过多年企业实践积累了大量经验。Dubbo3 是站在巨人肩膀上的下一代产品，它汲取了上一代的优点并针对已知问题做了大量优化，因此，Dubbo 在解决业务落地与规模化实践方面有着无可比拟的优势：

开箱即用
- 易用性高，如 Java 版本的面向接口代理特性能实现本地透明调用
- 功能丰富，基于原生库或轻量扩展即可实现绝大多数的微服务治理能力
超大规模微服务集群实践
- 高性能的跨进程通信协议
- 地址发现、流量治理层面，轻松支持百万规模集群实例
企业级微服务治理能力
- 服务测试
- 服务Mock

Dubbo3 是在云原生背景下诞生的，使用 Dubbo 构建的微服务遵循云原生思想，能更好的复用底层云原生基础设施、贴合云原生微服务架构。这体现在：

服务支持部署在容器、Kubernetes平台，服务生命周期可实现与平台调度周期对齐；
支持经典 Service Mesh 微服务架构，引入了 Proxyless Mesh 架构，进一步简化 Mesh 的落地与迁移成本，提供更灵活的选择；
作为桥接层，支持与 SpringCloud、gRPC 等异构微服务体系的互调互通

一站式微服务解决方案

Dubbo 提供了从服务定义、服务发现、服务通信到流量管控等几乎所有的服务治理能力，并且尝试从使用上对用户屏蔽底层细节，以提供更好的易用性。

脚本路由

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

使用方法

前置准备

Docker 以及 Docker compose 环境来部署Nacos配置中心。
Nacos 2.x+
Go 1.23+

启动Nacos配置中心

参考这个教程来启动Nacos。

Script router 介绍

Script router与condition router类似，都提供了使用表达式进行流量管控的功能。但是Script router具有更强大的匹配功能，与此同时带来的是匹配消耗的资源更多，因此在生产环境中应当尽量少使用。

Script router的示例代码与Condition router类似，在nacos配置上略有差别，这里仅提供nacos上的简单配置。

scope: "application"
key: "script-server"
enabled: true
type: "javascript"
script: |
 (function(invokers, invocation, context) {
 if (!invokers || invokers.length === 0) return [];
 return invokers.filter(function(invoker) {
 var url = invoker.GetURL();
 return url && url.Port === "20000";
 });
 })(invokers, invocation, context);

参数说明:

参数	说明
type	script的类型，目前仅可使用js
script	script实际内容

完整示例请见: 本示例完整代码。

接入 Ingress 流量

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

1. 准备工作

kubectl
一个 k8s 集群，配置好 kubeconfig

2. 使用 HTTP 协议通过网关调用 Triple 应用

Dubbo-go-pixiu 网关支持调用 GO/Java 的 Dubbo 集群。在 Dubbo-go 3.0 的场景下，我们可以通过 Pixiu 网关，在集群外以 HTTP 协议请求 pixiu 网关，在网关层进行协议转换，进一步调用集群内的Dubbo-go 服务。

用户调用 Dubbo-go 服务的 path 为http://$(app_name)/$(service_name)/$(method)。

例如一个proto文件内有如下定义：

package org.apache.dubbo.quickstart.samples;

service UserProvider {
 rpc SayHello (HelloRequest) returns (User) {}
}

message HelloRequest {
 string name = 1;
}

并在dubbo-go 服务启动时在dubbogo.yml 内配置应用名为my-dubbogo-app:

dubbo:
 application:
 name: my-dubbogo-app

pixiu 网关即可解析 path 为 my-dubbogo-app/org.apache.dubbo.quickstart.samples.UserProvider/SayHello 的路由，并转发至对应服务。来自外部HTTP 请求的 body 为 json 序列化的请求参数，例如 {“name”:“test”}。

开发 RPC Server & RPC Client

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

基于 Dubbo 定义的 Triple 协议，你可以轻松编写浏览器、gRPC 兼容的 RPC 服务，并让这些服务同时运行在 HTTP/1 和 HTTP/2 上。Dubbo Go SDK 支持使用 IDL 或编程语言特有的方式定义服务，并提供一套轻量的 API 来发布或调用这些服务。

本示例演示了基于 Triple 协议的 RPC 通信模式，示例使用 Protocol Buffer 定义 RPC 服务，并演示了代码生成、服务发布和服务访问等过程。

前置条件

因为使用 Protocol Buffer 的原因，我们首先需要安装相关的代码生成工具，这包括 protoc、protoc-gen-go、protoc-gen-go-triple。

安装 protoc

查看 Protocol Buffer Compiler 安装指南

安装 protoc 插件

接下来，我们安装插件 protoc-gen-go、protoc-gen-go-triple。

go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install github.com/dubbogo/protoc-gen-go-triple/v3@v3.0.3

确保 protoc-gen-go、protoc-gen-go-triple 在你的 PATH 中。这可以通过 which protoc-gen-go 验证，如果该命令不能正常工作的话，请执行以下命令：

[ -n "$(go env GOBIN)" ] && export PATH="$(go env GOBIN):${PATH}"
[ -n "$(go env GOPATH)" ] && export PATH="$(go env GOPATH)/bin:${PATH}"

快速运行示例

下载示例源码

我们在 apache/dubbo-go-samples 仓库维护了一系列 dubbo-go 使用示例，用来帮助用户快速学习 dubbo-go 使用方式。

可观测性

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

管理 Dubbo 最直接的方式就是通过 Dubbo 控制面（即 dubbo-control-plane）提供的可视化界面，之前我们在【快速开始 - 部署 Dubbo 应用】一文的最后，也有用到它查看服务启动后的状态。

dubbo-control-plane 支持可视化的展示、监控集群状态，还支持实时下发流量管控规则。

安装控制台

为了体验效果，我们首先需要安装 dubbo-control-plane，以下是在 Linux 环境下安装 dubbo-control-plane 的具体步骤：

下载 & 解压

curl -L https://dubbo.apache.org/releases/downloadDubbo.sh | sh -

cd dubbo-$version
export PATH=$PWD/bin:$PATH

安装
```
dubbo-cp run --mode universal --config conf/dubbo.yml
```
注意，conf/dubbo.yml 配置需要按需调整，指向你要连接的注册中心等后台服务，具体请查看 dubbo-control-plane 架构中依赖的后台服务。
访问 http://xxx 即可打开控制台页面。 页面截图

注意

请查看文档了解 dubbo-control-plane 详细安装步骤，包括多个平台的安装方法与配置指导。
对于 Kubernetes 环境下的 Dubbo 服务开发（包括 dubbo-control-plane 安装），我们有专门的章节说明，对于 Kubernetes 环境下的开发者可以去参考。

功能介绍

Admin 控制台提供了从开发、测试到流量治理等不同层面的丰富功能，功能总体上可分为以下几类：

服务状态与依赖关系查询
服务在线测试与文档管理
集群状态监控
实例诊断
流量管控

服务状态与依赖关系查询

服务状态查询以接口为维度展示 dubbo 集群信息，包含服务提供者、消费者信息和服务的元数据等。元数据包含了服务定义、方法名和参数列表等信息。Admin 支持最新版本 dubbo3 所提供的应用级发现模型，以统一的页面交互展示了应用级&接口级地址信息，并以特殊的标记对记录进行区分。

快速开始

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

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

建议先使用 java 定义接口 jar，并使用 erlanalysis 工具解析java接口至Erlang lib

导入依赖库

使用 Rebar 编译工具。

Add dubblerl to rebar.config with your project

{deps, [
 {dubboerl, {git, "https://github.com/apache/dubbo-erlang.git", {branch, "master"}}}
]}.

使用 erlang.mk 编译工具

待补充

导入接口库

Suppose the interface lib you exported is called dubbo_service.

If you didn’t upload your lib to your git repository, It is recommended that you copy the dubbo_service lib into the project’s apps directory.
If it is upload to your git repository, you can import like this:

{deps, [
 {dubboerl, {git, "https://github.com/apache/dubbo-erlang.git", {branch, "master"}}},
 {dubbo_service,{git,"${INTERFACE_LIB_URL}",{branch,"master"}}} %% replace ${INTERFACE_LIB_URL} with your lib git repos url
]}.

消费者配置

Please reference Reference Config

快速开始

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

建议先使用 java 定义接口 jar，并使用 erlanalysis 工具解析java接口至Erlang lib

导入依赖库

使用 Rebar 编译工具。

Add dubblerl to rebar.config with your project

{deps, [
 {dubboerl, {git, "https://github.com/apache/dubbo-erlang.git", {branch, "master"}}}
]}.

使用 erlang.mk 编译工具

待补充

导入接口库

Suppose the interface lib you exported is called dubbo_service.

If you didn’t upload your lib to your git repository, It is recommended that you copy the dubbo_service lib into the project’s apps directory.
If it is upload to your git repository, you can import like this:

{deps, [
 {dubboerl, {git, "https://github.com/apache/dubbo-erlang.git", {branch, "master"}}},
 {dubbo_service,{git,"${INTERFACE_LIB_URL}",{branch,"master"}}} %% replace ${INTERFACE_LIB_URL} with your lib git repos url
]}.

消费者配置

Please reference Reference Config

快速开始

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

建议先使用 java 定义接口 jar，并使用 erlanalysis 工具解析java接口至Erlang lib

导入依赖库

使用 Rebar 编译工具。

Add dubblerl to rebar.config with your project

{deps, [
 {dubboerl, {git, "https://github.com/apache/dubbo-erlang.git", {branch, "master"}}}
]}.

使用 erlang.mk 编译工具

待补充

导入接口库

Suppose the interface lib you exported is called dubbo_service.

If you didn’t upload your lib to your git repository, It is recommended that you copy the dubbo_service lib into the project’s apps directory.
If it is upload to your git repository, you can import like this:

{deps, [
 {dubboerl, {git, "https://github.com/apache/dubbo-erlang.git", {branch, "master"}}},
 {dubbo_service,{git,"${INTERFACE_LIB_URL}",{branch,"master"}}} %% replace ${INTERFACE_LIB_URL} with your lib git repos url
]}.

消费者配置

Please reference Reference Config

快速开始

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

基于 Dubbo 定义的 Triple 协议，你可以轻松编写浏览器、gRPC 兼容的 RPC 服务，并让这些服务同时运行在 HTTP/1 和 HTTP/2 上。Dubbo Node.js SDK 支持使用 IDL 或编程语言特有的方式定义服务，并提供一套轻量的 API 来发布或调用这些服务。

本示例演示了基于 Triple 协议的 RPC 通信模式，示例使用 Protocol Buffer 定义 RPC 服务，并演示了代码生成、服务发布和服务访问等过程。

前置条件

npm install @bufbuild/protoc-gen-es @bufbuild/protobuf @apachedubbo/protoc-gen-apache-dubbo-es @apachedubbo/dubbo

定义服务

现在，使用 Protocol Buffer (IDL) 来定义一个 Dubbo 服务。

创建目录，并生成文件

mkdir -p proto && touch proto/example.proto

写入内容

syntax = "proto3";

package apache.dubbo.demo.example.v1;

message SayRequest {
 string sentence = 1;
}

message SayResponse {
 string sentence = 1;
}

service ExampleService {
 rpc Say(SayRequest) returns (SayResponse) {}
}

这个文件声明了一个叫做 ExampleService 的服务，为这个服务定义了 Say 方法以及它的请求参数 SayRequest 和返回值 SayResponse。

快速开始

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

本指南将通过一个简单的工作示例帮助您开始使用 Python 中的 Dubbo，在此查看完整示例。

1 前置条件

Python 3.11 或更高版本
合适的pip 版本

2 安装Dubbo-python

直接安装
```
pip install apache-dubbo
```

从源码安装

git clone https://github.com/apache/dubbo-python.git
cd dubbo-python && pip install .

3 构建Dubbo服务

构建Dubbo Server

import dubbo
from dubbo.configs import ServiceConfig
from dubbo.proxy.handlers import RpcMethodHandler, RpcServiceHandler

class UnaryServiceServicer:
 def say_hello(self, message: bytes) -> bytes:
 print(f"Received message from client: {message}")
 return b"Hello from server"

def build_service_handler():
 # build a method handler
 method_handler = RpcMethodHandler.unary(
 method=UnaryServiceServicer().say_hello, method_name="unary"
 )
 # build a service handler
 service_handler = RpcServiceHandler(
 service_name="org.apache.dubbo.samples.HelloWorld",
 method_handlers=[method_handler],
 )
 return service_handler

if __name__ == "__main__":
 # build service config
 service_handler = build_service_handler()
 service_config = ServiceConfig(
 service_handler=service_handler, host="127.0.0.1", port=50051
 )
 # start the server
 server = dubbo.Server(service_config).start()

 input("Press Enter to stop the server...\n")

构建Dubbo Client

快速开始

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

请在此查看完整示例。

1 前置条件

安装 Rust 开发环境
安装 protoc 工具

2 使用 IDL 定义 Dubbo 服务

Greeter 服务定义如下，包含一个 Unary(request-response) 模型的 Dubbo 服务。

// ./proto/greeter.proto
syntax = "proto3";

option java_multiple_files = true;

package org.apache.dubbo.sample.tri;


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

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

service Greeter{
 // unary
 rpc greet(GreeterRequest) returns (GreeterReply);
}

3 添加 Dubbo-rust 及相关依赖到项目

# ./Cargo.toml
[package]
name = "example-greeter"
version = "0.1.0"
edition = "2021"

[[bin]]
name = "greeter-server"
path = "src/greeter/server.rs"

[[bin]]
name = "greeter-client"
path = "src/greeter/client.rs"

[dependencies]
http = "0.2"
http-body = "0.4.4"
futures-util = {version = "0.3", default-features = false}
tokio = { version = "1.0", features = [ "rt-multi-thread", "time", "fs", "macros", "net", "signal"] }
prost-derive = {version = "0.10", optional = true}
prost = "0.10.4"
async-trait = "0.1.56"
tokio-stream = "0.1"

dubbo = "0.1.0"
dubbo-config = "0.1.0"

[build-dependencies]
dubbo-build = "0.1.0"

4 配置 dubbo-build 编译 IDL

在项目根目录创建 (not /src)，创建 build.rs 文件并添加以下内容：

快速易用

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

无论你是计划采用微服务架构开发一套全新的业务系统，还是准备将已有业务从单体架构迁移到微服务架构，Dubbo 框架都可以帮助到你。Dubbo 让微服务开发变得非常容易，它允许你选择多种编程语言、使用任意通信协议，并且它还提供了一系列针对微服务场景的开发、测试工具帮助提升研发效率。

多语言 SDK

Dubbo 提供几乎所有主流语言的 SDK 实现，定义了一套统一的微服务开发范式。Dubbo 与每种语言体系的主流应用开发框架做了适配，总体编程方式、配置符合大多数开发者已有编程习惯。

比如在 Java 语言体系下，你可以使用 dubbo-spring-boot-starter 来开发符合 Spring、Spring Boot 模式的微服务应用，开发 Dubbo 应用只是为 Spring Bean 添加几个注解、完善 application.properties 配置文件。

任意通信协议

Dubbo 微服务间远程通信实现细节，支持 HTTP、HTTP/2、gRPC、TCP 等所有主流通信协议。与普通 RPC 框架不同，Dubbo 不是某个单一 RPC 协议的实现，它通过上层的 RPC 抽象可以将任意 RPC 协议接入 Dubbo 的开发、治理体系。

多协议支持让用户选型，多协议迁移、互通等变得更灵活。

加速微服务开发

项目脚手架

项目脚手架让 Dubbo 项目创建、依赖管理更容易。

比如通过如下可视化界面，勾选 Dubbo 版本、Zookeeper 注册中心以及必要的微服务生态选项后，一个完整的 Dubbo 项目模板就可以自动生成，接下来基于脚手架项目添加业务逻辑就可以了。更多脚手架使用方式的讲解，请参见任务模块的通过模板生成项目脚手架

开发测试

相比于单体应用，微服务分布式的特性会让不同组织之间的研发协同变得困难，这时我们需要有效的配套工具，用来提升整体的微服务研发效率。

Dubbo 从内核设计和实现阶段就考虑了如何解决开发、测试与运维问题，比如 Dubbo RPC 协议均支持 curl 访问，让开发协作更简单；配合官方提供的生态工具，可以实现服务测试、服务 Mock、文档管理、单机运维等能力，并通过 Dubbo Admin 控制台将所有操作都可视化的展现出来。

框架介绍

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

什么是 dubbo-go

Dubbo-go 是 Apache Dubbo 的 go 语言实现，它完全遵循 Apache Dubbo 设计原则与目标，是 go 语言领域的一款优秀微服务开发框架。dubbo-go 提供：

API 与 RPC 协议：帮助解决组件之间的 RPC 通信问题，提供基于 HTTP/1/2 的通信协议、streaming流式通信模型。
丰富的微服务治理能力：解决地址发现、流量管控、可观测性、全链路追踪、日志等微服务整体解决方案。

概念与架构

以下是 dubbo-go 的整体架构图：

dubbo-go 总体上遵循 框架内核+插件 的的设计理念，左侧的 框架内核 定义了 dubbo-go 作为微服务框架的一些核心概念，右侧的 插件 部分则提供了核心概念扩展实现。

框架内核 可分为 4 个层次，从上到下依次为：

API 层：dubbo-go 同时支持基于 IDL、interface/struct 的服务契约定义，兼顾跨语言与易用性诉求；支持基于纯 yaml 文件的微服务配置模式；提供了同步、异步、单次(unary)、流式(streaming) 等 RPC 通信与编码模型。
服务治理层：dubbo-go 内置了多维度的服务治理能力抽象，确保满足微服务开发与集群治理的核心诉求，这包括地址发现（Service Discovery）、负载均衡（Load Balancing）、可观测指标（Metrics）、流量管控（Traffic Management）、全链路追踪（Tracing）等。
RPC 协议层：dubbo-go 实现的最核心的 RPC 协议是 - triple 协议，triple 可同时工作在 http1/2 之上 (支持 CURL 直接访问)，兼容 gRPC；从设计上，dubbo-go 还提供了多协议发布服务的支持，你可以在一个进程内同时发布 triple、dubbo2、rest、jsonRPC 等多种不同通信协议的服务。

配置和管理框架日志

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

本示例演示如何配置 dubbo-go 框架日志组件，将框架运行态日志保存到指定的位置。可在此查看完整示例源码地址。

注意

这里配置的只是 dubbo-go 框架自身的日志组件行为，即框架内部使用的日志，不影响业务日志框架的使用！

1. 日志配置

如下所示，可以通过 log.WithZap()、log.WithLevel("warn") 设置 dubbo 框架日志行为：

ins, err := dubbo.NewInstance(
	dubbo.WithLogger(
		log.WithLevel("warn"),
		log.WithZap(),
	),
)

2. 应用共享日志组件

注意，这里配置的只是 dubbo-go 框架自身的日志组件行为（即框架内部使用的日志），不影响业务日志框架的使用！

通过以下方式，业务应用也可以选择复用这个日志组件：

import app_logger "github.com/dubbogo/gost/log/logger"

app_logger.Info("hello")

日志 Interface

type Logger interface {
	Info(args ...interface{})
	Warn(args ...interface{})
	Error(args ...interface{})
	Debug(args ...interface{})
	Fatal(args ...interface{})

	Infof(fmt string, args ...interface{})
	Warnf(fmt string, args ...interface{})
	Errorf(fmt string, args ...interface{})
	Debugf(fmt string, args ...interface{})
	Fatalf(fmt string, args ...interface{})
}

注意

日志API不可以在Init 阶段使用，否则可能会发生意料之外的问题。

2. 完全自定义日志

当前 dubbo-go 框架支持 zap、logrus 两个日志框架，如果您想让 dubbo 框架内核使用其他日志框架打印日志，推荐以标准扩展形式增加支持，具体可参考核心库中内置的源码实现。

类检查机制

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

特性说明

该机制保证服务提供方和服务消费方类之间的兼容性和安全。

使用场景

防止由于类版本不匹配、方法签名不兼容或缺少类而可能发生的潜在问题。

使用方式

支持版本 Dubbo >= 3.1.6

适用范围目前序列化检查支持 Hessian2、Fastjson2 序列化以及泛化调用。其他的序列化方式暂不支持。

检查模式

检查模式分为三个级别：STRICT 严格检查，WARN 告警，DISABLE 禁用。 STRICT 严格检查：禁止反序列化所有不在允许序列化列表（白名单）中的类。 WARN 告警：仅禁止序列化所有在不允许序列化列表中（黑名单）的类，同时在反序列化不在允许序列化列表（白名单）中类的时候通过日志进行告警。 DISABLE 禁用：不进行任何检查。

3.1 版本中默认为 WARN 告警级别，3.2 版本中默认为 STRICT 严格检查级别。

通过 ApplicationConfig 配置：

ApplicationConfig applicationConfig = new ApplicationConfig();
applicationConfig.setSerializeCheckStatus("STRICT");

通过 Spring XML 配置：

<dubbo:application name="demo-provider" serialize-check-status="STRICT"/>

通过 Spring Properties / dubbo.properties 配置：

dubbo.application.serialize-check-status=STRICT

通过 System Property 配置：

-Ddubbo.application.serialize-check-status=STRICT

配置成功后可以在日志中看到如下的提示：

INFO utils.SerializeSecurityManager: [DUBBO] Serialize check level: STRICT

注：在同一个进程（Dubbo Framework Model）下的多个应用如果同时配置不同的检查模式，最终会生效“最宽松”的级别。如两个 Spring Context 同时启动，一个配置为 STRICT，另外一个配置为 WARN，则最终生效 WARN 级别的配置。

全链路追踪使用与实现说明

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

Dubbo 内置了全链路追踪能力，你可以通过引入 spring-boot-starter 或者相关依赖开启链路跟踪能力，通过将跟踪数据导出到一些主流实现如 Zipkin、Skywalking、Jaeger 等后端系统，可以实现全链路跟踪数据的分析与可视化展示。

Dubbo 目前借助 Micrometer Observation 完成 Tracing 的所有埋点工作，依赖 Micrometer 提供的各种 Bridge 适配，我们可以实现将 Tracing 导入各种后端系统，具体工作原理如下。

使用方式

以 Dubbo Spring Boot 应用为例，通过加入如下依赖即可开启链路追踪，并使用 zipkin exporter bridge 将链路追踪数据导入 Zipkin 后端系统。

<dependency>
 <groupId>org.apache.dubbo</groupId>
 <artifactId>dubbo-spring-boot-tracing-otel-zipkin-starter</artifactId>
 <version>3.2.1-SNAPSHOT</version>
</dependency>

更多完整示例请参见：

关联日志

Dubbo Tracing 还实现了与日志系统的自动关联，即将 tracing-id、span-id 等信息自动置入日志 MDC 上下文，你只需要设置日志输出格式中包含类似 %X{traceId:-},%X{spanId:-}]，即可实现业务日志与 tracing 系统的自动关联，具体可参见 Tracing 日志上下文配置示例。

工作原理

Tracing相关概念

Span：基本工作单元。例如，发送 RPC 是一个新的 span，发送对 RPC 的响应也是如此。Span还有其他数据，例如description、带时间戳的事件、键值注释（标签）、导致它们的跨度的 ID 和进程 ID（通常是 IP 地址）。跨度可以启动和停止，并且它们会跟踪它们的时间信息。创建跨度后，您必须在将来的某个时间点停止它。

流式通信

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

Streaming 流式通信是 Dubbo3 新提供的一种 RPC 数据传输模式，适用于以下场景:

接口需要发送大量数据，这些数据无法被放在一个 RPC 的请求或响应中，需要分批发送，但应用层如果按照传统的多次 RPC 方式无法解决顺序和性能的问题，如果需要保证有序，则只能串行发送
流式场景，数据需要按照发送顺序处理, 数据本身是没有确定边界的
推送类场景，多个消息在同一个调用的上下文中被发送和处理

Streaming 流式通信类型分为以下三种:

SERVER_STREAM(服务端流)
CLIENT_STREAM(客户端流)
BIDIRECTIONAL_STREAM(双向流)

1.介绍

本文档演示如何在 Dubbo-go 中使用流式通信，可在此查看完整示例源码地址。

2.如何使用Dubbo-go流式通信

在proto文件中需要流式通信的方法的参数前面添加stream，使用proto-gen-triple生成相应文件

service GreetService {
 rpc Greet(GreetRequest) returns (GreetResponse) {}
 rpc GreetStream(stream GreetStreamRequest) returns (stream GreetStreamResponse) {}
 rpc GreetClientStream(stream GreetClientStreamRequest) returns (GreetClientStreamResponse) {}
 rpc GreetServerStream(GreetServerStreamRequest) returns (stream GreetServerStreamResponse) {}
}

编写服务端handler文件

源文件路径: dubbo-go-sample/streaming/go-server/cmd/server.go

type GreetTripleServer struct {
}

func (srv *GreetTripleServer) Greet(ctx context.Context, req *greet.GreetRequest) (*greet.GreetResponse, error) {
	resp := &greet.GreetResponse{Greeting: req.Name}
	return resp, nil
}

func (srv *GreetTripleServer) GreetStream(ctx context.Context, stream greet.GreetService_GreetStreamServer) error {
	for {
		req, err := stream.Recv()
		if err != nil {
			if triple.IsEnded(err) {
				break
			}
			return fmt.Errorf("triple BidiStream recv error: %s", err)
		}
		if err := stream.Send(&greet.GreetStreamResponse{Greeting: req.Name}); err != nil {
			return fmt.Errorf("triple BidiStream send error: %s", err)
		}
	}
	return nil
}

func (srv *GreetTripleServer) GreetClientStream(ctx context.Context, stream greet.GreetService_GreetClientStreamServer) (*greet.GreetClientStreamResponse, error) {
	var reqs []string
	for stream.Recv() {
		reqs = append(reqs, stream.Msg().Name)
	}
	if stream.Err() != nil && !triple.IsEnded(stream.Err()) {
		return nil, fmt.Errorf("triple ClientStream recv err: %s", stream.Err())
	}
	resp := &greet.GreetClientStreamResponse{
		Greeting: strings.Join(reqs, ","),
	}

	return resp, nil
}

func (srv *GreetTripleServer) GreetServerStream(ctx context.Context, req *greet.GreetServerStreamRequest, stream greet.GreetService_GreetServerStreamServer) error {
	for i := 0; i < 5; i++ {
		if err := stream.Send(&greet.GreetServerStreamResponse{Greeting: req.Name}); err != nil {
			return fmt.Errorf("triple ServerStream send err: %s", err)
		}
	}
	return nil
}

编写客户端client文件

Dubbo 路由（router）机制及其如何实现流量管控介绍

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

Dubbo 提供了丰富的流量管控策略

地址发现与负载均衡，地址发现支持服务实例动态上下线，负载均衡确保流量均匀的分布到每个实例上。
基于路由规则的流量管控，路由规则对每次请求进行条件匹配，并将符合条件的请求路由到特定的地址子集。

服务发现保证调用方看到最新的提供方实例地址，服务发现机制依赖注册中心 (Zookeeper、Nacos、Istio 等) 实现。在消费端，Dubbo 提供了多种负载均衡策略，如随机负载均衡策略、一致性哈希负载、基于权重的轮询、最小活跃度优先、P2C 等。

Dubbo 的流量管控规则可以基于应用、服务、方法、参数等粒度精准的控制流量走向，根据请求的目标服务、方法以及请求体中的其他附加参数进行匹配，符合匹配条件的流量会进一步的按照特定规则转发到一个地址子集。流量管控规则有以下几种：

条件路由规则
标签路由规则
脚本路由规则
动态配置规则

如果底层用的是基于 HTTP 的 RPC 协议 (如 REST、gRPC、Triple 等)，则服务和方法等就统一映射为 HTTP 路径 (path)，此时 Dubbo 路由规则相当于是基于 HTTP path 和 headers 的流量分发机制。

Dubbo 中有应用、服务和方法的概念，一个应用可以发布多个服务，一个服务包含多个可被调用的方法，从抽象的视角来看，一次 Dubbo 调用就是某个消费方应用发起了对某个提供方应用内的某个服务特定方法的调用，Dubbo 的流量管控规则可以基于应用、服务、方法、参数等粒度精准的控制流量走向。

Router工作原理

以下是 Dubbo 单个路由器的工作过程，路由器接收一个服务的实例地址集合作为输入，基于请求上下文 (Request Context) 和 (Router Rule) 实际的路由规则定义对输入地址进行匹配，所有匹配成功的实例组成一个地址子集，最终地址子集作为输出结果继续交给下一个路由器或者负载均衡组件处理。

通常，在 Dubbo 中，多个路由器组成一条路由链共同协作，前一个路由器的输出作为另一个路由器的输入，经过层层路由规则筛选后，最终生成有效的地址集合。

Dubbo 中的每个服务都有一条完全独立的路由链，每个服务的路由链组成可能不通，处理的规则各异，各个服务间互不影响。
对单条路由链而言，即使每次输入的地址集合相同，根据每次请求上下文的不同，生成的地址子集结果也可能不同。

路由规则分类

标签路由规则

标签路由通过将某一个服务的实例划分到不同的分组，约束具有特定标签的流量只能在指定分组中流转，不同分组为不同的流量场景服务，从而实现流量隔离的目的。标签路由可以作为蓝绿发布、灰度发布等场景能力的基础。

标签路由规则是一个非此即彼的流量隔离方案，也就是匹配标签的请求会 100% 转发到有相同标签的实例，没有匹配标签的请求会 100% 转发到其余未匹配的实例。如果您需要按比例的流量调度方案，请参考示例基于权重的按比例流量路由。

标签主要是指对 Provider 端应用实例的分组，目前有两种方式可以完成实例分组，分别是动态规则打标和静态规则打标。动态规则打标 可以在运行时动态的圈住一组机器实例，而 静态规则打标 则需要实例重启后才能生效，其中，动态规则相较于静态规则优先级更高，而当两种规则同时存在且出现冲突时，将以动态规则为准。

魔鬼在细节

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

最近一直担心如果 Dubbo 分布式服务框架维护人员增多或变更，会出现质量的下降的问题，我在想，有没有什么规则是需要大家共同遵守的。根据平时写代码时的一习惯，总结了以下在写代码过程中，尤其是框架代码，要时刻牢记的细节。可能下面要讲的这些，大家都会觉得很简单，很基础，但要做到时刻牢记。在每一行代码中都考虑这些因素，是需要很大耐心的，大家经常说，魔鬼在细节中，确实如此。

防止空指针和下标越界

这是我最不喜欢看到的异常，尤其在核心框架中，我更愿看到信息详细的参数不合法异常。这也是一个编写健壮程序的开发人员，在写每一行代码都应在潜意识中防止的异常。基本上要能确保每一次写完的代码，在不测试的情况下，都不会出现这两个异常才算合格。

保证线程安全性和可见性

对于框架的开发人员，对线程安全性和可见性的深入理解是最基本的要求。需要开发人员，在写每一行代码时都应在潜意识中确保其正确性。因为这种代码，在小并发下做功能测试时，会显得很正常。但在高并发下就会出现莫明其妙的问题，而且场景很难重现，极难排查。

尽早失败和前置断言

尽早失败也应该成为潜意识，在有传入参数和状态变化时，均在入口处全部断言。一个不合法的值和状态，在第一时间就应报错，而不是等到要用时才报错。因为等到要用时，可能前面已经修改其它相关状态，而在程序中很少有人去处理回滚逻辑。这样报错后，其实内部状态可能已经混乱，极易在一个隐蔽分支上引发程序不可恢复。

分离可靠操作和不可靠操作

这里的可靠是狭义的指是否会抛出异常或引起状态不一致，比如，写入一个线程安全的 Map，可以认为是可靠的，而写入数据库等，可以认为是不可靠的。开发人员必须在写每一行代码时，都注意它的可靠性与否，在代码中尽量划分开，并对失败做异常处理，并为容错，自我保护，自动恢复或切换等补偿逻辑提供清晰的切入点，保证后续增加的代码不至于放错位置，而导致原先的容错处理陷入混乱。

异常防御，但不忽略异常

这里讲的异常防御，指的是对非必须途径上的代码进行最大限度的容忍，包括程序上的 BUG，比如：获取程序的版本号，会通过扫描 Manifest 和 jar 包名称抓取版本号，这个逻辑是辅助性的，但代码却不少，初步测试也没啥问题，但应该在整个 getVersion() 中加上一个全函数的 try-catch 打印错误日志，并返回基本版本，因为 getVersion() 可能存在未知特定场景异常，或被其他的开发人员误修改逻辑(但一般人员不会去掉 try-catch)，而如果它抛出异常会导致主流程异常，这是我们不希望看到的。但这里要控制个度，不要随意 try-catch，更不要无声无息的吃掉异常。

缩小可变域和尽量 final

如果一个类可以成为不变类(Immutable Class)，就优先将它设计成不变类。不变类有天然的并发共享优势，减少同步或复制，而且可以有效帮忙分析线程安全的范围。就算是可变类，对于从构造函数传入的引用，在类中持有时，最好将字段 final，以免被中途误修改引用。不要以为这个字段是私有的，这个类的代码都是我自己写的，不会出现对这个字段的重新赋值。要考虑的一个因素是，这个代码可能被其他人修改，他不知道你的这个弱约定，final 就是一个不变契约。

降低修改时的误解性，不埋雷

前面不停的提到代码被其他人修改，这也开发人员要随时紧记的。这个其他人包括未来的自己，你要总想着这个代码可能会有人去改它。我应该给修改的人一点什么提示，让他知道我现在的设计意图，而不要在程序里面加潜规则，或埋一些容易忽视的雷，比如：你用 null 表示不可用，size 等于 0 表示黑名单，这就是一个雷，下一个修改者，包括你自己，都不会记得有这样的约定，可能后面为了改某个其它 BUG，不小心改到了这里，直接引爆故障。对于这个例子，一个原则就是永远不要区分 null 引用和 empty 值。

提高代码的可测性

这里的可测性主要指 Mock 的容易程度，和测试的隔离性。至于测试的自动性，可重复性，非偶然性，无序性，完备性(全覆盖)，轻量性(可快速执行)，一般开发人员，加上 JUnit 等工具的辅助基本都能做到，也能理解它的好处，只是工作量问题。这里要特别强调的是测试用例的单一性(只测目标类本身)和隔离性(不传染失败)。现在的测试代码，过于强调完备性，大量重复交叉测试，看起来没啥坏处，但测试代码越多，维护代价越高。经常出现的问题是，修改一行代码或加一个判断条件，引起 100 多个测试用例不通过。时间一紧，谁有这个闲功夫去改这么多形态各异的测试用例？久而久之，这个测试代码就已经不能真实反应代码现在的状况，很多时候会被迫绕过。最好的情况是，修改一行代码，有且只有一行测试代码不通过。如果修改了代码而测试用例还能通过，那也不行，表示测试没有覆盖到。另外，可 Mock 性是隔离的基础，把间接依赖的逻辑屏蔽掉。可 Mock 性的一个最大的杀手就是静态方法，尽量少用。

配置中心

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

配置中心 (config-center) 在 Dubbo 中可承担两类职责：

外部化配置：启动配置的集中式存储（简单理解为 dubbo.properties 的外部化存储）。
流量治理规则存储

请参考具体扩展实现了解如何启用配置中心。

值得注意的是 Dubbo 动态配置中心定义了两个不同层次的隔离选项，分别是 namespace 和 group。

namespace - 配置命名空间，默认值 dubbo。命名空间通常用于多租户隔离，即对不同用户、不同环境或完全不关联的一系列配置进行逻辑隔离，区别于物理隔离的点是不同的命名空间使用的还是同一物理集群。
group - 配置分组，默认值 dubbo。group 通常用于归类一组相同类型/目的的配置项，是对 namespace 下配置项的进一步隔离。

参考配置说明 - 配置项手册了解 namespace 和 group 之外 config-center 开放的更多配置项。

使用注册中心作为默认配置中心

在使用 Zookeeper、Nacos 作为注册中心且没有显式配置配置中心的情况下，Dubbo 框架会默认将此 Zookeeper、Nacos 用作配置中心，用作服务治理用途。

启动时检查

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

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

Dubbo 缺省会在启动时检查依赖的服务是否可用，不可用时会抛出异常，阻止 Spring 初始化完成，以便上线时，能及早发现问题，默认 check="true"。

可以通过 check="false" 关闭检查，比如，测试时，有些服务不关心，或者出现了循环依赖，必须有一方先启动。

另外，如果你的 Spring 容器是懒加载的，或者通过 API 编程延迟引用服务，请关闭 check，否则服务临时不可用时，会抛出异常，拿到 null 引用，如果 check="false"，总是会返回引用，当服务恢复时，能自动连上。

示例

通过 spring 配置文件

关闭某个服务的启动时检查 (没有提供者时报错)：

<dubbo:reference interface="com.foo.BarService" check="false" />

关闭所有服务的启动时检查 (没有提供者时报错)：

<dubbo:consumer check="false" />

关闭注册中心启动时检查 (注册订阅失败时报错)：

<dubbo:registry check="false" />

通过 dubbo.properties

dubbo.reference.com.foo.BarService.check=false
dubbo.consumer.check=false
dubbo.registry.check=false

通过 -D 参数

java -Ddubbo.reference.com.foo.BarService.check=false
java -Ddubbo.consumer.check=false 
java -Ddubbo.registry.check=false

配置的含义

dubbo.reference.com.foo.BarService.check，覆盖 com.foo.BarService的 reference 的 check 值，就算配置中有声明，也会被覆盖。

dubbo.consumer.check=false，是设置reference的 check 的缺省值，如果配置中有显式的声明，如：<dubbo:reference check="true"/>，不会受影响。

dubbo.registry.check=false，前面两个都是指订阅成功，但提供者列表是否为空是否报错，如果注册订阅失败时，也允许启动，需使用此选项，将在后台定时重试。

启动时检查

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

背景

Dubbo 缺省会在启动时检查依赖的服务是否可用，不可用时会抛出异常，阻止 Spring 初始化完成，以便上线时，能及早发现问题，默认 check="true"。

可以通过 check="false" 关闭检查，比如，测试时，有些服务不关心，或者出现了循环依赖，必须有一方先启动。

示例

通过 spring 配置文件

关闭某个服务的启动时检查 (没有提供者时报错)：

<dubbo:reference interface="com.foo.BarService" check="false" />

关闭所有服务的启动时检查 (没有提供者时报错)：

<dubbo:consumer check="false" />

关闭注册中心启动时检查 (注册订阅失败时报错)：

<dubbo:registry check="false" />

通过 dubbo.properties

dubbo.reference.com.foo.BarService.check=false
dubbo.reference.check=false
dubbo.consumer.check=false
dubbo.registry.check=false

通过 -D 参数

java -Ddubbo.reference.com.foo.BarService.check=false
java -Ddubbo.reference.check=false
java -Ddubbo.consumer.check=false 
java -Ddubbo.registry.check=false

配置的含义

dubbo.reference.check=false，强制改变所有 reference 的 check 值，就算配置中有声明，也会被覆盖。

dubbo.consumer.check=false，是设置 check 的缺省值，如果配置中有显式的声明，如：<dubbo:reference check="true"/>，不会受影响。

请求耗时采样

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

性能采样功能可以对 Dubbo 处理链路上的各处耗时进行检测，在出现超时的时候 ( usageTime / timeout > profilerWarnPercent * 100 ) 通过日志记录调用的耗时。

此功能分为 simple profiler 和 detail profiler 两个模式，其中 simple profiler 模式默认开启，detail profiler 模式默认关闭。 detail profiler 相较 simple profiler 模式多采集了每个 filter 的处理耗时、协议上的具体耗时等。在 simple profiler 模式下如果发现 Dubbo 框架内部存在耗时长的情况，可以开启 detail profiler 模式，以便更好地排查问题。

使用场景

需要对 Dubbo 请求的精确耗时进行采集分析的场景，如服务不明原因的超时等

使用方式

simple profiler 默认自动开启，对于请求处理时间超过超时时间 3/4 的，都会通过日志打印出慢调用信息。如果需要开启 detail profiler 模式或者修改超时告警比例，可以参考性能采样命令文档。

日志说明

日志中各字段的含义如下：

[Dubbo-Consumer] execute service 接口#方法 cost 实际耗时, this invocation almost (maybe already) timeout. Timeout: 超时时间
invocation context:
请求上下文
thread info: 
Start time: 开始请求时间（nano 时间）
+-[ Offset: 当前节点开始时间; Usage: 当前节点使用总耗时, 当前节点耗时比例 ] 当前节点描述
 +-[ Offset: 当前节点开始时间; Usage: 当前节点使用总耗时, 当前节点耗时比例 ] 当前节点描述

对于请求耗时这里以两个例子进行介绍：

自定义 SPI 扩展的基本步骤

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

下面以 RPC 协议插件 为例，说明如何利用 Dubbo 提供的 SPI 插件提供一个自定义的 RPC 协议实现。如果想了解 SPI 机制的工作原理以及框架内置的 SPI 扩展点列表，请查看参考手册 - SPI扩展。

1. 提供 SPI 插件实现类

提供一个 Java 类实现 org.apache.dubbo.rpc.Protocol 接口。

package com.spi.demo;
import org.apache.dubbo.rpc.Protocol;

@Activate
public class CustomizedProtocol implements Protocol {
	// ...
}

2. 在指定文件配置实现类

在应用 resources/META-INF/services/ 目录下添加 org.apache.dubbo.rpc.Protocol 文件，文件中增加如下配置：

customized=com.spi.demo.CustomizedProtocol

配置注意事项

文件名必须为 SPI 插件定义的 package 全路径名，具体取决于你要扩展的 SPI 定义，如示例中的 resources/META-INF/services/org.apache.dubbo.rpc.Protocol。
文件中的内容必须是 key=value 形式，其中 key 可随便定义，但建议增加特定前缀以避免与 Dubbo 内置实现重名，value 必须设置为扩展类实现的全路径名。

3. 通过配置启用自定义协议实现

在应用中修改协议配置，告诉 Dubbo 框架使用自定义协议：

# 使用 Spring Boot，可修改 application.yml 或 application.properties
dubbo
 protocol
 name: customized

或者

从 dubbo2 升级到 dubbo3（涵盖 2.5.x、2.6.x、2.7.x 等版本）

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

总体来说，Dubbo2 升级到 Dubbo3 后的核心能力都是兼容的，对于 90% 以上的常规用户而言（指未做深度 SPI 扩展或源码定制的用户），可以非常简单的完成升级。

2.7.x 升级 Dubbo3

步骤一：升级核心依赖

首先，在应用中增加 bom 依赖管理：

<dependencyManagement>
 <dependencies>
 <dependency>
 <groupId>org.apache.dubbo</groupId>
 <artifactId>dubbo-dependencies-bom</artifactId>
 <version>3.3.0</version>
 <type>pom</type>
 <scope>import</scope>
 </dependency>
 </dependencies>
</dependencyManagement>

如果您之前用的是 org.apache.dubbo:dubbo 依赖，请升级到以下版本（如果项目中还有其它 dubbo 子模块依赖，请一并升级版本号）：

<dependency>
 <groupId>org.apache.dubbo</groupId>
 <artifactId>dubbo</artifactId>
</dependency>

如果之前的应用是 Spring Boot，建议使用以下 starter 依赖方式并升级到最新版本（如果之前未使用 starter，请删除所有老的 dubbo 模块依赖，直接使用以下配置即可）：

<dependency>
 <groupId>org.apache.dubbo</groupId>
 <artifactId>dubbo-spring-boot-starter</artifactId>
</dependency>

Dubbo3 相关的 Spring、Spring Boot 版本升级说明

Dubbo3 支持的 Spring、Spring Boot 版本兼容范围非常广：

既支持 Spring 3.x ~ Spring 5.x 相关版本，同时也支持 Spring Boot 1.x ~ Spring Boot 2.x 版本。如果遇到应用无法升级高版本 Spring、Spring Boot 的情况下，可排掉 dubbo-spring-boot-starter 或 dubbo 中传递的高版本 Spring 依赖，指定项目可接受的 Spring 版本依赖即可。
Spring Boot 3.x 和 Spring 6 版本由于需要 JDK 17 及以上版本，请参考 Dubbo Spring Boot 手册 了解详情。

步骤二：升级其它组件依赖

Nacos 注册中心

生态组件

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

Dubbo-go

github.com/apache/dubbo-go

Apache Dubbo Go 语言实现主仓库

Dubbo-go-samples

github.com/apache/dubbo-go-samples

dubbo-go 的使用示例：

config-api: 使用 API 进行配置初始化
configcenter: 使用不同的配置中心，目前支持三种：zookeeper、apollo、和 nacos
context: 如何使用上下文传递 attachment
direct: 直连模式
game: 游戏服务例子
generic: 泛化调用
rpc: RPC 调用例子, 包含 Triple、Dubbo等协议以及跨语言/gRPC互通示例
helloworld: RPC调用入门例子
logger: 日志例子
registry: 展示与不同注册中心的对接，包含了 zk、nacos、etcd
metrics: 数据上报
filter: 使用提供filter和自定义filter的例子
registry/servicediscovery：应用级服务发现例子
router: 路由例子
tracing: 链路追踪例子

Dubbo-go-pixiu

github.com/apache/dubbo-go-pixiu

dubbo-go-pixiu 网关支持以 dubbo 协议和 http 协议调用 dubbo/dubbo-go 集群

Dubbo-getty

github.com/apache/dubbo-getty

dubbo-getty 是一个Go语言异步网络 io 库，支持 tcp/udp/websocket 协议。

Dubbo-go-hessian2

github.com/apache/dubbo-go-hessian2

Dubbo-go-hessian2 是一个Go语言 hessian2 序列化协议库

示例应用架构

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

此任务基于一个简单的线上商城微服务系统演示了 Dubbo 的流量管控能力。

注意

本示例展示的所有能力均基于 Dubbo 路由规则实现，如想了解具体工作原理可查看详情。

线上商城的架构图如下：

系统由 5 个微服务应用组成：

Frontend 商城主页，作为与用户交互的 web 界面，通过调用 User、Detail、Order 等提供用户登录、商品展示和订单管理等服务。
User 用户服务，负责用户数据管理、身份校验等。
Order 订单服务，提供订订单创建、订单查询等服务，依赖 Detail 服务校验商品库存等信息。
Detail 商品详情服务，展示商品详情信息，调用 Comment 服务展示用户对商品的评论记录。
Comment 评论服务，管理用户对商品的评论数据。

部署商场系统

为方便起见，我们将整个系统部署在 Kubernetes 集群，执行以下命令即可完成商城项目部署，项目源码示例在 dubbo-samples/task。

kubectl apply -f https://raw.githubusercontent.com/apache/dubbo-samples/master/10-task/dubbo-samples-shop/deploy/All.yml

完整的部署架构图如下：

Order 订单服务有两个版本 v1 和 v2，v2 是订单服务优化后发布的新版本。

版本 v1 只是简单的创建订单，不展示订单详情
版本 v2 在订单创建成功后会展示订单的收货地址详情

Detail 和 Comment 服务也分别有两个版本 v1 和 v2，我们通过多个版本来演示流量导流后的效果。

版本 v1 默认为所有请求提供服务
版本 v2 模拟被部署在特定的区域的服务，因此 v2 实例会带有特定的标签

执行以下命令，确定所有服务、Pod都已正常运行：

$ kubectl get services -n dubbo-demo

$ kubectl get pods -n dubbo-demo

为了保障系统完整性，除了商城相关的几个微服务应用，示例还在后台拉起了 Nacos 注册配置中心、Dubbo Admin 控制台和 Skywalking 全链路追踪系统。

条件路由

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

使用方法

前置准备

Docker 以及 Docker compose 环境来部署Nacos配置中心。
Nacos 2.x+
Go 1.23+

启动Nacos配置中心

参考这个教程来启动Nacos。

Condition router 介绍

Condition router 与 Tag router 类似，但是提供了更强大的流量管控功能，可以通过表达式consumer => provider，对服务端以及客户端进行流量管控。

匹配表达式示例:

host = 127.0.0.1 => host = 127.0.0.1, 192.168.1.1

可以使用 = 以及 != 等符号进行匹配，使用逗号进行多选择匹配。

示例代码:

服务端部分:

ins, err := dubbo.NewInstance(
		dubbo.WithName("condition-server"),
		dubbo.WithRegistry(
			registry.WithNacos(),
			registry.WithAddress(RegistryAddress),
		),
		dubbo.WithProtocol(
			protocol.WithTriple(),
			protocol.WithPort(TriPort),
		),
	)

客户端部分:

ins, err := dubbo.NewInstance(
		dubbo.WithName("condition-client"),
		dubbo.WithRegistry(
			registry.WithNacos(),
			registry.WithAddress(RegistryAddress),
		),
		dubbo.WithConfigCenter( // configure config center to enable condition router
			config_center.WithNacos(),
			config_center.WithAddress(RegistryAddress),
		),
	)
rep, err := srv.Greet(context.Background(), &greet.GreetRequest{Name: "hello world"})

使用condition router必须在nacos等配置中心动态设置匹配规则。

条件路由规则

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

条件路由规则将符合特定条件的请求转发到特定的地址实例子集上。规则首先对发起流量的请求参数进行匹配，符合匹配条件的请求将被转发到包含特定实例地址列表的子集。

以下是一个条件路由规则示例。

基于以下示例规则，所有 org.apache.dubbo.samples.CommentService 服务 getComment 方法的调用都将被转发到有 region=Hangzhou 标记的地址子集。

configVersion: v3.0
scope: service
force: true
runtime: true
enabled: true
key: org.apache.dubbo.samples.CommentService
conditions:
 - method=getComment => region=Hangzhou

可以看具体的例子代码：条件路由

ConditionRule

条件路由规则主体。定义路由规则生效的目标服务或应用、流量过滤条件以及一些特定场景下的行为。

字段名	类型	描述	必填
configVersion	string	条件路由的版本，当前版本为 `v3.0`	是
scope	string	支持 `service` 和 `application` 两种规则	是
key	string	应用到的目标服务或应用程序的标识符 - 当 `scope:service` 时, `key`应该是该规则生效的服务名比如 org.apache.dubbo.samples.CommentService - 当 `scope:application` 时, then `key`应该是该规则应该生效的应用名称，比如说my-dubbo-service.	是
enabled	bool	规则是否生效当 `enabled:false` 时，规则不生效	是
conditions	string[]	配置中定义的条件规则，详情可以看条件规则	是
force	bool	T路由后实例子集为空时的行为。 `true` 则抛出一个No Provider Exception。 `false` 则忽略规则，直接去请求其他的实例。默认值是false	否
runtime	bool	是否为每个 rpc 调用运行路由规则或使用路由缓存（如果可用）。默认值是false（false则走缓存，true不走缓存）	否

Condition

Condition 为条件路由规则的主体，类型为一个复合结构的 string 字符串，如 method=getComment => region=Hangzhou。其中，

通用 Release 流程

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

理解 Apache 发布的内容和流程

总的来说，Source Release 是 Apache 关注的重点，也是发布的必须内容；而 Binary Release 是可选项，Dubbo 可以选择是否发布二进制包到 Apache 仓库或者发布到 Maven 中央仓库。

请参考以下链接，找到更多关于 ASF 的发布指南:

发布流程

1. 准备分支

从主干分支拉取新分支作为发布分支，如现在要发布 ${release_version} 版本，则从开发分支拉出新分支 ${release_version}-release，此后${release_version} Release Candidates 涉及的修改及打标签等都在${release_version}-release分支进行，最终发布完成后合入主干分支。

例：如 Java SDK 需要发布 3.0.10 版本，从 3.0 分支拉出新分支 3.0.10-release，并在此分支提交从 Snapshot 替换为 3.0.10 版本号的 commit。

2. Github 打标签并发布 Pre Release 状态

在对应 GitHub 仓库中基于 ${release_version}-release 分支，打标签 ${release_version}-release，填写 Release Note 并发布 Pre Release 状态。（不允许在投票流程正式通过前把 Release 状态置为正式发布状态）

网络协议

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

对于 Dubbogo 微服务框架，网络协议为远程过程调用中负责网络通信的模块，负责应用层到网络层的数据序列化、打包、请求发起、网络端口监听等功能。Dubbogo 为协议抽象了一套接口如下：

type Protocol interface {
	// Export service for remote invocation
	Export(invoker Invoker) Exporter
	// Refer a remote service
	Refer(url *common.URL) Invoker
	// Destroy will destroy all invoker and exporter, so it only is called once.
	Destroy()
}

该接口包含三个方法。其中 Export 方法负责服务的暴露过程。入参 invoker 为dubbo 的概念，其封装了一个可以被调用的实例。在具体网络协议（例如Triple）实现的 Export 方法中，会针对特定的协议，将封装有一定逻辑的可调用实例 Invoker 以网络端口监听的形式暴露给外部服务，来自外部针对该网络端口的请求将会被 Export 方法开启的监听协程获取，进而根据网络协议进行拆解包和反序列化，得到解析后的请求数据。

Refer 方法负责服务的引用过程，其入参 url 为 dubbo 框架通用的结构，可以描述一个希望引用的服务，url 参数中包含了多个希望引用服务的参数，例如对应服务的接口名(interface)，版本号(version)，使用协议(protocol) 等等。在具体网络协议（例如Triple）实现的 Refer 方法中，会将特定的网络协议封装到 Invoker 可调用实例的方法中，用户层发起的 RPC 调用即可直接通过返回的 Invoker 对象，发起特定协议的网络请求。

Destroy 方法作用为销毁当前暴露的服务，用于服务下线场景。Dubbogo 框架有优雅下线机制，可以在服务进程终止前以监听信号的形式，下线所有已启动的服务。

微服务开发

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

Dubbo 解决企业微服务从开发、部署到治理运维的一系列挑战，Dubbo 为开发者提供从项目创建、开发测试，到部署、可视化监测、流量治理，再到生态集成的全套服务。

开发层面，Dubbo 提供了 Java、Go、Rust、Node.js 等语言实现并定义了一套微服务开发范式，配套脚手架可用于快速创建微服务项目骨架
部署层面，Dubbo 应用支持虚拟机、Docker 容器、Kubernetes、服务网格架构部署
服务治理层面，Dubbo 提供了地址发现、负载均衡、流量管控等治理能力，官方还提供 Admin 可视化控制台、丰富的微服务生态集成

开发

接下来以 Java 体系 Spring Boot 项目为例讲解 Dubbo 应用开发的基本步骤，整个过程非常直观简单，其他语言开发过程类似。

创建项目

Dubbo 微服务项目脚手架（支持浏览器页面、命令行和 IDE）可用于快速创建微服务项目，只需要告诉脚手架期望包含的功能或组件，脚手架最终可以帮助开发者生成具有必要依赖的微服务工程。更多脚手架使用方式的讲解，请参见任务模块的通过模板生成项目脚手架

开发服务

1. 定义服务

public interface DemoService {
 String hello(String arg);
}

2. 提供业务逻辑实现

@DubboService
public class DemoServiceImpl implements DemoService {
 public String hello(String arg) {
 // put your microservice logic here
 }
}

发布服务

1. 发布服务定义

为使消费方顺利调用服务，服务提供者首先要将服务定义以 Jar 包形式发布到 Maven 中央仓库。

2. 对外暴露服务

补充 Dubbo 配置并启动 Dubbo Server

协议概述

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

Dubbo 作为一款 RPC 框架内置了高效的 RPC 通信协议，帮助解决服务间的编码与通信问题，目前支持的协议包括：

triple，基于 HTTP/1、HTTP/2 的高性能通信协议，100% 兼容 gRPC，支持 Unary、Streming 等通信模式；支持发布 REST 风格的 HTTP 服务。
dubbo，基于 TCP 的高性能私有通信协议，缺点是通用性较差，更适合在 Dubbo SDK 间使用；
任意协议扩展，通过扩展 protocol 可以支持任意 RPC 协议，官方生态库提供 JsonRPC、thrift 等支持。

协议选型

开发者该如何确定使用哪一种协议那？ 以下是我们从使用场景、性能、编程易用性、多语言互通等方面对多个主流协议的对比分析：

协议	性能	网关友好	流式通信	多语言支持	编程API	说明
triple	高	高	支持，客户端流、服务端流、双向流	支持（Java、Go、Node.js、JavaScript、Rust）	Java Interface、Protobuf(IDL)	在多语言兼容、性能、网关、Streaming、gRPC 等方面最均衡的协议实现，官方推荐。支持 `application/json` 格式 payload http 直接访问。
dubbo	高	低	不支持	支持（Java、Go）	Java Interface	性能最高的私有协议，但前端流量接入、多语言支持等成本较高

以下是 triple、dubbo 两个主要协议的具体开发、配置、运行态信息：

协议名称	配置值	服务定义方式	默认端口	传输层协议	序列化协议	是否默认
triple	tri	- Java Interface - Java Interface+SpringWeb注解 - Java Interface+JaxRS注解 - Protobuf(IDL)	50051	HTTP/1、HTTP/2	Protobuf Binary、Protobuf-json	否
dubbo	dubbo	- Java Interface	20880	TCP	Hessian、Fastjson2、JSON、JDK、Avro、Kryo 等	是

注意

自 3.3 版本开始，triple 协议支持以 rest 风格发布标准的 http 服务，因此框架中实际已不存在独立的 rest protocol 扩展实现，
考虑到对过往版本的兼容性，当前 Dubbo 各个发行版本均默认使用 dubbo 通信协议。对于新用户而言，我们强烈建议在一开始就明确配置使用 triple 协议，老用户也尽快参考文档实现协议的平滑迁移。

多协议扩展

以下是当前 Dubbo 官方生态库提供的拓展协议实现。如果要扩展更多自定义协议，请参考 SPI 扩展手册或使用教程 - 协议扩展。

协议扩展

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

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

扩展说明

RPC 协议扩展，封装远程调用细节。

契约：

当用户调用 refer() 所返回的 Invoker 对象的 invoke() 方法时，协议需相应执行同 URL 远端 export() 传入的 Invoker 对象的 invoke() 方法。
其中，refer() 返回的 Invoker 由协议实现，协议通常需要在此 Invoker 中发送远程请求，export() 传入的 Invoker 由框架实现并传入，协议不需要关心。

注意：

协议不关心业务接口的透明代理，以 Invoker 为中心，由外层将 Invoker 转换为业务接口。
协议不一定要是 TCP 网络通讯，比如通过共享文件，IPC 进程间通讯等。

扩展接口

org.apache.dubbo.rpc.Protocol
org.apache.dubbo.rpc.Exporter
org.apache.dubbo.rpc.Invoker

public interface Protocol {
 /**
 * 暴露远程服务：<br>
 * 1. 协议在接收请求时，应记录请求来源方地址信息：RpcContext.getContext().setRemoteAddress();<br>
 * 2. export()必须是幂等的，也就是暴露同一个URL的Invoker两次，和暴露一次没有区别。<br>
 * 3. export()传入的Invoker由框架实现并传入，协议不需要关心。<br>
 * 
 * @param <T> 服务的类型
 * @param invoker 服务的执行体
 * @return exporter 暴露服务的引用，用于取消暴露
 * @throws RpcException 当暴露服务出错时抛出，比如端口已占用
 */
 <T> Exporter<T> export(Invoker<T> invoker) throws RpcException;
 
 /**
 * 引用远程服务：<br>
 * 1. 当用户调用refer()所返回的Invoker对象的invoke()方法时，协议需相应执行同URL远端export()传入的Invoker对象的invoke()方法。<br>
 * 2. refer()返回的Invoker由协议实现，协议通常需要在此Invoker中发送远程请求。<br>
 * 3. 当url中有设置check=false时，连接失败不能抛出异常，需内部自动恢复。<br>
 * 
 * @param <T> 服务的类型
 * @param type 服务的类型
 * @param url 远程服务的URL地址
 * @return invoker 服务的本地代理
 * @throws RpcException 当连接服务提供方失败时抛出
 */
 <T> Invoker<T> refer(Class<T> type, URL url) throws RpcException;
 
}

扩展配置

<!-- 声明协议，如果没有配置id，将以name为id -->
<dubbo:protocol id="xxx1" name="xxx" />
<!-- 引用协议，如果没有配置protocol属性，将在ApplicationContext中自动扫描protocol配置 -->
<dubbo:service protocol="xxx1" />
<!-- 引用协议缺省值，当<dubbo:service>没有配置prototol属性时，使用此配置 -->
<dubbo:provider protocol="xxx1" />

已知扩展

org.apache.dubbo.rpc.protocol.injvm.InjvmProtocol
org.apache.dubbo.rpc.protocol.dubbo.DubboProtocol
org.apache.dubbo.rpc.protocol.rmi.RmiProtocol
org.apache.dubbo.rpc.protocol.http.HttpProtocol
org.apache.dubbo.rpc.protocol.http.hessian.HessianProtocol
org.apache.dubbo.rpc.support.MockProtocol

扩展示例

Maven项目结构：

协议扩展

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

扩展说明

RPC 协议扩展，封装远程调用细节。

契约：

当用户调用 refer() 所返回的 Invoker 对象的 invoke() 方法时，协议需相应执行同 URL 远端 export() 传入的 Invoker 对象的 invoke() 方法。
其中，refer() 返回的 Invoker 由协议实现，协议通常需要在此 Invoker 中发送远程请求，export() 传入的 Invoker 由框架实现并传入，协议不需要关心。

注意：

协议不关心业务接口的透明代理，以 Invoker 为中心，由外层将 Invoker 转换为业务接口。
协议不一定要是 TCP 网络通讯，比如通过共享文件，IPC 进程间通讯等。

扩展接口

org.apache.dubbo.rpc.Protocol
org.apache.dubbo.rpc.Exporter
org.apache.dubbo.rpc.Invoker

public interface Protocol {
 /**
 * 暴露远程服务：<br>
 * 1. 协议在接收请求时，应记录请求来源方地址信息：RpcContext.getContext().setRemoteAddress();<br>
 * 2. export()必须是幂等的，也就是暴露同一个URL的Invoker两次，和暴露一次没有区别。<br>
 * 3. export()传入的Invoker由框架实现并传入，协议不需要关心。<br>
 * 
 * @param <T> 服务的类型
 * @param invoker 服务的执行体
 * @return exporter 暴露服务的引用，用于取消暴露
 * @throws RpcException 当暴露服务出错时抛出，比如端口已占用
 */
 <T> Exporter<T> export(Invoker<T> invoker) throws RpcException;
 
 /**
 * 引用远程服务：<br>
 * 1. 当用户调用refer()所返回的Invoker对象的invoke()方法时，协议需相应执行同URL远端export()传入的Invoker对象的invoke()方法。<br>
 * 2. refer()返回的Invoker由协议实现，协议通常需要在此Invoker中发送远程请求。<br>
 * 3. 当url中有设置check=false时，连接失败不能抛出异常，需内部自动恢复。<br>
 * 
 * @param <T> 服务的类型
 * @param type 服务的类型
 * @param url 远程服务的URL地址
 * @return invoker 服务的本地代理
 * @throws RpcException 当连接服务提供方失败时抛出
 */
 <T> Invoker<T> refer(Class<T> type, URL url) throws RpcException;
 
}

扩展配置

<!-- 声明协议，如果没有配置id，将以name为id -->
<dubbo:protocol id="xxx1" name="xxx" />
<!-- 引用协议，如果没有配置protocol属性，将在ApplicationContext中自动扫描protocol配置 -->
<dubbo:service protocol="xxx1" />
<!-- 引用协议缺省值，当<dubbo:service>没有配置prototol属性时，使用此配置 -->
<dubbo:provider protocol="xxx1" />

已知扩展

org.apache.dubbo.rpc.protocol.injvm.InjvmProtocol
org.apache.dubbo.rpc.protocol.dubbo.DubboProtocol
org.apache.dubbo.rpc.protocol.rmi.RmiProtocol
org.apache.dubbo.rpc.protocol.http.HttpProtocol
org.apache.dubbo.rpc.protocol.http.hessian.HessianProtocol
org.apache.dubbo.rpc.protocol.memcached.MemcachedProtocol
org.apache.dubbo.rpc.support.MockProtocol
org.apache.dubbo.rpc.protocol.redis.RedisProtocol
org.apache.dubbo.rpc.protocol.nativethrift.ThriftProtocol

扩展示例

Maven项目结构：

协议扩展

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

扩展说明

RPC 协议扩展，封装远程调用细节。

契约：

当用户调用 refer() 所返回的 Invoker 对象的 invoke() 方法时，协议需相应执行同 URL 远端 export() 传入的 Invoker 对象的 invoke() 方法。
其中，refer() 返回的 Invoker 由协议实现，协议通常需要在此 Invoker 中发送远程请求，export() 传入的 Invoker 由框架实现并传入，协议不需要关心。

注意

协议不关心业务接口的透明代理，以 Invoker 为中心，由外层将 Invoker 转换为业务接口。
协议不一定要是 TCP 网络通讯，比如通过共享文件，IPC 进程间通讯等。

扩展接口

org.apache.dubbo.rpc.Protocol
org.apache.dubbo.rpc.Exporter
org.apache.dubbo.rpc.Invoker

public interface Protocol {
 /**
 * 暴露远程服务：<br>
 * 1. 协议在接收请求时，应记录请求来源方地址信息：RpcContext.getContext().setRemoteAddress();<br>
 * 2. export()必须是幂等的，也就是暴露同一个URL的Invoker两次，和暴露一次没有区别。<br>
 * 3. export()传入的Invoker由框架实现并传入，协议不需要关心。<br>
 * 
 * @param <T> 服务的类型
 * @param invoker 服务的执行体
 * @return exporter 暴露服务的引用，用于取消暴露
 * @throws RpcException 当暴露服务出错时抛出，比如端口已占用
 */
 <T> Exporter<T> export(Invoker<T> invoker) throws RpcException;
 
 /**
 * 引用远程服务：<br>
 * 1. 当用户调用refer()所返回的Invoker对象的invoke()方法时，协议需相应执行同URL远端export()传入的Invoker对象的invoke()方法。<br>
 * 2. refer()返回的Invoker由协议实现，协议通常需要在此Invoker中发送远程请求。<br>
 * 3. 当url中有设置check=false时，连接失败不能抛出异常，需内部自动恢复。<br>
 * 
 * @param <T> 服务的类型
 * @param type 服务的类型
 * @param url 远程服务的URL地址
 * @return invoker 服务的本地代理
 * @throws RpcException 当连接服务提供方失败时抛出
 */
 <T> Invoker<T> refer(Class<T> type, URL url) throws RpcException;
 
}

扩展配置

<!-- 声明协议，如果没有配置id，将以name为id -->
<dubbo:protocol id="xxx1" name="xxx" />
<!-- 引用协议，如果没有配置protocol属性，将在ApplicationContext中自动扫描protocol配置 -->
<dubbo:service protocol="xxx1" />
<!-- 引用协议缺省值，当<dubbo:service>没有配置prototol属性时，使用此配置 -->
<dubbo:provider protocol="xxx1" />

已知扩展

org.apache.dubbo.rpc.protocol.injvm.InjvmProtocol
org.apache.dubbo.rpc.protocol.dubbo.DubboProtocol
org.apache.dubbo.rpc.protocol.rmi.RmiProtocol
org.apache.dubbo.rpc.protocol.http.HttpProtocol
org.apache.dubbo.rpc.protocol.http.hessian.HessianProtocol
org.apache.dubbo.rpc.support.MockProtocol

扩展示例

Maven项目结构：

需求

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

在大规模服务化之前，应用可能只是通过 RMI 或 Hessian 等工具，简单的暴露和引用远程服务，通过配置服务的URL地址进行调用，通过 F5 等硬件进行负载均衡。

服务配置

当服务越来越多时，服务 URL 配置管理变得非常困难，F5 硬件负载均衡器的单点压力也越来越大。 此时需要一个服务注册中心，动态地注册和发现服务，使服务的位置透明。并通过在消费方获取服务提供方地址列表，实现软负载均衡和 Failover，降低对 F5 硬件负载均衡器的依赖，也能减少部分成本。

服务依赖

当进一步发展，服务间依赖关系变得错踪复杂，甚至分不清哪个应用要在哪个应用之前启动，架构师都不能完整的描述应用的架构关系。 这时，需要自动画出应用间的依赖关系图，以帮助架构师理清关系。

服务容量

接着，服务的调用量越来越大，服务的容量问题就暴露出来，这个服务需要多少机器支撑？什么时候该加机器？ 为了解决这些问题，第一步，要将服务现在每天的调用量，响应时间，都统计出来，作为容量规划的参考指标。其次，要可以动态调整权重，在线上，将某台机器的权重一直加大，并在加大的过程中记录响应时间的变化，直到响应时间到达阈值，记录此时的访问量，再以此访问量乘以机器数反推总容量。

以上是 Dubbo 最基本的几个需求。

序列化安全

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

概述

Dubbo 支持序列化协议的扩展，理论上用户可以基于该扩展机制启用任意的序列化协议，这带来了极大的灵活的，但同时也要意识到其中潜藏的安全性风险。数据反序列化是最容易被被攻击者利用的一个环节，攻击者利用它执行 RCE 攻击等窃取或破坏服务端数据。用户在切换序列化协议或实现前，应充分调研目标序列化协议及其框架实现的安全性保障，并提前设置相应的安全措施（如设置黑/白名单）。 Dubbo 框架自身并不能直接保证目标序列化机制的安全性。

Dubbo 2.7 官方版本提供的序列化协议有如下几种：

Hessian2
Fastjson
Kryo
FST
JDK
Protostuff
Protocol Buffers
Avro
Gson

从 Dubbo 3.0 开始默认仅提供以下序列化协议支持：

Hessian2
JDK
Protocol Buffers

从 Dubbo 3.2 开始默认提供以下序列化协议支持：

Hessian2
Fastjson2
JDK
Protocol Buffers

出于安全性考虑，从 Dubbo 3.3 开始将默认仅提供以下序列化协议支持：

Hessian2
Fastjson2
Protocol Buffers

针对以上序列化扩展，在发现或收到相关的漏洞报告之后，Dubbo 官方会跟进并升级依赖到最新的安全版本，但最终的漏洞修复方案取决于序列化的框架实现。

针对使用 dubbo hessian2 版本的用户，Dubbo 官方会保证hessian2序列化机制的安全性并尽可能的修复上报的安全漏洞

此外，从 Dubbo 3.2 版本开始，对于 Hessian2 和 Fastjson2 默认采用白名单机制，如果您发现部分数据处理移除，可以参考文档进行配置。

全面加固

为了尽可能提高应用序列化的安全性，Dubbo3.0在序列化协议安全方面进行了升级加固，推荐使用 Tripe 协议的非 Wrapper 模式。该协议默认安全，但需要开发人员编写IDL文件。

Triple 协议 Wrapper 模式下，允许兼容其它序列化数据，提供了良好的兼容性。但其它协议可能存在反序列化安全缺陷，对于 Hessian2 协议，高安全属性用户应当按照 samples 代码指示，开启白名单模式，框架默认会开启黑名单模式，拦截恶意调用。

Dubbo 序列化机制介绍

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

支持的协议列表

以下是 Dubbo 框架支持的序列化协议列表，根据 triple、dubbo RPC 通信协议进行分类。

RPC协议	编程模式	序列化协议	配置方式	JDK版本	说明
triple	IDL	protobuf、 protobuf-json	默认值	8, 17, 21	使用 IDL 时的默认序列化方式，client 也可以选择 protobuf-json 序列化通信，无需额外配置
	Java接口	protobuf-wrapper	serialization=“hessian”	8, 17, 21	这种模式下采用的是两次序列化模式，即数据先被 hessian 序列化，再由 protobuf 序列化。为了支持与 IDL 同等的调用模型，易用性较好但性能略有下降
dubbo	Java接口	hessian	默认值，serialization=“hessian”	8, 17, 21	dubbo 协议默认序列化方式，具备兼容性好、高性能、跨语言的优势(java、go、c/c++、php、python、.net)
	Java接口	protostuff	serialization=“protostuff”	8	A java serialization library with built-in support for forward-backward compatibility (schema evolution) and validation.
	Java接口	gson	serialization=“gson”	8, 17, 21	谷歌推出的一款 json 序列化库
	Java接口	avro	serialization=“avro”	8, 17, 21	一款 Java 高性能序列化库
	Java接口	msgpack	serialization=“msgpack”	8, 17, 21	具备兼容性好，提供多语言（Java、C/C++、Python等）实现等优势
	Java接口	kryo	serialization=“kryo”	8, 17, 21	Kryo是一种非常成熟的序列化实现，已经在Twitter、Groupon、Yahoo以及多个著名开源项目（如Hive、Storm）中广泛的使用。
	Java接口	fastjson2	serialization=“fastjson2”	8, 17, 21	fastjson
	Java接口	更多扩展			dubbo-spi-extensions

性能对比报告

序列化对于远程调用的响应速度、吞吐量、网络带宽消耗等起着至关重要的作用，是我们提升分布式系统性能的最关键因素之一。

序列化协议安全

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

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

Dubbo3.0在序列化协议安全方面进行了升级加固，推荐使用Tripe协议非Wrapper模式。该协议默认安全，但需要开发人员编写IDL文件。

Triple协议Wrapper模式下，允许兼容其它序列化数据，提供了良好的兼容性。但其它协议可能存在反序列化安全缺陷，对于Hession2协议，高安全属性用户应当按照samples代码指示，开启白名单模式，框架默认会开启黑名单模式，拦截恶意调用。

不建议使用其它序列化协议，当攻击者可访问Provider接口时，其它序列化协议的安全缺陷，可能导致 Povider 接口命令执行。

若必须使用其它序列化协议，同时希望具备一定安全性。应当开启Token鉴权机制，防止未鉴权的不可信请求来源威胁Provider的安全性。开启Token鉴权机制时，应当同步开启注册中心的鉴权功能。

Dubbo 支持的 RPC 通信协议

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

Dubbo 作为一款 RPC 框架内置了高效的 RPC 通信协议，帮助解决服务间的编码与通信问题，目前支持的协议包括：

triple，基于 HTTP/1、HTTP/2 的高性能通信协议，100% 兼容 gRPC，支持 Unary、Streming 等通信模式；支持发布 REST 风格的 HTTP 服务。
dubbo，基于 TCP 的高性能私有通信协议，缺点是通用性较差，更适合在 Dubbo SDK 间使用；
任意协议扩展，通过扩展 protocol 可以之前任意 RPC 协议，官方生态库提供 JsonRPC、thrift 等支持。

协议概览

使用哪个协议？

开发者该如何确定使用哪一种协议那？ 以下是我们从使用场景、性能、编程易用性、多语言互通等方面对多个主流协议的对比分析：

协议	性能	网关友好	流式通信	多语言支持	编程API	说明
triple	高	高	支持，客户端流、服务端流、双向流	支持（Java、Go、Node.js、JavaScript、Rust）	Java Interface、Protobuf(IDL)	在多语言兼容、性能、网关、Streaming、gRPC 等方面最均衡的协议实现，官方推荐。
dubbo	高	低	不支持	支持（Java、Go）	Java Interface	性能最高的私有协议，但前端流量接入、多语言支持等成本较高
rest	低	高	不支持	支持	Java Interface	rest 协议在前端接入、互通等方面具备最高的灵活性，但对比 rpc 存在性能、弱类型等缺点。注意，rest 在 dubbo3 中仅是 triple 协议的一种发布形式

注意

自 3.3 版本开始，triple 协议支持以 rest 风格发布标准的 http 服务，因此框架中实际已不存在独立的 rest protocol 扩展实现。只是在文档说明上，我们依然选择将 triple 与 rest 作为独立的协议实现分开讲解，请大家注意。

协议默认值

以下是几个主要协议的具体开发、配置、运行态信息：

应用级服务发现基准测试

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

1 Benchmark 结论

对比 2.x 版本，Dubbo3 版本

服务发现资源利用率显著提升。
- 对比接口级服务发现，单机常驻内存下降 50%，地址变更期 GC 消耗下降一个数量级 (百次 -> 十次)
- 对比应用级服务发现，单机常驻内存下降 75%，GC 次数趋零

以下是详细压测过程与数据

2 应用级服务发现（地址推送链路）

此部分压测数据是由工商银行 Dubbo 团队基于内部生产数据给出，压测过程模拟了“生产环境地址+zookeeper”的服务发现架构。

2.1 环境

	描述
压测数据	提供者 500运行实例✖️8interface✖️5protocol，即每个提供者向注册中心注册40个URL，总计20000个URL，每个URL字符长度约1k。注册中心 2个独立zookeeper注册中心，服务提供者消费者采用并行配置。消费者配置1c2g，xmx=768，开启GC，从2个注册中心订阅，每5秒调用一次服务。运行20小时。
压测环境	Java version “1.8.0” Java(TM) SE Runtime Enviroment (build pxa6480sr3fp12-20160919_01(SR3 FP12)) IBM J9 VM (Build 2.8, JRE 1.8.0 Linux amd64-64 Compressed References 20160915_318796, JIT enabled, AOT enabled)

2.2 数据分析

图一服务发现模型内存占用变化

Dubbo3 接口级服务发现模型，常驻内存较 2.x 版本下降约 50%
Dubbo3 应用级服务发现模型，常驻内存较 2.x 版本下降约 75%

应用启动失败

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

在开发与生产部署过程中，由于各种非预期的变更，可能会出现应用无法启动的情况。对于 Dubbo 来说，通常启动失败时都会有类似以下的报错信息。

Caused by: java.lang.IllegalStateException: Dubbo Module[1.1.1] is stopping or stopped, can not start again

[DUBBO] Dubbo Application[1.1](first-dubbo-consumer) start failure

一句话总结

正确配置日志输出，往前翻到第一个报错的位置并进行处理。

排查方式

1 配置日志输出

目前 Dubbo 支持多种日志框架，如果环境中存在多种日志框架的支持（如 log4j 和 logback），Dubbo 会按照（log4j > slf4j > log4j2 > jcl）的顺序输出日志框架。

如果与预期的日志框架不同时，会出现日志无法输出的问题。此时可以通过以下的配置进行调整：

dubbo.application.logger=slf4j

注：3.2.0 及以上的版本中将自动分析日志框架是否存在配置，优选日志框架输出。

2 找到真正的报错信息

在正确配置日志输出之后，可以在日志中搜索 [DUBBO] Model start failed 或者 start failure 关键字，查看真正导致 Dubbo 启动失败的原因。

如下所示，启动失败的原因为有服务订阅找不到提供者。

[27/02/23 12:49:18:018 CST] main ERROR deploy.DefaultModuleDeployer: [DUBBO] Model start failed: Dubbo Module[1.1.1] start failed: java.lang.IllegalStateException: Failed to check the status of the service org.apache.dubbo.samples.api.GreetingsService. No provider available for the service org.apache.dubbo.samples.api.GreetingsService from the url consumer://30.221.144.195/org.apache.dubbo.samples.api.GreetingsService?application=first-dubbo-consumer&background=false&dubbo=2.0.2&environment=product&executor-management-mode=default&file-cache=true&interface=org.apache.dubbo.samples.api.GreetingsService&methods=sayHi&pid=54580&register.ip=30.221.144.195&release=3.2.0-beta.6-SNAPSHOT&side=consumer&sticky=false&timestamp=1677473358611&unloadClusterRelated=false to the consumer 30.221.144.195 use dubbo version 3.2.0-beta.6-SNAPSHOT, dubbo version: 3.2.0-beta.6-SNAPSHOT, current host: 30.221.144.195, error code: 5-14. This may be caused by , go to https://dubbo.apache.org/faq/5/14 to find instructions. 
java.lang.IllegalStateException: Failed to check the status of the service org.apache.dubbo.samples.api.GreetingsService. No provider available for the service org.apache.dubbo.samples.api.GreetingsService from the url consumer://30.221.144.195/org.apache.dubbo.samples.api.GreetingsService?application=first-dubbo-consumer&background=false&dubbo=2.0.2&environment=product&executor-management-mode=default&file-cache=true&interface=org.apache.dubbo.samples.api.GreetingsService&methods=sayHi&pid=54580&register.ip=30.221.144.195&release=3.2.0-beta.6-SNAPSHOT&side=consumer&sticky=false&timestamp=1677473358611&unloadClusterRelated=false to the consumer 30.221.144.195 use dubbo version 3.2.0-beta.6-SNAPSHOT

常见的原因

本章将介绍 Dubbo 中常见的启动失败原因。

元数据中心概述

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

元数据中心为 Dubbo 中的两类元数据提供了存取能力

1 地址发现元数据，用于应用级服务发现
2 服务运维元数据，用于外围运维系统如可视化控制台进行服务查询、测试等。

1 地址发现元数据

Dubbo3 中引入了应用级服务发现机制用来解决异构微服务体系互通与大规模集群实践的性能问题，应用级服务发现将全面取代 2.x 时代的接口级服务发现。同时为了保持 Dubbo 面向服务/接口的易用性、服务治理的灵活性，Dubbo 围绕应用级服务发现构建了一套元数据机制，即 接口 - 应用映射关系 与 接口配置元数据。

1.1 接口 - 应用映射关系

Dubbo 一直以来都能做到精确的地址发现，即只订阅 Consumer 声明要关心的服务及相关的地址列表，相比于拉取/订阅全量地址列表，这样做有很好的性能优势。在应用级服务发现模型中，想做到精确地址订阅并不容易，因为 Dubbo Consumer 只声明了要消费的接口列表，Consumer 需要能够将接口转换为 Provider 应用名才能进行精准服务订阅，

为此，Dubbo 需要在元数据中心维护这一份 接口名->应用名 的对应关系，Dubbo3 中通过 provider 启动的时候主动向元数据中心上报实现。接口 (service name) - 应用 (Provider application name) 的映射关系可以是一对多的，即一个 service name 可能会对应多个不同的 application name。

以 zookeeper 为例，映射关系保存在以下位置:

$ ./zkCli.sh
$ get /dubbo/mapping/org.apache.dubbo.demo.DemoService
$ demo-provider,two-demo-provider,dubbo-demo-annotation-provider

① 节点路径是 /dubbo/mapping/{interface name}

源码构建

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

代码签出

通过以下的这个命令签出最新的项目源码 ¹：

git clone https://github.com/apache/dubbo.git

分支

我们使用 master 作为主干版本的开发，使用分支作为维护版本。可以通过 https://github.com/apache/dubbo/tags 来查看所有版本的标签。

构建

Dubbo 使用 maven 作为构建工具。

要求

Java 1.8 以上的版本
Maven 2.2.1 或者以上的版本

构建之前需要配置以下的 MAVEN_OPTS

export MAVEN_OPTS=-Xmx1024m -XX:MaxPermSize=512m

使用以下命令做一次构建

mvn clean install

可以通过以下的构建命令来跳过单元测试

mvn install -Dmaven.test.skip

构建源代码 jar 包

通过以下命令以构建 Dubbo 的源代码 jar 包

mvn clean source:jar install -Dmaven.test.skip

并且修改你的样例项目中的 dubbo 依赖为本地仓库的 SANPSHOT 版本，然后使用远程 debug 来调试 dubbo。

IDE 支持

使用以下命令来生成 IDE 的工程

Intellij Idea

mvn idea:idea

eclipse

mvn eclipse:eclipse

在 eclipse 中导入

首先，需要在 eclipse 中配置 maven 仓库。通过 Preferences -> Java -> Build Path -> Classpath 定义 M2_REPO 的 classpath 变量指向本地的 maven 仓库。 ²

Apache 提交者注册流程

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

一、Apache 提交者的产生

项目孵化初始化提交者

项目孵化阶段，在孵化项目提案中，会有初始化提交者列表这一选项。确认你是初始化提交者的一员。项目在 apache 孵化器社区投票通过后，提交者可以开始准备注册账户了。可以参看孵化器 wiki

活跃的贡献者被选举为提交者

在后期的开发过程中，活跃的贡献者可以被选举为提交者。见如何成为 committer

二、个人开发者提交 ICLA

1、选择 apache id

在 apache 提交者列表页查看已经注册过的 apache id，

2、个人提交者授权协议（ICLA）：

下载 ICLA 模板，查找可用的 id。将 icla.pdf 个人信息填写正确后打印,签名、扫描、并当做附件发送邮件给秘书 secretary@apache.org，秘书会帮忙创建 apache 用户 id。同时会创建一个 your_id@apache.org 的邮箱，可以在 apache 提交者列表页查看查找用户是否已经创建。

3、导师帮助提交用户id创建请求

导师将帮助提交 apache 账户创建请求给 root 邮件组，会有人帮助建立 id。一般需要2天时间账户会建立，请等待并在 apache 提交者列表页查看查找用户是否已经创建。

三、加入apache开发者组

登陆 Apache 账户工具，在登陆页面点击"忘记密码"设置始化密码，会有一封密码重置邮件发送到 forward 邮箱(在孵化项目提案中提交的开发者邮件)
关于 apache 邮箱：apache.org 邮箱并没有自己的邮件内容存储服务器。它需要借用其他邮件提供商的邮件内容存储、分发功能。在很多投票环节是建议使用 apache 邮箱的。这里就有一个问题，怎么在其它邮箱里面配置 apache.org 邮箱转发功能：
- 收件箱：收取发送到 apache.org 的邮件。这个在第一步配置好 Apache 账户工具的 forward 邮箱就可以用 forward 邮箱收取邮件了
- 发件箱：将发出的邮件显示发件邮箱为 apache.org 邮箱。请参考：设置 apache 邮箱指南和 gmail 邮箱设置方式。其他邮箱服务的设置方式不方便找到，gmail 的最方便，建议换成 gmail 邮箱(不是广告)。
修改编辑页面的 homepage url，apache 提交者列表页中你的账户能加主页链接。
修改编辑页面的 github 账户(username)，提交确认后两个小时内会有邮件邀请你加入 github.com/apache-committers 组。这期间可以阅读 ASF 工作方式以对 ASF 开发做一些基本了解。

四、提交者获得对项目的写权限

GitBox 账户链接工具的操作

注册中心

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

Dubbogo 为注册中心抽象了一套接口如下：

// Registry Extension - Registry
type Registry interface {
	common.Node

	// Register is used for service provider calling, register services
	// to registry. And it is also used for service consumer calling, register
	// services cared about, for dubbo's admin monitoring.
	Register(url *common.URL) error

	// UnRegister is required to support the contract:
	// 1. If it is the persistent stored data of dynamic=false, the
	// registration data can not be found, then the IllegalStateException
	// is thrown, otherwise it is ignored.
	// 2. Unregister according to the full url match.
	// url Registration information, is not allowed to be empty, e.g:
	// dubbo://10.20.153.10/org.apache.dubbo.foo.BarService?version=1.0.0&application=kylin
	UnRegister(url *common.URL) error

	// Subscribe is required to support the contract:
	// When creating new registry extension, pls select one of the
	// following modes.
	// Will remove in dubbogo version v1.1.0
	// mode1: return Listener with Next function which can return
	// subscribe service event from registry
	// Deprecated!
	// subscribe(event.URL) (Listener, error)
	// Will replace mode1 in dubbogo version v1.1.0
	// mode2: callback mode, subscribe with notify(notify listener).
	Subscribe(*common.URL, NotifyListener) error

	// UnSubscribe is required to support the contract:
	// 1. If don't subscribe, ignore it directly.
	// 2. Unsubscribe by full URL match.
	// url Subscription condition, not allowed to be empty, e.g.
	// consumer://10.20.153.10/org.apache.dubbo.foo.BarService?version=1.0.0&application=kylin
	// listener A listener of the change event, not allowed to be empty
	UnSubscribe(*common.URL, NotifyListener) error
}

该接口主要包含四个方法，分别是注册、反注册、订阅、取消订阅。顾名思义，概括了客户端和服务端与注册中心交互的动作。针对普通接口级服务注册发现场景，在Provider 服务启动时，会将自身服务接口信息抽象为一个 url，该 url 包含了客户端发起调用所需的所有信息（ip、端口、协议等），服务端的注册中心组件会将该 url 写入注册中心（例如zk）。客户端启动后，在服务引用 Refer 步骤会通过注册中心组件订阅（Subscribe）需要的服务信息，获取到的服务信息以异步事件更新的形式写入客户端缓存，从而在服务发现成功后，可以根据拿到的服务 url 参数，向对应服务提供者发起调用。

注册中心概述

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

注册中心是 Dubbo 服务治理的核心组件，Dubbo 依赖注册中心的协调实现服务（地址）发现，自动化的服务发现是微服务实现动态扩缩容、负载均衡、、流量治理的基础。Dubbo 的服务发现机制经历了 Dubbo2 时代的接口级服务发现、Dubbo3 时代的应用级服务发现，具体可参见服务发现机制解析了解具体演进过程。

基本使用

开发应用时可以指定 Dubbo 注册中心（registry）组件，配置很简单，只需指定注册中心的集群地址即可：

以 Spring Boot 开发为例，在 application.yml 增加 registry 配置项目

dubbo
 registry
 address: {protocol}://{cluster-address}

其中，protocol 为选择的配置中心类型，cluster-address 为访问注册中心的集群地址，如

address: nacos://localhost:8848

如需集群格式地址可使用 backup 参数

address: nacos://localhost:8848?backup=localshot:8846,localshot:8847

流的语义保证

3.3.0 及之后的版本可不配置注册中心。而在 3.3.0 版本之前的 Dubbo 应用必须指定注册中心配置，即使不启用注册中心也要配置（可通过设置地址为空 address=‘N/A’ ）。

每个注册中心组件有自己特有的配置，可以用来控制命名空间、分组、鉴权等，具体可以参考 registry 配置参考手册或通过 parameters 参数进行扩展。

配置中心与元数据中心

配置中心、元数据中心是实现 Dubbo 高阶服务治理能力会依赖的组件，如流量管控规则等，相比于注册中心通常这两个组件的配置是可选的。

需要注意的是，对于部分注册中心类型（如 Zookeeper、Nacos 等），Dubbo 会默认同时将其用作元数据中心和配置中心（建议保持默认开启状态）。

dubbo
 registry
 address: nacos://localhost:8848

框架解析后的默认行为：

dubbo
 registry
 address: nacos://localhost:8848
 config-center
 address: nacos://localhost:8848
 metadata-report
 address: nacos://localhost:8848

如果您不想使用 nacos 作为配置中心，可以通过以下两个参数来调整或控制默认行为：

3.x 升级与兼容性指南

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

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

无需改动任何代码，直接升级到 Dubbo 3.0。

在 3.0 版本的设计与开发之初，我们就定下了兼容老版本 Dubbo 用户（2.5、2.6、2.7）的目标。因此，往 3.0 版本的升级过程将会是完全透明的，用户无需做任何业务改造，升级 3.x 后的框架行为将保持与 2.x 版本完全一致。

<dependency>
 <groupId>org.apache.dubbo</groupId>
 <artifactId>dubbo</artifactId>
 <version>3.0.0</version>
</dependency>

但也要注意，透明升级仅仅是通往 3.0 的第一步，因为 “框架行为保持一致” 也就意味着用户将无法体验到 3.0 的新特性。如果要启用 3.0 的带来的新特性，用户则需要进行一定的改造，我们称这个过程为迁移，这是一个按需开启的过程。

因此，对老用户而言，有两条不同的迁移路径：

分两步走，先以兼容模式推动业务升级到 3.0 版本（无需改造），之后在某些时机按需启用新特性（按需改造）；
升级与迁移同步完成，在业务升级到 3.0 版本的同时，完成改造并启用新特性；

Dubbo 3.0 提供的新特性包括：

新的地址发现模型（应用级服务发现）。
- 查看应用级服务发现的迁移步骤
- 查看应用级服务发现的使用方式
- 查看应用级服务发现设计与实现。
下一代基于 HTTP/2 的 Triple 协议。
- 查看Triple 协议迁移步骤
- 查看 Triple 协议使用方式
- 查看 Triple 协议设计与实现。
统一的路由规则。
- 查看统一路由规则的迁移步骤
- 查看统一路由规则使用方式
- 查看统一路由规则设计与实现

使用 Apache APISIX 代理 Dubbo 服务（triple协议）

Mon, 22 Apr 2024 00:00:00 +0000

关于如何用网关代理 triple 协议服务的原理介绍，请参见 HTTP 网关接入一节文档。

本文我们使用 Apache APISIX + triple 协议 + Nacos 注册中心 的组合，演示如何使用 Apache APISIX 代理 Dubbo 服务。

示例应用说明

本示例完整源码与部署资源文件可查看 dubbo-samples-gateway-triple-apisix，示例架构图如下：

在该示例中定义并发布了一个 org.apache.dubbo.samples.gateway.apisix.DemoService 的 triple 服务，接口定义为：

public interface DemoService {
	String sayHello(String name);
}

接口实现如下：

@DubboService
public class DemoServiceImpl implements DemoService {
 @Override
 public String sayHello(String name) {
 return "Hello " + name;
 }
}

Dubbo服务相关配置：

dubbo:
 application:
 name: gateway-apisix-triple
 registry:
 address: nacos://${nacos.address:127.0.0.1}:8848
 username: nacos
 password: nacos
 protocol:
 name: tri
 port: 50052

部署应用

在本地下载并启动 Nacos
运行以下命令，启动 Dubbo 应用。

工商银行 Dubbo3 应用级服务发现实践

Sun, 15 Jan 2023 00:00:00 +0000

问题分析

以下是经典的 Dubbo 的工作原理图，服务提供者和消费者通过注册中心协调实现地址的自动发现。

工商银行面临的主要瓶颈是在注册中心与服务消费端，接口级别地址的数量已经是亿级规模，一方面存储容量达到瓶颈、另一方面推送效率明显下降；而在消费端这一侧，Dubbo2 框架常驻内存已超 40%，每次地址推送带来的 cpu 等资源消耗率也非常高，影响正常的业务调用。

这是 Dubbo2 接口级服务发现架构在大规模集群场景下的固有问题（具体原因请查看应用级服务发现原理解析），通过常规的性能优化无法从根本上解决问题。因此工商银行采用了 Dubbo3 中提出的应用级服务发现模型，经过实测，新的服务发现模型能实现节点到注册中心间数据传输量 90% 的下降，这就使得注册中心的压力极大降低，同时消费端的框架常驻内存也实现超 50% 下降。

压测数据

下面是工商银行联合 Dubbo 社区给出的一组基于真实服务特点给出的模拟压测数据。

上图是对使用了应用级服务发现的消费端进程采样的内存对比数据。其中横轴是不同的 Dubbo 版本，纵轴是实际采样到的内存表现，可以看到 Dubbo 2.6、2.7 版本表现几乎一致，而升级到 3.0 版本后，即使不升级应用级服务发现，内存也降低接近 40%，而当切换到应用级服务发现之后，内存占用下降到只有原来的 30%。

上图是消费端的 GC 情况统计，同样的，横轴是不同的 Dubbo 版本，纵轴是实际采样到的 GC 表现。这里的压测数据，是通过模拟注册中心不停的往消费端进程推送地址列表的场景得到的。可以看到 Dubbo 2.6、2.7 版本表现几乎一致，而在 3.0 版本中切换到应用级服务发现之后，GC 已经趋近于零次。

0-2 - 非法属性值

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

可能的原因

这个提示是指用户配置的值与属性本身所需的数据类型并不匹配。比如 dubbo.comsumer.threads 属性只能接受数值属性，但是用户所输入的值混入了字母。

排查和解决步骤

根据配置项参考手册，查找出错的配置项，检查该项指定的类型，检查是否出现类型不一致的情况。

2-2 - 没有可用的 Provider（地址找不到）

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

可能的原因

Provider 服务没启动，或者注册中心（比如 ZooKeeper，Nacos，Consul）宕机了。
Dubbo 的服务配置有误差，必须保证服务名，组别（默认是 Dubbo），version 三者都正确。
访问的环境有误：通常我们会有开发环境、测试环境、线上生产环境等多套环境。有时候发布的服务到了测试环境，而访问调用时却走了开发环境。

排查和解决步骤

访问注册中心的 Ops 系统，查询对应的服务是否有提供者列表；同时检查调用者应用所在服务器的日志(一般每种注册服务的客户端都会有对应的日志记录)，查看是否有地址信息的推送/拉取记录。
如无，则表明发布者发布服务失败，检查发布者的应用启动是否成功。
如有服务，则检查调用者应用所连接的注册中心，确认跟预期的环境要匹配。
如上述都没有问题，检查是否配置了路由过滤的规则等。

这个错误码的 FAQ 页面参考了空冥同学的《Dubbo 常见错误及解决方法》。

所引文章通过 CC-BY-4.0 协议赋予了汇编的权利。在此向原作者表示感谢。

3-2 - 发布或推送服务失败

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

可能的原因

注册中心无法连接。
注册中心无法对外提供服务。

排查和解决步骤

服务与注册中心网络是否正常。
注册中心是否正常启动，并可通过第三方工具进行连接。
服务引用的版本与注册中心的版本是否存在版本兼容性问题。

3.0 升级至 3.1

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

功能修改点

1. Nacos Group 对齐（应用级服务发现）

在 Dubbo 2.7.x 中，配置在 Nacos Registry URL 上的 group 值是对齐 Nacos 注册中心中的 group 分组的。（group 可以当成类似 namespace 的软隔离）

在 Dubbo 3.0.x 中，配置在 Nacos Registry URL 上的 group 默认不使用，全部使用 DEFAULT_GROUP。（group 不再提供隔离功能）

在 Dubbo 3.1.x 中，配置在 Nacos Registry URL 上的 group 值将会重新对齐 Nacos 注册中心中的 group 分组的。

注意事项：

请检查注册中心 URL 上是否已经配置了 group 属性，如果是的话需要检查服务端和消费端的 group 是否都一致，如果不一致请修改为一致
如果不希望 group 重新对齐到 Nacos 注册中心中的 group 分组，可以配置 dubbo.nacos-service-discovery.use-default-group=false 全局属性值忽略该功能

4-2 - 序列化优化器初始发生错误

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

可能的原因

当前使用了 Kryo 和 FST 的序列化配置。

排查和解决步骤

Kryo 和 FST 序列化

5-2 - 注册/注销关闭钩子方法失败

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

可能的原因

自定义钩子方法,业务处理逻辑存在异常。

排查和解决步骤

检查自定义钩子方法，业务处理逻辑是否存在运行时异常。

6-2 - 客户端超时

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

超时是调用端发生在请求发出后，无法在指定的时间内获得对应的响应。

可能的原因

服务端确实处理比较慢，无法在指定的时间返回结果，调用端就自动返回一个超时的异常响应来结束此次调用。
服务端如果响应的比较快，但当客户端 Load 很高，负载压力很大的时候，会因为客户端请求发不出去、响应卡在 TCP Buffer 等问题，造成超时。因为客户端接收到服务端发来的数据或者请求服务端的数据，都会在系统层面排队，如果系统负载比较高，在内核态的时间占比就会加长，从而造成客户端获取到值时已经超时。
通常是业务处理太慢，可在服务提供方机器上执行：jstack [PID] > jstack.log 分析线程都卡在哪个方法调用上，这里就是慢的原因。如果不能调优性能，请调高 timeout 阈值。

排查和解决步骤

两边可能有 GC，检查服务端和客户端 GC 日志，耗时很长的 GC，会导致超时。超时的发生很可能意味着调用端或者服务端的资源（CPU，内存或者网络）出现了瓶颈，需要检查服务端的问题还是调用端的问题来排除 GC 抖动等嫌疑。
检查服务端的网络质量，比如重传率来排除网络嫌疑。
借助链路跟踪的分析服务（比如阿里的 ARMS ，开源的 OpenTracing 系的实现 Zipkin 、SkyWalking 等）来分析下各个点的耗时情况。

这个错误码的 FAQ 页面参考了空冥同学的《Dubbo 常见错误及解决方法》。所引文章通过 CC-BY-4.0 协议赋予了汇编的权利。在此向原作者表示感谢。

7-2 - QOS 已开启

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

可能的原因

QOS 已开启，默认为开启状态。

排查和解决步骤

请参考QOS 操作手册。

81-2 - ZK 销毁异常

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

可能的原因

当前实例已销毁完成。网络或已断开。

排查和解决步骤

可通过一些第三方的工具或者 jstack [PID] > jstack.log 分析堆栈信息，进行定位。

99-1 - 程序被打断

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

Dubbo 内部的未知错误。

可能的原因

程序收到来自 JVM 层面的打断通知，被迫停止阻塞等待

排查和解决步骤

此异常通常发生在线程池关闭或者应用关闭的过程中。请检查是否影响业务正常使用，如无影响可以忽略，如果有影响请参照对应的排查手册。更多的排查思路可以参考 99-0 一文。

API 配置

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

作为一款 RPC 框架，Dubbo 定义了一套完善的 API 接口，我们可以基于原生 API 开发 Dubbo 应用，关于如何使用原生API开发轻量RPC、微服务应用等的具体示例可查看使用教程 - API开发模式中的示例。它的适用场景包括以下两类：

轻量 RPC Server & Client，通常用于一些应用内、基础组件、中间件等内的简单远程调用场景
微服务应用，不依赖 Spring、Spring Boot 的情况下，直接用 API 开发微服务；同时，直接使用 API 对于一些网关或测试平台集成场景也可能比较有用。

目前的入口 API 主要有 Bootstrap、ServiceConfig、ReferenceConfig 等，分别用于不同场景下的 Dubbo 应用开发。

Bootstrap API

DubboBootstrap 实例代表一个 Dubbo 应用，是整个 Dubbo 应用的启动入口。在 DubboBootstrap 基础上，我们可以设置 protocol、service、registry、metrics 等来注册服务、连接注册中心等，这和我们在 Spring Boot 中调整 application.yml 或者 application.properties 文件是对等的作用。

官方推荐使用 DubboBootstrap.start() 作为应用的集中启动入口，但为了方便在进程启动后，在运行态单独发布一些服务，Dubbo 也允许直接调用 ServiceConfig.export() 或 ReferenceConfig.refer() 方法发布服务，这时 Service/Reference 会注册到默认的 DubboBootstrap 实例中，效果同调用 DubboBootstrap.service(…).start() 类似。

import org.apache.dubbo.config.bootstrap.DubboBootstrap;
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) {

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

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

 // 注意：ServiceConfig为重对象，内部封装了与注册中心的连接，以及开启服务端口
 // 服务提供者暴露服务配置
 ServiceConfig<DemoService> demoServiceConfig = new ServiceConfig<>();
 demoServiceConfig.setInterface(DemoService.class);
 demoServiceConfig.setRef(new DemoServiceImpl());
 demoServiceConfig.setVersion("1.0.0");

 // 第二个服务配置
 ServiceConfig<FooService> fooServiceConfig = new ServiceConfig<>();
 fooServiceConfig.setInterface(FooService.class);
 fooServiceConfig.setRef(new FooServiceImpl());
 fooServiceConfig.setVersion("1.0.0");

 ...

 // 通过DubboBootstrap简化配置组装，控制启动过程
 DubboBootstrap.getInstance()
 .application("demo-provider") // 应用配置
 .registry(new RegistryConfig("zookeeper://127.0.0.1:2181")) // 注册中心配置
 .protocol(protocol) // 全局默认协议配置
 .service(demoServiceConfig) // 添加ServiceConfig
 .service(fooServiceConfig)
 .start() // 启动Dubbo
 .await(); // 挂起等待(防止进程退出）
 }
}

import org.apache.dubbo.config.bootstrap.DubboBootstrap;
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 DemoConsumer {
 public static void main(String[] args) {

 // 引用远程服务
 ReferenceConfig<DemoService> demoServiceReference = new ReferenceConfig<DemoService>();
 demoServiceReference.setInterface(DemoService.class);
 demoServiceReference.setVersion("1.0.0");

 ReferenceConfig<FooService> fooServiceReference = new ReferenceConfig<FooService>();
 fooServiceReference.setInterface(FooService.class);
 fooServiceReference.setVersion("1.0.0");

 // 通过DubboBootstrap简化配置组装，控制启动过程
 DubboBootstrap bootstrap = DubboBootstrap.getInstance();
 bootstrap.application("demo-consumer") // 应用配置
 .registry(new RegistryConfig("zookeeper://127.0.0.1:2181")) // 注册中心配置
 .reference(demoServiceReference) // 添加ReferenceConfig
 .reference(fooServiceReference)
 .start(); // 启动Dubbo

 ...

 // 和本地bean一样使用demoService
 // 通过Interface获取远程服务接口代理，不需要依赖ReferenceConfig对象
 DemoService demoService = DubboBootstrap.getInstance().getCache().get(DemoService.class);
 demoService.sayHello("Dubbo");

 FooService fooService = fooServiceReference.get();
 fooService.greeting("Dubbo");
 }

}

基本配置

可以在 DubboBootstrap 中设置全局基本配置，包括应用配置、协议配置、注册中心、配置中心、元数据中心、模块、监控、SSL、provider 配置、consumer 配置等。

CLA 签署向导

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

以下情况，需要您签署 Apache ICLA：

在 Dubbo 被捐赠给 Apache 之前，您已经为 Dubbo 作出了很多贡献，并且您以前没有签署过 Alibaba-CLA。
您已经为 Dubbo 作出了很多贡献，并且您被邀请成为 Dubbo 提交者，且之前没有签署过 Alibaba-CLA 或者 Apache ICLA。

步骤

下载这篇 pdf 文档
编辑该文档，在必要的空格处填上适当的内容
打印
在打印好的文件上签字
扫描
发送一封邮件到secretary@apache.org，并抄送给private@dubbo.apache.org：
- 邮件标题为 “ICLA submission”
- 请在邮件正文附上您的github账号链接
- 请记得将您的 ICLA 文档放入邮件的附件里

空格填写必要说明

Mailing address：首选英文格式的公司地址
Preferred apache id(s)：如果您被邀请成为一名提交者，那么需要您填写一个apache账号，否则，可以不填
Notify project：Dubbo（意思就是Dubbo就是通知您签署ICLA的项目）

Debug参考文档

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

前置环境准备

docker环境
kubernetes环境（推荐docker desktop，图形化界面，还内嵌了一个小型的Kubernetes环境，后文演示也是基于docker desktop）
istio环境
dubbo-samples代码，master分支即可
dubbo 版本 >= 3.1.0 搭建 Kubernetes 环境目前 Dubbo 仅支持在 Kubernetes 环境下的 Mesh 部署，所以在运行启动本示例前需要先搭Kubernetes 环境。(建议采用docker desktop进行搭建，直接就可以运行一个kubernetes环境) https://docs.docker.com/desktop/install/mac-install/

搭建 Kubernetes 环境

目前 Dubbo 仅支持在 Kubernetes 环境下的 Mesh 部署，所以在运行启动本示例前需要先搭Kubernetes 环境。(建议采用docker desktop进行搭建，直接就可以运行一个kubernetes环境) https://docs.docker.com/desktop/install/mac-install/

搭建 Istio 环境

搭建 Istio 环境参考文档： Istio 安装文档(https://istio.io/latest/docs/setup/getting-started/) 注：安装 Istio 的时候需要开启 first-party-jwt 支持（使用 istioctl 工具安装的时候加上 –set values.global.jwtPolicy=first-party-jwt 参数），否则将导致客户端认证失败的问题。附安装命令参考：

curl -L https://istio.io/downloadIstio | sh -
cd istio-1.xx.x
export PATH=$PWD/bin:$PATH
istioctl install --set profile=demo --set values.global.jwtPolicy=first-party-jwt -y

构建dubbo和dubbo-samples环境

进入dubbo-dependencies-bom，更改grpc版本为1.41.0

<grpc.version>1.41.0</grpc.version>

进入dubbo-samples-xds目录，新增配置:

Dubbo 管理控制台介绍

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

目前的管理控制台已经发布 0.1 版本，结构上采取了前后端分离的方式，前端使用 Vue 和 Vuetify 分别作为 Javascript 框架和UI框架，后端采用 Spring Boot 框架。既可以按照标准的 Maven 方式进行打包，部署，也可以采用前后端分离的部署方式，方便开发，功能上，目前具备了服务查询，服务治理(包括 Dubbo 2.7 中新增的治理规则)以及服务测试三部分内容。

Maven方式部署

安装

git clone https://github.com/apache/dubbo-admin.git
cd dubbo-admin
mvn clean package
cd dubbo-admin-distribution/target
java -jar dubbo-admin-0.1.jar

访问

http://localhost:8080

前后端分离部署

前端

cd dubbo-admin-ui 
npm install 
npm run dev

后端

cd dubbo-admin-server
mvn clean package 
cd target
java -jar dubbo-admin-server-0.1.jar

访问

http://localhost:8081

前后端分离模式下，前端的修改可以实时生效

配置: ¹

配置文件为：

dubbo-admin-server/src/main/resources/application.properties

主要的配置有：

admin.config-center=zookeeper://127.0.0.1:2181
admin.registry.address=zookeeper://127.0.0.1:2181
admin.metadata-report.address=zookeeper://127.0.0.1:2181

三个配置项分别指定了配置中心，注册中心和元数据中心的地址，关于这三个中心的详细说明，可以参考这里。

也可以和 Dubbo 2.7 一样，在配置中心指定元数据和注册中心的地址，以 zookeeper 为例，配置的路径和内容如下:

dubbo-pilot Control Plane 部署

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

1 总体目标

控制面编译和镜像构建
使用 istioctl 在 kubernetes 环境部署
如何对控制面程序 debug

2 基本流程

这个例子将演示如何在编译 dubbo-pilot 控制平面并在 kubernetes 环境下如何使用 istioctl 进行部署

本地启动控制平面，对 dubbo-pilot 进行启动和 debug
使用 istioctl 在 k8s 环境启动和 debug

3 详细步骤

3.1 环境要求

Golang
Docker
Minikube/Kind
Kubectl
Dlv

3.2 本地部署

3.2.1 编译

编译 docker-builder

cd dubbo-go-pixiu/tools/docker-builder && go install

docker-builder -h:

Builds Istio docker images

Usage:
 [flags]

Flags:
 --architecures strings architectures to build (default [linux/amd64])
 --base-version string base version to use (default "latest")
 --builder string type of builder to use. options are crane or docker (default "docker")
 -h, --help help for this command
 --hub strings docker hub(s) (default [localhost:5000])
 --istio-version string istio version to use (default "1.14-dev")
 --kind-load kind cluster to load into
 --no-cache disable caching
 --no-clobber do not allow pushing images that already exist
 --proxy-version string proxy version to use (default "7ae8e27f274b33dc2f4d83100aea5971ed6698d3")
 --push push targets to registry
 --save save targets to tar.gz
 --tag strings docker tag(s) (default [latest])
 --targets strings targets to build (default [app,app_sidecar_centos_7,app_sidecar_debian_11,app_sidecar_ubuntu_jammy,app_sidecar_ubuntu_xenial,ext-authz,install-cni,istioctl,operator,pilot,proxyv2])
 --variants strings variants to build (default [default])
 --version show build version

使用 docker-builder 自动编译 && 构建镜像

编译 istioctl

Dubbo2 协议规范

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

协议规范 Specification

Magic - Magic High & Magic Low (16 bits)

标识协议版本号，Dubbo 协议：0xdabb
Req/Res (1 bit)

标识是请求或响应。请求： 1; 响应： 0。
2 Way (1 bit)

仅在 Req/Res 为1（请求）时才有用，标记是否期望从服务器返回值。如果需要来自服务器的返回值，则设置为1。
Event (1 bit)

标识是否是事件消息，例如，心跳事件。如果这是一个事件，则设置为1。
Serialization ID (5 bit)

标识序列化类型：比如 fastjson 的值为6。
Status (8 bits)

仅在 Req/Res 为0（响应）时有用，用于标识响应的状态。
- 20 - OK
- 30 - CLIENT_TIMEOUT
- 31 - SERVER_TIMEOUT
- 40 - BAD_REQUEST
- 50 - BAD_RESPONSE
- 60 - SERVICE_NOT_FOUND
- 70 - SERVICE_ERROR
- 80 - SERVER_ERROR
- 90 - CLIENT_ERROR
- 100 - SERVER_THREADPOOL_EXHAUSTED_ERROR
Request ID (64 bits)

通过网关将 http 流量接入 Dubbo 后端服务

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

由于 dubbo 协议是基于 TCP 的二进制私有协议，因此更适合作为后端微服务间的高效 RPC 通信协议，这也导致 dubbo 协议对于前端流量接入不是很友好。在 Dubbo 框架中，有两种方式可以帮助开发者解决这个问题：

多协议发布【推荐】，为 dubbo 协议服务暴露 rest 风格的 http 协议访问方式，这种模式架构上会变得非常简单，通用的网关产品即可支持。
通过网关实现 http->dubbo 协议转换，这种方式需要将 http 协议转换为后端服务能识别的 dubbo 协议，要求网关必须支持 dubbo 协议。

同时发布 http、dubbo 协议

如果我们能让一个服务同时发布 dubbo、http 协议，这样后端调用是基于高效的 dubbo 二进制协议，同时浏览器、web服务等前端设施也可以用 http 协议访问到相同的服务。好消息是，Dubbo 框架支持为同一个服务发布多个协议，并且支持客户端通过同一个端口以不同的协议访问服务，如下所示：

为了实现同时发布 dubbo、http 协议，我们只需要在配置文件中增加一行配置即可：

dubbo:
 protocol:
 dubbo: dubbo
 port: 20880
 ext-protocol: tri

增加 ext-protocol: tri 配置后，进程就可以在 20880 端口上提供 http 服务了，这点我们从之前的 triple 协议中有过具体了解了，启用应用后就可以在 20880 端口访问：

curl \
 --header "Content-Type: application/json" \
 --data '["Dubbo"]' \
 http://localhost:20880/org.apache.dubbo.protocol.multiple.demo.DemoService/sayHello

此时，网关就可以直接以 http 方式接入后端 dubbo 服务，任何 http 网关都可以非常容易接入，操作非常简洁明了。

基于 TCP 的 RPC 通信协议 - dubbo

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

本示例演示了如何开发基于 dubbo 协议通信的服务，可在此查看本示例的完整代码：

注意

为了保证老版本兼容性，Dubbo 3.3.0 及之前版本的默认协议都是 dubbo。但如果您是新用户，正在考虑使用 Dubbo 构建一套全新的微服务系统，我们推荐您在应用中明确配置使用 triple 协议。

运行示例

你可以跟随以下步骤，尝试运行本文档对应的示例源码。

首先，可通过以下命令下载示例源码

git clone --depth=1 https://github.com/apache/dubbo-samples.git

进入示例源码目录：

cd dubbo-samples/2-advanced/dubbo-samples-dubbo

使用 maven 打包示例：

mvn clean install -DskipTests

启动提供者

运行以下命令启动提供者：

java -jar ./dubbo-samples-dubbo-provider/target/dubbo-samples-dubbo-provider-1.0-SNAPSHOT.jar

启动消费者

运行以下命令：

java -jar ./dubbo-samples-dubbo-consumer/target/dubbo-samples-dubbo-consumer-1.0-SNAPSHOT.jar

源码讲解

定义服务

首先是服务定义，使用 dubbo 协议时，我们首选需要通过 Java Interface 定义 Dubbo 服务。

public interface DemoService {
 String sayHello(String name);
}

服务提供者

其次，对于提供者一侧而言，需要提供服务的具体实现。

@DubboService
public class DemoServiceImpl implements DemoService {
 @Override
 public String sayHello(String name) {
 return "Hello " + name;
 }
}

配置使用 dubbo 协议：

Filter

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

在 RPC框架 - Filter请求拦截一节中，我们了解了 Filter 的工作机制，以及 Dubbo 框架提供的一些内置 Filter 实现。在本文中，我们来了解如何扩展自定义的过滤器实现：一个可以对返回的结果进行统一的处理、验证等统一 Filter 处理器，减少对开发人员的打扰。

本示例的完整源码请参见 dubbo-samples-extensibility。除了本示例之外，Dubbo 核心仓库 apache/dubbo 以及扩展库 apache/dubbo-spi-extensions 中的众多 Filter 实现，都可以作为扩展参考实现。

任务详情

对所有调用Provider服务的请求在返回的结果的后面统一添加's customized AppendedFilter。

实现方式

在Provider中自定义一个Filter，在Filter中修改返回结果。

代码结构

src
 |-main
 |-java
 |-org
 |-apache
 |-dubbo
 |-samples
 |-extensibility
 |-filter
 |-provider
 |-AppendedFilter.java (实现Filter接口)
 |-resources
 |-META-INF
 |-application.properties (Dubbo Provider配置文件)
 |-dubbo
 |-org.apache.dubbo.rpc.Filter (纯文本文件)

代码详情

package org.apache.dubbo.samples.extensibility.filter.provider;

import org.apache.dubbo.rpc.Filter;
import org.apache.dubbo.rpc.Result;
import org.apache.dubbo.rpc.Invoker;
import org.apache.dubbo.rpc.Invocation;
import org.apache.dubbo.rpc.RpcException;
import org.apache.dubbo.rpc.AsyncRpcResult;

public class AppendedFilter implements Filter {

 @Override
 public Result invoke(Invoker<?> invoker, Invocation invocation) throws RpcException {
 Result result= invoker.invoke(invocation);
 // Obtain the returned value
 Result appResponse = ((AsyncRpcResult) result).getAppResponse();
 // Appended value
 appResponse.setValue(appResponse.getValue()+"'s customized AppendedFilter");
 return result;
 }
}

SPI配置

在resources/META-INF/dubbo/org.apache.dubbo.rpc.Filter文件中添加如下配置：

Grafana

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

Grafana 是一种开源的监控解决方案，可用于为 Dubbo 配置可视化仪表板，您可以使用 Grafana 来监控 Dubbo 集群的运行状况。

配置可视化控制面板

以下是 Dubbo 社区提供的默认指标面板，您配置好数据源并直接导入使用即可。如果默认面板不能满足要求，您还可以自定义 Grafana 面板。

您可以通过以下几种方式快速的导入 Grafana 监控面板。

方式一：Kubernetes 安装

你可以使用 Dubbo 社区提供的示例配置快速安装 Grafana，安装后的 Grafana 提供了社区默认指标面板视图。

kubectl create -f https://raw.githubusercontent.com/apache/dubbo-kubernetes/master/deploy/kubernetes/grafana.yaml

你可能需要端口映射获得访问地址 $ kubectl port-forward service/grafana 3000:3000，打开浏览器访问页面 http://localhost:3000。

获取登录信息

kubectl get secrets grafana -o jsonpath="{.data.admin-user}" | base64 --decode ; echo && kubectl get secrets grafana -o jsonpath="{.data.admin-password}" | base64 --decode ; echo

方式二：向已经安装好的集群导入 dashboard

如果你已经有安装好的 Grafana 服务了，则还可以通过 Grafana 控制台的导入菜单导入 dashboard。根据 Grafana 的要求，导入 dashboard 的过程中需要同时指定 Prometheus 数据源地址。

Hessian

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

1 介绍

Hessian序列化是一种支持动态类型、跨语言、基于对象传输的网络协议，Java对象序列化的二进制流可以被其他语言（如，c++，python）。特性如下：

自描述序列化类型。不依赖外部描述文件或者接口定义，用一个字节表示常用的基础类型，极大缩短二进制流。
语言无关，支持脚本语言
协议简单，比Java原生序列化高效
相比hessian1，hessian2中增加了压缩编码，其序列化二进制流大小是Java序列化的50%，序列化耗时是Java序列化的30%，反序列化耗时是Java序列化的20%。

2 使用方式

在 Dubbo 框架中，当使用 dubbo 通信协议时，默认使用 Hessian2 作为序列化。

2.1 配置启用

# application.yml (Spring Boot)
dubbo:
 protocol:
 serialization: hessian2

或

# dubbo.properties
dubbo.protocol.serialization=hessian2

# or
dubbo.consumer.serialization=hessian2

# or
dubbo.reference.com.demo.DemoService.serialization=hessian2

或

<dubbo:protocol serialization="hessian2" />

 <!-- or -->
<dubbo:consumer serialization="hessian2" />

 <!-- or -->
<dubbo:reference interface="xxx" serialization="hessian2" />

Istio 环境部署 Dubbo-go 应用

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

在本章节中，我们将使用应用模板快速创建一组 Dubbo-go Server和 Client 端应用，部署在 Istio 集群中；观察、调试和验证服务发现和调用成功。

1. 准备工作

dubbo-go cli 工具和依赖工具已安装、grpc_cli (如需本地调试)。
docker、helm、kubectl 环境已安装。（arm 机器需支持 docker buildx）
任务【istio 环境部署】已完成

2. 开发 server 端 Dubbo-go 应用

2.1 使用 dubbogo-cli 创建项目模板

$ mkdir mesh-app-server
$ cd mesh-app-server
$ dubbogo-cli newApp . 
$ tree .
.
├── Makefile
├── api
│ └── api.proto
├── build
│ └── Dockerfile
├── chart
│ ├── app
│ │ ├── Chart.yaml
│ │ ├── templates
│ │ │ ├── _helpers.tpl
│ │ │ ├── deployment.yaml
│ │ │ ├── service.yaml
│ │ │ └── serviceaccount.yaml
│ │ └── values.yaml
│ └── nacos_env
│ ├── Chart.yaml
│ ├── templates
│ │ ├── _helpers.tpl
│ │ ├── deployment.yaml
│ │ └── service.yaml
│ └── values.yaml
├── cmd
│ └── app.go
├── conf
│ └── dubbogo.yaml
├── go.mod
├── go.sum
└── pkg
 └── service
 └── service.go

生成项目包括几个目录：

Java SDK Release 流程

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

理解 Apache 发布的内容和流程

请参考以下链接，找到更多关于 ASF 的发布指南:

本地构建环境准备

主要包括签名工具、Maven 仓库认证相关准备

安装GPG

详细文档请参见这里, Mac OS 下配置如下

$ brew install gpg
$ gpg --version #检查版本，应该为2.x

用gpg生成key

根据提示，生成 key

$ gpg --full-gen-key
gpg (GnuPG) 2.0.12; Copyright (C) 2009 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Please select what kind of key you want:
 (1) RSA and RSA (default)
 (2) DSA and Elgamal
 (3) DSA (sign only)
 (4) RSA (sign only)
Your selection? 1
RSA keys may be between 1024 and 4096 bits long.
What keysize do you want? (2048) 4096
Requested keysize is 4096 bits
Please specify how long the key should be valid.
 0 = key does not expire
 <n> = key expires in n days
 <n>w = key expires in n weeks
 <n>m = key expires in n months
 <n>y = key expires in n years
Key is valid for? (0) 
Key does not expire at all
Is this correct? (y/N) y

GnuPG needs to construct a user ID to identify your key.

Real name: Robert Burrell Donkin
Email address: rdonkin@apache.org
Comment: CODE SIGNING KEY
You selected this USER-ID:
 "Robert Burrell Donkin (CODE SIGNING KEY) <rdonkin@apache.org>"

Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O
You need a Passphrase to protect your secret key. # 填入密码，以后打包过程中会经常用到

查看 key id

$ gpg --list-keys
pub rsa4096/28681CB1 2018-04-26 # 28681CB1就是key id
uid [ultimate] liujun (apache-dubbo) <liujun@apache.org>
sub rsa4096/D3D6984B 2018-04-26

# 通过key id发送public key到keyserver
$ gpg --keyserver pgpkeys.mit.edu --send-key 28681CB1
# 其中，pgpkeys.mit.edu为随意挑选的keyserver，keyserver列表为：https://sks-keyservers.net/status/，为相互之间是自动同步的，选任意一个都可以。

PS: 上文bash中两个server地址均无法打开，可以使用直接使用网页上传: https://keyserver.ubuntu.com/

部署 Dubbo 应用到 Kubernetes 环境

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

这种模式与传统的非 Kubernetes 部署并无太大差异，如下图所示，仍然使用 Nacos 或者 Zookeeper 等作为注册中心，只不过将 Kubernetes 作为应用生命周期调度的底层平台。

安装 Nacos

在 Kubernetes 模式下，我们推荐使用 dubboctl 快速安装 Nacos、dubbo-control-plane、prometheus 等组件：

$ dubboctl install --profile=demo

提示

请查看 dubboctl 了解更多细节
您也可以在此了解 Nacos 官方提供的 Kubernetes 集群安装方案

部署应用

我们仍然以 快速开始 中的项目为例，演示应用打包部署的具体步骤。

首先，克隆示例项目到本地：

$ git clone -b master --depth 1 https://github.com/apache/dubbo-samples

切换到示例目录：

$ cd dubbo-samples/11-quickstart

打包镜像

$ dubboctl build
# 具体写一下推送到 docker 仓库

部署

$ dubboctl deploy

以下是生成的完整 Kubernetes manifests：

执行以下命令，将应用部署到 Kubernetes 集群：

$ kubectl apply -f xxx.yml

查看部署状态

如果之前已经使用 dubboctl 安装 dubbo-control-plane，则可以通过以下方式查看服务部署情况：

Kubernetes

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

本章节介绍如何在 Kubernetes 集群中安装 Pixiu Gateway。需要注意的是，手动安装方式在配置灵活性方面不如 Helm 安装方式。如果需要对 Pixiu Gateway 的安装过程进行更精细的控制，建议使用 Helm 方式进行部署。

使用 YAML 安装

kubectl apply --server-side -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.3.0/standard-install.yaml
kubectl apply -k https://github.com/apache/dubbo-go-pixiu/controllers/config/crd?ref=develop

创建 Pixiu Gateway

kubectl apply -f https://raw.githubusercontent.com/apache/dubbo-go-pixiu-samples/main/gateway/k8s/pixiu-gateway.yaml

NAME READY STATUS RESTARTS AGE
pixiu-3465d618-7456884484-5rzs9 1/1 Running 0 37s
pixiu-gateway-864764d586-wgvsx 1/1 Running 0 57s

KVCache 卸载与分布式管理调度

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

AI KVCache 过滤器配置

本文档说明如何在 Dubbo-go-Pixiu 中配置和使用 dgp.filter.ai.kvcache 过滤器。

该过滤器通过对接 vLLM（/tokenize）与 LMCache controller API（/lookup、/pin、/compress、/evict），实现：

cache 感知的路由提示
异步缓存管理动作触发
主请求链路非阻塞

架构与请求链路

dgp.filter.ai.kvcache 是一个 HTTP Decode 过滤器。典型处理流程如下：

读取请求体，提取 model 与 prompt（必要时从 messages 回退提取）。
在 TokenManager 中记录本地热点统计（model + prompt）。
尝试 cache 感知路由：
- 从本地 token cache 获取 token
- 调用 LMCache /lookup
- 把优选端点提示写入上下文（llm_preferred_endpoint_id）
启动异步缓存管理协程（best-effort）：
- 调用 vLLM /tokenize
- 必要时调用 LMCache /lookup
- 按策略执行 compress / pin / evict
立即放行后续过滤器链（主请求不被缓存管理阻塞）。

路由约定（重点）

当前 cache 路由依赖 instance id 对齐：

kvcache 过滤器在上下文写入 llm_preferred_endpoint_id
dgp.filter.llm.proxy 读取该值并按 endpoint.id 选目标实例

因此要生效必须满足：

metrics监控

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

Dubbo 支持采集运行态 Metrics 指标并接入 Prometheus、Grafana 系统，实现对微服务集群的可视化监控，以下是一个具体的使用示例，可查看示例完整源码。

server/main.go - is the main definition of the service, handler and rpc server
client/main.go - is the rpc client
proto - contains the protobuf definition of the API

How to run

Run server

go run ./go-server/cmd/main.go

test server work as expected:

curl \
 --header "Content-Type: application/json" \
 --data '{"name": "Dubbo"}' \
 http://localhost:20000/greet.GreetService/Greet

Run client

go run ./go-client/cmd/main.go

deploy to local

install prometheus and open prometheus config file prometheus.yml, write the config like this

Multicast 注册中心

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

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

Multicast 注册中心不需要启动任何中心节点，只要广播地址一样，就可以互相发现。

提供方启动时广播自己的地址
消费方启动时广播订阅请求
提供方收到订阅请求时，单播自己的地址给订阅者，如果设置了 unicast=false，则广播给订阅者
消费方收到提供方地址时，连接该地址进行 RPC 调用。

组播受网络结构限制，只适合小规模应用或开发阶段使用。组播地址段: 224.0.0.0 - 239.255.255.255

配置

<dubbo:registry address="multicast://224.5.6.7:1234" />

或

<dubbo:registry protocol="multicast" address="224.5.6.7:1234" />

为了减少广播量，Dubbo 缺省使用单播发送提供者地址信息给消费者，如果一个机器上同时启了多个消费者进程，消费者需声明 unicast=false，否则只会有一个消费者能收到消息; 当服务者和消费者运行在同一台机器上，消费者同样需要声明unicast=false，否则消费者无法收到消息，导致No provider available for the service异常：

<dubbo:application name="demo-consumer">
 <dubbo:parameter key="unicast" value="false" />
</dubbo:application>

或

<dubbo:consumer>
 <dubbo:parameter key="unicast" value="false" />
</dubbo:consumer>

Multicast 注册中心

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

Multicast 注册中心不需要启动任何中心节点，只要广播地址一样，就可以互相发现。

提供方启动时广播自己的地址
消费方启动时广播订阅请求
提供方收到订阅请求时，单播自己的地址给订阅者，如果设置了 unicast=false，则广播给订阅者
消费方收到提供方地址时，连接该地址进行 RPC 调用。

组播受网络结构限制，只适合小规模应用或开发阶段使用。组播地址段: 224.0.0.0 - 239.255.255.255

配置

<dubbo:registry address="multicast://224.5.6.7:1234" />

或

<dubbo:registry protocol="multicast" address="224.5.6.7:1234" />

<dubbo:application name="demo-consumer">
 <dubbo:parameter key="unicast" value="false" />
</dubbo:application>

或

<dubbo:consumer>
 <dubbo:parameter key="unicast" value="false" />
</dubbo:consumer>

Nacos

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

1 预备工作

了解 Dubbo 基本开发步骤
参考 Nacos 启动 Nacos server

当Dubbo使用3.0.0及以上版本时，需要使用Nacos 2.0.0及以上版本

2 使用说明

Dubbo 融合 Nacos 成为元数据中心的操作步骤非常简单，大致分为 增加 Maven 依赖 以及 配置元数据中心 两步。

如果元数据地址(dubbo.metadata-report.address)也不进行配置，会使用注册中心的地址来用作元数据中心。

2.1 增加 Maven 依赖

如果项目已经启用 Nacos 作为注册中心，则无需增加任何额外配置。

如果未启用 Nacos 注册中心，则请参考为注册中心增加 Nacos 依赖。

2.2 启用 Nacos 配置中心

<dubbo:metadata-report address="nacos://127.0.0.1:8848"/>

或者

dubbo
 metadata-report
 address: nacos://127.0.0.1:8848

或者

dubbo.metadata-report.address=nacos://127.0.0.1:8848

或者

MetadataReportConfig metadataConfig = new MetadataReportConfig();
metadataConfig.setAddress("nacos://127.0.0.1:8848");

address 格式请参考 Nacos 注册中心 - 启用配置

3 高级配置

完整配置参数请参考 metadata-report-config。

4 工作原理

4.1 服务运维元数据

在 Nacos 的控制台上可看到服务提供者、消费者注册的服务运维相关的元数据信息：

在 Nacos 中，本身就存在配置中心这个概念，正好用于元数据存储。在配置中心的场景下，存在命名空间- namespace 的概念，在 namespace 之下，还存在 group 概念。即通过 namespace 和 group 以及 dataId 去定位一个配置项，在不指定 namespace 的情况下，默认使用 public 作为默认的命名空间。

OTlp

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

概述

这个案例展示了在 Dubbo 项目中以 OpenTelemetry 作为 Tracer，将 Trace 信息上报到 Otlp Collector，再由 collector 转发至 Zipkin、Jagger。代码地址

有三部分组成：

dubbo-samples-spring-boot-tracing-otel-oltp-interface
dubbo-samples-spring-boot-tracing-otel-oltp-provider
dubbo-samples-spring-boot-tracing-otel-oltp-consumer

案例架构图

快速开始

安装 & 启动 Otlp Collector

按照 OpenTelemetry Collector Quick Start 去启动 otlp collector.

启动 Provider

直接运行org.apache.dubbo.springboot.demo.provider.ProviderApplication directly from IDE.

启动 Consumer

Start org.apache.dubbo.springboot.demo.consumer.ConsumerApplication directly from IDE.

查看 Trace 信息

在浏览器中打开zipkin看板 http://localhost:9411/zipkin/ :

在浏览器中打开Jaeger看板 http://localhost:16686/search :

如何在SpringBoot项目中使用

1. 在你的项目中添加依赖

对于 SpringBoot 项目，你可以使用dubbo-spring-boot-tracing-otel-otlp-starter ：


<!-- OpenTelemetry as Tracer, Otlp as exporter -->
<dependency>
 <groupId>org.apache.dubbo</groupId>
 <artifactId>dubbo-spring-boot-tracing-otel-otlp-starter</artifactId>
</dependency>

2. 配置

application.yml

dubbo:
 tracing:
 enabled: true # default is false
 sampling:
 probability: 0.5 # sampling rate, default is 0.1
 propagation:
 type: W3C # W3C/B3 default is W3C
 tracing-exporter:
 otlp-config:
 endpoint: http://localhost:4317
 timeout: 10s # default is 10s
 compression-method: none # none/gzip The method used to compress payloads, default is "none"
 headers: # customized added headers, default is empty
 auth: admin

# tracing info output to logging
logging:
 level:
 root: info
 pattern:
 console: '[%d{dd/MM/yy HH:mm:ss:SSS z}] %t %5p %c{2} [%X{traceId:-}, %X{spanId:-}]: %m%n'

如何基于Dubbo API使用

1. 在你的项目中添加依赖

 <!-- 必选，dubbo-tracing核心依赖 -->
 <dependency>
 <groupId>org.apache.dubbo</groupId>
 <artifactId>dubbo-tracing</artifactId>
 </dependency>
 <!-- Opentelemetry as Tracer -->
 <dependency>
 <groupId>io.micrometer</groupId>
 <artifactId>micrometer-tracing-bridge-otel</artifactId>
 </dependency>
 <!-- OTlp as exporter -->
 <dependency>
 <groupId>io.opentelemetry</groupId>
 <artifactId>opentelemetry-exporter-otlp</artifactId>
 </dependency>

2. 配置

TracingConfig tracingConfig = new TracingConfig();
// 开启dubbo tracing
tracingConfig.setEnabled(true);
// 设置采样率
tracingConfig.setSampling(new SamplingConfig(1.0f));
// 设置Propagation，默认为W3C，可选W3C/B3
tracingConfig.setPropagation(new PropagationConfig("W3C"));
// 设置trace上报
ExporterConfig exporterConfig = new ExporterConfig();
// 设置将trace上报到Zipkin
exporterConfig.setZipkin(new ExporterConfig.OtlpConfig("http://localhost:4317", Duration.ofSeconds(10), "none"));
tracingConfig.setExporter(exporterConfig);

PixiuFilterPolicy

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

概述

PixiuFilterPolicy 是一个自定义资源扩展，用于为 Pixiu Gateway 配置特定过滤器的策略。

用例

提供声明式方式来配置过滤器，而无需直接修改 Gateway 或 HTTPRoute 资源
支持多种过滤器，包括身份验证、授权、速率限制和协议代理
将过滤器配置应用于 Gateway、HTTPRoute 或其他 Gateway API 资源
为 Gateway 中的特定监听器配置过滤器

为 HTTPRoute 启用基于 JWT 的身份验证：

apiVersion: pixiu.apache.org/v1alpha1
kind: PixiuFilterPolicy
metadata:
 name: jwt-filter-policy
 namespace: default
spec:
 targetRef:
 group: gateway.networking.k8s.io
 kind: HTTPRoute
 name: backend
 filterType: dgp.filter.http.auth.jwt
 config:
 rules:
 - match:
 prefix: /health
 - match:
 prefix: /user
 requires:
 requires_any:
 provider_name: provider1
 providers:
 - name: provider1
 from_headers:
 name: Authorization
 value_prefix: "Bearer "
 issuer: issuer1
 local_jwks:
 inline_string: "{...}"

应用速率限制以保护后端服务

从 Prometheus 查询 Metrics 监控指标

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

准备条件

本文演示如何在 Kubernetes 环境下部署 Prometheus 并实现对 Dubbo 集群的监控数据统计与查询，你需要完成或具备以下内容：

本地或远端 Kubernetes 集群
确保 Prometheus 正确安装
部署示例应用并开启指标采集
使用 Prometheus dashboard 查询数据指标

确保 Prometheus 正确运行

验证 Prometheus 已经正确部署

kubectl -n dubbo-system get svc prometheus-server
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
prometheus-server ClusterIP 10.109.160.254 <none> 9090/TCP 4m

部署示例

kubectl apply -f https://raw.githubusercontent.com/apache/dubbo-samples/master/4-governance/dubbo-samples-metrics-spring-boot/Deployment.yml

等待示例应用正常运行，通过以下命令确认应用状态：

kubectl -n dubbo-demo get deployments

查询 Prometheus

获得 Prometheus 访问地址 kubectl port-forward service/prometheus-server 9090:9090，打开浏览器，访问 localhost:9090/graph 即可打开 Prometheus 控制台。

接下来，执行 Prometheus 查询命令。可以在此确认 Dubbo 支持的 Metrics 指标。

基于 Java 接口模式开发 triple 服务时，底层的序列化机制实现

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

1 介绍

Dubbo 实现的 triple 协议易用性更好（不绑定 Protobuf），开发者可以继续使用 Java 接口直接定义服务。对于期望平滑升级、没有多语言业务或者不熟悉 Protobuf 的用户而言，Java 接口方式是最简单的使用 triple 的方式。

以下介绍这种协议模式下的底层序列化细节：框架会用一个内置的 protobuf 对象将 request 和 response 进行包装（wrapper），也就是对象会被序列化两次，第一次是使用如 serialization=hessian 指定的方式进行序列化，第二次是用 protobuf wrapper 对第一步中序列化后的 byte[] 进行包装后传输。

2 使用方式

在使用 Java 接口方式开发 triple 通信服务的时候，dubbo server 将自动启用 protobuf、protobuf-json 序列化模式支持。

2.1 添加依赖

使用 triple 协议，必须先添加如下依赖：

<dependencies>
	<dependency>
		<groupId>com.google.protobuf</groupId>
		<artifactId>protobuf-java</artifactId>
		<version>3.19.6</version>
	</dependency>
	<!-- 提供 protobuf-json 格式请求支持 -->>
	<dependency>
		<groupId>com.google.protobuf</groupId>
		<artifactId>protobuf-java-util</artifactId>
		<version>3.19.6</version>
	</dependency>
</dependencies>

2.2 配置启用

只要是基于 Java 接口方式模式使用 triple 协议，就会使用 protobuf wrapper 序列化，只要定义 Java 接口并启用 triple 协议即可：

使用 Protobuf(IDL) 开发 triple 通信服务

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

使用方式

POM依赖

<plugin>
 <groupId>org.apache.dubbo</groupId>
 <artifactId>dubbo-maven-plugin</artifactId>
 <version>${dubbo.version}</version> <!-- 3.3.0及以上版本 -->
 <configuration>
 <outputDir>build/generated/source/proto/main/java</outputDir> <!-- 参考下文可配置参数 -->
 </configuration>
</plugin>

configuration可配置参数

参数	必填参数	默认值	说明	备注
outputDir	否	${project.build.directory}/generated-sources/protobuf/java	生成的java文件存放目录
protoSourceDir	否	${basedir}/src/main/proto	proto文件目录
protocArtifact	否	com.google.protobuf:protoc:3.25.0:exe:操作系统名:操作系统架构	proto编译器组件
protocVersion	否	3.25.0	protobuf-java的版本
dubboGenerateType	否	tri	代码生成类型	可填tri或者tri_reactor

服务定义

使用 Protocol Buffers 定义 Greeter 服务

syntax = "proto3";
option java_multiple_files = true;
package org.apache.dubbo.samples.tri.unary;

message GreeterRequest {
 string name = 1;
}
message GreeterReply {
 string message = 1;
}

service Greeter{
 rpc greet(GreeterRequest) returns (GreeterReply);
}

请注意以上 package 定义 package org.apache.dubbo.samples.tri.unary;，在此示例中 package 定义的路径将同时作为 java 包名和服务名前缀。这意味着 rpc 服务的完整定义是：org.apache.dubbo.samples.tri.unary.Greeter，与生成代码的路径完全一致。

Protocol

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

在通信协议一章中，我们了解了 Dubbo 内置的几个核心 RPC 协议 dubbo、rest、和tri 以及它们的使用方式。本文讲解如何通过扩展 org.apache.dubbo.rpc.Protocol SPI，提供自定义的 RPC 协议实现。

自定义一套私有协议有两种方式，第一种是对原有的协议进行包装，添加一些特定的业务逻辑。另外一种是完全自定义一套协议。前者实现简单，在dubbo中也是有广泛的使用，比如：ProtocolFilterWrapper, QosProtocolWrapper, ProtocolListenerWrapper等。后者实现相对复杂，但却具有最大的灵活性，比如 Dubbo 框架内置的协议 dubbo、triple 协议都可以算作这种实现方式。

本示例的完整源码请参见 dubbo-samples-extensibility。除了本示例之外，Dubbo 核心仓库 apache/dubbo 以及扩展库 apache/dubbo-spi-extensions 中的众多 Protocol 实现，都可以作为扩展参考实现：

# Dubbo对外支持的常用协议
dubbo=org.apache.dubbo.rpc.protocol.dubbo.DubboProtocol
tri=org.apache.dubbo.rpc.protocol.tri.TripleProtocol

任务详情

基于现有的dubbo协议来实现自定义协议edubbo。

实现方式

通过对dubbo协议进行包装来实现edubbo协议。

代码结构

Common

src
 |-main
 |-java
 |-org
 |-apache
 |-dubbo
 |-samples
 |-extensibility
 |-protocol
 |-common
 |-EnhancedProtocol.java (实现Protocol接口)

Provider

src
 |-main
 |-java
 |-org
 |-apache
 |-dubbo
 |-samples
 |-extensibility
 |-protocol
 |-provider
 |-ExtensibilityProtocolProviderApplication.java
 |-ExtensibilityProtocolServiceImpl.java
 |-resources
 |-META-INF
 |-application.properties (Dubbo Provider配置文件)
 |-dubbo
 |-org.apache.dubbo.rpc.Protocol (纯文本文件)

Consumer

src
 |-main
 |-java
 |-org
 |-apache
 |-dubbo
 |-samples
 |-extensibility
 |-protocol
 |-consumer
 |-ExtensibilityProtocolConsumerApplication.java
 |-ExtensibilityProtocolConsumerTask.java
 |-resources
 |-META-INF
 |-application.properties (Dubbo Consumer配置文件)
 |-dubbo
 |-org.apache.dubbo.rpc.Protocol (纯文本文件)

代码详情

package org.apache.dubbo.samples.extensibility.protocol.common;

import org.apache.dubbo.common.URL;
import org.apache.dubbo.rpc.Protocol;
import org.apache.dubbo.rpc.Invoker;
import org.apache.dubbo.rpc.Exporter;
import org.apache.dubbo.rpc.ProtocolServer;
import org.apache.dubbo.rpc.RpcException;
import org.apache.dubbo.rpc.model.FrameworkModel;
import org.apache.dubbo.rpc.protocol.dubbo.DubboProtocol;

import java.util.List;

public class EnhancedProtocol implements Protocol {

 public EnhancedProtocol(FrameworkModel frameworkModel) {
 this.protocol = new DubboProtocol(frameworkModel);
 }

 private final Protocol protocol;

 @Override
 public int getDefaultPort() {
 return this.protocol.getDefaultPort();
 }

 @Override
 public <T> Exporter<T> export(Invoker<T> invoker) throws RpcException {
 // do something
 return this.protocol.export(invoker);
 }

 @Override
 public <T> Invoker<T> refer(Class<T> type, URL url) throws RpcException {
 // do something
 return this.protocol.refer(type, url);
 }

 @Override
 public void destroy() {
 this.protocol.destroy();
 }

 @Override
 public List<ProtocolServer> getServers() {
 return protocol.getServers();
 }
}

SPI配置

Provider

在resources/META-INF/dubbo/org.apache.dubbo.rpc.Protocol文件中添加如下配置：

rest 协议

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

基于标准的Java REST API——JAX-RS 2.0（Java API for RESTful Web Services的简写）实现的REST调用支持

快速入门

在dubbo中开发一个REST风格的服务会比较简单，下面以一个注册用户的简单服务为例说明。

这个服务要实现的功能是提供如下URL（注：这个URL不是完全符合REST的风格，但是更简单实用）：

http://localhost:8080/users/register

而任何客户端都可以将包含用户信息的JSON字符串POST到以上URL来完成用户注册。

首先，开发服务的接口：

public interface UserService { 
 void registerUser(User user);
}

然后，开发服务的实现：

@Path("/users")
public class UserServiceImpl implements UserService {
 
 @POST
 @Path("/register")
 @Consumes({MediaType.APPLICATION_JSON})
 public void registerUser(User user) {
 // save the user...
 }
}

上面的实现非常简单，但是由于该 REST 服务是要发布到指定 URL 上，供任意语言的客户端甚至浏览器来访问，所以这里额外添加了几个 JAX-RS 的标准 annotation 来做相关的配置。

@Path("/users")：指定访问UserService的URL相对路径是/users，即http://localhost:8080/users

@Path("/register")：指定访问registerUser()方法的URL相对路径是/register，再结合上一个@Path为UserService指定的路径，则调用UserService.register()的完整路径为http://localhost:8080/users/register

@POST：指定访问registerUser()用HTTP POST方法

@Consumes({MediaType.APPLICATION_JSON})：指定registerUser()接收JSON格式的数据。REST框架会自动将JSON数据反序列化为User对象

最后，在spring配置文件中添加此服务，即完成所有服务开发工作：

<!-- 用rest协议在8080端口暴露服务 -->
<dubbo:protocol name="rest" port="8080"/>

<!-- 声明需要暴露的服务接口 -->
<dubbo:service interface="xxx.UserService" ref="userService"/>

<!-- 和本地bean一样实现服务 -->
<bean id="userService" class="xxx.UserServiceImpl" />

REST服务提供端详解

下面我们扩充“快速入门”中的UserService，进一步展示在dubbo中REST服务提供端的开发要点。

RPC 协议安全

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

Dubbo 支持 RPC 协议的扩展，理论上用户可以基于该扩展机制启用任意的 RPC 协议，这带来了极大的灵活的，但同时也要意识到其中潜藏的安全性风险。

Dubbo 2.7 官方版本提供的序列化协议有如下几种：

Dubbo
RMI
Hessian
Http / Rest
Webservice
Thrift
gRPC
……

从 Dubbo 3.0 开始默认仅提供以下序列化协议支持：

Dubbo
Triple / gRPC
Http / Rest

对于 Triple、gRPC、Http、Rest 协议都是基于 HTTP 协议构建的，可以严格区分请求的格式，如 Header 为纯文本，避免在读取 Token 时带来的 RCE 等风险。对于 Dubbo 协议，由于其基于 TCP 二进制直接设计，除了特定几个字段外均使用序列化协议写入，因此如果开启了有风险的序列化协议，仍然会存在 RCE 等风险。对于 RMI 协议，由于其基于 Java 序列化机制，存在 RCE 等风险。对于 Hessian 协议，由于其基于 Hessian 序列化机制，且默认 Hessian 协议（非 Dubbo Shade 的 Hessian-Lite 协议）无法配置黑白名单且无默认黑名单，存在 RCE 等风险。

（1）如果用户希望使用 Token 鉴权机制，防止未鉴权的不可信请求来源威胁 Provider 的安全性，应使用 Triple 等基于 Http 标准扩展的协议，避免 token 参数读取时的安全风险。

Rust和Java互相调用

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

1 前置条件

安装 Rust 开发环境
安装 protoc 工具
安装 Java 开发环境

2 运行示例 Java 版本的 Dubbo provider

Java 版本的 Dubbo provider 示例源码见https://github.com/apache/dubbo-samples/tree/master/3-extensions/protocol/dubbo-samples-triple。

Clone 源代码、编译构建，并运行 provider：

$ # clone 源代码
$ git clone https://github.com/apache/dubbo-samples.git
$ cd dubbo-samples/dubbo-samples-triple/

$ # 构建
$ mvn clean compile package -DskipTests

$ # 运行 provider
$ java -Dprovider.port=8888 -jar ./target/dubbo-samples-triple-1.0-SNAPSHOT.jar
# ……省略部分日志
Dubbo triple stub server started, port=8888

Java 侧的接口定义

3 运行 Rust 版本的 Dubbo consumer

Rust 版本的 Dubbo consumer 示例源码见https://github.com/apache/dubbo-rust/tree/main/examples/greeter。

Dubbo SPI 插件及详情

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

Dubbo 在框架中定义了非常多的扩展点，因此，当你发现官方库没法满足业务需求，想为 Dubbo 框架提供定制能力时，请优先查阅以下扩展点定义，看是否能通过提供扩展实现的方式无侵入的定制 Dubbo 框架。

具体可参见本文下方的 Dubbo SPI 扩展定义汇总

扩展点汇总

生命周期与事件回调

SPI 扩展定义	功能说明	示例实现	激活条件
org.apache.dubbo.common.lang.ShutdownHookCallback	优雅下线回调逻辑扩展点，Dubbo 进程销毁前会调用所有 ShutdownHookCallback 实现	无	无需配置，自动激活
org.apache.dubbo.common.threadpool.event.ThreadPoolExhaustedListener	当 dubbo 业务线程池满时，会调用这个扩展点发出事件通知	org.apache.dubbo.metrics.collector.sample.MetricThreadPoolExhaustedListener	通过 dubbo.protocol.thread-pool-exhausted-listeners=spi-name1,spi-name2 设置激活哪些实现
org.apache.dubbo.rpc.ExporterListener	每个 Exporter 成功 export/unexport 发布后，都会回调这个扩展点	org.apache.dubbo.rpc.listener.InjvmExporterListener	扩展实现必须增加 @Activate 注解激活，可按需配置激活条件。支持通过在 URL 中配置 exporter.listener=spi-name1,spi-name2 控制具体激活哪个实现
org.apache.dubbo.rpc.InvokerListener	每个服务 Invoker 成功 refer/destroy 发布后，都会回调这个扩展点	org.apache.dubbo.rpc.protocol.CountInvokerListener	扩展实现必须增加 @Activate 注解激活，可按需配置激活条件。支持通过在 URL 中配置 invoker.listener=spi-name1,spi-name2 控制具体激活哪个实现
org.apache.dubbo.common.status.StatusChecker	对外透出内部组件状态的扩展点，每个需要透出状态的组件均可实现此扩展点。	org.apache.dubbo.rpc.protocol.dubbo.status.ThreadPoolStatusChecker	通过设置 dubbo.protocol.status=spi-name1,spi-name2 激活
org.apache.dubbo.config.ServiceListener	ServciceConfig 回调扩展点，每个 ServiceConfig 成功 export/unexport 后都会被回调。拦截点与 ExporterListener 略有不同	无	无需配置，自动激活
org.apache.dubbo.registry.RegistryServiceListener	服务 URL 向注册中心 register/unregister 之后的回调扩展点，所有扩展实现会被依次通知	无	扩展实现必须增加 @Activate 注解激活，默认激活。支持通过在 Registry URL 中配置 registry.listeners 控制具体激活哪个实现，如dubbo.registry.parameters.registry.listeners=spi-name1,spi-name2
org.apache.dubbo.registry.integration.RegistryProtocolListener	用于接口级服务发现。	org.apache.dubbo.registry.client.migration.MigrationRuleListener	RegistryProtocol listener is introduced to provide a chance to user to customize or change export and refer behavior of RegistryProtocol. For example: re-export or re-refer on the fly when certain condition meets.
org.apache.dubbo.qos.probe.LivenessProbe	生命周期检测扩展点。可通过 qos live http 接口配置为 k8s liveness 检测，qos live 会检查所有 LivenessProbe 扩展点实现	无	扩展实现必须增加 @Activate 注解激活，默认激活。支持通过在 URL 中配置 dubbo.application.liveness-probe=spi-name1,spi-name2 控制具体激活哪些实现
org.apache.dubbo.qos.probe.ReadinessProbe	生命周期检测扩展点。可通过 qos ready http 接口配置为 k8s readiness 检测，qos ready 会检查所有 ReadinessProbe 扩展点实现	无	扩展实现必须增加 @Activate 注解激活，默认激活。支持通过在 URL 中配置 dubbo.application.readiness-probe=spi-name1,spi-name2 控制具体激活哪些实现
org.apache.dubbo.qos.probe.StartupProbe	生命周期检测扩展点。可通过 qos startup http 接口配置为 k8s startup 检测，qos startup 会检查所有 StartupProbe 扩展点实现	无	扩展实现必须增加 @Activate 注解激活，默认激活。支持通过在 URL 中配置 dubbo.application.startup-probe=spi-name1,spi-name2 控制具体激活哪些实现
org.apache.dubbo.common.deploy.ApplicationDeployListener	Dubbo 进程启动生命周期中的回调扩展，支持包括初始化、启动成功、停止等多个回调点。如果是多应用部署的场景，则是单应用粒度的生命周期回调。	org.apache.dubbo.security.cert.CertDeployerListener	无需配置，自动激活
org.apache.dubbo.common.deploy.ModuleDeployListener	Dubbo 进程启动生命周期中的回调扩展，支持包括初始化、启动成功、停止等多个回调点。如果是多模块部署的场景，则是单模块粒度的生命周期回调。	无	无需配置，自动激活
org.apache.dubbo.qos.api.BaseCommand	QoS 命令扩展点，实现该扩展点增加新 QoS 命令。	org.apache.dubbo.qos.command.impl.Ls	无需配置，自动激活
~~org.apache.dubbo.remoting.telnet.TelnetHandler~~
~~org.apache.dubbo.config.bootstrap.DubboBootstrapStartStopListener~~

配置相关

SPI 扩展定义	功能说明	示例实现	激活条件
org.apache.dubbo.common.extension.ExtensionInjector	IoC 注入器扩展点，通过扩展可以实现多种类型的示例自动注入，用于 Dubbo 框架 SPI 实例与不同 IOC 容器之间的结合，如支持 Spring Bean 注入 SPI 实例。	org.apache.dubbo.config.spring.extension.SpringExtensionInjector	无需额外配置，自动激活
org.apache.dubbo.common.infra.InfraAdapter	用于自定义加载环境变量的扩展实现，可以批量的通过编码的方式获取你要读取的环境变量，框架会自动将这些值附加到每个服务的 URL 参数中。	org.apache.dubbo.common.infra.support.EnvironmentAdapter	无需额外配置，自动激活
org.apache.dubbo.common.logger.LoggerAdapter	日志框架适配，如果要额外提供 Dubbo 不支持的日志框架适配，可以使用此扩展点。	org.apache.dubbo.common.logger.slf4j.Slf4jLoggerAdapter	通过配置 dubbo.application.logger=spi-name 激活
org.apache.dubbo.config.ConfigInitializer	在配置初始化之前，服务初始化之前定制 ServciceConfig、ReferenceConfig 参数	无	扩展实现必须增加 @Activate 注解激活，可按需增加激活条件
org.apache.dubbo.config.CommonConfigPostProcessor	在配置初始化之后，服务初始化之前定制 ServciceConfig、ReferenceConfig 参数。在 ConfigInitializer 之后执行。	org.apache.dubbo.rpc.protocol.rest.config.FeignClientAnnotationConfigPostProcessor	扩展实现必须增加 @Activate 注解激活，可按需增加激活条件
org.apache.dubbo.config.spring.context.DubboSpringInitCustomizer	Custom dubbo spring initialization. Customize dubbo spring initialization on bean registry processing phase.�	无	无需额外配置，自动激活

服务发现

SPI 扩展定义	功能说明	示例实现	激活条件
org.apache.dubbo.registry.AddressListener	用于服务发现。URL 地址通知发生时会调用此扩展点实现，可做一些地址预处理操作	无	扩展实现必须增加 @Activate 注解激活，可按需配置激活条件
org.apache.dubbo.registry.ProviderFirstParams	用于服务发现。用于指定 URL 参数优先级，改扩展点实现返回的参数列表（provider优先级高于consumer），多个扩展实现的参数列表会合并	org.apache.dubbo.registry.support.DefaultProviderFirstParams	无需配置，自动激活
org.apache.dubbo.registry.RegistryFactory	用于接口级服务发现。通过扩展此可SPI实现不同的注册中心适配	org.apache.dubbo.registry.nacos.NacosRegistryFactory	通过配置 dubbo.registry.address=spi-name://ip:port 激活
org.apache.dubbo.registry.client.RegistryClusterIdentifier	用于应用级服务发现。Dubbo 框架支持为注册中心集群指定标识，通过此标识 key 可以对地址 URL 进行分类（来自哪个集群），从而根据不同集群做一些事情。此扩展点给用户机会指定依据哪个 key 来作为注册中心集群分类。	org.apache.dubbo.registry.client.DefaultRegistryClusterIdentifier	通过 dubbo.provider.parameters.registry-cluster-type=spi-name 激活指定扩展实现
org.apache.dubbo.registry.client.ServiceDiscoveryFactory	用于应用级服务发现。通过扩展此可SPI实现不同的注册中心适配	org.apache.dubbo.registry.nacos.NacosServiceDiscoveryFactory	通过配置 dubbo.registry.address=spi-name://ip:port 激活，同时指定 dubbo.registry.register-mode=instance 激活应用级服务发现
org.apache.dubbo.registry.client.ServiceInstanceCustomizer	用于应用级服务发现。在应用级地址实例 URL 注册到注册中心之前，通过此扩展点实现进行定制	org.apache.dubbo.registry.client.metadata.ServiceInstanceMetadataCustomizer	无需配置，自动激活
org.apache.dubbo.registry.client.migration.MigrationAddressComparator	用于应用级服务发现。作为接口级地址向应用级别地址迁移机制的一部分，在框架决策是否迁移之前，用于对两边的地址做比较，可自行定制决策逻辑。	org.apache.dubbo.registry.client.migration.DefaultMigrationAddressComparator	无需配置，自动激活
~~org.apache.dubbo.registry.client.migration.PreMigratingConditionChecker~~	~~用于应用级服务发现。作为接口级地址向应用级别地址迁移机制的一部分，在框架决策是否迁移之前，可自行定制检查逻辑。~~	无	~~无需配置，自动激活~~
org.apache.dubbo.metadata.MetadataParamsFilter	用于应用级服务发现。通过该扩展点可以控制哪些参数注册到注册中心，哪些参数注册到服务元数据。	org.apache.dubbo.metadata.DefaultMetadataParamsFilter	扩展实现必须增加 @Activate 注解激活。支持通过在 URL 中配置 params-filter 控制具体激活哪个实现，如 dubbo.provider.parameters.params-filter=-default,spi-name1 表示关闭所有扩展实现仅启用 spi-name1 实现
org.apache.dubbo.registry.client.metadata.ServiceInstanceNotificationCustomizer	用于应用级服务发现。识别特殊类型的地址 URL，示例扩展实现用于识别 Spring Cloud Alibaba Dubbo 类型地址	org.apache.dubbo.registry.client.metadata.SpringCloudServiceInstanceNotificationCustomizer	无需配置，自动激活。
org.apache.dubbo.registry.integration.ServiceURLCustomizer	用于接口级服务发现。在优化接口级地址列表并做 URL 精简时，可以通过该扩展点指定哪些 URL 注册到注册中心、哪些 URL 不注册。当有多个扩展实现时，效果叠加。	org.apache.dubbo.registry.integration.DefaultServiceURLCustomizer	无需配置，自动激活。
org.apache.dubbo.rpc.cluster.ProviderURLMergeProcessor	用于接口级服务发现。该扩展点用于完成 consumer url 和 provider url 合并，可以使用不同的实现控制合并策略，以确定保留不同的 key，使用不同的覆盖关系（仅对接口级服务发现有效）	org.apache.dubbo.rpc.cluster.support.merger.DefaultProviderURLMergeProcessor	可通过配置 dubbo.consumer.url-merge-processor=spi-name 启用指定扩展实现

RPC与流量管控

SPI 扩展定义	功能说明	示例实现	激活条件
org.apache.dubbo.rpc.Protocol	RPC 协议实现扩展点。通过扩展该扩展点增加更多的协议实现	org.apache.dubbo.rpc.protocol.dubbo.DubboProtocol	通过配置 dubbo.prorocol.name=spi-nam,e 激活
org.apache.dubbo.rpc.ProxyFactory	RPC 代理实现扩展点。可以提供多种不同的代理实现，如字节码增强、JDK 等	org.apache.dubbo.rpc.proxy.javassist.JavassistProxyFactory	通过配置 dubbo.application.compiler=spi-name 激活
org.apache.dubbo.rpc.ZoneDetector	在多注册中心场景下，Dubbo 提供了自动同区域优先的匹配策略。此扩展点可以让用户更方便的扩展 zone 读取策略，以更灵活的决策当前请求属于哪个 zone。默认情况下框架会从 RpcContext 特定的 key 读取	无	只会有一个 ZoneDetector 实现会被激活。key 为 `default`的扩展实现将优先被激活。
org.apache.dubbo.rpc.cluster.Cluster	RPC 请求容灾策略扩展点，比如通过 Cluster 可以设置在请求失败时动作，如 FailoverCluster、FailfastCluster 等。	org.apache.dubbo.rpc.cluster.support.FailoverCluster	通过配置 dubbo.consumer.cluster=spi-name 激活
org.apache.dubbo.rpc.cluster.LoadBalance	负载均衡策略扩展点，通过扩展可以实现不同的负载均衡策略。	org.apache.dubbo.rpc.cluster.loadbalance.RandomLoadBalance	通过配置 dubbo.consumer.loadbalance=spi-name 激活
org.apache.dubbo.rpc.HeaderFilter	在 RPC 请求前，通过不同的扩展实现各种 attachment/header 校验策略	org.apache.dubbo.rpc.filter.TokenHeaderFilter	扩展实现必须增加 @Activate 注解激活。支持通过在 URL 中配置 header.filter=spi-name1,spi-name2 控制具体激活哪个实现
org.apache.dubbo.rpc.Filter	RPC 请求过滤器，用于在请求发起前、响应结果返回后，对 RPC 调用进行过滤	org.apache.dubbo.rpc.filter.GenericFilter	扩展实现必须增加 @Activate 注解激活，可按需配置激活条件如@Activate(group=“consumer”)。支持通过在 URL 中配置 service.filter=spi-name1,spi-name2 控制具体在provider侧激活哪些实现；支持通过在 URL 中配置 reference.filter=spi-name1,spi-name2 控制具体在consumer侧激活哪些实现
org.apache.dubbo.rpc.cluster.filter.ClusterFilter	RPC 请求过滤器，与 Filter 作用相同，但 ClusterFilter 发生在选址之前。对于大部分用户可以直接使用：org.apache.dubbo.rpc.Filter	org.apache.dubbo.rpc.cluster.filter.support.ConsumerContextFilter	扩展实现必须增加 @Activate 注解激活，可按需配置激活条件。支持通过在 URL 中配置 filter=spi-name1,spi-name2 控制具体激活哪个实现
org.apache.dubbo.rpc.cluster.RouterFactory	路由器扩展点，可以通过扩展增加不同的路由规则策略。	无	扩展实现必须增加 @Activate 注解激活，可按需配置激活条件。支持通过在 URL 中配置 router=spi-name1,spi-name2 控制具体激活哪个实现
org.apache.dubbo.rpc.cluster.router.state.StateRouterFactory	路由器扩展点，可以通过扩展增加不同的路由规则策略。与 RouterFactory 作用一致，但具备更高性能。对大部分用户，为简单起见可直接使用 RouterFactory	org.apache.dubbo.rpc.cluster.router.condition.ConditionStateRouterFactory	扩展实现必须增加 @Activate 注解激活，可按需配置激活条件。支持通过在 URL 中配置 router=spi-name1,spi-name2 控制具体激活哪个实现
org.apache.dubbo.rpc.cluster.ConfiguratorFactory	动态配置规则扩展点，通过增加扩展可以增加不同的动态配置规则策略	org.apache.dubbo.rpc.cluster.configurator.override.OverrideConfiguratorFactory	扩展实现必须增加 @Activate 注解激活，可按需配置激活条件。支持通过在 URL 中配置 router=spi-name1,spi-name2 控制具体激活哪个实现
org.apache.dubbo.rpc.cluster.router.condition.matcher.pattern.ValuePattern	路由规则处理扩展点。条件路由规则内部的规则处理器，通过扩展可支持更丰富的规则和匹配条件	org.apache.dubbo.rpc.cluster.router.condition.matcher.pattern.range.RangeValuePattern	自动激活，通过规则控制激活哪个具体实现
org.apache.dubbo.rpc.cluster.router.condition.matcher.ConditionMatcherFactory	路由规则处理扩展点。条件路由规则内部的规则处理器，通过扩展可支持更丰富的规则和匹配条件	org.apache.dubbo.rpc.cluster.router.condition.matcher.argument.ArgumentConditionMatcherFactory	扩展实现必须增加 @Activate 注解激活，可按需配置激活条件。
org.apache.dubbo.rpc.cluster.router.mesh.util.TracingContextProvider	MeshRule 路由规则处理扩展点，可用于从不同的第三方 Tracing 系统读取上下文	无	无需配置，自动激活
org.apache.dubbo.rpc.cluster.router.mesh.route.MeshEnvListenerFactory	MeshRule 路由规则处理扩展点	无	无需配置，自动激活
org.apache.dubbo.cache.CacheFactory	缓存实现扩展点，用于缓存 RPC 调用结果	org.apache.dubbo.cache.support.expiring.ExpiringCacheFactory	通过在 URL 中配置 cache=spi-name 控制具体激活哪个实现
org.apache.dubbo.common.serialize.Serialization	序列化协议扩展点，如果要扩展新的序列化协议，可以使用此扩展点。	org.apache.dubbo.common.serialize.hessian2.Hessian2Serialization	通过配置 dubbo.provider.serialization=spi-name 激活
org.apache.dubbo.common.threadpool.ThreadPool	线程池策略扩展点。目前仅适用于 dubbo 协议实现，不适用于 triple 协议。	org.apache.dubbo.common.threadpool.support.fixed.FixedThreadPool	通过配置 dubbo.provider.threadpool=spi-name 激活
org.apache.dubbo.rpc.executor.IsolationExecutorSupportFactory	线程池隔离策略扩展点。如 dubbo 协议、triple 协议都可以定义不同的隔离策略，每个协议可设置一个线程池隔离策略。	org.apache.dubbo.rpc.protocol.tri.transport.TripleIsolationExecutorSupportFactory	跟随用户配置的 dubbo.protocol.name，因此必须确保配置的 key 值与 rpc 协议名相同
org.apache.dubbo.rpc.PenetrateAttachmentSelector	通过此扩展点可以自定义参数全链路传递（dubbo链路），Dubbo 默认只会在 A->B 链路传递参数，通过此扩展点可以控制参数在 A->B->C一直传递下去。	无	无需配置，自动激活
~~org.apache.dubbo.rpc.cluster.interceptor.ClusterInterceptor~~	~~与 ~~~~org.apache.dubbo.rpc.cluster.filter.ClusterFilter 相同，废弃~~	废弃

服务治理

SPI 扩展定义	功能说明	示例实现	激活条件
org.apache.dubbo.common.config.configcenter.DynamicConfigurationFactory	配置中心核心扩展点。用于提供不同配置中心适配实现。	org.apache.dubbo.configcenter.support.nacos.NacosDynamicConfigurationFactory	通过指定 dubbo.config-center.address=spi-name:// 激活
org.apache.dubbo.metadata.report.MetadataReportFactory	元数据中心扩展点，用于提供新的元数据中心存储实现	org.apache.dubbo.metadata.store.nacos.NacosMetadataReportFactory	通过指定 dubbo.metadata-report.address=spi-name:// 激活
org.apache.dubbo.metrics.report.MetricsReporterFactory	Metrics 指标上报扩展点，可以通过扩展实现适配到不同的 Metrics 后端服务	org.apache.dubbo.metrics.prometheus.PrometheusMetricsReporterFactory	通过指定 dubbo.metrics.protocol=spi-name 激活
org.apache.dubbo.metrics.collector.MetricsCollector	框架内部 Metrics 采集扩展点，可以通过扩展支持 RPC、注册中心等不同组件的 metrics 埋点数据采集	org.apache.dubbo.metrics.registry.collector.RegistryMetricsCollector	扩展实现必须增加 @Activate 注解激活，可按需增加激活条件
org.apache.dubbo.auth.spi.AccessKeyStorage	用于 dubbo-auth 模块，该扩展点可不同的扩展 AK 来源读取方式	org.apache.dubbo.auth.DefaultAccessKeyStorage	通过指定 accessKey.storage URL 参数激活
org.apache.dubbo.auth.spi.Authenticator	用于 dubbo-auth 模块，该扩展点用于实现具体的认证逻辑	org.apache.dubbo.auth.AccessKeyAuthenticator	通过指定 authenticator URL 参数激活
org.apache.dubbo.common.ssl.CertProvider	TLS 证书来源扩展，用于适配不同的证书来源实现	org.apache.dubbo.common.ssl.impl.SSLConfigCertProvider	扩展实现必须增加 @Activate 注解激活

协议与传输层实现

SPI 扩展定义	功能说明	示例实现	激活条件
org.apache.dubbo.remoting.ChannelHandler
org.apache.dubbo.remoting.Codec
org.apache.dubbo.remoting.Codec2
org.apache.dubbo.remoting.Dispatcher
org.apache.dubbo.remoting.Transporter
org.apache.dubbo.rpc.protocol.dubbo.ByteAccessor
org.apache.dubbo.remoting.api.pu.PortUnificationTransporter
org.apache.dubbo.remoting.api.WireProtocol
org.apache.dubbo.remoting.api.connection.ConnectionManager
org.apache.dubbo.remoting.exchange.Exchanger
org.apache.dubbo.remoting.http.HttpBinder
org.apache.dubbo.remoting.http12.message.HttpMessageEncoderFactory
org.apache.dubbo.remoting.http12.message.HttpMessageDecoderFactory
org.apache.dubbo.remoting.http12.h2.Http2ServerTransportListenerFactory
org.apache.dubbo.remoting.http12.h1.Http1ServerTransportListenerFactory
org.apache.dubbo.remoting.http12.message.HttpMessageAdapterFactory
org.apache.dubbo.metadata.annotation.processing.builder.TypeBuilder
org.apache.dubbo.metadata.annotation.processing.rest.AnnotatedMethodParameterProcessor
org.apache.dubbo.metadata.annotation.processing.rest.ServiceRestMetadataResolver
org.apache.dubbo.metadata.definition.builder.TypeBuilder
org.apache.dubbo.metadata.rest.AnnotatedMethodParameterProcessor
org.apache.dubbo.metadata.rest.ServiceRestMetadataReader
org.apache.dubbo.rpc.protocol.tri.compressor.Compressor
org.apache.dubbo.rpc.protocol.tri.compressor.DeCompressor
org.apache.dubbo.rpc.protocol.tri.rest.argument.ArgumentConverter
org.apache.dubbo.rpc.protocol.tri.rest.argument.ArgumentResolver
org.apache.dubbo.rpc.protocol.tri.rest.filter.RestExtension
org.apache.dubbo.rpc.protocol.tri.rest.filter.RestExtensionAdapter
org.apache.dubbo.rpc.protocol.tri.rest.mapping.RequestMappingResolver
org.apache.dubbo.rpc.protocol.tri.route.RequestHandlerMapping
org.apache.dubbo.rpc.protocol.rest.annotation.param.parse.provider.BaseProviderParamParser
org.apache.dubbo.metadata.rest.ServiceRestMetadataResolver
org.apache.dubbo.rpc.protocol.rest.filter.RestRequestFilter
org.apache.dubbo.rpc.protocol.rest.filter.RestResponseFilter
org.apache.dubbo.metadata.rest.NoAnnotatedParameterRequestTagProcessor
org.apache.dubbo.rpc.protocol.rest.message.HttpMessageCodec
org.apache.dubbo.rpc.protocol.rest.annotation.consumer.HttpConnectionPreBuildIntercept
org.apache.dubbo.rpc.protocol.rest.annotation.param.parse.consumer.BaseConsumerParamParser
org.apache.dubbo.remoting.http.factory.RestClientFactory
org.apache.dubbo.rpc.protocol.rest.filter.RestResponseInterceptor
org.apache.dubbo.remoting.zookeeper.ZookeeperTransporter

框架内部实现

SPI 扩展定义	功能说明	示例实现	激活条件
org.apache.dubbo.common.url.component.param.DynamicParamSource	可通过扩展自定义动态参数列表，与 Dubbo3 中关于 URL 存储的优化相关。	org.apache.dubbo.common.url.component.param.DefaultDynamicParamSource
org.apache.dubbo.common.compiler.Compiler	用于设置 Dubbo IoC 容器的自适应扩展实现依赖的字节码工具。默认使用 javassist，可设置使用 jdk 或 bytebuddy 等实现。	org.apache.dubbo.common.compiler.support.JavassistCompiler
org.apache.dubbo.common.serialize.MultipleSerialization
org.apache.dubbo.common.convert.Converter	实现原类型到目标类型的转换，多限于框架内部集成使用	org.apache.dubbo.common.convert.StringToFloatConverter
org.apache.dubbo.common.config.OrderedPropertiesProvider	通过扩展可以为框架提供更多的 properties 来源，多限于框架内部集成使用	无
org.apache.dubbo.common.convert.multiple.MultiValueConverter	实现原类型到目标类型的转换，多限于框架内部集成使用	org.apache.dubbo.common.convert.multiple.StringToArrayConverter
org.apache.dubbo.common.store.DataStore
org.apache.dubbo.common.threadpool.manager.ExecutorRepository
org.apache.dubbo.spring.security.jackson.ObjectMapperCodecCustomer
org.apache.dubbo.validation.Validation
org.apache.dubbo.rpc.PathResolver
org.apache.dubbo.rpc.model.PackableMethodFactory
org.apache.dubbo.rpc.model.ApplicationInitListener
org.apache.dubbo.rpc.model.BuiltinServiceDetector
org.apache.dubbo.rpc.model.ScopeModelInitializer
org.apache.dubbo.aot.api.ReflectionTypeDescriberRegistrar
org.apache.dubbo.aot.api.ProxyDescriberRegistrar
org.apache.dubbo.common.json.JsonUtil
org.apache.dubbo.rpc.protocol.injvm.ParamDeepCopyUtil
org.apache.dubbo.aot.api.ResourceDescriberRegistrar
org.apache.dubbo.common.context.ApplicationExt
org.apache.dubbo.common.context.ModuleExt
org.apache.dubbo.metrics.service.MetricsService	用于对外发布/透出 Metrics 指标的内部服务定义，以标准 Dubbo 服务形式发布。	org.apache.dubbo.metrics.service.DefaultMetricsService
org.apache.dubbo.metrics.service.MetricsServiceExporter
org.apache.dubbo.rpc.cluster.filter.FilterChainBuilder
org.apache.dubbo.rpc.cluster.filter.InvocationInterceptorBuilder
org.apache.dubbo.rpc.cluster.Merger	目前用于多 group 调用场景，对请求结果进行合并
org.apache.dubbo.rpc.cluster.governance.GovernanceRuleRepository
org.apache.dubbo.qos.permission.PermissionChecker	用于检查扩展QoS执行权限检查逻辑，配合每个 QoS 命令配置的 @CMD 权限注解，结合上下文进行检查。	org.apache.dubbo.qos.permission.DefaultAnonymousAccessPermissionChecker	默认只支持 qosPermissionChecker
org.apache.dubbo.common.status.reporter.FrameworkStatusReporter	用于上报 Dubbo 框架内部运行状态的扩展点，目前框架在服务发现模型自动迁移等位置做了统计埋点，所有迁移动作都会通过此扩展实现上报出去。未来可考虑用 metrics 标准埋点取代。	无	无需配置，自动激活
org.apache.dubbo.registry.client.metadata.MetadataServiceURLBuilder	用于应用级服务发现。在收到应用级地址 URL 推送后，生成 MetadataService URL 时的定制逻辑（仅对点对点应用级地址发现有效）	org.apache.dubbo.registry.client.metadata.StandardMetadataServiceURLBuilder
org.apache.dubbo.metadata.ServiceNameMapping	用于应用级服务发现	org.apache.dubbo.registry.client.metadata.MetadataServiceNameMapping
~~org.apache.dubbo.common.extension.ExtensionFactory~~

SPI 自适应拓展

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

1.原理

在 Dubbo 中，很多拓展都是通过 SPI 机制进行加载的，比如 Protocol、Cluster、LoadBalance 等。有时，有些拓展并不想在框架启动阶段被加载，而是希望在拓展方法被调用时，根据运行时参数进行加载。这听起来有些矛盾。拓展未被加载，那么拓展方法就无法被调用（静态方法除外）。拓展方法未被调用，拓展就无法被加载。对于这个矛盾的问题，Dubbo 通过自适应拓展机制很好的解决了。自适应拓展机制的实现逻辑比较复杂，首先 Dubbo 会为拓展接口生成具有代理功能的代码。然后通过 javassist 或 jdk 编译这段代码，得到 Class 类。最后再通过反射创建代理类，整个过程比较复杂。为了让大家对自适应拓展有一个感性的认识，下面我们通过一个示例进行演示。这是一个与汽车相关的例子，我们有一个车轮制造厂接口 WheelMaker：

public interface WheelMaker {
 Wheel makeWheel(URL url);
}

WheelMaker 接口的自适应实现类如下：

public class AdaptiveWheelMaker implements WheelMaker {
 public Wheel makeWheel(URL url) {
 if (url == null) {
 throw new IllegalArgumentException("url == null");
 }
 
 	// 1.从 URL 中获取 WheelMaker 名称
 String wheelMakerName = url.getParameter("Wheel.maker");
 if (wheelMakerName == null) {
 throw new IllegalArgumentException("wheelMakerName == null");
 }
 
 // 2.通过 SPI 加载具体的 WheelMaker
 WheelMaker wheelMaker = ExtensionLoader
 .getExtensionLoader(WheelMaker.class).getExtension(wheelMakerName);
 
 // 3.调用目标方法
 return wheelMaker.makeWheel(url);
 }
}

AdaptiveWheelMaker 是一个代理类，与传统的代理逻辑不同，AdaptiveWheelMaker 所代理的对象是在 makeWheel 方法中通过 SPI 加载得到的。makeWheel 方法主要做了三件事情：

Trie 前缀树介绍

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

简介

网关的核心之一是路由逻辑，决定一个请求需要经过怎样的加工，被转发到哪个下行服务。
其中 80% 的路由需求表达都以 URL 为基础。需要描述清楚具有某个特征的 URL 或者 URL 集合对应怎样的一系列下游处理策略。

例如，’/test/’ 开头的 URL 路由到测试环境集群，’/release/user/’ 开头的 URL 会被路由到正式环境的 user 服务集群。

同时网关作为所有请求的入口，每一毫秒的延时都会做用在全量的业务下，在 mesh 场景下，延时还会随着调用链路的加深，被倍数放大。按照生产环境业务相应 <=7 毫秒的标准来看，规则匹配的性能要求也是十分苛刻的。一定不能随着规则数目的增加而性能退化。

使用介绍

仅从使用方的角度阐述 pixiu 的配置文件如何描述 URL 相关的路由规则。（下面，我们介绍一下如何配置 URL 路由规则）
如下是一份 pixiu 的 api 配置文件，这份配置文件会被解析后生成一份对应的内存模型，作为 pixiu 路由相关配置的初始状态。之后由 RDS 协议修改解析后得到的内存模型，实现路由逻辑动态生效的效果。RDS 协议（RDS：xDS 协议下描述路由规则的部分）相关内容是后话不详细阐述。我们把注意力聚焦到resource部分。
resource 下 path 部分就是上文阐述的，URL 相关的路由描述。意思是满足 path 描述特征的 URL 会被成功匹配。

name: server
description: server sample
resources:
 - path: '/api/v1/test-dubbo/user/name/:name'
 type: restful
 description: user
 methods:
 - httpVerb: GET
 enable: true
 timeout: 1000ms
 inboundRequest:
 requestType: http
 uri:
 - name: name
 required: true
 integrationRequest:
 requestType: dubbo
 mappingParams:
 - name: uri.name
 mapTo: 0
 mapType: "string"
 applicationName: "UserProvider"
 interface: "com.dubbogo.server.UserService"
 method: "GetUserByName"
 group: "test"
 version: 1.0.0
 clusterName: "test_dubbo"

被匹配后的请求会被转化成 dubbo 协议转发到 test_dubbo 集群调用 com.dubbogo.server.UserService 下的 GetUserByName 服务。
我们继续聚焦到如下范围：

协议概述

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

请参考文档其他部分了解 triple 协议规范规范和基本使用方式。本文只展开 triple 协议 Java 实现中的一些具体细节内容。

编程模式

使用 triple 协议时，开发者可以使用 Java Interface、Protobuf(IDL) 两种方式定义 RPC 服务，两种服务定义方式的协议能力是对等的，仅影响开发者的编程体验、序列化方式，具体选用那种开发模式，取决于使用者的业务背景。

Java接口

适合于 Dubbo 老用户、没有跨语言诉求的开发团队，具备学习成本低的优势，Dubbo2 老用户可以零成本切换到该协议。

服务定义范例：

public interface DemoService {
 String sayHello(String name);
}

这种模式下，序列化方式可以选用 Hessian、JSON、Kryo、JDK、自定义扩展等任意编码协议。在使用体验上，可以说与老版本 dubbo 协议没有任何区别，只需要改一个 protocol 配置项即可，因此对于 dubbo 协议迁移到 triple 也会更平滑。

请通过【进阶学习 - 通信协议】查看 java Interface + Triple 协议的具体使用示例。

Protobuf

使用 Protobuf(IDL) 的方式定义服务，适合于当前或未来有跨语言诉求的开发团队，同一份 IDL 服务可同时用于 Java/Go/Node.js 等多语言微服务开发，劣势是学习成本较高。

syntax = "proto3";
option java_multiple_files = true;
package org.apache.dubbo.springboot.demo.idl;

message GreeterRequest {
 string name = 1;
}
message GreeterReply {
 string message = 1;
}

service Greeter{
 rpc greet(GreeterRequest) returns (GreeterReply);
}

通过 Dubbo 提供的 protoc 编译插件，将以上 IDL 服务定义预编译为相关 stub 代码，其中就包含 Dubbo 需要的 Interface 接口定义，因此在后续编码上区别并不大，只不过相比于前面的用户自定义 Java Interface 模式，这里由插件自动帮我们生成 Interface 定义。

Zookeeper

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

1 前置条件

了解 Dubbo 基本开发步骤
安装并启动 Zookeeper

2 使用说明

在此查看完整示例代码

2.1 增加 Maven 依赖

如果项目已经启用 Zookeeper 作为注册中心，则无需增加任何额外配置。

如果未使用 Zookeeper 注册中心，则请参考为注册中心增加 Zookeeper 相关依赖。

2.2 启用 Zookeeper 配置中心

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

或者

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

address 格式请参考 zookeeper 注册中心 - 启用配置

3 高级配置

如要开启认证鉴权，请参考 zookeeper 注册中心 - 启用认证鉴权

3.1 定制外部化配置 key

1. 启用外部化配置，并指定 key

dubbo
 config-center
 address: zookeeper://127.0.0.1:2181
 config-file: dubbo.properties

config-file - 外部化配置文件 key 值，默认 dubbo.properties。config-file 代表将 Dubbo 配置文件存储在远端注册中心时，文件在配置中心对应的 key 值，通常不建议修改此配置项。

标签路由规则

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

标签路由通过将某一个服务的实例划分到不同的分组，约束具有特定标签的流量只能在指定分组中流转，不同分组为不同的流量场景服务，从而达到实现流量隔离的目的，可以作为蓝绿发布、灰度发布等场景能力的基础。目前有两种方式可以对实例打标，分别是动态规则打标和静态规则打标。动态规则打标 可以在运行时动态的圈住一组机器实例，而 静态规则打标 则需要实例重启后才能生效，其中，动态规则相较于静态规则优先级更高，而当两种规则同时存在且出现冲突时，将以动态规则为准。

本文要讲的就是标签路由规则就是 动态规则打标。

标签路由是一套严格隔离的流量体系，对于同一个应用而言，一旦打了标签则这部分地址子集就被隔离出来，只有带有对应标签的请求流量可以访问这个地址子集，这部分地址不再接收没有标签或者具有不同标签的流量。

举个例子，如果我们将一个应用进行打标，打标后划分为 tag-a、tag-b、无 tag 三个地址子集，则访问这个应用的流量，要么路由到 tag-a (当请求上下文 dubbo.tag=tag-a)，要么路由到 tag-b (dubbo.tag=tag-b)，或者路由到无 tag 的地址子集 (dubbo.tag 未设置)，不会出现混调的情况。

标签路由的作用域是提供者应用，消费者应用无需配置标签路由规则。一个提供者应用内的所有服务只能有一条分组规则，不会有服务 A 使用一条路由规则、服务 B 使用另一条路由规则的情况出现。以下条件路由示例，在 shop-detail 应用中圈出了一个隔离环境 gray，gray 环境包含所有带有 env=gray 标识的机器实例。

configVersion: v3.0
force: true
enabled: true
key: shop-detail
tags:
 - name: gray
 match:
 - key: env
 value:
 exact: gray

TagRule

标签路由规则主体。定义路由规则生效的目标应用、标签分类规则以及一些特定场景下的行为。

Field	Type	Description	Required
configVersion	string	The version of the tag rule definition, currently available version is `v3.0`	Yes
key	string	The identifier of the target application that this rule is about to control	Yes
enabled	bool	Whether enable this rule or not, set `enabled:false` to disable this rule.	Yes
tags	Tag[]	The tag definition of this rule.	Yes
force	bool	The behaviour when the instance subset is empty after routing. `true` means return no provider exception while `false` means fallback to subset without any tags.	No
runtime	bool	Whether run routing rule for every rpc invocation or use routing cache if available.	No

Tag

标签定义，根据 match 条件筛选出一部分地址子集。

超高性能

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

Dubbo 被设计用于解决阿里巴巴超大规模的电商微服务集群实践，并在各个行业头部企业经过多年的十万、百万规模的微服务实践检验，因此，Dubbo 在通信性能、稳定性方面具有无可比拟的优势，非常适合构建近乎无限水平伸缩的微服务集群，这也是 Dubbo 从实践层面优于业界很多同类的产品的巨大优势。

高性能数据传输

Dubbo 内置支持 Dubbo2、Triple 两款高性能通信协议。其中

Dubbo2 是基于 TCP 传输协议之上构建的二进制私有 RPC 通信协议，是一款非常简单、紧凑、高效的通信协议。
Triple 是基于 HTTP/2 的新一代 RPC 通信协议，在网关穿透性、通用性以及 Streaming 通信上具备优势，Triple 完全兼容 gRPC 协议。

以下是基于 Dubbo 3.2 版本得出的压测指标数据，您也可以通过 dubbo-benchmark 项目自行压测。

TCP protocol benchmark

对比 Dubbo 2.x 及早期 3.x 版本

较小报文场景 createUser、getUser 下，提升率约 180%。
极小报文 existUser(仅一个boolean值)下提升率约 24%
较大报文 listUser 提升率最高，达到了 1000%！

Triple protocol benchmark

较小报文场景 createUser、existUser、getUser 下，较 3.1 版本性能提升约 40-45%，提升后的性能与 gRPC 同场景的性能基本持平。
较大报文场景 listUser 下较 3.1 版本提升了约 17%，相较于同场景下的 gRPC 低 11%。

超时时间

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

1.介绍

本示例演示如何在 Dubbo-go 客户端发起调用时设置请求超时时间。可在此查看完整示例源码地址

2.如何设置请求超时时间

在创建客户端时，可以使用 client.WithRequestTimeout() 方法设置全局超时时间（所有使用改 client 的服务代理共享）。

 cli, err := client.NewClient(
 client.WithClientURL("tri://127.0.0.1:20000"),
 client.WithClientRequestTimeout(3 * time.Second),
 )

可以使用 client.WithRequestTimeout() 创建服务粒度的超时时间（以下服务代理 svc 发起的方法调用都使用这个时间）。

 svc, err := greet.NewGreetService(cli, client.WithRequestTimeout(5 * time.Second))

也可以在调用发起时，使用 client.WithCallRequestTimeout() 指定一个超时时间

resp, err := svc.GreetTimeout(context.Background(), &greet.GreetRequest{Name: "hello world"}, client.WithCallRequestTimeout(10 * time.Second))

从上往下，以上三种方式的优先级逐步提高，client.WithCallRequestTimeout() 指定的超时时间优先级最高。

3.示例详解

3.1服务端介绍

服务端proto文件

源文件路径：dubbo-go-sample/timeout/proto/greet.proto

syntax = "proto3";

package greet;

option go_package = "github.com/apache/dubbo-go-samples/timeout/proto;greet";

message GreetRequest {
 string name = 1;
}

message GreetResponse {
 string greeting = 1;
}

service GreetService {
 rpc Greet(GreetRequest) returns (GreetResponse) {}
 rpc GreetTimeout(GreetRequest) returns (GreetResponse) {}
}

服务端handler文件

Greet方法直接响应，GreetTimeout方法等待五秒后响应（模拟超时）。

创建基于Spring Boot的微服务应用

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

以下文档将引导您从头创建一个基于 Spring Boot 的 Dubbo 应用，并为应用配置 Triple 通信协议、服务发现等微服务基础能力。

快速创建应用

以下是我们为您提前准备好的示例项目，可通过如下命令快速下载示例源码。在实际开发中，您也可以访问 start.dubbo.apache.org 快速创建一个全新的 Dubbo 应用模板。

curl -O -# https://dubbo-demo.oss-cn-hangzhou.aliyuncs.com/quickstart/dubbo-quickstart.zip
unzip dubbo-quickstart
cd dubbo-quickstart

提示

本项目源码在 Dubbo Github 示例仓库中维护 https://github.com/apache/dubbo-samples

本地启动应用

接下来，让我们尝试在本地启动应用。运行以下命令启动应用：

chmod a+x ./mvnw
./mvnw clean install -DskipTests
./mvnw compile -pl quickstart-service exec:java -Dexec.mainClass="org.apache.dubbo.samples.quickstart.QuickStartApplication"

注意

运行示例要求 JDK 17+ 版本。
由于配置文件中启用了注册中心，您需要首先在本地启动 Nacos 注册中心 server。或者参考下一篇 Kubernetes 部署方式。

在应用启动成功后，本地进程使用 Triple 协议在指定端口发布了服务。同时可以看到消费端持续对提供端发起调用：

Started QuickStartApplication in 4.38 seconds (process running for 4.629)
Receive result ======> Hello world

可直接使用 cURL 测试服务是否已经正常运行：

使用原生 API 开发 Dubbo 应用

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

你可能已经注意到了，文档中大部分的功能、示例都是基于 Spring Boot 模式编写的，但 Spring Boot 或 Spring 仅仅是 Dubbo 适配的一种应用或者微服务开发模式。作为一款 RPC 框架，Dubbo 定义了一套完善的 API 接口，我们可以基于原生 API 开发 Dubbo 应用，纯 API 可以实现的业务场景包括：

轻量 RPC Server & Client，通常用于一些应用内、基础组件、中间件等内的简单远程调用场景
微服务应用，不依赖 Spring 的情况下，直接用 API 开发微服务

API 概览

public class Application {
 public static void main(String[] args) {
 DubboBootstrap.getInstance()
 .protocol(new ProtocolConfig(CommonConstants.TRIPLE, 50051))
 .service(ServiceBuilder.newBuilder().interfaceClass(DemoService.class).ref(new DemoServiceImpl()).build())
 .start()
 .await();
 }
}

以上是启动 Dubbo RPC Server 的一段代码示例，DubboBootstrap 实例代表一个 Dubbo 应用，是整个 Dubbo 应用的启动入口。在 DubboBootstrap 基础上，我们可以设置 protocol、service、registry、metrics 等来注册服务、连接注册中心等，这和我们在 Spring Boot 中调整 application.yml 或者 application.properties 文件是对等的作用。

代码架构

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

整体设计

图例说明：

图中左边淡蓝背景的为服务消费方使用的接口，右边淡绿色背景的为服务提供方使用的接口，位于中轴线上的为双方都用到的接口。
图中从下至上分为十层，各层均为单向依赖，右边的黑色箭头代表层之间的依赖关系，每一层都可以剥离上层被复用，其中，Service 和 Config 层为 API，其它各层均为 SPI。
图中绿色小块的为扩展接口，蓝色小块为实现类，图中只显示用于关联各层的实现类。
图中蓝色虚线为初始化过程，即启动时组装链，红色实线为方法调用过程，即运行时调用链，紫色三角箭头为继承，可以把子类看作父类的同一个节点，线上的文字为调用的方法。

各层说明

Config 配置层：对外配置接口，以 ServiceConfig, ReferenceConfig 为中心，可以直接初始化配置类，也可以通过 spring 解析配置生成配置类
Proxy 服务代理层：服务接口透明代理，生成服务的客户端 Stub 和服务器端 Skeleton, 以 ServiceProxy 为中心，扩展接口为 ProxyFactory
Registry 注册中心层：封装服务地址的注册与发现，以服务 URL 为中心，扩展接口为 RegistryFactory, Registry, RegistryService
Cluster 路由层：封装多个提供者的路由及负载均衡，并桥接注册中心，以 Invoker 为中心，扩展接口为 Cluster, Directory, Router, LoadBalance
Monitor 监控层：RPC 调用次数和调用时间监控，以 Statistics 为中心，扩展接口为 MonitorFactory, Monitor, MonitorService
Protocol 远程调用层：封装 RPC 调用，以 Invocation, Result 为中心，扩展接口为 Protocol, Invoker, Exporter
Exchange 信息交换层：封装请求响应模式，同步转异步，以 Request, Response 为中心，扩展接口为 Exchanger, ExchangeChannel, ExchangeClient, ExchangeServer
Transport 网络传输层：抽象 mina 和 netty 为统一接口，以 Message 为中心，扩展接口为 Channel, Transporter, Client, Server, Codec
Serialize 数据序列化层：可复用的一些工具，扩展接口为 Serialization, ObjectInput, ObjectOutput, ThreadPool

关系说明

在 RPC 中，Protocol 是核心层，也就是只要有 Protocol + Invoker + Exporter 就可以完成非透明的 RPC 调用，然后在 Invoker 的主过程上 Filter 拦截点。
图中的 Consumer 和 Provider 是抽象概念，只是想让看图者更直观的了解哪些类分属于客户端与服务器端，不用 Client 和 Server 的原因是 Dubbo 在很多场景下都使用 Provider, Consumer, Registry, Monitor 划分逻辑拓扑节点，保持统一概念。
而 Cluster 是外围概念，所以 Cluster 的目的是将多个 Invoker 伪装成一个 Invoker，这样其它人只要关注 Protocol 层 Invoker 即可，加上 Cluster 或者去掉 Cluster 对其它层都不会造成影响，因为只有一个提供者时，是不需要 Cluster 的。
Proxy 层封装了所有接口的透明化代理，而在其它层都以 Invoker 为中心，只有到了暴露给用户使用时，才用 Proxy 将 Invoker 转成接口，或将接口实现转成 Invoker，也就是去掉 Proxy 层 RPC 是可以 Run 的，只是不那么透明，不那么看起来像调本地服务一样调远程服务。
而 Remoting 实现是 Dubbo 协议的实现，如果你选择 RMI 协议，整个 Remoting 都不会用上，Remoting 内部再划为 Transport 传输层和 Exchange 信息交换层，Transport 层只负责单向消息传输，是对 Mina, Netty, Grizzly 的抽象，它也可以扩展 UDP 传输，而 Exchange 层是在传输层之上封装了 Request-Response 语义。
Registry 和 Monitor 实际上不算一层，而是一个独立的节点，只是为了全局概览，用层的方式画在一起。

模块分包

地址找不到异常

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

在开发与生产部署过程中，由于 Dubbo 是一个需要基于服务发现功能进行调用的框架，很容易由于各种客观原因出现 No Provder 的异常，本文旨在通过体系化的排查思路，让您能够在异常的时候快速定位原因并解决。

java.lang.IllegalStateException: Failed to check the status of the service org.apache.dubbo.samples.api.GreetingsService. No provider available for the service org.apache.dubbo.samples.api.GreetingsService from the url consumer://*** to the consumer 30.221.146.226 use dubbo version 3.2.0-beta.4

Exception in thread "main" org.apache.dubbo.rpc.RpcException: No provider available from registry 127.0.0.1:2181 for service org.apache.dubbo.samples.api.GreetingsService on consumer 30.221.146.226 use dubbo version 3.2.0-beta.4, please check status of providers(disabled, not registered or in blacklist).

一句话总结

服务找不到时先自查服务是否已经开发完部署了，然后在注册中心中确认是否已经注册，如果注册检查服务端发布情况、如果未注册检查消费端订阅情况，中间任何一步出问题都会导致异常。

排查思路全览

调用拦截扩展

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

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

扩展说明

服务提供方和服务消费方调用过程拦截，Dubbo 本身的大多功能均基于此扩展点实现，每次远程方法执行，该拦截都会被执行，请注意对性能的影响。

约定：

用户自定义 filter 默认在内置 filter 之后。
特殊值 default，表示缺省扩展点插入的位置。比如：filter="xxx,default,yyy"，表示 xxx 在缺省 filter 之前，yyy 在缺省 filter 之后。
特殊符号 -，表示剔除。比如：filter="-foo1"，剔除添加缺省扩展点 foo1。比如：filter="-default"，剔除添加所有缺省扩展点。
provider 和 service 同时配置的 filter 时，累加所有 filter，而不是覆盖。比如：<dubbo:provider filter="xxx,yyy"/> 和 <dubbo:service filter="aaa,bbb" />，则 xxx,yyy,aaa,bbb 均会生效。如果要覆盖，需配置：<dubbo:service filter="-xxx,-yyy,aaa,bbb" />

扩展接口

org.apache.dubbo.rpc.Filter

扩展配置

<!-- 消费方调用过程拦截 -->
<dubbo:reference filter="xxx,yyy" />
<!-- 消费方调用过程缺省拦截器，将拦截所有reference -->
<dubbo:consumer filter="xxx,yyy"/>
<!-- 提供方调用过程拦截 -->
<dubbo:service filter="xxx,yyy" />
<!-- 提供方调用过程缺省拦截器，将拦截所有service -->
<dubbo:provider filter="xxx,yyy"/>

已知扩展

org.apache.dubbo.rpc.filter.EchoFilter
org.apache.dubbo.rpc.filter.GenericFilter
org.apache.dubbo.rpc.filter.GenericImplFilter
org.apache.dubbo.rpc.filter.TokenFilter
org.apache.dubbo.rpc.filter.AccessLogFilter
org.apache.dubbo.rpc.filter.CountFilter
org.apache.dubbo.rpc.filter.ActiveLimitFilter
org.apache.dubbo.rpc.filter.ClassLoaderFilter
org.apache.dubbo.rpc.filter.ContextFilter
org.apache.dubbo.rpc.filter.ConsumerContextFilter
org.apache.dubbo.rpc.filter.ExceptionFilter
org.apache.dubbo.rpc.filter.ExecuteLimitFilter
org.apache.dubbo.rpc.filter.DeprecatedFilter

扩展示例

Maven 项目结构：

调用拦截扩展

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

扩展说明

服务提供方和服务消费方调用过程拦截，Dubbo 本身的大多功能均基于此扩展点实现，每次远程方法执行，该拦截都会被执行，请注意对性能的影响。

约定：

用户自定义 filter 默认在内置 filter 之后。
特殊值 default，表示缺省扩展点插入的位置。比如：filter="xxx,default,yyy"，表示 xxx 在缺省 filter 之前，yyy 在缺省 filter 之后。
特殊符号 -，表示剔除。比如：filter="-foo1"，剔除添加缺省扩展点 foo1。比如：filter="-default"，剔除添加所有缺省扩展点。
provider 和 service 同时配置的 filter 时，累加所有 filter，而不是覆盖。比如：<dubbo:provider filter="xxx,yyy"/> 和 <dubbo:service filter="aaa,bbb" />，则 xxx,yyy,aaa,bbb 均会生效。如果要覆盖，需配置：<dubbo:service filter="-xxx,-yyy,aaa,bbb" />

扩展接口

org.apache.dubbo.rpc.Filter

扩展配置

<!-- 消费方调用过程拦截 -->
<dubbo:reference filter="xxx,yyy" />
<!-- 消费方调用过程缺省拦截器，将拦截所有reference -->
<dubbo:consumer filter="xxx,yyy"/>
<!-- 提供方调用过程拦截 -->
<dubbo:service filter="xxx,yyy" />
<!-- 提供方调用过程缺省拦截器，将拦截所有service -->
<dubbo:provider filter="xxx,yyy"/>

已知扩展

org.apache.dubbo.rpc.filter.EchoFilter
org.apache.dubbo.rpc.filter.GenericFilter
org.apache.dubbo.rpc.filter.GenericImplFilter
org.apache.dubbo.rpc.filter.TokenFilter
org.apache.dubbo.rpc.filter.AccessLogFilter
org.apache.dubbo.rpc.filter.CountFilter
org.apache.dubbo.rpc.filter.ActiveLimitFilter
org.apache.dubbo.rpc.filter.ClassLoaderFilter
org.apache.dubbo.rpc.filter.ContextFilter
org.apache.dubbo.rpc.filter.ConsumerContextFilter
org.apache.dubbo.rpc.filter.ExceptionFilter
org.apache.dubbo.rpc.filter.ExecuteLimitFilter
org.apache.dubbo.rpc.filter.DeprecatedFilter

扩展示例

Maven 项目结构：

调用拦截扩展

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

扩展说明

服务提供方和服务消费方调用过程拦截，Dubbo 本身的大多功能均基于此扩展点实现，每次远程方法执行，该拦截都会被执行，请注意对性能的影响。

约定：

用户自定义 filter 默认在内置 filter 之后。
特殊值 default，表示缺省扩展点插入的位置。比如：filter="xxx,default,yyy"，表示 xxx 在缺省 filter 之前，yyy 在缺省 filter 之后。
特殊符号 -，表示剔除。比如：filter="-foo1"，剔除添加缺省扩展点 foo1。比如：filter="-default"，剔除添加所有缺省扩展点。
provider 和 service 同时配置的 filter 时，累加所有 filter，而不是覆盖。比如：<dubbo:provider filter="xxx,yyy"/> 和 <dubbo:service filter="aaa,bbb" />，则 xxx,yyy,aaa,bbb 均会生效。如果要覆盖，需配置：<dubbo:service filter="-xxx,-yyy,aaa,bbb" />

扩展接口

org.apache.dubbo.rpc.Filter

扩展配置

<!-- 消费方调用过程拦截 -->
<dubbo:reference filter="xxx,yyy" />
<!-- 消费方调用过程缺省拦截器，将拦截所有reference -->
<dubbo:consumer filter="xxx,yyy"/>
<!-- 提供方调用过程拦截 -->
<dubbo:service filter="xxx,yyy" />
<!-- 提供方调用过程缺省拦截器，将拦截所有service -->
<dubbo:provider filter="xxx,yyy"/>

已知扩展

org.apache.dubbo.rpc.filter.EchoFilter
org.apache.dubbo.rpc.filter.GenericFilter
org.apache.dubbo.rpc.filter.GenericImplFilter
org.apache.dubbo.rpc.filter.TokenFilter
org.apache.dubbo.rpc.filter.AccessLogFilter
org.apache.dubbo.rpc.filter.CountFilter
org.apache.dubbo.rpc.filter.ActiveLimitFilter
org.apache.dubbo.rpc.filter.ClassLoaderFilter
org.apache.dubbo.rpc.filter.ContextFilter
org.apache.dubbo.rpc.filter.ConsumerContextFilter
org.apache.dubbo.rpc.filter.ExceptionFilter
org.apache.dubbo.rpc.filter.ExecuteLimitFilter
org.apache.dubbo.rpc.filter.DeprecatedFilter

扩展示例

Maven 项目结构：

动态调整服务超时时间

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

Dubbo 提供动态调整服务超时时间的能力，在无需重启应用的情况下调整服务的超时时间，这对于临时解决一些服务上下游依赖不稳定而导致的调用失败问题非常有效。

开始之前

部署 Shop 商城项目
部署并打开 Dubbo Admin

任务详情

商城项目通过 org.apache.dubbo.samples.UserService 提供用户信息管理服务，访问 http://localhost:8080/ 打开商城并输入任意账号密码，点击 Login 即可以正常登录到系统。

有些场景下，User 服务的运行速度会变慢，比如存储用户数据的数据库负载过高导致查询变慢，这时就会出现 UserService 访问超时的情况，导致登录失败。

在示例系统中，可通过下图 Timeout Login 模拟突发的 UserService 访问超时异常

通过规则动态调整超时时间

为了解决突发的登录超时问题，我们只需要适当增加 UserService 服务调用的等待时间即可。

操作步骤

打开 Dubbo Admin 控制台
在左侧导航栏选择【服务治理】>【动态配置】
点击 “创建”，输入服务 org.apache.dubbo.samples.UserService 和新的超时时间如 2000 即可。

保存后，再次点击 Timeout Login，此时在经过短暂的等待后系统可以正常登录。

规则详解

规则 key ：org.apache.dubbo.samples.UserService

规则体

configVersion: v3.0
enabled: true
configs:
 - side: provider
 parameters:
 timeout: 2000

从 UserService 服务提供者视角，将超时时间总体调整为 2s。

动态配置中心

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

废弃警告

dubbo-go 泛化调用仅适用于 dubbo2 协议，不适用 triple 协议

泛化调用是一种 Dubbo-Go 的特殊调用方式，它允许中间节点在没有接口信息的情况下传递调用信息，常被用于测试、网关的场景下。泛化调用支持 Dubbo 和 Triple 协议，但是目前序列化方案只支持 Hessian。

背景

为了便于理解，这篇文档中以网关使用场景介绍泛化调用。我们先来考虑普通调用（非泛化调用）。下图包含了 consumer 和 provider 两个关键角色（后文中用 endpoint 代表一个 consumer 或一个 provider），各自都有一份关于 org.apache.dubbo.sample.User 接口的定义。假定在调用行为中需要使用 org.apache.dubbo.sample.User 接口。

RPC 需要借助网络介质传输，因此数据不能以 go struct 形式传输，而必须以二进制形式传输。这就要求 consumer 端在传输前，需要将实现 org.apache.dubbo.sample.User 接口的结构体序列化为二进制格式。同样的，对于 provider 端，需要将二进制数据反序列化为结构体信息。总之，普通调用要求接口信息在每一个 endpoint 必须有相同的定义，这样才能保证数据序列化和反序列化的结果与预期一致。

在网关场景下，网关不可能存储全部接口定义。比如一个网关需要转发 100 个服务调用，每个服务需要的接口数量为 10 个，普通调用要求把 1000 个（100 * 10）接口定义提前全部存储在网关内，这显然是难以做到的。所以有没有一种方式可以既不需要提前存储接口定义，又能正确转发调用呢？答案是肯定的，这就是使用泛化调用的原因。

原理

泛化调用本质上就是把复杂结构转化为通用结构，这里说的通用结构是指 map、string 等，网关是可以顺利解析并传递这些通用结构的。

目前，Dubbo-go v3 只支持 Map 泛化方式（default）。我们以 User 接口为例，其定义如下所示。

// definition
type User struct {
	ID string
	Name string
	Age int32
}

func (u *User) JavaClassName() string {
	return "org.apache.dubbo.sample.User"
}

假定调用一个服务需要一个 user 作为入参，其定义如下所示。

服务发现

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

Dubbo Rust服务发现简介

Dubbo Rust提供的是一种 Client-Based 的服务发现机制，依赖第三方注册中心组件来协调服务发现过程，支持的注册中心： Nacos、Zookeeper

以下是 Dubbo Rust服务发现机制的基本工作原理图：

服务发现包含提供者、消费者和注册中心三个参与角色，其中，Dubbo 提供者实例注册 URL 地址到注册中心，注册中心负责对数据进行聚合，Dubbo 消费者从注册中心读取地址列表并订阅变更，每当地址列表发生变化，注册中心将最新的列表通知到所有订阅的消费者实例。

Dubbo Rust注册中心以服务粒度聚合实例数据，消费者按消费需求精准订阅。

Dubbo Rust服务发现的一个示例：example

高效地址推送实现

从注册中心视角来看，它负责以服务名 (例如：org.apache.dubbo.sample.tri.Greeter) 对整个集群的实例地址进行聚合，每个对外提供服务的实例将自身的实例ip:port 地址信息 (例如：127.0.0.1:8848) 注册到注册中心。

配置方式

Dubbo Rust服务发现支持两种注册中心组件，既Nacos、Zookeeper，可以通过以下方式创建不同的注册中心，并将其绑定到Dubbo Rust框架。

配置方式：假设有服务：Greeter，对应的服务实现为GreeterServerImpl

服务端：

 //注册服务
 register_server(GreeterServerImpl {
 name: "greeter".to_string(),
 });
 
 //创建注册中心
 let zkr = ZookeeperRegistry::default();
 
 let r = RootConfig::new();
 let r = match r.load() {
 Ok(config) => config,
 Err(_err) => panic!("err: {:?}", _err), // response was droped
 };
 
 //启动Dubbo框架
 let mut f = Dubbo::new()
 .with_config(r)
 //将创建出的注册中心绑定Dubbo框架
 .add_registry("zookeeper", Box::new(zkr));
 f.start().await;

对于上述过程，可以通过修改创建注册中心的步骤来更改所使用的注册中心

服务发现

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

Dubbo 提供的是一种 Client-Based 的服务发现机制，依赖第三方注册中心组件来协调服务发现过程，支持常用的注册中心如 Nacos、Consul、Zookeeper 等。

以下是 Dubbo 服务发现机制的基本工作原理图：

面向百万实例集群的服务发现机制

区别于其他很多微服务框架的是，Dubbo3 的服务发现机制诞生于阿里巴巴超大规模微服务电商集群实践场景，因此，其在性能、可伸缩性、易用性等方面的表现大幅领先于业界大多数主流开源产品。是企业面向未来构建可伸缩的微服务集群的最佳选择。

首先，Dubbo 注册中心以应用粒度聚合实例数据，消费者按消费需求精准订阅，避免了大多数开源框架如 Istio、Spring Cloud 等全量订阅带来的性能瓶颈。
其次，Dubbo SDK 在实现上对消费端地址列表处理过程做了大量优化，地址通知增加了异步、缓存、bitmap 等多种解析优化，避免了地址更新常出现的消费端进程资源波动。
最后，在功能丰富度和易用性上，服务发现除了同步 ip、port 等端点基本信息到消费者外，Dubbo 还将服务端的 RPC/HTTP 服务及其配置的元数据信息同步到消费端，这让消费者、提供者两端的更细粒度的协作成为可能，Dubbo 基于此机制提供了很多差异化的治理能力。

高效地址推送实现

从注册中心视角来看，它负责以应用名 (dubbo.application.name) 对整个集群的实例地址进行聚合，每个对外提供服务的实例将自身的应用名、实例ip:port 地址信息 (通常还包含少量的实例元数据，如机器所在区域、环境等) 注册到注册中心。

Dubbo2 版本注册中心以服务粒度聚合实例地址，比应用粒度更细，也就意味着传输的数据量更大，因此在大规模集群下也遇到一些性能问题。针对 Dubbo2 与 Dubbo3 跨版本数据模型不统一的问题，Dubbo3 给出了平滑迁移方案，可做到模型变更对用户无感。

每个消费服务的实例从注册中心订阅实例地址列表，相比于一些产品直接将注册中心的全量数据 (应用 + 实例地址) 加载到本地进程，Dubbo 实现了按需精准订阅地址信息。比如一个消费者应用依赖 app1、app2，则只会订阅 app1、app2 的地址列表更新，大幅减轻了冗余数据推送和解析的负担。

丰富元数据配置

除了与注册中心的交互，Dubbo3 的完整地址发现过程还有一条额外的元数据通路，我们称之为元数据服务 (MetadataService)，实例地址与元数据共同组成了消费者端有效的地址列表。

完整工作流程如上图所示，首先，消费者从注册中心接收到地址 (ip:port) 信息，然后与提供者建立连接并通过元数据服务读取到对端的元数据配置信息，两部分信息共同组装成 Dubbo 消费端有效的面向服务的地址列表。以上两个步骤都是在实际的 RPC 服务调用发生之前。

服务路由规则

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

条件路由

使用模式与条件路由文档中的模式类似，但配置格式略有不同，以下是条件路由规则示例。

基于以下示例规则，所有 org.apache.dubbo.sample.tri.Greeter 服务 greet 方法的调用都将被转发到有 port=8888 标记的地址子集

configVersion: v1.0
scope: "service"
force: false
enabled: true
key: "org.apache.dubbo.sample.tri.Greeter"
conditions:
 - method=greet => port=8888

注：
dubbo rust目前还没有实现对于应用粒度的区分，无法区分服务来自哪个应用
因此对于标签路由和条件路由，都仅能配置一条应用级别的配置
对于应用级别的配置，默认key指定为application，此配置将对全部服务生效
例如：

configVersion: v1.0
scope: "application"
force: false
enabled: true
key: application
conditions:
 - ip=127.0.0.1 => port=8000~8888

匹配/过滤条件

参数支持

服务调用上下文，如：service_name, method等
URL 本身的字段，如：location, ip, port等
URL params中存储的字段信息

条件支持

等号 = 表示 “匹配”，如：method = getComment
不等号 != 表示 “不匹配”，如：method != getComment

值支持

以逗号 , 分隔多个值，如：ip != 10.20.153.10,10.20.153.11
以星号 * 结尾，表示通配，如：ip != 10.20.*
整数值范围，如：port = 80~8080

标签路由

使用模式与标签路由文档中的模式类似，但配置格式略有不同，以下是标签路由规则示例

通过重试提高服务调用成功率

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

在服务初次调用失败后，通过重试能有效的提升总体调用成功率。但也要注意重试可能带来的响应时间增长，系统负载升高等，另外，重试一般适用于只读服务，或者具有幂等性保证的写服务。

开始之前

部署 Shop 商城项目
部署并打开 Dubbo Admin

任务详情

成功登录商城项目后，商城会默认在首页展示当前登录用户的详细信息。

但有些时候，提供用户详情的 Dubbo 服务也会由于网络不稳定等各种原因变的不稳定，比如我们提供用户详情的 User 服务就很大概率会调用失败，导致用户无法看到账户的详细信息。

用户账户详情查询失败后的系统界面如下：

商城为了获得带来更好的使用体验，用户信息的加载过程是异步的，因此用户信息加载失败并不会影响对整个商城页面的正常访问，但如果能始终展示完整的用户信息总能给使用者留下更好的印象。

增加重试提高成功率

考虑到访问用户详情的过程是异步的（隐藏在页面加载背后），只要最终数据能加载出来，适当的增加等待时间并不是大的问题。因此，我们可以考虑通过对每次用户访问增加重试次数的方式，提高服务详情服务的整体访问成功率。

操作步骤

打开 Dubbo Admin 控制台
在左侧导航栏选择【服务治理】>【动态配置】
点击 “创建”，输入服务 org.apache.dubbo.samples.UserService 和失败重试次数如 4 即可。

保存后，尝试多次刷新页面，发现用户详情数据总是能正常显示，虽然有时由于重试的缘故加载时间会明显变长。

规则详解

规则 key ：org.apache.dubbo.samples.UserService

规则体

configVersion: v3.0
enabled: true
configs:
 - side: consumer
 parameters:
 retries: 5

从 UserService 服务消费者视角（即 Frontend 应用）增加了调用失败后的重试次数。

parameters:
 retries: 5

side: consumer 配置会将规则发送到服务消费方实例，所有 UserService 服务实例会基于新的 timeout 值进行重新发布，并通过注册中心通知给所有消费方。

清理

为了不影响其他任务效果，通过 Admin 删除或者禁用刚刚配置的重试规则。

基础命令手册

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

基础命令功能提供了一系列的基础命令。

help 命令

显示更多命令

//列出所有命令
dubbo>help

//列出单个命令的具体使用情况
dubbo>help online
+--------------+----------------------------------------------------------------------------------+
| COMMAND NAME | online |
+--------------+----------------------------------------------------------------------------------+
| EXAMPLE | online dubbo |
| | online xx.xx.xxx.service |
+--------------+----------------------------------------------------------------------------------+

dubbo>

version 命令

显示当前运行的 Dubbo 的版本号

dubbo>version
dubbo version "3.0.10-SNAPSHOT"

dubbo>

quit 命令

退出命令状态

dubbo>quit
BYE!
Connection closed by foreign host.

集群容错

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

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

在集群调用失败时，Dubbo 提供了多种容错方案，缺省为 failover 重试。

各节点关系：

这里的 Invoker 是 Provider 的一个可调用 Service 的抽象，Invoker 封装了 Provider 地址及 Service 接口信息
Directory 代表多个 Invoker，可以把它看成 List<Invoker> ，但与 List 不同的是，它的值可能是动态变化的，比如注册中心推送变更
Cluster 将 Directory 中的多个 Invoker 伪装成一个 Invoker，对上层透明，伪装过程包含了容错逻辑，调用失败后，重试另一个
Router 负责从多个 Invoker 中按路由规则选出子集，比如读写分离，应用隔离等
LoadBalance 负责从多个 Invoker 中选出具体的一个用于本次调用，选的过程包含了负载均衡算法，调用失败后，需要重选

集群容错模式

可以自行扩展集群容错策略，参见：集群扩展

Failover Cluster

失败自动切换，当出现失败，重试其它服务器。通常用于读操作，但重试会带来更长延迟。可通过 retries="2" 来设置重试次数(不含第一次)。

重试次数配置如下：

<dubbo:service retries="2" />

或

<dubbo:reference retries="2" />

或

<dubbo:reference>
 <dubbo:method name="findFoo" retries="2" />
</dubbo:reference>

提示

该配置为缺省配置

Failfast Cluster

快速失败，只发起一次调用，失败立即报错。通常用于非幂等性的写操作，比如新增记录。

Failsafe Cluster

失败安全，出现异常时，直接忽略。通常用于写入审计日志等操作。

集群容错

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

背景

在集群调用失败时，Dubbo 提供了多种容错方案，缺省为 failover 重试。

各节点关系：

这里的 Invoker 是 Provider 的一个可调用 Service 的抽象，Invoker 封装了 Provider 地址及 Service 接口信息
Directory 代表多个 Invoker，可以把它看成 List<Invoker> ，但与 List 不同的是，它的值可能是动态变化的，比如注册中心推送变更
Cluster 将 Directory 中的多个 Invoker 伪装成一个 Invoker，对上层透明，伪装过程包含了容错逻辑，调用失败后，重试另一个
Router 负责从多个 Invoker 中按路由规则选出子集，比如读写分离，应用隔离等
LoadBalance 负责从多个 Invoker 中选出具体的一个用于本次调用，选的过程包含了负载均衡算法，调用失败后，需要重选

集群容错模式

可以自行扩展集群容错策略，参见：集群扩展

Failover Cluster

失败自动切换，当出现失败，重试其它服务器。通常用于读操作，但重试会带来更长延迟。可通过 retries="2" 来设置重试次数(不含第一次)。

重试次数配置如下：

<dubbo:service retries="2" />

或

<dubbo:reference retries="2" />

或

<dubbo:reference>
 <dubbo:method name="findFoo" retries="2" />
</dubbo:reference>

提示

该配置为缺省配置

Failfast Cluster

快速失败，只发起一次调用，失败立即报错。通常用于非幂等性的写操作，比如新增记录。

Failsafe Cluster

失败安全，出现异常时，直接忽略。通常用于写入审计日志等操作。

开发微服务

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

本示例演示了使用 dubbo-go 开发微服务应用，为应用增加包括服务发现、负载均衡、流量管控等微服务核心能力。

前置条件

本示例我们继续使用 Protobuf 开发微服务应用，请参考开发 rpc server 和 rpc client 了解如何安装 protoc、protoc-gen-go-triple 等必须插件。

快速运行示例

下载示例源码

我们在 apache/dubbo-go-samples 仓库维护了一系列 dubbo-go 使用示例，用来帮助用户快速学习 dubbo-go 使用方式。

$ git clone --depth 1 https://github.com/apache/dubbo-go-samples

切换到快速开始示例目录：

$ cd dubbo-go-samples/registry/nacos

启动 Nacos

由于示例应用中启用了服务发现能力且使用 Nacos 作为注册中心，在运行示例之前需要先启动注册中心。请参考 Nacos 本地安装了解如何快速安装和启动 Nacos。

运行 server

在 go-server/cmd 示例目录：

运行以下命令，启动 server：

$ go run server.go

使用 cURL 验证 server 正常启动：

$ curl \
 --header "Content-Type: application/json" \
 --data '{"name": "Dubbo"}' \
 http://localhost:50051/greet.v1.GreetService/Greet

Greeting: Hello world

运行 client

打开一个新的 terminal，运行以下命令，启动 client

快速开始

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

Dubbo 采用全 Spring 配置方式，透明化接入应用，对应用没有任何 API 侵入，只需用 Spring 加载 Dubbo 的配置即可，Dubbo 基于 Spring 的 Schema 扩展进行加载。

如果不想使用 Spring 配置，可以通过 API 的方式进行调用。

服务提供者

完整安装步骤，请参见：示例提供者安装

定义服务接口

DemoService.java ¹：

package org.apache.dubbo.demo;

public interface DemoService {
 String sayHello(String name);
}

在服务提供方实现接口

DemoServiceImpl.java ²：


package org.apache.dubbo.demo.provider;
 
import org.apache.dubbo.demo.DemoService;
 
public class DemoServiceImpl implements DemoService {
 public String sayHello(String name) {
 return "Hello " + name;
 }
}

用 Spring 配置声明暴露服务

provider.xml：

<?xml version="1.0" encoding="UTF-8"?>
<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"
 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:application name="hello-world-app" />
 
 <!-- 使用multicast广播注册中心暴露服务地址 -->
 <dubbo:registry address="multicast://224.5.6.7:1234" />
 
 <!-- 用dubbo协议在20880端口暴露服务 -->
 <dubbo:protocol name="dubbo" port="20880" />
 
 <!-- 声明需要暴露的服务接口 -->
 <dubbo:service interface="org.apache.dubbo.demo.DemoService" ref="demoService" />
 
 <!-- 和本地bean一样实现服务 -->
 <bean id="demoService" class="org.apache.dubbo.demo.provider.DemoServiceImpl" />
</beans>

加载 Spring 配置

Provider.java：

Dubbo 框架内置的并发控制策略

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

Dubbo 通过 Filter 拦截器机制，内置了并发控制策略实现。限制从同一客户端到同一服务的并发请求数，防止恶意请求使服务器过载，确保服务的稳定性，并防止使用过多资源。

控制某些服务的最大并发请求数，确保其他服务的资源可用性。系统过载和确保系统稳定性。
允许在需求增加时更平滑地扩展服务。
确保服务在高峰使用时间保持可靠和稳定。

注意

这种方式要求用户准确的预先评估系统能处理的并发数，而准确的评估系统处理能力并不是一件容易的事情，因此 Dubbo 还提供了自适应限流模式，根据系统负载自动识别系统健康程度并进行限流保护，可以在此查看自适应限流模式使用文档。

限流策略配置

限制服务器端并发执行数(服务粒度)

限制 com.foo.BarService 的每个方法，服务器端并发执行（或占用线程池线程数）不能超过 10 个

XML 方式：

<dubbo:service interface="com.foo.BarService" executes="10" />

注解方式：

@DubboService(executes=10)
private DemoServiceImpl implements DemoService{}

限制服务器端并发执行数(方法粒度)

限制 com.foo.BarService 的 sayHello 方法，服务器端并发执行（或占用线程池线程数）不能超过 10 个

XML 方式：

<dubbo:service interface="com.foo.BarService">
 <dubbo:method name="sayHello" executes="10" />
</dubbo:service>

注解方式：

@DubboService(executes=10, methods = {@Method(name="sayHello",executes=10)})
private DemoServiceImpl implements DemoService{}

限制消费端并发调用数(服务粒度)

限制 com.foo.BarService 的每个方法，每客户端并发执行（或占用连接的请求数）不能超过 10 个

XML 方式：

<dubbo:service interface="com.foo.BarService" actives="10" />

注解方式：

@DubboReference(actives=10)
private DemoService demoService;

限制消费端并发调用数(方法粒度)

限制 com.foo.BarService 的 sayHello 方法，每客户端并发执行（或占用连接的请求数）不能超过 10 个

框架设计

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

整体设计

图例说明：

图中左边淡蓝背景的为服务消费方使用的接口，右边淡绿色背景的为服务提供方使用的接口，位于中轴线上的为双方都用到的接口。
图中从下至上分为十层，各层均为单向依赖，右边的黑色箭头代表层之间的依赖关系，每一层都可以剥离上层被复用，其中，Service 和 Config 层为 API，其它各层均为 SPI。
图中绿色小块的为扩展接口，蓝色小块为实现类，图中只显示用于关联各层的实现类。
图中蓝色虚线为初始化过程，即启动时组装链，红色实线为方法调用过程，即运行时调时链，紫色三角箭头为继承，可以把子类看作父类的同一个节点，线上的文字为调用的方法。

各层说明

config 配置层：对外配置接口，以 ServiceConfig, ReferenceConfig 为中心，可以直接初始化配置类，也可以通过 spring 解析配置生成配置类
proxy 服务代理层：服务接口透明代理，生成服务的客户端 Stub 和服务器端 Skeleton, 以 ServiceProxy 为中心，扩展接口为 ProxyFactory
registry 注册中心层：封装服务地址的注册与发现，以服务 URL 为中心，扩展接口为 RegistryFactory, Registry, RegistryService
cluster 路由层：封装多个提供者的路由及负载均衡，并桥接注册中心，以 Invoker 为中心，扩展接口为 Cluster, Directory, Router, LoadBalance
monitor 监控层：RPC 调用次数和调用时间监控，以 Statistics 为中心，扩展接口为 MonitorFactory, Monitor, MonitorService
protocol 远程调用层：封装 RPC 调用，以 Invocation, Result 为中心，扩展接口为 Protocol, Invoker, Exporter
exchange 信息交换层：封装请求响应模式，同步转异步，以 Request, Response 为中心，扩展接口为 Exchanger, ExchangeChannel, ExchangeClient, ExchangeServer
transport 网络传输层：抽象 mina 和 netty 为统一接口，以 Message 为中心，扩展接口为 Channel, Transporter, Client, Server, Codec
serialize 数据序列化层：可复用的一些工具，扩展接口为 Serialization, ObjectInput, ObjectOutput, ThreadPool

关系说明

在 RPC 中，Protocol 是核心层，也就是只要有 Protocol + Invoker + Exporter 就可以完成非透明的 RPC 调用，然后在 Invoker 的主过程上 Filter 拦截点。
图中的 Consumer 和 Provider 是抽象概念，只是想让看图者更直观的了解哪些类分属于客户端与服务器端，不用 Client 和 Server 的原因是 Dubbo 在很多场景下都使用 Provider, Consumer, Registry, Monitor 划分逻辑拓扑节点，保持统一概念。
而 Cluster 是外围概念，所以 Cluster 的目的是将多个 Invoker 伪装成一个 Invoker，这样其它人只要关注 Protocol 层 Invoker 即可，加上 Cluster 或者去掉 Cluster 对其它层都不会造成影响，因为只有一个提供者时，是不需要 Cluster 的。
Proxy 层封装了所有接口的透明化代理，而在其它层都以 Invoker 为中心，只有到了暴露给用户使用时，才用 Proxy 将 Invoker 转成接口，或将接口实现转成 Invoker，也就是去掉 Proxy 层 RPC 是可以 Run 的，只是不那么透明，不那么看起来像调本地服务一样调远程服务。
而 Remoting 实现是 Dubbo 协议的实现，如果你选择 RMI 协议，整个 Remoting 都不会用上，Remoting 内部再划为 Transport 传输层和 Exchange 信息交换层，Transport 层只负责单向消息传输，是对 Mina, Netty, Grizzly 的抽象，它也可以扩展 UDP 传输，而 Exchange 层是在传输层之上封装了 Request-Response 语义。
Registry 和 Monitor 实际上不算一层，而是一个独立的节点，只是为了全局概览，用层的方式画在一起。

模块分包

QoS 命令列表，命令大全

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

QoS 命令	说明	telnet 用法示例	http 用法示例
cd	设定服务上下文，cd 之后所有的命令都是针对该服务	cd org.demo.DemoService	http://localhost:22222/cd?service=org.demo.DemoService
count	展示服务或方法调用次数。暂时只支持 dubbo 协议，不支持 triple 协议；RpcStatus 实现依赖 Active/Limit Filter，需改造	count org.demo.DemoService count org.demo.DemoService methodName	http://localhost:22222/count?service=org.demo.DemoService&method=methodName
disableDetailProfiler	关闭 RPC 调用 profiler 工具（细粒度版本）	disableDetailProfiler	http://localhost:22222/disableDetailProfiler
disableRouterSnapshot	关闭 RPC 请求 Router 路由结果跟踪	disableRouterSnapshot	http://localhost:22222/disableRouterSnapshot
disableSimpleProfiler	关闭 RPC 调用 profiler 工具（粗粒度版）	disableSimpleProfiler	http://localhost:22222/disableSimpleProfiler
enableDetailProfiler	开启 RPC 调用 profiler 工具（细粒度版本）	enableDetailProfiler	http://localhost:22222/enableDetailProfiler
enableRouterSnapshot	开启 RPC 请求 Router 路由结果跟踪，有助于跟踪路由规则执行是否符合预期	enableRouterSnapshot org.demo.DemoService	http://localhost:22222/enableRouterSnapshot?service=org.demo.DemoService
enableSimpleProfiler	开启 RPC 调用 profiler 工具（粗粒度版）	enableSimpleProfiler	http://localhost:22222/enableSimpleProfiler
getAddress	查看某个服务的有效 ip 地址列表	getAddress org.demo.DemoService	http://localhost:22222/getAddress?service=org.demo.DemoService
getConfig	dump 当前应用的有效配置	getConfig	http://localhost:22222/getConfig
getEnabledRouterSnapshot	查看当前 “启用 Router 路由结果跟踪” 的服务列表	getEnabledRouterSnapshot	http://localhost:22222/getEnabledRouterSnapshot
getRecentRouterSnapshot	查看最近 32 条 “Router 路由结果跟踪” 数据	getRecentRouterSnapshot	http://localhost:22222/getRecentRouterSnapshot
gracefulShutdown	从注册中心下线当前 ip 实例注册的所有服务，与offline的区别是，该命令会同时通过 tcp 连接告知所有消费方停止调用此实例。如要恢复，请执行 online 上线所有服务	gracefulShutdown	http://localhost:22222/gracefulShutdown
help	帮助命令	help	http://localhost:22222/help
invoke	调用某个 RPC 服务	invoke org.demo.DemoService.methodName(1234, “abcd”, {“prop”:“value”})	?
live	检查当前进程/服务是否存活，可配置为 kubernetes liveness	live	http://localhost:22222/live
loggerInfo	查看当前日志 logger 配置	loggerInfo	http://localhost:22222/loggerInfo
ls	查看当前所有服务列表	ls	http://localhost:22222/ls
metrics	查看 metrics 指标，需开启metrics 统计才能看到数据。什么粒度？	metrics	http://localhost:22222/metrics
metrics_default	查看 metrics 指标，需开启metrics 统计才能看到数据。什么粒度？	metrics_default	http://localhost:22222/metrics_default
offline	从注册中心下线某个或多个服务（包含应用级和接口级地址）	offline offline org.demo.DemoService	http://localhost:22222/offline http://localhost:22222/offline?service=org.demo.DemoService
offlineApp	从注册中心下线某个或多个服务（仅应用级）	offlineApp offlineApp org.demo.DemoService	http://localhost:22222/offlineApp?service=org.demo.DemoService
offlineInterface	从注册中心下线某个或多个服务（仅接口级）	offlineInterface offlineInterface org.demo.DemoService	http://localhost:22222/offlineInterface?service=org.demo.DemoService
online	将一个或多个服务注册到注册中心（包含应用级和接口级地址）	online online org.demo.DemoService	http://localhost:22222/online?service=org.demo.DemoService
onlineApp	将一个或多个服务注册到注册中心（仅应用级）	onlineApp onlineApp org.demo.DemoService	http://localhost:22222/onlineApp?service=org.demo.DemoService
onlineInterface	将一个或多个服务注册到注册中心（仅接口级）	onlineInterface onlineInterface org.demo.DemoService	http://localhost:22222/onlineInterface?service=org.demo.DemoService
ps	查看当前进程信息，包括监听的端口等	ps	http://localhost:22222/ps
publishMetadata	发布或更新当前应用Metadata数据（可用于手动更新应用级服务发现元数据）。publishMetadata 10 表示延迟 10s 发布。在3.3.0之前版本的命令为 publish-metadata	publishMetadata publishMetadata 10	http://localhost:22222/publishMetadata
pwd	查看当前服务上下文，与 cd 配合使用	pwd	http://localhost:22222/pwd
quit	退出当前 telnet 命令	quit	无
ready	检查当前进程/服务是否准备就绪对外服务，可配置为 kubernetes readiness	ready	http://localhost:22222/ready
select	调用方法？和invoke的关系？	?	http://localhost:22222/?
serializeCheckStatus	检查当前在序列化白名单中的类列表	serializeCheckStatus	http://localhost:22222/serializeCheckStatus
serializeWarnedClasses	检查当前在序列化警告名单中的类列表	serializeWarnedClasses	http://localhost:22222/serializeWarnedClasses
setProfilerWarnPercent	控制序列化报警频率（仅限在警告名单中的类）	setProfilerWarnPercent 0.75	http://localhost:22222/setProfilerWarnPercent?k=0.75
shutdown	尝试关闭当前 Dubbo 应用（销毁所有资源，重启前无法恢复）	shutdown	http://localhost:22222/shutdown
startup	检查当前进程/服务是否已经正常启动，可配置为 kubernetes startup	startup	http://localhost:22222/startup
switchLogLevel	动态调整日志级别	switchLogLevel debug	http://localhost:22222/switchLogLevel?k=debug
switchLogger	切换日志logger组件。可用 logger 组件，可通过 loggerInfo 查看（切换前请务必确保应用已经加入相关组件依赖）	switchLogger log4j2	http://localhost:22222/switchLogger?k=log4j2
version	查看当前使用的 Dubbo 框架版本	version	http://localhost:22222/version

配置 MCP

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

MCP (Model Context Protocol) 网关配置

本文档解释了如何在您的网关中配置 MCP (Model Context Protocol) 过滤器，使您能够安全地将后端 HTTP API 暴露为可供 AI Agent 调用的"工具"。

简介

MCP (Model Context Protocol) 是一个智能桥梁，连接 AI Agent 与您现有的后端服务。它将一个简单、统一的协议动态转换为标准的 HTTP 请求，允许 Agent 与您的 API 进行交互，就好像它们是本地函数或工具一样。这种方法简化了 Agent 的开发，并为安全性、控制和可观察性提供了一个中心化的管理点。

设置 MCP 端点主要涉及两个过滤器：

dgp.filter.mcp.mcpserver: 核心的 MCP 服务器过滤器，用于定义服务器的身份并将后端 API 暴露为工具。
dgp.filter.http.auth.mcp: 一个可选但推荐使用的安全过滤器，它使用 OAuth 2.0 和基于 JWT 的授权来保护 MCP 端点。

MCP 服务器过滤器 (`dgp.filter.mcp.mcpserver`) 配置

此过滤器是 MCP 网关的核心。它负责定义哪些工具可用，以及它们如何映射到您的后端 HTTP 服务。

服务器信息 (`server_info`)

server_info 块提供了有关您的 MCP 服务器的元数据，这对于服务发现和诊断非常有用。

server_info:
 name: "MCP OAuth 示例服务器"
 version: "1.0.0"
 description: "一个用于工具演示的受 OAuth 保护的 MCP 服务器"
 instructions: "使用读/写令牌通过 MCP 与模拟服务器 API 进行交互"

name (string): MCP 服务器的显示名称。
version (string): 服务器的版本。
description (string): 服务器用途的简要描述。
instructions (string): 为客户端或开发者提供的关于如何与暴露的工具进行交互的说明。

工具配置 (`tools`)

tools 部分是一个数组，其中每个项目定义了 MCP 网关暴露的单个工具。每个工具对应一个特定的后端 HTTP API 端点。

配置上游 endpoint

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

LLM 网关 endpoint 配置

本文档解释了如何在您的网关路由配置中为大语言模型 (LLM) 配置上游 endpoint。

endpoint 结构

集群中的每个 endpoint 都由一个 id 定义，并且可以包含一个 llm_meta 块用于自定义行为。

clusters:
 - name: "my_llm_cluster"
 endpoints:
 - id: "provider-1-main"
 socket_address:
 domains:
 - api.deepseek.com
 llm_meta:
 # ... 其他特定于 LLM 的配置在此处 ...
 - id: "provider-2-fallback"
 socket_address:
 domains:
 - api.openai.com/v1
 llm_meta:
 # ... 其他特定于 LLM 的配置在此处 ...

`llm_meta` 配置字段

llm_meta 块包含所有与网关应如何处理此 LLM endpoint 相关的特定配置。

fallback

类型: boolean
描述: 决定如果在此endpoint上的所有重试尝试都失败后，网关是否应继续处理集群中的下一个 endpoint。
- true: 如果此endpoint失败，网关将尝试下一个可用的 endpoint。
- false: 如果此endpoint失败，则处理停止，并将最后一个错误返回给客户端。对于 fallback 链中的最后一个 endpoint ，此值应设置为 false。

api_key

配置设计

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

Dubbo 现在的设计是完全无侵入，也就是使用者只依赖于配置契约。经过多个版本的发展，为了满足各种需求场景，配置越来越多。为了保持兼容，配置只增不减，里面潜伏着各种风格，约定，规则。新版本也将配置做了一次调整，将想到的一些记在这，备忘。

配置分类

首先，配置的用途是有多种的，大致可以分为：

环境配置，比如：连接数，超时等配置。
描述配置，比如：服务接口描述，服务版本等。
扩展配置，比如：协议扩展，策略扩展等。

配置格式

通常环境配置，用 properties 配置会比较方便，因为都是一些离散的简单值，用 key-value 配置可以减少配置的学习成本。

而描述配置，通常信息比较多，甚至有层次关系，用 xml 配置会比较方便，因为树结构的配置表现力更强。如果非常复杂，也可以考虑自定义 DSL 做为配置。有时候这类配置也可以用 Annotation 代替，因为这些配置和业务逻辑相关，放在代码里也是合理的。

另外扩展配置，可能不尽相同。如果只是策略接口实现类替换，可以考虑 properties 等结构。如果有复杂的生命周期管理，可能需要 XML 等配置。有时候扩展会通过注册接口的方式提供。

配置加载

对于环境配置，在 java 世界里，比较常规的做法，是在 classpath 下约定一个以项目为名称的 properties 配置，比如：log4j.properties，velocity.properties等。产品在初始化时，自动从 classpath 下加载该配置。我们平台的很多项目也使用类似策略，如：dubbo.properties，comsat.xml 等。这样有它的优势，就是基于约定，简化了用户对配置加载过程的干预。但同样有它的缺点，当 classpath 存在同样的配置时，可能误加载，以及在 ClassLoader 隔离时，可能找不到配置，并且，当用户希望将配置放到统一的目录时，不太方便。

而对于描述配置，因为要参与业务逻辑，通常会嵌到应用的生命周期管理中。现在使用 spring 的项目越来越多，直接使用 spring 配置的比较普遍，而且 spring 允许自定义 schema，配置简化后很方便。当然，也有它的缺点，就是强依赖 spring，可以提编程接口做了配套方案。

在 Dubbo 既存在描述配置也有环境配置。一部分用 spring 的 schema 做配置加载，一部分从 classpath 扫描 properties 做配置加载。在新版本中做了一个优先级约定，统一以 spring 的 schema 驱动配置加载，dubbo.properties作为配置补充。

同时，在 Spring 的场景下，除了使用 schema 外，还支持完全以 application.properties 的方式配置：

配置中心参考手册

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

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

配置中心在 Dubbo 中承担3个职责：

外部化配置：启动配置的集中式存储（简单理解为 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 用作配置中心，但将只作服务治理用途。

外部化配置

请参考文档外部化配置

动态配置

[TODO 待完善]

服务治理

Zookeeper

默认节点结构：

namespace，用于不同配置的环境隔离。
config，Dubbo 约定的固定节点，不可更改，所有配置和服务治理规则都存储在此节点下。
dubbo，所有服务治理规则都是全局性的，dubbo 为默认节点
configurators/tag-router/condition-router/migration，不同的服务治理规则类型，node value 存储具体规则内容

Apollo

所有的服务治理规则都是全局性的，默认从公共命名空间 dubbo 读取和订阅：

不同的规则以不同的 key 后缀区分：

configurators，覆盖规则
tag-router，标签路由
condition-router，条件路由
migration，迁移规则

Nacos

所有的服务治理规则都是全局的，默认从 namespace: public 下进行读取，通过 dataId: interface name 以及 group: dubbo 去读取和订阅：

权限控制

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

特性说明

通过令牌验证在注册中心控制权限，以决定要不要下发令牌给消费者，可以防止消费者绕过注册中心访问提供者，另外通过注册中心可灵活改变授权方式，而不需修改或升级提供者。

使用场景

在一定程度上实现客户端和服务端的可信鉴权，避免任意客户端都可以访问，降低出现安全问题的风险。

使用方式

全局设置

开启令牌验证

<!--随机token令牌，使用UUID生成-->
<dubbo:provider token="true" />

或

<!--固定token令牌，相当于密码-->
<dubbo:provider token="123456" />

服务级别设置

<!--随机token令牌，使用UUID生成-->
<dubbo:service interface="com.foo.BarService" token="true" />

或

<!--固定token令牌，相当于密码-->
<dubbo:service interface="com.foo.BarService" token="123456" />

日志阅读介绍

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

Log

如何在Dubbogo-pixiu中阅读日志

DEBUG log

Dubbo request log

2020-11-17T11:31:05.716+0800 DEBUG dubbo/dubbo.go:150 [dubbo-go-pixiu] dubbo invoke, method:GetUserByName, types:[java.lang.String], reqData:[tiecheng]

Dubbo response log

2020-11-17T11:31:05.718+0800 DEBUG dubbo/dubbo.go:160 [dubbo-go-pixiu] dubbo client resp:map[age:88 iD:3213 name:tiecheng time:<nil>]

升级到triple协议

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

请注意

本文档内容并不是升级 Dubbo3 必须的，您完全可以只升级框架并继续使用 dubbo 通信协议。
如果您是 Dubbo 新用户，强烈建议直接使用 triple 协议即可。

本文档适合服务已经运行在 dubbo 协议之上的老用户，请先参考上一篇文档如何从 Dubbo2 升级到 Dubbo3 完成框架版本升级，然后遵循以下步骤以最小改动平滑迁移到 triple 协议。

以下是协议升级的架构图，展示了平滑升级过程中不同 Dubbo 应用的状态：

按先后顺序，升级基本步骤如下：

Provider 提供者侧配置单端口双协议（dubbo、triple）发布
Provider 提供者侧配置首选协议为 triple（此时，提供者注册的URL地址为 dubbo://host:port/DemoService?preferred-protocol=tri）
Consumer 消费者升级，根据情况不同有以下两种方式：
- 升级消费者到 3.3 版本，消费者会根据 preferred-protocol=tri 优先调用 triple 协议
- 无法升级到 3.3 版本的消费者应用，可以配置 @DubboReference(protocol="tri") 调用 triple 协议
推动所有应用升级到最新 Dubbo3 版本，最终所有流量都是 triple 协议

请注意

请注意，以上提到的单端口多协议、识别 preferred-protocol 首选协议等功能，需要 Dubbo 3.3.0+ 版本！

步骤一：提供者双协议发布

假设我们有以下应用配置，即在 20880 端口发布 dubbo 协议：

dubbo:
 protocol:
 name: dubbo
 port: 20880

我们需要增加两个配置项，如下所示：

示例提供者安装

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

安装：

git clone https://github.com/apache/dubbo.git
cd dubbo/dubbo-demo/dubbo-demo-xml
运行 dubbo-demo-xml-provider中的org.apache.dubbo.demo.provider.Application
如果使用Intellij Idea 请加上-Djava.net.preferIPv4Stack=true

配置：

resources/spring/dubbo-provider.xml
修改其中的dubbo:registry，替换成真实的注册中心地址，推荐使用zookeeper，如：
<dubbo:registry address="zookeeper://127.0.0.1:2181"/>

属性配置

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 作为默认属性。

Admin 服务查询

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

Admin 支持可视化的展示 Dubbo 微服务集群的状态，方便用户从全局掌握集群的应用、服务和实例分布，Admin 还可以通过查询的方式了解某一个服务更详细的信息：

首页集群大盘，展示集群应用、服务、示例的总体分布，集群总体流量情况等
支持根据应用名、服务名(可包含版本&分组)、实例 IP 查询详细信息
支持服务名/应用名的自动补全
支持查看单条服务实例的详情

首页大盘

根据 Dubbo 服务名查询

精确输入接口名:版本 查询服务

通过 * 通配符模糊查询服务

根据应用名查询

输入应用名查询某应用关联的所有服务（包含提供和消费的服务）

根据实例 IP 名查询

输入实例 IP 查询某实例关联的所有服务（包含提供和消费的服务）

支持基于端口过滤服务

查看服务实例详情

在服务列表点击 详情 查看服务详细情况

消费端线程模型，提供者端线程模型

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

消费端线程模型

对 2.7.5 版本之前的 Dubbo 应用，尤其是一些消费端应用，当面临需要消费大量服务且并发数比较大的大流量场景时（典型如网关类场景），经常会出现消费端线程数分配过多的问题，具体问题讨论可参见 Need a limited Threadpool in consumer side #2013

改进后的消费端线程池模型，通过复用业务端被阻塞的线程，很好的解决了这个问题。

老的线程池模型

我们重点关注 Consumer 部分：

业务线程发出请求，拿到一个 Future 实例。
业务线程紧接着调用 future.get 阻塞等待业务结果返回。
当业务数据返回后，交由独立的 Consumer 端线程池进行反序列化等处理，并调用 future.set 将反序列化后的业务结果置回。
业务线程拿到结果直接返回

当前线程池模型

业务线程发出请求，拿到一个 Future 实例。
在调用 future.get() 之前，先调用 ThreadlessExecutor.wait()，wait 会使业务线程在一个阻塞队列上等待，直到队列中被加入元素。
当业务数据返回后，生成一个 Runnable Task 并放入 ThreadlessExecutor 队列
业务线程将 Task 取出并在本线程中执行：反序列化业务数据并 set 到 Future。
业务线程拿到结果直接返回

这样，相比于老的线程池模型，由业务线程自己负责监测并解析返回结果，免去了额外的消费端线程池开销。

提供端线程模型

Dubbo协议的和Triple协议目前的线程模型还并没有对齐，下面分开介绍Triple协议和Dubbo协议的线程模型。

Dubbo协议

介绍Dubbo协议的Provider端线程模型之前，先介绍Dubbo对channel上的操作抽象成了五种行为：

建立连接：connected，主要是的职责是在channel记录read、write的次数，以及处理建立连接后的回调逻辑，比如dubbo支持在断开后自定义回调的hook（onconnect），即在该操作中执行。
断开连接：disconnected，主要是的职责是在channel移除read、write的时间，以及处理断开连接后的回调逻辑，比如dubbo支持在断开后自定义回调的hook（ondisconnect），即在该操作中执行。
发送消息：sent，包括发送请求和发送响应。记录write的时间。
接收消息：received，包括接收请求和接收响应。记录read的时间。
异常捕获：caught，用于处理在channel上发生的各类异常。

Dubbo框架的线程模型与以上这五种行为息息相关，Dubbo协议Provider线程模型可以分为五类，也就是AllDispatcher、DirectDispatcher、MessageOnlyDispatcher、ExecutionDispatcher、ConnectionOrderedDispatcher。

配置方式

线程模型	配置值
All Dispatcher	all
Direct Dispatcher	direct
Execution Dispatcher	execution
Message Only Dispatcher	message
Connection Ordered Dispatcher	connection

拿 application.yaml 的配置方式举例：在protocol下配置dispatcher: all，即可把dubbo协议的线程模型调整为All Dispatcher

消费者配置

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

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

基础配置

消费者配置项需要添加到 sys.config 文件 dubboerl 应用配置项里。

{dubboerl,[
	%% other config ...
	{consumer,[
		{<<"interface fullname">>,[Option]},
		%% eg:
		{<<"org.apache.dubbo.erlang.sample.service.facade.UserOperator">>,[]},
	]}
]}

Option 配置项待添加中。

消费者配置

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

基础配置

消费者配置项需要添加到 sys.config 文件 dubboerl 应用配置项里。

{dubboerl,[
	%% other config ...
	{consumer,[
		{<<"interface fullname">>,[Option]},
		%% eg:
		{<<"org.apache.dubbo.erlang.sample.service.facade.UserOperator">>,[]},
	]}
]}

Option 配置项待添加中。

消费者配置

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

基础配置

消费者配置项需要添加到 sys.config 文件 dubboerl 应用配置项里。

{dubboerl,[
	%% other config ...
	{consumer,[
		{<<"interface fullname">>,[Option]},
		%% eg:
		{<<"org.apache.dubbo.erlang.sample.service.facade.UserOperator">>,[]},
	]}
]}

Option 配置项待添加中。

RPC 通信协议

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

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

Dubbo3 提供了 Triple(Dubbo3)、Dubbo2 协议，这是 Dubbo 框架的原生协议。除此之外，Dubbo3 也对众多第三方协议进行了集成，并将它们纳入 Dubbo 的编程与服务治理体系，包括 gRPC、Thrift、JsonRPC、Hessian2、REST 等。以下重点介绍 Triple 与 Dubbo2 协议。

Triple 协议

Triple 协议是 Dubbo3 推出的主力协议。Triple 意为第三代，通过 Dubbo1.0/ Dubbo2.0 两代协议的演进，以及云原生带来的技术标准化浪潮，Dubbo3 新协议 Triple 应运而生。

RPC 协议的选择

协议是 RPC 的核心，它规范了数据在网络中的传输内容和格式。除必须的请求、响应数据外，通常还会包含额外控制数据，如单次请求的序列化方式、超时时间、压缩方式和鉴权信息等。

协议的内容包含三部分

数据交换格式：定义 RPC 的请求和响应对象在网络传输中的字节流内容，也叫作序列化方式
协议结构：定义包含字段列表和各字段语义以及不同字段的排列方式
协议通过定义规则、格式和语义来约定数据如何在网络间传输。一次成功的 RPC 需要通信的两端都能够按照协议约定进行网络字节流的读写和对象转换。如果两端对使用的协议不能达成一致，就会出现鸡同鸭讲，无法满足远程通信的需求。

RPC 协议的设计需要考虑以下内容：

通用性：统一的二进制格式，跨语言、跨平台、多传输层协议支持
扩展性：协议增加字段、升级、支持用户扩展和附加业务元数据
性能：As fast as it can be
穿透性：能够被各种终端设备识别和转发：网关、代理服务器等通用性和高性能通常无法同时达到，需要协议设计者进行一定的取舍。

HTTP/1.1

比于直接构建于 TCP 传输层的私有 RPC 协议，构建于 HTTP 之上的远程调用解决方案会有更好的通用性，如WebServices 或 REST 架构，使用 HTTP + JSON 可以说是一个事实标准的解决方案。

协议识别

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

可以按照下文步骤，将 Dubbo 服务轻松部署到 Kubernetes 集群，此查看文章用到的完整代码示例地址

1 总体目标

部署 Dubbo 应用到 Kubernetes
基于 Kubernetes 内置 Service 实现服务发现
将 Dubbo 应用对接到 Kubernetes 生命周期

2 基本流程

创建一个 Dubbo 应用( dubbo-samples-kubernetes )
构建容器镜像并推送到镜像仓库（ dubbo-demo 示例例镜像）
分别部署 Dubbo Provider 与 Dubbo Consumer 到 Kubernetes
验证服务发现与调用正常

3 详细步骤

3.1 环境要求

请确保本地安装如下环境，以提供容器运行时、Kubernetes集群及访问工具

通过以下命令启动本地 Kubernetes 集群

minikube start

通过 kubectl 检查集群正常运行，且 kubectl 绑定到默认本地集群

kubectl cluster-info

3.2 前置条件

由于示例 Dubbo 项目均部署在 Pod 中且与 API-SERVER 有交互，因此有相应的权限要求，我们这里创建独立 ServiceAccount 并绑定必须的 Roles，后面所有的 Dubbo Kubernetes 资源都将使用这里新建的 ServiceAccount。

What's New in Dubbo3

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

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

全新服务发现模型

相比于 2.x 版本中的基于接口粒度的服务发现机制，3.x 引入了全新的基于应用粒度的服务发现机制，新模型带来两方面的巨大优势：

进一步提升了 Dubbo3 在大规模集群实践中的性能与稳定性。新模型可大幅提高系统资源利用率，降低 Dubbo 地址的单机内存消耗（50%），降低注册中心集群的存储与推送压力（90%）， Dubbo 可支持集群规模步入百万实例层次。
打通与其他异构微服务体系的地址互发现障碍。新模型使得 Dubbo3 能实现与异构微服务体系如Spring Cloud、Kubernetes Service、gRPC 等，在地址发现层面的互通，为连通 Dubbo 与其他微服务体系提供可行方案。

在 Dubbo3 前期版本将会同时提供对两套地址发现模型的支持，以最大程度保证业务升级的兼容性。

下一代 RPC 通信协议

定义了全新的 RPC 通信协议 – Triple，一句话概括 Triple：它是基于 HTTP/2 上构建的 RPC 协议，完全兼容 gRPC，并在此基础上扩展出了更丰富的语义。使用 Triple 协议，用户将获得以下能力

更容易到适配网关、Mesh架构，Triple 协议让 Dubbo 更方便的与各种网关、Sidecar 组件配合工作。
多语言友好，推荐配合 Protobuf 使用 Triple 协议，使用 IDL 定义服务，使用 Protobuf 编码业务数据。
流式通信支持。Triple 协议支持 Request Stream、Response Stream、Bi-direction Stream

云原生

Dubbo3 构建的业务应用可直接部署在 VM、Container、Kubernetes 等平台，Dubbo3 很好的解决了 Dubbo 服务与调度平台之间的生命周期对齐，Dubbo 服务发现地址与容器平台绑定的问题。

新贡献者向导

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

这篇向导旨在给正在准备向 Dubbo 提交贡献的新手提供指导。

邮件列表描述

邮件列表是 Dubbo 官方推荐的讨论方式，所有与 Dubbo 相关的内容都可以在这里讨论，请点击 Issue 了解更多关于邮件列表订阅的内容

如需订阅如下邮件列表，请参考邮件列表订阅向导

dev@dubbo.apache.org：开发邮件列表，您在使用或者开发 Dubbo 的过程中遇到的任何问题，都可以在这里进行提问。
commits@dubbo.apache.org：所有的提交内容都会推送到这个邮件列表，如果您对 Dubbo 的进展感兴趣，可以订阅这个邮件列表。
issues@dubbo.apache.org：所有的 JIRA Issues 和修改信息都会推送到这个邮件列表。Dubbo 社区已经决定使用 GitHub Issues 代替 JIRA Issues，因此大部分 Issues 将由 GitHub Issues 进行跟踪。JIRA Issues 用于跟踪 ASF 相关问题。

报告问题

非安全问题直接在 GitHub Issue 中提出，另请参考 Issue Template 。
安全问题请参考 “反馈漏洞” 。

贡献代码流程

此贡献流程适用于所有的 Apache Dubbo 社区内容，包括但不限于 dubbo（主干仓库）、dubbo-admin、dubbo-website。

以下以贡献 dubbo （主干仓库）为例，详细说明贡献流程。

1. Fork apache/dubbo 项目到您的 GitHub 帐号下

2. 克隆您 Fork 的 Dubbo 代码仓库到您本地

git clone ${your fork dubbo repo address，for example：https://github.com/${your github id}/dubbo.git}
cd dubbo

3. 添加 apache/dubbo 仓库为 upstream 仓库

git remote add upstream https://github.com/apache/dubbo.git

git remote -v

 origin ${your fork dubbo repo address} (fetch)
 origin ${your fork dubbo repo address} (push)
 upstream https://github.com/apache/dubbo.git (fetch)
 upstream https://github.com/apache/dubbo.git (push)

git fetch origin
git fetch upstream

4. 我们的工作以 Issue 为驱动，认领个 Issue，或者创建一个 Issue 并描述清楚要做什么。

新人推荐标记为： good first issue 的 Issue

应用级地址发现迁移指南

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

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

总体上来说，在地址注册与发现环节，3.x 是完全兼容 2.x 版本的，这意味着，用户可以选择将集群内任意数量的应用或机器升级到 3.x，同时在这个过程中保持与 2.x 版本的互操作性。

1 快速升级步骤

简单的修改 pom.xml 到最新版本就可以完成升级，如果要迁移到应用级地址，只需要调整开关控制 3.x 版本的默认行为。

升级 Provider 应用到最新 3.x 版本依赖，配置双注册开关dubbo.application.register-mode=all（建议通过全局配置中心设置，默认已自动开启），完成应用发布。
升级 Consumer 应用到最新 3.x 版本依赖，配置双订阅开关dubbo.application.service-discovery.migration=APPLICATION_FIRST（建议通过全局配置中心设置，默认已自动开启），完成应用发布。
在确认 Provider 的上有 Consumer 全部完成应用级地址迁移后，Provider 切到应用级地址单注册。完成升级

以下是关于迁移流程的详细描述。

2 Provider 端升级过程详解

在不改变任何 Dubbo 配置的情况下，可以将一个应用或实例升级到 3.x 版本，升级后的 Dubbo 实例会默保保证与 2.x 版本的兼容性，即会正常注册 2.x 格式的地址到注册中心，因此升级后的实例仍会对整个集群仍保持可见状态。

同时新的地址发现模型（注册应用级别的地址）也将会自动注册。

通过 -D 参数，可以指定 provider 启动时的注册行为

-Ddubbo.application.register-mode=all
# 可选值 interface、instance、all，默认是 all，即接口级地址、应用级地址都注册

另外，可以在配置中心修改全局默认行为，来控制所有 3.x 实例注册行为。其中，全局性开关的优先级低于 -D 参数。

为了保证平滑迁移，即升级到 3.x 的实例能同时被 2.x 与 3.x 的消费者实例发现，3.x 实例需要开启双注册；当所有上游的消费端都迁移到 3.x 的地址模型后，提供端就可以切换到 instance 模式（只注册应用级地址）。对于如何升级消费端到 3.x 请参见下一小节。

与 gRPC、Spring Cloud、Istio 的关系

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

很多开发者经常会问到 Apache Dubbo 与 Spring Cloud、gRPC 以及一些 Service Mesh 项目如 Istio 的关系，要解释清楚它们的关系并不困难，你只需要跟随这篇文章和 Dubbo 文档做一些更深入的了解，但总的来说，它们之间有些能力是重合的，但在一些场景你可以把它们放在一起使用。

虽然这是一篇 Dubbo 维护者写的文档，我们仍会尽力将 Dubbo 与其他组件之间的联系与差异客观、透明的展现出来，但考虑到每个人对不同产品的熟悉程度不一，这里的个别表述可能并不完全准确，希望能给开发者带来帮助。

Dubbo 与 Spring Cloud

从上图我们可以看出，Dubbo 和 Spring Cloud 有很多相似之处，它们都在整个架构图的相同位置并提供一些相似的功能。

Dubbo 和 Spring Cloud 都侧重在对分布式系统中常见问题模式的抽象（如服务发现、负载均衡、动态配置等），同时对每一个问题都提供了配套组件实现，形成了一套微服务整体解决方案，让使用 Dubbo 及 Spring Cloud 的用户在开发微服务应用时可以专注在业务逻辑开发上。
Dubbo 和 Spring Cloud 都完全兼容 Spring 体系的应用开发模式，Dubbo 对 Spring 应用开发框架、Spring Boot 微服务框架都做了很好的适配，由于 Spring Cloud 出自 Spring 体系，在这一点上自然更不必多说。

虽然两者有很多相似之处，但由于它们在诞生背景与架构设计上的巨大差异，两者在性能、适用的微服务集群规模、生产稳定性保障、服务治理等方面都有很大差异。

Spring Cloud 的优势在于：

同样都支持 Spring 开发体系的情况下，Spring Cloud 得到更多的原生支持
对一些常用的微服务模式做了抽象如服务发现、动态配置、异步消息等，同时包括一些批处理任务、定时任务、持久化数据访问等领域也有涉猎。
基于 HTTP 的通信模式，加上相对比较完善的入门文档和演示 demo 和 starters，让开发者在第一感觉上更易于上手

Spring Cloud 的问题有：

注册中心、配置中心和元数据中心

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

三中心逻辑架构

本节侧重描述传统模式下的 Dubbo 部署架构，在云原生背景下的部署架构会有些变化，主要体现在基础设施（Kubernetes、Service Mesh等）会承担更多的职责，中心化组件如注册中心、元数据中心、配置中心等的职责被集成、运维变得更加简单，但通过强调这些中心化的组件能让我们更容易理解 Dubbo 的工作原理。

作为一个微服务框架，Dubbo sdk 跟随着微服务组件被部署在分布式集群各个位置，为了在分布式环境下实现各个微服务组件间的协作， Dubbo 定义了一些中心化组件，这包括：

注册中心。协调 Consumer 与 Provider 之间的地址注册与发现
配置中心。
- 存储 Dubbo 启动阶段的全局配置，保证配置的跨环境共享与全局一致性
- 负责服务治理规则（路由规则、动态配置等）的存储与推送。
元数据中心。
- 接收 Provider 上报的服务接口元数据，为 Admin 等控制台提供运维能力（如服务测试、接口文档等）
- 作为服务发现机制的补充，提供额外的接口/方法级别配置信息的同步能力，相当于注册中心的额外扩展

上图完整的描述了 Dubbo 微服务组件与各个中心的交互过程。

以上三个中心并不是运行 Dubbo 的必要条件，用户完全可以根据自身业务情况决定只启用其中一个或多个，以达到简化部署的目的。通常情况下，所有用户都会以独立的注册中心以开始 Dubbo 服务开发，而配置中心、元数据中心则会在微服务演进的过程中逐步的按需被引入进来。

注册中心

注册中心扮演着非常重要的角色，它承载着服务注册和服务发现的职责。目前Dubbo支持以下两种粒度的服务发现和服务注册，分别是接口级别和应用级别，注册中心可以按需进行部署：

在传统的Dubbo SDK使用姿势中，如果仅仅提供直连模式的RPC服务，不需要部署注册中心。
无论是接口级别还是应用级别，如果需要Dubbo SDK自身来做服务注册和服务发现，则可以选择部署注册中心，在Dubbo中集成对应的注册中心。
在Dubbo + Mesh 的场景下，随着 Dubbo 服务注册能力的弱化，Dubbo内的注册中心也不再是必选项，其职责开始被控制面取代，如果采用了Dubbo + Mesh的部署方式，无论是ThinSDK的mesh方式还是Proxyless的mesh方式，都不再需要独立部署注册中心。

而注册中心并不依赖于配置中心和元数据中心，如下图所示：

该图中没有部署配置中心和元数据中心，在Dubbo中会默认将注册中心的实例同时作为配置中心和元数据中心，这是Dubbo的默认行为，如果确实不需要配置中心或者元数据中心的能力，可在配置中关闭，在注册中心的配置中有两个配置分别为use-as-config-center和use-as-metadata-center，将配置置为false即可。

元数据中心

元数据中心在2.7.x版本开始支持，随着应用级别的服务注册和服务发现在Dubbo中落地，元数据中心也变的越来越重要。在以下几种情况下会需要部署元数据中心：

对于一个原先采用老版本Dubbo搭建的应用服务，在迁移到Dubbo 3时，Dubbo 3 会需要一个元数据中心来维护RPC服务与应用的映射关系（即接口与应用的映射关系），因为如果采用了应用级别的服务发现和服务注册，在注册中心中将采用“应用 —— 实例列表”结构的数据组织形式，不再是以往的“接口 —— 实例列表”结构的数据组织形式，而以往用接口级别的服务注册和服务发现的应用服务在迁移到应用级别时，得不到接口与应用之间的对应关系，从而无法从注册中心得到实例列表信息，所以Dubbo为了兼容这种场景，在Provider端启动时，会往元数据中心存储接口与应用的映射关系。
为了让注册中心更加聚焦于地址的发现和推送能力，减轻注册中心的负担，元数据中心承载了所有的服务元数据、大量接口/方法级别配置信息等，无论是接口粒度还是应用粒度的服务发现和注册，元数据中心都起到了重要的作用。

如果有以上两种需求，都可以选择部署元数据中心，并通过Dubbo的配置来集成该元数据中心。

元数据中心并不依赖于注册中心和配置中心，用户可以自由选择是否集成和部署元数据中心，如下图所示：

注册服务到网关

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

LLM 服务发现与注册

本文档旨在指导 LLM 服务提供商如何通过 Nacos 注册中心，将其服务实例动态地注册到 LLM 网关。通过遵循这些准则，网关将能够自动发现您的服务，并根据您提供的元数据（metadata）应用相应的路由、重试和 fallback 策略。

注册机制概述

服务发现的核心机制是：您的 LLM 服务作为一个Nacos 实例进行注册，并在注册时提供一组特定的元数据。LLM 网关会监听 Nacos 中的服务变更，读取这些元数据，并将其动态地转换为一个功能齐全的网关 endpoint 配置。

一个基本的 Nacos 注册请求包含以下关键信息：

ServiceName: 您的服务集合的名称 (例如, deepseek-service)。
Ip & Port: 您的服务实例监听流量的网络地址。
Metadata: 一个键值对集合，这是配置所有网关行为的关键。

`metadata` 配置字段

所有网关的特定配置都通过 Nacos 实例的 metadata 字段进行传递。以下是所有支持的 metadata 键及其说明。

cluster

类型: string
必需: 是
描述: 定义此 endpoint 应归属到网关中的哪个集群 (cluster)。网关会根据此值将具有相同 cluster 名称的服务实例聚合在一起。
示例: "deepseek_cluster"

id

类型: string
必需: 是
描述: endpoint 的唯一标识符。它在所属的 cluster 内必须是唯一的。
示例: "deepseek-primary-instance-1"

ip

自定义序列化

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

在此查看完整示例。

Python 是一种动态语言，其灵活性使得在其他语言中设计通用的序列化层具有挑战性。因此，我们移除了框架级别的序列化层，而是提供接口，允许用户根据需求自行实现（因为用户更了解他们要传输的数据格式）。

序列化通常分为两个部分：序列化和反序列化。我们为这些函数定义了类型，自定义的序列化/反序列化函数必须遵循这些 “格式”。

对于序列化函数，我们规定：

# A function that takes any number of arguments and returns data of type bytes
SerializingFunction = Callable[..., bytes]

对于反序列化函数，我们规定：

# A function that takes an argument of type bytes and returns data of any type
DeserializingFunction = Callable[[bytes], Any]

下面，我将演示如何使用 protobuf 和 json 进行序列化。

protobuf

有关定义和编译 protobuf 文件的详细说明，请参阅 protobuf tutorial。

在Client的unary、client_stream、server_stream 和 bi_stream 方法中通过设置request_serializer 和 response_deserializer 设置对应的序列化和反序列化函数。

class GreeterServiceStub:
 def __init__(self, client: dubbo.Client):
 self.unary = client.unary(
 method_name="sayHello",
 request_serializer=greeter_pb2.GreeterRequest.SerializeToString,
 response_deserializer=greeter_pb2.GreeterReply.FromString,
 )

 def say_hello(self, request):
 return self.unary(request)

if __name__ == "__main__":
 reference_config = ReferenceConfig.from_url(
 "tri://127.0.0.1:50051/org.apache.dubbo.samples.data.Greeter"
 )
 dubbo_client = dubbo.Client(reference_config)

 stub = GreeterServiceStub(dubbo_client)
 result = stub.say_hello(greeter_pb2.GreeterRequest(name="Dubbo-python"))
 print(f"Received reply: {result.message}")

同理在Server中设置对应的序列化和反序列化函数。

自动加载环境变量

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 Admin 控制面总体架构设计

Tue, 28 Feb 2023 00:00:00 +0000

1 Dubbo 整体架构

架构上分为：服务治理抽象控制面 和 Dubbo 数据面 。

服务治理控制面。控制面包含注册中心、流量管控策略、Admin 控制台、Istio、OpenSergo 等组件。
Dubbo 数据面。数据面代表集群部署的所有 Dubbo 进程，进程之间通过 RPC 协议实现数据交换，并与控制面进行治理策略交互。

**进一步解释：**https://cn.dubbo.apache.org/zh-cn/overview/what/overview/

Dubbo Admin 的整体定位与解释

Dubbo Admin 是对微服务治理体系的统一定义与抽象，通过自定义核心组件与一系列配套工具，为不同部署架构和基础设施环境下部署的微服务集群带来统一的开发与运维差异。

2 面向用户的开发步骤

第一步：安装 Dubbo Stack/Admin

核心思路是，屏蔽架构差异，通过统一入口将治理组件的安装和配置纳入成为 Dubbo 体系中的前置步骤

dubboctl install dubbo-stack

安装请参见: Dubbo Admin 安装指南

第二步：服务框架开发

3 控制面方案

3.1 确定 Dubbo 微服务治理体系的核心能力

服务发现
配置管理
流量治理规则
安全基础设施
可视化控制台

3.2 统一服务治理层接入方式

**对于任何微服务部署模式，Dubbo 数据面统一面向 ****dubbo://hopst:ip**抽象服务治理控制面编程。

具体工作流程：

数据面通过配置先与 admin 组件进行交互，admin 返回当前部署架构下的实际注册中心、配置中心等组件地址，如图中的 nacos://host:port。
数据面组件接收到新的组件地址后，直接与 Nacos 建立通信，此后依赖 Nacos 完成服务发现等功能。

3.3 在不同场景下如何兑现这些核心能力？

场景一：传统微服务体系 (VM & Kubernetes)

控制面治理体系一键安装 (Admin & Nacos)
传统 Nacos 服务发现与治理模式
控制面可按需拉起更多的的组件，如 prometheus 等

饿了么全站成功升级 Dubbo3

Sun, 15 Jan 2023 00:00:00 +0000

升级目标

这里是饿了么的的基本部署架构图。

在升级之前，饿了么的微服务框架采用的是 HSF2，跨单元的 RPC 调用是通过 proxy 中转代理，在这个过程中 proxy 所承载的机器数和流量迅速增长，比较突出的一点是 proxy 在订阅所有的地址数据后资源消耗和稳定性都收到严峻挑战。

通过全站升级 Dubbo3，业务线期望达到两个目标：

将地址模型切换到应用级服务发现大幅减轻中心化节点和消费端节点的资源消耗压力。
以应用级服务发现架构下的全局共享注册中心取代 proxy 模式，实现跨单元节点通信直连。

升级过程

不论是针对 Dubbo2 还是 HSF2，我们都做了全面的 API 兼容，因此 Dubbo3 基本可以做到零改造升级，并且每个应用都是独立透明升级，不需要关心它的上下游应用的升级状态，因为 Dubbo3 升级之后不论是从地址发现模型还是协议的默认行为都保持与 2.0 版本兼容，用户可以在任意时间点对任意应用按需切换 Dubbo3 行为。如右图所示，我们模拟展示了饿了么集群 Dubbo3 升级过程的一个中间状态，其中灰色标记的是老版本 HSF2 应用，橙色和绿色标记的是已经升级 Dubbo3 的应用，橙色部分的应用及其调用链路代表不但已经升级到 Dubbo3，同时也完成了 Dubbo3 行为的切换，在这里是指已经切换到了应用级地址模型。这里的升级过程主要为了说明 Dubbo3 框架升级的兼容性和独立性。

接下来，我们详细分析一下橙色部分节点往 Dubbo3 应用级发现迁移的具体过程。

首先看 Provider 侧，服务提供者在升级 Dubbo3 后会默认保持双注册行为，即同时注册接口级地址和应用级地址到注册中心，一方面保持兼容，另一方面为未来消费端迁移做好准备。双注册的开关可通过 -Ddubbo.application.register-mode=al/interface/interface控制，我们推荐保持双注册的默认行为以减少后续迁移成本。

大家可能担心双注册给注册中心带来的存储压力，实际上在应用级服务发现模型下这并不是一个问题，因为大家如果回想前面我们对应用级服务发现工作原理的分析，注册地址已经被大幅精简，根据我们实际推算，每多注册一条应用级服务发现 URL 地址，只会增加 0.1% ～ 1% 的额外开销。

与提供端类似，要实现平滑迁移消费端也要经历双订阅的过程，流程上就不再赘述。消费端的双订阅行为也可通过规则或开关进行动态调整，控制消费端的消费的某个服务、应用迁移到应用级地址模型；除此之外，Dubbo3 还内置了自动决策机制，在发现应用级地址可用的情况下即会自动完成切换，并且这个行为是默认的。

以下是消费端双订阅时的选址流程：

升级效果

0-3 - 无法访问缓存路径

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

其它模块复用了 Common 层的基于文件的缓存机制（目前是元数据模块），而 Common 层的文件缓存机制无法访问它指定的目录。

2022-08-29 00:35:00,189 ERROR [org.apache.dubbo.common.cache.FileCacheStoreFactory:?] - [DUBBO] Cache store path can't be created: , dubbo version: , current host: 10.0.1.1, error code: 0-3. This may be caused by inaccessible of cache path, go to https://dubbo.apache.org/faq/0/3 to find instructions. 
java.nio.file.FileAlreadyExistsException: [Path]
	at java.base/sun.nio.fs.WindowsException.translateToIOException(WindowsException.java:87)
	at java.base/sun.nio.fs.WindowsException.rethrowAsIOException(WindowsException.java:103)
	at java.base/sun.nio.fs.WindowsException.rethrowAsIOException(WindowsException.java:108)
	at java.base/sun.nio.fs.WindowsFileSystemProvider.createDirectory(WindowsFileSystemProvider.java:521)
	at java.base/java.nio.file.Files.createDirectory(Files.java:700)
	at java.base/java.nio.file.Files.createAndCheckIsDirectory(Files.java:807)
	at java.base/java.nio.file.Files.createDirectories(Files.java:753)
	at org.apache.dubbo.common.cache.FileCacheStoreFactory.getInstance(FileCacheStoreFactory.java:90)
	...

可能的原因

多个 Dubbo 进程（或其他 Java 进程）使用了同一个缓存文件。
由于缓存文件所在目录的文件系统权限问题，导致读写失败。

排查和解决步骤

根据下面显示的实际异常找到访问不了的目录，确定下它的文件访问权限。
确定下是否有别的 Dubbo 实例正在访问这个路径。
尝试配置 Java System Property（用 -D 配置的 Java 系统属性） dubbo.meta.cache.filePath 和 dubbo.mapping.cache.filePath，将它指定成一个当前用户能够完全控制的目录下。

1-3 - URL 销毁失败

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

可能的原因

当FrameworkExecutorRepository被销毁以后，调用CacheableFailbackRegistry.evictURLCache会导致销毁失败，产生错误码。

排查和解决步骤

另请参阅配置项参考手册

2-3 - 路由关闭失败

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

可能的原因

用户自定义路由未按规范编写。

排查和解决步骤

参照社区SPI扩展使用手册，检查用户自定义路由《SPI 扩展使用手册》。

3-3 - 通过Javassist生成字节码失败

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

可能的原因

该错误码的意义已经调整。对于 Dubbo 3.1.4、3.2.0-beta.3 及其之前的版本的该错误码的出错，请参考错误码 3-8。

排查和解决步骤

（该错误码目前空缺）

3.1 升级至 3.2

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

对于绝大多数的用户，升级到 Dubbo 3.2.0 是完全平滑的，仅需要修改依赖包版本即可。

<dependency>
 <groupId>org.apache.dubbo</groupId>
 <artifactId>dubbo</artifactId>
 <version>3.2.0</version>
</dependency>

或者

<dependency>
 <groupId>org.apache.dubbo</groupId>
 <artifactId>dubbo-spring-boot-starter</artifactId>
 <version>3.2.0</version>
</dependency>

兼容性 CheckList

1. 序列化检查模式（重要！！！）

在 Dubbo 3.2.0 版本中，Dubbo 将默认开启序列化白名单的强校验，以提升 Dubbo 的安全性，避免远程命令执行的问题。对于一些使用了泛型等可能存在扫描不全或者是服务规模较大的用户，我们建议您添加 -Ddubbo.application.serialize-check-status=WARN 配置。观察一段时间后（通过日志、QoS 命令），如果没有触发安全告警，则可以配置强校验模式。

关于自定义白名单的配置，可以参考官网的文档 / SDK 手册 / Java SDK / 高级特性和用法 / 提升安全性 / 类检查机制一文进行配置。

Q1：为什么要开启序列化白名单的强校验？

由于 Java 本身机制的问题，Dubbo 支持的非 IDL 序列化天然允许访问任意类，这将可能导致远程命令执行（RCE）风险。

Q2：升级到 3.2 的最佳实践是什么？

我们建议所有用户在升级 Dubbo 3.2.0 版本前添加 -Ddubbo.application.serialize-check-status=WARN 配置以保证最佳的兼容性。否则可能导致线上数据异常的情况！

2. 默认序列化切换

Dubbo 3.2.0 版本开始默认序列化方式从 hessian2 切换为 fastjson2，对于升级到 3.2.0 的应用，Dubbo 会自动尝试采用 fastjson2 进行序列化。

4-3 - 接口引用调用失败

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

可能的原因

根据指定的协议参数，未找到暴露的服务接口或方法。

排查和解决步骤

可根据接口 URL 及方法名称，确认服务端是否存在。

5-3 - 销毁方法调用时发生意外错误

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

可能的原因

自定义销毁方法，业务处理上存在异常。

排查和解决步骤

检查自定义销毁方法，业务处理逻辑是否存在运行时异常。

6-3 - 网络连接关闭失败

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

可能的原因

非优雅关闭服务，此时服务端可能在对外输出流未完成。

排查和解决步骤

一般为提示类警告信息，不影响后续的程序执行。

7-3 - 设置超时时间的警告百分比值

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

可能的原因

QOS 设置超时时间的警告百分比值, 默认为0.75。修改后，控制台会打印此消息。

排查和解决步骤

请参考 QOS 操作手册性能采样命令。

81-3 - 通过url无法下载文件

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

可能的原因

url 映射文件不存在。
url 无法连接。

排查和解决步骤

检查 url 映射文件是否存在。
通过浏览器或其他工具，能否正常访问。

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(); // 注意：此代理对象内部封装了所有通讯细节，对象较重，请缓存复用

特殊场景

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

Dubbo协议

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

Dubbo 缺省协议采用单一长连接和 NIO 异步通讯，适合于小数据量大并发的服务调用，以及服务消费者机器数远大于服务提供者机器数的情况。dubbo RPC是dubbo体系中最核心的一种高性能、高吞吐量的远程调用方式，我喜欢称之为多路复用的TCP长连接调用。

主要用于两个dubbo系统之间作远程调用，特别适合高并发、小数据的互联网场景。反之，Dubbo 缺省协议不适合传送大数据量的服务，比如传文件，传视频等，除非请求量很低。

长连接：避免了每次调用新建TCP连接，提高了调用的响应速度。
多路复用：单个TCP连接可交替传输多个请求和响应的消息，降低了连接的等待闲置时间，从而减少了同样并发数下的网络连接数，提高了系统吞吐量。

Transporter: mina, netty, grizzy
Serialization: dubbo, hessian2, java, json
Dispatcher: all, direct, message, execution, connection
ThreadPool: fixed, cached

缺省协议，使用基于 netty 3.2.5.Final 和 hessian2 3.2.1-fixed-2(Alibaba embed version) 的 tbremoting 交互。

连接个数：单连接
连接方式：长连接
传输协议：TCP
传输方式：NIO 异步传输
序列化：Hessian 二进制序列化
适用范围：传入传出参数数据包较小（建议小于100K），消费者比提供者个数多，单一消费者无法压满提供者，尽量不要用 dubbo 协议传输大文件或超大字符串。
适用场景：常规远程服务方法调用

约束

参数及返回值需实现 Serializable 接口
参数及返回值不能自定义实现 List, Map, Number, Date, Calendar 等接口，只能用 JDK 自带的实现，因为 hessian 会做特殊处理，自定义实现类中的属性值都会丢失。
Hessian 序列化，只传成员属性值和值的类型，不传方法或静态变量，兼容情况由吴亚军提供

数据通讯	情况	结果
A->B	类A多一种属性（或者说类B少一种属性）	不抛异常，A多的那个属性的值，B没有，其他正常
A->B	枚举A多一种枚举（或者说B少一种枚举）	A使用多出来的枚举进行传输
A->B	枚举A多一种枚举（或者说B少一种枚举）	A不使用多出来的枚举进行传输
A->B	A和B的属性名相同，但类型不相同	抛异常
A->B	serialId 不相同	正常传输

Fastjson2

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

1 介绍

FASTJSON v2是FASTJSON项目的重要升级，目标是为下一个十年提供一个高性能的JSON库。通过同一套API，

支持JSON/JSONB两种协议，JSONPath 是一等公民。
支持全量解析和部分解析。
支持Java服务端、客户端Android、大数据场景。
支持Kotlin https://alibaba.github.io/fastjson2
支持JSON Schema https://alibaba.github.io/fastjson2
支持Android 8+
支持Graal Native-Image
支持 JSON Schema https://alibaba.github.io/fastjson2

2 使用方式

2.1 添加依赖

<dependencies>
 <dependency>
 <groupId>com.alibaba.fastjson2</groupId>
 <artifactId>fastjson2</artifactId>
 <version>2.0.23</version>
 </dependency>
</dependencies>

注：Fastjson2 序列化仅 Dubbo > 3.1.0 版本支持。在 Dubbo > 3.2.0 中将替代 Hessian 作为默认序列化方式。

2.2 配置启用

# application.yml (Spring Boot)
dubbo:
 protocol:
 serialization: fastjson2

或

# dubbo.properties
dubbo.protocol.serialization=fastjson2

# or
dubbo.consumer.serialization=fastjson2

# or
dubbo.reference.com.demo.DemoService.serialization=fastjson2

或

<dubbo:protocol serialization="fastjson2" />

<!-- or -->
<dubbo:consumer serialization="fastjson2" />

<!-- or -->
<dubbo:reference interface="xxx" serialization="fastjson2" />

使用 Filter 过滤器动态拦截请求（request）或响应（response）

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

Filter 过滤器动态拦截请求（request）或响应（response）以转换或使用请求或响应中包含的信息。过滤器本身通常不会创建响应，而是提供可以“附加”到任何一次 RPC 请求的通用函数。Dubbo Filter 是可插拔的，我们可以在一次 RPC 请求中插入任意类型的、任意多个 Filter。

Filter 工作原理如下图所示：

可以通过 Filter 实现的一些典型能力如下：

记录请求参数、响应结果等到日志文件
为 RPC 请求添加认证或校验逻辑
在发送或执行请求之前，格式化请求体或 header 参数
压缩响应结果
对请求数据进行埋点，统计调用耗时、成功、失败次数等
监测并发执行的请求数量，实现限流降级能力

使用方式

如上图所示，Dubbo 代理会自动加载 Filter 实现并将它们组装到调用链路。Filter 是一个标准的 SPI 定义，框架按照一定的激活规则自动加载 Filter 实现。

@SPI(scope = ExtensionScope.MODULE)
public interface Filter extends BaseFilter {}

Filter 的默认激活状态可在定义中通过 @Activate 注解设置，如以下定义表示该 Filter 在提供者端执行 RPC 请求时自动开启（在消费端不开启）。@Activate 支持多种条件控制，包括 classpath 下有某个类的定义时开启，URL 中有哪个参数值时开启等，具体可参见 SPI 扩展 Activate 介绍。

@Activate(group = PROVIDER)
public class AccessLogFilter implements Filter {}

关闭自动加载

如想关闭某个 filter 加载，在不修改 Filter 定义的情况下，可通过以下几种配置关闭。

全局关闭 filter，所有 rpc 调用均不启用 filter

使用 Grafana 可视化查看集群 Metrics 指标

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

指标可视化页面目前推荐的方式是使用 Grafana 来配置 Dubbo 的可观测性监控大盘。

在您开始之前

一个可以访问的 Kubernetes 集群
正确安装并配置普罗米修斯服务
安装 Grafana
部署示例应用并开启指标采集

确认组件正常运行

Kubernetes

确保 Prometheus 正常运行

$ kubectl -n dubbo-system get svc prometheus
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
prometheus ClusterIP 10.0.250.230 <none> 9090/TCP 180s

确保 Grafana 正常运行

$ kubectl -n dubbo-system get svc grafana
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
grafana ClusterIP 10.0.244.130 <none> 3000/TCP 180s

部署示例

kubectl apply -f https://raw.githubusercontent.com/apache/dubbo-samples/master/4-governance/dubbo-samples-metrics-spring-boot/Deployment.yml

等待示例应用正常运行，通过以下命令确认应用状态：

kubectl -n dubbo-demo get deployments

查看 Grafana 可视化面板

示例程序启动后会自动模拟服务调用，只需等待一会能在 Grafana 中可视化的看到 Metrics 指标。

Helm

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

敬请期待

HTTP 协议规范

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

注意

从 Dubbo 3.3 版本开始，Rest 协议已移至 Extensions 库，由 Triple 协议来对 Rest 提供更全面的支持，具体参见 Triple Rest用户手册，如需继续使用原 Rest 协议，可引入对应 dubbo-spi-extensions 库依赖

什么是 Dubbo Http

基于 spring web 和 resteasy 注解编码风格，通过http协议进行服务间调用互通，dubbo protocol扩展实现的协议

为什么选择Dubbo Http

dubbo http 可以实现微服务与dubbo之间的互通
多协议发布服务，可以实现服务协议的平滑迁移
http的通用性，解决跨语言互通
最新版本的http 无需添加其他组件，更轻量
resteasy以及spring web的编码风格，上手更快

协议规范

Request

相对于原生的http协议dubbo http 请求增加version和group两个header用于确定服务的唯一, 如果provider一端没有声明group和version,http请求时就不需要传递这连个header,反之必须要传递目标服务的group和version, 如果使用dubbo http的RestClient这两个header将会默认通过attachment传递为区别于其他的header，attachment将会增加rest-service-前缀，因此通过其他形式的http client调用 dubbo http服务需要传递 rest-service-version 和 rest-service-group 两个header

POST /test/path HTTP/1.1
Host: localhost:8080
Content-type: application/json
Accept: text/html
rest-service-version: 1.0.0
rest-service-group: dubbo

{"name":"dubbo","age":10,"address":"hangzhou"}

Response

HTTP/1.1 200
Content-Type: text/html
Content-Length: 4
Date: Fri, 28 Apr 2023 14:16:42 GMT

"success"

content-type支持
- application/json
- application/x-www-form-urlencoded
- text/plain
- text/xml

目前支持以上media，后面还会对type进行扩展

http 协议

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

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

基于 HTTP 表单的远程调用协议，采用 Spring 的 HttpInvoker 实现

提示

2.3.0 以上版本支持

特性

连接个数：多连接
连接方式：短连接
传输协议：HTTP
传输方式：同步传输
序列化：表单序列化
适用范围：传入传出参数数据包大小混合，提供者比消费者个数多，可用浏览器查看，可用表单或URL传入参数，暂不支持传文件。
适用场景：需同时给应用程序和浏览器 JS 使用的服务。

约束

参数及返回值需符合 Bean 规范

配置

配置协议：

<dubbo:protocol name="http" port="8080" />

配置 Jetty Server (默认)：

<dubbo:protocol ... server="jetty" />

配置 Servlet Bridge Server (推荐使用)：

<dubbo:protocol ... server="servlet" />

配置 DispatcherServlet：

<servlet>
 <servlet-name>dubbo</servlet-name>
 <servlet-class>org.apache.dubbo.remoting.http.servlet.DispatcherServlet</servlet-class>
 <load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
 <servlet-name>dubbo</servlet-name>
 <url-pattern>/*</url-pattern>
</servlet-mapping>

注意，如果使用 servlet 派发请求：

协议的端口 <dubbo:protocol port="8080" /> 必须与 servlet 容器的端口相同，
协议的上下文路径 <dubbo:protocol contextpath="foo" /> 必须与 servlet 应用的上下文路径相同。

http 协议

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

基于 HTTP 表单的远程调用协议，采用 Spring 的 HttpInvoker 实现

提示

2.3.0 以上版本支持

特性

连接个数：多连接
连接方式：短连接
传输协议：HTTP
传输方式：同步传输
序列化：表单序列化
适用范围：传入传出参数数据包大小混合，提供者比消费者个数多，可用浏览器查看，可用表单或URL传入参数，暂不支持传文件。
适用场景：需同时给应用程序和浏览器 JS 使用的服务。

约束

参数及返回值需符合 Bean 规范

配置

配置协议：

<dubbo:protocol name="http" port="8080" />

配置 Jetty Server (默认)：

<dubbo:protocol ... server="jetty" />

配置 Servlet Bridge Server (推荐使用)：

<dubbo:protocol ... server="servlet" />

配置 DispatcherServlet：

<servlet>
 <servlet-name>dubbo</servlet-name>
 <servlet-class>org.apache.dubbo.remoting.http.servlet.DispatcherServlet</servlet-class>
 <load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
 <servlet-name>dubbo</servlet-name>
 <url-pattern>/*</url-pattern>
</servlet-mapping>

注意，如果使用 servlet 派发请求：

协议的端口 <dubbo:protocol port="8080" /> 必须与 servlet 容器的端口相同，
协议的上下文路径 <dubbo:protocol contextpath="foo" /> 必须与 servlet 应用的上下文路径相同。

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 支持以下配置：

Nacos

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

1 前置条件

了解 Dubbo 基本开发步骤
安装并启动 Nacos

当Dubbo使用3.0.0及以上版本时，需要使用Nacos 2.0.0及以上版本。请参考 nacos 注册中心了解 nacos 版本适配情况。

2 使用说明

2.1 增加 Maven 依赖

如果项目已经启用 Nacos 作为注册中心，则无需增加任何额外配置。

如果未启用 Nacos 注册中心，则请参考为注册中心增加 Nacos 依赖。

2.2 启用 Nacos 配置中心

<dubbo:config-center address="nacos://127.0.0.1:8848"/>

或者

dubbo
 config-center
 address: nacos://127.0.0.1:8848

或者

dubbo.config-center.address=nacos://127.0.0.1:8848

或者

ConfigCenterConfig configCenter = new ConfigCenterConfig();
configCenter.setAddress("nacos://127.0.0.1:8848");

address 格式请参考 Nacos 注册中心 - 启用配置

3 高级配置

如要开启认证鉴权，请参考 Nacos 注册中心 - 启用认证鉴权

3.1 外部化配置

3.1.1 全局外部化配置

1. 应用开启 config-center 配置

dubbo
 config-center
 address: nacos://127.0.0.1:2181
 config-file: dubbo.properties # optional

config-file - 全局外部化配置文件 key 值，默认 dubbo.properties。config-file 代表将 Dubbo 配置文件存储在远端注册中心时，文件在配置中心对应的 key 值，通常不建议修改此配置项。

PixiuGatewayPolicy

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

概述

PixiuGatewayPolicy 是一个自定义资源扩展，用于为 Pixiu Gateway 实例配置网关级别的策略。

用例

提供统一的方式来配置网关级别设置，而无需直接修改 Gateway 资源
配置日志和分布式追踪，以便更好地观测网关操作
在监听器和全局级别管理连接和请求超时
配置优雅关闭行为以确保零停机部署

控制 Gateway 中所有监听器的空闲、读取和写入超时

apiVersion: pixiu.apache.org/v1alpha1
kind: PixiuGatewayPolicy
metadata:
 name: gateway-timeout-policy
 namespace: pixiu-gateway-system
spec:
 targetRef:
 group: gateway.networking.k8s.io
 kind: Gateway
 name: pixiu-listeners
 listener:
 timeout:
 idle: 300s
 read: 60s
 write: 60s

配置分布式追踪以跟踪跨服务的请求

apiVersion: pixiu.apache.org/v1alpha1
kind: PixiuGatewayPolicy
metadata:
 name: gateway-tracing-policy
 namespace: pixiu-gateway-system
spec:
 targetRef:
 group: gateway.networking.k8s.io
 kind: Gateway
 name: pixiu-listeners
 tracing:
 name: jaeger
 serviceName: pixiu-gateway
 sampler:
 type: probabilistic
 param: "0.1"
 config:
 url: http://jaeger-collector:14268/api/traces
 headers:
 Authorization: "Bearer token"

自定义网关的日志行为

Redis 注册中心

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

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

基于 Redis [^1] 实现的注册中心。

提示

从 2.1.0 版本开始支持。

Redis 过期数据通过心跳的方式检测脏数据，服务器时间必须同步，并且对服务器有一定压力，否则过期检测会不准确

使用 Redis 的 Key/Map 结构存储数据结构：

主 Key 为服务名和类型
Map 中的 Key 为 URL 地址
Map 中的 Value 为过期时间，用于判断脏数据，脏数据由监控中心删除 [^3]

使用 Redis 的 Publish/Subscribe 事件通知数据变更：

通过事件的值区分事件类型：register, unregister, subscribe, unsubscribe
普通消费者直接订阅指定服务提供者的 Key，只会收到指定服务的 register, unregister 事件
监控中心通过 psubscribe 功能订阅 /dubbo/*，会收到所有服务的所有变更事件

调用过程：

服务提供方启动时，向 Key:/dubbo/com.foo.BarService/providers 下，添加当前提供者的地址
并向 Channel:/dubbo/com.foo.BarService/providers 发送 register 事件
服务消费方启动时，从 Channel:/dubbo/com.foo.BarService/providers 订阅 register 和 unregister 事件
并向 Key:/dubbo/com.foo.BarService/consumers 下，添加当前消费者的地址
服务消费方收到 register 和 unregister 事件后，从 Key:/dubbo/com.foo.BarService/providers 下获取提供者地址列表
服务监控中心启动时，从 Channel:/dubbo/* 订阅 register 和 unregister，以及 subscribe 和unsubsribe 事件
服务监控中心收到 register 和 unregister 事件后，从 Key:/dubbo/com.foo.BarService/providers 下获取提供者地址列表
服务监控中心收到 subscribe 和 unsubsribe 事件后，从 Key:/dubbo/com.foo.BarService/consumers 下获取消费者地址列表

配置

<dubbo:registry address="redis://10.20.153.10:6379" />

或

Redis 注册中心

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

基于 Redis [^1] 实现的注册中心。

提示

从 2.1.0 版本开始支持。

Redis 过期数据通过心跳的方式检测脏数据，服务器时间必须同步，并且对服务器有一定压力，否则过期检测会不准确

使用 Redis 的 Key/Map 结构存储数据结构：

主 Key 为服务名和类型
Map 中的 Key 为 URL 地址
Map 中的 Value 为过期时间，用于判断脏数据，脏数据由监控中心删除 [^3]

使用 Redis 的 Publish/Subscribe 事件通知数据变更：

通过事件的值区分事件类型：register, unregister, subscribe, unsubscribe
普通消费者直接订阅指定服务提供者的 Key，只会收到指定服务的 register, unregister 事件
监控中心通过 psubscribe 功能订阅 /dubbo/*，会收到所有服务的所有变更事件

调用过程：

服务提供方启动时，向 Key:/dubbo/com.foo.BarService/providers 下，添加当前提供者的地址
并向 Channel:/dubbo/com.foo.BarService/providers 发送 register 事件
服务消费方启动时，从 Channel:/dubbo/com.foo.BarService/providers 订阅 register 和 unregister 事件
并向 Key:/dubbo/com.foo.BarService/consumers 下，添加当前消费者的地址
服务消费方收到 register 和 unregister 事件后，从 Key:/dubbo/com.foo.BarService/providers 下获取提供者地址列表
服务监控中心启动时，从 Channel:/dubbo/* 订阅 register 和 unregister，以及 subscribe 和unsubsribe 事件
服务监控中心收到 register 和 unregister 事件后，从 Key:/dubbo/com.foo.BarService/providers 下获取提供者地址列表
服务监控中心收到 subscribe 和 unsubsribe 事件后，从 Key:/dubbo/com.foo.BarService/consumers 下获取消费者地址列表

配置

<dubbo:registry address="redis://10.20.153.10:6379" />

或

Registry

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

在服务发现一章中，我们了解了 Dubbo 内置的几个核心注册中心实现 Nacos、Zookeeper 的使用方式与工作原理。本文讲解如何通过扩展 org.apache.dubbo.registry.client.ServiceDiscovery 和 org.apache.dubbo.registry.nacos.NacosServiceDiscoveryFactory SPI，提供自定义的注册中心实现。

本示例的完整源码请参见 dubbo-registry-etcd。除了本示例之外，Dubbo 核心仓库 apache/dubbo 以及扩展库 apache/dubbo-spi-extensions 中的众多注册中心扩展实现，都可以作为扩展参考实现：

# Dubbo对外支持的常用注册中心实现
nacos=org.apache.dubbo.registry.nacos.NacosServiceDiscoveryFactory
zookeeper=org.apache.dubbo.registry.zookeeper.ZookeeperServiceDiscoveryFactory

任务详情

通过扩展 SPI 实现基于的 etcd 注册中心。

实现方式

代码详情

首先，通过继承 AbstractServiceDiscoveryFactory 实现 ServiceDiscoveryFactory 接口

public class EtcdServiceDiscoveryFactory extends AbstractServiceDiscoveryFactory {

 @Override
 protected ServiceDiscovery createDiscovery(URL registryURL) {
 return new EtcdServiceDiscovery(applicationModel, registryURL);
 }

}

EtcdServiceDiscovery 的一些关键方法与实现如下：

public class EtcdServiceDiscovery extends AbstractServiceDiscovery {

 private final Set<String> services = new ConcurrentHashSet<>();
 private final Map<String, InstanceChildListener> childListenerMap = new ConcurrentHashMap<>();

 EtcdClient etcdClient;

 public EtcdServiceDiscovery(ApplicationModel applicationModel, URL registryURL) {
 super(applicationModel, registryURL);
 EtcdTransporter etcdTransporter = applicationModel.getExtensionLoader(EtcdTransporter.class).getAdaptiveExtension();

 etcdClient = etcdTransporter.connect(registryURL);

 etcdClient.addStateListener(state -> {
 if (state == StateListener.CONNECTED) {
 try {
 recover();
 } catch (Exception e) {
 logger.error(e.getMessage(), e);
 }
 }
 });

 this.registryURL = registryURL;
 }

 @Override
 public void doRegister(ServiceInstance serviceInstance) {
 try {
 String path = toPath(serviceInstance);
 etcdClient.putEphemeral(path, new Gson().toJson(serviceInstance));
 services.add(serviceInstance.getServiceName());
 } catch (Throwable e) {
 throw new RpcException("Failed to register " + serviceInstance + " to etcd " + etcdClient.getUrl()
 + ", cause: " + (OptionUtil.isProtocolError(e)
 ? "etcd3 registry may not be supported yet or etcd3 registry is not available."
 : e.getMessage()), e);
 }
 }

 @Override
 protected void doUnregister(ServiceInstance serviceInstance) {
 try {
 String path = toPath(serviceInstance);
 etcdClient.delete(path);
 services.remove(serviceInstance.getServiceName());
 } catch (Throwable e) {
 throw new RpcException("Failed to unregister " + serviceInstance + " to etcd " + etcdClient.getUrl() + ", cause: " + e.getMessage(), e);
 }
 }

 @Override
 public void addServiceInstancesChangedListener(ServiceInstancesChangedListener listener) throws NullPointerException, IllegalArgumentException {
 for (String serviceName : listener.getServiceNames()) {
 registerServiceWatcher(serviceName, listener);
 }
 }

 @Override
 public List<ServiceInstance> getInstances(String serviceName) {
 List<String> children = etcdClient.getChildren(toParentPath(serviceName));
 if (CollectionUtils.isEmpty(children)) {
 return Collections.emptyList();
 }
 List<ServiceInstance> list = new ArrayList<>(children.size());
 for (String child : children) {
 ServiceInstance serviceInstance = new Gson().fromJson(etcdClient.getKVValue(child), DefaultServiceInstance.class);
 list.add(serviceInstance);
 }
 return list;
 }
}

SPI配置

在 resources/META-INF/dubbo/org.apache.dubbo.registry.client.ServiceDiscoveryFactory 文件中添加如下配置：

发布 REST 风格的服务

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

本文要讲的 “rest 协议” 实际上并不是一个真正的协议实现，而是关于如何使得 triple 协议支持以 rest 风格的 http 请求直接访问。我们将演示如何使用 rest 请求访问标准 triple 协议的 Dubbo 服务。

注意

从 Dubbo 3.3 版本开始，rest 协议已移至 extensions 库，由 triple 协议来对 Rest 提供更全面的支持，新版本的内置协议实现只剩下 triple 和 dubbo。
因此，当我们提到 rest 时，都是指 triple 协议的 rest 访问支持能力，具体参见 Triple Rest用户手册

在讲解 triple 协议示例时，我们曾提到 triple 协议支持以 application/json 格式直接访问：

curl \
 --header "Content-Type: application/json" \
 --data '["Dubbo"]' \
 http://localhost:50052/org.apache.dubbo.samples.api.GreetingsService/sayHi/

如果你认为以上 http://localhost:50052/org.apache.dubbo.samples.api.GreetingsService/sayHi 格式的 path 请求不够友好，还可以通过注解自定义 http 请求的路径和方法等参数，目前已支持内置，Spring Web和JAX-RS 三种注解格式。以下示例的完整代码请参见 dubbo-samples-triple-rest。

下载并运行示例

# 获取示例代码
git clone --depth=1 https://github.com/apache/dubbo-samples.git
cd dubbo-samples/2-advanced/dubbo-samples-triple-rest/dubbo-samples-triple-rest-basic
# 直接运行
mvn spring-boot:run
# 或打包后运行
mvn clean package -DskipTests
java -jar target/dubbo-samples-triple-rest-basic-1.0.0-SNAPSHOT.jar

当然，也可以直接用IDE导入工程后直接执行 org.apache.dubbo.rest.demo.BasicRestApplication#main 来运行，并通过下断点 debug 的方式来深入理解原理。

Sentinel限流降级

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

Dubbo-go 中提供了内置的限流组件，用户可根据自己的业务场景调整限流值、限流后的行为等，具体可 TpsLimiter 定义与具体实现。用户可通过类似以下方式在服务端设置简单的限流策略：

server.WithTpsLimiter("method-service") // 目前支持 method-service、polaris 等几个实现
server.WithTpsLimiterXxx() // 设置限流相关阈值，请根据具体方法填写
//tps.limit.strategy: "slidingWindow"
//tps.limit.rejected.handler: "default"
//tps.limit.interval: 1000
//tps.limit.rate: 3

Dubbo-go 内置限流策略相对简单，对于一些更复杂的场景，我们建议通过使用 Sentinel 等专业的第三方框架可以实现更丰富、更灵活的限流策略。

可在此查看本示例完整源码，也可以参考 Dubbo+Sentinel 的 Java 示例获得更多灵感。

Provider 限流

基于 QpS 限流

基于并发任务数限流(当前在运行任务数)

Consumer 限流

熔断策略

基于并发请求数限流(未收到响应的请求数)

Skywalking

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

安装

你可以使用 Dubbo 社区提供的示例配置快速安装 Skywalking。

kubectl create -f https://raw.githubusercontent.com/apache/dubbo-kubernetes/master/deploy/kubernetes/skywalking.yaml

本安装仅适用于测试或体验使用，生产级别的安装请参考 Skywalking 官方安装文档。

Spring Boot

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

关于 Spring Boot 的注解、基本使用方法等请参考使用教程 - Spring Boot。以下是 spring boot 支持的配置详情与 starter 列表。

application.yaml

以下是 Dubbo 框架支持的配置组件列表，可以在 Spring Boot 配置文件中指定所需配置。

配置示例

dubbo:
 application:
 name: dubbo-springboot-demo-provider
 logger: slf4j
 protocol:
 name: dubbo
 port: 50052
 registry:
 address: nacos://${nacos.address:127.0.0.1}:8848?username=nacos&password=nacos

dubbo

dubbo.metrics

dubbo.tracing

starter列表

dubbo-spring-boot-starter

以下是一些 dubbo-spring-boot-starter 版本对应的 SpringBoot、JDK 依赖：

Streaming 通信模型

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

在此查看完整示例。

Dubbo-Python 支持流式调用，包括 ClientStream、ServerStream 和 BidirectionalStream 三种模式。

在流式调用中，操作可以分为写入流和读取流两部分。对于 ClientStream，是多次写入、单次读取；对于 ServerStream，是单次写入、多次读取；而 BidirectionalStream 支持多次写入和多次读取。

写入流

流式调用的写入操作分为单次写入（ServerStream）和多次写入（ClientStream 和 BidirectionalStream）。

单次写入

单次写入流的调用方式与 unary 模式类似。例如：

stub.server_stream(greeter_pb2.GreeterRequest(name="hello world from dubbo-python"))

多次写入

对于多次写入流，用户可以通过迭代器或 writeStream 方式写入数据（两者只能选其一）。

迭代器写入：写入方式类似于 unary 模式，唯一的区别是传入的是迭代器。例如：

# Use an iterator to send multiple requests
def request_generator():
 for i in ["hello", "world", "from", "dubbo-python"]:
 yield greeter_pb2.GreeterRequest(name=str(i))

# Call the remote method and return a read_stream
stream = stub.client_stream(request_generator())

使用 writeStream 写入：此方法不传入参数，使用空参调用，然后通过 write 方法逐条写入数据，写入完成后调用 done_writing 方法结束流。例如：

stream = stub.bi_stream()
# Use the write method to send messages
stream.write(greeter_pb2.GreeterRequest(name="jock"))
stream.write(greeter_pb2.GreeterRequest(name="jane"))
stream.write(greeter_pb2.GreeterRequest(name="alice"))
stream.write(greeter_pb2.GreeterRequest(name="dave"))
# Call done_writing to notify the server that the client has finished writing
stream.done_writing()

读取流

流式调用的读取操作分为单次读取（ClientStream）和多次读取（ServerStream 和 BidirectionalStream）。在流式调用中，无论是哪种模式，返回的都是一个 ReadStream。我们可以使用 read 方法或迭代器读取数据，针对 read 方法，需要注意以下几点：

Streaming 通信模型

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

本文重点讲解 Dubbo Rust Streaming 通信模式，请先查看 Quick Start 了解 Dubbo Rust 基本使用，在此查看本文的完整示例。

1 IDL 中增加 Streaming 模型定义

完整 Greeter 服务定义如下，包含一个 Unary、Client stream、Server stream、Bidirectional stream 模型的 Dubbo 服务。

// ./proto/greeter.proto
syntax = "proto3";

option java_multiple_files = true;

package org.apache.dubbo.sample.tri;


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

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

service Greeter{

 // unary
 rpc greet(GreeterRequest) returns (GreeterReply);

 // clientStream
 rpc greetClientStream(stream GreeterRequest) returns (GreeterReply);

 // serverStream
 rpc greetServerStream(GreeterRequest) returns (stream GreeterReply);

 // bi streaming
 rpc greetStream(stream GreeterRequest) returns (stream GreeterReply);

}

2 使用 Streaming 模型定义编写逻辑

2.1 编写 Streaming Server

// ./src/greeter/server.rs
pub mod protos {
 include!(concat!(env!("OUT_DIR"), "/org.apache.dubbo.sample.tri.rs"));
}

use futures_util::StreamExt;
use protos::{
 greeter_server::{register_server, Greeter},
 GreeterReply, GreeterRequest,
};

use std::{io::ErrorKind, pin::Pin};

use async_trait::async_trait;
use futures_util::Stream;
use tokio::sync::mpsc;
use tokio_stream::wrappers::ReceiverStream;

use dubbo_config::RootConfig;
use dubbo::{codegen::*, Dubbo};

type ResponseStream =
 Pin<Box<dyn Stream<Item = Result<GreeterReply, dubbo::status::Status>> + Send>>;

#[tokio::main]
async fn main() {
 register_server(GreeterServerImpl {
 name: "greeter".to_string(),
 });

 // Dubbo::new().start().await;
 Dubbo::new()
 .with_config({
 let r = RootConfig::new();
 match r.load() {
 Ok(config) => config,
 Err(_err) => panic!("err: {:?}", _err), // response was droped
 }
 })
 .start()
 .await;
}

#[allow(dead_code)]
#[derive(Default, Clone)]
struct GreeterServerImpl {
 name: String,
}

// #[async_trait]
#[async_trait]
impl Greeter for GreeterServerImpl {
 async fn greet(
 &self,
 request: Request<GreeterRequest>,
 ) -> Result<Response<GreeterReply>, dubbo::status::Status> {
 println!("GreeterServer::greet {:?}", request.metadata);

 Ok(Response::new(GreeterReply {
 message: "hello, dubbo-rust".to_string(),
 }))
 }

 async fn greet_client_stream(
 &self,
 request: Request<Decoding<GreeterRequest>>,
 ) -> Result<Response<GreeterReply>, dubbo::status::Status> {
 let mut s = request.into_inner();
 loop {
 let result = s.next().await;
 match result {
 Some(Ok(val)) => println!("result: {:?}", val),
 Some(Err(val)) => println!("err: {:?}", val),
 None => break,
 }
 }
 Ok(Response::new(GreeterReply {
 message: "hello client streaming".to_string(),
 }))
 }

 type greetServerStreamStream = ResponseStream;
 async fn greet_server_stream(
 &self,
 request: Request<GreeterRequest>,
 ) -> Result<Response<Self::greetServerStreamStream>, dubbo::status::Status> {
 println!("greet_server_stream: {:?}", request.into_inner());

 let data = vec![
 Result::<_, dubbo::status::Status>::Ok(GreeterReply {
 message: "msg1 from server".to_string(),
 }),
 Result::<_, dubbo::status::Status>::Ok(GreeterReply {
 message: "msg2 from server".to_string(),
 }),
 Result::<_, dubbo::status::Status>::Ok(GreeterReply {
 message: "msg3 from server".to_string(),
 }),
 ];
 let resp = futures_util::stream::iter(data);

 Ok(Response::new(Box::pin(resp)))
 }

 type greetStreamStream = ResponseStream;
 async fn greet_stream(
 &self,
 request: Request<Decoding<GreeterRequest>>,
 ) -> Result<Response<Self::greetStreamStream>, dubbo::status::Status> {
 println!(
 "GreeterServer::greet_stream, grpc header: {:?}",
 request.metadata
 );

 let mut in_stream = request.into_inner();
 let (tx, rx) = mpsc::channel(128);

 // this spawn here is required if you want to handle connection error.
 // If we just map `in_stream` and write it back as `out_stream` the `out_stream`
 // will be drooped when connection error occurs and error will never be propagated
 // to mapped version of `in_stream`.
 tokio::spawn(async move {
 while let Some(result) = in_stream.next().await {
 match result {
 Ok(v) => {
 // if v.name.starts_with("msg2") {
 // tx.send(Err(dubbo::status::Status::internal(format!("err: args is invalid, {:?}", v.name))
 // )).await.expect("working rx");
 // continue;
 // }
 tx.send(Ok(GreeterReply {
 message: format!("server reply: {:?}", v.name),
 }))
 .await
 .expect("working rx")
 }
 Err(err) => {
 if let Some(io_err) = match_for_io_error(&err) {
 if io_err.kind() == ErrorKind::BrokenPipe {
 // here you can handle special case when client
 // disconnected in unexpected way
 eprintln!("\tclient disconnected: broken pipe");
 break;
 }
 }

 match tx.send(Err(err)).await {
 Ok(_) => (),
 Err(_err) => break, // response was droped
 }
 }
 }
 }
 println!("\tstream ended");
 });

 // echo just write the same data that was received
 let out_stream = ReceiverStream::new(rx);

 Ok(Response::new(
 Box::pin(out_stream) as Self::greetStreamStream
 ))
 }
}

fn match_for_io_error(err_status: &dubbo::status::Status) -> Option<&std::io::Error> {
 let mut err: &(dyn std::error::Error + 'static) = err_status;

 loop {
 if let Some(io_err) = err.downcast_ref::<std::io::Error>() {
 return Some(io_err);
 }

 err = match err.source() {
 Some(err) => err,
 None => return None,
 };
 }
}

2.2 编写 Streaming Client

// ./src/greeter/client.rs
pub mod protos {
 include!(concat!(env!("OUT_DIR"), "/org.apache.dubbo.sample.tri.rs"));
}

use dubbo::codegen::*;
use futures_util::StreamExt;
use protos::{greeter_client::GreeterClient, GreeterRequest};

#[tokio::main]
async fn main() {
 let mut cli = GreeterClient::new().with_uri("http://127.0.0.1:8888".to_string());

 println!("# unary call");
 let resp = cli
 .greet(Request::new(GreeterRequest {
 name: "message from client".to_string(),
 }))
 .await;
 let resp = match resp {
 Ok(resp) => resp,
 Err(err) => return println!("{:?}", err),
 };
 let (_parts, body) = resp.into_parts();
 println!("Response: {:?}", body);

 println!("# client stream");
 let data = vec![
 GreeterRequest {
 name: "msg1 from client streaming".to_string(),
 },
 GreeterRequest {
 name: "msg2 from client streaming".to_string(),
 },
 GreeterRequest {
 name: "msg3 from client streaming".to_string(),
 },
 ];
 let req = futures_util::stream::iter(data);
 let resp = cli.greet_client_stream(req).await;
 let client_streaming_resp = match resp {
 Ok(resp) => resp,
 Err(err) => return println!("{:?}", err),
 };
 let (_parts, resp_body) = client_streaming_resp.into_parts();
 println!("client streaming, Response: {:?}", resp_body);

 println!("# bi stream");
 let data = vec![
 GreeterRequest {
 name: "msg1 from client".to_string(),
 },
 GreeterRequest {
 name: "msg2 from client".to_string(),
 },
 GreeterRequest {
 name: "msg3 from client".to_string(),
 },
 ];
 let req = futures_util::stream::iter(data);

 let bidi_resp = cli.greet_stream(req).await.unwrap();

 let (parts, mut body) = bidi_resp.into_parts();
 println!("parts: {:?}", parts);
 while let Some(item) = body.next().await {
 match item {
 Ok(v) => {
 println!("reply: {:?}", v);
 }
 Err(err) => {
 println!("err: {:?}", err);
 }
 }
 }
 let trailer = body.trailer().await.unwrap();
 println!("trailer: {:?}", trailer);

 println!("# server stream");
 let resp = cli
 .greet_server_stream(Request::new(GreeterRequest {
 name: "server streaming req".to_string(),
 }))
 .await
 .unwrap();

 let (parts, mut body) = resp.into_parts();
 println!("parts: {:?}", parts);
 while let Some(item) = body.next().await {
 match item {
 Ok(v) => {
 println!("reply: {:?}", v);
 }
 Err(err) => {
 println!("err: {:?}", err);
 }
 }
 }
 let trailer = body.trailer().await.unwrap();
 println!("trailer: {:?}", trailer);
}

3 运行示例

编译

执行cargo build来编译server和client。

通过网关将 http 流量接入 Dubbo 后端服务

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

在 triple协议规范中我们曾详细介绍了 triple 对于浏览器、网关的友好性设计，其中非常重要的一点是 triple 同时支持跑在 HTTP/1、HTTP/2 上：

在后端服务之间使用高效的 triple 二进制协议。
对于前端接入层，则支持所有标准 HTTP 工具如 cURL 等以标准 application/json 、application/yaml 等格式请求后端服务。

接下来我们就看一下，对于前端 HTTP 流量而言，如何通过一些通用的网关产品快速接入后端的 triple 微服务体系。

注意

使用 triple 协议后，不再需要泛化调用、http -> dubbo 协议转换等步骤，任何主流的网关设备都可以通过 http 流量直接访问后端 triple 协议服务。具体参见发布 REST 风格的服务

原生 HTTP 接入

如上图所示，从浏览器、手机或 Web 服务器过来的 HTTP 请求，网关可直接转发给后端 Dubbo 服务，后端服务之间则继续走 triple 二进制协议。由于进出网关的都是标准的 HTTP 流量，网关不需要做任何的私有协议转换工作，不需要任何定制化逻辑，只需专注于流量路由等职责即可。

在真正的生产环境下，唯一需要网关解决的只剩下地址发现问题，即如何动态感知后端 triple 服务的实例变化？ 好消息是，目前几款主流的开源网关产品如 Apache APISIX、Higress 等普遍支持以 Nacos、Zookeeper、Kubernetes 作为 upstream 数据源。

以下我们以 Higress + Nacos + Dubbo 的典型用法为例，详细说明整套机制的工作流程。

Zipkin

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

这个示例演示了 Dubbo 集成 Zipkin 全链路追踪的基础示例，完整代码请参考 dubbo-samples-tracing-zipkin，此示例共包含三部分内容：

dubbo-samples-spring-boot3-tracing-provider
dubbo-samples-spring-boot3-tracing-consumer
dubbo-samples-spring-boot3-tracing-interface

快速开始

安装 & 启动 Zipkin

参考 Zipkin’s quick start 安装 Zipkin。

这里我们使用 Docker 来演示如何快速的启动 Zipkin 服务。

docker run -d -p 9411:9411 --name zipkin openzipkin/zipkin

紧接着，你可以通过如下链接确认 Zipkin 正常工作 [http://localhost:9411](http://localhost:9411)

安装 & 启动 Nacos

跟随 Nacos’s quick start 快速安装并启动 Nacos。

启动示例 Provider

在 IDE 中直接运行 org.apache.dubbo.springboot.demo.provider.ProviderApplication。

启动示例 Consumer

在 IDE 中直接运行 org.apache.dubbo.springboot.demo.consumer.ConsumerApplication。

检查监控效果

在浏览器中打开 http://localhost:9411/zipkin/ 查看效果。

如何在SpringBoot项目中使用 Dubbo Tracing

1. 添加 Dubbo Tracing 相关的 Starter 依赖

从下面两个 starter 中选择一个加入到你的项目中，区别在于 Tracer 的选型不一样，一个是 Opentelemetry，一个是 Brave：

使用 Zookeeper 作为注册中心实现自动服务发现

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

本示例演示 Zookeeper 作为注册中心实现自动服务发现，示例基于 Spring Boot 应用展开，可在此查看完整示例代码

1 基本配置

1.1 增加 Maven 依赖

添加 dubbo、zookeeper 等依赖。dubbo-spring-boot-starter 将自动为应用增加 Zookeeper 相关客户端的依赖，减少用户使用 Zookeeper 成本，如使用中遇到版本兼容问题，用户也可以选择自行添加 Curator、Zookeeper Client 等依赖。

对于 Spring Boot 应用而言，可使用如下依赖：

<dependency>
 <groupId>org.apache.dubbo</groupId>
 <artifactId>dubbo-spring-boot-starter</artifactId>
 <version>${dubbo.version}</version>
</dependency>
<!-- 推荐 Zookeeper Server 3.8.0+ 版本 -->
<dependency>
 <groupId>org.apache.dubbo</groupId>
 <artifactId>dubbo-zookeeper-curator5-spring-boot-starter</artifactId>
 <version>${dubbo.version}</version>
</dependency>
<!-- 仅当 Zookeeper Server 版本是 3.4.x 及以下时，使用此依赖
<dependency>
 <groupId>org.apache.dubbo</groupId>
 <artifactId>dubbo-zookeeper-spring-boot-starter</artifactId>
 <version>${dubbo.version}</version>
</dependency>
-->

其中，dubbo-zookeeper-spring-boot-starter 或 dubbo-zookeeper-curator5-spring-boot-starter 负责管理 zookeeper 相关依赖。

注意

如果您不使用 Spring Boot，也可以使用以下方式管理依赖

Zookeeper

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

1 预备工作

了解 Dubbo 基本开发步骤
安装并启动 Zookeeper

2 使用说明

2.1 增加 Maven 依赖

如果项目已经启用 Zookeeper 作为注册中心，则无需增加任何额外配置。

如果未使用 Zookeeper 注册中心，则请参考为注册中心增加 Zookeeper 相关依赖。

2.2 启用 Zookeeper 配置中心

<dubbo:metadata-report address="zookeeper://127.0.0.1:2181"/>

或者

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

或者

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

或者

MetadataReportConfig metadataConfig = new MetadataReportConfig();
metadataConfig.setAddress("zookeeper://127.0.0.1:2181");

address 格式请参考 zookeeper 注册中心 - 启用配置

3 高级配置

完整配置参数请参考 metadata-report-config。

4 工作原理

4.1 服务运维元数据

Zookeeper 基于树形结构进行数据存储，它的元数据信息位于以下节点:

Provider: /dubbo/metadata/{interface name}/{version}/{group}/provider/{application name}
Consumer: /dubbo/metadata/{interface name}/{version}/{group}/consumer/{application name}

当 version 或者 group 不存在时，version 路径和 group 路径会取消，路径如下:

Provider: /dubbo/metadata/{interface name}/provider/{application name}
Consumer: /dubbo/metadata/{interface name}/consumer/{application name}

通过 zkCli get 操作查看数据.

快速部署Dubbo应用

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

在上一篇文章中，我们学习了如何开发基于 Spring Boot 的 Dubbo 应用。接下来，我们将学习部署这个 Dubbo 应用。

本文将以 Kubernetes 集群作为基础环境来讲解 Dubbo 应用的部署，部署架构如下图所示：

注意

在实际使用中可能会选择不同的部署环境与架构，如使用服务网格(Service Mesh)、虚拟机等多种部署模式，请参考部署文档了解更多详细内容。

部署应用

我们为您提前准备好了示例项目的镜像与部署文件，您可以使用如下命令将示例快速部署到 Kubernetes 集群（请确保在示例源码根目录执行如下命令）：

kubectl apply -f ./Kubernetes-manifests.yaml

以上命令将自动部署如下资源：

dubbo-system 命名空间
- Nacos Deployment
- Nacos Service
dubbo-quickstart 命名空间
- Quickstart Deployment
- Quickstart Service

运行以下命令，确认资源已经部署成功：

kubectl get services -n dubbo-system

kubectl get services -n dubbo-quickstart

访问应用

部署成功后，可以通过以下方式检查应用状态。

执行以下命令进行本地端口映射：

为服务调用指定 timeout 超时时间

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

为 RPC 调用设置超时时间可以提升集群整体稳定性，避免无限等待响应结果导致的资源占用（比如大量长期无响应的请求占用线程池等）。在调用没有响应的情况下，比如 5s 之后，Dubbo 框架就会自动终止调用等待过程（抛出 TimeoutException），释放此次调用占用的资源。

使用方式

有多种方式可以配置 rpc 调用超时时间，从粗粒度的全局默认值，到特定服务、特定方法级别的独立配置：

配置全局默认超时时间为 5s（不配置的情况下，所有服务的默认超时时间是 1s）。

dubbo:
 provider:
 timeout: 5000

在消费端，指定 DemoService 服务调用的超时时间为 5s

@DubboReference(timeout=5000)
private DemoService demoService;

在提供端，指定 DemoService 服务调用的超时时间为 5s（可作为所有消费端的默认值，如果消费端有指定则优先级更高）

@DubboService(timeout=5000)
public class DemoServiceImpl implements DemoService{}

在消费端，指定 DemoService sayHello 方法调用的超时时间为 5s

@DubboReference(methods = {@Method(name = "sayHello", timeout = 5000)})
private DemoService demoService;

在提供端，指定 DemoService sayHello 方法调用的超时时间为 5s（可作为所有消费端的默认值，如果消费端有指定则优先级更高）

@DubboService(methods = {@Method(name = "sayHello", timeout = 5000)})
public class DemoServiceImpl implements DemoService{}

以上配置形式的优先级从高到低依次为：方法级别配置 > 服务级别配置 > 全局配置 > 默认值。

Deadline 机制

我们来分析一下以上调用链路以及可能出现的超时情况：

A 调用 B 设置了超时时间 5s，因此 B -> C -> D 总计耗时不应该超过 5s，否则 A 就会收到超时异常
在任何情形下，只要 A 等待 5s 没有收到响应，整个调用链路就可以被终止了（如果此时 C 正在运行，则 C -> D 就没有发起的意义了）
理论上 B -> C、C -> D 都有自己独立的超时时间设置，超时计时也是独立计算的，它们不知道 A 作为调用发起方是否超时

在 Dubbo 框架中，A -> B 的调用就像一个开关，一旦启动，在任何情形下整个 A -> B -> C -> D 调用链路都会被完整执行下去，即便调用方 A 已经超时，后续的调用动作仍会继续。这在一些场景下是没有意义的，尤其是链路较长的情况下会带来不必要的资源消耗，deadline 就是设计用来解决这个问题，通过在调用链路中传递 deadline（deadline初始值等于超时时间，随着时间流逝而减少）可以确保调用链路只在有效期内执行，deadline 消耗殆尽之后，调用链路中其他尚未执行的任务将被取消。

防痴呆设计

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

最近有点痴呆，因为解决了太多的痴呆问题。服务框架实施面越来越广，已有 50 多个项目在使用，每天都要去帮应用查问题，来来回回，发现大部分都是配置错误，或者重复的文件或类，或者网络不通等，所以准备在新版本中加入防痴呆设计。估且这么叫吧，可能很简单，但对排错速度还是有点帮助，希望能抛砖引玉，也希望大家多给力，想出更多的防范措施共享出来。

检查重复的jar包

最痴呆的问题，就是有多个版本的相同jar包，会出现新版本的 A 类，调用了旧版本的 B 类，而且和JVM加载顺序有关，问题带有偶然性，误导性，遇到这种莫名其妙的问题，最头疼，所以，第一条，先把它防住，在每个 jar 包中挑一个一定会加载的类，加上重复类检查，给个示例：

static { 
 Duplicate.checkDuplicate(Xxx.class); 
}

检查重复工具类：

public final class Duplicate { 
 
 private Duplicate() {} 
 
 public static void checkDuplicate(Class cls) { 
 checkDuplicate(cls.getName().replace('.', '/') + ".class"); 
 } 
 
 public static void checkDuplicate(String path) { 
 try { 
 // 在ClassPath搜文件 
 Enumeration urls = Thread.currentThread().getContextClassLoader().getResources(path); 
 Set files = new HashSet(); 
 while (urls.hasMoreElements()) { 
 URL url = urls.nextElement(); 
 if (url != null) { 
 String file = url.getFile(); 
 if (file != null && file.length() > 0) { 
 files.add(file); 
 } 
 } 
 } 
 // 如果有多个，就表示重复 
 if (files.size() > 1) { 
 logger.error("Duplicate class " + path + " in " + files.size() + " jar " + files); 
 } 
 } catch (Throwable e) { // 防御性容错 
 logger.error(e.getMessage(), e); 
 } 
 } 
 
}

检查重复的配置文件

配置文件加载错，也是经常碰到的问题。用户通常会和你说：“我配置的很正确啊，不信我发给你看下，但就是报错”。然后查一圈下来，原来他发过来的配置根本没加载，平台很多产品都会在 classpath 下放一个约定的配置，如果项目中有多个，通常会取JVM加载的第一个，为了不被这么低级的问题折腾，和上面的重复jar包一样，在配置加载的地方，加上：

通过动态开启访问日志跟踪服务调用情况

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

访问日志可以很好的记录某台机器在某段时间内处理的所有服务请求信息，包括请求接收时间、远端 IP、请求参数、响应结果等，运行态动态的开启访问日志对于排查问题非常有帮助。

开始之前

部署 Shop 商城项目
部署并打开 Dubbo Admin

任务详情

商城的所有用户服务都由 User 应用的 UserService 提供，通过这个任务，我们为 User 应用的某一台或几台机器开启访问日志，以便观察用户服务的整体访问情况。

动态开启访问日志

Dubbo 通过 accesslog 标记识别访问日志的开启状态，我们可以指定日志文件的输出位置，也可以单独打开某台机器的访问日志。

操作步骤

打开 Dubbo Admin 控制台
在左侧导航栏选择【服务治理】>【动态配置】
点击 “创建”，输入应用名 shop-user 并勾选 “开启访问日志”（此时访问日志将和普通日志打印在一起）。

再次访问登录页面，登录到 User 应用的任意一台机器，可以看到如下格式的访问日志。

[2022-12-30 12:36:31.15900] -> [2022-12-30 12:36:31.16000] 192.168.0.103:60943 -> 192.168.0.103:20884 - org.apache.dubbo.samples.UserService login(java.lang.String,java.lang.String) ["test",""], dubbo version: 3.2.0-beta.4-SNAPSHOT, current host: 192.168.0.103
[2022-12-30 12:36:33.95900] -> [2022-12-30 12:36:33.95900] 192.168.0.103:60943 -> 192.168.0.103:20884 - org.apache.dubbo.samples.UserService getInfo(java.lang.String) ["test"], dubbo version: 3.2.0-beta.4-SNAPSHOT, current host: 192.168.0.103
[2022-12-30 12:36:31.93500] -> [2022-12-30 12:36:34.93600] 192.168.0.103:60943 -> 192.168.0.103:20884 - org.apache.dubbo.samples.UserService getInfo(java.lang.String) ["test"], dubbo version: 3.2.0-beta.4-SNAPSHOT, current host: 192.168.0.103

规则详解

规则 key ： shop-user

服务测试

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

请参考这篇博客

Admin 服务测试功能简介

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

服务测试功能通常提供给 Dubbo 服务的开发者使用，用来对自己发布的服务进行自测。通过在 Admin 控制台上模拟真实的消费端进程，对服务提供者发起调用，并验证调用结果是否符合预期。

使用方式

准备用例

启动用例

可以参考快速开始启动一个简单的 Dubbo 服务，对于服务测试来说，只需要启动 provider 即可。
查询服务

完成服务端部署后，可以到 Admin 的 服务测试 页面查询对应的服务:

这里的信息和元数据类似，包含方法名，参数类型和返回值信息，点击右边的标签就可以进入服务测试页面

执行服务测试

服务测试页面包含了两个 json 编辑器，参数类型的信息都是以 json 格式保存。

如以下示例所示，在左侧编辑器中填入对应的参数值(本例中数类型是 String )，填写完成后点击 执行 即可对服务端发起调用，调用结果展示在右边的编辑器中。

如果调用失败，会显示详细的失败原因，下面来看一下调用失败的例子：

本例中，先关掉 Dubbo 服务提供者的进程，再执行服务测试，可以看到返回的结果是找不到服务提供者的异常。和普通调用一样，业务和框架的异常都会返回在结果中，方便业务排查。

复合类型参数的填写

考虑 UserService 中的以下方法和类型：

//org.apache.dubbo.demo.api.UserService
Result getUser(String name, UserInfoDO userInfoDO);

public class UserInfoDO {
 private int id;
 private LocationDO locationDO;
 private DepartmentDO departmentDO;

 @Override
 public String toString() {
 return "UserInfoDO{" +
 "id=" + id +
 ", locationDO=" + locationDO.toString() +
 ", departmentDO=" + departmentDO.toString() +
 '}';
 }
}

public class DepartmentDO {

 private String departName;
 private LocationDO departLocation;

 @Override
 public String toString() {
 return "DepartmentDO{" +
 "departName='" + departName + '\'' +
 ", departLocation=" + departLocation.toString() +
 '}';
 }
}

public class LocationDO {
 private String address;
 private int postNum;

 @Override
 public String toString() {
 return "LocationDO{" +
 "address='" + address + '\'' +
 ", postNum=" + postNum +
 '}';
 }
}

参数是比较复杂的符合类型参数，服务测试的时候，会逐层展开填写每一个field的值，如下图所示：同样可以调用成功并且返回结果

服务查询和详情展示

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

服务查询是 Dubbo OPS 最基本的功能，目前支持服务，应用和 IP 三个维度的查询，并且服务和应用支持模糊查询和自动提示:

其中详情页展示了服务提供者，消费者等信息，元数据信息需要在 Dubbo 2.7 及之后的版本才会展示:

服务导出

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

1.简介

本篇文章，我们来研究一下 Dubbo 导出服务的过程。Dubbo 服务导出过程始于 Spring 容器发布刷新事件，Dubbo 在接收到事件后，会立即执行服务导出逻辑。整个逻辑大致可分为三个部分，第一部分是前置工作，主要用于检查参数，组装 URL。第二部分是导出服务，包含导出服务到本地 (JVM)，和导出服务到远程两个过程。第三部分是向注册中心注册服务，用于服务发现。本篇文章将会对这三个部分代码进行详细的分析。

2.源码分析

服务导出的入口方法是 ServiceBean 的 onApplicationEvent。onApplicationEvent 是一个事件响应方法，该方法会在收到 Spring 上下文刷新事件后执行服务导出操作。方法代码如下：

public void onApplicationEvent(ContextRefreshedEvent event) {
 // 是否有延迟导出 && 是否已导出 && 是不是已被取消导出
 if (isDelay() && !isExported() && !isUnexported()) {
 // 导出服务
 export();
 }
}

这个方法首先会根据条件决定是否导出服务，比如有些服务设置了延时导出，那么此时就不应该在此处导出。还有一些服务已经被导出了，或者当前服务被取消导出了，此时也不能再次导出相关服务。注意这里的 isDelay 方法，这个方法字面意思是“是否延迟导出服务”，返回 true 表示延迟导出，false 表示不延迟导出。但是该方法真实意思却并非如此，当方法返回 true 时，表示无需延迟导出。返回 false 时，表示需要延迟导出。与字面意思恰恰相反，这个需要大家注意一下。下面我们来看一下这个方法的逻辑。

// -☆- ServiceBean
private boolean isDelay() {
 // 获取 delay
 Integer delay = getDelay();
 ProviderConfig provider = getProvider();
 if (delay == null && provider != null) {
 // 如果前面获取的 delay 为空，这里继续获取
 delay = provider.getDelay();
 }
 // 判断 delay 是否为空，或者等于 -1
 return supportedApplicationListener && (delay == null || delay == -1);
}

暂时忽略 supportedApplicationListener 这个条件，当 delay 为空，或者等于-1时，该方法返回 true，而不是 false。这个方法的返回值让人有点困惑。该方法目前已被重构，详细请参考 dubbo #2686。

服务管理命令

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

服务管理功能提供了一系列的命令对 Dubbo 服务进行管理。

服务管理

ls 命令

列出消费者和提供者

dubbo>ls
As Provider side:
+------------------------------------------------------------------------+---------------------+
| Provider Service Name | PUB |
+------------------------------------------------------------------------+---------------------+
|DubboInternal - UserRead/org.apache.dubbo.metadata.MetadataService:1.0.0| |
+------------------------------------------------------------------------+---------------------+
| com.dubbo.dubbointegration.UserReadService |nacos-A(Y)/nacos-I(Y)|
+------------------------------------------------------------------------+---------------------+
As Consumer side:
+-----------------------------------------+-----------------+
| Consumer Service Name | NUM |
+-----------------------------------------+-----------------+
|com.dubbo.dubbointegration.BackendService|nacos-AF(I-2,A-2)|
+-----------------------------------------+-----------------+

列出 dubbo 的所提供的服务和消费的服务，以及消费的服务地址数。

注意

带有 DubboInternal 前缀的服务是 Dubbo 内置的服务，默认不向注册中心中注册。
服务发布状态中的 nacos-A(Y) 第一部分是对应的注册中心名，第二部分是注册的模式（A 代表应用级地址注册，I 代表接口级地址注册），第三部分代表对应模式是否已经注册
服务订阅状态中的 nacos-AF(I-2,A-2) 第一部分是对应的注册中心名，第二部分是订阅的模式（AF 代表双订阅模式，FA 代表仅应用级订阅，FI 代表仅接口级订阅），第三部分中前半部分代表地址模式来源（A 代表应用级地址，I 代表接口级地址）后半部分代表对应的地址数量

上线

online 命令

Online 上线服务命令

部署 Dubbo 应用到虚拟机环境

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

这种模式将 Dubbo Service 与 Kubernetes Service 概念映射起来，不再需要 Nacos 等传统注册中心，而是由 Kubernetes APISERVER 承担注册中心指责。

安装 Control Plane

在这个模式下，我们需要安装 dubbo-control-plane

这里是要用 istio 配合一起工作（提供xds推送能力），还是dubbo-control-plane自己实现xds server？

dubboctl manifests install --profile=control-plane

部署应用

打包镜像

定义 YAML

请查看 dubbo-samples 了解示例

kind: service

kind: deployment

优雅上下线

配置 probe 配置 pre-stop

观测服务状态

与 Service Mesh 的区别

特性说明

Pod 的生命周期与服务调度息息相关，通过对 Kubernetes 官方探针的实现，能够使 Dubbo3 乃至整个应用的生命周期与 Pod 的生命周期，在 Pod 的整个生命周期中，影响到 Pod 的就只有健康检查这一部分, 我们可以通过配置 liveness probe（存活探针）和 readiness probe（可读性探针）来影响容器的生命周期。

通过 Dubbo3 的 SPI 机制，在内部实现多种“探针”，基于 Dubbo3 QOS 运维模块的 HTTP 服务，使容器探针能够获取到应用内对应探针的状态。另外，SPI 的实现机制也利于用户自行拓展内部“探针”，使整个应用的生命周期更有效的进行管控。

服务治理

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

流量管控

在地址发现和负载均衡机制之外，Dubbo 丰富的流量管控规则可以控制服务间的流量走向和 API 调用，基于这些规则可以实现在运行期动态的调整服务行为如超时时间、重试次数、限流参数等，通过控制流量分布可以实现 A/B 测试、金丝雀发布、多版本按比例流量分配、条件匹配路由、黑白名单等，提高系统稳定性。

Dubbo 流量管控能解决哪些问题

场景一：搭建多套独立的逻辑测试环境。

场景二：搭建一套完全隔离的线上灰度环境用来部署新版本服务。

场景三：金丝雀发布

场景四：同区域优先。当应用部署在多个不同机房/区域的时候，优先调用同机房/区域的服务提供者，避免了跨区域带来的网络延时，从而减少了调用的响应时间。

除了以上几个典型场景，我们还可以基于 Dubbo 支持的流量管控规则实现微服务场景中更丰富的流量管控，如：

动态调整超时时间
服务重试
访问日志
同区域优先
灰度环境隔离
参数路由
按权重比例分流
金丝雀发布
服务降级
实例临时拉黑
指定机器导流

可以在流量管理任务中了解以上实践场景细节。背后的规则定义与工作原理请参见 Dubbo 流量管控规则设计与定义。。

微服务生态

围绕 Dubbo 我们构建了完善的微服务治理生态，对于绝大多数服务治理需求，通过简单几行配置即可开启。对于官方尚未适配的组件或者用户内部系统，也可以通过 Dubbo 扩展机制轻松适配。

可视化控制台

Dubbo Admin 是 Dubbo 官方提供的可视化 Web 交互控制台，基于 Admin 你可以实时监测集群流量、服务部署状态、排查诊断问题。

安全体系

Dubbo 支持基于 TLS 的 HTTP、HTTP/2、TCP 数据传输通道，并且提供认证、鉴权策略，让开发者实现更细粒度的资源访问控制。

服务网格

基于 Dubbo 开发的服务可以透明的接入 Istio 等服务网格体系，Dubbo 支持基于 Envoy 的流量拦截方式，也支持更加轻量的 Proxyless Mesh 部署模式。

负载均衡

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

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

在集群负载均衡时，Dubbo 提供了多种均衡策略，缺省为 random 随机调用。

具体实现上，Dubbo 提供的是客户端负载均衡，即由 Consumer 通过负载均衡算法得出需要将请求提交到哪个 Provider 实例。

可以自行扩展负载均衡策略，参见：负载均衡扩展

负载均衡策略

目前 Dubbo 内置了如下负载均衡算法，用户可直接配置使用：

算法	特性	备注
RandomLoadBalance	加权随机	默认算法，默认权重相同
RoundRobinLoadBalance	加权轮询	借鉴于 Nginx 的平滑加权轮询算法，默认权重相同，
LeastActiveLoadBalance	最少活跃优先 + 加权随机	背后是能者多劳的思想
ShortestResponseLoadBalance	最短响应优先 + 加权随机	更加关注响应速度
ConsistentHashLoadBalance	一致性 Hash	确定的入参，确定的提供者，适用于有状态请求

Random

加权随机，按权重设置随机概率。
在一个截面上碰撞的概率高，但调用量越大分布越均匀，而且按概率使用权重后也比较均匀，有利于动态调整提供者权重。
缺点：存在慢的提供者累积请求的问题，比如：第二台机器很慢，但没挂，当请求调到第二台时就卡在那，久而久之，所有请求都卡在调到第二台上。

RoundRobin

加权轮询，按公约后的权重设置轮询比率，循环调用节点
缺点：同样存在慢的提供者累积请求的问题。

加权轮询过程过程中，如果某节点权重过大，会存在某段时间内调用过于集中的问题。
例如 ABC 三节点有如下权重：{A: 3, B: 2, C: 1}
那么按照最原始的轮询算法，调用过程将变成：A A A B B C

对此，Dubbo 借鉴 Nginx 的平滑加权轮询算法，对此做了优化，调用过程可抽象成下表:

轮前加和权重	本轮胜者	合计权重	轮后权重（胜者减去合计权重）
起始轮	\	\	`A(0), B(0), C(0)`
`A(3), B(2), C(1)`	A	6	`A(-3), B(2), C(1)`
`A(0), B(4), C(2)`	B	6	`A(0), B(-2), C(2)`
`A(3), B(0), C(3)`	A	6	`A(-3), B(0), C(3)`
`A(0), B(2), C(4)`	C	6	`A(0), B(2), C(-2)`
`A(3), B(4), C(-1)`	B	6	`A(3), B(-2), C(-1)`
`A(6), B(0), C(0)`	A	6	`A(0), B(0), C(0)`

我们发现经过合计权重（3+2+1）轮次后，循环又回到了起点，整个过程中节点流量是平滑的，且哪怕在很短的时间周期内，概率都是按期望分布的。

负载均衡

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

背景

在集群负载均衡时，Dubbo 提供了多种均衡策略，缺省为 random 随机调用。

可以自行扩展负载均衡策略，参见：负载均衡扩展

负载均衡策略

Random LoadBalance

随机，按权重设置随机概率。
在一个截面上碰撞的概率高，但调用量越大分布越均匀，而且按概率使用权重后也比较均匀，有利于动态调整提供者权重。

RoundRobin LoadBalance

轮询，按公约后的权重设置轮询比率。
存在慢的提供者累积请求的问题，比如：第二台机器很慢，但没挂，当请求调到第二台时就卡在那，久而久之，所有请求都卡在调到第二台上。

LeastActive LoadBalance

最少活跃调用数，相同活跃数的随机，活跃数指调用前后计数差。
使慢的提供者收到更少请求，因为越慢的提供者的调用前后计数差会越大。

ConsistentHash LoadBalance

一致性 Hash，相同参数的请求总是发到同一提供者。
当某一台提供者挂时，原本发往该提供者的请求，基于虚拟节点，平摊到其它提供者，不会引起剧烈变动。
算法参见：http://en.wikipedia.org/wiki/Consistent_hashing
缺省只对第一个参数 Hash，如果要修改，请配置 <dubbo:parameter key="hash.arguments" value="0,1" />
缺省用 160 份虚拟节点，如果要修改，请配置 <dubbo:parameter key="hash.nodes" value="320" />

配置

服务端服务级别

<dubbo:service interface="..." loadbalance="roundrobin" />

客户端服务级别

<dubbo:reference interface="..." loadbalance="roundrobin" />

服务端方法级别

<dubbo:service interface="...">
 <dubbo:method name="..." loadbalance="roundrobin"/>
</dubbo:service>

客户端方法级别

<dubbo:reference interface="...">
 <dubbo:method name="..." loadbalance="roundrobin"/>
</dubbo:reference>

负载均衡

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

在集群负载均衡时，Dubbo 提供了多种均衡策略，缺省为 weighted random 基于权重的随机负载均衡策略。

具体实现上，Dubbo 提供的是客户端负载均衡，即由 Consumer 通过负载均衡算法得出需要将请求提交到哪个 Provider 实例。

负载均衡策略

目前 Dubbo 内置了如下负载均衡算法，可通过调整配置项启用。

算法	特性	备注
Weighted Random LoadBalance	加权随机	默认算法，默认权重相同
RoundRobin LoadBalance	加权轮询	借鉴于 Nginx 的平滑加权轮询算法，默认权重相同，
LeastActive LoadBalance	最少活跃优先 + 加权随机	背后是能者多劳的思想
Shortest-Response LoadBalance	最短响应优先 + 加权随机	更加关注响应速度
ConsistentHash LoadBalance	一致性哈希	确定的入参，确定的提供者，适用于有状态请求
P2C LoadBalance	Power of Two Choice	随机选择两个节点后，继续选择“连接数”较小的那个节点。
Adaptive LoadBalance	自适应负载均衡	在 P2C 算法基础上，选择二者中 load 最小的那个节点

Weighted Random

加权随机，按权重设置随机概率。
在一个截面上碰撞的概率高，但调用量越大分布越均匀，而且按概率使用权重后也比较均匀，有利于动态调整提供者权重。
缺点：存在慢的提供者累积请求的问题，比如：第二台机器很慢，但没挂，当请求调到第二台时就卡在那，久而久之，所有请求都卡在调到第二台上。

RoundRobin

加权轮询，按公约后的权重设置轮询比率，循环调用节点
缺点：同样存在慢的提供者累积请求的问题。

加权轮询过程中，如果某节点权重过大，会存在某段时间内调用过于集中的问题。例如 ABC 三节点有如下权重：{A: 3, B: 2, C: 1} 那么按照最原始的轮询算法，调用过程将变成：A A A B B C

回声测试

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

特性说明

回声测试用于检测服务是否可用，回声测试按照正常请求流程执行，能够测试整个调用是否通畅，可用于监控。执行回声测试，客户端发送一个包含特定值（如字符串）的请求。服务器应使用相同的值进行响应，从而验证请求是否已成功接收和处理。如果响应与请求不匹配，则表示服务运行不正常，应进一步调查。要求 Dubbo 服务器正在运行，并且服务器和客户端之间具有网络连接。在客户端，必须配置 Dubbo 客户端以连接到服务器，客户端将向服务器发送请求，然后服务器应返回与请求相同的响应。

使用场景

测试验证是否可以调用服务以及响应是否正确，对于在尝试在生产环境中使用服务之前验证服务特别有用。 echo 测试是验证 Dubbo 服务基本功能的一种简单有效的方法，在将服务部署到生产环境之前执行此测试非常重要，以确保服务按预期工作。

使用方式

本示例完整源码请参考 dubbo-samples-echo。

所有服务自动实现 EchoService 接口，只需将任意服务引用强制转型为 EchoService，即可使用。

如有以下 Dubbo proxy 实例：

@DubboReference
private DemoService demoService;

代码示例

EchoService echoService = (EchoService) demoService;

String status = (String) echoService.$echo("OK");

基本依赖

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

必须依赖

JDK 1.6+ ¹

缺省依赖

通过 mvn dependency:tree > dep.log 命令分析，Dubbo 缺省依赖以下三方库：

[INFO] +- com.alibaba:dubbo:jar:2.5.9-SNAPSHOT:compile
[INFO] | +- org.springframework:spring-context:jar:4.3.10.RELEASE:compile
[INFO] | +- org.javassist:javassist:jar:3.21.0-GA:compile
[INFO] | \- org.jboss.netty:netty:jar:3.2.5.Final:compile

这里所有依赖都是按照 Dubbo 缺省配置选的，这些缺省值是基于稳定性和性能考虑的。

javassist.jar ²: 如果 <dubbo:provider proxy="jdk" /> 或 <dubbo:consumer proxy="jdk" />，以及 <dubbo:application compiler="jdk" />，则不需要。
spring-context.jar ³: 如果用 ServiceConfig 和 ReferenceConfig 的 API 调用，则不需要。
netty.jar ⁴: 如果 <dubbo:protocol server="mina"/> 或 <dubbo:protocol server="grizzly"/>，则换成 mina.jar 或 grizzly.jar。如果 <protocol name="rmi"/>，则不需要。

可选依赖

以下依赖，在主动配置使用相应实现策略时用到，需自行加入依赖。

netty-all 4.0.35.Final
mina: 1.1.7
grizzly: 2.1.4
httpclient: 4.5.3
hessian_lite: 3.2.1-fixed
fastjson: 1.2.31
zookeeper: 3.4.9
jedis: 2.9.0
xmemcached: 1.3.6
hessian: 4.0.38
jetty: 6.1.26
hibernate-validator: 5.4.1.Final
zkclient: 0.2
curator: 2.12.0
cxf: 3.0.14
thrift: 0.8.0
servlet: 3.0 ⁵
validation-api: 1.1.0.GA ⁵
jcache: 1.0.0 ⁵
javax.el: 3.0.1-b08 ⁵
kryo: 4.0.1
kryo-serializers: 0.42
fst: 2.48-jdk-6
resteasy: 3.0.19.Final
tomcat-embed-core: 8.0.11
slf4j: 1.7.25
log4j: 1.2.16

理论上 Dubbo 可以只依赖 JDK，不依赖于任何三方库运行，只需配置使用 JDK 相关实现策略 ↩︎

架构

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

节点角色说明

节点	角色说明
`Provider`	暴露服务的服务提供方
`Consumer`	调用远程服务的服务消费方
`Registry`	服务注册与发现的注册中心
`Monitor`	统计服务的调用次数和调用时间的监控中心
`Container`	服务运行容器

调用关系说明

服务容器负责启动，加载，运行服务提供者。
服务提供者在启动时，向注册中心注册自己提供的服务。
服务消费者在启动时，向注册中心订阅自己所需的服务。
注册中心返回服务提供者地址列表给消费者，如果有变更，注册中心将基于长连接推送变更数据给消费者。
服务消费者，从提供者地址列表中，基于软负载均衡算法，选一台提供者进行调用，如果调用失败，再选另一台调用。
服务消费者和提供者，在内存中累计调用次数和调用时间，定时每分钟发送一次统计数据到监控中心。

Dubbo 架构具有以下几个特点，分别是连通性、健壮性、伸缩性、以及向未来架构的升级性。

连通性

注册中心负责服务地址的注册与查找，相当于目录服务，服务提供者和消费者只在启动时与注册中心交互，注册中心不转发请求，压力较小
监控中心负责统计各服务调用次数，调用时间等，统计先在内存汇总后每分钟一次发送到监控中心服务器，并以报表展示
服务提供者向注册中心注册其提供的服务，并汇报调用时间到监控中心，此时间不包含网络开销
服务消费者向注册中心获取服务提供者地址列表，并根据负载算法直接调用提供者，同时汇报调用时间到监控中心，此时间包含网络开销
注册中心，服务提供者，服务消费者三者之间均为长连接，监控中心除外
注册中心通过长连接感知服务提供者的存在，服务提供者宕机，注册中心将立即推送事件通知消费者
注册中心和监控中心全部宕机，不影响已运行的提供者和消费者，消费者在本地缓存了提供者列表
注册中心和监控中心都是可选的，服务消费者可以直连服务提供者

健壮性

监控中心宕掉不影响使用，只是丢失部分采样数据
数据库宕掉后，注册中心仍能通过缓存提供服务列表查询，但不能注册新服务
注册中心对等集群，任意一台宕掉后，将自动切换到另一台
注册中心全部宕掉后，服务提供者和服务消费者仍能通过本地缓存通讯
服务提供者无状态，任意一台宕掉后，不影响使用
服务提供者全部宕掉后，服务消费者应用将无法使用，并无限次重连等待服务提供者恢复

伸缩性

注册中心为对等集群，可动态增加机器部署实例，所有客户端将自动发现新的注册中心
服务提供者无状态，可动态增加机器部署实例，注册中心将推送新的服务提供者信息给消费者

升级性

当服务集群规模进一步扩大，带动IT治理结构进一步升级，需要实现动态部署，进行流动计算，现有分布式服务架构不会带来阻力。下图是未来可能的一种架构：

节点角色说明

节点	角色说明
`Deployer`	自动部署服务的本地代理
`Repository`	仓库用于存储服务应用发布包
`Scheduler`	调度中心基于访问压力自动增减服务提供者
`Admin`	统一管理控制台
`Registry`	服务注册与发现的注册中心
`Monitor`	统计服务的调用次数和调用时间的监控中心

健康检查

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

背景

Dubbo-go 内置了基于 triple 协议的健康检查服务，帮助用户管理和监测服务健康状态，可在此查看完整示例源码。

使用方法

框架在通过 instance 启动后会自动向框架中注册健康检查服务 grpc.health.v1.Health，用于记录并对外暴露每个triple服务的健康状态。
健康检查服务可以通过发起 http 请求检查框架中服务的状态，也可以通过客户端调用该健康检查服务，调用的接口为grpc.health.v1.Health，方法为 check。

1、通过客户端调用健康检查服务

启动 dubbo-go-samples/healthcheck/go-server 中的服务，通过下方客户端即可查看 greet.GreetService 的状态。

package main

import (
	"context"
	"dubbo.apache.org/dubbo-go/v3/client"
	_ "dubbo.apache.org/dubbo-go/v3/imports"
	health "dubbo.apache.org/dubbo-go/v3/protocol/triple/health/triple_health"
	"github.com/dubbogo/gost/log/logger"
)

func main() {
	cli, err := client.NewClient(
		client.WithClientURL("tri://127.0.0.1:20000"),
	)
	if err != nil {
		panic(err)
	}
	svc, err := health.NewHealth(cli)
	if err != nil {
		panic(err)
	}
	check, err := svc.Check(context.Background(), &health.HealthCheckRequest{Service: "greet.GreetService"})
	if err != nil {
		logger.Error(err)
	} else {
		logger.Info("greet.GreetService's health", check.String())
	}
	watch, err := svc.Watch(context.Background(), &health.HealthCheckRequest{Service: "greet.GreetService"})
	if err != nil {
		logger.Error(err)
	} else {
		if watch.Recv() {
			logger.Info("greet.GreetService's health", watch.Msg().String())
		}
	}
}

启动后会有以下输出

脚本路由规则

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

脚本路由为流量管理提供了最大的灵活性，所有流量在执行负载均衡选址之前，都会动态的执行一遍规则脚本，根据脚本执行的结果确定可用的地址子集。

脚本路由只对消费者生效且只支持应用粒度管理，因此， key 必须设置为消费者应用名；脚本语法支持多种，以 Dubbo Java SDK 为例，脚本语法支持 Javascript、Groovy、Kotlin 等，具体可参见每个语言实现的限制。

脚本路由由于可以动态加载远端代码执行，因此存在潜在的安全隐患，在启用脚本路由前，一定要确保脚本规则在安全沙箱内运行。

configVersion: v3.0
key: demo-provider
type: javascript
enabled: true
script: |
 (function route(invokers,invocation,context) {
 var result = new java.util.ArrayList(invokers.size());
 for (i = 0; i < invokers.size(); i ++) {
 if ("10.20.3.3".equals(invokers.get(i).getUrl().getHost())) {
 result.add(invokers.get(i));
 }
 }
 return result;
 } (invokers, invocation, context)); // 表示立即执行方法

ScriptRule

脚本路由规则主体。定义脚本规则生效的目标消费者应用、流量过滤脚本以及一些特定场景下的行为。

Field	Type	Description	Required
configVersion	string	The version of the script rule definition, currently available version is `v3.0`	Yes
key	string	The identifier of the target application that this rule is about to apply to.	Yes
type	string	The script language used to define `script`.	Yes
enabled	bool	Whether enable this rule or not, set `enabled:false` to disable this rule.	Yes
script	string	The script definition used to filter dubbo provider instances.	Yes
force	bool	The behaviour when the instance subset is empty after after routing. `true` means return no provider exception while `false` means ignore this rule.	No

Script

script 为脚本路由规则的主体，类型为一个具有符合结构的 string 字符串，具体取决于 type 指定的脚本语言。

Spring Boot 快速开发 Dubbo 服务

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

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

Dubbo 还提供了包括XML、API 等多种启动与接入方式，更多开发方式和配置细节可参见配置手册。

下载示例代码

完整示例代码在 dubbo-samples 中

下载源码

git clone -b master https://github.com/apache/dubbo-samples.git

cd dubbo-samples/dubbo-samples-spring-boot
ls # 查看目录结构

快速运行示例

编译 Provider 在 dubbo-samples-spring-boot 目录，进入 dubbo-samples-spring-boot-provider 目录并执行 maven 命令

cd ./dubbo-samples-spring-boot-provider
mvn clean package

运行 Provider

java -jar ./target/dubbo-samples-spring-boot-provider-1.0-SNAPSHOT.jar

编译 Consumer 进入 dubbo-samples-spring-boot-consumer 目录并执行 maven 命令

cd ../dubbo-samples-spring-boot-consumer
mvn clean package

运行 consumer

java -jar ./target/dubbo-samples-spring-boot-consumer-1.0-SNAPSHOT.jar

详细解释

定义服务接口

dubbo-samples-spring-boot-interface/DemoService.java

package org.apache.dubbo.samples.basic.api;

public interface DemoService {
 String sayHello(String name);
}

提供方实现接口并暴露服务

dubbo-samples-spring-boot-provider/DemoServiceImpl.java

扩展点加载

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

扩展点配置

来源：

Dubbo 的扩展点加载从 JDK 标准的 SPI (Service Provider Interface) 扩展点发现机制加强而来。

Dubbo 改进了 JDK 标准的 SPI 的以下问题：

JDK 标准的 SPI 会一次性实例化扩展点所有实现，如果有扩展实现初始化很耗时，但如果没用上也加载，会很浪费资源。
如果扩展点加载失败，连扩展点的名称都拿不到了。比如：JDK 标准的 ScriptEngine，通过 getName() 获取脚本类型的名称，但如果 RubyScriptEngine 因为所依赖的 jruby.jar 不存在，导致 RubyScriptEngine 类加载失败，这个失败原因被吃掉了，和 ruby 对应不起来，当用户执行 ruby 脚本时，会报不支持 ruby，而不是真正失败的原因。
增加了对扩展点 IoC 和 AOP 的支持，一个扩展点可以直接 setter 注入其它扩展点。

约定：

在扩展类的 jar 包内 ¹，放置扩展点配置文件 META-INF/dubbo/接口全限定名，内容为：配置名=扩展实现类全限定名，多个实现类用换行符分隔。

示例：

以扩展 Dubbo 的协议为例，在协议的实现 jar 包内放置文本文件：META-INF/dubbo/org.apache.dubbo.rpc.Protocol，内容为：

xxx=com.alibaba.xxx.XxxProtocol

实现类内容 ²：

package com.alibaba.xxx;
 
import org.apache.dubbo.rpc.Protocol;
 
public class XxxProtocol implements Protocol { 
 // ...
}

配置模块中的配置

Dubbo 配置模块中，扩展点均有对应配置属性或标签，通过配置指定使用哪个扩展实现。比如：

服务流量管理

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

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

流量管理

流量管理的本质是将请求根据制定好的路由规则分发到应用服务上，如下图所示：

其中：

路由规则可以有多个，不同的路由规则之间存在优先级。如：Router(1) -> Router(2) -> …… -> Router(n)
一个路由规则可以路由到多个不同的应用服务。如：Router(2) 既可以路由到 Service(1) 也可以路由到 Service(2)
多个不同的路由规则可以路由到同一个应用服务。如：Router(1) 和 Router(2) 都可以路由到 Service(2)
路由规则也可以不路由到任何应用服务。如：Router(m) 没有路由到任何一个 Service 上，所有命中 Router(m) 的请求都会因为没有对应的应用服务处理而导致报错
应用服务可以是单个的实例，也可以是一个应用集群。

Dubbo 流量管理介绍

Dubbo 提供了支持 mesh 方式的流量管理策略，可以很容易实现 A/B测试、金丝雀发布、蓝绿发布等能力。

Dubbo 将整个流量管理分成 VirtualService 和 DestinationRule 两部分。当 Consumer 接收到一个请求时，会根据 VirtualService 中定义的 DubboRoute 和 DubboRouteDetail 匹配到对应的 DubboDestination 中的 subnet，最后根据 DestinationRule 中配置的 subnet 信息中的 labels 找到对应需要具体路由的 Provider 集群。其中：

VirtualService 主要处理入站流量分流的规则，支持服务级别和方法级别的分流。
DubboRoute 主要解决服务级别的分流问题。同时，还提供的重试机制、超时、故障注入、镜像流量等能力。
DubboRouteDetail 主要解决某个服务中方法级别的分流问题。支持方法名、方法参数、参数个数、参数类型、header 等各种维度的分流能力。同时也支持方法级的重试机制、超时、故障注入、镜像流量等能力。
DubboDestination 用来描述路由流量的目标地址，支持 host、port、subnet 等方式。
DestinationRule 主要处理目标地址规则，可以通过 hosts、subnet 等方式关联到 Provider 集群。同时可以通过 trafficPolicy 来实现负载均衡。

这种设计理念很好的解决流量分流和目标地址之间的耦合问题。不仅将配置规则进行了简化有效避免配置冗余的问题，还支持 VirtualService 和 DestinationRule 的任意组合，可以非常灵活的支持各种业务使用场景。

流量管理

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

在本节中，我们将延续上一个任务【在 Istio 环境部署 Dubbo-go 应用】。

在之前的任务中，我们在集群中部署了一组 Dubbo-go Server和 Client 端应用，验证了服务发现和调用成功。在本节中，我们将创建新版本的 Server 端应用。通过配置 VirtualService 和 DestinationRule ，实现路由管理，和流量转移能力

1. 准备工作

dubbo-go cli 工具和依赖工具已安装、grpc_cli (如需本地调试)。
docker、helm、kubectl 环境已安装。（arm 机器需支持 docker buildx）
任务【在 Istio 环境部署 Dubbo-go 应用】已完成

2. 开发多版本Dubbo-go 应用。

2.1 使用 dubbogo-cli 创建另一个项目模板

$ dubbogo-cli newApp .

2.2 开发和部署客户端 Dubbo-go 应用 v2：

编写业务逻辑

修改 package/service/service.go 的实现方法，返回版本号为 v2.0.0

func (s *GreeterServerImpl) SayHello(ctx context.Context, in *api.HelloRequest) (*api.User, error) {
	return &api.User{Name: "Hello " + in.Name, Id: "v2.0.0"}, nil
}

修改如下配置文件，使用xds协议作为注册中心，加载名为 GreeterServerImpl 的服务结构。

conf/dubbogo.yaml

dubbo:
 registries:
 xds:
 protocol: xds
 address: istiod.istio-system.svc.cluster.local:15010
 protocols:
 triple:
 name: tri
 port: 20000
 provider:
 services:
 GreeterServerImpl:
 interface: "" # read from stub

至此，应用开发完成。

多实例相关的模型与概念定义

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

Dubbo 架构

JVM —— 虚拟机层目的：Dubbo 框架之间完全隔离（端口不能复用）

Dubbo Framework —— 框架层目的：将需要全局缓存的进行复用（端口、序列化等）

Application —— 应用层目的：隔离应用之间的信息，包括注册中心、配置中心、元数据中心

Services —— 模块层目的：提供热加载能力，可以按 ClassLoader、Spring Context 进行隔离上下文

Dubbo 概念对齐

DubboBoorstrap
1. 需要拆分 export/refer services、ServiceInstance、Metadata/Config 等 Client
ConfigManager
1. 需要拆分应用级配置信息、模块级配置信息
ApplicationModel
1. 实际存储应用层信息，持有到 ConfigManager 应用级配置信息的引用
ConsumerModel
1. 实际存储接口信息，由 ModuleModel 持有引用
ProviderModel
1. 实际存储接口信息，由 ModuleModel 持有引用
ExtensionLoader
1. 需要根据不同层级 load 出不同的实例对象
Registry
1. 应用级别共享，需要确保多实例订阅正常（考虑单元化场景）
Router / Filter
1. 模块级别共享
Protocol / Remoting
1. 框架级别共享，复用 IO，多应用间贡献
Metadata
应用级别共享，考虑应用级服务发现
QoS
框架级别共享，与 IO 有关
Serialization
框架级别共享，与 IO 有关
ConfigCenter
应用级别贡献
ModuleModel（新）
实际存储模块层信息，持有接口级信息
FrameworkModel（新）
实际存储框架层信息

配置存储梳理

FrameworkModel

Qos、Protocol、Remoting、Serialization、ExtensionLoader

其他问题？

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

Proxyless 模式是指 Dubbo 直接与 Istiod 通信，通过 xDS 协议实现服务发现和服务治理等能力。本示例中将通过一个简单的示例来演示如何使用 Proxyless 模式。

示例地址

代码架构

本小节中主要介绍本文所使用的示例的代码架构，通过模仿本示例中的相关配置改造已有的项目代码可以使已有的项目快速跑在 Proxyless Mesh 模式下。

1. 接口定义

为了示例足够简单，这里使用了一个简单的接口定义，仅对参数做拼接进行返回。

public interface GreetingService {
 String sayHello(String name);
}

2. 接口实现

@DubboService(version = "1.0.0")
public class AnnotatedGreetingService implements GreetingService {
 @Override
 public String sayHello(String name) {
 System.out.println("greeting service received: " + name);
 return "hello, " + name + "! from host: " + NetUtils.getLocalHost();
 }
}

3. 客户端订阅方式

由于原生 xDS 协议无法支持获取从接口到应用名的映射，因此需要配置 providedBy 参数来标记此服务来自哪个应用。

未来我们将基于 Dubbo Mesh 的控制面实现自动的服务映射关系获取，届时将不需要独立配置参数即可将 Dubbo 运行在 Mesh 体系下，敬请期待。

@Component("annotatedConsumer")
public class GreetingServiceConsumer {
 @DubboReference(version = "1.0.0", providedBy = "dubbo-samples-xds-provider")
 private GreetingService greetingService;
 public String doSayHello(String name) {
 return greetingService.sayHello(name);
 }
}

4. 服务端配置

服务端配置注册中心为 istio 的地址，协议为 xds。

多实例启动流程与模块依赖关系

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

1、应用启动流程初始化应用配置，启动内部模块，启动其它模块。应用启动方式包括：DubboBootstrap.start(), ApplicationModel.getDeployer().start() 2、模块启动流程上图中从ModuleDeployer.start() 开始，自动初始化应用配置，启动内部模块，然后启动当前模块。模块启动方式包括：

Spring context 加载dubbo xml配置或者注解
手工启动模块：ModuleModel.getDeployer().start()

3、服务接口API方式启动 ServiceConfig.export() 或者 ReferenceConfig.get() 先自动启动module，然后执行export/refer服务接口

请求成功率低

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

在生产环境中，请求成功率与延时是最关键的指标，本文将介绍在请求成功率下降时候的排查思路。

一句话总结

全链路指标（消费端、网络、服务端、外部依赖等）分析瓶颈

排查思路

1 消费端是否正常构造请求

1.1 检查类对象是否都是可以序列化的

在使用 Dubbo 进行 RPC 进行远程调用的时候，由于是跨进程的调用，为了防止非预期的数据在网络中请求，Dubbo 遵循 Java 的序列化最佳实践会检查所有数据对象是否实现了 Serializable 接口。

以下是检查到序列化异常时的日志样例：

io.netty.handler.codec.EncoderException: java.lang.IllegalArgumentException: [Serialization Security] Serialized class org.apache.dubbo.samples.api.GreetingsService$Data has not implement Serializable interface. Current mode is strict check, will disallow to deserialize it by default. 
	at io.netty.handler.codec.MessageToByteEncoder.write(MessageToByteEncoder.java:125)
	at io.netty.channel.AbstractChannelHandlerContext.invokeWrite0(AbstractChannelHandlerContext.java:881)
	at io.netty.channel.AbstractChannelHandlerContext.invokeWrite(AbstractChannelHandlerContext.java:863)
	at io.netty.channel.AbstractChannelHandlerContext.write(AbstractChannelHandlerContext.java:968)
	at io.netty.channel.AbstractChannelHandlerContext.write(AbstractChannelHandlerContext.java:856)
	at io.netty.handler.timeout.IdleStateHandler.write(IdleStateHandler.java:304)
	at io.netty.channel.AbstractChannelHandlerContext.invokeWrite0(AbstractChannelHandlerContext.java:879)
	at io.netty.channel.AbstractChannelHandlerContext.invokeWrite(AbstractChannelHandlerContext.java:863)
	at io.netty.channel.AbstractChannelHandlerContext.write(AbstractChannelHandlerContext.java:968)
	at io.netty.channel.AbstractChannelHandlerContext.write(AbstractChannelHandlerContext.java:856)
	at io.netty.channel.ChannelDuplexHandler.write(ChannelDuplexHandler.java:115)
	at org.apache.dubbo.remoting.transport.netty4.NettyClientHandler.write(NettyClientHandler.java:88)
	at io.netty.channel.AbstractChannelHandlerContext.invokeWrite0(AbstractChannelHandlerContext.java:879)
	at io.netty.channel.AbstractChannelHandlerContext.invokeWriteAndFlush(AbstractChannelHandlerContext.java:940)
	at io.netty.channel.AbstractChannelHandlerContext$WriteTask.run(AbstractChannelHandlerContext.java:1247)
	at io.netty.util.concurrent.AbstractEventExecutor.runTask(AbstractEventExecutor.java:174)
	at io.netty.util.concurrent.AbstractEventExecutor.safeExecute(AbstractEventExecutor.java:167)
	at io.netty.util.concurrent.SingleThreadEventExecutor.runAllTasks(SingleThreadEventExecutor.java:470)
	at io.netty.channel.nio.NioEventLoop.run(NioEventLoop.java:569)
	at io.netty.util.concurrent.SingleThreadEventExecutor$4.run(SingleThreadEventExecutor.java:997)
	at io.netty.util.internal.ThreadExecutorMap$2.run(ThreadExecutorMap.java:74)
	at io.netty.util.concurrent.FastThreadLocalRunnable.run(FastThreadLocalRunnable.java:30)
	at java.lang.Thread.run(Thread.java:748)
Caused by: java.lang.IllegalArgumentException: [Serialization Security] Serialized class org.apache.dubbo.samples.api.GreetingsService$Data has not implement Serializable interface. Current mode is strict check, will disallow to deserialize it by default. 
	at org.apache.dubbo.common.utils.DefaultSerializeClassChecker.loadClass(DefaultSerializeClassChecker.java:112)
	at org.apache.dubbo.common.serialize.hessian2.Hessian2SerializerFactory.getDefaultSerializer(Hessian2SerializerFactory.java:49)
	at com.alibaba.com.caucho.hessian.io.SerializerFactory.getSerializer(SerializerFactory.java:393)
	at com.alibaba.com.caucho.hessian.io.Hessian2Output.writeObject(Hessian2Output.java:411)
	at org.apache.dubbo.common.serialize.hessian2.Hessian2ObjectOutput.writeObject(Hessian2ObjectOutput.java:99)
	at org.apache.dubbo.rpc.protocol.dubbo.DubboCodec.encodeRequestData(DubboCodec.java:208)
	at org.apache.dubbo.remoting.exchange.codec.ExchangeCodec.encodeRequest(ExchangeCodec.java:261)
	at org.apache.dubbo.remoting.exchange.codec.ExchangeCodec.encode(ExchangeCodec.java:75)
	at org.apache.dubbo.rpc.protocol.dubbo.DubboCountCodec.encode(DubboCountCodec.java:47)
	at org.apache.dubbo.remoting.transport.netty4.NettyCodecAdapter$InternalEncoder.encode(NettyCodecAdapter.java:69)
	at io.netty.handler.codec.MessageToByteEncoder.write(MessageToByteEncoder.java:107)
	... 22 more

典型的日志关键字为 has not implement Serializable interface。

请求重试

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

当一次服务调用失败时，我们可以让框架选择自动重试几次，这样能提高用户侧看到的请求成功率。在 failover cluster 模式下 dubbo-go 支持自动重试。

1.介绍

本示例演示如何在 client 端调用失败时配置重试功能，完整示例源码地址

2.如何使用重试功能

在使用 client.NewClient() 创建客户端时，可以使用 client.WithClientRetries() 方法设置重试次数。

cli, err := client.NewClient(
	client.WithClientURL("tri://127.0.0.1:20000"),
	client.WithClientRetries(3),
)

或者，可以使用 client.WithRequestTimeout() 设置服务粒度的超时时间（以下配置对服务 svc 起作用）。

svc, err := greet.NewGreetService(cli, client.WithClientRetries(5))

也可以在调用发起时，使用 client.WithCallRetries() 指定重试次数

resp, err := svc.Greet(context.Background(), &greet.GreetRequest{Name: "hello world"}, client.WithCallRetries(6))

从上往下，以上三种方式的优先级逐步提高，client.WithCallRetries() 指定的重试次数优先级最高。

3.示例解读

3.1服务端介绍

服务端proto文件

源文件路径：dubbo-go-sample/retry/proto/greet.proto

syntax = "proto3";

package greet;

option go_package = "github.com/apache/dubbo-go-samples/retry/proto;greet";

message GreetRequest {
 string name = 1;
}

message GreetResponse {
 string greeting = 1;
}

service GreetService {
 rpc Greet(GreetRequest) returns (GreetResponse) {}
 rpc GreetTimeout(GreetRequest) returns (GreetResponse) {}
}

服务端handler文件

Greet方法直接响应，GreetRetry方法用于模拟重试。

链路追踪

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

Dubbo-go 支持基于 OpenTelemetry 标准的全链路追踪埋点，同时支持通过以下 exporter 导出到不同的 tracing 后端系统。

使用方式

请注意，仅支持通过 dubbo.NewInstance 方式创建 dubbo 应用时开启 tracing 功能，也就是我们快速开始中提到的微服务应用模式，对于轻量 RPC API暂时不支持开启 tracing。

示例详解

可在此查看完整示例源码地址。

使用 dubbo.WithTracing() 开启 tracing，可以通过多个参数控制 tracing 行为：

package main

import (
 "dubbo.apache.org/dubbo-go/v3"
 _ "dubbo.apache.org/dubbo-go/v3/imports"
 "dubbo.apache.org/dubbo-go/v3/otel/trace"
)

func main() {
 instance, err := dubbo.NewInstance(
 dubbo.WithTracing(
 // add tracing options here
 trace.WithEnabled(), // enable tracing feature
 trace.WithStdoutExporter(),
 trace.WithW3cPropagator(),
 trace.WithAlwaysMode(),
 trace.WithRatioMode(), // use ratio mode
 trace.WithRatio(0.5), // sample ratio, only active when use ratio mode
 ),
 )
}

如果你在 dubbo.WithTracing() 调用中不指定任何 option 参数，则会使用默认行为：

日志管理

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

支持的日志框架

Dubbo 支持以下日志框架，用户可根据业务应用实际使用的日志框架进行配置。

第三方日志框架	优先级	说明
Log4j	最高（默认就用这个）	log4j 的直接适配，需要增加 log4j-core、log4j-api 依赖与 log4j.properties
SLF4J	次高（当前推荐）	可支持 log4j、log4j2、logback 等实现。如 logback 可添加slf4j-api、logback-classic、logback-core 依赖与 logback.xml
Log4j2	次低	log4j2 的直接适配，需要增加 log4j2-core 依赖与 log4j2.xml 配置
Common Logging(jcl就是common logging)	次低（Log4j和SLF4J在项目中均没有就用这个）	较少项目使用
JDK log	最低（最后的选择）	较少项目使用

注意

无论使用哪种日志框架，除了 Dubbo 侧配置外，还需要确保应用中加入正确的日志框架依赖和配置文件。

使用 slf4j

对于 spring boot 用户，通过在 application.yaml 或 application.properties 增加以下配置，开启 slf4j 日志：

dubbo:
 application:
 logger: slf4j

dubbo.application.logger=slf4j

除此之外，还可以使用使用 JVM 参数进行设置：

java -Ddubbo.application.logger=slf4j

使用 slf4j-log4j2 提供日志输出

增加依赖：

多实例让源码开发更复杂，学习如何正确的扩展 SPI 实现

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

本文对Dubbo 3多实例改造后编码相关变化进行一个简单的总结。

层次模型

从只有ApplicationModel，新增 ScopeModel/FrameworkModel/ModuleModel 表达多实例的层次模型。每个ScopeModel实例都会创建并绑定属于自己的重要成员：

ExtensionDirector
BeanFactory
ServiceRepository

ScopeModel 作为最基础的模型，可以在SPI/Bean/URL 等持有和传递。

SPI扩展

ExtensionScope

SPI 注解添加scope属性，标记其所属的作用域。 ExtensionScope 与层次模型对应关系：

FRAMEWORK
APPLICATION
MODULE

�

ExtensionDirector

新增ExtensionDirector用于实现多层级的spi管理及依赖注入。

ExtensionDirector spi extension 创建流程如下：

每个SPI 只能在匹配的Scope的ExtensionDirector上创建，目的是实现层级之间共享实例和正确注入依赖对象。即APPLICATION scope的SPI必定在ApplicationModel绑定的ExtensionDirector上创建，FRAMEWORK scope的SPI必定在FrameworkModel绑定的ExtensionDirector上创建。
可见性与scope作用范围相关，这里的可见性是是否能直接注入依赖。即FRAMEWORK scope的SPI可以在FRAMEWORK/APPLICATION/MODULE 都可见，而 APPLICATION scope的SPI只能在APPLICATION/MODULE 可见。
不可见的SPI需要通过上下文来获取，如可以通过URL传递ScopeModel，可以解决在FRAMEWORK spi访问 APPLICATION spi。

Scope 作用范围如下图：上层对象可以注入本层及下层的SPI/Bean对象，下层对象不能注入上层的SPI/Bean对象。

Bean托管

新增ScopeBeanFactory用于内部Bean托管，支持在多个不同模块中共享一个实例对象。 ScopeBeanFactory 也支持scope，注入规则与ExtensionDirector相同。用法请参考：FrameworkStatusReportService、RemoteMetadataServiceImpl、MetadataReportInstance

ServiceRepository

将原来的ServiceRepository拆分为3个类，分别对应3个层次的模型。 FrameworkServiceRepository �ServiceRepository ModuleServiceRepository � 将服务接口信息ProviderModel/ConsumerModel/ServiceDescriptor 注册到ModuleServiceRepository 中，同时在FrameworkServiceRepository 保存一份映射，用于根据请求查找对应的服务接口模型。

编码变化总结

1、如何获取ApplicationModel及应用数据

原方法：ApplicationModel 提供了一系列静态方法用于获取共享应用实例的数据

ApplicationModel.getConfigManager()
ApplicationModel.getEnvironment()
ApplicationModel.getServiceRepository()
ApplicationModel.getExecutorRepository()
ApplicationModel.getName()

新办法：先找到ApplicationModel实例，然后通过实例的方法获取数据

升级到应用级服务发现

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

请注意

本文档内容并不是升级 Dubbo3 必须的，您完全可以只升级框架并使用框架的服务发现默认行为。
本文档更适用于 Dubbo2 老用户，用于了解在升级到 Dubbo3 版本后，框架中的服务发现模型切换过程与工作原理。新用户请直接配置启用应用级服务发现。

对于 Dubbo2 老用户而言，在升级 Dubbo3 时有以下两个选择，而决策的考虑因素仅有一个：性能。

如果您的集群规模不算大，之前使用 Dubbo2 未遇到任何地址推送等性能问题，完全可以继续使用接口级别服务发现
如果您集群规模较大，之前使用 Dubbo2 遇到服务发现负载飙高等问题，则建议迁移到新的应用级服务发现

基于以上决策结论，请在升级 Dubbo3 框架时调整以下配置。

继续使用接口级服务发现

在升级到 Dubbo3 框架时，您需要调整应用配置如下，（仅仅是一个配置项调整，提供者应用必须配置、消费者应用可选）：

<dubbo:application name="xxx" register-mode="interface">

或者

dubbo:
 application:
 name: xxx
 register-mode: interface #表示继续使用老版本服务发现模型，可选值 interface、instance、all

或者，以上是全局默认配置，可以根据每个注册中心来单独配置

<dubbo:registry address="nacos://localhost:8848" register-mode="interface">

或者

dubbo:
 registry:
 address: nacos://localhost:8848
 register-mode: interface #表示继续使用老版本服务发现模型，可选值 interface、instance、all

启用应用级服务发现(默认)

对于老用户而言，如果要启用应用级服务发现，就需要一个平滑迁移的过程。这时需要让新升级的 Dubbo3 应用进行双注册双订阅（当前框架默认行为，因此用户无需修改任何配置，以下内容均会自行发生，注意：未来版本可能切换为应用级单注册单订阅），以确保新老服务发现模型都能兼顾。

请注意

对于新用户而言，可以直接配置 dubbo.application.register-mode=instance，即在一开始就配置仅使用应用级服务发现。

提供者端注册行为

在默认情况下，Dubbo3 框架会同时注册接口级、应用级两种服务发现地址，因此，集群中的新老应用都能够正常的发现改应用地址，并正常发起调用。如下图所示：

消费者端订阅行为

在默认情况下，Dubbo3 框架具备同时发现 Dubbo2 与 Dubbo3 地址列表的能力。在默认情况下，如果集群中存在可以消费的 Dubbo3 的地址，将自动消费 Dubbo3 的地址，如果不存在新地址则自动消费 Dubbo2 的地址（Dubbo3 提供了开关来控制这个行为），具体如下图所示：

使用 dubbogo-cli 工具

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

废弃警告

自 dubbo-go 3.1.0 版本开始，本工具不再适用。本工具已经停止维护，未来将由 dubboctl 代替，请关注社区动态了解 dubboctl 最新进展。

1. 安装

dubbogo-cli 是 Apach/dubbo-go 生态的子项目，为开发者提供便利的应用模板创建、工具安装、接口调试等功能，以提高用户的研发效率。

执行以下指令安装dubbogo-cli 至 $GOPATH/bin

go install github.com/dubbogo/dubbogo-cli@latest

2. 功能概览

dubbogo-cli 支持以下能力

应用模板创建
```
dubbogo-cli newApp .
```
在当前目录下创建应用模板
Demo 创建
```
dubbogo-cli newDemo .
```
在当前目录下创建 RPC 示例，包含一个客户端和一个服务端
编译、调试工具安装
```
dubbogo-cli install all
```
一键安装以下等工具至 $GOPATH/bin
- protoc-gen-go-triple
  
  用于 triple 协议接口编译
- imports-formatter
  
  用于整理代码 import 块。
  
  import-formatte README

查看 dubbo-go 应用注册信息

查看 Zookeeper 上面的注册信息, 获取接口及方法列表

$ dubbogo-cli show --r zookeeper --h 127.0.0.1:2181
interface: com.dubbogo.pixiu.UserService
methods: [CreateUser,GetUserByCode,GetUserByName,GetUserByNameAndAge,GetUserTimeout,UpdateUser,UpdateUserByName]

查看 Nacos 上面的注册信息【功能开发中】

使用Unix套接字连接器通信

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

本文重点讲解 Dubbo Rust Triple 协议使用Unix 套接，请先查看 Quick Start 了解 Dubbo Rust 基本使用，在此查看本文的完整示例。

1 使用 Unix 套接字连接器说明

#[cfg(any(target_os = “macos”, target_os=“unix”))] 当操作系统符合cfg配置时，unix 模块会被编译使用，否则无法使用

2 使用 client/connection 使用 Unix 套接字连接器编写逻辑

2.1 编写 Client 端

// examples/echo/src/echo/client.rs
// 使用 ClientBuilder 初始化 Client
let builder = ClientBuilder::new().with_connector("unix").with_host("unix://127.0.0.1:8888");
let mut cli = EchoClient::build(builder);

2.2 编写 Server 端

// examples/echo/src/echo/server.rs
// 通过 serverbuilder 来初始化 Server
let builder = ServerBuilder::new()
 .with_listener("unix".to_string())
 .with_service_names(vec!["grpc.examples.echo.Echo".to_string()])
 .with_addr("127.0.0.1:8888");
builder.build().serve().await.unwrap();

3 运行示例

编译

执行cargo build来编译server和client。

使用 Zookeeper 作为注册中心实现自动服务发现

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

本示例演示 Zookeeper 作为注册中心实现自动服务发现，示例基于 Spring Boot 应用展开，可在此查看完整示例代码

1 基本配置

1.1 增加 Maven 依赖

对于 Spring Boot 应用而言，可使用如下依赖：

<dependency>
 <groupId>org.apache.dubbo</groupId>
 <artifactId>dubbo-spring-boot-starter</artifactId>
 <version>3.3.0</version>
</dependency>
<!-- 仅当 Zookeeper Server 版本是 3.4.x 及以下时，使用此依赖 -->
<dependency>
 <groupId>org.apache.dubbo</groupId>
 <artifactId>dubbo-zookeeper-spring-boot-starter</artifactId>
 <version>3.3.0</version>
</dependency>
<!-- 仅当 Zookeeper Server 版本是 3.5.x 及以上时，使用此依赖
<dependency>
 <groupId>org.apache.dubbo</groupId>
 <artifactId>dubbo-zookeeper-curator5-spring-boot-starter</artifactId>
 <version>3.3.0</version>
</dependency>
-->

其中，dubbo-zookeeper-spring-boot-starter 或 dubbo-zookeeper-curator5-spring-boot-starter 负责管理 zookeeper 相关依赖。

注意

如果您不使用 Spring Boot，也可以使用以下方式管理依赖

示例消费者安装

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

安装:

git clone https://github.com/apache/dubbo.git
cd dubbo/dubbo-demo/dubbo-demo-xml
运行 dubbo-demo-xml-consumer 中的 org.apache.dubbo.demo.consumer.Application
请确保先启动 Provider，如果使用 Intellij Idea 请加上 -Djava.net.preferIPv4Stack=true

配置:

resources/spring/dubbo-consumer.xml
修改其中的dubbo:registry，替换成Provider提供的注册中心地址, 如：
<dubbo:registry address="zookeeper://127.0.0.1:2181"/>

提供者配置

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

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

基本配置

提供者配置项需要添加到 sys.config 文件 dubboerl 应用配置项里。

{dubboerl,[
	%% other config ...
	{provider,[
		{module_implements,interface_module,interface_fullname,[Options]},
		%% eg:
		{userOperator_impl,userOperator,<<"org.apache.dubbo.erlang.sample.service.facade.UserOperator">>,[Option]}
	]}
]}

ConfigName	Type	DefaultValue	Remarks
module_implements	atom()	-	The service implements module name
interface_module	atom()	-	Interface module name is transfer form java jar
interface_fullname	binary()	-	Interface full name is the java class name

Option is to be added.

提供者配置

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

基本配置

提供者配置项需要添加到 sys.config 文件 dubboerl 应用配置项里。

{dubboerl,[
	%% other config ...
	{provider,[
		{module_implements,interface_module,interface_fullname,[Options]},
		%% eg:
		{userOperator_impl,userOperator,<<"org.apache.dubbo.erlang.sample.service.facade.UserOperator">>,[Option]}
	]}
]}

ConfigName	Type	DefaultValue	Remarks
module_implements	atom()	-	The service implements module name
interface_module	atom()	-	Interface module name is transfer form java jar
interface_fullname	binary()	-	Interface full name is the java class name

Option is to be added.

提供者配置

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

基本配置

提供者配置项需要添加到 sys.config 文件 dubboerl 应用配置项里。

{dubboerl,[
	%% other config ...
	{provider,[
		{module_implements,interface_module,interface_fullname,[Options]},
		%% eg:
		{userOperator_impl,userOperator,<<"org.apache.dubbo.erlang.sample.service.facade.UserOperator">>,[Option]}
	]}
]}

ConfigName	Type	DefaultValue	Remarks
module_implements	atom()	-	The service implements module name
interface_module	atom()	-	Interface module name is transfer form java jar
interface_fullname	binary()	-	Interface full name is the java class name

Option is to be added.

通信协议

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

Dubbo-go 框架内置提供了两款协议：triple、dubbo，除此之外，框架还提供了多种协议扩展接入方式。

triple，基于 HTTP/1、HTTP/2 的高性能通信协议，100% 兼容 gRPC，支持 Unary、Streming 等通信模式；支持发布 REST 风格的 HTTP 服务。
dubbo，基于 TCP 的高性能私有通信协议，缺点是通用性较差，更适合在 Dubbo SDK 间使用；
任意协议扩展，通过扩展 protocol 可以之前任意 RPC 协议，官方生态库提供 JsonRPC、thrift 等支持。

本篇文档中，我们将介绍关于 triple 协议的使用方式、如何实现与已有 dubbo2 系统的互相调用、扩展更多协议支持等。更多原理性介绍请参考协议规范或者 dubbo java 中相关描述文档。

triple 协议

triple 协议支持使用 protobuf 和 non-protobuf 两种开发模式，我们 推荐使用 protobuf 模式开发服务。

目前我们大部分示例都是使用这个模式开发，可查看快速开始学习完整开发示例，以下是基本步骤：

先使用 protobuf 定义服务

syntax = "proto3";
package greet;
option go_package = "github.com/apache/dubbo-go-samples/helloworld/proto;greet";

message GreetRequest {
 string name = 1;
}

message GreetResponse {
 string greeting = 1;
}

service GreetService {
 rpc Greet(GreetRequest) returns (GreetResponse) {}
}

安装 protoc 插件，编译生成代码：

protoc --go_out=. --go_opt=paths=source_relative \
 --go-triple_out=. --go-triple_opt=paths=source_relative \
 proto/greet.proto

server 端发布服务

srv, err := server.NewServer(
	server.WithServerProtocol(
		protocol.WithPort(20000),
		protocol.WithTriple(),
	),
)

greet.RegisterGreetServiceHandler(srv, &GreetTripleServer{})

client 端调用服务

cli, err := client.NewClient(
	client.WithClientURL("127.0.0.1:20000"),
)

svc, err := greet.NewGreetService(cli)
resp, err := svc.Greet(context.Background(), &greet.GreetRequest{Name: "hello world"})

dubbo-java 体系互调

如果 java 和 go 都使用 triple+protobuf 模式，很明显他们是可以直接互调通信的。

网站向导

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

Apache Dubbo 的网站仓库是 https://github.com/apache/dubbo-website
网站构建完毕后，它会被自动发布到 dubbo.apache.org，您也可以通过 https://selfserve.apache.org 手动触发（需要使用 Apache 账号登陆）

给问题打标签

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

如果您正在处理一个问题，请记得给这个问题标记一个或者多个您认为有意义的标签。有了标签，其他开发人员就会很轻松地识别出问题，以便对其进行分类并跟踪进度。

对于需要编码和发版修复的 issues 和 pull requests，需要您将其标记为 milestone。

一些常用的标签：

请求帮助
- help wanted
- good first issue
优先级
- priority/blocker
- priority/high
- priority/low
- priority/normal
状态
- status/need-triage
- status/DO-NOT-MERGE
- status/READY-TO-MERGE
- status/invalid
- status/wontfix
类型
- type/bug
- type/documentation
- type/enhancement
- type/feature

新特性

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

1. Triple 协议

1.1 概述

通信层面

Triple 协议，也称为Dubbo3协议，是基于HTTP2 + gRPC协议，增加特定字段和逻辑的扩展协议，保证了和原生gRPC协议互通。在此基础之上，Triple 新协议将更原生地支持 Dubbo 服务治理能力。并支持流式RPC调用。

简单来说，可以理解为 Triple = gRPC + Dubbo
序列化

Triple 协议使用高效的PB序列化方式，并在此基础之上增加序列化协议的可扩展支持。
用户开发习惯：

Triple 服务在开发前需要预定义.proto文件，对于习惯在编码前先定义IDL的Go语言开发者带来便捷。不同于符合java编程习惯的，定义JavaClassName用于描述接口的 Dubbo-go 1.x版本。
跨语言互通性：

可与 Dubbo-Java 实现跨语言互通。

2. 应用级服务发现

2.1 简介

在服务注册阶段，服务端实例将应用级别的注册信息，主要包含从应用名到实例IP的映射注册到注册中心。在服务发现阶段，客户端实例，通过注册中心获取到需要请求的服务实例IP。进入服务自省阶段，服务自省过程为通过应用信息获取接口信息的过程。如上图，包含两种模式：

remote模式：通过元数据中心（例如 zk ）获取应用到接口元数据的映射
local模式：直接通过服务端获取应用到接口元数据的映射（通过 Dubbo 协议针对 Metadata Service 发起 RPC 调用）

经过服务自省后，客户端正式向对应实例发起调用。这样做最明显的好处是减少了注册中心的数据量，即注册中心只保存了应用级别的数据。

用户在使用 Dubbo-go 3.0的应用级服务发现能力时，可以仿照示例，直接在配置文件中配置服务自省模式和元数据中心信息，引入依赖，开启应用级别服务发现。

2.2 应用级服务发现介绍文章

应用级服务发现解析

3. Mesh 路由规则

用户可定义路由文件：

virtual_service.yaml

以及 dist_rule.yml

框架可根据路由文件针对特定的请求进行流量转发。

4. 相关文章

阿里云官方介绍文章：《Dubbo 3.0 - 开启下一代云原生微服务》

异步调用

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

Dubbo 异步调用分为 Provider 端异步调用和 Consumer 端异步两种模式。

Consumer 端异步是指发起 RPC 调用后立即返回，调用线程继续处理其他业务逻辑，当响应结果返回后通过回调函数通知消费端结果。
Provider 端异步执行将阻塞的业务从 Dubbo 内部线程池切换到业务自定义线程，避免Dubbo线程池的过度占用，有助于避免不同服务间的互相影响。

以下是消费端 consumer 异步调用的工作示例图：

Provider 端异步执行和 Consumer 端异步调用是相互独立的，你可以任意正交组合两端配置。

Consumer同步 - Provider同步
Consumer异步 - Provider同步
Consumer同步 - Provider异步
Consumer异步 - Provider异步

本文档演示的完整示例源码请参见：

Provider异步

1 使用CompletableFuture

接口定义：

public interface AsyncService {
 /**
 * 同步调用方法
 */
 String invoke(String param);
 /**
 * 异步调用方法
 */
 CompletableFuture<String> asyncInvoke(String param);
}

服务实现：

@DubboService
public class AsyncServiceImpl implements AsyncService {

 @Override
 public String invoke(String param) {
 try {
 long time = ThreadLocalRandom.current().nextLong(1000);
 Thread.sleep(time);
 StringBuilder s = new StringBuilder();
 s.append("AsyncService invoke param:").append(param).append(",sleep:").append(time);
 return s.toString();
 }
 catch (InterruptedException e) {
 Thread.currentThread().interrupt();
 }
 return null;
 }

 @Override
 public CompletableFuture<String> asyncInvoke(String param) {
 // 建议为supplyAsync提供自定义线程池
 return CompletableFuture.supplyAsync(() -> {
 try {
 // Do something
 long time = ThreadLocalRandom.current().nextLong(1000);
 Thread.sleep(time);
 StringBuilder s = new StringBuilder();
 s.append("AsyncService asyncInvoke param:").append(param).append(",sleep:").append(time);
 return s.toString();
 } catch (InterruptedException e) {
 Thread.currentThread().interrupt();
 }
 return null;
 });
 }
}

通过 return CompletableFuture.supplyAsync() ，业务执行已从 Dubbo 线程切换到业务线程，避免了对 Dubbo 线程池的阻塞。

异常类型返回值

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

1.介绍

本文档演示如何在 RPC 调用过程中处理 error 错误类型响应，可在此查看完整示例源码地址。

2.示例详解

2.1 服务端

服务端proto文件

源文件路径：dubbo-go-sample/error/proto/greet.proto

syntax = "proto3";

package greet;

option go_package = "github.com/apache/dubbo-go-samples/error/proto;greet";

message GreetRequest {
 string name = 1;
}

message GreetResponse {
 string greeting = 1;
}

service GreetService {
 rpc Greet(GreetRequest) returns (GreetResponse) {}
}

服务端handler文件

请注意，在本程序设计中，Greet方法只有接收到 name="right name" 时才会认为是正确请求，否则会返回错误。

源文件路径：dubbo-go-sample/context/go-server/main.go

package main

import (
	"context"
	"fmt"
	"github.com/pkg/errors"

	_ "dubbo.apache.org/dubbo-go/v3/imports"
	"dubbo.apache.org/dubbo-go/v3/protocol"
	"dubbo.apache.org/dubbo-go/v3/server"
	greet "github.com/apache/dubbo-go-samples/helloworld/proto"
	"github.com/dubbogo/gost/log/logger"
)

type GreetTripleServer struct {
}

func (srv *GreetTripleServer) Greet(ctx context.Context, req *greet.GreetRequest) (*greet.GreetResponse, error) {
	name := req.Name
	if name != "right name" {
		errInfo := fmt.Sprintf("name is not right: %s", name)
		logger.Error(errInfo)
		return nil, errors.New(errInfo)
	}

	resp := &greet.GreetResponse{Greeting: req.Name}
	return resp, nil
}

func main() {
	srv, err := server.NewServer(
		server.WithServerProtocol(
			protocol.WithPort(20000),
			protocol.WithTriple(),
		),
	)
	if err != nil {
		panic(err)
	}

	if err = greet.RegisterGreetServiceHandler(srv, &GreetTripleServer{}); err != nil {
		panic(err)
	}

	if err = srv.Serve(); err != nil {
		logger.Error(err)
	}
}

从 rpc 方法签名中，我们可以看到 func (srv *GreetTripleServer) Greet(ctx context.Context, req *greet.GreetRequest) (*greet.GreetResponse, error) 包含 error 返回值。

引用监听扩展

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

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

扩展说明

当有服务引用时，触发该事件。

扩展接口

org.apache.dubbo.rpc.InvokerListener

扩展配置

<!-- 引用服务监听 -->
<dubbo:reference listener="xxx,yyy" /> 
<!-- 引用服务缺省监听器 -->
<dubbo:consumer listener="xxx,yyy" />

已知扩展

org.apache.dubbo.rpc.listener.DeprecatedInvokerListener

扩展示例

Maven 项目结构：

src
 |-main
 |-java
 |-com
 |-xxx
 |-XxxInvokerListener.java (实现InvokerListener接口)
 |-resources
 |-META-INF
 |-dubbo
 |-org.apache.dubbo.rpc.InvokerListener (纯文本文件，内容为：xxx=com.xxx.XxxInvokerListener)

XxxInvokerListener.java：

package com.xxx;
 
import org.apache.dubbo.rpc.InvokerListener;
import org.apache.dubbo.rpc.Invoker;
import org.apache.dubbo.rpc.RpcException;
 
public class XxxInvokerListener implements InvokerListener {
 public void referred(Invoker<?> invoker) throws RpcException {
 // ...
 }
 public void destroyed(Invoker<?> invoker) throws RpcException {
 // ...
 }
}

META-INF/dubbo/org.apache.dubbo.rpc.InvokerListener：

引用监听扩展

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

扩展说明

当有服务引用时，触发该事件。

扩展接口

org.apache.dubbo.rpc.InvokerListener

扩展配置

<!-- 引用服务监听 -->
<dubbo:reference listener="xxx,yyy" /> 
<!-- 引用服务缺省监听器 -->
<dubbo:consumer listener="xxx,yyy" />

已知扩展

org.apache.dubbo.rpc.listener.DeprecatedInvokerListener

扩展示例

Maven 项目结构：

src
 |-main
 |-java
 |-com
 |-xxx
 |-XxxInvokerListener.java (实现InvokerListener接口)
 |-resources
 |-META-INF
 |-dubbo
 |-org.apache.dubbo.rpc.InvokerListener (纯文本文件，内容为：xxx=com.xxx.XxxInvokerListener)

XxxInvokerListener.java：

package com.xxx;
 
import org.apache.dubbo.rpc.InvokerListener;
import org.apache.dubbo.rpc.Invoker;
import org.apache.dubbo.rpc.RpcException;
 
public class XxxInvokerListener implements InvokerListener {
 public void referred(Invoker<?> invoker) throws RpcException {
 // ...
 }
 public void destroyed(Invoker<?> invoker) throws RpcException {
 // ...
 }
}

META-INF/dubbo/org.apache.dubbo.rpc.InvokerListener：

引用监听扩展

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

扩展说明

当有服务引用时，触发该事件。

扩展接口

org.apache.dubbo.rpc.InvokerListener

扩展配置

<!-- 引用服务监听 -->
<dubbo:reference listener="xxx,yyy" /> 
<!-- 引用服务缺省监听器 -->
<dubbo:consumer listener="xxx,yyy" />

已知扩展

org.apache.dubbo.rpc.listener.DeprecatedInvokerListener

扩展示例

Maven 项目结构：

src
 |-main
 |-java
 |-com
 |-xxx
 |-XxxInvokerListener.java (实现InvokerListener接口)
 |-resources
 |-META-INF
 |-dubbo
 |-org.apache.dubbo.rpc.InvokerListener (纯文本文件，内容为：xxx=com.xxx.XxxInvokerListener)

XxxInvokerListener.java：

package com.xxx;
 
import org.apache.dubbo.rpc.InvokerListener;
import org.apache.dubbo.rpc.Invoker;
import org.apache.dubbo.rpc.RpcException;
 
public class XxxInvokerListener implements InvokerListener {
 public void referred(Invoker<?> invoker) throws RpcException {
 // ...
 }
 public void destroyed(Invoker<?> invoker) throws RpcException {
 // ...
 }
}

META-INF/dubbo/org.apache.dubbo.rpc.InvokerListener：

邮件列表订阅向导

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

Apache incubator 的 Dubbo 开发者邮件列表（dev@dubbo.apache.org）已经建立，请随时订阅并参考[^1]获取更多细节。

你也可以直接查看历史邮件

下面是一个关于 Dubbo 邮件列表订阅的简短指南：

发一封邮件到 dev-subscribe@dubbo.apache.org，其内容和标题均可为空。随后，您会收到一封邮件，其内容如下：

from: dev-help@dubbo.apache.org
reply-to: dev-sc.xxxxxxx.xxxxxxxx-hello=example.com@dubbo.apache.org
to: hello@example.com
date: Sat, Feb 24, 2018 at 3:12 PM
subject: confirm subscribe to dev@dubbo.apache.org
mailed-by: apache.org

Hi! This is the ezmlm program. I'm managing the
dev@dubbo.apache.org mailing list.

I'm working for my owner, who can be reached
at dev-owner@dubbo.apache.org.

To confirm that you would like

 hello@example.com

added to the dev mailing list, please send
a short reply to this address:

 dev-sc.xxxxxxx.xxxxxxxx-hello=example.com@dubbo.apache.org

Usually, this happens when you just hit the "reply" button.
If this does not work, simply copy the address and paste it into
the "To:" field of a new message.

or click here:
 mailto:dev-sc.xxxxxxx.xxxxxxxx-hello=example.com@dubbo.apache.org

...

直接回复邮件，其内容和标题仍然可以为空，随后，您将再次收到一封邮件，其内容如下：

from: dev-help@dubbo.apache.org
to: hello@example.com
date: Sat, Feb 24, 2018 at 3:14 PM
subject: WELCOME to dev@dubbo.apache.org
mailed-by: apache.org

Hi! This is the ezmlm program. I'm managing the
dev@dubbo.apache.org mailing list.

I'm working for my owner, who can be reached
at dev-owner@dubbo.apache.org.

Acknowledgment: I have added the address

 hello@example.com

to the dev mailing list.

Welcome to dev@dubbo.apache.org!

Please save this message so that you know the address you are
subscribed under, in case you later want to unsubscribe or change your
subscription address.

...

到此，邮件列表订阅完毕，从现在开始，您将收到很多发送到该邮件列表的邮件，如果您有更多的问题，只需发送邮件到dev@dubbo.apache.org，就会有人回答您的问题。

远程配置文件

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

Dubbo 框架支持将配置文件 ‘dubbogo.yaml’ 的内容预先放入配置中心，再通过远程加载的方式与本地配置合并，以此实现一些配置的动态和集中式管理。

注意

凡是正确配置了config-center 地址的应用，都会优先从配置中心加载整个配置文件。

可在此查看完整示例源码地址，本文使用 zookeeper 演示，nacos 使用方法类似，并且在以上地址中有具体源码示例。

启用配置中心

在 dubbo-go 应用通过 dubbo.WithConfigCenter() 启用配置中心：

ins, err := dubbo.NewInstance(
 dubbo.WithConfigCenter(
 	config_center.WithZookeeper(),
 	config_center.WithDataID("dubbo-go-samples-configcenter-zookeeper-server"),
 	config_center.WithAddress("127.0.0.1:2181"),
 	config_center.WithGroup("dubbogo"),
	),
)
if err != nil {
 panic(err)
}

在运行应用之前，提前将以下配置写入 zookeeper 集群，写入路径为 /dubbo/config/dubbogo/dubbo-go-samples-configcenter-zookeeper-server：

dubbo:
 registries:
 demoZK:
 protocol: zookeeper
 timeout: 3s
 address: '127.0.0.1:2181'
 protocols:
 triple:
 name: tri
 port: 20000

启动服务端并注册服务

srv, err := ins.NewServer()
if err != nil {
 panic(err)
}

if err := greet.RegisterGreetServiceHandler(srv, &GreetTripleServer{}); err != nil {
 panic(err)
}

if err := srv.Serve(); err != nil {
 logger.Error(err)
}

可以发现，应用已经读取了远端的 dubbogo.yml 文件，并连接到文件中配置的注册中心地址、协议及端口配置。

注册中心安全

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

Dubbo 支持注册中心的扩展，理论上用户可以基于该扩展机制启用任意的注册中心，这带来了极大的灵活的，但同时也要意识到其中潜藏的安全性风险。

Dubbo 2.7 官方版本提供的注册中心有如下几种：

Zookeeper
Redis
Nacos
Etcd
Consul
……

从 Dubbo 3.0 开始默认仅提供以下注册中心支持：

Zookeeper
Nacos

对于注册中心，Dubbo 只能完全信任其推送的数据，因此如果注册中心存在安全漏洞，可能会导致 Dubbo 服务被恶意注册或者是被恶意推送数据，从而导致服务被攻击。因此为了保证注册中心的安全性，Dubbo 官方建议您：

开启注册中心的鉴权机制，如 Zookeeper 的 ACL 机制、Nacos 的用户名密码机制等
避免将注册中心暴露在公网环境下，尽量将注册中心部署在可信内网环境下

自适应限流

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

自适应限流的设计与实现思路请参考 Dubbo 自适应限流功能。自适应限流能够确保分布式系统稳定性和可靠性，例如在服务提供商资源有限且多变的场景下。

使用场景

服务降级预防：当服务提供者因资源耗尽而性能下降时，使用自适应限流暂时减少其接受的请求数直至恢复正常。
峰值流量处理：当服务流量突然激增时，自适应流量限制可以通过动态减少接受的请求数量来帮助防止服务过载。
不可预测流量处理：服务提供商可能会遇到不可预测的流量，第三方应用程序使用服务时可能会偶尔产生流量，自适应流量限制可以根据当前系统负载调整允许的最大并发请求数并防止过载。

使用方式

设置方法与静态的最大并发值设置类似，只需在服务端设置 flowcontrol 参数即可，可选值有以下两种：

heuristicSmoothingFlowControl。当服务端收到一个请求时，首先判断CPU的使用率是否超过50%。如果没有超过50%，则接受这个请求进行处理。如果超过50%，说明当前的负载较高，便从 HeuristicSmoothingFlowControl 算法中获得当前的 maxConcurrency 值。如果当前正在处理的请求数量超过了 maxConcurrency，则拒绝该请求。
autoConcurrencyLimiter。与 HeuristicSmoothingFlowControl 的最大区别是，AutoConcurrencyLimiter 是基于窗口的，每当窗口内积累了一定量的采样数据时，才利用窗口内的数据来更新得到 maxConcurrency，其次，利用exploreRatio来对剩余的容量进行探索。

在确保服务端存在多个节点，并且消费端开启重试策略的前提下，限流功能才能更好的发挥作用。

示例一：使用 heuristicSmoothingFlowControl 自适应限流算法

dubbo.provider.flowcontrol=heuristicSmoothingFlowControl

<dubbo:provider flowcontrol="heuristicSmoothingFlowControl" />

示例二：使用 autoConcurrencyLimiter 自适应限流算法

dubbo.provider.flowcontrol=autoConcurrencyLimiter

<dubbo:provider flowcontrol="autoConcurrencyLimiter" />

示例三：设置服务粒度的 heuristicSmoothingFlowControl 自适应限流

<dubbo:service interface="com.foo.BarService" flowcontrol="heuristicSmoothingFlowControl" />

指标埋点

Mon, 20 Feb 2023 00:00:00 +0000

概述

1. 指标接入说明

2. 指标体系设计

Dubbo的指标体系，总共涉及三块，指标收集、本地聚合、指标推送

指标收集：将Dubbo内部需要监控的指标推送至统一的Collector中进行存储
本地聚合：指标收集获取的均为基础指标，而一些分位数指标则需通过本地聚合计算得出
指标推送：收集和聚合后的指标通过一定的方式推送至第三方服务器，目前只涉及Prometheus

3. 结构设计

移除原来与 Metrics 相关的类
创建新模块 dubbo-metrics/dubbo-metrics-api、dubbo-metrics/dubbo-metrics-prometheus，MetricsConfig 作为该模块的配置类
使用micrometer，在Collector中使用基本类型代表指标，如Long、Double等，并在dubbo-metrics-api中引入micrometer，由micrometer对内部指标进行转换

4. 数据流转

5. 目标

指标接口将提供一个 MetricsService，该 Service 不仅提供柔性服务所的接口级数据，也提供所有指标的查询方式，其中方法级指标的查询的接口可按如下方式声明

public interface MetricsService {

 /**
 * Default {@link MetricsService} extension name.
 */
 String DEFAULT_EXTENSION_NAME = "default";

 /**
 * The contract version of {@link MetricsService}, the future update must make sure compatible.
 */
 String VERSION = "1.0.0";

 /**
 * Get metrics by prefixes
 *
 * @param categories categories
 * @return metrics - key=MetricCategory value=MetricsEntityList
 */
 Map<MetricsCategory, List<MetricsEntity>> getMetricsByCategories(List<MetricsCategory> categories);

 /**
 * Get metrics by interface and prefixes
 *
 * @param serviceUniqueName serviceUniqueName (eg.group/interfaceName:version)
 * @param categories categories
 * @return metrics - key=MetricCategory value=MetricsEntityList
 */
 Map<MetricsCategory, List<MetricsEntity>> getMetricsByCategories(String serviceUniqueName, List<MetricsCategory> categories);

 /**
 * Get metrics by interface、method and prefixes
 *
 * @param serviceUniqueName serviceUniqueName (eg.group/interfaceName:version)
 * @param methodName methodName
 * @param parameterTypes method parameter types
 * @param categories categories
 * @return metrics - key=MetricCategory value=MetricsEntityList
 */
 Map<MetricsCategory, List<MetricsEntity>> getMetricsByCategories(String serviceUniqueName, String methodName, Class<?>[] parameterTypes, List<MetricsCategory> categories);
}

其中 MetricsCategory 设计如下:

店小蜜升级 Triple 协议

Sun, 15 Jan 2023 00:00:00 +0000

前言

阿里云-达摩院-云小蜜对话机器人产品基于深度机器学习技术、自然语言理解技术和对话管理技术，为企业提供多引擎、多渠道、多模态的对话机器人服务。17年云小蜜对话机器人在公共云开始公测，同期在混合云场景也不断拓展。为了同时保证公共云、混合云发版效率和稳定性，权衡再三我们采用了1-2个月一个大版本迭代。经过几年发展，为了更好支撑业务发展，架构升级、重构总是一个绕不过去的坎，为了保证稳定性每次公共云发版研发同学都要做两件事：

1. 梳理各个模块相较线上版本接口依赖变化情况，决定十几个应用的上线顺序、每批次发布比例；
2. 模拟演练上述1产出的发布顺序，保证后端服务平滑升级，客户无感知；

上述 1、2 动作每次都需要 2-3 周左右的时间梳理、集中演练，但是也只能保证开放的PaaS API平滑更新；

控制台服务因为需要前端、API、后端保持版本一致才能做到体验无损（如果每次迭代统一升级API版本开发、协同成本又会非常大），权衡之下之前都是流量低谷期上线，尽量缩短发布时间，避免部分控制台模块偶发报错带来业务问题。针对上面问题，很早之前就考虑过用蓝绿发布、灰度等手段解决，但是无奈之前对话机器人在阿里云内部业务区域，该不再允许普通云产品扩容，没有冗余的机器，流量治理完全没法做。

迁移阿里云云上

带着上面的问题，终于迎来的 2021 年 9 月份，云小蜜将业务迁移至阿里云云上。

Dubbo3 的实践

“当时印象最深的就是这张图，虽然当时不知道中间件团队具体要做什么事情，但是记住了两个关键词：三位一体、红利。没想到在2021年底，真真切切享受到了这个红利。”

云小蜜使用的是集团内部的HSF服务框架，需要迁移至阿里云云上，并且存在阿里云云上与阿里内部业务域的互通、互相治理的诉求。云小蜜的公共服务部署在公有云VPC，部分依赖的数据服务部署在内部，内部与云上服务存在RPC互调的诉求，其实属于混合云的典型场景。简单整理了下他们的核心诉求，概括起来有以下三点吧：希望尽可能采用开源方案，方便后续业务推广；在网络通信层面需要保障安全性；对于业务升级改造来说需要做到低成本。

在此场景下，经过许多讨论与探索，方案也敲定了下来

全链路升级至开源 Dubbo3.0，云原生网关默认支持Dubbo3.0，实现透明转发，网关转发RT小于1ms
利用 Dubbo3.0 支持HTTP2特性，云原生网关之间采用 mTLS 保障安全
利用云原生网关默认支持多种注册中心的能力，实现跨域服务发现对用户透明，业务侧无需做任何额外改动
业务侧升级SDK到支持 Dubbo3.0，配置发布 Triple 服务即可，无需额外改动

解决了互通、服务注册发现的问题之后，就是开始看如何进行服务治理方案了

阿里云云上流量治理

迁移至阿里云云上之后，流量控制方案有非常多，比如集团内部的全链路方案、集团内单元化方案等等。

设计目标和原则

要引入一套流量隔离方案，上线过程中，新、旧两个版本服务同时存在时，流量能保证在同一个版本的“集群”里流转，这样就能解决重构带来的内部接口不兼容问题。
要解决上线过程中控制台的平滑性问题，避免前端、后端、API更新不一致带来的问题。
无上线需求的应用，可以不参与上线。
资源消耗要尽量少，毕竟做产品最终还是要考虑成本和利润。

方案选型

集团内部的全链路方案：目前不支持阿里云云上
集团内单元化方案：主要解决业务规模、容灾等问题，和我们碰到的问题不一样
搭建独立集群，版本迭代时切集群：成本太大
自建：在同一个集群隔离新、老服务，保证同一个用户的流量只在同版本服务内流转

以RPC为例：

方案一：通过开发保证，当接口不兼容升级时，强制要求升级HSF version，并行提供两个版本的服务；缺点是一个服务变更，关联使用方都要变更，协同成本特别大，并且为了保持平滑，新老接口要同时提供服务，维护成本也比较高
方案二：给服务（机器）按版本打标，通过RPC框架的路由规则，保证流量优先在同版本内流转

全链路灰度方案

就当1、2、3、4都觉得不完美，一边调研一边准备自建方案5的时候，兜兜绕绕拿到了阿里云 MSE 微服务治理团队《20分钟获得同款企业级全链路灰度能力》，方案中思路和准备自建的思路完全一致，也是利用了RPC框架的路由策略实现的流量治理，并且实现了产品化（微服务引擎-微服务治理中心），同时，聊了两次后得到几个“支持”，以及几个“后续可以支持”后，好像很多事情变得简单了…

从上图可以看到，各个应用均需要搭建基线(base)环境和灰度(gray)环境，除了流量入口-业务网关以外，下游各个业务模块按需部署灰度（gray）环境，如果某次上线某模块没有变更则无需部署。

各个中间件的治理方案

Mysql、ElasticSearch：持久化或半持久化数据，由业务模块自身保证数据结构兼容升级；
Redis：由于对话产品会有多轮问答场景，问答上下文是在Redis里，如果不兼容则上线会导致会话过程中的C端用户受影响，因此目前Redis由业务模块自身保证数据结构兼容升级；
配置中心：基线(base)环境、灰度(gray)环境维护两套全量配置会带来较大工作量，为了避免人工保证数据一致性成本，基线(base)环境监听dataId，灰度(gray)环境监听gray.dataId如果未配置gray.dataId则自动监听dataId；（云小蜜因为在18年做混合云项目为了保证混合云、公共云使用一套业务代码，建立了中间件适配层，本能力是在适配层实现）
RPC服务：使用阿里云 one agent 基于Java Agent技术利用Dubbo框架的路由规则实现，无需修改业务代码；

应用只需要加一点配置：

瓜子二手车 Dubbo 实践

Sun, 15 Jan 2023 00:00:00 +0000

前言

随着瓜子业务的不断发展，系统规模在逐渐扩大，目前在瓜子的私有云上已经运行着数百个dubbo应用，上千个dubbo实例。瓜子各部门业务迅速发展，版本没有来得及统一，各个部门都有自己的用法。随着第二机房的建设，dubbo版本统一的需求变得越发迫切。几个月前，公司发生了一次与dubbo相关的生产事故，成为了公司dubbo版本升级的诱因。

接下来，我会从这次事故开始，讲讲我们这段时间所做的dubbo版本升级的历程以及dubbo后续多机房的方案。

一、Ephermal节点未及时删除导致provider不能恢复注册的问题修复

事故背景

在生产环境，瓜子内部各业务线共用一套zookeeper集群作为dubbo的注册中心。2019年9月份，机房的一台交换机发生故障，导致zookeeper集群出现了几分钟的网络波动。在zookeeper集群恢复后，正常情况下dubbo的provider应该会很快重新注册到zookeeper上，但有一小部分的provider很长一段时间没有重新注册到zookeeper上，直到手动重启应用后才恢复注册。

排查过程

首先，我们统计了出现这种现象的dubbo服务的版本分布情况，发现在大多数的dubbo版本中都存在这种问题，且发生问题的服务比例相对较低，在github中我们也未找到相关问题的issues。因此，推断这是一个尚未修复的且在网络波动情况的场景下偶现的问题。

接着，我们便将出现问题的应用日志、zookeeper日志与dubbo代码逻辑进行相互印证。在应用日志中，应用重连zookeeper成功后provider立刻进行了重新注册，之后便没有任何日志打印。而在zookeeper日志中，注册节点被删除后，并没有重新创建注册节点。对应到dubbo的代码中，只有在FailbackRegistry.register(url)的doRegister(url)执行成功或线程被挂起的情况下，才能与日志中的情况相吻合。

 public void register(URL url) {
 super.register(url);
 failedRegistered.remove(url);
 failedUnregistered.remove(url);
 try {
 // Sending a registration request to the server side
 doRegister(url);
 } catch (Exception e) {
 Throwable t = e;

 // If the startup detection is opened, the Exception is thrown directly.
 boolean check = getUrl().getParameter(Constants.CHECK_KEY, true)
 && url.getParameter(Constants.CHECK_KEY, true)
 && !Constants.CONSUMER_PROTOCOL.equals(url.getProtocol());
 boolean skipFailback = t instanceof SkipFailbackWrapperException;
 if (check || skipFailback) {
 if (skipFailback) {
 t = t.getCause();
 }
 throw new IllegalStateException("Failed to register " + url + " to registry " + getUrl().getAddress() + ", cause: " + t.getMessage(), t);
 } else {
 logger.error("Failed to register " + url + ", waiting for retry, cause: " + t.getMessage(), t);
 }

 // Record a failed registration request to a failed list, retry regularly
 failedRegistered.add(url);
 }
 }

在继续排查问题前，我们先普及下这些概念：dubbo默认使用curator作为zookeeper的客户端，curator与zookeeper是通过session维持连接的。当curator重连zookeeper时，若session未过期，则继续使用原session进行连接；若session已过期，则创建新session重新连接。而ephemeral节点与session是绑定的关系，在session过期后，会删除此session下的ephemeral节点。

小米与 Dubbo 社区的合作

Sun, 15 Jan 2023 00:00:00 +0000

小米一直在积极拥抱开源社区并提交贡献，参与Dubbo3建设发布以来，在内部业务也积极推进升级工作，目前实例数已经升级到了一定的比例。升级过程总体平稳，稳定性指标正常，性能提升明显，率先升级完成的应用更早拥有了mesh化的条件。从升级后的数据表现来看，Dubbo3改变以往接口粒度的注册发现方式为应用粒度的注册发现方式，这样带来了注册中心存储和运行的更稳定，降低运维成本；使用protobuf协议进行序列化与反序列化，性能和字节大小均提升数量级；完全兼容gprc，给小米这样多言语并存的服务环境带来了极大便利。

Xiaomi is devoted to making continuous contribution to the open source community. Since the introduction of Dubbo3, internal projects are rapidly upgrading to the latest version of Dubbo. Currently, At present the numbers of instances has been upgrade to a certain proportion. Not only performance improvements have been seen, but services are also running smoothly with improvements in availability. Statistics provide proof that Dubbo’s switch from api-level discovery to application-level discovery has improved the availability and reliability of service discovery, which leads to lower operations cost. In addition, using ProtoBuf for serialization and deserialization has reduced data exchange size. Lastly, full compatibility with grpc provides convenience to Xiaomi’s multi-language development environment.

中伦网络 Dubbo3 升级实践

Sun, 15 Jan 2023 00:00:00 +0000

中伦网络在 2022 年完成了服务框架从 Dubbo2 到 Dubbo3 的全站升级，深度使用了应用级服务发现、Kubernetes 原生服务部署、服务治理等核心能力。来自中仑网络的技术负责人来彬彬对整个 Dubbo3 的选型、升级过程及收益等做了深入总结。

值得一提的是近期 Dubbo3 官网文档整体有了本质的提升，并且社区承诺短期内文档还会投入大量精力完善文档，这点对于 Dubbo3 的使用和用户信心提升非常重要。

一、公司业务与技术架构简介

苏州中仑网络科技有限公司是一家“专注零售门店增收服务”的公司，一直以“解决中小零售门店经营难的问题”为初心，致力于为零售商户提供门店运营一体化解决方案，帮助零售门店实现增收。中仑网络以零售技术为核心，为零售商户打造出集收银系统、中仑掌柜、微商城、汇邻生活平台、大数据平台、移动支付、智慧农贸、汇邻门店运营服务等为一体的新零售生态体系，实现线上线下全方位融合，为零售商家赋能增收。技术团队在构建之初选取Dubbo 2.5.3+Zookeeper版本构建公司微服务基座支撑公司业务发展，后期同阿里云深度合作整体迁移使用阿里云，使用云原生基础设施ACK（Kubernetes）+MSE（Zookeeper）+Dubbo+PolarDB等构建，实现可动态缩扩容的服务能力。伴随合作商扩展3000+，市场遍及300+城市，零售商户30万+，服务覆盖餐饮、茶饮、服装、母婴、烘焙、生鲜、商超、美业、美妆、宠物等多个行业。伴随着领域拓宽、商户量快速增长上升，系统数量和部署节点也迎来了暴增，随之在系统可用性上受到较大挑战：微服务治理能力、微服务地址注册发现，Kubernetes平台服务的无损上下线顺滑度上问题与挑战越来越多。架构图见图一。

图一

二、Dubbo3 升级总结

在升级微服务组件技术选型上主要考虑解决以前的痛点：服务治理能力、云原生友好性、服务注册发现，这几个制约业务发展的紧要问题。比较下来Dubbo3架构设计理念与我们较为契合，能较好的满足我们业务发展要求。

1、服务治理能力

Dubbo 3提供丰富的服务治理能力，可实现诸如服务发现、负载均衡、流量调度等服务治理诉求。在使用上我们有两种选择：一、使用Dubbo管理控制台管理配置、二、集成相关API能力到系统。同时Dubbo 扩展性较好，可以在很多功能点（见图二）去定制自己的实现，以改变框架的默认行为来满足自己的业务需求。Dubbo SPI ( Service Provider Interface)将接口实现类的全限定名配置在文件中，并由服务加载器读取配置文件，加载实现类。这样可以在运行时，动态为接口替换实现类。基于此特性，我们可以很容易的通过 SPI 机制为我们的程序提供拓展功能，如我们在此基础上实现了基于生产和消费者过滤器Filter实现全链路自定义的链路监控;基于路由扩展标签路由方式进行测试环境的隔离方便快速多版本服务测试验证。实操上我们基于生产者注册服务时打标，如原系统A V1版本部署在fat环境上,现在为了测试V2版本，我们将V2版本打标tag=fat-v2;使用端在消费时指定Invocation Attachment 参数,inv.setAttachment(TAG_KEY, routeTag);基于此我们可以方便自测试，同时生产上我们也可以做简单的生产灰度运用。

图二

2、云原生友好性

Dubbo 在设计上遵循云原生微服务开发理念，微服务支持 Kubernetes平台调度，实现服务生命周期与容器生命周期的对齐，包括 Dubbo 的启动、销毁、服务注册等生命周期事件。中仑网络微服务管理使用的是MSE（Zookeeper）,因而我们服务暴露使用需与之对齐。具体操作上我们自定义Startup 启动探针、 Liveness 存活探针、Readiness 就绪探针。项目的正常切换需要保障无损的上下线，在实施中无损上线相对于下线来说会更麻烦点，项目的发布上线过程大体会遵从如下流程：大致分成三个阶段，第一阶段升级少量（如 20% ）的实例，并切换少量流量到新版本，完成这个阶段后先暂停升级。经过人工确认之后继续第二个阶段，升级更大比例（如 90% ）的实例和流量，再次暂停等待人工确认。最后阶段将全量升级到新版本并验证完毕，从而完成整个发布过程。如果升级期间发现包括业务指标在内的任何异常，例如 CPU 或 memory 异常使用率升高或请求 500 日志过多等情况，可以快速回滚。因为我们使用的是MSE（Zookeeper）服务，dubbo服务自注册在应用启动过程暴露不受Kubernetes 生命周期的控制，出现项目未完全就绪部分服务可被提前可被访问问题。

图三

实施处理上我们主要利用Dubbo Qos指令,初始使用服务不暴露，在应用就绪后调用Qos online指令进行服务上线替换老节点，每次替换的节点数量基于发布策略来制定;下线过程针对需下线节点我们会先使用Qos指令进行下线offline操作等待应用执行完服务，从而进行优雅停机，从实践的效果来看能满足我们的生产需求。

3、实例级别升级切换

相比于 2.x 版本中的基于接口粒度的服务发现机制，3.x 引入了全新的基于应用粒度的服务发现机制，进一步提升了 Dubbo3 在大规模集群实践中的性能与稳定性。此次升级过程中我们也同步引入了配置中心与原数据中心，即将图四置灰部分启用

0-4 - 缓存条目超限

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

其它模块复用了 Common 层的基于文件的缓存机制（目前是元数据模块），而 Common 层的文件缓存机制 “发觉” 条目超限。

可能的原因

用户不合理地配置了 Java System Property （用 -D 配置的 Java 系统属性） dubbo.mapping.cache.entrySize 或者 dubbo.meta.cache.entrySize

默认值

dubbo.mapping.cache.entrySize	dubbo.meta.cache.entrySize
10000	100

排查和解决步骤

尝试重新配置上述 Java System Property（用 -D 配置的 Java 系统属性）。
如果确实没有配置这些 System Property，请到 GitHub Issue Tracker 下发 Issue。

1-4 - 空地址

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

可能的原因

registry.integration.RegistryDirectory 中的1-4错误是refreshInvoker过程中invokerUrls为空导致的，可以忽略。
registry.support.CacheableFailbackRegistry 中的1-4错误可能是consumer和provider不匹配，并且关闭了“空保护”所导致。

排查和解决步骤

确保 Provider 和 Consumer 端的服务分组配置相对应。
确保 Provider 和 Consumer 端的服务版本配置相对应。
检查注册中心的enable-empty-protection是否为true（默认为true）。

另请参阅配置项参考手册

2-4 - Merger接口加载失败

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

可能的原因

Dubbo 提供了聚合下游所有提供方响应的 SPI 扩展 Merger 接口，Dubbo 在加载用户在自定义扩展 Merger 接口时，加载配置失败。

排查和解决步骤

参照社区 SPI 扩展使用手册，检查用户自定义扩展 Merger 接口实现《SPI 扩展使用手册》。

3-4 - 客户端发送请求超时

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

可能的原因

客户端连接数过高，响应较慢, 无法及时向服务端发出请求。
网络的一些原因。

排查和解决步骤

网络是否正常。
可通过一些第三方的工具或者jstack [PID] > jstack.log 分析堆栈信息，进行定位。

3.2 升级至 3.3

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

对于绝大多数的用户，升级到 Dubbo 3.3.0 是完全平滑的，仅需要修改依赖包版本即可。

<dependency>
 <groupId>org.apache.dubbo</groupId>
 <artifactId>dubbo</artifactId>
 <version>3.3.0</version>
</dependency>

或者

<dependency>
 <groupId>org.apache.dubbo</groupId>
 <artifactId>dubbo-spring-boot-starter</artifactId>
 <version>3.3.0</version>
</dependency>

兼容性 CheckList

1. 默认序列化切换

Dubbo 3.3.0 版本开始默认序列化方式从 fastjson2 切换为 hessian2，对于升级到 3.3.0 的应用，Dubbo 会自动尝试采用 hessian2 进行序列化。

Q1：为什么要切换默认序列化方式？

hessian2 为 Dubbo 3.1.x 及以下版本中默认的序列化，长期的生产验证了其稳定性和兼容性，在评估了向前兼容性和长期可维护性后，Dubbo 团队决定将 hessian-lite 升级到最新 hessian4 主干版本，以支持 JDK17 和 JDK21。

升级到 Dubbo 3.3.0 以后，依赖的 hessian-lite 版本将同步升级为 4.0.x，主要包含以下修改：

同步 hessian 到上游 4.0.66 版本
修复 JDK17 及 JDK21 下类可见性带来的兼容性问题
支持 Record、ImmutableCollections 等 JDK9+ 特性

Q2：会不会影响和低版本的 Dubbo 互通？

部分场景下可能会有影响，具体如下：

4-4 - 非安全序列化方式

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

可能的原因

当前在使用非安全的序列化器, 并不推荐。具体配置为：serialization="java"

Java 序列化是不安全的。Dubbo 团队不推荐任何人使用它。如果你仍然想使用它，请遵循 JEP 290 来设置序列化过滤器，以防止反序列化泄露。

排查和解决步骤

修改serialization的参数值. 将 protocol 内的序列化参数值修改为其他,如hessian2，fastjson2等。

5-4 - 服务接口中找不到方法

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

可能的原因

消费端调用的接口名#方法不存在。
服务端未正确的暴露当前接口。

排查和解决步骤

检查消费端调用的接口名#方法是否存在。
检查服务端暴露的服务列表内是否存在。

6-4 - 网络通讯层未知异常

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

可能的原因

该错误码的意义已经调整。对于 Dubbo 3.1.4、3.2.0-beta.3 及其之前的版本的该错误码的出错，请参考错误码 99-0。

排查和解决步骤

（该错误码目前空缺）

7-4 - QOS 服务启动失败

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

可能的原因

QOS 参数值未正确设置。主要参数有 qos.host 和 qos.port

排查和解决步骤

请参考QOS 操作手册QOS 概述。

81-4 - 嵌入式ZooKeeper运行异常

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

可能的原因

ZooKeeper 服务运行异常或宕机。
Zookeeper 客户端版本与服务端启动版本不兼容，无法连接。
应用服务器与 ZooKeeper 服务连接中断。
受限防火墙或第三方防护工具。

排查和解决步骤

检查 ZooKeeper 服务及所在服务器健康状态。
检查 Zookeeper 客户端版本与服务端启动版本是否存在兼容问题，保持版本一致。
检查应用服务器与 ZooKeeper 服务端口是否通畅。
检查防火墙或第三方防护工具设置，是否已禁止。

API文档&测试

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

dubbo api docs

dubbo 接口文档、测试工具,根据注解生成文档,并提供测试功能.

增加一些注解就能生成类似swagger的文档, 不会把非web的dubbo项目变为web项目.

如何使用?

dubbo项目的方法参数中加上 dubbo api docs 注解
- dubbo提供者项目引入 dubbo-api-docs-core
- 如果dubbo的接口和参数是一个单独的jar包项目,引入dubbo-api-docs-annotations
- 在提供者项目的项目启动类(标注了@SpringBootApplication的类)或者配制类(标注了@Configuration的类)中增加注解 @EnableDubboApiDocs 以启用Dubbo Api Docs功能
  - 为避免增加生产环境中的资源占用, 建议单独创建一个配制类用于启用Dubbo Api Docs, 并配合 @Profile(“dev”) 注解使用
  - 当然, Dubbo Api Docs 仅在项目启动时多消耗了点CPU资源, 并使用了一点点内存用于缓存, 将来会考虑将缓存中的内容放到元数据中心.

版本

当前版本: 同Dubbo版本号

<dependency>
 <groupId>org.apache.dubbo</groupId>
 <artifactId>dubbo-api-docs-annotations</artifactId>
 <version>${dubbo-version}</version>
</dependency>

<dependency>
 <groupId>org.apache.dubbo</groupId>
 <artifactId>dubbo-api-docs-core</artifactId>
 <version>${dubbo-version}</version>
</dependency>

下载 dubbo-admin 下载地址
启动 dubbo-admin
访问: http:// localhost:8080

Apollo

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

1 前置条件

了解 Dubbo 基本开发步骤
安装并启动 Apollo

2 使用说明

在此查看完整示例代码

2.1 增加 Maven 依赖

<dependency>
 <groupId>org.apache.dubbo</groupId>
 <artifactId>dubbo</artifactId>
 <version>3.0.9</version>
</dependency>
<dependency>
 <groupId>com.ctrip.framework.apollo</groupId>
 <artifactId>apollo-openapi</artifactId>
 <version>2.0.0</version>
</dependency>
<dependency>
 <groupId>com.ctrip.framework.apollo</groupId>
 <artifactId>apollo-client</artifactId>
 <version>2.0.0</version>
</dependency>

2.2 启用 Apollo 配置中心

<dubbo:config-center address="apollo://localhost:8080"/>

或者

dubbo
 config-center
 address: apollo://localhost:8080

或者

dubbo.config-center.address=apollo://localhost:8080

或者

ConfigCenterConfig configCenter = new ConfigCenterConfig();
configCenter.setAddress("apollo://localhost:8080");

3 高级配置

Apollo中的一个核心概念是命名空间 - namespace，和上面 Zookeeper、Nacos 的 namespace 概念不同，因此使用方式上也比较特殊些，建议充分了解 Apollo 自身的用法后再阅读以下文档内容。

但总的来说，对 Apollo 的适配而言：

group 特用于外部化配置的隔离，参见 3.1
namespace 特用于流量治理规则隔离，参见 3.2

3.1 外部化配置

<dubbo:config-center group="demo-provider" address="apollo://localhost:8080"/>

config-center 的 group 决定了 Apollo 读取外部化配置 dubbo.properties 文件的位置：

Dubbo Admin 安全

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

为了便于使用 Dubbo，Dubbo 官方提供了 Dubbo Admin 控制台，以便于管理 Dubbo 应用。

风险

Dubbo Admin 默认拥有整个集群的查询、调用权限，因此对于线上环境，需要更加谨慎地使用。此外，为了减低任意访问 Dubbo Admin 的风险，Dubbo Admin 还提供了简易的鉴权机制。为了使 Dubbo Admin 更安全，请参考下面的文档。

鉴权方案

Dubbo Admin 默认提供基于用户名密码的登陆机制，在请求过程中基于 JWT Token 进行鉴权。从便于初学者的角度出发，Dubbo Admin 包含了一个默认的用户名密码、JWT Secret Token。

由于 Dubbo Admin 是公开发行的，因此默认的用户名密码、JWT Secret Token 都是公开的。在您的生产环境中，请务必更换默认的用户名密码、JWT Secret Token。

如何更换默认的用户名密码、JWT Secret Token

对于直接基于 Java 代码打包部署的用户，可以直接修改 dubbo-admin-server/src/main/resources/application.properties 中以下配置：

admin.root.user.name=root
admin.root.user.password=root
admin.check.signSecret=86295dd0c4ef69a1036b0b0c15158d77

对于通过 Docker 部署的用户，可以修改 /dubbo/dubbo-admin/properties 中以下配置：

admin.root.user.name=root
admin.root.user.password=root
admin.check.signSecret=86295dd0c4ef69a1036b0b0c15158d77

对于通过 Kubernetes 部署的用户，可以修改 ConfigMap 中以下配置：

admin.root.user.name=root
admin.root.user.password=root
admin.check.signSecret=86295dd0c4ef69a1036b0b0c15158d77

对于通过 Helm 部署的用户，可以指定以下配置：

Fastjson

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

1 介绍

Fastjson 是一个 Java 库，可用于将 Java 对象转换为其 JSON 表示形式。它还可用于将 JSON 字符串转换为等效的 Java 对象。 Fastjson 可以处理任意 Java 对象，包括您没有源代码的预先存在的对象。

2 使用方式

2.1 添加依赖

<dependencies>
 <dependency>
 <groupId>org.apache.dubbo.extensions</groupId>
 <artifactId>dubbo-serialization-fastjson</artifactId>
 <version>3.3.0</version>
 </dependency>
 <dependency>
 <groupId>com.alibaba</groupId>
 <artifactId>fastjson</artifactId>
 <version>1.2.83</version>
 </dependency>
</dependencies>

2.2 配置启用

# application.yml (Spring Boot)
dubbo:
 protocol:
 serialization: fastjson

或

# dubbo.properties
dubbo.protocol.serialization=fastjson

# or
dubbo.consumer.serialization=fastjson

# or
dubbo.reference.com.demo.DemoService.serialization=fastjson

或

<dubbo:protocol serialization="fastjson" />

<!-- or -->
<dubbo:consumer serialization="fastjson" />

<!-- or -->
<dubbo:reference interface="xxx" serialization="fastjson" />

3 支持的rpc协议

hessian 协议

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

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

Hessian ¹ 协议用于集成 Hessian 的服务，Hessian 底层采用 Http 通讯，采用 Servlet 暴露服务，Dubbo 缺省内嵌 Jetty 作为服务器实现。

Dubbo 的 Hessian 协议可以和原生 Hessian 服务互操作，即：

提供者用 Dubbo 的 Hessian 协议暴露服务，消费者直接用标准 Hessian 接口调用
或者提供方用标准 Hessian 暴露服务，消费方用 Dubbo 的 Hessian 协议调用。

特性

连接个数：多连接
连接方式：短连接
传输协议：HTTP
传输方式：同步传输
序列化：Hessian二进制序列化
适用范围：传入传出参数数据包较大，提供者比消费者个数多，提供者压力较大，可传文件。
适用场景：页面传输，文件传输，或与原生hessian服务互操作

依赖

<dependency>
 <groupId>com.caucho</groupId>
 <artifactId>hessian</artifactId>
 <version>4.0.7</version>
</dependency>

约束

参数及返回值需实现 Serializable 接口
参数及返回值不能自定义实现 List, Map, Number, Date, Calendar 等接口，只能用 JDK 自带的实现，因为 hessian 会做特殊处理，自定义实现类中的属性值都会丢失。

配置

定义 hessian 协议：

<dubbo:protocol name="hessian" port="8080" server="jetty" />

设置默认协议：

hessian 协议

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

Hessian ¹ 协议用于集成 Hessian 的服务，Hessian 底层采用 Http 通讯，采用 Servlet 暴露服务，Dubbo 缺省内嵌 Jetty 作为服务器实现。

Dubbo 的 Hessian 协议可以和原生 Hessian 服务互操作，即：

提供者用 Dubbo 的 Hessian 协议暴露服务，消费者直接用标准 Hessian 接口调用
或者提供方用标准 Hessian 暴露服务，消费方用 Dubbo 的 Hessian 协议调用。

特性

连接个数：多连接
连接方式：短连接
传输协议：HTTP
传输方式：同步传输
序列化：Hessian二进制序列化
适用范围：传入传出参数数据包较大，提供者比消费者个数多，提供者压力较大，可传文件。
适用场景：页面传输，文件传输，或与原生hessian服务互操作

依赖

<dependency>
 <groupId>com.caucho</groupId>
 <artifactId>hessian</artifactId>
 <version>4.0.7</version>
</dependency>

约束

参数及返回值需实现 Serializable 接口
参数及返回值不能自定义实现 List, Map, Number, Date, Calendar 等接口，只能用 JDK 自带的实现，因为 hessian 会做特殊处理，自定义实现类中的属性值都会丢失。

配置

定义 hessian 协议：

<dubbo:protocol name="hessian" port="8080" server="jetty" />

设置默认协议：

Multicast

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

Multicast 注册中心不需要启动任何中心节点，只要广播地址一样，就可以互相发现。

1 使用说明

<dubbo:registry address="multicast://224.5.6.7:1234" />

或

<dubbo:registry protocol="multicast" address="224.5.6.7:1234" />

注意:

为了减少广播量，Dubbo 缺省使用单播发送提供者地址信息给消费者。如果一个机器上同时启了多个消费者进程，消费者需声明 unicast=false，否则只会有一个消费者能收到消息; 当服务者和消费者运行在同一台机器上，消费者同样需要声明unicast=false，否则消费者无法收到消息，导致No provider available for the service异常：

<dubbo:application name="demo-consumer">
 <dubbo:parameter key="unicast" value="false" />
</dubbo:application>

或

<dubbo:consumer>
 <dubbo:parameter key="unicast" value="false" />
</dubbo:consumer>

2 工作原理

2.1 基本流程

提供方启动时广播自己的地址
消费方启动时广播订阅请求
提供方收到订阅请求时，单播自己的地址给订阅者，如果设置了 unicast=false，则广播给订阅者
消费方收到提供方地址时，连接该地址进行 RPC 调用。

2.2 使用限制

组播受网络结构限制，只适合小规模应用或开发阶段使用。组播地址段: 224.0.0.0 - 239.255.255.255

使用 Nacos 作为注册中心实现自动服务发现

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

本示例演示 Nacos 作为注册中心实现自动服务发现，示例基于 Spring Boot 应用展开，可在此查看完整示例代码

1 基本配置

1.1 增加依赖

对于 Spring Boot 应用，可以使用如下 spring-boot-starter：

<dependency>
 <groupId>org.apache.dubbo</groupId>
 <artifactId>dubbo-spring-boot-starter</artifactId>
 <version>3.3.0</version>
</dependency>
<dependency>
 <groupId>org.apache.dubbo</groupId>
 <artifactId>dubbo-nacos-spring-boot-starter</artifactId>
 <version>3.3.0</version>
</dependency>

非 Spring Boot 用户，可以自行增加 dubbo、nacos-client 依赖：

<dependencies>
 <dependency>
 <groupId>org.apache.dubbo</groupId>
 <artifactId>dubbo</artifactId>
 <version>3.3.0</version>
 </dependency>
 <dependency>
 <groupId>com.alibaba.nacos</groupId>
 <artifactId>nacos-client</artifactId>
 <version>2.1.0</version>
 </dependency>
</dependencies>

1.2 Nacos 版本

Nacos 版本映射关系：

Dubbo	推荐 Nacos 版本	Nacos 兼容范围
3.3.0	2.3.0	2.x
3.2.21	2.1.0	2.x
3.1.11	2.0.9	2.x
3.0.10	2.0.9	2.x
2.7.21	1.x最新版本	1.x
2.6.0	1.x最新版本	1.x

1.3 配置并启用 Nacos

# application.yml (Spring Boot)
dubbo
 registry
 address: nacos://localhost:8848

或

基于 protobuf 实现 triple 协议互通（适用于两边都用 protobuf 开发的场景）

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

我们这里提供一个示例，演示如何使用 triple 协议实现 dubbo-java 和 dubbo-go 互通，可在此查看示例完整源码。

示例主要内容如下：

go，go 语言实现的 rpc server 与 client
java，java 语言实现的 rpc server 与 client

共享 protobuf 服务定义

共享服务定义如下，请注意以下 package、go_package 、java_package 的具体定义：

//protoc --go_out=. --go_opt=paths=source_relative --go-triple_out=. greet.proto
syntax = "proto3";
package org.apache.dubbo.sample;

option go_package = "github.com/apache/dubbo-go-samples/java_interop/protobuf-triple/go/proto;proto";
//package of go
option java_package = 'org.apache.dubbo.sample';
option java_multiple_files = true;
option java_outer_classname = "HelloWorldProto";
option objc_class_prefix = "WH";

// The greeting service definition.
service Greeter {
 // Sends a greeting
 rpc SayHello(HelloRequest) returns (HelloReply);
 // Sends a greeting via stream
 // rpc SayHelloStream (stream HelloRequest) returns (stream 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;
}

java-client调用go-server

首先启动 go server：

go run go/go-server/cmd/server.go

运行以上命令后，go server 运行在 50052 端口，可通过以下命令测试服务运行正常：

Redis 协议

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

基于 Redis ¹ 实现的 RPC 协议。

提示

2.3.0 以上版本支持

注册 redis 服务的地址

RegistryFactory registryFactory = ExtensionLoader.getExtensionLoader(RegistryFactory.class).getAdaptiveExtension();
Registry registry = registryFactory.getRegistry(URL.valueOf("zookeeper://10.20.153.10:2181"));
registry.register(URL.valueOf("redis://10.20.153.11/com.foo.BarService?category=providers&dynamic=false&application=foo&group=member&loadbalance=consistenthash"));

在客户端引用

在客户端使用 ²：

<dubbo:reference id="store" interface="java.util.Map" group="member" />

或者，点对点直连：

<dubbo:reference id="store" interface="java.util.Map" url="redis://10.20.153.10:6379" />

也可以使用自定义接口：

<dubbo:reference id="store" interface="com.foo.StoreService" url="redis://10.20.153.10:6379" />

方法名建议和 redis 的标准方法名相同，即：get(key), set(key, value), delete(key)。

如果方法名和 redis 的标准方法名不相同，则需要配置映射关系 ³：

<dubbo:reference id="cache" interface="com.foo.CacheService" url="redis://10.20.153.10:6379" p:set="putFoo" p:get="getFoo" p:delete="removeFoo" />

Redis 是一个高效的 KV 存储服务器 ↩︎
不需要感知 Redis 的地址 ↩︎
其中 “p:xxx” 为 spring 的标准 p 标签 ↩︎

Redis 注册中心安装

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

Redis ¹ 使用方式参见: Redis 注册中心参考手册。

只需搭一个原生的 Redis 服务器，并将快速启动中 Provider 和 Consumer 里的 conf/dubbo.properties 中的 dubbo.registry.address 的值改为 redis://127.0.0.1:6379 即可使用。

Redis 注册中心集群 ² 采用在客户端同时写入多个服务器，读取单个服务器的策略实现。

安装:

wget http://redis.googlecode.com/files/redis-2.4.8.tar.gz
tar xzf redis-2.4.8.tar.gz
cd redis-2.4.8
make

配置:

vi redis.conf

启动:

nohup ./src/redis-server redis.conf &

停止:

killall redis-server

命令行 ³:

./src/redis-cli
hgetall /dubbo/com.foo.BarService/providers

或者：

telnet 127.0.0.1 6379
hgetall /dubbo/com.foo.BarService/providers

Redis 是一个高效的 KV 存储服务器，参见：http://redis.io/topics/quickstart ↩︎
2.1.0 以上版本支持 ↩︎
参见: http://redis.io/commands ↩︎

redis 协议

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

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

基于 Redis ¹ 实现的 RPC 协议。

提示

2.3.0 以上版本支持

注册 redis 服务的地址

RegistryFactory registryFactory = ExtensionLoader.getExtensionLoader(RegistryFactory.class).getAdaptiveExtension();
Registry registry = registryFactory.getRegistry(URL.valueOf("zookeeper://10.20.153.10:2181"));
registry.register(URL.valueOf("redis://10.20.153.11/com.foo.BarService?category=providers&dynamic=false&application=foo&group=member&loadbalance=consistenthash"));

在客户端引用

在客户端使用 ²：

<dubbo:reference id="store" interface="java.util.Map" group="member" />

或者，点对点直连：

<dubbo:reference id="store" interface="java.util.Map" url="redis://10.20.153.10:6379" />

也可以使用自定义接口：

<dubbo:reference id="store" interface="com.foo.StoreService" url="redis://10.20.153.10:6379" />

方法名建议和 redis 的标准方法名相同，即：get(key), set(key, value), delete(key)。

如果方法名和 redis 的标准方法名不相同，则需要配置映射关系 ³：

<dubbo:reference id="cache" interface="com.foo.CacheService" url="redis://10.20.153.10:6379" p:set="putFoo" p:get="getFoo" p:delete="removeFoo" />

Redis 是一个高效的 KV 存储服务器 ↩︎
不需要感知 Redis 的地址 ↩︎
其中 “p:xxx” 为 spring 的标准 p 标签 ↩︎

redis 协议

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

基于 Redis ¹ 实现的 RPC 协议。

提示

2.3.0 以上版本支持

注册 redis 服务的地址

RegistryFactory registryFactory = ExtensionLoader.getExtensionLoader(RegistryFactory.class).getAdaptiveExtension();
Registry registry = registryFactory.getRegistry(URL.valueOf("zookeeper://10.20.153.10:2181"));
registry.register(URL.valueOf("redis://10.20.153.11/com.foo.BarService?category=providers&dynamic=false&application=foo&group=member&loadbalance=consistenthash"));

在客户端引用

在客户端使用 ²：

<dubbo:reference id="store" interface="java.util.Map" group="member" />

或者，点对点直连：

<dubbo:reference id="store" interface="java.util.Map" url="redis://10.20.153.10:6379" />

也可以使用自定义接口：

<dubbo:reference id="store" interface="com.foo.StoreService" url="redis://10.20.153.10:6379" />

方法名建议和 redis 的标准方法名相同，即：get(key), set(key, value), delete(key)。

如果方法名和 redis 的标准方法名不相同，则需要配置映射关系 ³：

<dubbo:reference id="cache" interface="com.foo.CacheService" url="redis://10.20.153.10:6379" p:set="putFoo" p:get="getFoo" p:delete="removeFoo" />

Redis 是一个高效的 KV 存储服务器 ↩︎
不需要感知 Redis 的地址 ↩︎
其中 “p:xxx” 为 spring 的标准 p 标签 ↩︎

Router

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

通过自定义路由，可以根据业务场景的特点来实现特定的路由方式。本示例 router 扩展实现源码请参见 dubbo-samples-extensibility。

开始之前

任务详情

对所有的请求都使用第一提供服务的Provider，如果该Provider下线，则从新选择一个新的Provider。

实现方式

在Consumer中自定义一个Router，在Router中将第一次调用的Provider保存下来，如果后续有请求调用且Provider列表中包含第一次调用时使用的Provider，则继续使用第一次调用时使用的Provider，否则重新选去一个Provider。

代码结构

src
 |-main
 |-java
 |-org
 |-apache
 |-dubbo
 |-samples
 |-extensibility
 |-router
 |-consumer
 |-router
 |-StickFirstStateRouter.java (实现StateRouter接口)
 |-StickFirstStateRouterFactory.java (实现StateRouterFactory接口)
 |-resources
 |-META-INF
 |-application.properties (Dubbo Consumer配置文件)
 |-dubbo
 |-org.apache.dubbo.rpc.cluster.router.state.StateRouterFactory (纯文本文件)

代码详情

StickFirstStateRouter

package org.apache.dubbo.samples.extensibility.router.consumer.router;

import org.apache.dubbo.common.URL;
import org.apache.dubbo.common.config.configcenter.ConfigChangeType;
import org.apache.dubbo.common.config.configcenter.ConfigChangedEvent;
import org.apache.dubbo.common.config.configcenter.ConfigurationListener;
import org.apache.dubbo.common.logger.ErrorTypeAwareLogger;
import org.apache.dubbo.common.logger.LoggerFactory;
import org.apache.dubbo.common.utils.CollectionUtils;
import org.apache.dubbo.common.utils.Holder;
import org.apache.dubbo.rpc.Invocation;
import org.apache.dubbo.rpc.Invoker;
import org.apache.dubbo.rpc.RpcException;
import org.apache.dubbo.rpc.cluster.router.RouterSnapshotNode;
import org.apache.dubbo.rpc.cluster.router.state.AbstractStateRouter;
import org.apache.dubbo.rpc.cluster.router.state.BitList;

public class StickFirstStateRouter<T> extends AbstractStateRouter<T> implements ConfigurationListener {
 public StickFirstStateRouter(URL url) {
 super(url);
 }

 public static final String NAME = "STICK_FIRST_ROUTER";
 private static final ErrorTypeAwareLogger logger = LoggerFactory.getErrorTypeAwareLogger(StickFirstStateRouter.class);
 private volatile BitList<Invoker<T>> firstInvokers;

 @Override
 protected BitList<Invoker<T>> doRoute(BitList<Invoker<T>> invokers, URL url, Invocation invocation, boolean needToPrintMessage, Holder<RouterSnapshotNode<T>> routerSnapshotNodeHolder, Holder<String> messageHolder) throws RpcException {
 if (CollectionUtils.isEmpty(invokers)) {
 if (needToPrintMessage) {
 messageHolder.set("Directly Return. Reason: Invokers from previous router is empty.");
 }
 return invokers;
 }
 BitList<Invoker<T>> copy = invokers.clone();
 if (CollectionUtils.isEmpty(copy)) {
 this.firstInvokers = new BitList<>(BitList.emptyList());
 this.firstInvokers.add(copy.get(0));
 } else {
 this.firstInvokers = copy.and(invokers);
 if(CollectionUtils.isEmpty(this.firstInvokers)){
 this.firstInvokers.add(copy.get(0));
 }
 }
 return this.firstInvokers;
 }

 @Override
 public void process(ConfigChangedEvent event) {
 if (logger.isDebugEnabled()) {
 logger.debug("Notification of tag rule, change type is: " + event.getChangeType() + ", raw rule is:\n " +
 event.getContent());
 }
 // Reset
 if (event.getChangeType().equals(ConfigChangeType.DELETED)) {
 this.firstInvokers = null;
 }
 }

 @Override
 public void stop() {
 super.stop();
 this.firstInvokers = null;
 }
}

StickFirstStateRouterFactory

package org.apache.dubbo.samples.extensibility.router.consumer.router;

import org.apache.dubbo.common.URL;
import org.apache.dubbo.rpc.cluster.router.state.StateRouter;
import org.apache.dubbo.rpc.cluster.router.state.StateRouterFactory;

public class StickFirstStateRouterFactory implements StateRouterFactory {
 @Override
 public <T> StateRouter<T> getRouter(Class<T> interfaceClass, URL url) {
 return new StickFirstStateRouter<>(url);
 }
}

SPI配置

在resources/META-INF/dubbo/org.apache.dubbo.rpc.cluster.router.state.StateRouterFactory文件中添加如下配置：

Simple 注册中心

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

此文档已经不再维护。您当前查看的是快照版本。

Simple 注册中心本身就是一个普通的 Dubbo 服务，可以减少第三方依赖，使整体通讯方式一致。

配置

将 Simple 注册中心暴露成 Dubbo 服务：

<?xml version="1.0" encoding="UTF-8"?>
<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"
 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:application name="simple-registry" />
 <!-- 暴露服务协议配置 -->
 <dubbo:protocol port="9090" />
 <!-- 暴露服务配置 -->
 <dubbo:service interface="org.apache.dubbo.registry.RegistryService" ref="registryService" registry="N/A" ondisconnect="disconnect" callbacks="1000">
 <dubbo:method name="subscribe"><dubbo:argument index="1" callback="true" /></dubbo:method>
 <dubbo:method name="unsubscribe"><dubbo:argument index="1" callback="false" /></dubbo:method>
 </dubbo:service>
 <!-- 简单注册中心实现，可自行扩展实现集群和状态同步 -->
 <bean id="registryService" class="org.apache.dubbo.registry.simple.SimpleRegistryService" />
</beans>

引用 Simple Registry 服务：

<dubbo:registry address="127.0.0.1:9090" />

或者：

<dubbo:service interface="org.apache.dubbo.registry.RegistryService" group="simple" version="1.0.0" ... >

或者：

Simple 注册中心

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

Simple 注册中心本身就是一个普通的 Dubbo 服务，可以减少第三方依赖，使整体通讯方式一致。

配置

将 Simple 注册中心暴露成 Dubbo 服务：

<?xml version="1.0" encoding="UTF-8"?>
<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"
 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:application name="simple-registry" />
 <!-- 暴露服务协议配置 -->
 <dubbo:protocol port="9090" />
 <!-- 暴露服务配置 -->
 <dubbo:service interface="org.apache.dubbo.registry.RegistryService" ref="registryService" registry="N/A" ondisconnect="disconnect" callbacks="1000">
 <dubbo:method name="subscribe"><dubbo:argument index="1" callback="true" /></dubbo:method>
 <dubbo:method name="unsubscribe"><dubbo:argument index="1" callback="false" /></dubbo:method>
 </dubbo:service>
 <!-- 简单注册中心实现，可自行扩展实现集群和状态同步 -->
 <bean id="registryService" class="org.apache.dubbo.registry.simple.SimpleRegistryService" />
</beans>

引用 Simple Registry 服务：

<dubbo:registry address="127.0.0.1:9090" />

或者：

<dubbo:service interface="org.apache.dubbo.registry.RegistryService" group="simple" version="1.0.0" ... >

或者：

Skywalking

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

本文演示如何将 Dubbo 接入 Skywalking 全链路监控体系，完整示例请参考 dubbo-samples-tracing-skywalking。依赖的 Skywalking Agent 版本为 skywalking micrometer-1.10 api.

1. 添加 Micrometer Observation 依赖到你的项目

为了能够将 Micrometer 及相关 Metrics 依赖添加到 classpath，需要增加 dubbo-metrics-api 依赖，如下所示：


<dependency>
 <groupId>org.apache.dubbo</groupId>
 <artifactId>dubbo-metrics-api</artifactId>
</dependency>

2. 添加 Skywalking Micrometer-1.10 Api 到项目

为了将 Dubbo Micrometer tracing 数据集成到 Skywalking，需要添加以下依赖。

<dependency>
 <groupId>org.apache.skywalking</groupId>
 <artifactId>apm-toolkit-micrometer-1.10</artifactId>
</dependency>

3. 配置 ObservationRegistry

@Configuration
public class ObservationConfiguration {
 @Bean
 ApplicationModel applicationModel(ObservationRegistry observationRegistry) {
 ApplicationModel applicationModel = ApplicationModel.defaultModel();
 observationRegistry.observationConfig()
 .observationHandler(new ObservationHandler.FirstMatchingCompositeObservationHandler(
 new SkywalkingSenderTracingHandler(), new SkywalkingReceiverTracingHandler(),
 new SkywalkingDefaultTracingHandler()
 ));
 applicationModel.getBeanFactory().registerBean(observationRegistry);
 return applicationModel;
 }
}

4. 启动 Skywalking OAP

请参考这里了解如何设置 Skywalking OAP

Streaming 通信

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

在选择 RPC 通信协议一节提到，Streaming 是 Dubbo3 新提供的一种 RPC 数据传输模式，适用于以下场景:

接口需要发送大量数据，这些数据无法被放在一个 RPC 的请求或响应中，需要分批发送，但应用层如果按照传统的多次 RPC 方式无法解决顺序和性能的问题，如果需要保证有序，则只能串行发送
流式场景，数据需要按照发送顺序处理, 数据本身是没有确定边界的
推送类场景，多个消息在同一个调用的上下文中被发送和处理

Streaming 分为以下三种:

SERVER_STREAM(服务端流)
CLIENT_STREAM(客户端流)
BIDIRECTIONAL_STREAM(双向流)

以下示例演示 triple streaming 流式通信的基本使用方法，涵盖了客户端流、服务端流、双向流等三种模式，示例使用 Protocol Buffers 的服务开发模式，对于 Java 接口模式的开发者可以在本文最后查看相应说明。可在此查看本示例完整代码。

运行示例

首先，可通过以下命令下载示例源码：

git clone --depth=1 https://github.com/apache/dubbo-samples.git

进入示例源码目录：

cd dubbo-samples/2-advanced/dubbo-samples-triple-streaming

编译项目，由 IDL 生成代码，这会调用 dubbo 提供的 protoc 插件生成对应的服务定义代码：

mvn clean compile

启动server

运行以下命令，启动 server：

$ mvn compile exec:java -Dexec.mainClass="org.apache.dubbo.samples.tri.streaming.TriStreamServer"

启动client

运行以下命令，启动 client：

$ mvn compile exec:java -Dexec.mainClass="org.apache.dubbo.samples.tri.streaming.TriStreamClient"

源码解读

与使用 Protobuf(IDL) 开发 triple 协议服务一节中提到的一样，这个示例使用 protobuf 定义服务，因此示例需要的依赖、配置等基本是一致的，请参考那一节了解完整详情。接下来，我们将重点讲解流式通信部分的内容。

Thrift 协议

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

当前 dubbo 支持的 thrift 协议是对 thrift 原生协议 ¹ 的扩展，在原生协议的基础上添加了一些额外的头信息，比如 service name，magic number 等。

提示

2.3.0 以上版本支持

使用 dubbo thrift 协议同样需要使用 thrift 的 idl compiler 编译生成相应的 java 代码，后续版本中会在这方面做一些增强。

依赖

<dependency>
 <groupId>org.apache.thrift</groupId>
 <artifactId>libthrift</artifactId>
 <version>0.8.0</version>
</dependency>

配置

所有服务共用一个端口 ²：

<dubbo:protocol name="thrift" port="3030" />

使用

可以参考 dubbo 项目中的示例代码

常见问题

Thrift 不支持 null 值，即：不能在协议中传递 null 值

Thrift 是 Facebook 捐给 Apache 的一个 RPC 框架 ↩︎
与原生Thrift不兼容 ↩︎

thrift 协议

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

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

当前 dubbo 支持的 thrift 协议是对 thrift 原生协议 ¹ 的扩展，在原生协议的基础上添加了一些额外的头信息，比如 service name，magic number 等。

提示

2.3.0 以上版本支持

使用 dubbo thrift 协议同样需要使用 thrift 的 idl compiler 编译生成相应的 java 代码，后续版本中会在这方面做一些增强。

依赖

<dependency>
 <groupId>org.apache.thrift</groupId>
 <artifactId>libthrift</artifactId>
 <version>0.8.0</version>
</dependency>

配置

所有服务共用一个端口 ²：

<dubbo:protocol name="thrift" port="3030" />

使用

可以参考 dubbo 项目中的示例代码

常见问题

Thrift 不支持 null 值，即：不能在协议中传递 null 值

Thrift 是 Facebook 捐给 Apache 的一个 RPC 框架 ↩︎
与原生Thrift不兼容 ↩︎

thrift 协议

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

当前 dubbo 支持的 thrift 协议是对 thrift 原生协议 ¹ 的扩展，在原生协议的基础上添加了一些额外的头信息，比如 service name，magic number 等。

提示

2.3.0 以上版本支持

使用 dubbo thrift 协议同样需要使用 thrift 的 idl compiler 编译生成相应的 java 代码，后续版本中会在这方面做一些增强。

依赖

<dependency>
 <groupId>org.apache.thrift</groupId>
 <artifactId>libthrift</artifactId>
 <version>0.8.0</version>
</dependency>

配置

所有服务共用一个端口 ²：

<dubbo:protocol name="thrift" port="3030" />

使用

可以参考 dubbo 项目中的示例代码

常见问题

Thrift 不支持 null 值，即：不能在协议中传递 null 值

Thrift 是 Facebook 捐给 Apache 的一个 RPC 框架 ↩︎
与原生Thrift不兼容 ↩︎

Triple协议迁移指南

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

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

Triple 介绍

Triple 协议的格式和原理请参阅 RPC 通信协议

根据 Triple 设计的目标，Triple 协议有以下优势:

具备跨语言交互的能力，传统的多语言多 SDK 模式和 Mesh 化跨语言模式都需要一种更通用易扩展的数据传输协议。
提供更完善的请求模型，除了支持传统的 Request/Response 模型（Unary 单向通信），还支持 Stream（流式通信）和 Bidirectional（双向通信）。
易扩展、穿透性高，包括但不限于 Tracing / Monitoring 等支持，也应该能被各层设备识别，网关设施等可以识别数据报文，对 Service Mesh 部署友好，降低用户理解难度。
完全兼容 grpc，客户端/服务端可以与原生grpc客户端打通。
可以复用现有 grpc 生态下的组件, 满足云原生场景下的跨语言、跨环境、跨平台的互通需求。

当前使用其他协议的 Dubbo 用户，框架提供了兼容现有序列化方式的迁移能力，在不影响线上已有业务的前提下，迁移协议的成本几乎为零。

需要新增对接 Grpc 服务的 Dubbo 用户，可以直接使用 Triple 协议来实现打通，不需要单独引入 grpc client 来完成，不仅能保留已有的 Dubbo 易用性，也能降低程序的复杂度和开发运维成本，不需要额外进行适配和开发即可接入现有生态。

对于需要网关接入的 Dubbo 用户，Triple 协议提供了更加原生的方式，让网关开发或者使用开源的 grpc 网关组件更加简单。网关可以选择不解析 payload ，在性能上也有很大提高。在使用 Dubbo 协议时，语言相关的序列化方式是网关的一个很大痛点，而传统的 HTTP 转 Dubbo 的方式对于跨语言序列化几乎是无能为力的。同时，由于 Triple 的协议元数据都存储在请求头中，网关可以轻松的实现定制需求，如路由和限流等功能。

Dubbo2 协议迁移流程

Dubbo2 的用户使用 dubbo 协议 + 自定义序列化，如 hessian2 完成远程调用。

XML 配置

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

Dubbo 有基于 Spring Schema 扩展的自定义配置组件，XML 支持的配置项与配置参考手册中描述的一一对。本文使用的示例请参考 dubbo-samples-spring-xml

XML完整示例

服务提供者

定义服务接口

DemoService.java：

package org.apache.dubbo.demo;

public interface DemoService {
 String sayHello(String name);
}

在服务提供方实现接口

DemoServiceImpl.java：

package org.apache.dubbo.demo.provider;
import org.apache.dubbo.demo.DemoService;

public class DemoServiceImpl implements DemoService {
 public String sayHello(String name) {
 return "Hello " + name;
 }
}

用 Spring 配置声明暴露服务

<?xml version="1.0" encoding="UTF-8"?>
<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" xmlns:context="http://www.springframework.org/schema/context"
 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 http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context.xsd">
 <context:property-placeholder/>

 <dubbo:application name="demo-provider"/>

 <dubbo:registry address="zookeeper://${zookeeper.address:127.0.0.1}:2181"/>

 <dubbo:provider token="true"/>

 <bean id="demoService" class="org.apache.dubbo.samples.basic.impl.DemoServiceImpl"/>

 <dubbo:service interface="org.apache.dubbo.samples.basic.api.DemoService" ref="demoService"/>

</beans>

加载 Spring 配置

public class Application {
 public static void main(String[] args) throws InterruptedException {
 ClassPathXmlApplicationContext context = new ClassPathXmlApplicationContext("spring/dubbo-demo-provider.xml");
 context.start();

 System.out.println("dubbo service started");
 // to hang up main thread
 new CountDownLatch(1).await();
 }
}

服务消费者

通过 Spring 配置引用远程服务

<?xml version="1.0" encoding="UTF-8"?>
<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" xmlns:context="http://www.springframework.org/schema/context"
 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 http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context.xsd">
 <context:property-placeholder/>

 <dubbo:application name="demo-consumer"/>

 <dubbo:registry address="zookeeper://${zookeeper.address:127.0.0.1}:2181"/>

 <dubbo:reference id="demoService" check="true" interface="org.apache.dubbo.samples.basic.api.DemoService"/>

</beans>

加载 Spring 配置，并调用远程服务

public class Application {
 public static void main(String[] args) throws IOException {
 ClassPathXmlApplicationContext context = new ClassPathXmlApplicationContext("spring/dubbo-demo-consumer.xml");
 context.start();
 GreetingsService greetingsService = (GreetingsService) context.getBean("greetingsService");

 String message = greetingsService.sayHi("dubbo");
 System.out.println("Receive result ======> " + message);
 System.in.read();
 System.exit(0);
 }
}

Zipkin

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

安装

你可以使用 Dubbo 社区提供的示例配置快速安装 Zipkin。

kubectl create -f https://raw.githubusercontent.com/apache/dubbo-kubernetes/master/deploy/kubernetes/zipkin.yaml

本安装仅适用于测试或体验使用，生产级别的安装请参考 Zipkin 官方安装文档。

Zookeeper 注册中心安装

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

建议使用 dubbo-2.3.3 以上版本的 zookeeper ¹ 注册中心客户端。

Dubbo 未对 Zookeeper 服务器端做任何侵入修改，只需安装原生的 Zookeeper 服务器即可，所有注册中心逻辑适配都在调用 Zookeeper 客户端时完成。

安装:

wget http://archive.apache.org/dist/zookeeper/zookeeper-3.3.3/zookeeper-3.3.3.tar.gz
tar zxvf zookeeper-3.3.3.tar.gz
cd zookeeper-3.3.3
cp conf/zoo_sample.cfg conf/zoo.cfg

配置:

vi conf/zoo.cfg

如果不需要集群，zoo.cfg 的内容如下 ²：

tickTime=2000
initLimit=10
syncLimit=5
dataDir=/home/dubbo/zookeeper-3.3.3/data
clientPort=2181

如果需要集群，zoo.cfg 的内容如下 ³：

tickTime=2000
initLimit=10
syncLimit=5
dataDir=/home/dubbo/zookeeper-3.3.3/data
clientPort=2181
server.1=10.20.153.10:2555:3555
server.2=10.20.153.11:2555:3555

并在 data 目录 ⁴ 下放置 myid 文件：

mkdir data
vi myid

myid 指明自己的 id，对应上面 zoo.cfg 中 server. 后的数字，第一台的内容为 1，第二台的内容为 2，内容如下：

启动:

./bin/zkServer.sh start

停止:

./bin/zkServer.sh stop

命令行 ⁵:

版本与分组

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

Dubbo服务中，接口并不能唯一确定一个服务，只有 接口+分组+版本号 的三元组才能唯一确定一个服务。

当同一个接口针对不同的业务场景、不同的使用需求或者不同的功能模块等场景，可使用服务分组来区分不同的实现方式。同时，这些不同实现所提供的服务是可并存的，也支持互相调用。
当接口实现需要升级又要保留原有实现的情况下，即出现不兼容升级时，我们可以使用不同版本号进行区分。

本文示例完整源码可在以下链接查看：

使用方式

使用 @DubboService 注解，配置 group 参数和 version 参数：

接口定义：

public interface DevelopService {
 String invoke(String param);
}

接口实现1：

@DubboService(group = "group1", version = "1.0")
public class DevelopProviderServiceV1 implements DevelopService{
 @Override
 public String invoke(String param) {
 StringBuilder s = new StringBuilder();
 s.append("ServiceV1 param:").append(param);
 return s.toString();
 }
}

接口实现2：

@DubboService(group = "group2", version = "2.0")
public class DevelopProviderServiceV2 implements DevelopService{
 @Override
 public String invoke(String param) {
 StringBuilder s = new StringBuilder();
 s.append("ServiceV2 param:").append(param);
 return s.toString();
 }
}

客户端接口调用：

使用 @DubboReference 注解，添加 group 参数和 version 参数

暴露监听扩展

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

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

扩展说明

当有服务暴露时，触发该事件。

扩展接口

org.apache.dubbo.rpc.ExporterListener

扩展配置

<!-- 暴露服务监听 -->
<dubbo:service listener="xxx,yyy" />
<!-- 暴露服务缺省监听器 -->
<dubbo:provider listener="xxx,yyy" />

已知扩展

org.apache.dubbo.registry.directory.RegistryExporterListener

扩展示例

Maven 项目结构：

src
 |-main
 |-java
 |-com
 |-xxx
 |-XxxExporterListener.java (实现ExporterListener接口)
 |-resources
 |-META-INF
 |-dubbo
 |-org.apache.dubbo.rpc.ExporterListener (纯文本文件，内容为：xxx=com.xxx.XxxExporterListener)

XxxExporterListener.java：

package com.xxx;
 
import org.apache.dubbo.rpc.ExporterListener;
import org.apache.dubbo.rpc.Exporter;
import org.apache.dubbo.rpc.RpcException;
 
 
public class XxxExporterListener implements ExporterListener {
 public void exported(Exporter<?> exporter) throws RpcException {
 // ...
 }
 public void unexported(Exporter<?> exporter) throws RpcException {
 // ...
 }
}

META-INF/dubbo/org.apache.dubbo.rpc.ExporterListener：

暴露监听扩展

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

扩展说明

当有服务暴露时，触发该事件。

扩展接口

org.apache.dubbo.rpc.ExporterListener

扩展配置

<!-- 暴露服务监听 -->
<dubbo:service listener="xxx,yyy" />
<!-- 暴露服务缺省监听器 -->
<dubbo:provider listener="xxx,yyy" />

已知扩展

org.apache.dubbo.registry.directory.RegistryExporterListener

扩展示例

Maven 项目结构：

src
 |-main
 |-java
 |-com
 |-xxx
 |-XxxExporterListener.java (实现ExporterListener接口)
 |-resources
 |-META-INF
 |-dubbo
 |-org.apache.dubbo.rpc.ExporterListener (纯文本文件，内容为：xxx=com.xxx.XxxExporterListener)

XxxExporterListener.java：

package com.xxx;
 
import org.apache.dubbo.rpc.ExporterListener;
import org.apache.dubbo.rpc.Exporter;
import org.apache.dubbo.rpc.RpcException;
 
 
public class XxxExporterListener implements ExporterListener {
 public void exported(Exporter<?> exporter) throws RpcException {
 // ...
 }
 public void unexported(Exporter<?> exporter) throws RpcException {
 // ...
 }
}

META-INF/dubbo/org.apache.dubbo.rpc.ExporterListener：

暴露监听扩展

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

扩展说明

当有服务暴露时，触发该事件。

扩展接口

org.apache.dubbo.rpc.ExporterListener

扩展配置

<!-- 暴露服务监听 -->
<dubbo:service listener="xxx,yyy" />
<!-- 暴露服务缺省监听器 -->
<dubbo:provider listener="xxx,yyy" />

已知扩展

org.apache.dubbo.registry.directory.RegistryExporterListener

扩展示例

Maven 项目结构：

src
 |-main
 |-java
 |-com
 |-xxx
 |-XxxExporterListener.java (实现ExporterListener接口)
 |-resources
 |-META-INF
 |-dubbo
 |-org.apache.dubbo.rpc.ExporterListener (纯文本文件，内容为：xxx=com.xxx.XxxExporterListener)

XxxExporterListener.java：

package com.xxx;
 
import org.apache.dubbo.rpc.ExporterListener;
import org.apache.dubbo.rpc.Exporter;
import org.apache.dubbo.rpc.RpcException;
 
 
public class XxxExporterListener implements ExporterListener {
 public void exported(Exporter<?> exporter) throws RpcException {
 // ...
 }
 public void unexported(Exporter<?> exporter) throws RpcException {
 // ...
 }
}

META-INF/dubbo/org.apache.dubbo.rpc.ExporterListener：

成熟度

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

功能成熟度

Feature	Maturity	Strength	Problem	Advise	User
并发控制	Tested	并发控制		试用
连接控制	Tested	连接数控制		试用
直连提供者	Tested	点对点直连服务提供方，用于测试		测试环境使用	Alibaba
分组聚合	Tested	分组聚合返回值，用于菜单聚合等服务	特殊场景使用	可用于生产环境
参数验证	Tested	参数验证，JSR303验证框架集成	对性能有影响	试用	LaiWang
结果缓存	Tested	结果缓存，用于加速请求		试用
泛化引用	Stable	泛化调用，无需业务接口类进行远程调用，用于测试平台，开放网关桥接等		可用于生产环境	Alibaba
泛化实现	Stable	泛化实现，无需业务接口类实现任意接口，用于Mock平台		可用于生产环境	Alibaba
回声测试	Tested	回声测试		试用
隐式传参	Stable	附加参数		可用于生产环境
异步调用	Tested	不可靠异步调用		试用
本地调用	Tested	本地调用		试用
参数回调	Tested	参数回调	特殊场景使用	试用	Registry
事件通知	Tested	事件通知，在远程调用执行前后触发		试用
本地存根	Stable	在客户端执行部分逻辑		可用于生产环境	Alibaba
本地伪装	Stable	伪造返回结果，可在失败时执行，或直接执行，用于服务降级	需注册中心支持	可用于生产环境	Alibaba
延迟暴露	Stable	延迟暴露服务，用于等待应用加载warmup数据，或等待spring加载完成		可用于生产环境	Alibaba
延迟连接	Tested	延迟建立连接，调用时建立		试用	Registry
粘滞连接	Tested	粘滞连接，总是向同一个提供方发起请求，除非此提供方挂掉，再切换到另一台		试用	Registry
令牌验证	Tested	令牌验证，用于服务授权	需注册中心支持	试用
路由规则	Tested	动态决定调用关系	需注册中心支持	试用
配置规则	Tested	动态下发配置，实现功能的开关	需注册中心支持	试用
访问日志	Tested	访问日志，用于记录调用信息	本地存储，影响性能，受磁盘大小限制	试用
分布式事务	Research	JTA/XA三阶段提交事务	不稳定	不可用

策略成熟度

Feature	Maturity	Strength	Problem	Advise
Zookeeper注册中心	Stable	支持基于网络的集群方式，有广泛周边开源产品，建议使用dubbo-2.3.3以上版本（推荐使用）	依赖于Zookeeper的稳定性	可用于生产环境
Redis注册中心	Stable	支持基于客户端双写的集群方式，性能高	要求服务器时间同步，用于检查心跳过期脏数据	可用于生产环境
Multicast注册中心	Tested	去中心化，不需要安装注册中心	依赖于网络拓扑和路由，跨机房有风险	小规模应用或开发测试环境
Simple注册中心	Tested	Dogfooding，注册中心本身也是一个标准的RPC服务	没有集群支持，可能单点故障	试用

Feature	Maturity	Strength	Problem	Advise	User
Simple监控中心	Stable	支持JFreeChart统计报表	没有集群支持，可能单点故障，但故障后不影响RPC运行	可用于生产环境

Feature	Maturity	Strength	Problem	Advise	User
Dubbo协议	Stable	采用NIO复用单一长连接，并使用线程池并发处理请求，减少握手和加大并发效率，性能较好（推荐使用）	在大文件传输时，单一连接会成为瓶颈	可用于生产环境	Alibaba
Rmi协议	Stable	可与原生RMI互操作，基于TCP协议	偶尔会连接失败，需重建Stub	可用于生产环境	Alibaba
Hessian协议	Stable	可与原生Hessian互操作，基于HTTP协议	需hessian.jar支持，http短连接的开销大	可用于生产环境

Feature	Maturity	Strength	Problem	Advise	User
Netty Transporter	Stable	JBoss的NIO框架，性能较好（推荐使用）	一次请求派发两种事件，需屏蔽无用事件	可用于生产环境	Alibaba
Mina Transporter	Stable	老牌NIO框架，稳定	待发送消息队列派发不及时，大压力下，会出现FullGC	可用于生产环境	Alibaba
Grizzly Transporter	Tested	Sun的NIO框架，应用于GlassFish服务器中	线程池不可扩展，Filter不能拦截下一Filter	试用

Feature	Maturity	Strength	Problem	Advise	User
Hessian Serialization	Stable	性能较好，多语言支持（推荐使用）	Hessian的各版本兼容性不好，可能和应用使用的Hessian冲突，Dubbo内嵌了hessian3.2.1的源码	可用于生产环境	Alibaba
Dubbo Serialization	Tested	通过不传送POJO的类元信息，在大量POJO传输时，性能较好	当参数对象增加字段时，需外部文件声明	试用
Json Serialization	Tested	纯文本，可跨语言解析，缺省采用FastJson解析	性能较差	试用
Java Serialization	Stable	Java原生支持	性能较差	可用于生产环境

Feature	Maturity	Strength	Problem	Advise	User
Javassist ProxyFactory	Stable	通过字节码生成代替反射，性能比较好（推荐使用）	依赖于javassist.jar包，占用JVM的Perm内存，Perm可能要设大一些：java -XX:PermSize=128m	可用于生产环境	Alibaba
Jdk ProxyFactory	Stable	JDK原生支持	性能较差	可用于生产环境

Feature	Maturity	Strength	Problem	Advise	User
Failover Cluster	Stable	失败自动切换，当出现失败，重试其它服务器，通常用于读操作（推荐使用）	重试会带来更长延迟	可用于生产环境	Alibaba
Failfast Cluster	Stable	快速失败，只发起一次调用，失败立即报错,通常用于非幂等性的写操作	如果有机器正在重启，可能会出现调用失败	可用于生产环境	Alibaba
Failsafe Cluster	Stable	失败安全，出现异常时，直接忽略，通常用于写入审计日志等操作	调用信息丢失	可用于生产环境	Monitor
Failback Cluster	Tested	失败自动恢复，后台记录失败请求，定时重发，通常用于消息通知操作	不可靠，重启丢失	可用于生产环境	Registry
Forking Cluster	Tested	并行调用多个服务器，只要一个成功即返回，通常用于实时性要求较高的读操作	需要浪费更多服务资源	可用于生产环境
Broadcast Cluster	Tested	广播调用所有提供者，逐个调用，任意一台报错则报错，通常用于更新提供方本地状态	速度慢，任意一台报错则报错	可用于生产环境

Feature	Maturity	Strength	Problem	Advise	User
Random LoadBalance	Stable	随机，按权重设置随机概率（推荐使用）	在一个截面上碰撞的概率高，重试时，可能出现瞬间压力不均	可用于生产环境	Alibaba
RoundRobin LoadBalance	Stable	轮询，按公约后的权重设置轮询比率	存在慢的机器累积请求问题，极端情况可能产生雪崩	可用于生产环境
LeastActive LoadBalance	Stable	最少活跃调用数，相同活跃数的随机，活跃数指调用前后计数差，使慢的机器收到更少请求	不支持权重，在容量规划时，不能通过权重把压力导向一台机器压测容量	可用于生产环境
ConsistentHash LoadBalance	Stable	一致性Hash，相同参数的请求总是发到同一提供者，当某一台提供者挂时，原本发往该提供者的请求，基于虚拟节点，平摊到其它提供者，不会引起剧烈变动	压力分摊不均	可用于生产环境

Feature	Maturity	Strength	Problem	Advise	User
条件路由规则	Stable	基于条件表达式的路由规则，功能简单易用	有些复杂多分支条件情况，规则很难描述	可用于生产环境	Alibaba
脚本路由规则	Tested	基于脚本引擎的路由规则，功能强大	没有运行沙箱，脚本能力过于强大，可能成为后门	试用

Feature	Maturity	Strength	Problem	Advise	User
Spring Container	Stable	自动加载META-INF/spring目录下的所有Spring配置		可用于生产环境	Alibaba
Jetty Container	Stable	启动一个内嵌Jetty，用于汇报状态	大量访问页面时，会影响服务器的线程和内存	可用于生产环境	Alibaba
Log4j Container	Stable	自动配置log4j的配置，在多进程启动时，自动给日志文件按进程分目录	用户不能控制log4j的配置，不灵活	可用于生产环境	Alibaba

传递附加参数

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

理解隐式参数传递的最直接方式 http header，它的工作方式与 http header 完全一致，在 GET 或 POST 请求体之外可以传递任意多个 header 参数。而对于 RPC 调用而言，context就是在方法签名的参数之外提供附加参数传递能力，在实现原理上，对于不同的协议，attachment 的实现方式略有不同：

对于 triple 协议，attachment 会转换为标准的 http header 进行传输。
对于 dubbo 协议，attachment 是编码在协议体的固定位置进行传输，具体请参见 dubbo 协议规范。、

注意

在使用 triple 协议时，由于 http header 的限制，仅支持小写的 ascii 字符
path, group, version, dubbo, token, timeout 等一些 key 是保留字段，传递 attachment 时应避免使用，尽量通过业务前缀等确保 key 的唯一性。

1.介绍

本文档演示如何在 Dubbo-go 框架中使用 context 上下文传递和读取附加参数，来实现上下文信息传递，可在此查看完整示例源码地址

2.使用说明

2.1客户端使用说明

在客户端中，使用下述方式传递字段, 示例中 key 为 constant.AttachmentKey 即 “attachment”:

	ctx := context.Background()
	ctx = context.WithValue(ctx, constant.AttachmentKey, map[string]interface{}{
 "key1": "user defined value 1",
 "key2": "user defined value 2"
	})

2.2服务端使用说明

在服务端中，使用下述方式获取字段, value的类型为 map[string]interface{}：

动态配置规则

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

动态配置规则 (ConfigurationRule) 是 Dubbo 设计的在无需重启应用的情况下，动态调整 RPC 调用行为的一种能力，也称为动态覆盖规则，因为它是通过在运行态覆盖 Dubbo 实例或者 Dubbo 实例中 URL 地址的各种参数值，实现改变 RPC 调用行为的能力。

使用动态配置规则，有以下几条关键信息值得注意：

设置规则生效过滤条件。 配置规则支持一系列的过滤条件，用来限定规则只对符合特定条件的服务、应用或实例才生效。
设置规则生效范围。 一个 rpc 服务有服务发起方（消费者）和服务处理方（提供者）两个角色，对某一个服务定义的规则，可以具体到限制是对消费者还是提供者生效。
选择规则管理粒度。 Dubbo 支持从服务和应用两个粒度来管理和下发规则。

以下一个应用级别的配置示例，配置生效后，shop-detail 应用下提供的所有服务都将启用 accesslog，对 shop-detail 部署的所有实例生效。

configVersion: v3.0
scope: application
key: shop-detail
configs:
 - side: provider
 parameters:
 accesslog: 'true'

以下是一个服务级别的配置示例，key: org.apache.dubbo.samples.UserService 和 side: consumer 说明这条配置对所有正在消费 UserService 的 Dubbo 实例生效，在调用失败后都执行 4 次重试。match 条件进一步限制了消费端的范围，限定为只对应用名为 shop-frontend 的这个消费端应用生效。

configVersion: v3.0
scope: service
key: org.apache.dubbo.samples.UserService
configs:
 - match:
 application:
 oneof:
 - exact: shop-frontend
 side: consumer
 parameters:
 retries: '4'

ConfigurationRule

配置规则主体，定义要设置的目标服务或应用、具体的规则配置。具体配置规则 (configs) 可以设置多条。

多协议

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

区别于普通的 RPC 框架，Dubbo 作为一款微服务框架提供了非常灵活的协议支持，它不绑定一个单一通信协议。因此你可以发布在一个进程中同时发布多个 RPC 协议、调用不同的 RPC 协议。接下来我们就详细介绍多协议的具体使用场景与使用方式。

使用场景

有很多场景可能会用到不同的协议，包括安全性、性能、与第三方系统互调等业务诉求。本文我们不分析具体的业务需求，而是从 Dubbo 框架提供的多协议能力出发分析框架能提供的多协议能力：

作为服务提供者（provider），同一个服务发布为多个协议，供不同消费端调用
作为服务提供者（provider），多个服务分别发布为不同协议，供不同消费端调用
作为服务消费者（consumer），指定以某个特定协议调用某一个服务

使用方式

同一个服务发布为多个协议

如果使用 Spring Boot，可以修改 application.yml 或 application.properties 如下：

dubbo:
 protocols:
 dubbo-id:
 name: dubbo
 port: 20880
 tri-id:
 name: tri
 port: 50051

对于 Spring XML：

<dubbo:protocol id="dubbo-id" name="dubbo" port="20880"/>
<dubbo:protocol id="triple-id" name="tri" port="50051"/>

接下来为服务配置（默认不配置的情况下，服务会发布到以上所有协议配置）：

@DubboService(protocol="dubbo-id,triple-id")
private DemoServiceImpl implements DemoService {}

多个服务分别发布为不同协议

如果使用 Spring Boot，可以修改 application.yml 或 application.properties 如下：

dubbo:
 protocols:
 dubbo-id:
 name: dubbo
 port: 20880
 tri-id:
 name: tri
 port: 50051

接下来为不同的服务分别配置不同的协议引用：

报告安全问题

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

Apache Software Foundation 在消除其软件项目中的安全性问题方面采取严格的立场。Apache Dubbo 对与其功能和特性有关的问题非常敏感并很快提出。

报告漏洞

如果您对 Dubbo 的安全性有担心，或者发现漏洞或潜在威胁，请发送电子邮件至 security@dubbo.apache.org 与 Apache Dubbo 安全团队联系。在邮件中，指定问题或潜在威胁的描述。还敦促您推荐重现和复制问题的方法。Dubbo 社区会在评估和分析调查结果之后与您联系。

请先注意在安全电子邮件中报告安全问题，然后再在公共领域公开该问题。

漏洞处理

漏洞处理过程的概述是：

报告者将漏洞秘密报告给 Apache。
相应项目的安全团队与报告者私下合作来解决漏洞。
制作了包含该修复程序的有关 Apache 产品的新版本。
该漏洞已公开宣布。

有关此过程的详细说明，请参见此处

非protoubf模式协议互通（适用于老版本 dubbo java 应用）

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

注意

在阅读本文档之前，请记住我们推荐使用 protobuf+triple 的模式编写 java 和 go 语言互通的服务。本文仅当您已经有老版本 dubbo java 应用的情况下适用，否则的话请参考上一篇文档，使用 protobuf+triple 开发服务。

可在此查看本文档完整示例源码。

go-client 调用 java-server

但如果您是 dubbo java 的老用户，可能您的 dubbo java 应用并没有使用 protobuf（直接使用 java interface 定义服务），这个时候您需要使用以下方式开发 dubbo go-client，来调用老版本的 dubbo 服务。

以下方案同时支持 triple(non-protobuf) 和 dubbo 协议，你只需要调整协议配置 client.WithClientProtocolTriple() 即可。

假设我们当前的 java 服务定义如下：

package org.apache.dubbo.samples.api;

public interface GreetingsService {
 String sayHi(String name);
}

我们需要这么编写 go-client，以实现服务调用：

// 生成共享 client，指定
cliDubbo, _ := client.NewClient(
	client.WithClientProtocolDubbo(),
	client.WithClientSerialization(constant.Hessian2Serialization),
)

// 生成服务代理，这里指定 java 服务全路径名
connDubbo, _ := cliDubbo.Dial("org.apache.dubbo.samples.api.GreetingsService", client.WithURL("tri://localhost:50052"))

var respDubbo string
// 发起调用，参数以数组形式指定（标准 json 格式，可参考 java 泛化调用）
connDubbo.CallUnary(context.Background(), []interface{}{"hello"}, &respDubbo, "SayHello")

接下来我们尝试运行示例：

Admin 服务 Mock 功能简介

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

Mock 功能是设计用来提升微服务研发与测试效率的，它可以短路 Consumer 侧发起的远程调用，提前返回预先设定好的 Mock 值，这样即使在没有 Provider 可用的情况下，消费端也能正常的推进开发、测试进程。除此之外，mock 也可用于快速模拟负责返回值的测试数据、模拟服务端异常等场景

需要注意的是，Mock 能力仅限用于测试环境，应避免将其用于生产环境。

设计背景

在跨团队或是多应用开发时，在前期开发中往往会出现依赖的服务还未开发完成的情况，这样就会导致流程的阻塞，影响研发效率。基于这种情况，Dubbo Admin 提供了 mock 能力来解耦 Consumer 与 Provider 之间的依赖，以确保在 Provider 未就绪的情况下 Consumer 仍能正常开展测试，提高研发效率。

Dubbo 框架本身设计有服务降级（有时也称为 mock）能力，通过配置 org.apache.dubbo.config.ReferenceConfig 的 mock 字段（可设置为true或是对应接口的Mock实现）或动态配置规则，此时就可以启动服务降级能力。这种服务降级能力是为生产环境的限流降级准备的，虽然也可以用于本地开发测试场景，但灵活度并不高，基于提升开发效率的根本诉求，我们设计了基于 Admin 的服务降级能力。

Dubbo Admin 服务 mock 是一种更为轻量和便捷实现方式，主要用于开发测试阶段的，目标是提升微服务场景下的整体研发效率。需求详见：Dubbo Admin Mock需求。

架构设计

实现 Mock 能力，Dubbo 框架与 Admin 侧要支持的能力

Dubbo Admin
- 规则管理
  - 规则新增
  - 规则查询
  - 规则修改
  - 规则删除
- 请求历史记录
- Mock 请求数据查询
- MockService Provider
  - 根据规则生成 Mock 数据
  - 响应 Consumer Mock 请求
  - 保存请求和返回数据
Dubbo
- 根据 mock 开关配置，转发请求到 Admin 注册的 MockService
- 处理 mock 返回值并转换为匹配方法签名的强类型数据

Mock 请求原理时序图

服务调用扩展点

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

如上图所示，从服务调用的角度来看，Dubbo 在链路中提供了丰富的扩展点，覆盖了负载均衡方式、选址前后的拦截器、服务端处理拦截器等。简单来说 Dubbo 发起远程调用的时候，主要工作流程可以分为消费端和服务端两个部分。

消费端的工作流程如下：

通过 Stub 接收来自用户的请求，并且封装在 Invocation 对象中
将 Invocation 对象传递给 ClusterFilter（扩展点）做选址前的请求预处理，如请求参数的转换、请求日志记录、限流等操作都是在此阶段进行的
将 Invocation 对象传递给 Cluster（扩展点）进行集群调用逻辑的决策，如快速失败模式、安全失败模式等决策都是在此阶段进行的
- Cluster 调用 Directory 获取所有可用的服务端地址信息
- Directory 调用 StateRouter（扩展点，推荐使用）和 Router（扩展点）对服务端的地址信息进行路由筛选，此阶段主要是从全量的地址信息中筛选出本次调用允许调用到的目标，如基于打标的流量路由就是在此阶段进行的
- Cluster 获得从 Directory 提供的可用服务端信息后，会调用 LoadBalance （扩展点）从多个地址中选择出一个本次调用的目标，如随机调用、轮询调用、一致性哈希等策略都是在此阶段进行的
- Cluster 获得目标的 Invoker 以后将 Invocation 传递给对应的 Invoker，并等待返回结果，如果出现报错则执行对应的决策（如快速失败、安全失败等）
经过上面的处理，得到了带有目标地址信息的 Invoker，会再调用 Filter（扩展点）进行选址后的请求处理（由于在消费端侧创建的 Filter 数量级和服务端地址量级一致，如无特殊需要建议使用 ClusterFilter 进行扩展拦截，以提高性能）
最后 Invocation 会被通过网络发送给服务端

服务端的工作流程如下：

服务端通信层收到请求以后，会将请求传递给协议层构建出 Invocation
将 Invocation 对象传递给 Filter （扩展点）做服务端请求的预处理，如服务端鉴权、日志记录、限流等操作都是在此阶段进行的
将 Invocation 对象传递给动态代理做真实的服务端调用

Filter（拦截器）

拦截器可以实现服务提供方和服务消费方调用过程拦截，Dubbo 本身的大多功能均基于此扩展点实现，每次远程方法执行，该拦截都会被执行，请注意对性能的影响。其中在消费端侧，ClusterFilter 用于选址前的拦截和 Filter 用于选址后的拦截。如无特殊需要使用 ClusterFilter 进行扩展拦截，以提高性能。

服务发现

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

在此查看完整示例。

使用服务注册和发现非常简单。事实上，与点对点调用相比，它只需要增加两行代码。在使用该功能之前，我们需要安装相关的注册客户端。目前，Dubbo-python 只支持 Zookeeper，因此下面的演示将使用 Zookeeper。与之前类似，我们需要克隆 Dubbo-python 源代码并安装它。不过，在这种情况下，我们还需要安装 Zookeeper 客户端。命令如下：

git clone https://github.com/apache/dubbo-python.git
cd dubbo-python && pip install .[zookeeper]

而后，只需启动 Zookeeper 并在现有示例中插入以下代码即可：

# Configure the Zookeeper registry
registry_config = RegistryConfig.from_url("zookeeper://127.0.0.1:2181")
bootstrap = Dubbo(registry_config=registry_config)

# Create the client
client = bootstrap.create_client(reference_config)

# Create and start the server
bootstrap.create_server(service_config).start()

服务引用

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

1. 简介

上一篇文章详细分析了服务导出的过程，本篇文章我们趁热打铁，继续分析服务引用过程。在 Dubbo 中，我们可以通过两种方式引用远程服务。第一种是使用服务直连的方式引用服务，第二种方式是基于注册中心进行引用。服务直连的方式仅适合在调试或测试服务的场景下使用，不适合在线上环境使用。因此，本文我将重点分析通过注册中心引用服务的过程。从注册中心中获取服务配置只是服务引用过程中的一环，除此之外，服务消费者还需要经历 Invoker 创建、代理类创建等步骤。这些步骤，将在后续章节中一一进行分析。

2.服务引用原理

Dubbo 服务引用的时机有两个，第一个是在 Spring 容器调用 ReferenceBean 的 afterPropertiesSet 方法时引用服务，第二个是在 ReferenceBean 对应的服务被注入到其他类中时引用。这两个引用服务的时机区别在于，第一个是饿汉式的，第二个是懒汉式的。默认情况下，Dubbo 使用懒汉式引用服务。如果需要使用饿汉式，可通过配置 <dubbo:reference> 的 init 属性开启。下面我们按照 Dubbo 默认配置进行分析，整个分析过程从 ReferenceBean 的 getObject 方法开始。当我们的服务被注入到其他类中时，Spring 会第一时间调用 getObject 方法，并由该方法执行服务引用逻辑。按照惯例，在进行具体工作之前，需先进行配置检查与收集工作。接着根据收集到的信息决定服务用的方式，有三种，第一种是引用本地 (JVM) 服务，第二是通过直连方式引用远程服务，第三是通过注册中心引用远程服务。不管是哪种引用方式，最后都会得到一个 Invoker 实例。如果有多个注册中心，多个服务提供者，这个时候会得到一组 Invoker 实例，此时需要通过集群管理类 Cluster 将多个 Invoker 合并成一个实例。合并后的 Invoker 实例已经具备调用本地或远程服务的能力了，但并不能将此实例暴露给用户使用，这会对用户业务代码造成侵入。此时框架还需要通过代理工厂类 (ProxyFactory) 为服务接口生成代理类，并让代理类去调用 Invoker 逻辑。避免了 Dubbo 框架代码对业务代码的侵入，同时也让框架更容易使用。

以上就是服务引用的大致原理，下面我们深入到代码中，详细分析服务引用细节。

3.源码分析

服务引用的入口方法为 ReferenceBean 的 getObject 方法，该方法定义在 Spring 的 FactoryBean 接口中，ReferenceBean 实现了这个方法。实现代码如下：

public Object getObject() throws Exception {
 return get();
}

public synchronized T get() {
 if (destroyed) {
 throw new IllegalStateException("Already destroyed!");
 }
 // 检测 ref 是否为空，为空则通过 init 方法创建
 if (ref == null) {
 // init 方法主要用于处理配置，以及调用 createProxy 生成代理类
 init();
 }
 return ref;
}

以上两个方法的代码比较简短，并不难理解。这里需要特别说明一下，如果你对 2.6.4 及以下版本的 getObject 方法进行调试时，会碰到比较奇怪的的问题。这里假设你使用 IDEA，且保持了 IDEA 的默认配置。当你面调试到 get 方法的if (ref == null)时，你会发现 ref 不为空，导致你无法进入到 init 方法中继续调试。导致这个现象的原因是 Dubbo 框架本身有一些小问题。该问题已经在 pull request #2754 修复了此问题，并跟随 2.6.5 版本发布了。如果你正在学习 2.6.4 及以下版本，可通过修改 IDEA 配置规避这个问题。首先 IDEA 配置弹窗中搜索 toString，然后取消Enable 'toString' object view勾选。具体如下：

服务治理和配置管理

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

服务治理

服务治理主要作用是改变运行时服务的行为和选址逻辑，达到限流，权重配置等目的，主要有以下几个功能：

应用级别的服务治理

在 Dubbo 2.6 及更早版本中，所有的服务治理规则都只针对服务粒度，如果要把某条规则作用到应用粒度上，需要为应用下的所有服务配合相同的规则，变更，删除的时候也需要对应的操作，这样的操作很不友好，因此 Dubbo 2.7 版本中增加了应用粒度的服务治理操作，对于条件路由(包括黑白名单)，动态配置(包括权重，负载均衡)都可以做应用级别的配置：

上图是条件路由的配置，可以按照应用名，服务名两个维度来填写，也可以按照这两个维度来查询。

标签路由

标签路由是 Dubbo 2.7 引入的新功能，配置以应用作为维度，给不同的服务器打上不同名字的标签，配置如下图所示：

调用的时候，客户端可以通过setAttachment的方式，来设置不同的标签名称，比如本例中，setAttachment(tag1)，客户端的选址范围就在如图所示的三台机器中，可以通过这种方式来实现流量隔离，灰度发布等功能。

条件路由

条件路由是 Dubbo 一直以来就有的功能，目前可以配置服务和应用两个维度，条件路由为 yaml 格式，具体的规则体以及各种适用场景，请参考这里

黑白名单

黑白名单是条件路由的一部分，规则存储和条件路由放在一起，为了方便配置所以单独拿出来，同样可以通过服务和应用两个维度，指定黑名单和白名单:

动态配置

动态配置是和路由规则平行的另一类服务治理治理功能，主要作用是在不重启服务的情况下，动态改变调用行为，从Dubbo2.7版本开始，支持服务和应用两个维度的配置，采用yaml格式，界面如下：

具体的规则体说明请参考这里

权重调节

权重调节是动态配置的子功能，主要作用是改变服务端的权重，更大的权重会有更大的几率被客户端选中作为服务提供者，从而达到流量分配的目的：

负载均衡

负载均衡也是动态配置的子功能，主要作用是调整客户端的选址逻辑，目前可选的负载均衡策略有随机，轮训和最小活跃，关于各个策略的解释请参考这里

配置管理

配置管理也是配合Dubbo2.7新增的功能，在Dubbo2.7中，增加了全局和应用维度的配置，分别在全局和应用范围内生效，其中应用配置也可以指定该应用中的服务级别的配置，可以在控制台中查看，修改配置规则，默认展示全局维度的配置。

全局配置：

全局配置里可以指定注册中心，元数据中心的地址，服务端和客户端的超时时间等，这些配置在全局内生效。除了配置写入，也可以用来查看。如果使用zookeeper作为注册中心和元数据中心，还可以看到配置文件所在位置的目录结构。
应用，服务配置

应用级别的配置可以为应用或者应用内的服务指定配置，在服务维度上，需要区分提供者和消费者。dubbo.reference.{serviceName}表示作为该服务消费者的配置，dubbo.provider.{servcieName}表示作为该服务提供者的配置。其中注册中心和元数据中心的地址，只能在全局配置中指定，这也是Dubbo2.7中推荐的使用方式。
优先级：服务配置 > 应用配置 > 全局配置

软件捐献向导

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

在您阅读这篇指南之前，请确保您已经向PMC确认了实际需要的 SGA。

如果您向 Apache Dubbo 捐赠了大量的代码或文档，则需要在合并代码或者文档之前签署软件授权书。

操作步骤

下载这篇pdf文档
打印下载好的文档
按要求填充表格（请看下边示例）
请您的领导在上边签字
扫描
将扫描好的文档以邮件的方式发送给secretary@apache.org，并抄送给private@dubbo.apache.org

示例

下边是一个文本示例，原始文本可以在这里找到

License Agreement


 This License Agreement is entered into as of the _12th_ day of
___April____, __2018__ by ___ABC Software Co., Ltd.____ ("Licensor"),
in favor of The Apache Software Foundation, a Delaware nonstock
membership corporation (the "Foundation").

 WHEREAS, Licensor owns or has sufficient rights to contribute the
software source code and other related intellectual property as
itemized on Exhibit A ("Software") under the terms of this agreement
to the Foundation for use within Foundation software development
projects ("Projects").

 NOW, THEREFORE, FOR GOOD AND VALUABLE CONSIDERATION, the receipt
and legal sufficiency of which are hereby acknowledged, the parties
hereto, intending to be legally bound, agree as follows:

1. Subject to the terms and conditions of this License, Licensor
hereby grants to the Foundation:

 a) a non-exclusive, worldwide, royalty-free, irrevocable
 copyright license to reproduce, prepare derivative works of,
 publicly display, publicly perform, distribute and sublicense,
 internally and externally, the Software and such derivative
 works, in source code and object code form; and,

 b) a non-exclusive, worldwide, royalty-free, irrevocable
 patent license under Licensed Patents to make, use, sell,
 offer to sell, import and otherwise transfer the Software
 in source code and object code form. "Licensed Patents" mean
 patent claims owned by Licensor which are necessarily
 infringed by the use or sale of the Software alone.

2. Licensor represents that, to Licensor's knowledge, Licensor is
legally entitled to grant the above license. Licensor agrees to notify
the Foundation of any facts or circumstances of which Licensor becomes
aware and which makes or would make Licensor's representations in this
License Agreement inaccurate in any respect.

3. This Software is provided AS-IS, WITHOUT WARRANTIES OR CONDITIONS
OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, WITHOUT LIMITATION,
ANY WARRANTIES OR CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY
OR FITNESS FOR A PARTICULAR PURPOSE. NEITHER THE LICENSOR NOR ITS
SUPPLIERS WILL BE LIABLE TO THE FOUNDATION OR ITS LICENSEES FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING WITHOUT LIMITATION LOST PROFITS), HOWEVER CAUSED
AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
THE USE OR DISTRIBUTION OF THE WORK OR THE EXERCISE OF ANY RIGHTS
GRANTED HEREUNDER, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

This License Agreement is the entire agreement of the parties
with respect to its subject matter, and may only be amended by a
writing signed by each party. This License Agreement may be
executed in one or more counterparts, each of which shall be
considered an original.

 IN WITNESS WHEREOF, Licensor has executed this License Agreement
as of the date first written above.


 LICENSOR:


 Signed By: _____________________________________ <--- Your boss's sign here

 Print Name: _____Lei Li_________________________ <--- Your boss's name here

 Title: ____Director_____________________________ <--- Your boss's title here

 Representing: ____ABC Software Co., Ltd. _______ 

 ________________________________________________

 Contact Name: ____Lei Li________________________ <--- Your boss's name here

 Contact Email: ____lilei@abc.com________________ <--- Your boss's email here

Exhibit A

List of software and other intellectual property covered by this agreement:

* Github address where your code is hosted
* Pull request link

框架状态命令

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

startup 命令

检测当前框架是否已经启动完毕

dubbo>startup
true

dubbo>

ready 命令

检测当前框架是否能正常提供服务（可能是临时下线）

dubbo>ready
true

dubbo>

live 命令

检测当前框架是否正常运行（可能是永久异常）

dubbo>live
true

dubbo>

配置管理

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

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

Dubbo配置主要分为几大类：启动阶段配置项、服务治理规则、动态配置项。

启动阶段配置项

Dubbo启动时读取的配置项，用于初始化各个组件，不会监听这些配置项的变化。

Dubbo的配置来源有多种，配置项划分为多个配置组件，详细请参考配置概述。

配置方式

按照编程方式可以分为四种方式：API配置、XML配置、Annotation配置、属性配置。

API配置

以Java编码的方式组织配置，包括Raw API和Bootstrap API，具体请参考API配置。

XML配置

以XML方式配置各种组件，支持与Spring无缝集成，具体请参考XML配置。

Annotation配置

以注解方式暴露服务和引用服务接口，支持与Spring无缝集成，具体请参考Annotation配置。

属性配置

根据Key-value属性生成配置组件，类似SpringBoot的ConfigurationProperties，具体请参考属性配置。

属性配置的另外一个重要的功能特性是属性覆盖，使用外部属性的值覆盖已创建的配置组件属性。

如果要将属性配置放到外部的配置中心，请参考外部化配置。

服务治理规则

服务治理规则主要作用是改变运行时服务的行为和选址逻辑，达到限流，权重配置等目的，包括覆盖规则、标签路由、条件路由。

Dubbo启动后监听服务治理相关的配置项，当配置发生变化时，会自动进行相应的处理。

服务治理规则的用法介绍请参考服务治理和配置管理

服务治理规则的存储方法请参考配置中心#服务治理

动态配置项

动态配置项一般用于控制动态开关。

Dubbo启动后监听动态配置项，当配置发生变化时，会自动进行相应的处理。

动态配置的存储方式请参考配置中心#动态配置

常用的动态配置项如下：

[TODO 补充动态配置项说明]

名称	描述	默认值
dubbo.application.migration.threshold
dubbo.application.service-discovery.migration

启动时检查

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

Dubbo 框架缺省会在启动时检查依赖的服务是否可用（注册中心是否有可用地址），不可用时会抛出异常，阻止应用初始化完成，以便上线时，能及早发现问题，默认 check=“true”，并等待3s。

可以通过 check=“false” 关闭检查，比如，测试时，有些服务不关心，或者出现了循环依赖，必须有一方先启动。

关闭 check 后，请注意 provider数量比较多时， consumer 订阅 provider 生成服务地址可能会有一定延迟，如果 consumer 一启动就对外提供服务，可能会造成"冷启动"。所以在这个时候，请对服务进行预热。

示例：

dubbo:
 consumer:
 check : false
 reference: 
 myserivce:
 check: true

或者

cli, err := client.NewClient(
	client.WithClientCheck(false),
)

或者

svc, err := health.NewHealth(cli)
svc.Check(context.Background(), &health.HealthCheckRequest{Service: "greet.GreetService"}, client.WithCheck(false))

生产环境验证

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

Apache Dubbo 是一款有着数以万计企业用户的国际化开源项目，经过了多年大规模集群生产环境的检验，影响了数百万开发者，带动了大量微服务开源生态发展。Dubbo 从企业实践中孵化并走向开源，又迅速在开源社区获得了成功，大量的生产实践用户是 Dubbo 长期保持先进性、稳定性和活跃度的核心驱动力。

Dubbo 在阿里巴巴的应用

Dubbo 设计用于解决阿里巴巴内部复杂的电商微服务集群的开发和治理问题，在 2020 年，阿里巴巴与 Apache Dubbo 社区共同合作，基于 Dubbo2 & HSF2 发布了面向云原生架构的下一代服务框架 - Dubbo3，目前，Dubbo3 已经完全升级 HSF2、Dubbo2 成为阿里巴巴内部统一的服务框架，成功的跑在了数十万应用、数百万节点的双十一集群之上。

Dubbo3 吸取了 HSF2 框架所有大规模微服务集群的治理经验，解决了 Dubbo2 架构设计上长期积累的一些缺陷，同时增加了一系列面向云原生架构的新特性。

阿里巴巴结合 HSF 框架的大规模集群实践经验，基于 Apache Dubbo、开源社区需求等推出了面向云原生架构的全新服务框架 - Dubbo3，Dubbo3 在完全兼容之前 API 模式的情况下，完成了彻底的云原生架构升级。
Dubbo 的高度可扩展能力是其广泛适用的重要前提，阿里巴巴基于 Dubbo3 内核维护了一套内部特有的适配插件体系以实现平滑升级，这包括注册中心扩展、路由组件扩展、监控组件扩展等。
几乎所有主流云厂商、主流微服务开源社区都提供了 Dubbo 适配或托管服务。

关于阿里巴巴 Dubbo3 应用的更多细节，请参见博客文章

实现细节

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

初始化过程细节

解析服务

基于 dubbo.jar 内的 META-INF/spring.handlers 配置，Spring 在遇到 dubbo 名称空间时，会回调 DubboNamespaceHandler。

所有 dubbo 的标签，都统一用 DubboBeanDefinitionParser 进行解析，基于一对一属性映射，将 XML 标签解析为 Bean 对象。

在 ServiceConfig.export() 或 ReferenceConfig.get() 初始化时，将 Bean 对象转换 URL 格式，所有 Bean 属性转成 URL 的参数。

然后将 URL 传给协议扩展点，基于扩展点的扩展点自适应机制，根据 URL 的协议头，进行不同协议的服务暴露或引用。

暴露服务

1. 只暴露服务端口：

在没有注册中心，直接暴露提供者的情况下 ¹，ServiceConfig 解析出的 URL 的格式为： dubbo://service-host/com.foo.FooService?version=1.0.0。

基于扩展点自适应机制，通过 URL 的 dubbo:// 协议头识别，直接调用 DubboProtocol的 export() 方法，打开服务端口。

2. 向注册中心暴露服务：

在有注册中心，需要注册提供者地址的情况下 ²，ServiceConfig 解析出的 URL 的格式为: registry://registry-host/org.apache.dubbo.registry.RegistryService?export=URL.encode("dubbo://service-host/com.foo.FooService?version=1.0.0")，

基于扩展点自适应机制，通过 URL 的 registry:// 协议头识别，就会调用 RegistryProtocol 的 export() 方法，将 export 参数中的提供者 URL，先注册到注册中心。

使用 Nacos 作为注册中心实现自动服务发现

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

本示例演示 Nacos 作为注册中心实现自动服务发现，示例基于 Spring Boot 应用展开，可在此查看完整示例代码

1 基本配置

1.1 增加依赖

增加 dubbo、nacos-client 依赖：

<dependencies>
 <dependency>
 <groupId>org.apache.dubbo</groupId>
 <artifactId>dubbo</artifactId>
 <version>3.3.0</version>
 </dependency>
 <dependency>
 <groupId>com.alibaba.nacos</groupId>
 <artifactId>nacos-client</artifactId>
 <version>2.1.0</version>
 </dependency>
</dependencies>

对于 Spring Boot 应用，可以使用如下 spring-boot-starter：

<dependency>
 <groupId>org.apache.dubbo</groupId>
 <artifactId>dubbo-spring-boot-starter</artifactId>
 <version>3.3.0</version>
</dependency>
<dependency>
 <groupId>org.apache.dubbo</groupId>
 <artifactId>dubbo-nacos-spring-boot-starter</artifactId>
 <version>3.3.0</version>
</dependency>

1.2 Nacos 版本

Nacos 版本映射关系：

Dubbo	推荐 Nacos 版本	Nacos 兼容范围
3.3.0	2.2.3	2.x
3.2.21	2.1.0	2.x
3.1.11	2.0.9	2.x
3.0.10	2.0.9	2.x
2.7.21	1.x	1.x
2.6.0	1.x	1.x

1.3 配置并启用 Nacos

# application.yml (Spring Boot)
dubbo
 registry
 address: nacos://localhost:8848
 register-mode: instance # 新用户请设置此值，表示启用应用级服务发现，可选值 interface、instance、all，默认值为 all，未来版本将切换默认值为 instance

或

谈谈扩充式扩展与增量式扩展

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

我们平台的产品越来越多，产品的功能也越来越多。平台的产品为了适应各 BU 和部门以及产品线的需求，势必会将很多不相干的功能凑在一起，客户可以选择性的使用。为了兼容更多的需求，每个产品，每个框架，都在不停的扩展，而我们经常会选择一些扩展的扩展方式，也就是将新旧功能扩展成一个通用实现。我想讨论是，有些情况下也可以考虑增量式的扩展方式，也就是保留原功能的简单性，新功能独立实现。我最近一直做分布式服务框架的开发，就拿我们项目中的问题开涮吧。

比如：远程调用框架，肯定少不了序列化功能，功能很简单，就是把流转成对象，对象转成流。但因有些地方可能会使用 osgi，这样序列化时，IO 所在的 ClassLoader 可能和业务方的 ClassLoader 是隔离的。需要将流转换成 byte[] 数组，然后传给业务方的 ClassLoader 进行序列化。为了适应 osgi 需求，把原来非 osgi 与 osgi 的场景扩展了一下，这样，不管是不是 osgi 环境，都先将流转成 byte[] 数组，拷贝一次。然而，大部分场景都用不上 osgi，却为 osgi 付出了代价。而如果采用增量式扩展方式，非 osgi 的代码原封不动，再加一个 osgi 的实现，要用 osgi 的时候，直接依赖 osgi 实现即可。

再比如：最开始，远程服务都是基于接口方法，进行透明化调用的。这样，扩展接口就是， invoke(Method method, Object[] args)，后来，有了无接口调用的需求，就是没有接口方法也能调用，并将 POJO 对象都转换成 Map 表示。因为 Method 对象是不能直接 new 出来的，我们不自觉选了一个扩展式扩展，把扩展接口改成了 invoke(String methodName, String[] parameterTypes, String returnTypes, Object[] args)，导致不管是不是无接口调用，都得把 parameterTypes 从 Class[] 转成 String[]。如果选用增量式扩展，应该是保持原有接口不变，增加一个 GeneralService 接口，里面有一个通用的 invoke() 方法，和其它正常业务上的接口一样的调用方式，扩展接口也不用变，只是 GeneralServiceImpl 的 invoke() 实现会将收到的调用转给目标接口，这样就能将新功能增量到旧功能上，并保持原来结构的简单性。

再再比如：无状态消息发送，很简单，序列化一个对象发过去就行。后来有了同步消息发送需求，需要一个 Request/Response 进行配对，采用扩展式扩展，自然想到，无状态消息其实是一个没有 Response 的 Request，所以在 Request 里加一个 boolean 状态，表示要不要返回 Response。如果再来一个会话消息发送需求，那就再加一个 Session 交互，然后发现，原来同步消息发送是会话消息的一种特殊情况，所有场景都传 Session，不需要 Session 的地方无视即可。

同机房/区域优先

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

为了保证服务的整体高可用，我们经常会采用把服务部署在多个可用区(机房)的策略，通过这样的冗余/容灾部署模式，当一个区域出现故障的时候，我们仍可以保证服务整体的可用性。

当应用部署在多个不同机房/区域的时候，应用之间相互调用就会出现跨区域的情况，而跨区域调用会增加响应时间，影响用户体验。同机房/区域优先是指应用调用服务时，优先调用同机房/区域的服务提供者，避免了跨区域带来的网络延时，从而减少了调用的响应时间。

开始之前

部署 Shop 商城项目
部署并打开 Dubbo Admin

任务详情

Detail 应用和 Comment 应用都有双区域部署，其中 Detail v1 与 Comment v1 部署在区域 Beijing，Detail v2 与 Comment v2 部署在区域 Hangzhou 区域。为了保证服务调用的响应速度，我们需要增加同区域优先的调用规则，确保 Beijing 区域内的 Detail v1 始终默认调用 Comment v1，Hangzhou 区域内的 Detail v2 始终调用 Comment v2。

当同区域内的服务出现故障或不可用时，则允许跨区域调用。

配置 `Detail` 访问同区域部署的 `Comment` 服务

正常登录商城系统后，首页默认展示商品详情信息，多次刷新页面，发现商品详情 (description) 与评论 (comment) 选项会出现多个不同版本的组合，结合上面 Detail 和 Comment 的部署结构，这说明服务调用并没有遵循同区域优先的原则。

因此，接下来我们需要添加同区域优先规则，保证：

hangzhou 区域的 Detail 服务调用同区域的 Comment 服务，即 description v1 与 comment v1 始终组合展示
beijing 区域的 Detail 服务调用同区域的 Comment 服务，即 description v2 与 comment v2 始终组合展示

操作步骤

登录 Dubbo Admin 控制台
在左侧导航栏选择【服务治理】 > 【条件路由】。
点击 “创建” 按钮，填入要启用同区域优先的服务如 org.apache.dubbo.samples.CommentService 与 区域标识 如 region 即可。

线程模型

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

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

如果事件处理的逻辑能迅速完成，并且不会发起新的 IO 请求，比如只是在内存中记个标识，则直接在 IO 线程上处理更快，因为减少了线程池调度。

但如果事件处理逻辑较慢，或者需要发起新的 IO 请求，比如需要查询数据库，则必须派发到线程池，否则 IO 线程阻塞，将导致不能接收其它请求。

如果用 IO 线程处理事件，又在事件处理过程中发起新的 IO 请求，比如在连接事件中发起登录请求，会报“可能引发死锁”异常，但不会真死锁。

因此，需要通过不同的派发策略和不同的线程池配置的组合来应对不同的场景:

<dubbo:protocol name="dubbo" dispatcher="all" threadpool="fixed" threads="100" />

Dispatcher

all 所有消息都派发到线程池，包括请求，响应，连接事件，断开事件，心跳等。
direct 所有消息都不派发到线程池，全部在 IO 线程上直接执行。
message 只有请求响应消息派发到线程池，其它连接断开事件，心跳等消息，直接在 IO 线程上执行。
execution 只有请求消息派发到线程池，不含响应，响应和其它连接断开事件，心跳等消息，直接在 IO 线程上执行。
connection 在 IO 线程上，将连接断开事件放入队列，有序逐个执行，其它消息派发到线程池。

ThreadPool

fixed 固定大小线程池，启动时建立线程，不关闭，一直持有。(缺省)
cached 缓存线程池，空闲一分钟自动删除，需要时重建。
limited 可伸缩线程池，但池中的线程数只会增长不会收缩。只增长不收缩的目的是为了避免收缩时突然来了大流量引起的性能问题。
eager 优先创建Worker线程池。在任务数量大于corePoolSize但是小于maximumPoolSize时，优先创建Worker来处理任务。当任务数量大于maximumPoolSize时，将任务放入阻塞队列中。阻塞队列充满时抛出RejectedExecutionException。(相比于cached:cached在任务数量超过maximumPoolSize时直接抛出异常而不是将任务放入阻塞队列)

线程模型

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

背景

如果事件处理的逻辑能迅速完成，并且不会发起新的 IO 请求，比如只是在内存中记个标识，则直接在 IO 线程上处理更快，因为减少了线程池调度。

但如果事件处理逻辑较慢，或者需要发起新的 IO 请求，比如需要查询数据库，则必须派发到线程池，否则 IO 线程阻塞，将导致不能接收其它请求。

如果用 IO 线程处理事件，又在事件处理过程中发起新的 IO 请求，比如在连接事件中发起登录请求，会报“可能引发死锁”异常，但不会真死锁。

示例

因此，需要通过不同的派发策略和不同的线程池配置的组合来应对不同的场景:

<dubbo:protocol name="dubbo" dispatcher="all" threadpool="fixed" threads="100" />

Dispatcher

all 所有消息都派发到线程池，包括请求，响应，连接事件，断开事件，心跳等。
direct 所有消息都不派发到线程池，全部在 IO 线程上直接执行。
message 只有请求响应消息派发到线程池，其它连接断开事件，心跳等消息，直接在 IO 线程上执行。
execution 只有请求消息派发到线程池，不含响应，响应和其它连接断开事件，心跳等消息，直接在 IO 线程上执行。
connection 在 IO 线程上，将连接断开事件放入队列，有序逐个执行，其它消息派发到线程池。

ThreadPool

fixed 固定大小线程池，启动时建立线程，不关闭，一直持有。(缺省)
cached 缓存线程池，空闲一分钟自动删除，需要时重建。
limited 可伸缩线程池，但池中的线程数只会增长不会收缩。只增长不收缩的目的是为了避免收缩时突然来了大流量引起的性能问题。
eager 优先创建Worker线程池。在任务数量大于corePoolSize但是小于maximumPoolSize时，优先创建Worker来处理任务。当任务数量大于maximumPoolSize时，将任务放入阻塞队列中。阻塞队列充满时抛出RejectedExecutionException。(相比于cached:cached在任务数量超过maximumPoolSize时直接抛出异常而不是将任务放入阻塞队列)

序列化配置项

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

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

当前该库只实现了 dubbo:// 通讯协议。

序列化方式实现了 hessian 和 json 两种方式。

配置样例

序列化配置需要添加到 sys.config 文件 dubboerl 应用配置项里。

{dubboerl,[
	%% other config ...
	{protocol,hessian}
]}

ConfigName	Type	DefaultValue	Remarks
protocol	atom()	hessian	hessian,json

序列化配置项

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

当前该库只实现了 dubbo:// 通讯协议。

序列化方式实现了 hessian 和 json 两种方式。

配置样例

序列化配置需要添加到 sys.config 文件 dubboerl 应用配置项里。

{dubboerl,[
	%% other config ...
	{protocol,hessian}
]}

ConfigName	Type	DefaultValue	Remarks
protocol	atom()	hessian	hessian,json

序列化配置项

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

当前该库只实现了 dubbo:// 通讯协议。

序列化方式实现了 hessian 和 json 两种方式。

配置样例

序列化配置需要添加到 sys.config 文件 dubboerl 应用配置项里。

{dubboerl,[
	%% other config ...
	{protocol,hessian}
]}

ConfigName	Type	DefaultValue	Remarks
protocol	atom()	hessian	hessian,json

用法

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

本地服务 Spring 配置

local.xml

<bean id=“xxxService” class=“com.xxx.XxxServiceImpl” />
<bean id=“xxxAction” class=“com.xxx.XxxAction”>
 <property name=“xxxService” ref=“xxxService” />
</bean>

远程服务 Spring 配置

在本地服务的基础上，只需做简单配置，即可完成远程化：

将上面的 local.xml 配置拆分成两份，将服务定义部分放在服务提供方 remote-provider.xml，将服务引用部分放在服务消费方 remote-consumer.xml。
并在提供方增加暴露服务配置 <dubbo:service>，在消费方增加引用服务配置 <dubbo:reference>。

remote-provider.xml

<!-- 和本地服务一样实现远程服务 -->
<bean id=“xxxService” class=“com.xxx.XxxServiceImpl” /> 
<!-- 增加暴露远程服务配置 -->
<dubbo:service interface=“com.xxx.XxxService” ref=“xxxService” />

remote-consumer.xml

<!-- 增加引用远程服务配置 -->
<dubbo:reference id=“xxxService” interface=“com.xxx.XxxService” />
<!-- 和本地服务一样使用远程服务 -->
<bean id=“xxxAction” class=“com.xxx.XxxAction”> 
 <property name=“xxxService” ref=“xxxService” />
</bean>

动态指定 IP 调用

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

特性说明

在发起 RPC 请求的时候，需要指定本次调用的服务端，常用的场景包括消息回调、流量隔离等。

使用方式

插件依赖

首先，需要添加以下插件依赖到项目中

<dependency>
 <groupId>org.apache.dubbo.extensions</groupId>
 <artifactId>dubbo-cluster-specify-address-dubbo3</artifactId>
 <version>3.3.0</version>
</dependency>

适配 Dubbo 2 版本

<dependency>
 <groupId>org.apache.dubbo.extensions</groupId>
 <artifactId>dubbo-cluster-specify-address-dubbo2</artifactId>
 <version>1.0.0</version>
</dependency>

调用示例

ReferenceConfig<DemoService> referenceConfig = new ReferenceConfig<>();
// ... init
DemoService demoService = referenceConfig.get();

// for invoke
// 1. find 10.10.10.10:20880 exist
// 2. if not exist, create a invoker to 10.10.10.10:20880 if `needToCreate` is true (only support in Dubbo 3.x's implementation)
UserSpecifiedAddressUtil.setAddress(new Address("10.10.10.10", 20880, true));
demoService.sayHello("world");


// for invoke
// 1. find 10.10.10.10:any exist
// 2. if not exist, create a invoker to 10.10.10.10:20880 if `needToCreate` is true (only support in Dubbo 3.x's implementation)
UserSpecifiedAddressUtil.setAddress(new Address("10.10.10.10", 0, true));
demoService.sayHello("world");

参数说明

指定 IP 调用的参数围绕 Address 对象展开。参数类型参考如下：

注解配置

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, 30 Jan 2023 00:00:00 +0000

整体介绍

本文所说的柔性服务主要是指consumer端的负载均衡和provider端的限流两个功能。在之前的dubbo版本中，

负载均衡部分更多的考虑的是公平性原则，即consumer端尽可能平等的从provider中作出选择，在某些情况下表现并不够理想。
限流部分只提供了静态的限流方案，需要用户对provider端设置静态的最大并发值，然而该值的合理选取对用户来讲并不容易。

我们针对这些存在的问题进行了改进。

负载均衡

使用介绍

在原本的dubbo版本中，有五种负载均衡的方案供选择，他们分别是 Random、ShortestResponse、RoundRobin、LeastActive 和 ConsistentHash。其中除 ShortestResponse 和 LeastActive 外，其他的几种方案主要是考虑选择时的公平性和稳定性。

对于 ShortestResponse 来说，其设计目的是从所有备选的 provider 中选择 response 时间最短的以提高系统整体的吞吐量。然而存在两个问题：

在大多数的场景下，不同provider的response时长没有非常明显的区别，此时该算法会退化为随机选择。
response的时间长短有时也并不能代表机器的吞吐能力。对于 LeastActive 来说，其认为应该将流量尽可能分配到当前并发处理任务较少的机器上。但是其同样存在和 ShortestResponse 类似的问题，即这并不能单独代表机器的吞吐能力。

基于以上分析，我们提出了两种新的负载均衡算法。一种是同样基于公平性考虑的单纯 P2C 算法，另一种是基于自适应的方法 adaptive，其试图自适应的衡量 provider 端机器的吞吐能力，然后将流量尽可能分配到吞吐能力高的机器上，以提高系统整体的性能。

总体效果

对于负载均衡部分的有效性实验在两个不同的情况下进行的，分别是提供端机器配置比较均衡和提供端机器配置差距较大的情况。

使用方法

Dubbo Java 实现的使用方法与原本的负载均衡方法相同。只需要在consumer端将"loadbalance"设置为"p2c"或者"adaptive"即可。

代码结构

负载均衡部分的算法实现只需要在原本负载均衡框架内继承 LoadBalance接口即可。

原理介绍

P2C算法

Power of Two Choice 算法简单但是经典，主要思路如下：

对于每次调用，从可用的provider列表中做两次随机选择，选出两个节点providerA和providerB。
比较providerA和providerB两个节点，选择其“当前正在处理的连接数”较小的那个节点。

adaptive算法

代码的github地址

平安健康的 Dubbo3 迁移历程

Sun, 15 Jan 2023 00:00:00 +0000

1 背景

我们公司从15年开始就使⽤dubbo作为微服务框架，当社区推出dubbo3时，我们也⽴刻跟进并做了深⼊调研，发现dubbo3 的应⽤/实例级服务注册和发现模式能够在一定程度上解决我们当前注册中⼼⾯临的压⼒，解决稳定性和安全性问题。同时dubbo3在服务治理上也做了升级，契合云原⽣架构，⽽且dubbo3能够向下兼容dubbo2，这也将降低升级的成本和⻛险。

升级项目有了阶段性的进展，目前仍然在进行中。通过本⽂，我们对公司内部的Dubbo3 升级过程及收益等做了深⼊总结。

2 Dubbo3 核⼼功能介绍

dubbo社区关于dubbo3的文档和资料越来越完善，以下是我们从社区引用的一些内容。

2.1 下一代云原生服务框架

Dubbo3被社区寄予厚望，将其视为下一代云原生服务框架打造，Dubbo3 提供的核心特性列表，主要包括四部分。

全新服务发现模型 。应用粒度服务发现，面向云原生设计，适配基础设施与异构系统；性能与集群伸缩性大幅提升。
**下一代 **** RPC **协议 Triple 。基于 HTTP/2 的 Triple 协议，兼容 gRPC；网关穿透性强、多语言友好、支持 Reactive Stream。
统一流量治理模型 。面向云原生流量治理，SDK、Mesh、VM、Container 等统一治理规则；能够支持更丰富的流量治理场景。
Service Mesh 。在最新的3.1.0的版本中支持Sidecar Mesh 与 Proxyless Mesh，提供更多架构选择，降低迁移、落地成本。

首先是性能、资源利用率的提升。社区资料显示，升级 Dubbo3 的应用预期能实现单机内存 50% 的下降，对于越大规模的集群效果将越明显，Dubbo3 从架构上支持百万实例级别的集群横向扩展,同时依赖应用级服务发现、Triple协议等可以大大提供应用的服务治理效率和吞吐量。

其次， Dubbo3 让业务架构升级变得更容易、更合理，尤其是RPC协议，在 2.x 版本中，web、移动端与后端的通信都要经过网关代理，完成协议转换、类型映射等工作，dubbo3的Triple 协议让这些变得更容易与自然；并通过流式通信模型满足更多的使用场景。

最后，得益于 Dubbo3 的完善云原生解决方案，Dubbo3的mesh架构可以帮助业务屏蔽底层云原生基础设施细节，让业务更专注于业务，这也是mesh的最根本的优势。

2.2 应用级服务发现核心原理

我们从 Dubbo 最经典的工作原理图说起，Dubbo 从设计之初就内置了服务地址发现的能力，Provider 注册地址到注册中心，Consumer 通过订阅实时获取注册中心的地址更新，在收到地址列表后，consumer 基于特定的负载均衡策略发起对 provider 的 RPC 调用。在这个过程中

0-5 - 缓存文件大小超限

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

其它模块复用了 Common 层的基于文件的缓存机制（目前是元数据模块），而 Common 层的文件缓存机制 “发觉” 文件大小超限。

可能的原因

用户不合理地配置了 Java System Property （用 -D 配置的 Java 系统属性） dubbo.mapping.cache.maxFileSize 或者 dubbo.meta.cache.maxFileSize
缓存文件因文件系统或磁盘错误而被破坏。

dubbo.mapping.cache.maxFileSize 和 dubbo.meta.cache.maxFileSize 没有显示默认值，而根据 org.apache.dubbo.common.cache.FileCacheStore.LimitedLengthBufferedWriter 的逻辑而查到的最大文件大小的默认值为：Long.MAX_VALUE ( 2⁶³-1 ) 。

排查和解决步骤

尝试重新配置上述 Java System Property（用 -D 配置的 Java 系统属性）。
删除缓存文件夹重启 Provider 和 Consumer （缓存文件夹的位置一般在 ~/.dubbo。如果配置了 dubbo.meta.cache.filePath 和 dubbo.mapping.cache.filePath 则为该路径）。
如果确实没有配置这些 System Property，请到 GitHub Issue Tracker 下发 Issue。

1-5 - 接收到没有任何参数的 URL

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

可能的原因

在调用 CacheableFailbackRegistry.toUrlsWithoutEmpty 时，若传入的参数 Collection<String>providers 中存在某个 provider 其没有任何参数的话，就会接收到没有任何参数的 URL。

排查和解决步骤

该错误为 Dubbo 内部错误，如果您遇到可以在 github 创建 Issue 并提供错误信息以及复现步骤，我们将协助您解决问题。

另请参阅 Dubbo社区

2-5 - 筛选提供方失败

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

可能的原因

Dubbo 在负载均衡时会从提供方列表中最终选择一个提供方发起调用，在选择过程中提供方列表变动，发生读写冲突，导致筛选异常。
Dubbo 重试机制在调用提供方失败时，会重新筛选另一个提供方发起调用，重新筛选过程发生异常。

排查和解决步骤

检查注册中心提供方列表，与对应提供方可用性。
在社区提 Issue，提供环境现场信息及复现步骤。

3-5 - 异步响应出现异常

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

可能的原因

业务逻辑确实出现运行时异常。
网络原因，连接被拒绝。

排查和解决步骤

业务代码请根据堆栈提示行，回溯定位排查。
检查服务提供方的网络是否正常。

4-5 - 流关闭异常

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

可能的原因

提示信息，不影响程序的执行结果。

排查和解决步骤

可通过一些第三方的工具或者jstack [PID] > jstack.log 分析堆栈信息，进行定位。

5-5 - 无法获得env变量

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

可能的原因

环境变量无法获取。

排查和解决步骤

检查提示的变量名，是否配置并可以正常读取加载。

6-5 - 网络连接断开失败

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

可能的原因

超时是调用端发生在请求发出后，无法在指定的时间内获得对应的响应，出现客户端主动断开连接

排查和解决步骤

一般为提示类警告信息，不影响后续的程序执行。

7-5 - QOS 命令未找到

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

可能的原因

QOS 命令拼写错误。

排查和解决步骤

QOS 命令不存在。

请参考 QOS 操作手册基础命令手册。

Avro

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

1 介绍

Avro是一种远程过程调用和数据序列化框架，是在Apache的Hadoop项目之内开发的。它使用JSON来定义数据类型和通讯协议，使用压缩二进制格式来序列化数据。它主要用于Hadoop，它可以为持久化数据提供一种序列化格式，并为Hadoop节点间及从客户端程序到Hadoop服务的通讯提供一种电报格式。

2 使用方式

2.1 添加依赖

<dependencies>
 <dependency>
 <groupId>org.apache.dubbo.extensions</groupId>
 <artifactId>dubbo-serialization-avro</artifactId>
 <version>3.3.0</version>
 </dependency>
 <dependency>
 <groupId>org.apache.avro</groupId>
 <artifactId>avro</artifactId>
 <version>1.11.1</version>
 </dependency>
</dependencies>

2.2 配置启用

# application.yml (Spring Boot)
dubbo:
 protocol:
 serialization: avro

或

# dubbo.properties
dubbo.protocol.serialization=avro

# or
dubbo.consumer.serialization=avro

# or
dubbo.reference.com.demo.DemoService.serialization=avro

或

<dubbo:protocol serialization="avro" />

<!-- or -->
<dubbo:consumer serialization="avro" />

<!-- or -->
<dubbo:reference interface="xxx" serialization="avro" />

Consul

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

前置条件

了解 Dubbo 基本开发步骤
安装并启动 Consul 服务

使用说明

添加依赖

从 Dubbo3 开始，consul 注册中国适配已经不再内嵌在 Dubbo 中，使用前需要单独引入独立的模块。

<dependency>
 <groupId>org.apache.dubbo.extensions</groupId>
 <artifactId>dubbo-registry-consul</artifactId>
 <version>3.3.0</version>
</dependency>

基本配置

<dubbo:registry address="redis://10.20.153.10:6379" />

或

<dubbo:registry address="redis://10.20.153.10:6379?backup=10.20.153.11:6379,10.20.153.12:6379" />

或

<dubbo:registry protocol="redis" address="10.20.153.10:6379" />

或

<dubbo:registry protocol="redis" address="10.20.153.10:6379,10.20.153.11:6379,10.20.153.12:6379" />

使用场景

使用 Consul 作为共享注册中心实现，可用于 Dubbo 与 Spring Cloud 体系的互通或迁移

Etcd

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

前置条件

了解 Dubbo 基本开发步骤
安装并启动 Etcd 服务

使用说明

添加依赖

从 Dubbo3 开始，etcd 注册中心适配已经不再内嵌在 Dubbo 中，使用前需要单独引入独立的模块。

<dependency>
 <groupId>org.apache.dubbo.extensions</groupId>
 <artifactId>dubbo-registry-etcd</artifactId>
 <version>3.3.0</version>
</dependency>

基本配置

<dubbo:registry address="etcd://10.20.153.10:6379" />

或

<dubbo:registry address="etcd://10.20.153.10:6379?backup=10.20.153.11:6379,10.20.153.12:6379" />

或

<dubbo:registry protocol="etcd" address="10.20.153.10:6379" />

或

<dubbo:registry protocol="etcd" address="10.20.153.10:6379,10.20.153.11:6379,10.20.153.12:6379" />

gRPC 协议

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

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

Dubbo 自 2.7.5 版本开始支持 gRPC 协议，对于计划使用 HTTP/2 通信，或者想利用 gRPC 带来的 Stream、反压、Reactive 编程等能力的开发者来说，都可以考虑启用 gRPC 协议。

支持 gRPC 的好处

为期望使用 gRPC 协议的用户带来服务治理能力，方便接入 Dubbo 体系
用户可以使用 Dubbo 风格的，基于接口的编程风格来定义和使用远程服务

如何在 Dubbo 中使用 gRPC

大概需要以下步骤：

使用 IDL 定义服务
配置 compiler 插件，本地预编译
配置暴露/引用 Dubbo 服务

具体可参见以下示例

除了原生 StreamObserver 接口类型之外，Dubbo 还支持 RxJava、Reactor 编程风格的 API

gRPC 协议

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

支持 gRPC 的好处

为期望使用 gRPC 协议的用户带来服务治理能力，方便接入 Dubbo 体系
用户可以使用 Dubbo 风格的，基于接口的编程风格来定义和使用远程服务

如何在 Dubbo 中使用 gRPC

大概需要以下步骤：

使用 IDL 定义服务
配置 compiler 插件，本地预编译
配置暴露/引用 Dubbo 服务

具体可参见以下示例

除了原生 StreamObserver 接口类型之外，Dubbo 还支持 RxJava、Reactor 编程风格的 API

Memcached 协议

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

基于 memcached ¹ 实现的 RPC 协议。

提示

2.3.0 以上版本支持

注册 memcached 服务的地址

RegistryFactory registryFactory = ExtensionLoader.getExtensionLoader(RegistryFactory.class).getAdaptiveExtension();
Registry registry = registryFactory.getRegistry(URL.valueOf("zookeeper://10.20.153.10:2181"));
registry.register(URL.valueOf("memcached://10.20.153.11/com.foo.BarService?category=providers&dynamic=false&application=foo&group=member&loadbalance=consistenthash"));

在客户端引用

在客户端使用 ²：

<dubbo:reference id="cache" interface="java.util.Map" group="member" />

或者，点对点直连：

<dubbo:reference id="cache" interface="java.util.Map" url="memcached://10.20.153.10:11211" />

也可以使用自定义接口：

<dubbo:reference id="cache" interface="com.foo.CacheService" url="memcached://10.20.153.10:11211" />

方法名建议和 memcached 的标准方法名相同，即：get(key), set(key, value), delete(key)。

如果方法名和 memcached 的标准方法名不相同，则需要配置映射关系 ³：

<dubbo:reference id="cache" interface="com.foo.CacheService" url="memcached://10.20.153.10:11211" p:set="putFoo" p:get="getFoo" p:delete="removeFoo" />

Memcached 是一个高效的 KV 缓存服务器 ↩︎
不需要感知 Memcached 的地址 ↩︎
其中 “p:xxx” 为 spring 的标准 p 标签 ↩︎

memcached 协议

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

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

基于 memcached ¹ 实现的 RPC 协议。

提示

2.3.0 以上版本支持

注册 memcached 服务的地址

RegistryFactory registryFactory = ExtensionLoader.getExtensionLoader(RegistryFactory.class).getAdaptiveExtension();
Registry registry = registryFactory.getRegistry(URL.valueOf("zookeeper://10.20.153.10:2181"));
registry.register(URL.valueOf("memcached://10.20.153.11/com.foo.BarService?category=providers&dynamic=false&application=foo&group=member&loadbalance=consistenthash"));

在客户端引用

在客户端使用 ²：

<dubbo:reference id="cache" interface="java.util.Map" group="member" />

或者，点对点直连：

<dubbo:reference id="cache" interface="java.util.Map" url="memcached://10.20.153.10:11211" />

也可以使用自定义接口：

<dubbo:reference id="cache" interface="com.foo.CacheService" url="memcached://10.20.153.10:11211" />

方法名建议和 memcached 的标准方法名相同，即：get(key), set(key, value), delete(key)。

如果方法名和 memcached 的标准方法名不相同，则需要配置映射关系 ³：

<dubbo:reference id="cache" interface="com.foo.CacheService" url="memcached://10.20.153.10:11211" p:set="putFoo" p:get="getFoo" p:delete="removeFoo" />

Memcached 是一个高效的 KV 缓存服务器 ↩︎
不需要感知 Memcached 的地址 ↩︎
其中 “p:xxx” 为 spring 的标准 p 标签 ↩︎

memcached 协议

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

基于 memcached ¹ 实现的 RPC 协议。

提示

2.3.0 以上版本支持

注册 memcached 服务的地址

RegistryFactory registryFactory = ExtensionLoader.getExtensionLoader(RegistryFactory.class).getAdaptiveExtension();
Registry registry = registryFactory.getRegistry(URL.valueOf("zookeeper://10.20.153.10:2181"));
registry.register(URL.valueOf("memcached://10.20.153.11/com.foo.BarService?category=providers&dynamic=false&application=foo&group=member&loadbalance=consistenthash"));

在客户端引用

在客户端使用 ²：

<dubbo:reference id="cache" interface="java.util.Map" group="member" />

或者，点对点直连：

<dubbo:reference id="cache" interface="java.util.Map" url="memcached://10.20.153.10:11211" />

也可以使用自定义接口：

<dubbo:reference id="cache" interface="com.foo.CacheService" url="memcached://10.20.153.10:11211" />

方法名建议和 memcached 的标准方法名相同，即：get(key), set(key, value), delete(key)。

如果方法名和 memcached 的标准方法名不相同，则需要配置映射关系 ³：

<dubbo:reference id="cache" interface="com.foo.CacheService" url="memcached://10.20.153.10:11211" p:set="putFoo" p:get="getFoo" p:delete="removeFoo" />

Memcached 是一个高效的 KV 缓存服务器 ↩︎
不需要感知 Memcached 的地址 ↩︎
其中 “p:xxx” 为 spring 的标准 p 标签 ↩︎

Nacos

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

本文档讲解如何安装与配置 Nacos，涵盖本地、docker、kubernetes 等环境。以下仅为快速示例安装指南，如想搭建生产可用集群请参考 Nacos 官方文档。

本地下载

Nacos 依赖 Java 环境来运行，目前支持 Linux、MacOS、Windows 等环境。

您可以下载最新稳定版本 Nacos，解压缩二进制包：

unzip nacos-server-$version.zip
cd nacos/bin
#tar -xvf nacos-server-$version.tar.gz

启动命令

# Linux/Unix/Mac
sh startup.sh -m standalone

# Ubuntu
bash startup.sh -m standalone

# Windows
startup.cmd -m standalone

验证 nacos 正常启动

通过浏览器访问以下链接打开控制台：http://127.0.0.1:8080/index.html

docker

下载 nacos-docker 项目。

git clone https://github.com/nacos-group/nacos-docker.git
cd nacos-docker

执行 docker-compose 命令启动Nacos。

docker-compose -f example/standalone-derby.yaml up

kubernetes

下载 nacos-k8s 项目

git clone https://github.com/nacos-group/nacos-k8s.git
cd nacos-k8s

快速启动（注意：使用此方式快速启动,请注意这是没有使用持久化卷的,可能存在数据丢失风险）

OpenAPI 文档生成与管理

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

Dubbo-go 提供了内置的 OpenAPI 支持，可以自动为 Triple 协议服务生成符合 OpenAPI 3.0 规范的 API 文档，并通过 Swagger UI 和 ReDoc 提供可视化的 API 浏览与调试界面。

功能概览

自动文档生成：基于服务接口定义（protobuf IDL 或非 IDL 模式），自动生成 OpenAPI 3.0.1 规范的 API 文档
Swagger UI：内置 Swagger UI 界面，支持在线浏览和调试 API
ReDoc：内置 ReDoc 界面，提供美观的 API 文档展示
多格式输出：支持 JSON 和 YAML 两种格式输出
分组管理：支持按 OpenAPI Group 对服务进行分组，方便管理多个版本的 API 文档
静态文档生成：通过 protoc-gen-triple-openapi 插件，在编译期从 .proto 文件生成静态 OpenAPI 文档

快速开始

1. 启用 OpenAPI

在创建 Server 时，通过 Triple 协议选项启用 OpenAPI：

package main

import (
 "dubbo.apache.org/dubbo-go/v3/protocol"
 triple "dubbo.apache.org/dubbo-go/v3/protocol/triple"
 "dubbo.apache.org/dubbo-go/v3/server"
)

func main() {
 srv, err := server.NewServer(
 server.WithServerProtocol(
 protocol.WithTriple(
 triple.WithOpenAPI(
 triple.OpenAPIEnable(),
 ),
 ),
 protocol.WithPort(20000),
 ),
 )
 if err != nil {
 panic(err)
 }
 // 注册服务...
 srv.Serve()
}

启动服务后，即可通过以下地址访问 OpenAPI 文档：

Redis

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

前置条件

了解 Dubbo 基本开发步骤
安装并启动 Redis 服务

使用说明

添加依赖

从 Dubbo3 开始，redis 注册中心适配已经不再内嵌在 Dubbo 中，使用前需要单独引入独立的模块。

<dependency>
 <groupId>org.apache.dubbo.extensions</groupId>
 <artifactId>dubbo-registry-redis</artifactId>
 <version>3.3.0</version>
</dependency>

基本配置

<dubbo:registry address="redis://10.20.153.10:6379" />

或

<dubbo:registry address="redis://10.20.153.10:6379?backup=10.20.153.11:6379,10.20.153.12:6379" />

或

<dubbo:registry protocol="redis" address="10.20.153.10:6379" />

或

<dubbo:registry protocol="redis" address="10.20.153.10:6379,10.20.153.11:6379,10.20.153.12:6379" />

其他配置项

可通过 <dubbo:registry group="dubbo" /> 设置 redis 中 key 的前缀，缺省为 dubbo。
可通过 <dubbo:registry cluster="replicate" /> 设置 redis 集群策略，缺省为 failover：
- failover: 只写入和读取任意一台，失败时重试另一台，需要服务器端自行配置数据同步
- replicate: 在客户端同时写入所有服务器，只读取单台，服务器端不需要同步，注册中心集群增大，性能压力也会更大

工作原理

基于 Redis [^1] 实现的注册中心。

Redis 过期数据通过心跳的方式检测脏数据，服务器时间必须同步，并且对服务器有一定压力，否则过期检测会不准确

使用 Redis 的 Key/Map 结构存储数据结构：

主 Key 为服务名和类型
Map 中的 Key 为 URL 地址
Map 中的 Value 为过期时间，用于判断脏数据，脏数据由监控中心删除 [^3]

使用 Redis 的 Publish/Subscribe 事件通知数据变更：

rmi 协议

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

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

RMI 协议采用 JDK 标准的 java.rmi.* 实现，采用阻塞式短连接和 JDK 标准序列化方式。

注意：如果正在使用 RMI 提供服务给外部访问 ¹，同时应用里依赖了老的 common-collections 包 ² 的情况下，存在反序列化安全风险 ³。

特性

连接个数：多连接
连接方式：短连接
传输协议：TCP
传输方式：同步传输
序列化：Java 标准二进制序列化
适用范围：传入传出参数数据包大小混合，消费者与提供者个数差不多，可传文件。
适用场景：常规远程服务方法调用，与原生RMI服务互操作

约束

参数及返回值需实现 Serializable 接口
dubbo 配置中的超时时间对 RMI 无效，需使用 java 启动参数设置：-Dsun.rmi.transport.tcp.responseTimeout=3000，参见下面的 RMI 配置

RMI配置

java -Dsun.rmi.transport.tcp.responseTimeout=3000

更多 RMI 优化参数请查看 JDK 文档

接口

如果服务接口继承了 java.rmi.Remote 接口，可以和原生 RMI 互操作，即：

提供者用 Dubbo 的 RMI 协议暴露服务，消费者直接用标准 RMI 接口调用，
或者提供方用标准 RMI 暴露服务，消费方用 Dubbo 的 RMI 协议调用。

如果服务接口没有继承 java.rmi.Remote 接口：

缺省 Dubbo 将自动生成一个 com.xxx.XxxService$Remote 的接口，并继承 java.rmi.Remote 接口，并以此接口暴露服务，
但如果设置了 <dubbo:protocol name="rmi" codec="spring" />，将不生成 $Remote 接口，而使用 Spring 的 RmiInvocationHandler 接口暴露服务，和 Spring 兼容。

配置

定义 RMI 协议：

rmi 协议

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

RMI 协议采用 JDK 标准的 java.rmi.* 实现，采用阻塞式短连接和 JDK 标准序列化方式。

注意：如果正在使用 RMI 提供服务给外部访问 ¹，同时应用里依赖了老的 common-collections 包 ² 的情况下，存在反序列化安全风险 ³。

特性

连接个数：多连接
连接方式：短连接
传输协议：TCP
传输方式：同步传输
序列化：Java 标准二进制序列化
适用范围：传入传出参数数据包大小混合，消费者与提供者个数差不多，可传文件。
适用场景：常规远程服务方法调用，与原生RMI服务互操作

约束

参数及返回值需实现 Serializable 接口
dubbo 配置中的超时时间对 RMI 无效，需使用 java 启动参数设置：-Dsun.rmi.transport.tcp.responseTimeout=3000，参见下面的 RMI 配置

dubbo.properties 配置

dubbo.service.protocol=rmi

RMI配置

java -Dsun.rmi.transport.tcp.responseTimeout=3000

更多 RMI 优化参数请查看 JDK 文档

接口

如果服务接口继承了 java.rmi.Remote 接口，可以和原生 RMI 互操作，即：

提供者用 Dubbo 的 RMI 协议暴露服务，消费者直接用标准 RMI 接口调用，
或者提供方用标准 RMI 暴露服务，消费方用 Dubbo 的 RMI 协议调用。

如果服务接口没有继承 java.rmi.Remote 接口：

缺省 Dubbo 将自动生成一个 com.xxx.XxxService$Remote 的接口，并继承 java.rmi.Remote 接口，并以此接口暴露服务，
但如果设置了 <dubbo:protocol name="rmi" codec="spring" />，将不生成 $Remote 接口，而使用 Spring 的 RmiInvocationHandler 接口暴露服务，和 Spring 兼容。

配置

定义 RMI 协议：

Simple 监控中心安装

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

不再单独提供监控中心，功能会整合到运维控制台，基于Metrics提供更丰富，实时的信息展示，敬请期待

Tripe 3.3 新特性

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

全新的 Rest 支持

特性

在3.3版本中，基于现有 HTTP 协议栈，triple实现了全面的 REST 风格服务导出能力，无需使用泛化或网关层协议转换，无需配置，用户即可通过 HTTP 协议去中心化直接访问后端的 Triple 协议服务。同时，针对高级 REST 用法，如路径定制、输出格式定制和异常处理，提供了丰富的注解和 SPI 扩展支持。其主要特性包括：

Triple协议融合
重用Triple原有HTTP协议栈，无需额外配置或新增端口，即可同时支持 HTTP/1、HTTP/2 和 HTTP/3 协议的访问。
去中心化
可直接对外暴露 Rest API，不再依赖网关应用进行流量转发，从而提升性能，并降低因网关引发的稳定性风险。安全问题可通过应用内部扩展解决，这一实践已在淘宝内部的 MTOP 中得到验证。
支持已有servlet设施
支持 Servlet API 和 Filter，用户可以重用现有基于 Servlet API 的安全组件。通过实现一个 Servlet Filter，即可集成 OAuth 和 Spring Security 等安全框架。
多种方言
考虑到大部分用户习惯使用 SpringMVC 或 JAX-RS 进行 REST API 开发，Triple Rest 允许继续沿用这些方式定义服务，并支持大部分扩展和异常处理机制（具备原框架 80% 以上的功能）。对于追求轻量级的用户，可使用 Basic 方言，Triple 的开箱即用 REST 访问能力即基于此方言导出服务。
扩展能力强
提供超过 20 个扩展点，用户不仅可以轻松实现自定义方言，还能灵活定制参数获取、类型转换、错误处理等逻辑。
开箱即用
REST 能力开箱即用，只需启用 Triple 协议，即具备 REST 直接访问服务能力。
高性能路由
路由部分采用优化的 Radix Tree 和 Zero Copy 技术，提升路由性能。
OpenAPI无缝集成(TBD)
即将完成 OpenAPI 集成，开箱即用支持导出 OpenAPI Schema，引入 Swagger 依赖可直接使用 Web UI 来进行服务测试。有了 OpenAPI Schema 可使用 Postman、Apifox 等API工具来管理和测试 API，利用 OpenAPI 生态可轻松实现跨语言调用。未来会进一步支持 Schema First 的方式，先和前端团队一起定义 OpenAPI, 前端基于 OpenAPI 来生成调用代码和 Mock，后端基于 OpenAPI 来生成 Stub 来开发服务，极大提升协同效率。

示例

webservice 协议

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

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

基于 WebService 的远程调用协议，基于 Apache CXF ¹ 的 frontend-simple 和 transports-http 实现。

提示

2.3.0 以上版本支持

可以和原生 WebService 服务互操作，即：

提供者用 Dubbo 的 WebService 协议暴露服务，消费者直接用标准 WebService 接口调用，
或者提供方用标准 WebService 暴露服务，消费方用 Dubbo 的 WebService 协议调用。

依赖

<dependency>
 <groupId>org.apache.cxf</groupId>
 <artifactId>cxf-rt-frontend-simple</artifactId>
 <version>2.6.1</version>
</dependency>
<dependency>
 <groupId>org.apache.cxf</groupId>
 <artifactId>cxf-rt-transports-http</artifactId>
 <version>2.6.1</version>
</dependency>

特性

连接个数：多连接
连接方式：短连接
传输协议：HTTP
传输方式：同步传输
序列化：SOAP 文本序列化
适用场景：系统集成，跨语言调用

约束

参数及返回值需实现 Serializable 接口
参数尽量使用基本类型和 POJO

配置

配置协议：

<dubbo:protocol name="webservice" port="8080" server="jetty" />

配置默认协议：

<dubbo:provider protocol="webservice" />

配置服务协议：

<dubbo:service protocol="webservice" />

多端口：

webservice 协议

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

基于 WebService 的远程调用协议，基于 Apache CXF ¹ 的 frontend-simple 和 transports-http 实现。

提示

2.3.0 以上版本支持

可以和原生 WebService 服务互操作，即：

提供者用 Dubbo 的 WebService 协议暴露服务，消费者直接用标准 WebService 接口调用，
或者提供方用标准 WebService 暴露服务，消费方用 Dubbo 的 WebService 协议调用。

依赖

<dependency>
 <groupId>org.apache.cxf</groupId>
 <artifactId>cxf-rt-frontend-simple</artifactId>
 <version>2.6.1</version>
</dependency>
<dependency>
 <groupId>org.apache.cxf</groupId>
 <artifactId>cxf-rt-transports-http</artifactId>
 <version>2.6.1</version>
</dependency>

特性

连接个数：多连接
连接方式：短连接
传输协议：HTTP
传输方式：同步传输
序列化：SOAP 文本序列化
适用场景：系统集成，跨语言调用

约束

参数及返回值需实现 Serializable 接口
参数尽量使用基本类型和 POJO

配置

配置协议：

<dubbo:protocol name="webservice" port="8080" server="jetty" />

配置默认协议：

<dubbo:provider protocol="webservice" />

配置服务协议：

<dubbo:service protocol="webservice" />

多端口：

<dubbo:protocol id="webservice1" name="webservice" port="8080" />
<dubbo:protocol id="webservice2" name="webservice" port="8081" />

直连：

部署架构（注册中心配置中心元数据中心）

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

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

注册中心。协调 Consumer 与 Provider 之间的地址注册与发现
配置中心。
- 存储 Dubbo 启动阶段的全局配置，保证配置的跨环境共享与全局一致性
- 负责服务治理规则（路由规则、动态配置等）的存储与推送。
元数据中心。
- 接收 Provider 上报的服务接口元数据，为 Admin 等控制台提供运维能力（如服务测试、接口文档等）
- 作为服务发现机制的补充，提供额外的接口/方法级别配置信息的同步能力，相当于注册中心的额外扩展

上图完整的描述了 Dubbo 微服务组件与各个中心的交互过程。

以上三个中心并不是运行 Dubbo 的必要条件，用户完全可以根据自身业务情况决定只启用其中一个或多个，以达到简化部署的目的。通常情况下，所有用户都会以独立的注册中心开始 Dubbo 服务开发，而配置中心、元数据中心则会在微服务演进的过程中逐步的按需被引入进来。

注册中心

在传统的Dubbo SDK使用姿势中，如果仅仅提供直连模式的RPC服务，不需要部署注册中心。
无论是接口级别还是应用级别，如果需要Dubbo SDK自身来做服务注册和服务发现，则可以选择部署注册中心，在Dubbo中集成对应的注册中心。
在Dubbo + Mesh 的场景下，随着 Dubbo 服务注册能力的弱化，Dubbo内的注册中心也不再是必选项，其职责开始被控制面取代，如果采用了Dubbo + Mesh的部署方式，无论是ThinSDK的mesh方式还是Proxyless的mesh方式，都不再需要独立部署注册中心。

而注册中心并不依赖于配置中心和元数据中心，如下图所示：

元数据中心

对于一个原先采用老版本Dubbo搭建的应用服务，在迁移到Dubbo 3时，Dubbo 3 会需要一个元数据中心来维护RPC服务与应用的映射关系（即接口与应用的映射关系），因为如果采用了应用级别的服务发现和服务注册，在注册中心中将采用“应用 —— 实例列表”结构的数据组织形式，不再是以往的“接口 —— 实例列表”结构的数据组织形式，而以往用接口级别的服务注册和服务发现的应用服务在迁移到应用级别时，得不到接口与应用之间的对应关系，从而无法从注册中心得到实例列表信息，所以Dubbo为了兼容这种场景，在Provider端启动时，会往元数据中心存储接口与应用的映射关系。
为了让注册中心更加聚焦与地址的发现和推送能力，减轻注册中心的负担，元数据中心承载了所有的服务元数据、大量接口/方法级别配置信息等，无论是接口粒度还是应用粒度的服务发现和注册，元数据中心都起到了重要的作用。

如果有以上两种需求，都可以选择部署元数据中心，并通过Dubbo的配置来集成该元数据中心。

元数据中心并不依赖于注册中心和配置中心，用户可以自由选择是否集成和部署元数据中心，如下图所示：

该图中不配备配置中心，意味着可以不需要全局管理配置的能力。该图中不配备注册中心，意味着可能采用了Dubbo mesh的方案，也可能不需要进行服务注册，仅仅接收直连模式的服务调用。

配置中心

配置中心与其他两大中心不同，它无关于接口级还是应用级，它与接口并没有对应关系，它仅仅与配置数据有关，即使没有部署注册中心和元数据中心，配置中心也能直接被接入到Dubbo应用服务中。在整个部署架构中，整个集群内的实例（无论是Provider还是Consumer）都将会共享该配置中心集群中的配置，如下图所示：

该图中不配备注册中心，意味着可能采用了Dubbo mesh的方案，也可能不需要进行服务注册，仅仅接收直连模式的服务调用。

调用链路传递隐式参数

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

在不修改方法签名与参数定义的情况下，可以通过 RpcContext 上的 setAttachment 和 getAttachment 在服务消费方和提供方之间进行参数的隐式传递。隐式参数传递支持以下两个方向：

从消费方到提供方，也就是在请求发起时，在方法参数之外通过 attachment 传递附加参数。
从提供方到消费方，也就是在响应结果返回时，在响应结果之外通过 attachment 传递附加参数。

理解隐式参数传递的最直接方式 http header，它的工作方式与 http header 完全一致，在 GET 或 POST 请求体之外可以传递任意多个 header 参数。在实现原理上，对于不同的协议，attachment 的实现方式略有不同：

对于 triple 协议，attachment 会转换为标准的 http header 进行传输。
对于 dubbo 协议，attachment 是编码在协议体的固定位置进行传输，具体请参见 dubbo 协议规范。

注意

在使用 triple 协议时，由于 http header 的限制，仅支持小写的 ascii 字符
path, group, version, dubbo, token, timeout 一些 key 是保留字段，传递 attachment 时应避免使用，尽量通过业务前缀等确保 key 的唯一性。

消费端隐式参数

本文示例完整源码可在以下链接查看 dubbo-samples-attachment

设置隐式参数

RpcContext.getClientAttachment().setAttachment("index", "1"); // 隐式传参，后面的远程调用都会隐式将这些参数发送到服务器端，类似cookie，比如用于框架集成
xxxService.xxx(); // 远程调用
// ...

读取隐式参数

public class XxxServiceImpl implements XxxService {

 public void xxx() {
 // 获取客户端隐式传入的参数，比如用于框架集成
 String index = RpcContext.getServerAttachment().getAttachment("index");
 }
}

提供端隐式参数

设置隐式参数

public class XxxServiceImpl implements XxxService {

 public void xxx() {
 String index = xxx;
 RpcContext.getServerContext().setAttachment("result", index);
 }
}

读取隐式参数

xxxService.xxx(); // 远程调用
String result = RpcContext.getServerContext().getAttachment("result");
// ...

参数透传问题

请注意！setAttachment 设置的 KV 对，在完成下面一次远程调用会被清空，即多次远程调用要多次设置！这一点与 Dubbo2 中的行为是不一致的！

使用 Dubbo 开发 gRPC 服务

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

这个示例演示了如何使用 triple 协议实现 Dubbo 服务与标准 gRPC 服务的互相调用，可在此查看示例完整源码

就像在 Triple协议规范中所描述的，triple 协议与 gRPC 协议保持 100% 兼容，同时在易用性方面有了非常大的提升（比如支持 cURL、浏览器直接访问等），可以说 triple 是一个更好用的 gRPC 设计与实现。

运行示例

首先，可通过以下命令下载示例源码

git clone --depth=1 https://github.com/apache/dubbo-samples.git

进入示例源码目录：

cd dubbo-samples/2-advanced/dubbo-samples-triple-grpc

接下来，我们分别从 dubbo 调用 grpc、grpc 调用 dubbo 两个不同的方向，看一下如何基于 triple 协议实现互调。

作为标准的 gRPC Server

在这一部分，我们会发布一个 Dubbo Triple Server，然后启动一个标准的 gRPC 消费端（示例采用谷歌官方发布的 grpc-java 编码）来调用 Triple 服务。

启动 Dubbo server

确保你在 dubbo-samples-triple-grpc 目录，运行以下命令：

$ mvn compile exec:java -Dexec.mainClass="org.apache.dubbo.samples.tri.grpc.interop.server.TriOpServer"

使用标准 gRPC client 调用 Triple 服务

打开一个新的终端，在 dubbo-samples-triple-grpc 目录运行以下命令：

服务调用过程

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

1. 简介

在前面的文章中，我们分析了 Dubbo SPI、服务导出与引入、以及集群容错方面的代码。经过前文的铺垫，本篇文章我们终于可以分析服务调用过程了。Dubbo 服务调用过程比较复杂，包含众多步骤，比如发送请求、编解码、服务降级、过滤器链处理、序列化、线程派发以及响应请求等步骤。限于篇幅原因，本篇文章无法对所有的步骤一一进行分析。本篇文章将会重点分析请求的发送与接收、编解码、线程派发以及响应的发送与接收等过程，至于服务降级、过滤器链和序列化大家自行进行分析，也可以将其当成一个黑盒，暂时忽略也没关系。介绍完本篇文章要分析的内容，接下来我们进入正题吧。

2. 源码分析

在进行源码分析之前，我们先来通过一张图了解 Dubbo 服务调用过程。

首先服务消费者通过代理对象 Proxy 发起远程调用，接着通过网络客户端 Client 将编码后的请求发送给服务提供方的网络层上，也就是 Server。Server 在收到请求后，首先要做的事情是对数据包进行解码。然后将解码后的请求发送至分发器 Dispatcher，再由分发器将请求派发到指定的线程池上，最后由线程池调用具体的服务。这就是一个远程调用请求的发送与接收过程。至于响应的发送与接收过程，这张图中没有表现出来。对于这两个过程，我们也会进行详细分析。

2.1 服务调用方式

Dubbo 支持同步和异步两种调用方式，其中异步调用还可细分为“有返回值”的异步调用和“无返回值”的异步调用。所谓“无返回值”异步调用是指服务消费方只管调用，但不关心调用结果，此时 Dubbo 会直接返回一个空的 RpcResult。若要使用异步特性，需要服务消费方手动进行配置。默认情况下，Dubbo 使用同步调用方式。

本节以及其他章节将会使用 Dubbo 官方提供的 Demo 分析整个调用过程，下面我们从 DemoService 接口的代理类开始进行分析。Dubbo 默认使用 Javassist 框架为服务接口生成动态代理类，因此我们需要先将代理类进行反编译才能看到源码。这里使用阿里开源 Java 应用诊断工具 Arthas 反编译代理类，结果如下：

/**
 * Arthas 反编译步骤：
 * 1. 启动 Arthas
 * java -jar arthas-boot.jar
 *
 * 2. 输入编号选择进程
 * Arthas 启动后，会打印 Java 应用进程列表，如下：
 * [1]: 11232 org.jetbrains.jps.cmdline.Launcher
 * [2]: 22370 org.jetbrains.jps.cmdline.Launcher
 * [3]: 22371 com.alibaba.dubbo.demo.consumer.Consumer
 * [4]: 22362 com.alibaba.dubbo.demo.provider.Provider
 * [5]: 2074 org.apache.zookeeper.server.quorum.QuorumPeerMain
 * 这里输入编号 3，让 Arthas 关联到启动类为 com.....Consumer 的 Java 进程上
 *
 * 3. 由于 Demo 项目中只有一个服务接口，因此此接口的代理类类名为 proxy0，此时使用 sc 命令搜索这个类名。
 * $ sc *.proxy0
 * com.alibaba.dubbo.common.bytecode.proxy0
 *
 * 4. 使用 jad 命令反编译 com.alibaba.dubbo.common.bytecode.proxy0
 * $ jad com.alibaba.dubbo.common.bytecode.proxy0
 *
 * 更多使用方法请参考 Arthas 官方文档：
 * https://arthas.aliyun.com/doc/quick-start.html
 */
public class proxy0 implements ClassGenerator.DC, EchoService, DemoService {
 // 方法数组
 public static Method[] methods;
 private InvocationHandler handler;

 public proxy0(InvocationHandler invocationHandler) {
 this.handler = invocationHandler;
 }

 public proxy0() {
 }

 public String sayHello(String string) {
 // 将参数存储到 Object 数组中
 Object[] arrobject = new Object[]{string};
 // 调用 InvocationHandler 实现类的 invoke 方法得到调用结果
 Object object = this.handler.invoke(this, methods[0], arrobject);
 // 返回调用结果
 return (String)object;
 }

 /** 回声测试方法 */
 public Object $echo(Object object) {
 Object[] arrobject = new Object[]{object};
 Object object2 = this.handler.invoke(this, methods[1], arrobject);
 return object2;
 }
}

如上，代理类的逻辑比较简单。首先将运行时参数存储到数组中，然后调用 InvocationHandler 接口实现类的 invoke 方法，得到调用结果，最后将结果转型并返回给调用方。关于代理类的逻辑就说这么多，继续向下分析。

官方 Dubbo 主页的维护

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

Apache 有一个官方的网站，用来维护所有的孵化项目的信息。每一个孵化项目在这个网站下都有一个信息页。 Dubbo 的信息页地址是 https://incubator.apache.org/projects/dubbo.html。

当项目发生比较大的变化，比如新的 committer 的加入，新的 PMC 的当选，或是新版本的 Release 等，都需要将这些更新信息维护到这个页面。

这个官方网站的项目地址是https://svn.apache.org/repos/asf/incubator/public/trunk。

维护这个页面的方法如下：

1.安装 SVN。若是 Mac OS X 系统或是 Linux 系统，则自带了 SVN。若是 Windows 系统，则请首先自行安装 SVN。

2.用 SVN 将这个项目 checkout 下来。

3.修改 content/projects/dubbo.xml 文件，并保存。

4.安装 ANT。执行 trunk 目录下的 build.sh 或者 build.bat 脚本构建项目。

5.构建完成后，可以用浏览器打开 target/site/projects/dubbo.html 文件，预览修改是否生效。

6.用 SVN 的 commit 命令将 dubbo.xml 文件提交到服务器，并且不要提交 dubbo.html 文件（因为服务器端会定时自动构建）。此过程会要求输入Apache id和密码。

参考:

通过标签实现流量隔离环境（灰度、多套开发环境等）

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

无论是在日常开发测试环境，还是在预发生产环境，我们经常都会遇到流量隔离环境的需求。

在日常开发中，为了避免开发测试过程中互相干扰，我们有搭建多套独立测试环境的需求，但通过搭建物理集群的方式成本非常高且不够灵活
在生产发布过程中，为了保障新版本得到充分的验证，我们需要搭建一套完全隔离的线上灰度环境用来部署新版本服务，线上灰度环境能完全模拟生产运行情况，但只有固定的带有特定标记的线上流量会被导流到灰度环境，充分验证新版本的同时将线上变更风险降到最低。

利用 Dubbo 提供的标签路由能力，可以非常灵活的实现流量隔离能力。可以单独为集群中的某一个或多个应用划分隔离环境，也可以为整个微服务集群划分隔离环境；可以在部署态静态的标记隔离环境，也可以在运行态通过规则动态的隔离出一部分机器环境。

注意：标签路由是一套严格隔离的流量体系，对于同一个应用而言，一旦打了标签则这部分地址子集就被隔离出来，只有带有对应标签的请求流量可以访问这个地址子集，这部分地址不再接收没有标签或者具有不同标签的流量。举个例子，如果我们将一个应用进行打标，打标后划分为 tag-a、tag-b、无 tag 三个地址子集，则访问这个应用的流量，要么路由到 tag-a (当请求上下文 dubbo.tag=tag-a)，要么路由到 tag-b (dubbo.tag=tag-b)，或者路由到无 tag 的地址子集 (dubbo.tag 未设置)，不会出现混调的情况。

开始之前

部署 Shop 商城项目
部署并打开 Dubbo Admin

任务详情

我们决定为商城系统建立一套完整的线上灰度验证环境，灰度环境和线上环境共享一套物理集群，需要我们通过 Dubbo 标签路由从逻辑上完全隔离出一套环境，做到灰度流量和线上流量互不干扰。

为商城搭建一套完全隔离的灰度环境

首先，为 User、Detail、Comment、Order 几个应用都部署灰度环境实例，我们为这部分实例都带有 env=gray 的环境标。部署可以通过以下命令快速完成

kubectl apply -f https://raw.githubusercontent.com/apache/dubbo-samples/master/10-task/dubbo-samples-shop/deploy/Gray.yml

如何为机器或实例打标？

方法一：通过 dubbo.labels 或 DUBBO_LABELS 指定需要增加到 URL 中的键值对。

# 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 或 DUBBO_ENV_KEYS 指定要加载的环境变量，Dubbo 会尝试从环境变量加载每个 key。

基于条件的流量路由

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

路由是 Dubbo 中的核心流量管控机制，我们可以基于它实现金丝雀发布、按比例流量转发、同区域优先、全链路灰度等流量策略。Dubbo 中路由（Router）机制的设计与基本原理，内置的几种路由规则

常用流量管控场景

Dubbo 内置的流量策略非常的灵活，但同时也有一定的理解与使用成本，因此，我们根据总结了一些常用的使用场景，并给出了配置方法：

场景	效果	作用对象	说明
超时时间
访问日志
调用重试

接下来，我们就以一个条件路由为例，来看一下如何使用 Dubbo 流量管控机制。

一个条件路由示例

需求非常的直观明了。

匹配这个条件的流量，转发到这一批机器
匹配另一个条件的流量，转发到另一批机器

画一张流量匹配和转发的图

这在 Dubbo 中就是用条件路由来实现的，关于其详细工作原理我们在介绍中有详细讲解。在以上示例中，xxx 代表；yyy 代表

我们需要把规则下发到运行中的dubbo sdk，在 dubbo 体系中这是如下如下工作的。

路由规则的分发与生效原理图

一个 zk/nacos、下发一条规则，dubbo实例接收到规则推送，rpc调用过程中应用规则筛选，选出地址子集调用

注意

传统 Nacos/Zookeeper 的微服务部署方案中，Dubbo 的路由规则配置中心存储并转发到 Dubbo SDK，而在 Kubernetes Service 或服务网格场景下，路由规则的存储与推送机制会有一些变化，具体请参考 Kubernetes 最佳实践。

这时，如果我们对 xxx 服务发送一个请求，

集群扩展

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

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

扩展说明

当有多个服务提供方时，将多个服务提供方组织成一个集群，并伪装成一个提供方。

扩展接口

org.apache.dubbo.rpc.cluster.Cluster

扩展配置

<dubbo:protocol cluster="xxx" />
<!-- 缺省值配置，如果<dubbo:protocol>没有配置cluster时，使用此配置 -->
<dubbo:provider cluster="xxx" />

已知扩展

org.apache.dubbo.rpc.cluster.support.wrapper.MockClusterWrapper
org.apache.dubbo.rpc.cluster.support.FailoverCluster
org.apache.dubbo.rpc.cluster.support.FailfastCluster
org.apache.dubbo.rpc.cluster.support.FailsafeCluster
org.apache.dubbo.rpc.cluster.support.FailbackCluster
org.apache.dubbo.rpc.cluster.support.ForkingCluster
org.apache.dubbo.rpc.cluster.support.AvailableCluster
org.apache.dubbo.rpc.cluster.support.MergeableCluster
org.apache.dubbo.rpc.cluster.support.BroadcastCluster
org.apache.dubbo.rpc.cluster.support.registry.ZoneAwareCluster

扩展示例

Maven 项目结构：

src
 |-main
 |-java
 |-com
 |-xxx
 |-XxxCluster.java (实现Cluster接口)
 |-resources
 |-META-INF
 |-dubbo
 |-org.apache.dubbo.rpc.cluster.Cluster (纯文本文件，内容为：xxx=com.xxx.XxxCluster)

XxxCluster.java：

package com.xxx;
 
import org.apache.dubbo.rpc.cluster.Cluster;
import org.apache.dubbo.rpc.cluster.support.AbstractClusterInvoker;
import org.apache.dubbo.rpc.cluster.Directory;
import org.apache.dubbo.rpc.cluster.LoadBalance;
import org.apache.dubbo.rpc.Invoker;
import org.apache.dubbo.rpc.Invocation;
import org.apache.dubbo.rpc.Result;
import org.apache.dubbo.rpc.RpcException;
 
public class XxxCluster implements Cluster {
 public <T> Invoker<T> merge(Directory<T> directory) throws RpcException {
 return new AbstractClusterInvoker<T>(directory) {
 public Result doInvoke(Invocation invocation, List<Invoker<T>> invokers, LoadBalance loadbalance) throws RpcException {
 // ...
 }
 };
 }
}

META-INF/dubbo/org.apache.dubbo.rpc.cluster.Cluster：

集群扩展

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

扩展说明

当有多个服务提供方时，将多个服务提供方组织成一个集群，并伪装成一个提供方。

扩展接口

org.apache.dubbo.rpc.cluster.Cluster

扩展配置

<dubbo:protocol cluster="xxx" />
<!-- 缺省值配置，如果<dubbo:protocol>没有配置cluster时，使用此配置 -->
<dubbo:provider cluster="xxx" />

已知扩展

org.apache.dubbo.rpc.cluster.support.wrapper.MockClusterWrapper
org.apache.dubbo.rpc.cluster.support.FailoverCluster
org.apache.dubbo.rpc.cluster.support.FailfastCluster
org.apache.dubbo.rpc.cluster.support.FailsafeCluster
org.apache.dubbo.rpc.cluster.support.FailbackCluster
org.apache.dubbo.rpc.cluster.support.ForkingCluster
org.apache.dubbo.rpc.cluster.support.AvailableCluster
org.apache.dubbo.rpc.cluster.support.MergeableCluster
org.apache.dubbo.rpc.cluster.support.BroadcastCluster
org.apache.dubbo.rpc.cluster.support.registry.ZoneAwareCluster

扩展示例

Maven 项目结构：

src
 |-main
 |-java
 |-com
 |-xxx
 |-XxxCluster.java (实现Cluster接口)
 |-resources
 |-META-INF
 |-dubbo
 |-org.apache.dubbo.rpc.cluster.Cluster (纯文本文件，内容为：xxx=com.xxx.XxxCluster)

XxxCluster.java：

package com.xxx;
 
import org.apache.dubbo.rpc.cluster.Cluster;
import org.apache.dubbo.rpc.cluster.support.AbstractClusterInvoker;
import org.apache.dubbo.rpc.cluster.Directory;
import org.apache.dubbo.rpc.cluster.LoadBalance;
import org.apache.dubbo.rpc.Invoker;
import org.apache.dubbo.rpc.Invocation;
import org.apache.dubbo.rpc.Result;
import org.apache.dubbo.rpc.RpcException;
 
public class XxxCluster implements Cluster {
 public <T> Invoker<T> merge(Directory<T> directory) throws RpcException {
 return new AbstractClusterInvoker<T>(directory) {
 public Result doInvoke(Invocation invocation, List<Invoker<T>> invokers, LoadBalance loadbalance) throws RpcException {
 // ...
 }
 };
 }
}

META-INF/dubbo/org.apache.dubbo.rpc.cluster.Cluster：

集群扩展

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

扩展说明

当有多个服务提供方时，将多个服务提供方组织成一个集群，并伪装成一个提供方。

扩展接口

org.apache.dubbo.rpc.cluster.Cluster

扩展配置

<dubbo:protocol cluster="xxx" />
<!-- 缺省值配置，如果<dubbo:protocol>没有配置cluster时，使用此配置 -->
<dubbo:provider cluster="xxx" />

已知扩展

org.apache.dubbo.rpc.cluster.support.wrapper.MockClusterWrapper
org.apache.dubbo.rpc.cluster.support.FailoverCluster
org.apache.dubbo.rpc.cluster.support.FailfastCluster
org.apache.dubbo.rpc.cluster.support.FailsafeCluster
org.apache.dubbo.rpc.cluster.support.FailbackCluster
org.apache.dubbo.rpc.cluster.support.ForkingCluster
org.apache.dubbo.rpc.cluster.support.AvailableCluster
org.apache.dubbo.rpc.cluster.support.MergeableCluster
org.apache.dubbo.rpc.cluster.support.BroadcastCluster
org.apache.dubbo.rpc.cluster.support.registry.ZoneAwareCluster

扩展示例

Maven 项目结构：

src
 |-main
 |-java
 |-com
 |-xxx
 |-XxxCluster.java (实现Cluster接口)
 |-resources
 |-META-INF
 |-dubbo
 |-org.apache.dubbo.rpc.cluster.Cluster (纯文本文件，内容为：xxx=com.xxx.XxxCluster)

XxxCluster.java：

package com.xxx;
 
import org.apache.dubbo.rpc.cluster.Cluster;
import org.apache.dubbo.rpc.cluster.support.AbstractClusterInvoker;
import org.apache.dubbo.rpc.cluster.Directory;
import org.apache.dubbo.rpc.cluster.LoadBalance;
import org.apache.dubbo.rpc.Invoker;
import org.apache.dubbo.rpc.Invocation;
import org.apache.dubbo.rpc.Result;
import org.apache.dubbo.rpc.RpcException;
 
public class XxxCluster implements Cluster {
 public <T> Invoker<T> merge(Directory<T> directory) throws RpcException {
 return new AbstractClusterInvoker<T>(directory) {
 public Result doInvoke(Invocation invocation, List<Invoker<T>> invokers, LoadBalance loadbalance) throws RpcException {
 // ...
 }
 };
 }
}

META-INF/dubbo/org.apache.dubbo.rpc.cluster.Cluster：

扩展 Dubbo 向导

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

Dubbo 使用微内核+插件的设计模式。内核只负责组装插件，Dubbo 的功能都是由扩展点（插件）实现，这就意味着 Dubbo 的所有功能都可以被用户定制的扩展所替代。

Dubbo 生态系统

我们建议您将扩展加入到 Dubbo 生态系统。使用这种模式，可以使 Dubbo 的核心仓库更干净，并且可以减少维护工作。更少的代码也可以提高核心仓库的构建速度。

依赖

要实现您自己的 Dubbo 扩展，通常只需依赖 API jar 就可以满足您的需求。例如：

<dependency>
 <groupId>org.apache.dubbo</groupId>
 <artifactId>dubbo-serialization-api</artifactId>
 <version>${dubbo.version}</version>
</dependency>

Src指导

通常，要实现特殊的扩展，只需要参考开发者指南，实现Dubbo必要的接口和合适的扩展即可。除此之外，还有一些其它的事项需要注意：

良好的测试，您需要编写单元测试和冒烟测试以消除潜在的 bug。
没有警告，如有不可避免的警告，请使用 @SuppressWarnings 阻止它，但是请不要乱用。
README。添加必要的自述以说明如何使用扩展，以及需要注意的事项。
许可证：请确保使用Apache License 2.0。

通知社区

提交您的代码到 github。
加入邮件列表（建议）。点击这里查看如何加入邮件列表。
发送一封邮件到 dev@incubator.dubbo.apache.org 通知社区。
通常，发送邮件之后，社区会对您的扩展进行讨论，dubbo 组的管理员会联系您转移您的项目到 dubbo 生态系统。

转移项目到dubbo生态系统

dubbo 组的管理员会请您将您的项目的所有者转让给 dubbo。
dubbo 组的管理员会在 dubbo 组下新建一个项目并邀请您加入到这个项目。
一旦您接受邀请，您可以将您的项目转移到 dubbo 组下的新项目里。
dubbo 组的成员会对您的项目进行代码审查。随后，您可以对这些代码进行改进。

扩展点重构

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

随着服务化的推广，网站对Dubbo服务框架的需求逐渐增多，Dubbo 的现有开发人员能实现的需求有限，很多需求都被 delay，而网站的同学也希望参与进来，加上领域的推动，所以平台计划将部分项目对公司内部开放，让大家一起来实现，Dubbo 为试点项目之一。

既然要开放，那 Dubbo 就要留一些扩展点，让参与者尽量黑盒扩展，而不是白盒的修改代码，否则分支，质量，合并，冲突都会很难管理。

先看一下 Dubbo 现有的设计：

这里面虽然有部分扩展接口，但并不能很好的协作，而且扩展点的加载和配置都没有统一处理，所以下面对它进行重构。

第一步，微核心，插件式，平等对待第三方

即然要扩展，扩展点的加载方式，首先要统一，微核心+插件式，是比较能达到 OCP 原则的思路。

由一个插件生命周期管理容器，构成微核心，核心不包括任何功能，这样可以确保所有功能都能被替换，并且，框架作者能做到的功能，扩展者也一定要能做到，以保证平等对待第三方，所以，框架自身的功能也要用插件的方式实现，不能有任何硬编码。

通常微核心都会采用 Factory、IoC、OSGi 等方式管理插件生命周期。考虑 Dubbo 的适用面，不想强依赖 Spring 等 IoC 容器。自已造一个小的 IoC 容器，也觉得有点过度设计，所以打算采用最简单的 Factory 方式管理插件。

最终决定采用的是 JDK 标准的 SPI 扩展机制，参见：java.util.ServiceLoader ，也就是扩展者在 jar 包的 META-INF/services/ 目录下放置与接口同名的文本文件，内容为接口实现类名，多个实现类名用换行符分隔。比如，需要扩展 Dubbo 的协议，只需在 xxx.jar 中放置文件：META-INF/services/org.apache.dubbo.rpc.Protocol，内容为 com.alibaba.xxx.XxxProtocol。Dubbo 通过 ServiceLoader 扫描到所有 Protocol 实现。

并约定所有插件，都必须标注：@Extension("name")，作为加载后的标识性名称，用于配置选择。

第二步，每个扩展点只封装一个变化因子，最大化复用

每个扩展点的实现者，往往都只是关心一件事，现在的扩展点，并没有完全分离。比如：Failover, Route, LoadBalance, Directory 没有完全分开，全由 RoutingInvokerGroup 写死了。

再比如，协议扩展，扩展者可能只是想替换序列化方式，或者只替换传输方式，并且 Remoting 和 Http 也能复用序列化等实现。这样，需为传输方式，客户端实现，服务器端实现，协议头解析，数据序列化，都留出不同扩展点。

拆分后，设计如下：

第三步，全管道式设计，框架自身逻辑，均使用截面拦截实现

现在很多的逻辑，都是放在基类中实现，然后通过模板方法回调子类的实现，包括：local, mock, generic, echo, token, accesslog, monitor, count, limit 等等，可以全部拆分使用 Filter 实现，每个功能都是调用链上的一环。比如：(基类模板方法)

统一路由规则升级指南

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

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

配置加载流程

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

参见示例

配置工作原理

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

注意

自 3.0.10 开始，dubbo-qos 运行时管控支持查询日志配置以及动态修改使用的日志框架和日志级别。

通过 dubbo-qos 修改的日志配置不进行持久化存储，在应用重启后将会失效。

查询日志配置

命令：loggerInfo

示例：

> telnet 127.0.0.1 22222
> loggerInfo

输出：

Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
 ___ __ __ ___ ___ ____ 
 / _ \ / / / // _ ) / _ ) / __ \ 
 / // // /_/ // _ |/ _ |/ /_/ / 
/____/ \____//____//____/ \____/ 
dubbo>loggerInfo
Available logger adapters: [jcl, jdk, log4j, slf4j]. Current Adapter: [log4j]. Log level: INFO

修改日志级别

命令：switchLogLevel {level}

使用 Apache Skywalking 做分布式跟踪

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

Apache Skywalking 简介

Apache Skywalking 专门为微服务架构和云原生架构系统而设计并且支持分布式链路追踪的APM系统。Apache Skywalking 通过加载探针的方式收集应用调用链路信息，并对采集的调用链路信息进行分析，生成应用间关系和服务间关系以及服务指标。Apache Skywalking 目前支持多种语言，其中包括 Java，.Net Core，Node.js 和 Go 语言。

目前 Skywalking 已经支持从 6 个可视化维度剖析分布式系统的运行情况。总览视图是应用和组件的全局视图，其中包括组件和应用数量，应用的告警波动，慢服务列表以及应用吞吐量；拓扑图从应用依赖关系出发，展现整个应用的拓扑关系；应用视图则是从单个应用的角度，展现应用的上下游关系，TopN 的服务和服务器，JVM 的相关信息以及对应的主机信息。服务视图关注单个服务入口的运行情况以及此服务的上下游依赖关系，依赖度，帮助用户针对单个服务的优化和监控；调用链展现了调用的单次请求经过的所有埋点以及每个埋点的执行时长；告警视图根据配置阈值针对应用、服务器、服务进行实时告警。

Dubbo 与 Apache Skywalking

编写 Dubbo 示例程序

Dubbo 实例程序已上传到 Github 仓库中。方便大家下载使用。

API 工程

服务接口：

package org.apache.skywalking.demo.interfaces;

public interface HelloService {
	String sayHello(String name);
}

Dubbo 服务提供工程

package org.apache.skywalking.demo.provider;

@Service(version = "${demo.service.version}",
	application = "${dubbo.application.id}",
	protocol = "${dubbo.protocol.id}",
	registry = "${dubbo.registry.id}", timeout = 60000)
public class HelloServiceImpl implements HelloService {

	public String sayHello(String name) {
		LockSupport.parkNanos(TimeUnit.SECONDS.toNanos(1));
		return "Hello, " + name;
	}

}

Consumer 工程

package org.apache.skywalking.demo.consumer;

@RestController
public class ConsumerController {

	private static int COUNT = 0;

	@Reference(version = "${demo.service.version}",
		application = "${dubbo.application.id}",
		url = "dubbo://localhost:20880", timeout = 60000)
	private HelloService helloService;

	@GetMapping("/sayHello/{name}")
	public String sayHello(@PathVariable(name = "name") String name) {
		if ((COUNT++) % 3 == 0){
			throw new RuntimeException();
		}
		LockSupport.parkNanos(TimeUnit.SECONDS.toNanos(2));
		return helloService.sayHello(name);
	}
}

部署 Apache Skywalking

Apache Skywalking 共提供两种部署模式：单节点模式和集群模式，以下为单节点模式部署步骤，集群模式部署详情参考文档。

使用 Pinpoint 做分布式跟踪

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

在使用 Dubbo 进行服务化或者整合应用后，假设某个服务后台日志显示有异常，这个服务又被多个应用调用的情况下，我们通常很难判断是哪个应用调用的，问题的起因是什么，因此我们需要一套分布式跟踪系统来快速定位问题，Pinpoint 可以帮助我们快速定位问题（当然，解决方案也不止这一种）。

什么是 Pinpoint

摘自 Pinpoint 学习笔记

Pinpoint 是一个开源的 APM (Application Performance Management/应用性能管理)工具，用于基于java的大规模分布式系统。

仿照 Google Dapper，Pinpoint 通过跟踪分布式应用之间的调用来提供解决方案，以帮助分析系统的总体结构和内部模块之间如何相互联系。

注：对于各个模块之间的通讯英文原文中用的是transaction一词，但是我觉得如果翻译为"事务"容易引起误解，所以替换为"交互"或者"调用"这种比较直白的字眼。

在使用上力图简单高效：

安装 agent，不需要修改哪怕一行代码
最小化性能损失

服务器地图(ServerMap)

通过可视化分布式系统的模块和他们之间的相互联系来理解系统拓扑。点击某个节点会展示这个模块的详情，比如它当前的状态和请求数量。

实时活动线程图表(Realtime Active Thread Chart)

实时监控应用内部的活动线程。

请求/应答分布图表(Request/Response Scatter Chart)

长期可视化请求数量和应答模式来定位潜在问题。通过在图表上拉拽可以选择请求查看更多的详细信息。

调用栈(CallStack)

在分布式环境中为每个调用生成代码级别的可视图，在单个视图中定位瓶颈和失败点。

巡查(Inspector)

查看应用上的其他详细信息，比如CPU使用率，内存/垃圾回收，TPS，和JVM参数。

支持模块

JDK 6+
Tomcat 6/7/8, Jetty 8/9, JBoss EAP 6, Resin 4, Websphere 6/7/8, Vertx 3.3/3.4/3.5
Spring, Spring Boot (Embedded Tomcat, Jetty)
Apache HTTP Client 3.x/4.x, JDK HttpConnector, GoogleHttpClient, OkHttpClient, NingAsyncHttpClient
Thrift Client, Thrift Service, DUBBO PROVIDER, DUBBO CONSUMER
ActiveMQ, RabbitMQ
MySQL, Oracle, MSSQL, CUBRID,POSTGRESQL, MARIA
Arcus, Memcached, Redis, CASSANDRA
iBATIS, MyBatis
DBCP, DBCP2, HIKARICP
gson, Jackson, Json Lib
log4j, Logback
自定义模块

Pinpoint 与 Dubbo 的结合

启动 Pinpoint

参考 Pinpoint 的 Quick start 搭建环境（不需要启动 TestApp）

基于 Kubernetes Service 的服务发现

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

上面两节我们分别讲解了 Nacos、Zookeeper 两种注册中心模式，它们更像是传统的注册中心解决方案。在 Kubernetes 部署环境下，Dubbo 支持基于 Kubernetes Service 的服务发现模式，其基本工作原理如下图所示：

在这种模式下，服务发现与用户的部署运维操作形成统一，用户定义标准的 Kubernetes Service、Deployment，并将其部署到 Kubernetes，之后 Control Plane 通过监控 APISERVER 资源并与 SDK 进程联动，形成一整套的服务发现体系。

关于使用 Kubernetes 作为注册中心的具体实践案例，请参考 Kubernetes Service 部署 一节了解更多细节。

通信协议

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

Dubbo 框架提供了自定义的高性能 RPC 通信协议：基于 HTTP/2 的 Triple 协议和基于 TCP 的 Dubbo2 协议。除此之外，Dubbo 框架支持任意第三方通信协议，如官方支持的 gRPC、Thrift、REST、JsonRPC、Hessian2 等，更多协议可以通过自定义扩展实现。这对于微服务实践中经常要处理的多协议通信场景非常有用。

Dubbo 框架不绑定任何通信协议，在实现上 Dubbo 对多协议的支持也非常灵活，它可以让你在一个应用内发布多个使用不同协议的服务，并且支持用同一个 port 端口对外发布所有协议。

通过 Dubbo 框架的多协议支持，你可以做到：

将任意通信协议无缝地接入 Dubbo 服务治理体系。Dubbo 体系下的所有通信协议，都可以享受到 Dubbo 的编程模型、服务发现、流量管控等优势。比如 gRPC over Dubbo 的模式，服务治理、编程 API 都能够零成本接入 Dubbo 体系。
兼容不同技术栈，业务系统混合使用不同的服务框架、RPC 框架。比如有些服务使用 gRPC 或者 Spring Cloud 开发，有些服务使用 Dubbo 框架开发，通过 Dubbo 的多协议支持可以很好的实现互通。
让协议迁移变的更简单。通过多协议、注册中心的协调，可以快速满足公司内协议迁移的需求。比如如从自研协议升级到 Dubbo 协议，Dubbo 协议自身升级，从 Dubbo 协议迁移到 gRPC，从 HTTP 迁移到 Dubbo 协议等。

HTTP/2 (Triple)

Triple 协议是 Dubbo3 发布的面向云原生时代的通信协议，它基于 HTTP/2 并且完全兼容 gRPC 协议，原生支持 Streaming 通信语义，Triple 可同时运行在 HTTP/1 和 HTTP/2 传输协议之上，让你可以直接使用 curl、浏览器访问后端 Dubbo 服务。

限流 & 熔断

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

由于微服务分布式的特点，如何构建稳定的微服务集群是一个很大的挑战，其中有两项非常关键的点值得关注

流量控制 (Rate Limiting)
熔断降级 (Circuit Breaking)

流量控制

流量控制更多的是站在 Dubbo 服务提供者视角来保证服务稳定性，通过明确的为 Dubbo 服务设置请求上限阈值，确保服务所处理的请求数始终在一个合理范围之内，从而确保系统整体的稳定性。

根据服务的具体部署情况，服务所能处理的流量上限是一定的，当对服务的请求数量保持在合理的范围时，系统运行正常；而当请求数量严重超过服务处理能力时，如大促期间的流量洪峰等场景，就可能造成服务提供者端的资源过度消耗、负载过高，进而出现响应延迟、请求无应答、系统假死等情况。

流量控制解决的问题和工作方式比较容易理解，而其使用的难点就是如何确定服务所能处理的流量最大值？

一种模式是由用户预先设定一个固定的限流值，如 Dubbo 通过集成 Sentinel 等产品实现的限流能力即是这种模式
- Dubbo Sentinel 流量控制
另一种方式是 Dubbo 框架自动根据系统或集群负载情况执行限流，相比用户预先设置限流值更加灵活方便，Dubbo 目前内置了自适应限流模式，具体可参见：

熔断降级

熔断降级则是更多的从 Dubbo 服务消费者视角来保障系统稳定性的重要手段。一个服务往往需要调用更多的下游 Dubbo 服务来完成业务逻辑，这时下游服务的稳定性就会影响当前服务甚至整个系统的稳定性，熔断（Circuit Breaking）即是面向不稳定服务场景设计的，它能最大限度避免下游服务不稳定对上游服务带来的影响。

而相比于熔断后直接返回调用失败信息，配合服务降级能力，我们可以继续调用预先设置好的服务降级逻辑，以降级逻辑的结果作为最终调用结果，以更优雅的返回给服务调用方。

如上图所示，Dubbo Consumer 依赖的下游的三个 Dubbo 服务，当 Service 3 出现不稳定的情况时（如响应时间变长、错误率增加等），从而 Consumer 调用 Service 3 的线程等资源就会产生堆积，如果此时我们不在 Consumer 侧做任何限制，则 Service 1 与 Service 2 的调用都会受到稳定性影响。通过熔断 Service 3 我们就能保证整个 Dubbo Consumer 服务的稳定性，不拖垮整个 Consumer 服务，熔断 Service 3 的方式可以有很多种实现，包括线程数、信号量、错误率等。

序列化协议升级

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

在 3.1.0 版本中，Dubbo 默认支持的序列化协议新增对 Fastjson2 的支持。部分用户可能会考虑在现有的系统中对序列化协议进行升级，但服务端和客户端版本的差异可能导致客户端并不支持服务端的序列化协议。

在 3.2.0 版本中, Dubbo 的服务端引入新的配置 prefer-serialization，该特性可以完美解决服务端序列化升级过程中可能带来的风险。

最佳实践

序列化协议升级，需要分两步走：

首先需要推动服务端的序列化协议升级，同时在服务端的暴露配置中需要添加 prefer-serialization 配置。

比如：升级前的序列化协议是 hessian2，升级之后的序列化协议是 Fastjson2 那么在服务端的暴露配置中就应该添加如下所示的配置。

dubbo.provider.prefer-serialization=fastjson2,hessian2
dubbo.provider.serialization=hessian2

其次，客户端需要升级至和服务端相同版本

实现原理

dubbo 客户端序列化协议是根据服务端的注册配置来选择的（即服务端的serialization配置）。在请求阶段 dubbo 会把客户端的序列化协议组装到请求头上，服务端在进行反序列化时会根据请求头来确定反序列化协议。所以，如果服务端和客户端的版本不一致就可能会出现客户端序列化不了的情况。

为了解决这个情况，3.2.0 在客户端序列化的时候会优先使用 prefer-serialization 配置的协议，如果不支持 prefer-serialization 相关的协议，才会使用 serialization 配置的协议。（可以把 serialization 理解为一个兜底的配置）

与 gRPC 应用互通

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

1.介绍

triple 协议 100% 兼容 gRPC，本示例演示使用 dubbo-go 开发与 grpc 互调的应用，可在此查看完整示例源码地址

2.如何互通

Dubbo-go的Triple协议能够兼容grpc协议在创建服务端时，可以设置protocol.WithTriple()使用Triple协议

	srv, err := server.NewServer(
 server.WithServerProtocol(
 protocol.WithPort(20000),
 protocol.WithTriple(),
 ),
 )

3.案例

3.1服务端介绍

服务端proto文件

源文件路径：dubbo-go-sample/rpc/grpc/proto/greet.proto

syntax = "proto3";

package greet;

option go_package = "github.com/apache/dubbo-go-samples/rpc/grpc/proto;greet";

message GreetRequest {
 string name = 1;
}

message GreetResponse {
 string greeting = 1;
}

service GreetService {
 rpc Greet(GreetRequest) returns (GreetResponse) {}
}

dubbo-go服务端

源文件路径：dubbo-go-sample/rpc/grpc/go-server/cmd/main.go

type GreetTripleServer struct {
}

func (srv *GreetTripleServer) Greet(ctx context.Context, req *greet.GreetRequest) (*greet.GreetResponse, error) {
	resp := &greet.GreetResponse{Greeting: "dubbo:" + req.Name}
	return resp, nil
}

func main() {
	srv, err := server.NewServer(
		server.WithServerProtocol(
			protocol.WithPort(20000),
			protocol.WithTriple(),
		),
	)
	if err != nil {
		panic(err)
	}

	if err := greet.RegisterGreetServiceHandler(srv, &GreetTripleServer{}); err != nil {
		panic(err)
	}

	if err := srv.Serve(); err != nil {
		logger.Error(err)
	}
}

grpc服务端

源文件路径: dubbo-go-sample/rpc/grpc/grpc-server/cmd/main.go

元数据参考手册

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

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

背景

dubbo provider中的服务配置项有接近30个配置项。排除注册中心服务治理需要之外，很大一部分配置项是provider自己使用，不需要透传给消费者。这部分数据不需要进入注册中心，而只需要以key-value形式持久化存储。 dubbo consumer中的配置项也有20+个配置项。在注册中心之中，服务消费者列表中只需要关注application，version，group，ip，dubbo版本等少量配置，其他配置也可以以key-value形式持久化存储。这些数据是以服务为维度注册进入注册中心，导致了数据量的膨胀，进而引发注册中心(如zookeeper)的网络开销增大，性能降低。
除了上述配置项的存储之外，dubbo服务元数据信息也需要被存储下来。元数据信息包括服务接口，及接口的方法信息。这些信息将被用于服务mock，服务测试。

以上的元数据都是基于接口级别。在3.0版本中，引入了应用元数据的概念，应用元数据描述的是整个应用的信息概览。并且引入了服务自省映射，用于应用级别的服务发现。

目标

需要将注册中心原来的数据信息和元数据信息保存到独立的key-value的存储中，这个key-value可以是DB，redis或者其他持久化存储。核心代码中支持了zookeeper，redis, nacos(推荐)的默认支持。

因为是基于key-value存储，key不会改变，最新的value会将原来的value进行覆盖

Provider存储内容的格式，参见：org.apache.dubbo.metadata.definition.model.FullServiceDefinition。是该类型gson化之后的存储。 Consumer存储内容，为Map格式。从Consumer端注册到注册中心的URL中的获取参数信息。即通过URL.getParameterMap()获取到的Map，进行gson化之后进行存储。

详细的内容，可以参考下面的sample输出。

配置

默认的元数据存储，额外支持以下几个特性：

失败重试
每天定时重刷

失败重试

失败重试可以通过retrytimes （重试次数,默认100），retryperiod（重试周期，默认3000ms）进行设置。

定时刷新

默认开启，可以通过设置cycleReport=false进行关闭。

完整的配置项：

dubbo.metadata-report.address=zookeeper://127.0.0.1:2181
dubbo.metadata-report.username=xxx ##非必须
dubbo.metadata-report.password=xxx ##非必须
dubbo.metadata-report.retry-times=30 ##非必须,default值100
dubbo.metadata-report.retry-period=5000 ##非必须,default值3000
dubbo.metadata-report.cycle-report=false ##非必须,default值true
dubbo.metadata-report.sync.report=false ##非必须,default值为false

如果元数据地址(dubbo.metadata-report.address)也不进行配置，会判断注册中心的协议是否支持元数据中心，如果支持，会使用注册中心的地址来用作元数据中心。

接下来看几个sample的配置。无论哪种配置方式，都需要引入maven依赖：

zookeeper:

<dependency>
 <groupId>org.apache.dubbo</groupId>
 <artifactId>dubbo-metadata-report-zookeeper</artifactId>
</dependency>

redis:

<dependency>
 <groupId>org.apache.dubbo</groupId>
 <artifactId>dubbo-metadata-report-redis</artifactId>
</dependency>

nacos:

<dependency>
 <groupId>org.apache.dubbo</groupId>
 <artifactId>dubbo-metadata-report-nacos</artifactId>
</dependency>

完整的sample，查看sample-2.7

方式一：在配置中心配置

参考sample：dubbo-samples-metadata-report/dubbo-samples-metadata-report-configcenter 工程。

配置中心配置

配置中心的配置，可以参考configcenter的文档。配置的内容如下：

dubbo.registry.address=zookeeper://127.0.0.1:2181
### 注意驼峰式风格
dubbo.metadata-report.address=zookeeper://127.0.0.1:2181 ###元数据存储的地址

在sample中，使用了Zookeeper作为配置中心。启动本地zookeeper服务之后，直接运行：org.apache.dubbo.samples.metadatareport.configcenter.ZKTools 就可以完成写入。如果配置中心使用了nacos，apollo，这些产品本身支持ops配置。

元数据参考手册

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

背景

目标

需要将注册中心原来的数据信息和元数据信息保存到独立的key-value的存储中，这个key-value可以是DB，redis或者其他持久化存储。核心代码中支持了zookeeper，redis(推荐)的默认支持。

provider存储内容的格式，参见：org.apache.dubbo.metadata.definition.model.FullServiceDefinition。是该类型gson化之后的存储。 Consumer存储内容，为Map格式。从Consumer端注册到注册中心的URL中的获取参数信息。即通过URL.getParameterMap()获取到的Map，进行gson化之后进行存储。

详细的内容，可以参考下面的sample输出。

配置

默认的元数据存储，额外支持以下几个特性：

失败重试
每天定时重刷

失败重试

失败重试可以通过retrytimes （重试次数,默认100），retryperiod（重试周期，默认3000ms）进行设置。

定时刷新

默认开启，可以通过设置cycleReport=false进行关闭。

完整的配置项：

dubbo.metadata-report.address=zookeeper://127.0.0.1:2181
dubbo.metadata-report.username=xxx ##非必须
dubbo.metadata-report.password=xxx ##非必须
dubbo.metadata-report.retry-times=30 ##非必须,default值100
dubbo.metadata-report.retry-period=5000 ##非必须,default值3000
dubbo.metadata-report.cycle-report=false ##非必须,default值true

如果元数据地址(dubbo.metadata-report.address)也不进行配置，整个元数据的写入不会生效，但是不影响程序运行。

接下来看几个sample的配置。无论哪种配置方式，都需要引入maven依赖：

<dependency>
 <groupId>org.apache.dubbo</groupId>
 <artifactId>dubbo-metadata-report-zookeeper</artifactId>
</dependency>

如果需要使用redis，可以引入对应的redis的依赖：

<dependency>
 <groupId>org.apache.dubbo</groupId>
 <artifactId>dubbo-metadata-report-redis</artifactId>
</dependency>

完整的sample，查看sample-2.7

方式一：在配置中心配置

参考sample：dubbo-samples-metadata-report/dubbo-samples-metadata-report-configcenter 工程。

配置中心配置

配置中心的配置，可以参考configcenter的文档。配置的内容如下：

dubbo.registry.address=zookeeper://127.0.0.1:2181
### 注意驼峰式风格
dubbo.metadata-report.address=zookeeper://127.0.0.1:2181 ###元数据存储的地址

应用配置

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

完成上述两步之后，注册中心地址、元数据地址将从配置中心进行获取。现在可以依次运行Provider类和Consumer类，会在console中得到对应的输出或者直接通过zookeeper的cli查看。

Provider配置

provider端存储的元数据内容如下：

{
 "parameters": {
 "side": "provider",
 "methods": "sayHello",
 "dubbo": "2.0.2",
 "threads": "100",
 "interface": "org.apache.dubbo.samples.metadatareport.configcenter.api.AnnotationService",
 "threadpool": "fixed",
 "version": "1.1.1",
 "generic": "false",
 "revision": "1.1.1",
 "valid": "true",
 "application": "metadatareport-configcenter-provider",
 "default.timeout": "5000",
 "group": "d-test",
 "anyhost": "true"
 },
 "canonicalName": "org.apache.dubbo.samples.metadatareport.configcenter.api.AnnotationService",
 "codeSource": "file:/Users/cvictory/workspace/work-mw/dubbo-samples/dubbo-samples-metadata-report/dubbo-samples-metadata-report-configcenter/target/classes/",
 "methods": [{
 "name": "sayHello",
 "parameterTypes": ["java.lang.String"],
 "returnType": "java.lang.String"
 }],
 "types": [{
 "type": "java.lang.String",
 "properties": {
 "value": {
 "type": "char[]"
 },
 "hash": {
 "type": "int"
 }
 }
 }, {
 "type": "int"
 }, {
 "type": "char"
 }]
}

provider存储的内容包括了provider服务往注册中心填写的全部参数，以及服务的方法信息（方法名，入参出参的格式）。

直连提供者

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

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

在开发及测试环境下，经常需要绕过注册中心，只测试指定服务提供者，这时候可能需要点对点直连，点对点直连方式，将以服务接口为单位，忽略注册中心的提供者列表，A 接口配置点对点，不影响 B 接口从注册中心获取列表。

通过 XML 配置

如果是线上需求需要点对点，可在 <dubbo:reference> 中配置 url 指向提供者，将绕过注册中心，多个地址用分号隔开，配置如下：

<dubbo:reference id="xxxService" interface="com.alibaba.xxx.XxxService" url="dubbo://localhost:20890" />

提示

1.0.6 及以上版本支持

通过 -D 参数指定

在 JVM 启动参数中加入-D参数映射服务地址，如：

java -Dcom.alibaba.xxx.XxxService=dubbo://localhost:20890

提示

key 为服务名，value 为服务提供者 url，此配置优先级最高，1.0.15 及以上版本支持

通过文件映射

如果服务比较多，也可以用文件映射，用 -Ddubbo.resolve.file 指定映射文件路径，此配置优先级高于 <dubbo:reference> 中的配置 [^3]，如：

java -Ddubbo.resolve.file=xxx.properties

然后在映射文件 xxx.properties 中加入配置，其中 key 为服务名，value 为服务提供者 URL：

com.alibaba.xxx.XxxService=dubbo://localhost:20890

提示

1.0.15 及以上版本支持，2.0 以上版本自动加载 ${user.home}/dubbo-resolve.properties文件，不需要配置

注意

为了避免复杂化线上环境，不要在线上使用这个功能，只应在测试阶段使用。

直连提供者

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

背景

示例

通过 XML 配置

如果是线上需求需要点对点，可在 <dubbo:reference> 中配置 url 指向提供者，将绕过注册中心，多个地址用分号隔开，配置如下：

<dubbo:reference id="xxxService" interface="com.alibaba.xxx.XxxService" url="dubbo://localhost:20890" />

提示

1.0.6 及以上版本支持

通过 -D 参数指定

在 JVM 启动参数中加入-D参数映射服务地址，如：

java -Dcom.alibaba.xxx.XxxService=dubbo://localhost:20890

提示

key 为服务名，value 为服务提供者 url，此配置优先级最高，1.0.15 及以上版本支持

通过文件映射

如果服务比较多，也可以用文件映射，用 -Ddubbo.resolve.file 指定映射文件路径，此配置优先级高于 <dubbo:reference> 中的配置 [^3]，如：

java -Ddubbo.resolve.file=xxx.properties

然后在映射文件 xxx.properties 中加入配置，其中 key 为服务名，value 为服务提供者 URL：

com.alibaba.xxx.XxxService=dubbo://localhost:20890

提示

1.0.15 及以上版本支持，2.0 以上版本自动加载 ${user.home}/dubbo-resolve.properties文件，不需要配置

注意

为了避免复杂化线上环境，不要在线上使用这个功能，只应在测试阶段使用。

直连提供者

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

如果是线上需求需要点对点，可在 reference 节点中配置 url 指向提供者，将绕过注册中心，多个地址用分号隔开，配置如下：

注解配置方式

@DubboReference(url="tri://localhost:50051")
private XxxService xxxService

xml配置方式

<dubbo:reference id="xxxService" interface="com.alibaba.xxx.XxxService" url="dubbo://localhost:20890" />

Dubbo3 应用级服务发现设计

Mon, 30 Jan 2023 00:00:00 +0000

Objective

显著降低服务发现过程的资源消耗，包括提升注册中心容量上限、降低消费端地址解析资源占用等，使得 Dubbo3 框架能够支持更大规模集群的服务治理，实现无限水平扩容。
适配底层基础设施服务发现模型，如 Kubernetes、Service Mesh 等。

Background

我们从 Dubbo 最经典的工作原理图说起，Dubbo 从设计之初就内置了服务地址发现的能力，Provider 注册地址到注册中心，Consumer 通过订阅实时获取注册中心的地址更新，在收到地址列表后，consumer 基于特定的负载均衡策略发起对 provider 的 RPC 调用。

在这个过程中：

每个 Provider 通过特定的 key 向注册中心注册本机可访问地址；
注册中心通过这个 key 对 provider 实例地址进行聚合；
Consumer 通过同样的 key 从注册中心订阅，以便及时收到聚合后的地址列表；

这里，我们对接口级地址发现的内部数据结构进行详细分析。

首先，看右下角 provider 实例内部的数据与行为。Provider 部署的应用中通常会有多个 Service，也就是 Dubbo2 中的服务，每个 service 都可能会有其独有的配置，我们所讲的 service 服务发布的过程，其实就是基于这个服务配置生成地址 URL 的过程，生成的地址数据如图所示；同样的，其他服务也都会生成地址。

然后，看一下注册中心的地址数据存储结构，注册中心以 service 服务名为数据划分依据，将一个服务下的所有地址数据都作为子节点进行聚合，子节点的内容就是实际可访问的ip地址，也就是我们 Dubbo 中 URL，格式就是刚才 provider 实例生成的。

这里把 URL 地址数据划分成了几份：

首先是实例可访问地址，主要信息包含 ip port，是消费端将基于这条数据生成 tcp 网络链接，作为后续 RPC 数据的传输载体
其次是 RPC 元数据，元数据用于定义和描述一次 RPC 请求，一方面表明这条地址数据是与某条具体的 RPC 服务有关的，它的版本号、分组以及方法相关信息，另一方面表明
下一部分是 RPC 配置数据，部分配置用于控制 RPC 调用的行为，还有一部分配置用于同步 Provider 进程实例的状态，典型的如超时时间、数据编码的序列化方式等。
最后一部分是自定义的元数据，这部分内容区别于以上框架预定义的各项配置，给了用户更大的灵活性，用户可任意扩展并添加自定义元数据，以进一步丰富实例状态。

结合以上两页对于 Dubbo2 接口级地址模型的分析，以及最开始的 Dubbo 基本原理图，我们可以得出这么几条结论：

0-6 - 线程中断异常

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

可能的原因

运行中的线程在处于 wait、sleep、join 时，被显示调用 interrupt()

排查和解决步骤

正常运行的线程在调用了 interrupt() 方法后，将对当前线程中断状态设置为 true，但线程的执行并不会受到影响。可根据实际情况进行操作或检查业务代码有无被错误使用。

1-6 - 清空URL缓存出错

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

可能的原因

在CacheableFailbackRegistry.RemovalTask清空 url 缓存时候出错将会触发清空 URL 缓存出错。

排查和解决步骤

该错误为 Dubbo 内部错误，如果您遇到可以在 github 创建 issues 并提供错误信息以及复现步骤，我们将协助您解决问题。

另请参阅 Dubbo社区

2-6 - 条件路由筛选提供方列表为空

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

可能的原因

条件路由提供方过滤条件为空。
条件路由在强制降级下筛选提供方列表仍为空。

排查和解决步骤

参照社区请求路由示例，调整条件路由配置。

3-6 - 代理执行服务发生异常

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

可能的原因

当前服务参数已显示入参 deprecated。
泛型声明类可能出现此提醒。

排查和解决步骤

确认URL中是否存在显示入参 deprecated=true
泛型声明类如果出现此错误，会试图创建没有实际接口类的代理。

4-6 - 反序列化失败

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

可能的原因

发生在使用自定义的序列化方式的时候，在自定义 SPI org.apache.dubbo.common.serialize.Serialization 序列化方法在使用时发生错误。

排查和解决步骤

可通过一些第三方的工具或者 jstack [PID] > jstack.log 分析堆栈信息，获取引起错误的对象内容，再配合自定义实现进行修改。

参考序列化扩展

5-6 - 接口类型的属性冲突

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

可能的原因

泛化定义配置不正确。

排查和解决步骤

检查泛化定义是否正确。

6-6 - 不支持的消息

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

可能的原因

返回的数据序列化错误，或超出序列化最大值

排查和解决步骤

可通过一些第三方的工具或者 jstack [PID] > jstack.log 分析堆栈信息，进行定位。

各组件支持的具体配置项及含义请参考配置项手册

7-6 - QOS 发生未知异常

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

可能的原因

QOS 发生未知异常

排查和解决步骤

检查当前请求的服务是否可正常访问。
可能由于某些原因，未能正确加载或返回 CommandContext 实例。可根据控制台的错误提醒信息，进行排查定位。

FST

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

1 介绍

FST序列化全称是Fast Serialization，它是对Java序列化的替换实现。既然前文中提到Java序列化的两点严重不足，在FST中得到了较大的改善，FST的特征如下：

比JDK提供的序列化提升了10倍，体积也减少 3-4 倍多
支持堆外Maps，和堆外Maps的持久化
支持序列化为JSON

2 使用方式

2.1 添加依赖

<dependencies>
 <dependency>
 <groupId>org.apache.dubbo.extensions</groupId>
 <artifactId>dubbo-serialization-fst</artifactId>
 <version>3.3.0</version>
 </dependency>
 <dependency>
 <groupId>de.ruedigermoeller</groupId>
 <artifactId>fst</artifactId>
 <version>3.0.3</version>
 </dependency>
</dependencies>

2.2 配置启用

# application.yml (Spring Boot)
dubbo:
 protocol:
 serialization: fst

或

# dubbo.properties
dubbo.protocol.serialization=fst

# or
dubbo.consumer.serialization=fst

# or
dubbo.reference.com.demo.DemoService.serialization=fst

或

<dubbo:protocol serialization="fst" />

 <!-- or -->
<dubbo:consumer serialization="fst" />

 <!-- or -->
<dubbo:reference interface="xxx" serialization="fst" />

3 注册被序列化类

要让Kryo和FST完全发挥出高性能，最好将那些需要被序列化的类注册到dubbo系统中，实现如下

回调接口

public class SerializationOptimizerImpl implements SerializationOptimizer {

 public Collection<Class> getSerializableClasses() {
 List<Class> classes = new LinkedList<Class>();
 classes.add(BidRequest.class);
 classes.add(BidResponse.class);
 classes.add(Device.class);
 classes.add(Geo.class);
 classes.add(Impression.class);
 classes.add(SeatBid.class);
 return classes;
 }
}

然后在XML配置中添加：

Higress

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

本文档讲解如何安装与配置 Higress，涵盖本地、docker、kubernetes 等环境。以下仅为快速示例安装指南，如想搭建生产可用集群请参考 Higress 官方文档。

docker

使用 docker 启动 Higress，请首先确保您已经在本地机器正确下载页面安装 docker。

使用以下命令安装 Higress：

curl -fsSL https://higress.io/standalone/get-higress.sh | bash -s -- -a -c nacos://192.168.0.1:8848 --nacos-username=nacos --nacos-password=nacos

请将 192.168.0.1 替换为 Nacos 服务器的 IP（如果 Nacos 部署在本机，请不要使用如 localhost 或 127.0.0.1 的 Loopback 地址）。按需调整 –nacos-username 和 –nacos-password 的取值，如果 Nacos 服务未开启认证功能，则可以移除这两个参数。

注意

如果您还没有安装 nacos，请参考文档完成安装。
如果您使用 Zookeeper 做服务发现，请修改对应的集群地址为 zookeeper 集群地址。

在浏览器中输入 http://127.0.0.1:8080 进入 Higress 控制台。

kubernetes

通过以下命令安装 Higress：

helm repo add higress.io https://higress.io/helm-charts
helm install higress -n higress-system higress.io/higress --create-namespace --render-subchart-notes --set global.local=true --set higress-console.o11y.enabled=false

通过以下端口映射命令，对本机访问开放端口：

Apache Dubbo 中文 on Apache Dubbo

阿里巴巴升级 Dubbo3 全面取代 HSF2

1 阿里电商

2 蚂蚁金服

3 本地生活

0-1 - 线程池资源枯竭

可能的原因

排查和解决步骤

1-1 - 地址非法

可能的原因

排查和解决步骤

2-1 - 路由选址执行失败

路由选址执行失败

2.x 升级至 3.x

升级到 Dubbo 3.X 的收益

Dubbo 3.0 新特性

升级前的兼容性检查

1. 直接修改 Dubbo 源码

3-1 - 将地址转换成 Invoker 失败

可能的原因

排查和解决步骤

4-1 - 不支持的协议

可能的原因

排查和解决步骤

5-1 - 配置中心连接失败

可能的原因

排查和解决步骤

6-1 - 服务端连接失败

可能的原因

排查和解决步骤

7-1 - QOS 已关闭

可能的原因

排查和解决步骤

81-1 - ZK 启动异常

可能的原因

排查和解决步骤

99-0 - 内部未知错误

可能的原因

排查和解决步骤

Dubbo SPI

1.简介

2.SPI 示例

2.1 Java SPI 示例

dubbo 协议

特性

约束

dubbo 协议

特性

约束

dubbo:application

dubbo:application

dubbo:argument

dubbo:argument

dubbo:config-center

dubbo:config-center

dubbo:consumer

dubbo:consumer

dubbo:method

dubbo:method

dubbo:module

dubbo:module

dubbo:monitor

dubbo:monitor

dubbo:parameter

dubbo:parameter

dubbo:protocol

dubbo:protocol

dubbo:provider

dubbo:provider

dubbo:reference

dubbo:reference

dubbo:registry

dubbo:registry

dubbo:service

dubbo:service

filter概述

Filter

Http Filter List

How to define custom http filter

step one