add api guide

rpcman-core/src/main/java/cn/ipman/rpc/core/api/Filter.java

@@ -1,15 +1,30 @@
 package cn.ipman.rpc.core.api;
 
 /**
- * 过滤器
+ * 过滤器接口。用于在RPC调用前后执行额外的逻辑。
  */
 public interface Filter {
 
+    /**
+     * 请求前置过滤器。在RPC请求发送前调用。
+     *
+     * @param request RPC请求对象。
+     * @return 返回可能修改后的请求或特定的业务对象。
+     */
     Object preFilter(RpcRequest request);
 
+    /**
+     * 请求后置过滤器。在RPC响应接收后调用。
+     *
+     * @param request  RPC请求对象。
+     * @param response RPC响应对象。
+     * @param result   RPC调用结果。
+     * @return 返回可能修改后的结果或特定的业务对象。
+     */
     Object postFilter(RpcRequest request, RpcResponse<?> response, Object result);
 
 
+    // 提供一个默认的过滤器实现，不做任何操作。
     @SuppressWarnings("unused")
     Filter Default = new Filter() {
         @Override

rpcman-core/src/main/java/cn/ipman/rpc/core/api/LoadBalancer.java

@@ -3,25 +3,30 @@
 import java.util.List;
 
 /**
- * 负载均衡, weightedRR, autoRR-自适应
- * 8081, w= 100, 25次
- * 8082, w= 300, 75次
+ * 负载均衡器接口，支持加权轮询（weightedRR）和自适应轮询（autoRR）算法。
+ * 例如，假设有两个服务提供者：
+ * - 8081 端口，权重为 100，在一轮中应该被选择 25 次；
+ * - 8082 端口，权重为 300，在一轮中应该被选择 75 次。
  * <p>
- * 0-99, random, <25, -8081, else 8082
+ * 请求被分配到服务提供者的策略为：
+ * - 随机选择一个数字 0-99；
+ * - 如果数字小于 25，则选择 8081 端口，否则选择 8082 端口。
  * <p>
- * UseService 10...
- * 8081, 10ms
- * 8082, 100ms
- * <p>
- * avg * 0.3  + last * 0.7 = w* ~
+ * 在使用服务时，考虑响应时间进行动态权重调整的示例：
+ * - 第一次请求，8081 端口用时 10ms，8082 端口用时 100ms。
+ * - 下一次选择时，根据平均响应时间（avg）的 30% 和上一次响应时间（last）的 70% 来动态计算权重。
  */
 public interface LoadBalancer<T> {
 
     /**
-     * 选择provider
+     * 从服务提供者列表中选择一个服务提供者。
+     *
+     * @param providers 服务提供者列表。
+     * @return 返回选择的服务提供者，如果没有可用的服务提供者，则返回 null。
      */
     T choose(List<T> providers);
 
+    // 默认负载均衡策略，选择列表中的第一个服务提供者
     @SuppressWarnings("unused")
     LoadBalancer<?> Default = p -> (p == null || p.isEmpty()) ? null : p.get(0);
 

rpcman-core/src/main/java/cn/ipman/rpc/core/api/RegistryCenter.java

@@ -3,41 +3,79 @@
 import cn.ipman.rpc.core.meta.InstanceMeta;
 import cn.ipman.rpc.core.meta.ServiceMeta;
 import cn.ipman.rpc.core.registry.ChangedListener;
+
 import java.util.List;
 
 /**
- * 注册中心
+ * 注册中心接口，提供服务注册与发现的功能。
  *
  * @Author IpMan
  * @Date 2024/3/16 20:39
  */
 public interface RegistryCenter {
 
+    /**
+     * 启动注册中心，初始化相关资源。
+     */
     void start(); // provider || consumer
 
+    /**
+     * 停止注册中心，释放相关资源。
+     */
     void stop(); // provider || consumer
 
-    // Provider侧
+    /**
+     * 服务提供者注册服务实例。
+     *
+     * @param service 服务元数据
+     * @param instance 服务实例元数据
+     */
     void register(ServiceMeta service, InstanceMeta instance); // provider
 
+    /**
+     * 服务提供者注销服务实例。
+     *
+     * @param service 服务元数据
+     * @param instance 服务实例元数据
+     */
     void unregister(ServiceMeta service, InstanceMeta instance); // provider
 
-    // Consumer侧
+    /**
+     * 服务消费者获取所有服务实例。
+     *
+     * @param service 服务元数据
+     * @return 返回该服务的所有实例元数据列表
+     */
     List<InstanceMeta> fetchAll(ServiceMeta service); // consumer
 
+    /**
+     * 服务消费者订阅服务变化。
+     *
+     * @param service 服务元数据
+     * @param listener 变化监听器
+     */
     void subscribe(ServiceMeta service, ChangedListener listener); // consumer
 
     // heartbeat()
+
+    /**
+     * 取消服务消费者的订阅。
+     */
     void unsubscribe();
 
     /**
-     * 静态的注册中心
+     * 静态注册中心类，用于简单场景或测试。
      */
     @SuppressWarnings("unused")
     class StaticRegistryCenter implements RegistryCenter {
 
         List<InstanceMeta> providers;
 
+        /**
+         * 构造函数。
+         *
+         * @param providers 提供者实例元数据列表
+         */
         public StaticRegistryCenter(List<InstanceMeta> providers) {
             this.providers = providers;
         }
@@ -54,22 +92,22 @@ public void stop() {
 
         @Override
         public void register(ServiceMeta service, InstanceMeta instance) {
-
+            // 在静态注册中心中不进行实际操作
         }
 
         @Override
         public void subscribe(ServiceMeta service, ChangedListener listener) {
-
+            // 在静态注册中心中不进行实际操作
         }
 
         @Override
         public void unsubscribe() {
-
+            // 在静态注册中心中不进行实际操作
         }
 
         @Override
         public void unregister(ServiceMeta ServiceMeta, InstanceMeta instance) {
-
+            // 在静态注册中心中不进行实际操作
         }
 
         @Override

rpcman-core/src/main/java/cn/ipman/rpc/core/api/Router.java

@@ -3,14 +3,23 @@
 import java.util.List;
 
 /**
- * 路由器
- * @param <T>
+ * 路由器接口。该接口用于定义路由逻辑，可以根据特定规则对服务提供者列表进行筛选或排序等操作。
+ * @param <T> 通用类型，代表需要进行路由处理的元素类型。
  */
 public interface Router<T> {
 
+    /**
+     * 执行路由操作的方法。该方法会接收一个服务提供者列表，并根据路由规则处理后返回一个新地列表。
+     * @param providers 待处理的服务提供者列表。
+     * @return 处理后的服务提供者列表。
+     */
     List<T> route(List<T> providers);
 
-    @SuppressWarnings("rawtypes")
+
+    /**
+     * 默认路由器。该静态内部类提供了一个默认的路由实现，即直接返回输入的服务提供者列表。
+     */
+    @SuppressWarnings({"rawtypes", "unused"})
     Router Default = p -> p;
 
 }

rpcman-core/src/main/java/cn/ipman/rpc/core/api/RpcContext.java

@@ -9,26 +9,38 @@
 import java.util.Map;
 
 /**
- * Description for this class
+ * RPC上下文环境，用于维护RPC调用过程中的上下文信息。
  *
  * @Author IpMan
  * @Date 2024/3/16 20:26
  */
 @Data
 public class RpcContext {
 
+    // 过滤器链
     List<Filter> filters;
 
+    // 路由器，用于选择合适的服务器实例
     Router<InstanceMeta> router;
 
+    // 负载均衡器，用于平衡请求到不同的服务器实例
     LoadBalancer<InstanceMeta> loadBalancer;
 
+    // 用户自定义参数
     private Map<String, String> parameters = new HashMap<>();
 
+    // 消费者配置属性
     private ConsumerConfigProperties consumerProperties;
 
+    // 线程本地存储，用于跨线程传递上下文参数，例如跟踪ID
     public static ThreadLocal<Map<String, String>> ContextParameters = ThreadLocal.withInitial(HashMap::new);
 
+    /**
+     * 获取上下文中的参数值。
+     *
+     * @param key 参数的键
+     * @return 参数的值，如果不存在则返回null
+     */
     public String param(String key) {
         return parameters.get(key);
     }
@@ -38,14 +50,31 @@ public String param(String key) {
     // gw -> service1 ->  service2(跨线程传递) ...
     // http headers
 
+    /**
+     * 设置上下文参数。
+     *
+     * @param key   参数的键
+     * @param value 参数的值
+     */
     public static void setContextParameter(String key, String value) {
         ContextParameters.get().put(key, value);
     }
 
+    /**
+     * 获取上下文参数。
+     *
+     * @param key 参数的键
+     * @return 参数的值，如果不存在则返回null
+     */
     public static String getContextParameter(String key) {
         return ContextParameters.get().get(key);
     }
 
+    /**
+     * 移除上下文参数。
+     *
+     * @param key 参数的键
+     */
     public static void removeContextParameter(String key) {
         ContextParameters.get().remove(key);
     }

rpcman-core/src/main/java/cn/ipman/rpc/core/api/RpcRequest.java

@@ -18,10 +18,8 @@
 @ToString
 public class RpcRequest {
 
-    private String service; // 接口, 如: cn.ipman.rpc.demo.api.UserService
-    private String methodSign; // 方法签名
-    private Object[] args; // 方法参数
-
-    // 跨调用方需要传递的参数
-    private Map<String, String> params = new HashMap<>();
+    private String service;         // 接口, 如: cn.ipman.rpc.demo.api.UserService
+    private String methodSign;      // 方法签名
+    private Object[] args;          // 方法参数
+    private Map<String, String> params = new HashMap<>(); // 额外传递的参数
 }

rpcman-core/src/main/java/cn/ipman/rpc/core/api/RpcResponse.java

@@ -7,7 +7,7 @@
 
 
 /**
- * RPC 响应体
+ * RPC响应结构体
  *
  * @Author IpMan
  * @Date 2024/3/9 20:07
@@ -18,8 +18,8 @@
 @AllArgsConstructor
 public class RpcResponse<T> {
 
-    boolean status; // 状态:true
-    T data; // new User
-    RpcException ex;
+    boolean status;     // 状态:true
+    T data;             // 如: new User
+    RpcException ex;    // RPC异常类
 
 }