dubbo 配置的中文注释

YunaiV · Feb 26, 2018 · 9d38b6f · 9d38b6f
1 parent bbdeff8
commit 9d38b6f
Show file tree

Hide file tree

Showing 17 changed files with 427 additions and 55 deletions.
diff --git a/dubbo-common/src/main/java/com/alibaba/dubbo/common/URL.java b/dubbo-common/src/main/java/com/alibaba/dubbo/common/URL.java
@@ -65,27 +65,47 @@
  * for this case, url protocol = null, url host = home, url path = user1/router.js
  * </ul>
  *
+ * 格式：protocol://username:password@host:port/path?key=value&key=value
+ * 所有配置最终都将转换为 URL 表示，并由服务提供方生成，经注册中心传递给消费方，各属性对应 URL 的参数，参见配置项一览表中的 "对应URL参数" 列。
+ * 来自 <a href="https://dubbo.gitbooks.io/dubbo-user-book/references/xml/introduction.html">schema 配置参考手册</>
+ *
  * @see java.net.URL
  * @see java.net.URI
  */
 public final class URL implements Serializable {
 
     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<String, String> parameters;
 
     // ==== cache ====

diff --git a/dubbo-common/src/main/java/com/alibaba/dubbo/common/utils/StringUtils.java b/dubbo-common/src/main/java/com/alibaba/dubbo/common/utils/StringUtils.java
@@ -349,13 +349,25 @@ public static Map<String, String> parseQueryString(String qs) {
         return parseKeyValuePair(qs, "\\&");
     }
 
+    /**
+     * 获得服务键
+     *
+     * 格式为 ${group}/${interface}:${version}
+     * 例如，com.alibaba.dubbo.demo.DemoService
+     *
+     * @param ps 参数集合 {@link com.alibaba.dubbo.common.URL#parameter}
+     * @return 服务键
+     */
     public static String getServiceKey(Map<String, String> ps) {
         StringBuilder buf = new StringBuilder();
+        // group
         String group = ps.get(Constants.GROUP_KEY);
         if (group != null && group.length() > 0) {
             buf.append(group).append("/");
         }
+        // interface
         buf.append(ps.get(Constants.INTERFACE_KEY));
+        // version
         String version = ps.get(Constants.VERSION_KEY);
         if (version != null && version.length() > 0) {
             buf.append(":").append(version);

diff --git a/dubbo-config/dubbo-config-api/src/main/java/com/alibaba/dubbo/config/AbstractConfig.java b/dubbo-config/dubbo-config-api/src/main/java/com/alibaba/dubbo/config/AbstractConfig.java
@@ -233,6 +233,13 @@ protected static void appendParameters(Map<String, String> parameters, Object co
         appendParameters(parameters, config, null);
     }
 
+    /**
+     * 将配置对象的属性，添加到参数集合
+     *
+     * @param parameters 参数集合
+     * @param config 配置对象
+     * @param prefix 属性前缀
+     */
     @SuppressWarnings("unchecked")
     protected static void appendParameters(Map<String, String> parameters, Object config, String prefix) {
         if (config == null) {
@@ -246,11 +253,12 @@ protected static void appendParameters(Map<String, String> parameters, Object co
                         && !"getClass".equals(name)
                         && Modifier.isPublic(method.getModifiers())
                         && method.getParameterTypes().length == 0
-                        && isPrimitive(method.getReturnType())) {
+                        && isPrimitive(method.getReturnType())) { // 方法为获取基本类型，public 的 getting 方法。
                     Parameter parameter = method.getAnnotation(Parameter.class);
                     if (method.getReturnType() == Object.class || parameter != null && parameter.excluded()) {
                         continue;
                     }
+                    // 获得属性名
                     int i = name.startsWith("get") ? 3 : 2;
                     String prop = StringUtils.camelToSplitName(name.substring(i, i + 1).toLowerCase() + name.substring(i + 1), ".");
                     String key;
@@ -259,18 +267,21 @@ && isPrimitive(method.getReturnType())) {
                     } else {
                         key = prop;
                     }
+                    // 获得属性值
                     Object value = method.invoke(config, new Object[0]);
                     String str = String.valueOf(value).trim();
                     if (value != null && str.length() > 0) {
+                        // 转义
                         if (parameter != null && parameter.escaped()) {
                             str = URL.encode(str);
                         }
+                        // 拼接，详细说明参见 `Parameter#append()` 方法的说明。
                         if (parameter != null && parameter.append()) {
-                            String pre = (String) parameters.get(Constants.DEFAULT_KEY + "." + key);
+                            String pre = parameters.get(Constants.DEFAULT_KEY + "." + key); // default. 里获取，适用于 ServiceConfig =》ProviderConfig 、ReferenceConfig =》ConsumerConfig 。
                             if (pre != null && pre.length() > 0) {
                                 str = pre + "," + str;
                             }
-                            pre = (String) parameters.get(key);
+                            pre = parameters.get(key); // 通过 `parameters` 属性配置，例如 `AbstractMethodConfig.parameters` 。
                             if (pre != null && pre.length() > 0) {
                                 str = pre + "," + str;
                             }
@@ -279,13 +290,14 @@ && isPrimitive(method.getReturnType())) {
                             key = prefix + "." + key;
                         }
                         parameters.put(key, str);
+//                        System.out.println("kv:" + key + "\t" + str);
                     } else if (parameter != null && parameter.required()) {
                         throw new IllegalStateException(config.getClass().getSimpleName() + "." + key + " == null");
                     }
                 } else if ("getParameters".equals(name)
                         && Modifier.isPublic(method.getModifiers())
                         && method.getParameterTypes().length == 0
-                        && method.getReturnType() == Map.class) {
+                        && method.getReturnType() == Map.class) { // `#getParameters()` 方法
                     Map<String, String> map = (Map<String, String>) method.invoke(config, new Object[0]);
                     if (map != null && map.size() > 0) {
                         String pre = (prefix != null && prefix.length() > 0 ? prefix + "." : "");
@@ -304,6 +316,13 @@ protected static void appendAttributes(Map<Object, Object> parameters, Object co
         appendAttributes(parameters, config, null);
     }
 
+    /**
+     * 将带有 @Parameter(attribute = true) 配置对象的属性，添加到参数集合
+     *
+     * @param parameters 参数集合
+     * @param config 配置对象
+     * @param prefix 前缀
+     */
     protected static void appendAttributes(Map<Object, Object> parameters, Object config, String prefix) {
         if (config == null) {
             return;
@@ -316,17 +335,19 @@ protected static void appendAttributes(Map<Object, Object> parameters, Object co
                         && !"getClass".equals(name)
                         && Modifier.isPublic(method.getModifiers())
                         && method.getParameterTypes().length == 0
-                        && isPrimitive(method.getReturnType())) {
+                        && isPrimitive(method.getReturnType())) { // 方法为获取基本类型，public 的 getting 方法。
                     Parameter parameter = method.getAnnotation(Parameter.class);
                     if (parameter == null || !parameter.attribute())
                         continue;
+                    // 获得属性名
                     String key;
                     if (parameter != null && parameter.key() != null && parameter.key().length() > 0) {
                         key = parameter.key();
                     } else {
                         int i = name.startsWith("get") ? 3 : 2;
                         key = name.substring(i, i + 1).toLowerCase() + name.substring(i + 1);
                     }
+                    // 获得属性值，存在则添加到 `parameters` 集合
                     Object value = method.invoke(config, new Object[0]);
                     if (value != null) {
                         if (prefix != null && prefix.length() > 0) {

diff --git a/...nfig/dubbo-config-api/src/main/java/com/alibaba/dubbo/config/AbstractInterfaceConfig.java b/...nfig/dubbo-config-api/src/main/java/com/alibaba/dubbo/config/AbstractInterfaceConfig.java
@@ -52,10 +52,25 @@ public abstract class AbstractInterfaceConfig extends AbstractMethodConfig {
 
     private static final long serialVersionUID = -1559314110797223229L;
 
-    // local impl class name for the service interface
+    /**
+     * local impl class name for the service interface
+     * 服务接口客户端本地代理类名，用于在客户端执行本地逻辑，如本地缓存等。
+     *
+     * 该本地代理类的构造函数必须允许传入远程代理对象，构造函数如：public XxxServiceLocal(XxxService xxxService)
+     *
+     * 设为 true，表示使用缺省代理类名，即：接口名 + Local 后缀
+     */
     protected String local; // TODO 芋艿
-
-    // local stub class name for the service interface
+    /**
+     * local stub class name for the service interface
+     * 服务接口客户端本地代理类名，用于在客户端执行本地逻辑，如本地缓存等。
+     *
+     * 该本地代理类的构造函数必须允许传入远程代理对象，构造函数如：public XxxServiceStub(XxxService xxxService)
+     *
+     * 设为 true，表示使用缺省代理类名，即：接口名 + Stub 后缀
+     *
+     * 参见文档 <a href="本地存根">http://dubbo.io/books/dubbo-user-book/demos/local-stub.html</>
+     */
     protected String stub; // TODO 芋艿
 
     // service monitor
@@ -104,8 +119,13 @@ public abstract class AbstractInterfaceConfig extends AbstractMethodConfig {
     // the scope for referring/exporting a service, if it's local, it means searching in current JVM only.
     private String scope;
 
+    /**
+     * 校验 RegistryConfig 配置数组。
+     * 实际上，该方法会初始化 RegistryConfig 的配置属性。
+     */
     protected void checkRegistry() {
-        // for backward compatibility
+        // 当 RegistryConfig 对象数组为空时，若有 `dubbo.registry.address` 配置，进行创建。
+        // for backward compatibility 向后兼容
         if (registries == null || registries.isEmpty()) {
             String address = ConfigUtils.getProperty("dubbo.registry.address");
             if (address != null && address.length() > 0) {
@@ -127,14 +147,20 @@ protected void checkRegistry() {
                     + Version.getVersion()
                     + ", Please add <dubbo:registry address=\"...\" /> to your spring config. If you want unregister, please set <dubbo:service registry=\"N/A\" />");
         }
+        // 读取环境变量和 properties 配置到 RegistryConfig 对象数组。
         for (RegistryConfig registryConfig : registries) {
             appendProperties(registryConfig);
         }
     }
 
+    /**
+     * 校验 ApplicationConfig 配置。
+     * 实际上，该方法会初始化 ApplicationConfig 的配置属性。
+     */
     @SuppressWarnings("deprecation")
     protected void checkApplication() {
-        // for backward compatibility
+        // 当 ApplicationConfig 对象为空时，若有 `dubbo.application.name` 配置，进行创建。
+        // for backward compatibility 向后兼容
         if (application == null) {
             String applicationName = ConfigUtils.getProperty("dubbo.application.name");
             if (applicationName != null && applicationName.length() > 0) {
@@ -145,8 +171,10 @@ protected void checkApplication() {
             throw new IllegalStateException(
                     "No such application config! Please add <dubbo:application name=\"...\" /> to your spring config.");
         }
+        // 读取环境变量和 properties 配置到 ApplicationConfig 对象。
         appendProperties(application);
 
+        // 初始化优雅停机的超时时长，参见 http://dubbo.io/books/dubbo-user-book/demos/graceful-shutdown.html 文档。
         String wait = ConfigUtils.getProperty(Constants.SHUTDOWN_WAIT_KEY);
         if (wait != null && wait.trim().length() > 0) {
             System.setProperty(Constants.SHUTDOWN_WAIT_KEY, wait.trim());
@@ -249,6 +277,14 @@ protected URL loadMonitor(URL registryURL) {
         return null;
     }
 
+    /**
+     * 校验接口和方法
+     *  1. 接口类非空，并是接口
+     *  2. 方法在接口中已定义
+     *
+     * @param interfaceClass 接口类
+     * @param methods 方法数组
+     */
     protected void checkInterfaceAndMethods(Class<?> interfaceClass, List<MethodConfig> methods) {
         // interface cannot be null
         if (interfaceClass == null) {
@@ -280,6 +316,12 @@ protected void checkInterfaceAndMethods(Class<?> interfaceClass, List<MethodConf
         }
     }
 
+    /**
+     * 校验 Stub 和 Mock 相关的配置
+     *
+     * TODO 芋艿，后续继续研究
+     * @param interfaceClass 接口类
+     */
     protected void checkStubAndMock(Class<?> interfaceClass) {
         if (ConfigUtils.isNotEmpty(local)) {
             Class<?> localClass = ConfigUtils.isDefault(local) ? ReflectUtils.forName(interfaceClass.getName() + "Local") : ReflectUtils.forName(local);

diff --git a/...-config/dubbo-config-api/src/main/java/com/alibaba/dubbo/config/AbstractMethodConfig.java b/...-config/dubbo-config-api/src/main/java/com/alibaba/dubbo/config/AbstractMethodConfig.java
@@ -53,8 +53,18 @@ public abstract class AbstractMethodConfig extends AbstractConfig {
     // whether to ack async-sent
     protected Boolean sent;
 
-    // the name of mock class which gets called when a service fails to execute
-    protected String mock;
+    /**
+     * the name of mock class which gets called when a service fails to execute
+     * 服务接口调用失败 Mock 实现类名。
+     *
+     * 该 Mock 类必须有一个无参构造函数。
+     * 与 Stub 的区别在于，Stub 总是被执行，而Mock只在出现非业务异常(比如超时，网络异常等)时执行，Stub 在远程调用之前执行，Mock 在远程调用后执行。
+     *
+     * 设为 true，表示使用缺省Mock类名，即：接口名 + Mock 后缀
+     *
+     * 参见文档 <a href="本地伪装">http://dubbo.io/books/dubbo-user-book/demos/local-mock.html</>
+     */
+    protected String mock; // TODO 芋艿
 
     // merger
     protected String merger;

diff --git a/dubbo-config/dubbo-config-api/src/main/java/com/alibaba/dubbo/config/ArgumentConfig.java b/dubbo-config/dubbo-config-api/src/main/java/com/alibaba/dubbo/config/ArgumentConfig.java
@@ -25,6 +25,7 @@
  *
  * 方法参数配置。
  * 属性参见：http://dubbo.io/books/dubbo-user-book/references/xml/dubbo-argument.html 。
+ * 用途参见：《参数回调》http://dubbo.io/books/dubbo-user-book/demos/callback-parameter.html
  *
  * @export
  */