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 473eec0300 Format advanced files (#1250)
473eec0300 is described below
commit 473eec03005b0c6696a1c6ff6777bb7abc0a8a9b
Author: Albumen Kevin <[email protected]>
AuthorDate: Mon Jul 18 16:13:52 2022 +0800
Format advanced files (#1250)
---
.../performance/simplify-registry-data.md | 43 ++++---
.../advanced-features-and-usage/rpc/async-call.md | 47 ++------
.../advanced-features-and-usage/rpc/attachment.md | 78 ++++++++++++-
.../rpc/callback-parameter.md | 6 +-
.../advanced-features-and-usage/rpc/context.md | 14 +--
.../rpc/echo-service.md | 8 ++
.../rpc/events-notify.md | 5 +-
.../rpc/generic-service.md | 124 ++++++++++++---------
.../rpc/group-merger.md | 5 +-
.../advanced-features-and-usage/rpc/local-mock.md | 2 -
.../rpc/parameter-validation.md | 5 +-
.../rpc/result-cache.md | 5 +-
.../advanced-features-and-usage/security/tls.md | 12 +-
.../security/token-authorization.md | 2 +
.../service/multi-versions.md | 10 +-
.../service/service-downgrade.md | 11 +-
.../service/service-group.md | 43 +++++--
static/imgs/v3/concepts/rpccontext.png | Bin 0 -> 222532 bytes
18 files changed, 260 insertions(+), 160 deletions(-)
diff --git
a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/performance/simplify-registry-data.md
b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/performance/simplify-registry-data.md
index 6704f7f595..99e5039520 100644
---
a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/performance/simplify-registry-data.md
+++
b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/performance/simplify-registry-data.md
@@ -7,7 +7,7 @@ weight: 3
description: "了解 dubbo3 减少注册中心上服务的注册数据"
---
-## 特性说明：
+## 特性说明
Dubbo provider 中的服务配置项有接近 [30 个配置项](/zh/docs/references/xml/dubbo-parameter)。
排除注册中心服务治理需要之外，很大一部分配置项是 provider 自己使用，不需要透传给消费者。这部分数据不需要进入注册中心，而只需要以 key-value
形式持久化存储。
@@ -25,27 +25,27 @@ Dubbo consumer 中的配置项也有 [20+个配置项](/zh/docs/references/xml/d
provider：
-| Constant Key | Key | remark |
-| ------ | ------ | ------ |
-| APPLICATION_KEY | application | |
-| CODEC_KEY | codec | |
-| EXCHANGER_KEY | exchanger | |
+| Constant Key | Key | remark |
+| ------ |---------------| ------ |
+| APPLICATION_KEY | application | |
+| CODEC_KEY | codec | |
+| EXCHANGER_KEY | exchanger | |
| SERIALIZATION_KEY | serialization | |
-| CLUSTER_KEY | cluster | |
-| CONNECTIONS_KEY | connections | |
-| DEPRECATED_KEY | deprecated | |
-| GROUP_KEY | group | |
-| LOADBALANCE_KEY | loadbalance | |
-| MOCK_KEY | mock | |
-| PATH_KEY | path | |
-| TIMEOUT_KEY | timeout | |
-| TOKEN_KEY | token | |
-| VERSION_KEY | version | |
-| WARMUP_KEY | warmup | |
-| WEIGHT_KEY | weight | |
-| TIMESTAMP_KEY | timestamp | |
-| DUBBO_VERSION_KEY | dubbo | |
-| SPECIFICATION_VERSION_KEY | **specVersion** | 新增，用于表述dubbo版本，如2.7.0 |
+| CLUSTER_KEY | cluster | |
+| CONNECTIONS_KEY | connections | |
+| DEPRECATED_KEY | deprecated | |
+| GROUP_KEY | group | |
+| LOADBALANCE_KEY | loadbalance | |
+| MOCK_KEY | mock | |
+| PATH_KEY | path | |
+| TIMEOUT_KEY | timeout | |
+| TOKEN_KEY | token | |
+| VERSION_KEY | version | |
+| WARMUP_KEY | warmup | |
+| WEIGHT_KEY | weight | |
+| DUBBO_VERSION_KEY | dubbo | |
+| RELEASE_KEY | release | |
+| SIDE_KEY | side | |
consumer：
@@ -56,7 +56,6 @@ consumer：
| VERSION_KEY | version | |
| GROUP_KEY | group | |
| DUBBO_VERSION_KEY | dubbo | |
-| SPECIFICATION_VERSION_KEY | **specVersion** | 新增，用于表述dubbo版本，如2.7.0 |
Constant Key 表示来自于类 org.apache.dubbo.common.Constants 的字段。
diff --git
a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/async-call.md
b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/async-call.md
index 7304ad3b15..7821d27b95 100644
---
a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/async-call.md
+++
b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/async-call.md
@@ -6,6 +6,7 @@ weight: 3
description: "在 Dubbo 中发起异步调用"
---
+## 背景
从 2.7.0 开始，Dubbo 的所有异步编程接口开始以
[CompletableFuture](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletableFuture.html)
为基础
@@ -13,7 +14,6 @@ description: "在 Dubbo 中发起异步调用"
-
## 使用 CompletableFuture 签名的接口
需要服务提供者事先定义 CompletableFuture 签名的服务，接口定义指南如下：
@@ -28,6 +28,9 @@ Provider 端异步执行和 Consumer 端异步调用是相互独立的，你可
- Consumer异步 - Provider异步
{{% /alert %}}
+## 参考用例
+
+[https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-async](https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-async)
## 定义 CompletableFuture 签名的接口
@@ -45,10 +48,8 @@ public interface AsyncService {
public class AsyncServiceImpl implements AsyncService {
@Override
public CompletableFuture<String> sayHello(String name) {
- RpcContext savedContext = RpcContext.getContext();
- // 建议为supplyAsync提供自定义线程池，避免使用JDK公用线程池
return CompletableFuture.supplyAsync(() -> {
- System.out.println(savedContext.getAttachment("consumer-key1"));
+ System.out.println(name);
try {
Thread.sleep(5000);
} catch (InterruptedException e) {
@@ -146,7 +147,7 @@ System.out.println("Executed before response return.");
// 此调用会立即返回null
asyncService.sayHello("world");
// 拿到调用的Future引用，当结果返回后，会被通知和设置到此Future
-CompletableFuture<String> helloFuture =
RpcContext.getContext().getCompletableFuture();
+CompletableFuture<String> helloFuture =
RpcContext.getServiceContext().getCompletableFuture();
// 为Future添加回调
helloFuture.whenComplete((retValue, exception) -> {
if (exception == null) {
@@ -160,7 +161,7 @@ helloFuture.whenComplete((retValue, exception) -> {
或者，你也可以这样做异步调用:
```java
-CompletableFuture<String> future = RpcContext.getContext().asyncCall(
+CompletableFuture<String> future = RpcContext.getServiceContext().asyncCall(
() -> {
asyncService.sayHello("oneway call request1");
}
@@ -170,40 +171,6 @@ future.get();
```
-
-## 重载服务接口
-
-如果你只有这样的同步服务定义，而又不喜欢 RpcContext 的异步使用方式。
-
-```java
-public interface GreetingsService {
- String sayHi(String name);
-}
-```
-
-那还有一种方式，就是利用 Java 8 提供的 default 接口实现，重载一个带有 CompletableFuture 签名的方法。
-
-> CompletableFuture 签名的方法目前只支持 Dubbo 协议，其他协议由于第三方实现问题，需要视具体情况而定。
-
-有两种方式来实现：
-
-1. 提供方或消费方自己修改接口签名
-
-```java
-public interface GreetingsService {
- String sayHi(String name);
-
- // AsyncSignal is totally optional, you can use any parameter type as long
as java allows your to do that.
- default CompletableFuture<String> sayHi(String name, AsyncSignal signal) {
- return CompletableFuture.completedFuture(sayHi(name));
- }
-}
-```
-
-1. Dubbo 官方提供 compiler
hacker，编译期自动重写同步方法，请[在此](https://github.com/dubbo/dubbo-async-processor#compiler-hacker-processer)讨论和跟进具体进展。
-
-
-
你也可以设置是否等待消息发出： [^1]
- `sent="true"` 等待消息发出，消息发送失败将抛出异常。
diff --git
a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/attachment.md
b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/attachment.md
index afb62a05b5..cd214607ae 100644
---
a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/attachment.md
+++
b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/attachment.md
@@ -5,11 +5,31 @@ linkTitle: "调用链路传递隐式参数"
weight: 5
description: "通过 Dubbo 中的 Attachment 在服务消费方和提供方之间隐式传递参数"
---
+
## 特性说明
-可以通过 `RpcContext` 上的 `setAttachment` 和 `getAttachment` 在服务消费方和提供方之间进行参数的隐式传递。
+可以通过 `RpcContext` 上的 `setAttachment` 和 `getAttachment` 在服务消费方和提供方之间进行参数的隐式传递。
+
+## 背景
+
+上下文信息是 RPC 框架很重要的一个功能，使用 RpcContext
可以为单次调用指定不同配置。如分布式链路追踪场景，其实现原理就是在全链路的上下文中维护一个 traceId，Consumer 和 Provider 通过传递
traceId 来连接一次RPC调用，分别上报日志后可以在追踪系统中串联并展示完整的调用流程。这样可以更方便地发现异常，定位问题。
+Dubbo 中的 RpcContext 是一个 ThreadLocal 的临时状态记录器，当接收到 RPC 请求，或发起 RPC
请求时，RpcContext 的状态都会变化。比如：A 调 B，B 再调 C，则 B 机器上，在 B 调 C 之前，RpcContext 记录的是 A 调 B
的信息，在 B 调 C 之后，RpcContext 记录的是 B 调 C 的信息。
+
+在 Dubbo 3 中，RpcContext
被拆分为四大模块（ServerContext、ClientAttachment、ServerAttachment 和 ServiceContext）。
+
+它们分别承担了不同的指责：
+- ServiceContext：在 Dubbo 内部使用，用于传递调用链路上的参数信息，如 invoker 对象等
+- ClientAttachment：在 Client 端使用，往 ClientAttachment 中写入的参数将被传递到 Server 端
+- ServerAttachment：在 Server 端使用，从 ServerAttachment 中读取的参数是从 Client 中传递过来的
+- ServerContext：在 Client 端和 Server 端使用，用于从 Server 端回传 Client 端使用，Server 端写入到
ServerContext 的参数在调用结束后可以在 Client 端的 ServerContext 获取到
+
+
+
+如上图所示，消费端发起调用的时候可以直接通过 Method Invoke 向远程的服务发起调用，同时消费端往 RpcClientAttachment
写入的数据会连同 Invoke 的参数信息写入到 Invocation 中。
+消费端的 Invocation 经过序列化后通过网络传输发送给服务端，服务端解析 Invocation 生成 Method Invoke 的参数和
RpcServerAttachment，然后发起真实调用。
+在服务端处理结束之后，Method Response 结果会连同 RpcServiceContext 一起生成 Result 对象。
+服务端的 Result 结果对象经过序列化后通过网络传输发送回消费端，消费端解析 Result 生成 Method Response 结果和
RpcServiceContext，返回真实调用结果和上下文给消费端。
-
#### 注意：
path, group, version, dubbo, token, timeout 几个 key 是保留字段，请使用其它值。
@@ -22,21 +42,69 @@ path, group, version, dubbo, token, timeout 几个 key 是保留字段，请使
内部系统通过 Dubbo 调用时, traceId 如何透传到服务提供方。
## 使用方式
+
#### 注意：
+
`setAttachment` 设置的 KV 对，在完成下面一次远程调用会被清空，即多次远程调用要多次设置。
+
#### 在服务消费方端设置隐式参数
-```xml
-RpcContext.getContext().setAttachment("index", "1"); //
隐式传参，后面的远程调用都会隐式将这些参数发送到服务器端，类似cookie，用于框架集成，不建议常规业务使用
+
+```java
+RpcContext.getClientAttachment().setAttachment("index", "1"); //
隐式传参，后面的远程调用都会隐式将这些参数发送到服务器端，类似cookie，用于框架集成，不建议常规业务使用
xxxService.xxx(); // 远程调用
// ...
```
+
#### 在服务提供方端获取隐式参数
+
```java
public class XxxServiceImpl implements XxxService {
public void xxx() {
// 获取客户端隐式传入的参数，用于框架集成，不建议常规业务使用
- String index = RpcContext.getContext().getAttachment("index");
+ String index = RpcContext.getServerAttachment().getAttachment("index");
}
}
```
+
+#### 在服务提供方写入回传参数
+
+```java
+public class XxxServiceImpl implements XxxService {
+
+ public void xxx() {
+ String index = xxx;
+ RpcContext.getServerContext().setAttachment("result", index);
+ }
+}
+```
+
+#### 在消费端获取回传参数
+
+```java
+xxxService.xxx(); // 远程调用
+String result = RpcContext.getServerContext().getAttachment("result");
+// ...
+```
+
+## 参数透传问题
+
+在 Dubbo 2.7 中，在 A 端设置的参数，调用 B 以后，如果 B 继续调用了 C，原来在 A 中设置的参数也会被带到 C
端过去，造成参数污染的问题。
+Dubbo 3 对 RpcContext 进行了重构，支持可选参数透传，默认开启参数透传。
+
+在 Dubbo 3 中提供了如下的 SPI，默认无实现，用户可以自行定义实现，`select` 的结果（可以从 RpcClientAttachment
获取当前所有参数）将作为需要透传的键值对传递到下一跳，如果返回 null 则表示不透传参数。
+
+```java
+@SPI
+public interface PenetrateAttachmentSelector {
+
+ /**
+ * Select some attachments to pass to next hop.
+ * These attachments can fetch from {@link
RpcContext#getServerAttachment()} or user defined.
+ *
+ * @return attachment pass to next hop
+ */
+ Map<String, Object> select();
+
+}
+```
\ No newline at end of file
diff --git
a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/callback-parameter.md
b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/callback-parameter.md
index 0dfc54703d..4d01bba427 100644
---
a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/callback-parameter.md
+++
b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/callback-parameter.md
@@ -123,8 +123,4 @@ callbackService.addListener("foo.bar", new
CallbackListener(){
System.out.println("callback1:" + msg);
}
});
-```
-
-#### 提示：
-`2.0.6` 及其以上版本支持
-
+```
\ No newline at end of file
diff --git
a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/context.md
b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/context.md
index ff4546dde1..ee7e6bcbbd 100644
---
a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/context.md
+++
b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/context.md
@@ -22,11 +22,11 @@ RpcContext 是一个 ThreadLocal 的临时状态记录器，当接收到 RPC 请
// 远程调用
xxxService.xxx();
// 本端是否为消费端，这里会返回true
-boolean isConsumerSide = RpcContext.getContext().isConsumerSide();
+boolean isConsumerSide = RpcContext.getServiceContext().isConsumerSide();
// 获取最后一次调用的提供方IP地址
-String serverIP = RpcContext.getContext().getRemoteHost();
+String serverIP = RpcContext.getServiceContext().getRemoteHost();
// 获取当前服务配置信息，所有配置信息都将转换为URL的参数
-String application =
RpcContext.getContext().getUrl().getParameter("application");
+String application =
RpcContext.getServiceContext().getUrl().getParameter("application");
// 注意：每发起RPC调用，上下文状态会变化
yyyService.yyy();
```
@@ -38,15 +38,15 @@ public class XxxServiceImpl implements XxxService {
public void xxx() {
// 本端是否为提供端，这里会返回true
- boolean isProviderSide = RpcContext.getContext().isProviderSide();
+ boolean isProviderSide =
RpcContext.getServiceContext().isProviderSide();
// 获取调用方IP地址
- String clientIP = RpcContext.getContext().getRemoteHost();
+ String clientIP = RpcContext.getServiceContext().getRemoteHost();
// 获取当前服务配置信息，所有配置信息都将转换为URL的参数
- String application =
RpcContext.getContext().getUrl().getParameter("application");
+ String application =
RpcContext.getServiceContext().getUrl().getParameter("application");
// 注意：每发起RPC调用，上下文状态会变化
yyyService.yyy();
// 此时本端变成消费端，这里会返回false
- boolean isProviderSide = RpcContext.getContext().isProviderSide();
+ boolean isProviderSide =
RpcContext.getServiceContext().isProviderSide();
}
}
```
diff --git
a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/echo-service.md
b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/echo-service.md
index f9fef53179..cf12052a18 100644
---
a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/echo-service.md
+++
b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/echo-service.md
@@ -6,8 +6,16 @@ weight: 12
description: "通过回声测试检测 Dubbo 服务是否可用"
---
+## 使用场景
+
回声测试用于检测服务是否可用，回声测试按照正常请求流程执行，能够测试整个调用是否通畅，可用于监控。
+## 参考用例
+
+[https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-echo](https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-echo)
+
+## 使用方式
+
所有服务自动实现 `EchoService` 接口，只需将任意服务引用强制转型为 `EchoService`，即可使用。
Spring 配置：
diff --git
a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/events-notify.md
b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/events-notify.md
index 5c9c3c6a0d..48b098fef8 100644
---
a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/events-notify.md
+++
b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/events-notify.md
@@ -8,8 +8,9 @@ description: "在调用前后出现异常时的事件通知"
## 特性说明
在调用之前、调用之后、出现异常时，会触发 `oninvoke`、`onreturn`、`onthrow`
三个事件，可以配置当事件发生时，通知哪个类的哪个方法。
-#### 提示：
-支持版本：`2.0.7` 之后
+## 参考用例
+
+[https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-notify](https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-notify)
## 使用场景
diff --git
a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/generic-service.md
b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/generic-service.md
index 311388d9ae..5ab3f8b061 100644
---
a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/generic-service.md
+++
b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/generic-service.md
@@ -9,19 +9,25 @@ description: "不需要服务端API的RPC调用"
## 特性说明
泛化调用是指在调用方没有服务方提供的API（SDK）的情况下，对服务方进行调用，并且可以正常拿到调用结果。
+
## 使用场景
+
泛化调用主要用于实现一个通用的远程服务 Mock 框架，可通过实现 GenericService 接口处理所有服务请求。比如如下场景：
-①网关服务：如果要搭建一个网关服务，那么服务网关要作为所有RPC服务的调用端。但是网关本身不应该依赖于服务提供方的接口API（这样会导致每有一个新的服务发布，就需要修改网关的代码以及重新部署），所以需要泛化调用的支持。
+1.
网关服务：如果要搭建一个网关服务，那么服务网关要作为所有RPC服务的调用端。但是网关本身不应该依赖于服务提供方的接口API（这样会导致每有一个新的服务发布，就需要修改网关的代码以及重新部署），所以需要泛化调用的支持。
-②测试平台：如果要搭建一个可以测试RPC调用的平台，用户输入分组名、接口、方法名等信息，就可以测试对应的RPC服务。那么由于同样的原因（即会导致每有一个新的服务发布，就需要修改网关的代码以及重新部署），所以平台本身不应该依赖于服务提供方的接口API。所以需要泛化调用的支持。
+2.
测试平台：如果要搭建一个可以测试RPC调用的平台，用户输入分组名、接口、方法名等信息，就可以测试对应的RPC服务。那么由于同样的原因（即会导致每有一个新的服务发布，就需要修改网关的代码以及重新部署），所以平台本身不应该依赖于服务提供方的接口API。所以需要泛化调用的支持。
## 使用方式
+
demo可见[dubbo
项目中的示例代码](https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-generic)
API部分以此demo为例讲解使用方式。
+
### 服务定义
+
#### 服务接口
+
``` java
public interface HelloService {
@@ -35,7 +41,9 @@ public interface HelloService {
}
```
+
#### 服务实现类
+
``` java
public class HelloServiceImpl implements HelloService {
@@ -94,14 +102,17 @@ public class HelloServiceImpl implements HelloService {
}
```
+
### 通过API使用泛化调用
+
#### 服务启动方
-①在设置ServiceConfig时，使用setGeneric("true")来开启泛化调用
-②在设置ServiceConfig时，使用setRef指定实现类时，要设置一个GenericService的对象。而不是真正的服务实现类对象
+1. 在设置 `ServiceConfig` 时，使用`setGeneric("true")`来开启泛化调用
+
+2. 在设置 `ServiceConfig` 时，使用setRef指定实现类时，要设置一个 `GenericService`
的对象。而不是真正的服务实现类对象
+3. 其他设置与正常Api服务启动一致即可
-③其他设置与正常Api服务启动一致即可
``` java
private static String zookeeperAddress = "zookeeper://" +
System.getProperty("zookeeper.address", "127.0.0.1") + ":2181";
@@ -136,17 +147,17 @@ private static String zookeeperAddress = "zookeeper://" +
System.getProperty("zo
}
}
```
+
#### 泛化调用方
步骤：
-①在设置ReferenceConfig时，使用setGeneric("true")来开启泛化调用
+1. 在设置 `ReferenceConfig` 时，使用 `setGeneric("true")` 来开启泛化调用
-②配置完ReferenceConfig后，使用referenceConfig.get()获取到GenericService类的实例
+2. 配置完 `ReferenceConfig` 后，使用 `referenceConfig.get()` 获取到 `GenericService` 类的实例
+3. 使用其 `$invoke` 方法获取结果
-③使用其$invoke方法获取结果
-
-④其他设置与正常Api服务启动一致即可
+4. 其他设置与正常 Api 服务启动一致即可
``` java
//定义泛化调用服务类
@@ -193,21 +204,24 @@ private static String zookeeperAddress = "zookeeper://" +
System.getProperty("zo
System.err.println("invokeSayHello(return): " + result);
latch.await();
}
-
```
+
### 通过Spring使用泛化调用
Spring中服务暴露与服务发现有多种使用方式，如xml，注解。这里以xml为例。
步骤：
-①生产者端无需改动
+1. 生产者端无需改动
+
+2. 消费者端原有的 `dubbo:reference` 标签加上 `generic=true` 的属性。
-②消费者端原有的reference标签加上generic=true的属性。
``` xml
<dubbo:reference id="helloService" generic = "true"
interface="org.apache.dubbo.samples.generic.call.api.HelloService"/>
```
-③获取到Bean容器，通过Bean容器拿到GenericService实例。
-④调用$invoke方法获取结果
+3. 获取到 Bean 容器，通过 Bean 容器拿到 `GenericService` 实例。
+
+4. 调用 `$invoke` 方法获取结果
+
``` java
private static GenericService genericService;
@@ -221,45 +235,11 @@ Spring中服务暴露与服务发现有多种使用方式，如xml，注解。
Object result = genericService.$invoke("sayHello", new
String[]{"java.lang.String"}, new Object[]{"world"});
}
```
-## 注意事项
-
-①如果参数为基本类型或者Date,List,Map等，则不需要转换，直接调用。
-②如果参数为其他POJO，则使用Map代替。
-如：
-``` java
-public class Student {
- String name;
- int age;
-
- public String getName() {
- return name;
- }
-
- public void setName(String name) {
- this.name = name;
- }
-
- public int getAge() {
- return age;
- }
-
- public void setAge(int age) {
- this.age = age;
- }
-}
-
-```
-在调用时应该转换为：
-``` java
-Map<String, Object> student = new HashMap<String, Object>();
-student.put("name", "xxx");
-student.put("age", "xxx");
-```
-③对于其他序列化格式，需要特殊配置
### Protobuf对象泛化调用
-一般泛化调用只能用于生成的服务参数为POJO的情况，而 GoogleProtobuf 的对象是基于 Builder 生成的非正常POJO，可以通过
protobuf-json 泛化调用。
+
+一般泛化调用只能用于生成的服务参数为POJO的情况，而 GoogleProtobuf 的对象是基于 Builder 生成的非正常POJO，可以通过
protobuf-json 泛化调用。
GoogleProtobuf 序列化相关的Demo可以参考
[protobuf-demo](https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-protobuf)
@@ -352,3 +332,45 @@ Google Protobuf 对象缺少标准的 JSON 格式，生成的服务元数据信
```
从服务元数据中也可以比较容易构建泛化调用对象。
+
+
+## 注意事项
+
+1. 如果参数为基本类型或者Date,List,Map等，则不需要转换，直接调用。
+
+2. 如果参数为其他POJO，则使用Map代替。
+
+如：
+``` java
+public class Student {
+ String name;
+ int age;
+
+ public String getName() {
+ return name;
+ }
+
+ public void setName(String name) {
+ this.name = name;
+ }
+
+ public int getAge() {
+ return age;
+ }
+
+ public void setAge(int age) {
+ this.age = age;
+ }
+}
+
+```
+
+在调用时应该转换为：
+
+``` java
+Map<String, Object> student = new HashMap<String, Object>();
+student.put("name", "xxx");
+student.put("age", "xxx");
+```
+
+3. 对于其他序列化格式，需要特殊配置
\ No newline at end of file
diff --git
a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/group-merger.md
b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/group-merger.md
index 9af8704700..9b57b0fe2d 100644
---
a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/group-merger.md
+++
b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/group-merger.md
@@ -64,7 +64,4 @@ description: "通过分组对结果进行聚合并返回聚合后的结果"
<dubbo:reference interface="com.xxx.MenuService" group="*">
<dubbo:method name="getMenuItems" merger=".addAll" />
</dubbo:reference>
-```
-
-#### 提示：
-从 `2.1.0` 版本开始支持
+```
\ No newline at end of file
diff --git
a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/local-mock.md
b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/local-mock.md
index 1bd90601cb..081b8421f3 100644
---
a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/local-mock.md
+++
b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/local-mock.md
@@ -97,8 +97,6 @@ public class DemoService {
### 使用 force 和 fail 关键字来配置 Mock 的行为
-在 `2.6.6` 以上的版本，可以开始在 Spring XML 配置文件中使用 `fail:` 和 `force:`。
-
`force:` 代表强制使用 Mock 行为，在这种情况下不会走远程调用。
`fail:` 与默认行为一致，只有当远程调用发生错误时才使用 Mock 行为。也就是说，配置的时候其实是可以不使用 `fail` 关键字的，直接使用
`throw` 或者 `return` 就可以了。
diff --git
a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/parameter-validation.md
b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/parameter-validation.md
index 24f708ab4e..ea65a9a911 100644
---
a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/parameter-validation.md
+++
b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/parameter-validation.md
@@ -33,6 +33,10 @@ description: "在 dubbo3 中进行参数校验"
服务端在向外提供接口服务时，解决各种接口参数校验问题。
+## 参考用例
+
+[https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-validation](https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-validation)
+
## 使用方式
#### 参数标注示例
@@ -201,7 +205,6 @@ public class ValidationConsumer {
```
#### 提示：
-自 `2.1.0` 版本开始支持, 如何使用 [dubbo
项目中的示例代码](https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-validation)
验证方式可扩展，扩展方式参见开发者手册中的
[验证扩展](../../../reference-manual/spi/description/validation)
diff --git
a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/result-cache.md
b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/result-cache.md
index 5f34f506ad..0fa91adac1 100644
---
a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/result-cache.md
+++
b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/result-cache.md
@@ -33,7 +33,4 @@ description: "通过缓存结果加速访问速度"
<dubbo:reference interface="com.foo.BarService">
<dubbo:method name="findBar" cache="lru" />
</dubbo:reference>
-```
-
-#### 提示：
-`2.1.0` 以上版本支持。
+```
\ No newline at end of file
diff --git
a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/security/tls.md
b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/security/tls.md
index c0118fd79b..d4a9e83515 100644
---
a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/security/tls.md
+++
b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/security/tls.md
@@ -6,7 +6,8 @@ weight: 1
description: " 了解在 dubbo3 的 TLS 保证传输安全"
---
## 特性说明
-2.7.5 版本在传输链路的安全性上做了很多工作，对于内置的 Dubbo Netty Server 和新引入的 gRPC 协议都提供了基于 TLS
的安全链路传输机制。
+
+内置的 Dubbo Netty Server 和新引入的 gRPC 协议都提供了基于 TLS 的安全链路传输机制。
TLS 的配置都有统一的入口。
#### 配置类型
@@ -14,6 +15,13 @@ TLS 的配置都有统一的入口。
- Consumer 端
## 使用场景
+
+对全链路有加密需求的用户可以使用 TLS。
+
+## 参考用例
+
+[https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-ssl](https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-ssl)
+
## 使用方式
##### Provider 端
@@ -44,7 +52,7 @@ if (!mutualTls) {}
}
```
-为尽可能保证应用启动的灵活性，TLS Cert 的指定还能通过 -D 参数或环境变量等方式来在启动阶段根据部署环境动态指定，参考 Dubbo
[配置读取规则](/zh/docs/advanced/config-rule)，TLS
[示例](https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-ssl)
+为尽可能保证应用启动的灵活性，TLS Cert 的指定还能通过 -D 参数或环境变量等方式来在启动阶段根据部署环境动态指定，参考 Dubbo
[配置读取规则](/zh/docs/advanced/config-rule)
#### 提示：
在服务调用的安全性上，Dubbo 在后续的版本中会持续投入，其中服务发现/调用的鉴权机制预计在接下来的版本中就会和大家见面。
diff --git
a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/security/token-authorization.md
b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/security/token-authorization.md
index 8dcfa99a82..b0d0b9d82a 100644
---
a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/security/token-authorization.md
+++
b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/security/token-authorization.md
@@ -5,12 +5,14 @@ linkTitle: "权限控制"
weight: 2
description: "了解 dubbo3 权限控制的配置和使用"
---
+
## 特性说明：
通过令牌验证在注册中心控制权限，以决定要不要下发令牌给消费者，
可以防止消费者绕过注册中心访问提供者，
另外通过注册中心可灵活改变授权方式，而不需修改或升级提供者。
+
#### 设置类型：
- 全局设置
- 服务级别设置
diff --git
a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/service/multi-versions.md
b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/service/multi-versions.md
index bd9f3a0d9c..32c864aa08 100644
---
a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/service/multi-versions.md
+++
b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/service/multi-versions.md
@@ -5,6 +5,7 @@ linkTitle: "服务分版本"
weight: 1
description: "在 Dubbo 中为同一个服务配置多个版本"
---
+
## 特性说明
按照以下的步骤进行版本迁移：
@@ -18,6 +19,11 @@ description: "在 Dubbo 中为同一个服务配置多个版本"
## 使用场景
当一个接口实现，出现不兼容升级时，可以用版本号过渡，版本号不同的服务相互间不引用。
+
+## 参考用例
+
+[https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-version](https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-version)
+
## 使用方式
- 服务提供者
老版本服务提供者配置：
@@ -43,6 +49,4 @@ description: "在 Dubbo 中为同一个服务配置多个版本"
如果不需要区分版本，可以按照以下的方式配置：
```xml
<dubbo:reference id="barService" interface="com.foo.BarService" version="*" />
-```
-#### 提示：
-`2.2.0` 以上版本支持
+```
\ No newline at end of file
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 07790c44c4..4590415a7c 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
@@ -6,8 +6,14 @@ weight: 3
description: "降级 Dubbo 服务"
---
+推荐使用相关限流降级组件（如
[Sentinel](https://sentinelguard.io/zh-cn/docs/open-source-framework-integrations.html)）以达到最佳体验。
+
+## 使用场景
+
可以通过服务降级功能临时屏蔽某个出错的非关键服务，并定义降级后的返回策略。
+## 使用方式
+
向注册中心写入动态配置覆盖规则：
```java
@@ -20,8 +26,3 @@
registry.register(URL.valueOf("override://0.0.0.0/com.foo.BarService?category=co
* `mock=force:return+null` 表示消费方对该服务的方法调用都直接返回 null
值，不发起远程调用。用来屏蔽不重要服务不可用时对调用方的影响。
* 还可以改为 `mock=fail:return+null` 表示消费方对该服务的方法调用在失败后，再返回 null
值，不抛异常。用来容忍不重要服务不稳定时对调用方的影响。
-
-{{% alert title="提示" color="primary" %}}
-`2.2.0` 以上版本支持
-{{% /alert %}}
-
diff --git
a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/service/service-group.md
b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/service/service-group.md
index 722f7efe8f..742a996bcc 100644
---
a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/service/service-group.md
+++
b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/service/service-group.md
@@ -5,8 +5,10 @@ linkTitle: "服务分组"
weight: 2
description: "使用服务分组区分服务接口的不同实现"
---
+
# 特性说明
同一个接口针对不同的业务场景、不同的使用需求或者不同的功能模块等场景，可使用服务分组来区分不同的实现方式。同时，这些不同实现所提供的服务是可并存的，也支持互相调用。
+
## 配置
- 服务提供端
- 服务消费端
@@ -14,12 +16,19 @@ description: "使用服务分组区分服务接口的不同实现"
# 使用场景
当一个接口有多种实现时，可以用 group 区分。
+# 参考用例
+
+[https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-group](https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-group)
+
# 使用方式
Dubbo服务分组可选择使用[注解配置](#properties1)、[xml配置](#properties2)或[API配置](#properties3)方式
-## <a id="properties1">注解配置</a>
+## 注解配置
+
### 服务提供端
+
使用@DubboService注解，添加group参数
+
```java
@DubboService(group = "demo")
public class DemoServiceImpl implements DemoService {
@@ -31,11 +40,15 @@ public class Demo2ServiceImpl implements DemoService {
...
}
```
+
启动Dubbo服务，可在注册中心看到相同服务名不同分组的服务，以Nacos作为注册中心为例，显示如下内容：
+
### 服务消费端
+
使用@DubboReference注解，添加group参数
+
```java
@DubboReference(group = "demo")
private DemoService demoService;
@@ -47,12 +60,16 @@ private DemoService demoService2;
@DubboReference(group = "*")
private DemoService demoService2;
```
+
同样启动Dubbo服务后，可在注册中心看到相同服务名不同分组的引用者，以Nacos作为注册中心为例，显示如下内容：
-## <a id="properties2">xml配置</a>
+## xml配置
+
### 服务提供端
+
使用<dubbo:service />标签，添加group参数
+
```xml
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans";
@@ -69,11 +86,15 @@ private DemoService demoService2;
...
</beans>
```
+
启动Dubbo服务，可在注册中心看到相同服务名不同分组的服务，以Nacos作为注册中心为例，显示如下内容：
+
### 服务消费端
+
使用<dubbo:reference/>注解，添加group参数
+
```xml
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans";
@@ -94,12 +115,17 @@ private DemoService demoService2;
...
</beans>
```
+
同样启动Dubbo服务后，可在注册中心看到相同服务名不同分组的引用者，以Nacos作为注册中心为例，显示如下内容：
+
-## <a id="properties3">API配置</a>
+## API配置
+
### 服务提供端
+
使用org.apache.dubbo.config.ServiceConfig类，添加group参数
+
```java
// ServiceConfig为重对象，内部封装了与注册中心的连接，以及开启服务端口
// 请自行缓存，否则可能造成内存和连接泄漏
@@ -112,13 +138,16 @@ ServiceConfig<DemoService> service2 = new
ServiceConfig<>();
service.setInterface(DemoService.class);
service.setGroup("demo2");
...
-
```
+
启动Dubbo服务，可在注册中心看到相同服务名不同分组的服务，以Nacos作为注册中心为例，显示如下内容：
+
### 服务消费端
+
使用org.apache.dubbo.config.ReferenceConfig，添加group参数
+
```java
// ReferenceConfig为重对象，内部封装了与注册中心的连接，以及开启服务端口
// 请自行缓存，否则可能造成内存和连接泄漏
@@ -141,6 +170,6 @@ reference3.setGroup("*");
同样启动Dubbo服务后，可在注册中心看到相同服务名不同分组的引用者，以Nacos作为注册中心为例，显示如下内容：
-{{% alert title="提示" color="primary" %}}
-`2.2.0` 以上版本支持，总是只调一个可用组的实现
-{{% /alert %}}
+### 提示
+
+总是**只调**一个可用组的实现
diff --git a/static/imgs/v3/concepts/rpccontext.png
b/static/imgs/v3/concepts/rpccontext.png
new file mode 100644
index 0000000000..eaaeb57a31
Binary files /dev/null and b/static/imgs/v3/concepts/rpccontext.png differ
