add cluster guide

rpcman-core/src/main/java/cn/ipman/rpc/core/cluster/GrayRouter.java

@@ -10,30 +10,44 @@
 
 /**
  * 灰度发布路由类
+ * 用于在服务调用时，根据指定的灰度比例选择是路由到灰度实例还是正常实例。
  *
  * @Author IpMan
  * @Date 2024/3/31 21:49
  */
 @Slf4j
 public class GrayRouter implements Router<InstanceMeta> {
 
-    private final int grayRatio;
-    private final Random random = new Random();
+    private final int grayRatio; // 灰度比例
+    private final Random random = new Random();  // 用于随机选择
 
+    /**
+     * 灰度路由器构造函数
+     *
+     * @param grayRatio 灰度比例，表示灰度实例被选中的概率。
+     */
     public GrayRouter(int grayRatio) {
         this.grayRatio = grayRatio;
     }
 
+    /**
+     * 根据灰度比例从服务提供者列表中路由选择实例。
+     *
+     * @param providers 服务提供者列表。
+     * @return 路由选择后的实例列表。
+     */
     @Override
     public List<InstanceMeta> route(List<InstanceMeta> providers) {
+        // 如果列表为空或只有一个实例，直接返回
         if (providers == null || providers.size() <= 1) {
             return providers;
         }
-        // 正常的节点
+
+        // 分别初始化正常节点和灰度节点列表
         List<InstanceMeta> normalNodes = new ArrayList<>();
-        // 灰度的节点
         List<InstanceMeta> grayNodes = new ArrayList<>();
 
+        // 根据实例的灰度标志，将实例分到正常或灰度节点列表
         providers.forEach(p -> {
             if ("true".equals(p.getParameters().get("gray"))) {
                 grayNodes.add(p);
@@ -42,16 +56,15 @@ public List<InstanceMeta> route(List<InstanceMeta> providers) {
             }
         });
 
+        // 如果正常和灰度节点都为空，返回原列表
         if (normalNodes.isEmpty() || grayNodes.isEmpty()) return providers;
-        // 如果灰度比例是10
         if (grayRatio <= 0) {
-            return normalNodes;
+            return normalNodes; // 灰度比例为0或负数时，返回正常节点
         } else if (grayRatio >= 100) {
-            return grayNodes;
+            return grayNodes;   // 灰度比例为100或更大时，返回灰度节点
         }
 
-        // 再A的情况下, 返回 normal nodes, ==> 不管LB的算法情况下, 一定是normal
-        // B的情况下, 返回 gray nodes ==> 不管LB不管算法情况下, 一定是gray
+        // 随机决定返回灰度节点还是正常节点
         if (random.nextInt(100) < grayRatio) {
             log.debug(" grayRoute grayNodes ===> {}", grayRatio);
             return grayNodes;

rpcman-core/src/main/java/cn/ipman/rpc/core/cluster/RandomLoadBalancer.java

@@ -6,21 +6,29 @@
 import java.util.Random;
 
 /**
- * Description for this class
+ * 随机负载均衡器。从提供者列表中随机选择一个服务提供者。
  *
  * @Author IpMan
  * @Date 2024/3/16 19:53
  */
 @SuppressWarnings("unused")
 public class RandomLoadBalancer<T> implements LoadBalancer<T> {
 
-    Random random = new Random();
+    Random random = new Random(); // 使用随机数生成器
 
+    /**
+     * 从给定的服务提供者列表中随机选择一个服务提供者。
+     *
+     * @param providers 服务提供者列表。不可为null且至少应包含一个元素。
+     * @return 随机选择的服务提供者。如果列表为空或null，则返回null；如果列表只有一个元素，则返回该元素。
+     */
     @Override
     public T choose(List<T> providers) {
+        // 判断列表是否为空或null
         if (providers == null || providers.isEmpty()) return null;
+        // 如果只有一个元素，直接返回
         if (providers.size() == 1) return providers.get(0);
-        // 随机返回
+        // 随机选择一个服务提供者并返回
         return providers.get(random.nextInt(providers.size()));
     }
 }

rpcman-core/src/main/java/cn/ipman/rpc/core/cluster/RoundRibonLoadBalancer.java

@@ -6,20 +6,30 @@
 import java.util.concurrent.atomic.AtomicInteger;
 
 /**
- * Description for this class
+ * 圆环负载均衡器，实现负载均衡接口。
+ * 以循环的方式选择服务提供者，实现请求的均衡分发。
  *
  * @Author IpMan
  * @Date 2024/3/16 19:53
  */
 public class RoundRibonLoadBalancer<T> implements LoadBalancer<T> {
 
+    // 使用原子整型 AtomicInteger 来保证线程安全的索引操作
     AtomicInteger index = new AtomicInteger(0);
 
+    /**
+     * 从服务提供者列表中选择一个服务提供者。
+     *
+     * @param providers 服务提供者列表，类型为泛型 T 的 List。
+     * @return 返回选择的服务提供者，如果列表为空或只有一个提供者，则直接返回；否则按轮询方式选择并返回。
+     */
     @Override
     public T choose(List<T> providers) {
+        // 判断服务提供者列表是否为空或者为空列表
         if (providers == null || providers.isEmpty()) return null;
+        // 如果只有一个服务提供者，直接返回该提供者
         if (providers.size() == 1) return providers.get(0);
-        // 轮询返回, & 0x7ffffff 保证是个正数
+        // 轮询选择服务提供者，使用取模运算确保索引在列表大小范围内，& 0x7ffffff 保证结果为正数
         return providers.get((index.getAndIncrement() & 0x7ffffff) % providers.size());
     }
 }