[incubator-dubbo-website] 01/02: enhance doc to explain mock behavior futher

[il...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

iluo pushed a commit to branch asf-site
in repository https://gitbox.apache.org/repos/asf/incubator-dubbo-website.git

commit 5d305c1e21cb362761e382b02702e07d1e7adca0
Author: beiwei30 <ia...@gmail.com>
AuthorDate: Tue Nov 6 16:43:51 2018 +0800

    enhance doc to explain mock behavior futher
---
 docs/en-us/user/demos/local-mock.md | 53 +++++++++++++++++++++++++++++++++++++
 docs/zh-cn/user/demos/local-mock.md | 53 +++++++++++++++++++++++++++++++++++++
 2 files changed, 106 insertions(+)

diff --git a/docs/en-us/user/demos/local-mock.md b/docs/en-us/user/demos/local-mock.md
index 28ab66b..2a69417 100644
--- a/docs/en-us/user/demos/local-mock.md
+++ b/docs/en-us/user/demos/local-mock.md
@@ -43,5 +43,58 @@ Consider changing to Mock implementation and return null in Mock implementation.
 <dubbo:reference interface="com.foo.BarService" mock="return null" />
 ```
 
+## Advanced Usage
+
+### return
+
+`return` can be used to return an object's string representation as the mocked return value. The legal values incude:
+* *empty*: empty value, default value for primary type, and empty value for collections.
+* *null*: `null`
+* *true*: `true`
+* *false*: `false`
+* *JSON format*: a mocked return value in JSON format, will be deserialized at runtime 
+
+### throw
+
+`throw` can be used to throw an exception object as the mocked return value. 
+
+Throw a default RPCException when invocation gets wrong:
+
+```xml
+<dubbo:reference interface="com.foo.BarService" mock="throw" />
+```
+
+Throw a specified exception when invocation gets wrong:
+
+```xml
+<dubbo:reference interface="com.foo.BarService" mock="throw com.foo.MockException" />
+```
+
+### force & fail
+
+Since `2.6.6` and above, it is possible to use `fail:` and `force:` in Spring's XML configuration to define mock behavior. `force:` means the mocked value is forced to use no matter the invocation gets wrong or not, in fact, the remote invocation will not happen at all. `fail:` is consistent with the default behavior, that is, mock happens only when invocation gets wrong. Futhermore, both `force:` and `fail:` can be used together with `throw` or `return` to define the mock behavior further.
+
+Force to return the specified value:
+
+```xml
+<dubbo:reference interface="com.foo.BarService" mock="force:return fake" />
+```
+
+Force to throw the specified exception:
+
+```xml
+<dubbo:reference interface="com.foo.BarService" mock="force:throw com.foo.MockException" />
+```
+
+### Specify Mock For Particular Method Only
+
+Mock behavior can be specified on the method level. Assume there are a couple of methods on `com.foo.BarService`, we can specify the mock behavior for one particular method only, say `sayHello()`. In the example below, "fake" is forced to return everytime when `sayHello()` is called, but other methods will not be effected:
+
+```xml
+<dubbo:reference id="demoService" check="false" interface="com.foo.BarService">
+    <dubbo:parameter key="sayHello.mock" value="force:return fake"/>
+</dubbo:reference>
+```
+
 [^1]: Mock is a subset of the Stub. If you use Stub, you may need to rely on the RpcException class. If you use Mock, you do not need to rely on RpcException, when throwing RpcException, it will callback Mock implementation class.
 [^2]: BarServiceMock implements BarService and has a no-argument constructor.
diff --git a/docs/zh-cn/user/demos/local-mock.md b/docs/zh-cn/user/demos/local-mock.md
index 1518b7a..7b627d7 100644
--- a/docs/zh-cn/user/demos/local-mock.md
+++ b/docs/zh-cn/user/demos/local-mock.md
@@ -43,5 +43,58 @@ try {
 <dubbo:reference interface="com.foo.BarService" mock="return null" />
 ```
 
+## 进阶用法
+
+### return
+
+使用 `return` 来返回一个字符串表示的对象，作为 Mock 的返回值。合法的字符串可以是：
+* *empty*: 代表空，基本类型的默认值，或者集合类的空值
+* *null*: `null`
+* *true*: `true`
+* *false*: `false`
+* *JSON 格式*: 反序列化 JSON 所得到的对象
+
+### throw
+
+使用 `throw` 来返回一个 Exception 对象，作为 Mock 的返回值。
+
+当调用出错时，抛出一个默认的 RPCException:
+
+```xml
+<dubbo:reference interface="com.foo.BarService" mock="throw" />
+```
+
+当调用出错时，抛出指定的 Exception：
+
+```xml
+<dubbo:reference interface="com.foo.BarService" mock="throw com.foo.MockException" />
+```
+
+### force 和 fail
+
+在 `2.6.6` 以上的版本，可以开始在 Spring XML 配置文件中使用 `fail:` 和 `force:`。`force:` 代表强制使用 Mock 行为，在这种情况下不会走远程调用。`fail:` 与默认行为一致，只有当远程调用发生错误时才使用 Mock 行为。`force:` 和 `fail:` 都支持与 `throw` 或者 `return` 组合使用。
+
+强制返回指定值：
+
+```xml
+<dubbo:reference interface="com.foo.BarService" mock="force:return fake" />
+```
+
+强制抛出指定异常：
+
+```xml
+<dubbo:reference interface="com.foo.BarService" mock="force:throw com.foo.MockException" />
+```
+
+### 在方法级别配置 Mock
+
+Mock 可以在方法级别上指定，假定 `com.foo.BarService` 上有好几个方法，我们可以单独为 `sayHello()` 方法指定 Mock 行为。具体配置如下所示，在本例中，只要 `sayHello()` 被调用到时，强制返回 "fake":
+
+```xml
+<dubbo:reference id="demoService" check="false" interface="com.foo.BarService">
+    <dubbo:parameter key="sayHello.mock" value="force:return fake"/>
+</dubbo:reference>
+```
+
 [^1]: Mock 是 Stub 的一个子集，便于服务提供方在客户端执行容错逻辑，因经常需要在出现 RpcException (比如网络失败，超时等)时进行容错，而在出现业务异常(比如登录用户名密码错误)时不需要容错，如果用 Stub，可能就需要捕获并依赖 RpcException 类，而用 Mock 就可以不依赖 RpcException，因为它的约定就是只有出现 RpcException 时才执行。
 [^2]: 在 interface 旁放一个 Mock 实现，它实现 BarService 接口，并有一个无参构造函数