wlliqipeng commented on a change in pull request #659: [RIP-9] The best
practice of rocketmq
URL: https://github.com/apache/rocketmq/pull/659#discussion_r250072133
##########
File path: docs/cn/best_practise.md
##########
@@ -0,0 +1,342 @@
+# 7 最佳实践(best practice)
+
+## 7.1 客户端
+
+ 相对于RocketMQ的Broker集群，生产者和消费者都是客户端。本小节主要描述生产者和消费者公共的行为配置。
+
+### 7.1.1 客户端寻址方式
+
+RocketMQ可以令客户端找到Name Server, 然后通过Name
Server再找到Broker，分别如下，如下所示有多种配置方式，优先级由高到低，高优先级会覆盖低优先级。
+
+1. 代码中指定Name Server地址
+ // 多个namesrv地址之间用分号分割
+
+```java
+producer.setNamesrvAddr("192.168.0.1:9876;192.168.0.2:9876");
+```
+或
+```java
+consumer.setNamesrvAddr("192.168.0.1:9876;192.168.0.2:9876");
+```
+2. Java启动参数中指定Name Server地址
+
+```text
+-Drocketmq.namesrv.addr=192.168.0.1:9876;192.168.0.2:9876
+```
+3. 环境变量指定Name Server地址
+
+```text
+export NAMESRV_ADDR=192.168.0.1:9876;192.168.0.2:9876
+```
+4. HTTP静态服务器寻址（默认）
+
+客户端启动后，会定时访问一个静态HTTP服务器，地址如下：<http://jmenv.tbsite.net:8080/rocketmq/nsaddr>，这个URL的返回内容如下：
+```text
+192.168.0.1:9876;192.168.0.2:9876
+```
+客户端默认每隔2分钟访问一次这个HTTP服务器，并更新本地的Name
Server地址。URL已经在代码中写死，可通过修改/etc/hosts文件来改变要访问的服务器，例如在/etc/hosts增加如下配置：
+```text
+10.232.22.67 jmenv.taobao.net
+```
+推荐使用HTTP静态服务器寻址方式，好处是客户端部署简单，且Name Server集群可以热升级。
+
+### 7.1.2 客户端配置
+
+DefaultMQProducer、TransactionMQProducer、DefaultMQPushConsumer、DefaultMQPullConsumer都继承于ClientConfig类，ClientConfig为客户端的公共配置类。客户端的配置都是get、set形式，每个参数都可以用spring来配置，也可以在代码中配置，例如namesrvAddr这个参数可以这样配置，其他参数同理。
+```java
+ producer.setNamesrvAddr("192.168.0.1:9876");
+```
+
+#### 1 客户端的公共配置
+
+| 参数名 | 默认值 | 说明
|
+| ----------------------------- | ------- |
------------------------------------------------------------ |
+| namesrvAddr | | Name
Server地址列表，多个NameServer地址用分号隔开 |
+| clientIP | 本机IP |
客户端本机IP地址，某些机器会发生无法识别客户端IP地址情况，需要应用在代码中强制指定 |
+| instanceName | DEFAULT |
客户端实例名称，客户端创建的多个Producer、Consumer实际是共用一个内部实例（这个实例包含网络连接、线程资源等） |
+| clientCallbackExecutorThreads | 4 | 通信层异步回调线程数
|
+| pollNameServerInteval | 30000 | 轮询Name Server间隔时间，单位毫秒
|
+| heartbeatBrokerInterval | 30000 | 向Broker发送心跳间隔时间，单位毫秒
|
+| persistConsumerOffsetInterval | 5000 | 持久化Consumer消费进度间隔时间，单位毫秒
|
+
+#### 2 Producer配置
+
+| 参数名 | 默认值 | 说明
|
+| -------------------------------- | ---------------- |
------------------------------------------------------------ |
+| producerGroup | DEFAULT_PRODUCER |
Producer组名，多个Producer如果属于一个应用，发送同样的消息，则应该将它们归为同一组 |
+| createTopicKey | TBW102 |
在发送消息时，自动创建服务器不存在的topic，需要指定Key，该Key可用于配置发送消息所在topic的默认路由。 |
+| defaultTopicQueueNums | 4 |
在发送消息，自动创建服务器不存在的topic时，默认创建的队列数 |
+| sendMsgTimeout | 10000 | 发送消息超时时间，单位毫秒
|
+| compressMsgBodyOverHowmuch | 4096 |
消息Body超过多大开始压缩（Consumer收到消息会自动解压缩），单位字节 |
+| retryAnotherBrokerWhenNotStoreOK | FALSE |
如果发送消息返回sendResult，但是sendStatus!=SEND_OK，是否重试发送 |
+| retryTimesWhenSendFailed | 2 |
如果消息发送失败，最大重试次数，该参数只对同步发送模式起作用 |
+| maxMessageSize | 4MB |
客户端限制的消息大小，超过报错，同时服务端也会限制，所以需要跟服务端配合使用。 |
+| transactionCheckListener | |
事务消息回查监听器，如果发送事务消息，必须设置 |
+| checkThreadPoolMinSize | 1 |
Broker回查Producer事务状态时，线程池大小 |
+| checkThreadPoolMaxSize | 1 |
Broker回查Producer事务状态时，线程池大小 |
+| checkRequestHoldMax | 2000 |
Broker回查Producer事务状态时，Producer本地缓冲请求队列大小 |
+| RPCHook | null |
该参数是在Producer创建时传入的，包含消息发送前的预处理和消息响应后的处理两个接口，用户可以在第一个接口中做一些安全控制或者其他操作。 |
+
+#### 3 PushConsumer配置
+
+| 参数名 | 默认值 | 说明
|
+| ---------------------------- | ----------------------------- |
------------------------------------------------------------ |
+| consumerGroup | DEFAULT_CONSUMER |
Consumer组名，多个Consumer如果属于一个应用，订阅同样的消息，且消费逻辑一致，则应该将它们归为同一组 |
+| messageModel | CLUSTERING | 消息模型，支持以下两种
1、集群消费 2、广播消费 |
Review comment:
“消费模型支持集群消费和广播消费两种”
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
[email protected]
With regards,
Apache Git Services
