update consul naming service doc

docs/cn/client.md

@@ -98,11 +98,15 @@ BNS是百度内常用的名字服务，比如bns://rdev.matrix.all，其中"bns"
 
 ### consul://\<service-name\>
 
-通过consul获取服务名称为service-name的服务列表，默认只获取状态为passing的服务。
+通过consul获取服务名称为service-name的服务列表。consul的默认地址是localhost:8500，可通过gflags设置-consul\_agent\_addr来修改。consul的连接超时时间默认是200ms，可通过-consul\_connect\_timeout\_ms来修改。
 
-当brpc服务重启时如果consul不可访问，服务可自动降级到file naming service获取服务列表。服务列表文件可通过consul-template生成，里面会保存consul不可用之前最新的下游服务节点。当consul恢复时可自动恢复到consul naming service。
+默认在consul请求参数中添加[stale](https://www.consul.io/api/index.html#consistency-modes)和passing（仅返回状态为passing的服务列表），可通过gflags中-consul\_url\_parameter改变[consul请求参数](https://www.consul.io/api/health.html#parameters-2)。
 
-除了对consul的首次请求，后续对consul的请求都采用long polling的方式，即仅当服务列表更新或请求超时后consul才返回结果。
+除了对consul的首次请求，后续对consul的请求都采用[long polling](https://www.consul.io/api/index.html#blocking-queries)的方式，即仅当服务列表更新或请求超时后consul才返回结果，这里超时时间默认为60s，可通过-consul\_blocking\_query\_wait\_secs来设置。
+
+若consul返回的服务列表[响应格式](https://www.consul.io/api/health.html#sample-response-2)有错误，或者列表中所有服务都因为地址、端口等关键字段缺失或无法解析而被过滤，consul naming server会拒绝更新服务列表，并在一段时间后（默认500ms，可通过-consul\_retry\_interval\_ms设置）重新访问consul。
+
+如果consul不可访问，服务可自动降级到file naming service获取服务列表。此功能默认关闭，可通过设置-consul\_enable\_degrade\_to\_file\_naming\_service来打开。服务列表文件目录通过-consul \_file\_naming\_service\_dir来设置，使用service-name作为文件名。该文件可通过consul-template生成，里面会保存consul不可用之前最新的下游服务节点。当consul恢复时可自动恢复到consul naming service。
 
 ### 名字服务过滤器
 

docs/en/client.md

@@ -98,11 +98,21 @@ Connect all servers under the domain, for example: http://www.baidu.com:80. Note
 
 ### consul://\<service-name\>
 
-Get a list of services with the specified service name through consul. By default, only services with the status of passing are obtained. 
+Get a list of services with the specified service-name through consul. The default address for consul is localhost:8500, which can be modified by setting -consul\_agent\_addr in gflags. The connection timeout time of consul is 200ms by default, which can be modified by -consul\_connect\_timeout\_ms. 
 
-If consul is not accessible when the brpc service is restarted, the naming service can be automatically downgraded to the file naming service to obtain the service list. The service list file can be generated through the consul-template, which will save the latest downstream service node before the consul is unavailable. When consul recovers, naming service can automatically switch back to consul naming service.
+By default, [stale](https://www.consul.io/api/index.html#consistency-modes) and passing(only the service list with the return status of passing is returned) are added to the consul request parameter. The [consul request parameter]((https://www.consul.io/api/health.html#parameters-2)) can be modified by -consul\_url\_parameter in gflags.
+
+
+In addition to the first request to the consul, the follow-up requests to the consul using the [long polling](https://www.consul.io/api/index.html#blocking-queries) feature. That is, the consul returns the result only when the service list is updated or the request time out. The timeout threshold defaults to 60 seconds, which can be modified by -consul\_blocking\_query\_wait\_secs.
+
+
+If the service list returned by the consul has an incorrect [response format](https://www.consul.io/api/health.html#sample-response-2), or all services in the list are filtered because the key fields such as the address and port are missing or cannot be parsed, the consul naming server will refuse to update the service list and revisit the consul after a period of time（
+default 500ms, can be modified by -consul\_retry\_interval\_ms）.
+
+
+If consul is not accessible, the service can be automatically downgraded to the file naming service for getting service list. This feature is turned off by default and can be turned on by setting -consul\_enable\_degrade\_to\_file\_naming\_service.
+The service list file directory is set with -consul \_file\_naming\_service\_dir. Using service-name as the file name. This file can be generated by the consul-template, which holds the latest downstream service node before the consul is unavailable. The consul naming service is automatically restored when consul is restored.
 
-In addition to the first request to the consul, subsequent requests to the consul use long polling. Long polling means that consul returns results only when the service list updates or requests time out. 
 
 
 ### Naming Service Filter