add config guide

rpcman-core/src/main/java/cn/ipman/rpc/core/config/ApolloChangedListener.java

@@ -10,8 +10,8 @@
 import org.springframework.context.ApplicationContextAware;
 
 /**
- * 更新对应的bean的属性值
- * 主要式存在@ConfigurationProperties注解的bean
+ * 用于监听Apollo配置变更事件，并更新对应Bean的属性值。
+ * 主要作用于使用了@ConfigurationProperties注解的Bean。
  *
  * @Author IpMan
  * @Date 2024/4/13 16:37
@@ -22,15 +22,23 @@ public class ApolloChangedListener implements ApplicationContextAware {
 
     ApplicationContext applicationContext;
 
+    /**
+     * 当Apollo配置发生变更时触发的处理方法。
+     * 会遍历所有变更的配置项，并记录日志。
+     * 然后发布一个环境变更事件，以触发属性值的更新。
+     *
+     * @param changeEvent 包含配置变更详细信息的事件对象。
+     */
     @ApolloConfigChangeListener({"rpcman-app"}) // listener to namespace
     @SuppressWarnings("unused")
     private void changeHandler(ConfigChangeEvent changeEvent) {
+        // 遍历所有变更的配置键
         for (String key : changeEvent.changedKeys()) {
             ConfigChange change = changeEvent.getChange(key);
             log.info("Found change - {}", change.toString());
         }
 
-        // 更新对应的bean的属性值,主要式存在@ConfigurationProperties注解的bean
+        // 发布环境变更事件，以触发使用@ConfigurationProperties注解的Bean的属性更新
         this.applicationContext.publishEvent(new EnvironmentChangeEvent(changeEvent.changedKeys()));
     }
 }

rpcman-core/src/main/java/cn/ipman/rpc/core/config/AppConfigProperties.java

@@ -5,7 +5,8 @@
 import org.springframework.context.annotation.Configuration;
 
 /**
- * config app properties.
+ * 配置应用程序属性。
+ * 该类用于定义RPC管理器应用的配置属性，包括应用实例ID、命名空间、环境、版本号及是否使用Netty等设置。
  *
  * @Author IpMan
  * @Date 2024/4/4 19:27
@@ -15,14 +16,18 @@
 @ConfigurationProperties(prefix = "rpcman.app")
 public class AppConfigProperties {
 
-    // for app instance
+    // 应用实例ID，默认为"app1"。
     private String id = "app1";
 
+    // 命名空间，默认为"public"。
     private String namespace = "public";
 
+    // 环境，默认为"dev"。
     private String env = "dev";
 
+    // 版本号，默认为"1.0"。
     private String version = "1.0";
 
+    // 是否使用Netty作为传输协议，默认为false
     private Boolean useNetty = false;
 }

rpcman-core/src/main/java/cn/ipman/rpc/core/config/ConsumerConfig.java

@@ -1,6 +1,5 @@
 package cn.ipman.rpc.core.config;
 
-import cn.ipman.rpc.core.api.*;
 import cn.ipman.rpc.core.api.*;
 import cn.ipman.rpc.core.cluster.GrayRouter;
 import cn.ipman.rpc.core.cluster.RoundRibonLoadBalancer;
@@ -24,8 +23,8 @@
 
 
 /**
- * Description for this class
- * RPC的Consumer端启动时,根据@RpcConsumer注解找到对应的依赖类,通过Java动态代理实现远程调用,并将代理后的Provider注入到容器种
+ * RPC消费者配置类。在RPC的Consumer端启动时，根据@RpcConsumer注解找到对应的依赖类，通过Java动态代理实现远程调用，
+ * 并将代理后的Provider注入到容器中。
  *
  * @Author IpMan
  * @Date 2024/3/10 19:49
@@ -36,26 +35,39 @@
 public class ConsumerConfig {
 
     @Value("${rpcman.providers:}")
-    String[] services;
+    String[] services;  // 从配置中获取的RPC服务提供者列表
 
     @Autowired
-    private AppConfigProperties appConfigProperties;
+    private AppConfigProperties appConfigProperties; // 应用配置属性
 
     @Autowired
-    private ConsumerConfigProperties consumerConfigProperties;
+    private ConsumerConfigProperties consumerConfigProperties; // 消费者配置属性
 
+    /**
+     * 创建Apollo配置变更监听器。
+     * @return ApolloChangedListener 实例
+     */
     @Bean
     @ConditionalOnMissingBean
     @ConditionalOnProperty(prefix = "apollo.bootstrap", value = "enabled")
     ApolloChangedListener consumer_apolloChangedListener() {
         return new ApolloChangedListener();
     }
 
