开发指南 on Apache Dubbo

源码构建

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 仓库。 ²

框架设计

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 的扩展点加载从 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

初始化过程细节

解析服务

基于 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，先注册到注册中心。

公共契约

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

URL

所有扩展点参数都包含 URL 参数，URL 作为上下文信息贯穿整个扩展点设计体系。
URL 采用标准格式：protocol://username:password@host:port/path?key=value&key=value

日志

如果不可恢复或需要报警，打印 ERROR 日志。
如果可恢复异常，或瞬时的状态不一致，打印 WARN 日志。
正常运行时的中间状态提示，打印 INFO 日志。

版本管理

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

新功能的开发 和 稳定性的提高 对产品都很重要。但是添加新功能会影响稳定性，Dubbo 使用如下的版本开发模式来保障两者。

2 个版本并行开发

BugFix 版本：低版本，比如 2.4.x。是 GA 版本，线上使用的版本，只会 BugFix，升级第三位版本号。
新功能版本：高版本，比如 2.5.x。加新功能的版本，会给对新功能有需求的应用试用。

2.5.x 的新功能基本稳定后，进入 2.5.x 试用阶段。找足够多的应用试用 2.5.x 版本。

在 2.5.x 够稳定后：

2.5.x 成为 GA 版本，只 BugFix，推广使用此版本。如果版本可用，可以推进应用在期望的时间点内升级到 GA 版本。
2.4.x 不再开发，应用碰到 Bug 让直接升级。（这个称为“夕阳条款”）
从 2.5.x 拉成分支 2.6.0，作为新功能开发版本。

优势

保证 GA 版本是稳定的！因为：
- 只会作 BugFix
- 成为 GA 版本前有试用阶段
新功能可以在高版本中快速响应，并让应用能试用新功能。
不会版本过多，导致开发和维护成本剧增

用户要配合的职责

由于开发只会 BugFix GA 版本，所以用户需要积极跟进升级到 GA 版本，以 Fix 发现的问题。

定期升级版本给用户带来了不安。这是一个假命题，说明如下：

GA 经过一个试用阶段保持稳定。
GA 版本有 Bug 会火速 Fix
相对出问题才升级到 GA 版本（可能跨了多个版本）定期升级平摊风险（类似小步快跑）。经历过周期长的大项目的同学会有这样的经历，三方库版本长时间不升级，结果出了问题不得不升级到新版本（跨了多个版本）风险巨大。

检查列表

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

发布前 checklist

jira ticket 过一遍
svn change list
ticket 关联 code
test code
find bugs

修复时 checklist

修复代码前先建 ticket
修复代码前先写测试用例
需要伙伴检查
test code(正常流程/异常流程)
讲一遍逻辑
契约文档化
以上内容都写到ticket的评论上
代码注释写清楚，用中文无妨
每个版本要有 owner，确保 scope 和 check

Partner Check

Partner 以用户的方式运行一下功能
Partner 发现问题、添加测试（集成测试）直到不再复现；Owner 完成实现。（保证两方在Partner Check上的时间投入）
Owner 向 Partner 讲述一遍实现。

编码约定

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

代码风格

Dubbo 的源代码和 JavaDoc 遵循以下的规范：

异常和日志

尽可能携带完整的上下文信息，比如出错原因，出错的机器地址，调用对方的地址，连的注册中心地址，使用 Dubbo 的版本等。
尽量将直接原因写在最前面，所有上下文信息，在原因后用键值对显示。
抛出异常的地方不用打印日志，由最终处理异常者决定打印日志的级别，吃掉异常必需打印日志。
打印 ERROR 日志表示需要报警，打印 WARN 日志表示可以自动恢复，打印 INFO 表示正常信息或完全不影响运行。
建议应用方在监控中心配置 ERROR 日志实时报警，WARN 日志每周汇总发送通知。
RpcException 是 Dubbo 对外的唯一异常类型，所有内部异常，如果要抛出给用户，必须转为 RpcException。
RpcException 不能有子类型，所有类型信息用 ErrorCode 标识，以便保持兼容。

配置和 URL

配置对象属性首字母小写，多个单词用驼峰命名 ¹。
配置属性全部用小写，多个单词用"-“号分隔 ²。
URL参数全部用小写，多个单词用”.“号分隔 ³。
尽可能用 URL 传参，不要自定义 Map 或其它上下文格式，配置信息也转成 URL 格式使用。
尽量减少 URL 嵌套，保持 URL 的简洁性。

单元和集成测试

单元测试统一用 JUnit 和 EasyMock，集成测试用 TestNG，数据库测试用 DBUnit。
保持单元测试用例的运行速度，不要将性能和大的集成用例放在单元测试中。
保持单元测试的每个用例都用 try...finally 或 tearDown 释放资源。
减少 while 循环等待结果的测试用例，对定时器和网络的测试，用以将定时器中的逻辑抽为方法测试。
对于容错行为的测试，比如 failsafe 的测试，统一用 LogUtil 断言日志输出。

扩展点基类与 AOP

