docs: 完善通知器文档

notify-core/src/main/java/com/cicdi/notify/AbstractNotifier.java

@@ -6,10 +6,16 @@ import com.cicdi.notify.template.TemplateManager;
 import java.util.Map;
 
 /**
+ * 通知器抽象实现
+ * <p>实现了通用的发送方法，还需要具体服务商继承此类，实现全部的方法</p>
+ *
  * @author xueye
  */
 public abstract class AbstractNotifier<T extends Template> implements Notifier<T> {
 
+    /**
+     * 通知模板管理器，用于获取当前通知类型使用的通知模板
+     */
     private final TemplateManager templateManager;
 
     public AbstractNotifier(TemplateManager templateManager) {
@@ -20,8 +26,10 @@ public abstract class AbstractNotifier<T extends Template> implements Notifier<T
     public void send(String templateId, Map<String, Object> context) {
         Template template = templateManager.getTemplate(this.getType(), templateId);
         if (null == template) {
-            throw new UnsupportedOperationException("模版不存在:" + templateId);
+            throw new UnsupportedOperationException("指定的模版不存在:" + templateId);
         }
         this.send((T) template, context);
     }
+
+
 }

notify-core/src/main/java/com/cicdi/notify/AbstractNotifierManager.java

@@ -6,14 +6,18 @@ import java.util.Map;
 import java.util.concurrent.ConcurrentHashMap;
 
 /**
+ * 通知器管理器抽象实现
+ * <p>实现了全部的接口，抽象的目的是为了方便实现Spring的自动装配回接口，实现服务商的自动注册</p>
+ *
  * @author xueye
  */
 public abstract class AbstractNotifierManager implements NotifierManager {
+
     private final Map<String, Map<String, NotifierProvider>> providers = new ConcurrentHashMap<>();
 
-    private Map<String, Notifier> notifiers = new ConcurrentHashMap<>();
+    private final Map<String, Notifier> notifiers = new ConcurrentHashMap<>();
 
-    private NotifyConfigManager configManager;
+    private final NotifyConfigManager configManager;
 
 //    private EventBus eventBus;
 
@@ -22,10 +26,24 @@ public abstract class AbstractNotifierManager implements NotifierManager {
 //        this.eventBus = eventBus;
     }
 
-    protected NotifierProperties getProperties(NotifyType notifyType, String id) {
+    @Override
-        return configManager.getNotifyConfig(notifyType, id);
+    public <T extends Template> Notifier<T> getNotifier(NotifyType type, String id) {
+        Notifier notifier;
+        if (null == notifiers.get(id)) {
+            notifier = createNotifier(getProperties(type, id));
+        } else {
+            notifier = notifiers.get(id);
+        }
+        return notifier;
     }
 
+    @Override
+    public void register(NotifierProvider provider) {
+        providers.computeIfAbsent(provider.getType().getId(), ignore -> new ConcurrentHashMap<>())
+                .put(provider.getProvider().getId(), provider);
+    }
+
+    @Override
     public void reload(String id) {
         Notifier notifier = notifiers.remove(id);
         if (null != notifier) {
@@ -33,6 +51,23 @@ public abstract class AbstractNotifierManager implements NotifierManager {
         }
     }
 
+    /**
+     * 根据通知配置属性ID获取通知配置属性
+     *
+     * @param notifyType 通知类型
+     * @param id         通知配置属性ID
+     * @return 通知配置属性
+     */
+    protected NotifierProperties getProperties(NotifyType notifyType, String id) {
+        return configManager.getNotifyConfig(notifyType, id);
+    }
+
+    /**
+     * 根据配置创建通知器
+     *
+     * @param properties 通知器配置属性
+     * @return 通知器
+     */
     protected Notifier createNotifier(NotifierProperties properties) {
         Map<String, NotifierProvider> providerMap = providers.get(properties.getType());
         if (null == providerMap) {
@@ -42,7 +77,7 @@ public abstract class AbstractNotifierManager implements NotifierManager {
         if (null == provider) {
             throw new UnsupportedOperationException("不支持的服务商: " + properties.getProvider());
         }
-        Notifier<? extends Template> notifier1 = provider.createNotifier(properties);
+        Notifier notifier1 = provider.createNotifier(properties);
         Notifier notifier2 = notifiers.put(properties.getId(), notifier1);
         if (null != notifier2) {
             notifier2.close();
@@ -50,19 +85,4 @@ public abstract class AbstractNotifierManager implements NotifierManager {
         return notifier1;
     }
 
-    @Override
-    public Notifier getNotifier(NotifyType type, String id) {
-        Notifier notifier = notifiers.get(id);
-        if (null == notifier) {
-            notifier = createNotifier(getProperties(type, id));
-        }
-        return notifier;
-    }
-
-    @Override
-    public void registerProvider(NotifierProvider provider) {
-        providers.computeIfAbsent(provider.getType().getId(), ignore -> new ConcurrentHashMap<>())
-                .put(provider.getProvider().getId(), provider);
-    }
-
 }

notify-core/src/main/java/com/cicdi/notify/DefaultNotifyType.java

@@ -1,7 +1,7 @@
 package com.cicdi.notify;
 
 /**
- * 默认通知类型
+ * 默认支持的通知类型
  *
  * @author xueye
  */
@@ -12,6 +12,9 @@ public enum DefaultNotifyType implements NotifyType {
     wechat("微信"),
     dingTalk("钉钉");
 
+    /**
+     * 通知类型名称
+     */
     private final String name;
 
     DefaultNotifyType(String name) {

notify-core/src/main/java/com/cicdi/notify/Notifier.java

@@ -5,42 +5,49 @@ import com.cicdi.notify.template.Template;
 import java.util.Map;
 
 /**
- * 通知器
+ * 消息通知器
  *
- * @param <T> 通知模板
  * @author xueye
  */
 public interface Notifier<T extends Template> {
 
     /**
+     * 获取通知器唯一标识
+     *
      * @return 通知器唯一标识
      */
     String getNotifierId();
 
     /**
-     * @return 通知器类型
+     * 获取通知类型
+     *
+     * @return 通知类型
      * @see NotifyType
      */
     NotifyType getType();
 
     /**
-     * @return 通知提供商
+     * 获取服务商
+     *
+     * @return 通知服务商
      */
     Provider getProvider();
 
     /**
-     * 指定模板ID进行发送
+     * 指定通知模板ID进行发送
+     * <p>用于一些固定模板的消息发送，例如验证码、定时消息</p>
      *
-     * @param templateId 模板唯一标识
+     * @param templateId 通知模板ID
-     * @param context    上下文
+     * @param context    模板上下文参数
      */
     void send(String templateId, Map<String, Object> context);
 
     /**
-     * 指定模板进行发送
+     * 指定通知模板进行发送
+     * <p>提供一个通知模板进行消息发送，比较灵活，适用于一些一次性的消息推送<p/>
      *
      * @param template 通知模板
-     * @param context  上下文
+     * @param context  模板上下文参数
      */
     void send(T template, Map<String, Object> context);
 
@@ -49,7 +56,15 @@ public interface Notifier<T extends Template> {
      */
     void close();
 
+    /**
+     * 将此通知器转换成特定类型通知器
+     *
+     * @param type 目标类型类
+     * @param <R>  目标类型
+     * @return 目标类型通知器
+     */
     default <R extends Notifier<T>> R unwrap(Class<R> type) {
         return type.cast(this);
     }
+
 }

notify-core/src/main/java/com/cicdi/notify/NotifierManager.java

@@ -3,7 +3,7 @@ package com.cicdi.notify;
 import com.cicdi.notify.template.Template;
 
 /**
- * 通知器管理
+ * 通知器管理器，用于获取获取通知器
  *
  * @author xueye
  */
@@ -11,12 +11,22 @@ public interface NotifierManager {
 
     /**
      * @param type 通知类型 {@link NotifyType}
-     * @param id   唯一标识
+     * @param id   通知器唯一标识
-     * @param <T>  模板类型
+     * @param <T>  通知模板类型
      * @return 通知器
+     * @see NotifierProvider
      */
     <T extends Template> Notifier<T> getNotifier(NotifyType type, String id);
 
+    /**
+     * 注册通知服务商
+     * <p>服务商经过注册之后才可以使用, 如果通知模板配置的服务商不在已注册集合中, 将会抛出{@link UnsupportedOperationException}</p>
+     *
+     * @param provider 通知服务商
+     * @see UnsupportedOperationException
+     */
+    void register(NotifierProvider provider);
+
     /**
      * 重新加载通知管理器
      *
@@ -24,5 +34,4 @@ public interface NotifierManager {
      */
     void reload(String id);
 
-    void registerProvider(NotifierProvider provider);
 }

notify-core/src/main/java/com/cicdi/notify/NotifierProperties.java

@@ -1,51 +1,63 @@
 package com.cicdi.notify;
 
+import java.io.Serializable;
 import java.util.Map;
 import java.util.Optional;
 
 /**
- * 通知器属性
+ * 通知配置属性
  *
  * @author xueye
  */
-public class NotifierProperties {
+public class NotifierProperties implements Serializable {
 
     /**
-     * 唯一标识
+     * 通知配置属性唯一标识
      */
     private String id;
 
     /**
-     * 通知类型标识
+     * 通知类型
      *
      * @see NotifyType
      */
     private String type;
 
     /**
-     * 通知服务提供商标识,如: aliyun ...
+     * 通知服务商标识
      */
     private String provider;
 
     /**
-     * 配置名称
+     * 通知配置名称
      */
     private String name;
 
     /**
-     * 配置内容,不同的服务提供商,配置不同.
+     * 通知配置内容
      *
      * @see NotifierProvider
      */
     private Map<String, Object> configuration;
 
 
-
+    /**
+     * 获取通知配置值
+     *
+     * @param key 通知配置项
+     * @return 通知配置项值
+     */
     public Optional<Object> getConfig(String key) {
         return Optional.ofNullable(configuration)
                 .map(conf -> conf.get(key));
     }
 
+    /**
+     * 获取通知配置值
+     *
+     * @param key 通知配置项
+     * @return 通知配置项值
+     */
     public Object getConfigOrNull(String key) {
         return Optional.ofNullable(configuration)
                 .map(conf -> conf.get(key))
@@ -91,4 +103,5 @@ public class NotifierProperties {
     public void setConfiguration(Map<String, Object> configuration) {
         this.configuration = configuration;
     }
+
 }

notify-core/src/main/java/com/cicdi/notify/NotifierProvider.java

@@ -3,7 +3,7 @@ package com.cicdi.notify;
 import com.cicdi.notify.template.Template;
 
 /**
- * 通知器提供商
+ * 通知服务商
  *
  * @author xueye
  */
@@ -17,17 +17,19 @@ public interface NotifierProvider {
     NotifyType getType();
 
     /**
-     * @return 服务商
+     * 获取通知器服务商
+     *
+     * @return 服务商标识
      */
     Provider getProvider();
 
     /**
-     * 根据配置创建通知器
+     * 根据通知器配置属性创建通知器
      *
-     * @param properties 通知配置
+     * @param properties 通知配置属性
-     * @return 创建结果
+     * @return 通知器
      */
-     Notifier<? extends Template> createNotifier(NotifierProperties properties);
+    Notifier<? extends Template> createNotifier(NotifierProperties properties);
 
 //    /**
 //     * 获取通知配置元数据,通过元数据可以知道此通知所需要的配置信息

notify-core/src/main/java/com/cicdi/notify/NotifyConfigManager.java

@@ -1,18 +1,18 @@
 package com.cicdi.notify;
 
 /**
- * 通知器配置管理
+ * 通知配置属性管理器，用于统一管理通知配置属性
  *
  * @author xueye
  */
 public interface NotifyConfigManager {
 
     /**
-     * 根据类型和配置ID获取通知器配置
+     * 根据类型和配置ID获取通知器配置属性
      *
-     * @param notifyType 通知器类型 {@link NotifyType}
+     * @param notifyType 通知类型 {@link NotifyType}
-     * @param configId   通知器配置ID
+     * @param configId   通知配置ID
-     * @return 通知器配置
+     * @return 通知配置属性
      */
     NotifierProperties getNotifyConfig(NotifyType notifyType, String configId);
 

notify-core/src/main/java/com/cicdi/notify/NotifyType.java

@@ -1,19 +1,23 @@
 package com.cicdi.notify;
 
 /**
- * 通知器类型
+ * 通知类型，通常使用枚举实现，枚举支持的通知类型
  *
  * @author xueye
  */
 public interface NotifyType {
 
     /**
+     * 通知类型唯一标识
+     *
      * @return 唯一标识
      */
     String getId();
 
     /**
-     * @return 通知器名称
+     * 获取通知类型
+     *
+     * @return 通知类型名称
      */
     String getName();
 

notify-core/src/main/java/com/cicdi/notify/Provider.java

@@ -1,19 +1,24 @@
 package com.cicdi.notify;
 
 /**
- * 提供商标识
+ * 服务商标识，通常使用枚举实现，枚举支持的服务商
  *
  * @author xueye
  */
 public interface Provider {
 
+
     /**
+     * 获取服务商ID
+     *
      * @return 唯一标识
      */
     String getId();
 
     /**
-     * @return 提供商名称
+     * 获取服务商名称
+     *
+     * @return 服务商名称
      */
     String getName();
 

notify-dingtalk/src/test/java/com/cicdi/notify/dingtalk/DingTalkTest.java

@@ -58,7 +58,7 @@ public class DingTalkTest {
 
         // register
         DingTalkNotifierProvider provider = new DingTalkNotifierProvider(templateManager);
-        notifierManager.registerProvider(provider);
+        notifierManager.register(provider);
         templateManager.register(provider);
 
         Notifier<Template> notifier = notifierManager.getNotifier(DefaultNotifyType.dingTalk, "123");

notify-email/src/test/java/com/cicdi/notify/email/DefaultEmailTest.java

@@ -64,7 +64,7 @@ public class DefaultEmailTest {
         NotifierManager notifierManager = new AbstractNotifierManager(notifyConfigManager){};
         DefaultEmailNotifierProvider defaultEmailNotifierProvider = new DefaultEmailNotifierProvider(templateManager);
         // register
-        notifierManager.registerProvider(defaultEmailNotifierProvider);
+        notifierManager.register(defaultEmailNotifierProvider);
         templateManager.register(defaultEmailNotifierProvider);
 
         Notifier<Template> notifier = notifierManager.getNotifier(DefaultNotifyType.email, "123");

notify-sms/src/test/java/com/cicdi/notify/sms/AliyunSmsTest.java

@@ -55,7 +55,7 @@ public class AliyunSmsTest {
         NotifierManager notifierManager = new AbstractNotifierManager(notifyConfigManager){};
         AliyunSmsNotifierProvider aliyunSmsNotifierProvider = new AliyunSmsNotifierProvider(templateManager);
         // register
-        notifierManager.registerProvider(aliyunSmsNotifierProvider);
+        notifierManager.register(aliyunSmsNotifierProvider);
         templateManager.register(aliyunSmsNotifierProvider);
 
         Notifier<Template> notifier = notifierManager.getNotifier(DefaultNotifyType.sms, "123");

notify-sms/src/test/java/com/cicdi/notify/sms/TelecomSmsTest.java

@@ -58,8 +58,8 @@ public class TelecomSmsTest {
         AliyunSmsNotifierProvider aliyunSmsNotifierProvider = new AliyunSmsNotifierProvider(templateManager);
         TelecomSmsNotifierProvider telecomSmsNotifierProvider = new TelecomSmsNotifierProvider(templateManager);
 
-        notifierManager.registerProvider(aliyunSmsNotifierProvider);
+        notifierManager.register(aliyunSmsNotifierProvider);
-        notifierManager.registerProvider(telecomSmsNotifierProvider);
+        notifierManager.register(telecomSmsNotifierProvider);
 
         templateManager.register(aliyunSmsNotifierProvider);
         templateManager.register(telecomSmsNotifierProvider);

notify-wechat/src/test/java/com/cicdi/notify/wechat/WechatTest.java

@@ -58,7 +58,7 @@ public class WechatTest {
 
         // register
         WechatNotifierProvider provider = new WechatNotifierProvider(templateManager);
-        notifierManager.registerProvider(provider);
+        notifierManager.register(provider);
         templateManager.register(provider);
 
         Notifier<Template> notifier = notifierManager.getNotifier(DefaultNotifyType.wechat, "123");