开发者指南

参与

(+) (#)

流程

(#)

1. 如果是扩展功能，直接新增工程，黑盒依赖Dubbo进行扩展。
2. 如果是改BUG，或修改框架本身，可以从Dubb的GitHub上Fork工程。
3. 修改后通过Push Request反馈修改。

任务

(#)

版本管理

(+) (#)

新功能的开发 和 稳定性的提高 对产品都很重要。

但是添加新功能对影响稳定性，Dubbo使用如下的版本开发模式来保障两者。

2个版本并行开发

• BugFix版本，低版本，比如2.4.x。是GA版本，线上使用的版本，只会BugFix，升级第三位版本号。
  # 这个版本可放在SVN的Fix分支上。
• 新功能版本，高版本，比如2.5.x。加新功能的版本，会给对新功能有需求的应用试用。
  # 这个版本可放在SVN的Trunk上。

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

在2.5.x够稳定后：

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

优势

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

用户要配合的职责

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

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

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

源码构建

(+) (#)

Browser:

To browse the source tree directly:

https://github.com/alibaba/dubbo

Git:

Use this command to check out the latest project source code:

Powered by: Git

Branches

We use the trunk for the next main release; then we use a branch for any bug fixes on the previous major release. You can look at all branches here:

https://github.com/alibaba/dubbo/tags

Building

Dubbo uses Maven as its build tool. If you don‘t fancy using Maven you can use your IDE directly or Download a distribution or JAR.

Required:

• Java 1.5 or better
• Download and install Maven 2.2.1 or better.
• Get the latest Source

  svn checkout http://code.alibabatech.com/svn/dubbo/trunk dubbo

Maven options

To build dubbo maven has to be configured to use more memory

A normal build

Doing a Quick Build

Available as of Dubbo 2.0

The following skips building the manual, the distro and does not execute the unit tests.

Using an IDE

If you prefer to use an IDE then you can auto-generate the IDE‘s project files using maven plugins. e.g.

or

Importing into Eclipse

If you have not already done so, you will need to make Eclipse aware of the Maven repository so that it can build everything. In the preferences, go to Java->Build Path->Classpath and define a new Classpath Variable named M2_REPO that points to your local Maven repository (i.e., ~/.m2/repository on Unix and c:\Documents and Settings\<user>\.m2\repository on Windows).

You can also get Maven to do this for you:

Building source jars

If you want to build jar files with the source code, that for instance Eclipse can important so you can debug the Dubbo code as well. Then you can run this command from the dubbo root folder:

框架设计

(+) (#)

整体设计

如果你觉得图过于复杂，请查看：>>框架图绘制步骤动画

图例说明：

• 图中左边淡蓝背景的为服务消费方使用的接口，右边淡绿色背景的为服务提供方使用的接口， 位于中轴线上的为双方都用到的接口。
• 图中从下至上分为十层，各层均为单向依赖，右边的黑色箭头代表层之间的依赖关系，每一层都可以剥离上层被复用，其中，Service和Config层为API，其它各层均为SPI。
• 图中绿色小块的为扩展接口，蓝色小块为实现类，图中只显示用于关联各层的实现类。
• 图中蓝色虚线为初始化过程，即启动时组装链，红色实线为方法调用过程，即运行时调时链，紫色三角箭头为继承，可以把子类看作父类的同一个节点，线上的文字为调用的方法。

各层说明：

• config，配置层，对外配置接口，以ServiceConfig, ReferenceConfig为中心，可以直接new配置类，也可以通过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实际上不算一层，而是一个独立的节点，只是为了全局概览，用层的方式画在一起。

模块分包

模块说明：

• dubbo-common 公共逻辑模块，包括Util类和通用模型。
• dubbo-remoting 远程通讯模块，相当于Dubbo协议的实现，如果RPC用RMI协议则不需要使用此包。
• dubbo-rpc 远程调用模块，抽象各种协议，以及动态代理，只包含一对一的调用，不关心集群的管理。
• dubbo-cluster 集群模块，将多个服务提供方伪装为一个提供方，包括：负载均衡, 容错，路由等，集群的地址列表可以是静态配置的，也可以是由注册中心下发。
• dubbo-registry 注册中心模块，基于注册中心下发地址的集群方式，以及对各种注册中心的抽象。
• dubbo-monitor 监控模块，统计服务调用次数，调用时间的，调用链跟踪的服务。
• dubbo-config 配置模块，是Dubbo对外的API，用户通过Config使用Dubbo，隐藏Dubbo所有细节。
• dubbo-container 容器模块，是一个Standlone的容器，以简单的Main加载Spring启动，因为服务通常不需要Tomcat/JBoss等Web容器的特性，没必要用Web容器去加载服务。

整体上按照分层结构进行分包，与分层的不同点在于：

• container为服务容器，用于部署运行服务，没有在层中画出。
• protocol层和proxy层都放在rpc模块中，这两层是rpc的核心，在不需要集群时(只有一个提供者)，可以只使用这两层完成rpc调用。
• transport层和exchange层都放在remoting模块中，为rpc调用的通讯基础。
• serialize层放在common模块中，以便更大程度复用。

依赖关系

图例说明：

• 图中小方块Protocol, Cluster, Proxy, Service, Container, Registry, Monitor代表层或模块，蓝色的表示与业务有交互，绿色的表示只对Dubbo内部交互。
• 图中背景方块Consumer, Provider, Registry, Monitor代表部署逻辑拓普节点。
• 图中蓝色虚线为初始化时调用，红色虚线为运行时异步调用，红色实线为运行时同步调用。
• 图中只包含RPC的层，不包含Remoting的层，Remoting整体都隐含在Protocol中。

调用链

展开总设计图的红色调用链，如下：

暴露服务时序

展开总设计图左边服务提供方暴露服务的蓝色初始化链，时序图如下：

引用服务时序

展开总设计图右边服务消费方引用服务的蓝色初始化链，时序图如下：

领域模型

在Dubbo的核心领域模型中：

• Protocol是服务域，它是Invoker暴露和引用的主功能入口，它负责Invoker的生命周期管理。
• Invoker是实体域，它是Dubbo的核心模型，其它模型都向它靠扰，或转换成它，它代表一个可执行体，可向它发起invoke调用，它有可能是一个本地的实现，也可能是一个远程的实现，也可能一个集群实现。
• Invocation是会话域，它持有调用过程中的变量，比如方法名，参数等。

基本原则

• 采用Microkernel + Plugin模式，Microkernel只负责组将Plugin，Dubbo自身的功能也是通过扩展点实现的，也就是Dubbo的所有功能点都可被用户自定义扩展所替换。
• 采用URL作为配置信息的统一格式，所有扩展点都通过传递URL携带配置信息。

更多设计原则参见：《框架设计原则》

扩展点加载

(+) (#)

扩展点配置

来源：

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/接口全限定名，内容为：配置名=扩展实现类全限定名，多个实现类用换行符分隔。

(注意：这里的配置文件是放在你自己的jar包内，不是dubbo本身的jar包内，Dubbo会全ClassPath扫描所有jar包内同名的这个文件，然后进行合并)

扩展Dubbo的协议示例：

在协议的实现jar包内放置文本文件：META-INF/dubbo/com.alibaba.dubbo.rpc.Protocol，内容为：

实现类内容：

注意： 扩展点使用单一实例加载（请确保扩展实现的线程安全性），Cache在ExtensionLoader中。

扩展点自动包装

自动Wrap扩展点的Wrapper类

ExtensionLoader会把加载扩展点时（通过扩展点配置文件中内容），如果该实现有拷贝构造函数，则判定为扩展点Wrapper类。

Wrapper类同样实现了扩展点接口。

Wrapper类内容：

Wrapper不是扩展点实现，用于从ExtensionLoader返回扩展点时，Wrap在扩展点实现外。即从ExtensionLoader中返回的实际上是Wrapper类的实例，Wrapper持有了实际的扩展点实现类。

扩展点的Wrapper类可以有多个，也可以根据需要新增。

通过Wrapper类可以把所有扩展点公共逻辑移至Wrapper中。新加的Wrapper在所有的扩展点上添加了逻辑，有些类似AOP（Wraper代理了扩展点）。

扩展点自动装配

加载扩展点时，自动注入依赖的扩展点

加载扩展点时，扩展点实现类的成员如果为其它扩展点类型，ExtensionLoader在会自动注入依赖的扩展点。

ExtensionLoader通过扫描扩展点实现类的所有set方法来判定其成员。

即ExtensionLoader会执行扩展点的拼装操作。

示例：有两个为扩展点CarMaker（造车者）、wheelMaker(造轮者)

接口类如下：

CarMaker的一个实现类：

ExtensionLoader加载CarMaker的扩展点实现RaceCar时，setWheelMaker方法的WheelMaker也是扩展点则会注入WheelMaker的实现。

这里带来另一个问题，ExtensionLoader要注入依赖扩展点时，如何决定要注入依赖扩展点的哪个实现。在这个示例中，即是在多个WheelMaker的实现中要注入哪个。

这个问题在下面一点“Adaptive实例”中说明。

扩展点自适应

扩展点的Adaptive实例

ExtensionLoader注入的依赖扩展点是一个Adaptive实例，直到扩展点方法执行时才决定调用是一个扩展点实现。

Dubbo使用URL对象（包含了Key-Value）传递配置信息。

扩展点方法调用会有URL参数（或是参数有URL成员）

这样依赖的扩展点也可以从URL拿到配置信息，所有的扩展点自己定好配置的Key后，配置信息从URL上从最外层传入。URL在配置传递上即是一条总线。

示例：有两个为扩展点CarMaker（造车者）、wheelMaker(造轮者)

接口类如下：

CarMaker的一个实现类：

当上面执行

时，注入的Adaptive实例可以提取约定Key来决定使用哪个WheelMaker实现来调用对应实现的真正的makeWheel方法。

如提取wheel.type key即url.get("wheel.type")来决定WheelMake实现。

Adaptive实例的逻辑是固定，指定提取的URL的Key，即可以代理真正的实现类上，可以动态生成。

在Dubbo的ExtensionLoader的扩展点类开对应的Adaptive实现是在加载扩展点里动态生成。指定提取的URL的Key通过@Adaptive注解在接口方法上提供。

下面是Dubbo的Transporter扩展点的代码：

对于bind方法表示，Adaptive实现先查找"server"key，如果该Key没有值则找"transport"key值，来决定代理到哪个实际扩展点。

3. Dubbo配置模块中扩展点的配置

Dubbo配置模块中，扩展点均有对应配置属性或标签，通过配置指定使用哪个扩展实现。

比如：<dubbo:protocol name="xxx" />

扩展点自动激活

对于集合类扩展点，比如：Filter, InvokerListener, ExportListener, TelnetHandler, StatusChecker等，
可以同时加载多个实现，此时，可以用自动激活来简化配置，如：

或：

或：

实现细节

(+) (#)

初始化过程细节

(+) (#)

解析服务

• 基于dubbo.jar内的META-INF/spring.handlers配置，Spring在遇到dubbo名称空间时，会回调DubboNamespaceHandler。
• 所有dubbo的标签，都统一用DubboBeanDefinitionParser进行解析，基于一对一属性映射，将XML标签解析为Bean对象。
• 在ServiceConfig.export()或ReferenceConfig.get()初始化时，将Bean对象转换URL格式，所有Bean属性转成URL的参数。
• 然后将URL传给Protocol扩展点，基于扩展点的Adaptive机制，根据URL的协议头，进行不同协议的服务暴露或引用。

暴露服务

(1) 只暴露服务端口：

• 在没有注册中心，直接暴露提供者的情况下，即：
  • <dubbo:service regisrty="N/A" /> or <dubbo:registry address="N/A" />
• ServiceConfig解析出的URL的格式为：
  • dubbo://service-host/com.foo.FooService?version=1.0.0
• 基于扩展点的Adaptive机制，通过URL的"dubbo://"协议头识别，直接调用DubboProtocol的export()方法，打开服务端口。

(2) 向注册中心暴露服务：

• 在有注册中心，需要注册提供者地址的情况下，即：
  • <dubbo:registry address="zookeeper://10.20.153.10:2181" />
• ServiceConfig解析出的URL的格式为：
  • registry://registry-host/com.alibaba.dubbo.registry.RegistryService?export=URL.encode("dubbo://service-host/com.foo.FooService?version=1.0.0")
• 基于扩展点的Adaptive机制，通过URL的"registry://"协议头识别，就会调用RegistryProtocol的export()方法，将export参数中的提供者URL，先注册到注册中心，再重新传给Protocol扩展点进行暴露：
  • dubbo://service-host/com.foo.FooService?version=1.0.0
• 基于扩展点的Adaptive机制，通过提供者URL的"dubbo://"协议头识别，就会调用DubboProtocol的export()方法，打开服务端口。

引用服务

(1) 直连引用服务：

• 在没有注册中心，直连提供者的情况下，即：
  • <dubbo:reference url="dubbo://service-host/com.foo.FooService?version=1.0.0" />
• ReferenceConfig解析出的URL的格式为：
  • dubbo://service-host/com.foo.FooService?version=1.0.0
• 基于扩展点的Adaptive机制，通过URL的"dubbo://"协议头识别，直接调用DubboProtocol的refer()方法，返回提供者引用。

(2) 从注册中心发现引用服务：

• 在有注册中心，通过注册中心发现提供者地址的情况下，即：
  • <dubbo:registry address="zookeeper://10.20.153.10:2181" />
• ReferenceConfig解析出的URL的格式为：
  • registry://registry-host/com.alibaba.dubbo.registry.RegistryService?refer=URL.encode("consumer://consumer-host/com.foo.FooService?version=1.0.0")
• 基于扩展点的Adaptive机制，通过URL的"registry://"协议头识别，就会调用RegistryProtocol的refer()方法，基于refer参数中的条件，查询提供者URL，如：
  • dubbo://service-host/com.foo.FooService?version=1.0.0
• 基于扩展点的Adaptive机制，通过提供者URL的"dubbo://"协议头识别，就会调用DubboProtocol的refer()方法，得到提供者引用。
• 然后RegistryProtocol将多个提供者引用，通过Cluster扩展点，伪装成单个提供者引用返回。

拦截服务

• 基于扩展点的Wrapper机制，所有的Protocol扩展点都会自动套上Wrapper类。
• 基于ProtocolFilterWrapper类，将所有Filter组装成链，在链的最后一节调用真实的引用。
• 基于ProtocolListenerWrapper类，将所有InvokerListener和ExporterListener组装集合，在暴露和引用前后，进行回调。
• 包括监控在内，所有附加功能，全部通过Filter拦截实现。

远程调用细节

(+) (#)

服务提供者暴露一个服务的详细过程

上图是服务提供者暴露服务的主过程：
首先ServiceConfig类拿到对外提供服务的实际类ref(如：HelloWorldImpl),然后通过ProxyFactory类的getInvoker方法使用ref生成一个AbstractProxyInvoker实例，到这一步就完成具体服务到Invoker的转化。接下来就是Invoker转换到Exporter的过程。
Dubbo处理服务暴露的关键就在Invoker转换到Exporter的过程(如上图中的红色部分)，下面我们以Dubbo和RMI这两种典型协议的实现来进行说明：

Dubbo的实现

Dubbo协议的Invoker转为Exporter发生在DubboProtocol类的export方法，它主要是打开socket侦听服务，并接收客户端发来的各种请求，通讯细节由Dubbo自己实现。

RMI的实现

RMI协议的Invoker转为Exporter发生在RmiProtocol类的export方法，
它通过Spring或Dubbo或JDK来实现RMI服务，通讯细节这一块由JDK底层来实现，这就省了不少工作量。

服务消费者消费一个服务的详细过程

上图是服务消费的主过程：
首先ReferenceConfig类的init方法调用Protocol的refer方法生成Invoker实例(如上图中的红色部分)，这是服务消费的关键。接下来把Invoker转换为客户端需要的接口(如：HelloWorld)。
关于每种协议如RMI/Dubbo/Web service等它们在调用refer方法生成Invoker实例的细节和上一章节所描述的类似。

满眼都是Invoker

由于Invoker是Dubbo领域模型中非常重要的一个概念，很多设计思路都是向它靠拢。这就使得Invoker渗透在整个实现代码里，对于刚开始接触Dubbo的人，确实容易给搞混了。
下面我们用一个精简的图来说明最重要的两种Invoker：服务提供Invoker和服务消费Invoker：

为了更好的解释上面这张图，我们结合服务消费和提供者的代码示例来进行说明：

服务消费者代码

上面代码中的’DemoService’就是上图中服务消费端的proxy，用户代码通过这个proxy调用其对应的Invoker(DubboInvoker、 HessianRpcInvoker、 InjvmInvoker、 RmiInvoker、 WebServiceInvoker中的任何一个)，而该Invoker实现了真正的远程服务调用。

服务提供者代码

上面这个类会被封装成为一个AbstractProxyInvoker实例，并新生成一个
Exporter实例。这样当网络通讯层收到一个请求后，会找到对应的Exporter实例，并调用它所对应的AbstractProxyInvoker实例，从而真正调用了服务提供者的代码。
Dubbo里还有一些其他的Invoker类，但上面两种是最重要的。

远程通讯细节

(+) (#)

协议头约定

线程派发模型

• Dispather
  • all, direct, message, execution, connection
• ThreadPool
  • fixed, cached

SPI参考手册

(+) (#)

协议扩展

(+) ([#])

(1) 扩展说明：

RPC协议扩展，封装远程调用细节。

契约：

• 当用户调用refer()所返回的Invoker对象的invoke()方法时，协议需相应执行同URL远端export()传入的Invoker对象的invoke()方法。
• 其中，refer()返回的Invoker由协议实现，协议通常需要在此Invoker中发送远程请求，export()传入的Invoker由框架实现并传入，协议不需要关心。

注意：

• 协议不关心业务接口的透明代理，以Invoker为中心，由外层将Invoker转换为业务接口。
• 协议不一定要是TCP网络通讯，比如通过共享文件，IPC进程间通讯等。

(2) 扩展接口：

(3) 扩展配置：

(4) 已知扩展：

(5) 扩展示例：

调用拦截扩展

(+) (#)

(1) 扩展说明

服务提供方和服务消费方调用过程拦截，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" />

(2) 扩展接口：

(3) 扩展配置：

(4) 已知扩展：

(5) 扩展示例：

引用监听扩展

(+) (#)

(1) 扩展说明：

当有服务引用时，触发该事件。

(2) 扩展接口：

(3) 扩展配置：

(4) 已知扩展：

(5) 扩展示例：

暴露监听扩展

(+) (#)

(1) 扩展说明：

当有服务暴露时，触发该事件。

(2) 扩展接口：

(3) 扩展配置：

(4) 已知扩展：

(5) 扩展示例：

集群扩展

(+) (#)

(1) 扩展说明：

当有多个服务提供方时，将多个服务提供方组织成一个集群，并伪装成一个提供方。

(2) 扩展接口：

(3) 扩展配置：

(4) 已知扩展：

(5) 扩展示例：

路由扩展

(+) (#)

(1) 扩展说明：

从多个服务提者方中选择一个进行调用。

(2) 扩展接口：

(3) 扩展配置：

(4) 已知扩展：

(5) 扩展示例：

负载均衡扩展

(+) (#)

(1) 扩展说明：

从多个服务提者方中选择一个进行调用。

(2) 扩展接口：

(3) 扩展配置：

(4) 已知扩展：

(5) 扩展示例：

合并结果扩展

(+) (#)

(1) 扩展说明：

合并返回结果，用于分组聚合。

(2) 扩展接口：

(3) 扩展配置：

(4) 已知扩展：

(5) 扩展示例：

注册中心扩展

(+) (#)

(1) 扩展说明：

负责服务的注册与发现。

(2) 扩展接口：

(3) 扩展配置：

(4) 扩展契约：

(5) 已知扩展：

(6) 扩展示例：

监控中心扩展

(+) (#)

(1) 扩展说明：

负责服务调用次和调用时间的监控。

(2) 扩展接口：

(3) 扩展配置：

(4) 已知扩展：

(5) 扩展示例：

扩展点加载扩展

(+) (#)

(1) 扩展说明：

扩展点本身的加载容器，可从不同容器加载扩展点。

(2) 扩展接口：

(3) 扩展配置：

(4) 已知扩展：

(5) 扩展示例：

动态代理扩展

(+) (#)

(1) 扩展说明：

将Invoker接口转换成业务接口。

(2) 扩展接口：

(3) 扩展配置：

(4) 已知扩展：

(5) 扩展示例：

编译器扩展

(+) (#)

(1) 扩展说明：

Java代码编译器，用于动态生成字节码，加速调用。

(2) 扩展接口：

(3) 扩展配置：

自动加载

(4) 已知扩展：

(5) 扩展示例：

消息派发扩展

(+) (#)

(1) 扩展说明：

通道信息派发器，用于指定线程池模型。

(2) 扩展接口：

(3) 扩展配置：

(4) 已知扩展：

(5) 扩展示例：

线程池扩展

(+) (#)

(1) 扩展说明：

服务提供方线程程实现策略，当服务器收到一个请求时，需要在线程池中创建一个线程去执行服务提供方业务逻辑。

(2) 扩展接口：

(3) 扩展配置：

(4) 已知扩展：

(5) 扩展示例：

序列化扩展

(+) (#)

(1) 扩展说明：

将对象转成字节流，用于网络传输，以及将字节流转为对象，用于在收到字节流数据后还原成对象。

(2) 扩展接口：

(3) 扩展配置：

(4) 已知扩展：

(5) 扩展示例：

网络传输扩展

(+) (#)

(1) 扩展说明：

远程通讯的服务器及客户端传输实现。

(2) 扩展接口：

(3) 扩展配置：

(4) 已知扩展：

(5) 扩展示例：

信息交换扩展

(+) (#)

(1) 扩展说明：

基于传输层之上，实现Request-Response信息交换语义。

(2) 扩展接口：

(3) 扩展配置：

(4) 已知扩展：

(5) 扩展示例：

组网扩展

(+) (#)

(1) 扩展说明：

对等网络节点组网器。

(2) 扩展接口：

(3) 扩展配置：

(4) 已知扩展：

(5) 扩展示例：

Telnet命令扩展

(+) (#)

(1) 扩展说明：

所有服务器均支持telnet访问，用于人工干预。

(2) 扩展接口：

(3) 扩展配置：

(4) 已知扩展：

(5) 扩展示例：

状态检查扩展

(+) (#)

(1) 扩展说明：

检查服务依赖各种资源的状态，此状态检查可同时用于telnet的status命令和hosting的status页面。

(2) 扩展接口：

(3) 扩展配置：

(4) 已知扩展：

(5) 扩展示例：

容器扩展

(+) (#)

(1) 扩展说明：

服务容器扩展，用于自定义加载内容。

(2) 扩展接口：

(3) 扩展配置：

(4) 已知扩展：

(5) 扩展示例：

页面扩展

(+) (#)

(1) 扩展说明：

对等网络节点组网器。

(2) 扩展接口：

(3) 扩展配置：

(4) 已知扩展：

(5) 扩展示例：

缓存扩展

(+) (#)

(1) 扩展说明：

用请求参数作为key，缓存返回结果。

(2) 扩展接口：

(3) 扩展配置：

(4) 已知扩展：

(5) 扩展示例：

验证扩展

(+) (#)

(1) 扩展说明：

参数验证扩展点。

(2) 扩展接口：

(3) 扩展配置：

(4) 已知扩展：

(5) 扩展示例：

日志适配扩展

(+) (#)

(1) 扩展说明：

日志输出适配扩展点。

(2) 扩展接口：

(3) 扩展配置：

(4) 已知扩展：

(5) 扩展示例：

技术兼容性测试

(+) (#)

TCK定义：http://en.wikipedia.org/wiki/Technology_Compatibility_Kit

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

(+) (#)

Registry TCK

(+) (#)

公共契约

(+) (#)

URL

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

日志

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

坏味道

(+) (#)

URL转换

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

1.1. 直接暴露服务：
EXPORT(dubbo://provider-address/com.xxx.XxxService?version=1.0.0")

1.2. 点对点直连服务：
REFER(dubbo://provider-address/com.xxx.XxxService?version=1.0.0)

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

2.1. 向注册中心暴露服务：
EXPORT(registry://registry-address/com.alibaba.dubbo.registry.RegistrySerevice?registry=dubbo&export=ENCODE(dubbo://provider-address/com.xxx.XxxService?version=1.0.0))

2.2. 获取注册中心：url.setProtocol(url.getParameter("registry", "dubbo"))
GETREGISTRY(dubbo://registry-address/com.alibaba.dubbo.registry.RegistrySerevice)

2.3. 注册服务地址：url.getParameterAndDecoded("export"))
REGISTER(dubbo://provider-address/com.xxx.XxxService?version=1.0.0)

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

3.1. 从注册中心订阅服务：
REFER(registry://registry-address/com.alibaba.dubbo.registry.RegistrySerevice?registry=dubbo&refer=ENCODE(version=1.0.0))

3.2. 获取注册中心：url.setProtocol(url.getParameter("registry", "dubbo"))
GETREGISTRY(dubbo://registry-address/com.alibaba.dubbo.registry.RegistrySerevice)

3.3. 订阅服务地址：url.addParameters(url.getParameterAndDecoded("refer"))
SUBSCRIBE(dubbo://registry-address/com.xxx.XxxService?version=1.0.0)

3.4. 通知服务地址：url.addParameters(url.getParameterAndDecoded("refer"))
NOTIFY(dubbo://provider-address/com.xxx.XxxService?version=1.0.0)

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

4.1. 注册中心路由规则推送：
NOTIFY(route://registry-address/com.xxx.XxxService?router=script&type=js&rule=ENCODE(function{...}))

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

5. 从文件加载路由规则

5.1. 从文件加载路由规则：
GETROUTE(file://path/file.js?router=script)

5.2. 获取路由器：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是根据调用方法参数（上面有调用哪个扩展点的信息）来选取一个真正的扩展点。

在Dubbo给定所有的扩展点上调用都有URL参数（整个扩展点网的上下文信息）。自适应扩展即是从URL确定要调用哪个扩展点实现。URL哪个Key的Value用来确定使用哪个扩展点，这个信息通过的@Adaptive注解在方法上说明。

由于自适应扩展点的上面的约定，ExtensionLoader会为扩展点自动生成自适应扩展点类(通过字节码)，并将其实例注入。

ExtensionLoader生成的自适应扩展点类如下：

@Adaptive注解使用如下：

如果URL这些Key都没有Value，使用 用 缺省的扩展（在接口的Default中设定的值）。
比如，String[] {"key1", "key2"}，表示

先在URL上找key1的Value作为要Adapt成的Extension名； 
key1没有Value，则使用key2的Value作为要Adapt成的Extension名。 
key2没有Value，使用缺省的扩展。 
如果没有设定缺省扩展，则方法调用会抛出IllegalStateException。 
如果不设置则缺省使用Extension接口类名的点分隔小写字串。
即对于Extension接口com.alibaba.dubbo.xxx.YyyInvokerWrapper的缺省值为String[] {"yyy.invoker.wrapper"}

Callback功能

1. 参数回调

1.1主要原理:在一个Consumer->provider的长连接上，自动在Consumer端暴露一个服务（实现方法参数上声明的接口A），provider端便可反向调用到consumer端的接口实例.
1.2实现细节：

• 为了在传输时能够对回调接口实例进行转换，自动暴露与自动引用目前在DubboCodec中实现.此处需要考虑将此逻辑与codec逻辑分离.
• 在根据invocation信息获取exporter时，需要判断是否是回调，如果是回调，会从attachments中取得回调服务实例的id，在获取exporter，此处用于consumer端可以对同一个callback接口做不同的实现。

2. 事件通知

2.1主要原理：Consumer在invoke方法时，判断如果有配置onreturn/onerror...则将onreturn对应的参数值(实例方法)加入到异步调用的回调列表中.
2.2实现细节：参数的传递采用URL，但URL中没有支持string-object，所以将实例方法存储在staticMap中，此处实现需要进行改造，http://code.alibabatech.com/jira/browse/DUBBO-168

Lazy连接

DubboProtocol特有功能，默认关闭
当客户端与服务端创建代理时，暂不建立tcp长连接，当有数据请求时在做连接初始化
此项功能自动关闭连接重试功能，开启发送重试功能（即发送数据时如果连接已断开，尝试重新建立连接）.

共享连接

DubboProtocol特有功能，默认开启
JVM A暴露了多个服务，JVM B引用了A中的多个服务，共享连接是说A与B多个服务调用是通过同一个TCP长连接进行数据传输，已达到减少服务端连接数的目的.
实现细节：对于同一个地址由于使用了共享连接，那invoker的destroy就需要特别注意，一方面要满足对同一个地址refer的invoker全部destroy后，连接需要关闭，另一方面还需要注意如何避免部分invoker destroy时不能关闭连接。在实现中采用了引用计数的方案，但为了防范，在连接关闭时，重新建立了一个Lazy connection(称为幽灵连接),用于当出现异常场景时，避免影响业务逻辑的正常调用.

sticky 策略

有多个服务提供者的情况下，配置了sticky后，在提供者可用的情况下，调用会继续发送到上一次的服务提供者. sticky策略默认开启了连接的lazy选项,用于避免开启无用的连接.

服务提供者选择逻辑

1.存在多个服务提供者的情况下，首先根据Loadbalance进行选择，如果选择的provider处于可用状态，则进行后续调用
2.如果第一步选择的服务提供者不可用，则从剩余服务提供者列表中继续选择，如果可用，进行后续调用
3.如果所有的服务提供者都不可用，重新遍历整个列表（优先从没有选过的列表中选择），判断是否有可用的服务提供者（选择过程中，不可用的服务提供者可能会恢复到可用状态），如果有，则进行后续调用
4.如果第三步没有选择出可用的服务提供者，会选第一步选出的invoker中的下一个（如果不是最后一个），避免碰撞.

编码约定

(+) (#)

Source code and documentation contributed to the Dubbo repositories should observe the:

• Code Conventions for the Java Programming Language
• How to Write Doc Comments for the Javadoc Tool

as core references regarding the formatting of code and documentation.

• 异常和日志：
  • 尽可能携带完整的上下文信息，比如出错原因，出错的机器地址，调用对方的地址，连的注册中心地址，使用Dubbo的版本等。
  • 尽量将直接原因写在最前面，所有上下文信息，在原因后用键值对显示。
  • 抛出异常的地方不用打印日志，由最终处理异常者决定打印日志的级别，吃掉异常必需打印日志。
  • 打印ERROR日志表示需要报警，打印WARN日志表示可以自动恢复，打印INFO表示正常信息或完全不影响运行。
  • 建议应用方在监控中心配置ERROR日志实时报警，WARN日志每周汇总发送通知。
  • RpcException是Dubbo对外的唯一异常类型，所有内部异常，如果要抛出给用户，必须转为RpcException。
  • RpcException不能有子类型，所有类型信息用ErrorCode标识，以便保持兼容。
• 配置和URL：
  • 配置对象属性首字母小写，多个单词用驼峰命名(Java约定)。
  • 配置属性全部用小写，多个单词用"-"号分隔(Spring约定)。
  • URL参数全部用小写，多个单词用"."号分隔(Dubbo约定)。
  • 尽可能用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子包下，不同实现用放在以扩展点名字命名的子包下。
  • 尽量保持子包依赖父包，而不要反向。

检查列表

(+) (#)

1. 发布前checklist:
1.1 jira ticket 过一遍
1.2 svn change list
1.3 ticket关联code
1.4 test code
1.5 find bugs

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

3. Partner Check
3.1 Partner以用户的方式运行一下功能
3.2 Partner发现问题、添加测试（集成测试）复现总是；Owner完成实现。（保证两方的时间投入PatternerCheck 的给予时间保证）
3.3 Owner向Partner讲述一遍实现。

设计原则

(+) (#)

• 魔鬼在细节中
• 一些设计上的基本常识
• 谈谈扩充式扩展与增量式扩展
• 配置设计
• 设计实现的健壮性
• 防痴呆设计
• 扩展点重构