extends Node {
/**
+ *
+ *
+ * com.alibaba.dubbo.rpc.cluster.Directory 接口 + com.alibaba.dubbo.rpc.cluster.directory 包。
+ * Directory 代表了多个 Invoker ，可以把它看成 List ，但与 List 不同的是，它的值可能是动态变化的，比如注册中心推送变更。
+ *
* get service type.
*
* @return service type.
diff --git a/dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/LoadBalance.java b/dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/LoadBalance.java
index 4e6ced18a0e5..c368a4d4f873 100644
--- a/dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/LoadBalance.java
+++ b/dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/LoadBalance.java
@@ -27,6 +27,10 @@
import java.util.List;
/**
+ *
+ * com.alibaba.dubbo.rpc.cluster.LoadBalance 接口 + com.alibaba.dubbo.rpc.cluster.loadbalance 包。
+ * LoadBalance 负责从多个 Invoker 中选出具体的一个用于本次调用，选的过程包含了负载均衡算法，调用失败后，需要重选。
+ *
* LoadBalance. (SPI, Singleton, ThreadSafe)
*
* Load-Balancing
diff --git a/dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/Merger.java b/dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/Merger.java
index 64bccf8cbdd5..1c1b227f31b2 100644
--- a/dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/Merger.java
+++ b/dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/Merger.java
@@ -18,6 +18,12 @@
import org.apache.dubbo.common.extension.SPI;
+/**
+ * 合并结果
+ * com.alibaba.dubbo.rpc.cluster.Merger 接口 + com.alibaba.dubbo.rpc.cluster.merger 包。
+ * 合并返回结果，用于分组聚合。
+ * @param
+ */
@SPI
public interface Merger {
diff --git a/dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/Router.java b/dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/Router.java
index 47aa2515a3c0..655b807da7c4 100644
--- a/dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/Router.java
+++ b/dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/Router.java
@@ -24,6 +24,11 @@
import java.util.List;
/**
+ *
+ * com.alibaba.dubbo.rpc.cluster.Router 接口 + com.alibaba.dubbo.rpc.cluster.router 包。
+ * 负责从多个 Invoker 中按路由规则选出子集，比如读写分离，应用隔离等。
+ *
+ *
* Router. (SPI, Prototype, ThreadSafe)
*
* Routing
diff --git "a/dubbo-cluster/\346\265\201\347\250\213\345\233\276.jpg" "b/dubbo-cluster/\346\265\201\347\250\213\345\233\276.jpg"
new file mode 100644
index 000000000000..ca8e7340a748
Binary files /dev/null and "b/dubbo-cluster/\346\265\201\347\250\213\345\233\276.jpg" differ
diff --git a/dubbo-common/readme.md b/dubbo-common/readme.md
new file mode 100644
index 000000000000..7f23fad64124
--- /dev/null
+++ b/dubbo-common/readme.md
@@ -0,0 +1,3 @@
+## dubbo-common
+
+> 公共逻辑模块：提供工具类和通用模型
\ No newline at end of file
diff --git a/dubbo-common/src/main/java/org/apache/dubbo/common/URL.java b/dubbo-common/src/main/java/org/apache/dubbo/common/URL.java
index a83ca91e227e..9e6bfb549b54 100644
--- a/dubbo-common/src/main/java/org/apache/dubbo/common/URL.java
+++ b/dubbo-common/src/main/java/org/apache/dubbo/common/URL.java
@@ -38,6 +38,12 @@
/**
* URL - Uniform Resource Locator (Immutable, ThreadSafe)
+ *
+ *
+ * 格式为 protocol://username:password@host:port/path?key=value&key=value ，通过 URL#buildString(...) 方法生成。
+ * parameters 属性，参数集合。从上面的 Service URL 例子我们可以看到，里面的 key=value ，实际上就是 Service 对应的配置项。
+ * 该属性，通过 AbstractConfig#appendParameters(parameters, config, prefix) 方法生成。
+ *
*
* url example:
*
@@ -72,20 +78,40 @@
private static final long serialVersionUID = -1985165475234910535L;
+ /**
+ * 协议名称
+ */
private final String protocol;
+ /**
+ * 用户名
+ */
private final String username;
+ /**
+ * 密码
+ */
private final String password;
- // by default, host to registry
+ /**
+ * by default, host to registry
+ * 地址
+ */
private final String host;
-
- // by default, port to registry
+ /**
+ * by default, port to registry
+ * 端口
+ */
private final int port;
+ /**
+ * 路径 服务名
+ */
private final String path;
+ /**
+ * 参数集合
+ */
private final Map parameters;
// ==== cache ====
diff --git a/dubbo-common/src/main/java/org/apache/dubbo/common/extension/ExtensionLoader.java b/dubbo-common/src/main/java/org/apache/dubbo/common/extension/ExtensionLoader.java
index fcbb292ec728..2719f4eb1f30 100644
--- a/dubbo-common/src/main/java/org/apache/dubbo/common/extension/ExtensionLoader.java
+++ b/dubbo-common/src/main/java/org/apache/dubbo/common/extension/ExtensionLoader.java
@@ -45,6 +45,8 @@
import java.util.regex.Pattern;
/**
+ * 拓展加载器。这是 Dubbo SPI 的核心
+ *
* Load dubbo extensions
*
* - auto inject dependency extension
@@ -52,7 +54,8 @@
* - default extension is an adaptive instance
*
*
- * @see Service Provider in Java 5
+ * @see Service
+ * Provider in Java 5
* @see org.apache.dubbo.common.extension.SPI
* @see org.apache.dubbo.common.extension.Adaptive
* @see org.apache.dubbo.common.extension.Activate
@@ -69,29 +72,117 @@ public class ExtensionLoader {
private static final Pattern NAME_SEPARATOR = Pattern.compile("\\s*[,]+\\s*");
+ //////////////////////////////// 静态属性 //////////////////////////////////////////
+
+ /**
+ * 拓展加载器集合
+ * key:拓展接口
+ */
private static final ConcurrentMap, ExtensionLoader> EXTENSION_LOADERS = new ConcurrentHashMap, ExtensionLoader>();
+ /**
+ * 拓展实现类集合
+ *
+ * key：拓展实现类
+ * value：拓展对象。
+ *
+ * 例如，key 为 Class
+ * value 为 AccessLogFilter 对象
+ */
private static final ConcurrentMap, Object> EXTENSION_INSTANCES = new ConcurrentHashMap, Object>();
- // ==============================
-
+ // ==============================对象属性===============================
+ /**
+ * 拓展接口。
+ * 例如，Protocol
+ */
private final Class type;
-
+ /**
+ * 对象工厂
+ *
+ * 用于调用 {@link #injectExtension(Object)} 方法，向拓展对象注入依赖属性。
+ *
+ * 例如，StubProxyFactoryWrapper 中有 `Protocol protocol` 属性。
+ */
private final ExtensionFactory objectFactory;
-
+ /**
+ * 缓存的拓展名与拓展类的映射。
+ *
+ * 和 {@link #cachedClasses} 的 KV 对调。
+ *
+ * 通过 {@link #loadExtensionClasses} 加载
+ */
private final ConcurrentMap, String> cachedNames = new ConcurrentHashMap, String>();
-
+ /**
+ * 缓存的拓展实现类集合。
+ *
+ * 不包含如下两种类型：
+ * 1. 自适应拓展实现类。例如 AdaptiveExtensionFactory
+ * 2. 带唯一参数为拓展接口的构造方法的实现类，或者说拓展 Wrapper 实现类。例如，ProtocolFilterWrapper 。
+ * 拓展 Wrapper 实现类，会添加到 {@link #cachedWrapperClasses} 中
+ *
+ * 通过 {@link #loadExtensionClasses} 加载
+ */
private final Holder>> cachedClasses = new Holder>>();
-
+ /**
+ * 拓展名与 @Activate 的映射
+ *
+ * 例如，AccessLogFilter。
+ *
+ * 用于 {@link #getActivateExtension(URL, String)}
+ */
private final Map cachedActivates = new ConcurrentHashMap();
+ /**
+ * 缓存的拓展对象集合
+ *
+ * key：拓展名
+ * value：拓展对象
+ *
+ * 例如，Protocol 拓展
+ * key：dubbo value：DubboProtocol
+ * key：injvm value：InjvmProtocol
+ *
+ * 通过 {@link #loadExtensionClasses} 加载
+ */
private final ConcurrentMap> cachedInstances = new ConcurrentHashMap>();
+ /**
+ * 缓存的自适应( Adaptive )拓展对象
+ */
private final Holder