AOP 类都命名为 XxxWrapper，基类都命名为 AbstractXxx。
扩展点之间的组合将关系由 AOP 完成，ExtensionLoader 只负载加载扩展点，包括 AOP 扩展。
尽量采用 IoC 注入扩展点之间的依赖，不要直接依赖 ExtensionLoader 的工厂方法。
尽量采用 AOP 实现扩展点的通用行为，而不要用基类，比如负载均衡之前的 isAvailable 检查，它是独立于负载均衡之外的，不需要检查的是URL参数关闭。
对多种相似类型的抽象，用基类实现，比如 RMI, Hessian 等第三方协议都已生成了接口代理，只需将将接口代理转成 Invoker 即可完成桥接，它们可以用公共基类实现此逻辑。
基类也是 SPI 的一部分，每个扩展点都应该有方便使用的基类支持。

模块与分包

基于复用度分包，总是一起使用的放在同一包下，将接口和基类分成独立模块，大的实现也使用独立模块。
所有接口都放在模块的根包下，基类放在 support 子包下，不同实现用放在以扩展点名字命名的子包下。
尽量保持子包依赖父包，而不要反向。

Java 约定 ↩︎

坏味道

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

URL 转换

1. 点对点暴露和引用服务

直接暴露服务：

EXPORT(dubbo://provider-address/com.xxx.XxxService?version=1.0.0")

点对点直连服务：

REFER(dubbo://provider-address/com.xxx.XxxService?version=1.0.0)

2. 通过注册中心暴露服务

向注册中心暴露服务：

EXPORT(registry://registry-address/org.apache.dubbo.registry.RegistrySerevice?registry=dubbo&export=ENCODE(dubbo://provider-address/com.xxx.XxxService?version=1.0.0))

获取注册中心：

url.setProtocol(url.getParameter("registry", "dubbo"))
GETREGISTRY(dubbo://registry-address/org.apache.dubbo.registry.RegistrySerevice)

注册服务地址：

url.getParameterAndDecoded("export"))
REGISTER(dubbo://provider-address/com.xxx.XxxService?version=1.0.0)

3. 通过注册中心引用服务

从注册中心订阅服务：

REFER(registry://registry-address/org.apache.dubbo.registry.RegistrySerevice?registry=dubbo&refer=ENCODE(version=1.0.0))

获取注册中心：

url.setProtocol(url.getParameter("registry", "dubbo"))
GETREGISTRY(dubbo://registry-address/org.apache.dubbo.registry.RegistrySerevice)

订阅服务地址：

url.addParameters(url.getParameterAndDecoded("refer"))
SUBSCRIBE(dubbo://registry-address/com.xxx.XxxService?version=1.0.0)

通知服务地址：

url.addParameters(url.getParameterAndDecoded("refer"))
NOTIFY(dubbo://provider-address/com.xxx.XxxService?version=1.0.0)

4. 注册中心推送路由规则

注册中心路由规则推送：

NOTIFY(route://registry-address/com.xxx.XxxService?router=script&type=js&rule=ENCODE(function{...}))

获取路由器：

url.setProtocol(url.getParameter("router", "script"))
GETROUTE(script://registry-address/com.xxx.XxxService?type=js&rule=ENCODE(function{...}))

5. 从文件加载路由规则

从文件加载路由规则：

GETROUTE(file://path/file.js?router=script)

获取路由器：

url.setProtocol(url.getParameter("router", "script")).addParameter("type", SUFFIX(file)).addParameter("rule", READ(file))
GETROUTE(script://path/file.js?type=js&rule=ENCODE(function{...}))

调用参数

path 服务路径
group 服务分组
version 服务版本
dubbo 使用的 dubbo 版本
token 验证令牌
timeout 调用超时

扩展点的加载

1. 自适应扩展点

ExtensionLoader 加载扩展点时，会检查扩展点的属性（通过set方法判断），如该属性是扩展点类型，则会注入扩展点对象。因为注入时不能确定使用哪个扩展点（在使用时确定），所以注入的是一个自适应扩展（一个代理）。自适应扩展点调用时，选取一个真正的扩展点，并代理到其上完成调用。Dubbo 是根据调用方法参数（上面有调用哪个扩展点的信息）来选取一个真正的扩展点。

技术兼容性测试

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

Dubbo 的协议，通讯，序列化，注册中心，负载均策等扩展点，都有多种可选策略，以应对不同应用场景，而我们的测试用例很分散，当用户自己需要加一种新的实现时，总是不确定能否满足扩展点的完整契约。

所以，我们需要对核心扩展点写 TCK (Technology Compatibility Kit)，用户增加一种扩展实现，只需通过 TCK，即可确保与框架的其它部分兼容运行，可以有效提高整体健壮性，也方便第三方扩展者接入，加速开源社区的成熟。

开源社区的行知同学已着手研究这一块，他的初步想法是借鉴 JBoss 的 CDI-TCK，做一个 Dubbo 的 TCK 基础框架，在此之上实现 Dubbo 的扩展点 TCK 用例。

参见：http://docs.jboss.org/cdi/tck/reference/1.0.1-Final/html/introduction.html

如果大家有兴趣，也可以一起研究，和行知一块讨论。

Protocol TCK

TODO

Registry TCK

TODO