+    /**
+     * 创建ConsumerBootstrap实例，用于Consumer的启动配置。
+     * @return ConsumerBootstrap 实例
+     */
     @Bean
     public ConsumerBootstrap createConsumerBootstrap() {
         return new ConsumerBootstrap();
     }
 
+    /**
+     * 创建ApplicationRunner，用于在Spring应用启动时执行Consumer的启动逻辑。
+     * @param consumerBootstrap ConsumerBootstrap实例
+     * @return ApplicationRunner 实例
+     */
     @Bean
     @Order(Integer.MIN_VALUE + 1) // 让ProviderBootstrap执行顺序提前,避免Consumer依赖时找不到Provider
     public ApplicationRunner consumerBootstrapRunner(@Autowired ConsumerBootstrap consumerBootstrap) {
@@ -66,42 +78,67 @@ public ApplicationRunner consumerBootstrapRunner(@Autowired ConsumerBootstrap co
         };
     }
 
+    /**
+     * 创建负载均衡器，默认为RoundRobinLoadBalancer。
+     * @return LoadBalancer<InstanceMeta> 负载均衡器实例
+     */
     @Bean
     public LoadBalancer<InstanceMeta> loadBalancer() {
         return new RoundRibonLoadBalancer<>();
     }
 
+    /**
+     * 创建路由选择器，默认为GrayRouter。
+     * @return Router<InstanceMeta> 路由选择器实例
+     */
     @Bean
     public Router<InstanceMeta> loadRouter() {
         return new GrayRouter(consumerConfigProperties.getGrayRatio());
     }
 
+    /**
+     * 创建注册中心实例，默认为ZkRegistryCenter。
+     * @return RegistryCenter 注册中心实例
+     */
     @Bean(initMethod = "start", destroyMethod = "stop")
     @ConditionalOnMissingBean
     public RegistryCenter consumerRc() {
         return new ZkRegistryCenter();
     }
 
+
+    /**
+     * 创建默认过滤器，用于Consumer的请求处理链。
+     * @return Filter 过滤器实例
+     */
     @Bean
     public Filter filterDefault() {
         return new ContextParameterFilter();
     }
 
+    /**
+     * 创建RPC上下文，配置路由、负载均衡、过滤器等核心组件。
+     * @param router 路由选择器
+     * @param loadBalancer 负载均衡器
+     * @param filters 过滤器列表
+     * @return RpcContext RPC上下文实例
+     */
     @Bean
-    @RefreshScope // context.refresh
+    @RefreshScope  // 支持配置动态刷新
     public RpcContext createContext(@Autowired Router<InstanceMeta> router,
                                     @Autowired LoadBalancer<InstanceMeta> loadBalancer,
                                     @Autowired List<Filter> filters) {
         RpcContext context = new RpcContext();
         context.setRouter(router);
         context.setLoadBalancer(loadBalancer);
         context.setFilters(filters);
+        // 设置应用相关参数
         context.getParameters().put("app.id", appConfigProperties.getId());
         context.getParameters().put("app.namespace", appConfigProperties.getNamespace());
         context.getParameters().put("app.env", appConfigProperties.getEnv());
         context.getParameters().put("app.version", appConfigProperties.getVersion());
         context.getParameters().put("app.useNetty", String.valueOf(appConfigProperties.getUseNetty()));
-        // 重试、超时等配置
+        // 配置Consumer相关属性
         context.setConsumerProperties(consumerConfigProperties);
         return context;
     }

rpcman-core/src/main/java/cn/ipman/rpc/core/config/ConsumerConfigProperties.java

@@ -5,7 +5,7 @@
 import org.springframework.context.annotation.Configuration;
 
 /**
- * config consumer properties.
+ * 配置 RPC 消费者属性。
  *
  * @Author IpMan
  * @Date 2024/4/4 19:27
@@ -16,19 +16,25 @@
 @ConfigurationProperties(prefix = "rpcman.consumer")
 public class ConsumerConfigProperties {
 
-    // for ha and governance
+    // 用于高可用性和治理的重试次数。
     private int retries = 1;
 
+    // 调用超时时间（毫秒）。
     private int timeout = 1000;
 
+    // 故障阈值，超过该值则进入熔断状态。
     private int faultLimit = 10;
 
+    // 熔断恢复初始延迟时间（毫秒）。
     private int halfOpenInitialDelay = 10_000;
 
+    // 熔断恢复后的观察时间（毫秒）。
     private int halfOpenDelay = 60_000;
 
+    // 灰度发布的比例。
     private int grayRatio = 0;
 
+    // 是否使用 Netty 作为传输层，默认为 false
     private Boolean useNetty = false;
 
 }

rpcman-core/src/main/java/cn/ipman/rpc/core/config/ProviderConfig.java

@@ -19,13 +19,11 @@
 
 
 /**
- * Description for this class
- * 将Provider启动项,配置到Spring容器中
+ * 提供者配置类，负责配置并初始化RPC提供者相关组件，将其注册到Spring容器中。
  *
  * @Author IpMan
  * @Date 2024/3/9 20:07
  */
