This is an automated email from the ASF dual-hosted git repository.
jerrick pushed a commit to branch asf-site
in repository https://gitbox.apache.org/repos/asf/incubator-dubbo-website.git
The following commit(s) were added to refs/heads/asf-site by this push:
new 3da2333 add titles to some docs (#154)
3da2333 is described below
commit 3da23334afb334b0ac5fd7d0ebed93cf5734f95b
Author: Song Kun <songkun...@gmail.com>
AuthorDate: Tue Sep 25 17:25:58 2018 +0800
add titles to some docs (#154)
---
docs/zh-cn/user/best-practice.md | 18 ++++++++-----
docs/zh-cn/user/capacity-plan.md | 18 ++++++++-----
docs/zh-cn/user/dependencies.md | 6 +++++
docs/zh-cn/user/maturity.md | 6 +++++
docs/zh-cn/user/perf-test.md | 14 +++++++---
docs/zh-cn/user/quick-start.md | 5 ++++
docs/zh-cn/user/recommend.md | 56 +++++++++++++++++++++-------------------
docs/zh-cn/user/rest.md | 8 +++++-
8 files changed, 88 insertions(+), 43 deletions(-)
diff --git a/docs/zh-cn/user/best-practice.md b/docs/zh-cn/user/best-practice.md
index 2d5d5e4..8586b30 100644
--- a/docs/zh-cn/user/best-practice.md
+++ b/docs/zh-cn/user/best-practice.md
@@ -1,10 +1,16 @@
+---
+title: 服务化最佳实践
+keywords: 分包, 粒度, 版本, 兼容性, 枚举, 序列化，异常
+description: Dubbo 最佳实践
+---
+
# 服务化最佳实践
## 分包
-建议将服务接口，服务模型，服务异常等均放在 API 包中，因为服务模型及异常也是 API
的一部分，同时，这样做也符合分包原则：重用发布等价原则(REP)，共同重用原则(CRP)。
+建议将服务接口、服务模型、服务异常等均放在 API 包中，因为服务模型和异常也是 API
的一部分，这样做也符合分包原则：重用发布等价原则(REP)，共同重用原则(CRP)。
-如果需要，也可以考虑在 API 包中放置一份 spring 的引用配置，这样使用方，只需在 spring
加载过程中引用此配置即可，配置建议放在模块的包目录下，以免冲突，如：`com/alibaba/china/xxx/dubbo-reference.xml`。
+如果需要，也可以考虑在 API 包中放置一份 Spring 的引用配置，这样使用方只需在 Spring
加载过程中引用此配置即可。配置建议放在模块的包目录下，以免冲突，如：`com/alibaba/china/xxx/dubbo-reference.xml`。
## 粒度
@@ -26,7 +32,7 @@
服务接口增加方法，或服务模型增加字段，可向后兼容，删除方法或删除字段，将不兼容，枚举类型新增字段也不兼容，需通过变更版本号升级。
-各协议的兼容性不同，参见： [服务协议](./references/protocol/introduction.md)
+各协议的兼容性不同，参见：[服务协议](./references/protocol/introduction.md)
## 枚举值
@@ -44,11 +50,11 @@
服务参数及返回值不建议使用接口，因为数据模型抽象的意义不大，并且序列化需要接口实现类的元信息，并不能起到隐藏实现的意图。
-服务参数及返回值都必需是 byValue 的，而不能是 byReference 的，消费方和提供方的参数或返回值引用并不是同一个，只是值相同，Dubbo
不支持引用远程对象。
+服务参数及返回值都必需是[传值调用](https://en.wikipedia.org/wiki/Evaluation_strategy#Call_by_value)，而不能是[传引用调用](https://en.wikipedia.org/wiki/Evaluation_strategy#Call_by_reference)，消费方和提供方的参数或返回值引用并不是同一个，只是值相同，Dubbo
不支持引用远程对象。
## 异常
-建议使用异常汇报错误，而不是返回错误码，异常信息能携带更多信息，以及语义更友好。
+建议使用异常汇报错误，而不是返回错误码，异常信息能携带更多信息，并且语义更友好。
如果担心性能问题，在必要时，可以通过 override 掉异常类的 `fillInStackTrace()` 方法为空方法，使其不拷贝栈信息。
@@ -60,4 +66,4 @@
不要只是因为是 Dubbo 调用，而把调用 `try...catch` 起来。`try...catch` 应该加上合适的回滚边界上。
-对于输入参数的校验逻辑在 Provider 端要有。如有性能上的考虑，服务实现者可以考虑在 API 包上加上服务 Stub 类来完成检验。
\ No newline at end of file
+Provider 端需要对输入参数进行校验。如有性能上的考虑，服务实现者可以考虑在 API 包上加上服务 Stub 类来完成检验。
\ No newline at end of file
diff --git a/docs/zh-cn/user/capacity-plan.md b/docs/zh-cn/user/capacity-plan.md
index 8dd47cc..6ea6bf3 100644
--- a/docs/zh-cn/user/capacity-plan.md
+++ b/docs/zh-cn/user/capacity-plan.md
@@ -1,3 +1,9 @@
+---
+title: 容量规划
+keywords: 容量规划
+description: Dubbo 应用容量规划参考
+---
+
# 容量规划
以下数据供参考：
@@ -5,13 +11,13 @@
## 使用 Dubbo 的会员服务项目
* 每天接收 4 亿次远程调用
-* 使用 12 台网站标配机器提供服务(8 核 CPU, 8G 内存)
-* 平均负载在 1 以下(对于 8 核 CPU 负载很低)
-* 平均响应时间 2.3 到 2.5 毫秒，网络开销约占 1.5 到 1.6 毫秒(和数据包大小有关)
+* 使用 12 台网站标配机器提供服务（8 核 CPU，8G 内存）
+* 平均负载在 1 以下（对于 8 核 CPU 负载很低）
+* 平均响应时间 2.3 到 2.5 毫秒，网络开销约占 1.5 到 1.6 毫秒（和数据包大小有关）
## 使用 Dubbo 的产品授权服务项目
* 每天接收 3 亿次远程调用
-* 使用 8 台网站标配机器提供服务(8 核CPU,8G 内存)
-* 平均负载在 1 以下(对于 8 核 CPU 负载很低)
-* 平均响应时间 1.4 到 2.8 毫秒，网络开销约占 1.0 到 1.1 毫秒(和数据包大小有关)
\ No newline at end of file
+* 使用 8 台网站标配机器提供服务（8 核CPU，8G 内存）
+* 平均负载在 1 以下（对于 8 核 CPU 负载很低）
+* 平均响应时间 1.4 到 2.8 毫秒，网络开销约占 1.0 到 1.1 毫秒（和数据包大小有关）
\ No newline at end of file
diff --git a/docs/zh-cn/user/dependencies.md b/docs/zh-cn/user/dependencies.md
index 684ae49..a579e6e 100644
--- a/docs/zh-cn/user/dependencies.md
+++ b/docs/zh-cn/user/dependencies.md
@@ -1,3 +1,9 @@
+---
+title: 依赖
+keywords: 必须依赖, 缺省依赖, 可选依赖
+description: Dubbo 依赖基本介绍
+---
+
# 依赖
## 必须依赖
diff --git a/docs/zh-cn/user/maturity.md b/docs/zh-cn/user/maturity.md
index 9d093dd..0e1c45a 100644
--- a/docs/zh-cn/user/maturity.md
+++ b/docs/zh-cn/user/maturity.md
@@ -1,3 +1,9 @@
+---
+title: 成熟度
+keywords: 功能成熟度, 策略成熟度
+description: 介绍 Dubbo 各个功能、策略的成熟度
+---
+
# 成熟度
## 功能成熟度
diff --git a/docs/zh-cn/user/perf-test.md b/docs/zh-cn/user/perf-test.md
index 3a50758..c9908de 100644
--- a/docs/zh-cn/user/perf-test.md
+++ b/docs/zh-cn/user/perf-test.md
@@ -1,11 +1,17 @@
+---
+title: 性能测试报告
+keywords: 性能测试
+description: Dubbo 2.0 性能测试报告
+---
+
# 性能测试报告
## 测试说明
-0. 本次性能测试，测试了 dubbo 2.0 所有支持的协议在不同大小和数据类型下的表现，并与 dubbo 1.0 进行了对比。
-1. 整体性能相比 1.0 有了提升，平均提升 10%，使用 dubbo 2.0 新增的 dubbo 序列化还能获得 10%~50%
的性能提升，详见下面的性能数据。
-2. 稳定性测试中由于将底层通信框架从 mina 换成 netty，old 区对象的增长大大减少，50 小时运行，增长不到 200m，无 fullgc。
-3. 存在的问题：在 50k 数据的时候 2.0 性能不如 1.0，怀疑可能是缓冲区设置的问题，下版本会进一步确认。
+1. 本次性能测试，测试了 dubbo 2.0 所有支持的协议在不同大小和数据类型下的表现，并与 dubbo 1.0 进行了对比。
+2. 整体性能相比 1.0 有了提升，平均提升 10%，使用 dubbo 2.0 新增的 dubbo 序列化还能获得 10%~50%
的性能提升，详见下面的性能数据。
+3. 稳定性测试中由于将底层通信框架从 mina 换成 netty，old 区对象的增长大大减少，50 小时运行，增长不到 200m，无 fullgc。
+4. 存在的问题：在 50k 数据的时候 2.0 性能不如 1.0，怀疑可能是缓冲区设置的问题，下版本会进一步确认。
## 测试环境
diff --git a/docs/zh-cn/user/quick-start.md b/docs/zh-cn/user/quick-start.md
index 03370e9..44f1ff1 100644
--- a/docs/zh-cn/user/quick-start.md
+++ b/docs/zh-cn/user/quick-start.md
@@ -1,3 +1,8 @@
+---
+title: 快速启动
+keywords: XML configuration, Consumer, Provider
+description: 使用 XML 配置方式快速上手 Dubbo
+---
# 快速启动
diff --git a/docs/zh-cn/user/recommend.md b/docs/zh-cn/user/recommend.md
index 902e244..3152922 100644
--- a/docs/zh-cn/user/recommend.md
+++ b/docs/zh-cn/user/recommend.md
@@ -1,20 +1,25 @@
+---
+title: 推荐用法
+keywords: Provider 配置, 管理信息, 缓存, 监控
+description: Dubbo 推荐用法举例
+---
+
# 推荐用法
## 在 Provider 上尽量多配置 Consumer 端属性
原因如下：
-* 作服务的提供者，比服务使用方更清楚服务性能参数，如调用的超时时间，合理的重试次数，等等
-* 在 Provider 配置后，Consumer 不配置则会使用 Provider 的配置值，即 Provider 配置可以作为 Consumer
的缺省值 [^1]。否则，Consumer 会使用 Consumer 端的全局设置，这对于 Provider 不可控的，并且往往是不合理的
+* 作服务的提供者，比服务使用方更清楚服务性能参数，如调用的超时时间、合理的重试次数等
+* 在 Provider 配置后，Consumer 不配置则会使用 Provider 的配置值，即 Provider 配置可以作为 Consumer
的缺省值 [^1]。否则，Consumer 会使用 Consumer 端的全局设置，这对于 Provider 是不可控的，并且往往是不合理的
-Provider 上尽量多配置 Consumer 端的属性，让 Provider 实现者一开始就思考 Provider 服务特点、服务质量的问题。
+Provider 上尽量多配置 Consumer 端的属性，让 Provider 实现者一开始就思考 Provider 服务特点、服务质量等问题。
示例：
```xml
<dubbo:service interface="com.alibaba.hello.api.HelloService" version="1.0.0"
ref="helloService"
- timeout="300" retry="2" loadbalance="random" actives="0"
-/>
+ timeout="300" retry="2" loadbalance="random" actives="0" />
<dubbo:service interface="com.alibaba.hello.api.WorldService" version="1.0.0"
ref="helloService"
timeout="300" retry="2" loadbalance="random" actives="0" >
@@ -24,11 +29,10 @@ Provider 上尽量多配置 Consumer 端的属性，让 Provider 实现者一开
在 Provider 上可以配置的 Consumer 端属性有：
-0. `timeout` 方法调用超时
-1. `retries` 失败重试次数，缺省是 2 [^2]
-2. `loadbalance` 负载均衡算法 [^3]，缺省是随机 `random`。还可以有轮询 `roundrobin`、最不活跃优先 [^4]
`leastactive`
-3. `actives` 消费者端，最大并发调用限制，即当 Consumer 对一个服务的并发调用到上限后，新调用会 Wait 直到超时
-在方法上配置 `dubbo:method` 则并发限制针对方法，在接口上配置 `dubbo:service`，则并发限制针对服务
+1. `timeout` 方法调用超时
+2. `retries` 失败重试次数，缺省是 2 [^2]
+3. `loadbalance` 负载均衡算法 [^3]，缺省是随机 `random`。还可以有轮询 `roundrobin`、最不活跃优先 [^4]
`leastactive` 等
+4. `actives` 消费者端，最大并发调用限制，即当 Consumer 对一个服务的并发调用到上限后，新调用会阻塞直到超时，在方法上配置
`dubbo:method` 则并发限制针对方法，在接口上配置 `dubbo:service`，则并发限制针对服务
详细配置说明参见：[Dubbo配置参考手册](./references/xml/introduction.md)
@@ -44,8 +48,8 @@ Provider 上尽量多配置 Consumer 端的属性，让 Provider 实现者一开
Provider 上可以配置的 Provider 端属性有：
-0. `threads` 服务线程池大小
-1. `executes` 一个服务提供者并行执行请求上限，即当 Provider 对一个服务的并发调用到上限后，新调用会 Wait，这个时候
Consumer可能会超时。在方法上配置 `dubbo:method` 则并发限制针对方法，在接口上配置 `dubbo:service`，则并发限制针对服务
+1. `threads` 服务线程池大小
+2. `executes` 一个服务提供者并行执行请求上限，即当 Provider 对一个服务的并发调用达到上限后，新调用会阻塞，此时 Consumer
可能会超时。在方法上配置 `dubbo:method` 则并发限制针对方法，在接口上配置 `dubbo:service`，则并发限制针对服务
## 配置管理信息
@@ -69,7 +73,7 @@ reference 配置负责人：
<dubbo:reference owner=”ding.lid,william.liangf” />
```
-`dubbo:service`、`dubbo:reference` 没有配置负责人，则使用 `dubbo:application` 设置的负责人。
+若没有配置 service 和 reference 的负责人，则默认使用 `dubbo:application` 设置的负责人。
## 配置 Dubbo 缓存文件
@@ -81,26 +85,26 @@ reference 配置负责人：
注意：
-0. 文件的路径，应用可以根据需要调整，保证这个文件不会在发布过程中被清除。
-1. 如果有多个应用进程注意不要使用同一个文件，避免内容被覆盖。
+1. 应用可以根据需要调整缓存文件的路径，保证这个文件不会在发布过程中被清除；
+2. 如果有多个应用进程，注意不要使用同一个文件，避免内容被覆盖；
-这个文件会缓存注册中心的列表和服务提供者列表。有了这项配置后，当应用重启过程中，Dubbo
注册中心不可用时则应用会从这个缓存文件读取服务提供者列表的信息，进一步保证应用可靠性。
+该文件会缓存注册中心列表和服务提供者列表。配置缓存文件后，应用重启过程中，若注册中心不可用，应用会从该缓存文件读取服务提供者列表，进一步保证应用可靠性。
## 监控配置
-0. 使用固定端口暴露服务，而不要使用随机端口
+1. 使用固定端口暴露服务，而不要使用随机端口
这样在注册中心推送有延迟的情况下，消费者通过缓存列表也能调用到原地址，保证调用成功。
-1. 使用 Dragoon 的 http 监控项监控注册中心上服务提供方
+2. 使用 Dubbo Ops 监控注册中心上的服务提供方
- Dragoon
监控服务在注册中心上的状态：http://dubbo-reg1.hst.xyi.cn.alidc.net:8080/status/com.alibaba.morgan.member.MemberService:1.0.5
确保注册中心上有该服务的存在。
+ 使用 [Dubbo Ops](https://github.com/apache/incubator-dubbo-ops)
监控服务在注册中心上的状态，确保注册中心上有该服务的存在。
-2. 服务提供方，使用 Dragoon 的 telnet 或 shell 监控项
+3. 服务提供方，使用 Dubbo Qos 的 telnet 或 shell 监控项
监控服务提供者端口状态：`echo status | nc -i 1 20880 | grep OK | wc -l`，其中的 20880 为服务端口
-3. 服务消费方，通过将服务强制转型为 EchoService，并调用 `$echo()` 测试该服务的提供者是可用
+4. 服务消费方，通过将服务强制转型为 EchoService，并调用 `$echo()` 测试该服务的提供者是可用
如 `assertEqauls(“OK”, ((EchoService)memberService).$echo(“OK”));`
@@ -112,21 +116,21 @@ Dubbo 中所有的配置项都可以配置在 Spring 配置文件中，并且可
### dubbo.properties 中属性名与 XML 的对应关系
-0. 应用名 `dubbo.application.name`
+1. 应用名 `dubbo.application.name`
```xml
<dubbo:application name="myalibaba" >
```
-1. 注册中心地址 `dubbo.registry.address`
+2. 注册中心地址 `dubbo.registry.address`
```xml
<dubbo:registry address="11.22.33.44:9090" >
```
-2. 调用超时 `dubbo.service.*.timeout`
+3. 调用超时 `dubbo.service.*.timeout`
- 可以在多个配置项设置超时
`timeout`，由上至下覆盖（即上面的优先）[^5]，其它的参数（`retries`、`loadbalance`、`actives`等）的覆盖策略也一样示例如下：
+ 可以在多个配置项设置超时
`timeout`，由上至下覆盖（即上面的优先）[^5]，其它的参数（`retries`、`loadbalance`、`actives`等）的覆盖策略与
`timeout` 相同。示例如下：
提供者端特定方法的配置
@@ -154,7 +158,7 @@ Dubbo 中所有的配置项都可以配置在 Spring 配置文件中，并且可
<dubbo:protocol threads="100" />
```
-6. 消费者启动时，没有提供者是否抛异常 Fast-Fail
`alibaba.intl.commons.dubbo.service.allow.no.provider`
+6. 消费者启动时，没有提供者是否抛异常 `alibaba.intl.commons.dubbo.service.allow.no.provider`
```xml
<dubbo:reference interface="com.alibaba.xxx.XxxService" check="false" />
diff --git a/docs/zh-cn/user/rest.md b/docs/zh-cn/user/rest.md
index b0bfc06..3c07479 100644
--- a/docs/zh-cn/user/rest.md
+++ b/docs/zh-cn/user/rest.md
@@ -1,4 +1,10 @@
-# 在Dubbo中开发REST风格的远程调用（RESTful Remoting）
+---
+title: 在 Dubbo 中开发 REST 风格的远程调用（RESTful Remoting）
+keywords: RESTful Remoting, REST
+description: 在 Dubbo 中开发 REST 风格的远程调用
+---
+
+# 在 Dubbo 中开发 REST 风格的远程调用（RESTful Remoting）
**作者：沈理**
