This is an automated email from the ASF dual-hosted git repository.
albumenj pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/dubbo-website.git
The following commit(s) were added to refs/heads/master by this push:
new 15bc654566 Improve document for dubbo3 service downgrade (#1261)
15bc654566 is described below
commit 15bc654566fbec2ab01ea784c937bf1d6ef5d11f
Author: cdfive <[email protected]>
AuthorDate: Wed Jul 20 16:35:01 2022 +0800
Improve document for dubbo3 service downgrade (#1261)
* Improve documentation for service downgrade feature of Dubbo3
* Resume sentinel document in previous version and improve format of
document
---
.../service/service-downgrade.md | 80 +++++++++++++++++++---
1 file changed, 71 insertions(+), 9 deletions(-)
diff --git
a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/service/service-downgrade.md
b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/service/service-downgrade.md
index 4590415a7c..0ddb716b59 100644
---
a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/service/service-downgrade.md
+++
b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/service/service-downgrade.md
@@ -8,21 +8,83 @@ description: "降级 Dubbo 服务"
推荐使用相关限流降级组件（如
[Sentinel](https://sentinelguard.io/zh-cn/docs/open-source-framework-integrations.html)）以达到最佳体验。
+## 特性说明
+
+服务降级是指服务在非正常情况下进行降级应急处理。
+
## 使用场景
-可以通过服务降级功能临时屏蔽某个出错的非关键服务，并定义降级后的返回策略。
+* 某服务或接口负荷超出最大承载能力范围，需要进行降级应急处理，避免系统崩溃
+
+* 调用的某非关键服务或接口暂时不可用时，返回模拟数据或空，业务还能继续可用
+
+* 降级非核心业务的服务或接口，腾出系统资源，尽量保证核心业务的正常运行
+
+* 某上游基础服务超时或不可用时，执行能快速响应的降级预案，避免服务整体雪崩
## 使用方式
-向注册中心写入动态配置覆盖规则：
+以xml配置为例：（通过注解方式配置类似）
+
+1.配置`mock="true"`
+例：
+```xml
+<dubbo:reference id="demoService" interface="com.xxx.service.DemoService"
mock="true" />
+```
+这种方式需要在相同包下有类名 + `Mock`后缀的实现类，即`com.xxx.service`包下有`DemoServiceMock`类。
+
+2.配置`mock="com.xxx.service.DemoServiceMock"`
+例：
+```xml
+<dubbo:reference id="demoService" interface="com.xxx.service.DemoService"
mock="com.xxx.service.DemoServiceMock" />
+```
+这种方式指定Mock类的全路径。
+
+3.配置`mock="[fail|force]return|throw xxx"`
+
+* fail或force关键字可选，表示调用失败或不调用强制执行mock方法，如果不指定关键字默认为fail
+* return表示指定返回结果，throw表示抛出指定异常
+* xxx根据接口的返回类型解析，可以指定返回值或抛出自定义的异常
-```java
-RegistryFactory registryFactory =
ExtensionLoader.getExtensionLoader(RegistryFactory.class).getAdaptiveExtension();
-Registry registry =
registryFactory.getRegistry(URL.valueOf("zookeeper://10.20.153.10:2181"));
-registry.register(URL.valueOf("override://0.0.0.0/com.foo.BarService?category=configurators&dynamic=false&application=foo&mock=force:return+null"));
+例：
+```xml
+<dubbo:reference id="demoService" interface="com.xxx.service.DemoService"
mock="return" />
```
-其中：
+```xml
+<dubbo:reference id="demoService" interface="com.xxx.service.DemoService"
mock="return null" />
+```
+
+```xml
+<dubbo:reference id="demoService" interface="com.xxx.service.DemoService"
mock="fail:return aaa" />
+```
+
+```xml
+<dubbo:reference id="demoService" interface="com.xxx.service.DemoService"
mock="force:return true" />
+```
+
+```xml
+<dubbo:reference id="demoService" interface="com.xxx.service.DemoService"
mock="fail:throw" />
+```
+
+```xml
+<dubbo:reference id="demoService" interface="com.xxx.service.DemoService"
mock="force:throw java.lang.NullPointException" />
+```
+
+4.配合dubbo-admin使用
+
+* 应用消费端引入<a
href="https://github.com/apache/dubbo-spi-extensions/tree/master/dubbo-mock-extensions";
target="_blank">`dubbo-mock-admin`</a>依赖
+
+* 应用消费端启动时设置JVM参数，`-Denable.dubbo.admin.mock=true`
+
+* 启动dubbo-admin，在服务Mock->规则配置菜单下设置Mock规则
+
+以服务方法的维度设置规则，设置返回模拟数据，动态启用/禁用规则
+
+## 注意事项
+
+Dubbo启动时会检查配置，当mock属性值配置有误时会启动失败，可根据错误提示信息进行排查：
+
+* 配置格式错误，如`return+null`会报错，被当做mock类型处理，`return`后面可省略不写或者跟空格后再跟返回值
-* `mock=force:return+null` 表示消费方对该服务的方法调用都直接返回 null
值，不发起远程调用。用来屏蔽不重要服务不可用时对调用方的影响。
-* 还可以改为 `mock=fail:return+null` 表示消费方对该服务的方法调用在失败后，再返回 null
值，不抛异常。用来容忍不重要服务不稳定时对调用方的影响。
+* 类型找不到错误，如自定义mock类、throw自定义异常，请检查类型是否存在或是否有拼写错误