-
 @Slf4j
 @Configuration
 @Import({AppConfigProperties.class, ProviderConfigProperties.class, SpringBootTransport.class})
@@ -34,24 +32,48 @@ public class ProviderConfig {
     @Value("${server.port:8081}")
     private String port;
 
+    /**
+     * 创建Apollo配置变更监听器Bean，仅当配置开启时生效。
+     *
+     * @return ApolloChangedListener 配置变更监听器实例。
+     */
     @Bean
     @ConditionalOnMissingBean
     @ConditionalOnProperty(prefix = "apollo.bootstrap", value = "enabled")
     ApolloChangedListener provider_apolloChangedListener() {
         return new ApolloChangedListener();
     }
 
+    /**
+     * 创建Provider启动器Bean。
+     *
+     * @param appConfigProperties 应用配置属性。
+     * @param providerConfigProperties 提供者配置属性。
+     * @return ProviderBootstrap 提供者启动器实例。
+     */
     @Bean
     ProviderBootstrap providerBootstrap(@Autowired AppConfigProperties appConfigProperties,
                                         @Autowired ProviderConfigProperties providerConfigProperties) {
         return new ProviderBootstrap(port, appConfigProperties, providerConfigProperties);
     }
 
+    /**
+     * 创建Provider调用器Bean。
+     *
+     * @param providerBootstrap 提供者启动器实例。
+     * @return ProviderInvoker 提供者调用器实例。
+     */
     @Bean
     ProviderInvoker providerInvoker(@Autowired ProviderBootstrap providerBootstrap) {
         return new ProviderInvoker(providerBootstrap);
     }
 
+    /**
+     * 创建应用启动运行器Bean，用于在应用启动时运行提供者启动器。
+     *
+     * @param providerBootstrap 提供者启动器实例。
+     * @return ApplicationRunner 应用启动运行器实例。
+     */
     @Bean
     @Order(Integer.MIN_VALUE) // 让ProviderBootstrap执行顺序提前,避免Consumer依赖时找不到Provider
     public ApplicationRunner providerBootstrapRunner(@Autowired ProviderBootstrap providerBootstrap) {
@@ -62,12 +84,24 @@ public ApplicationRunner providerBootstrapRunner(@Autowired ProviderBootstrap pr
         };
     }
 
+    /**
+     * 创建注册中心Bean，如果容器中不存在则创建一个新的ZkRegistryCenter实例。
+     *
+     * @return RegistryCenter 注册中心实例。
+     */
     @Bean
     @ConditionalOnMissingBean
     public RegistryCenter consumer_rc() {
         return new ZkRegistryCenter();
     }
 
+    /**
+     * 创建Netty服务器Bean，用于提供HTTP服务。
+     *
+     * @param appConfigProperties 应用配置属性。
+     * @param providerInvoker 提供者调用器实例。
+     * @return NettyServer Netty服务器实例。
+     */
     @Bean(initMethod = "start")
     public NettyServer nettyServer(@Autowired AppConfigProperties appConfigProperties,
                                    @Autowired ProviderInvoker providerInvoker) {

rpcman-core/src/main/java/cn/ipman/rpc/core/config/ProviderConfigProperties.java

@@ -8,18 +8,17 @@
 import java.util.Map;
 
 /**
- * config provider properties.
+ * RPC提供者配置属性类。用于配置RPC服务提供者的相关属性。
  *
  * @Author IpMan
  * @Date 2024/4/4 19:27
  */
-
 @Data
-@Configuration
+@Configuration // 表示这是一个Spring配置类
 @ConfigurationProperties(prefix = "rpcman.provider")
 public class ProviderConfigProperties {
 
-    // for provider
+    // 用于存储RPC提供者的元数据信息，键值对形式。
     Map<String, String> metas = new HashMap<>();
 
 }