Add migration doc (#2974)

apache · May 14, 2024 · 01df972 · 01df972
1 parent 99d1d01
commit 01df972
Show file tree

Hide file tree

Showing 40 changed files with 1,531 additions and 970 deletions.
diff --git a/content/zh-cn/blog/integration/how-to-proxy-dubbo-in-higress.md b/content/zh-cn/blog/integration/how-to-proxy-dubbo-in-higress.md
@@ -1,10 +1,10 @@
 ---
 aliases:
     - /zh/overview/what/ecosystem/gateway/higress/
-description: "使用 Higress 作为 Dubbo 网关"
+description: "使用 Higress 作为 Dubbo 网关，代理 dubbo 协议服务。"
 linkTitle: 如何通过 Higress 网关代理 Dubbo 服务
 title: 如何通过 Higress 网关代理 Dubbo 服务
-date: 2023-04-01
+date: 2024-04-01
 tags: ["网关", "生态"]
 ---
 {{% alert title="注意" color="warning" %}}
@@ -14,6 +14,8 @@ tags: ["网关", "生态"]
 
 Higress提供了从HTTP协议到Dubbo协议进行转换的功能，用户通过配置协议转换，可以将一个Dubbo服务以HTTP接口暴露出来，从而用HTTP请求实现对Dubbo接口的调用。本文将通过一个示例来介绍如何用Higress配置HTTP到Dubbo的协议转换。该示例会引导您轻松地部署一个Nacos server和一个Dubbo服务，然后通过Ingress将HTTP请求转发到注册在Nacos上的Dubbo服务，并通过Higress的协议转换能力完成对Dubbo服务的HTTP调用。
 
+<img style="max-width:800px;height:auto;" src="/imgs/v3/tasks/gateway/http-to-dubbo.png"/>
+
 以下是一个使用 `Higress + dubbo协议 + Nacos注册中心` 的完整示例：[dubbo-samples-gateway-higress-dubbo](https://github.com/apache/dubbo-samples/tree/master/2-advanced/dubbo-samples-gateway/dubbo-samples-gateway-higress/dubbo-samples-gateway-higress-dubbo)。
 
 ## 前提条件

diff --git a/...ades-and-compatibility/multi-protocols.md → ...nalysis/multiple-protocols-on-one-port.md b/...ades-and-compatibility/multi-protocols.md → ...nalysis/multiple-protocols-on-one-port.md
@@ -5,13 +5,14 @@ aliases:
 description: ""
 linkTitle: 单端口多协议
 title: 发布使用不同协议的多个服务，通过单端口监听
-type: docs
-weight: 5
+date: 2024-3-19
+author: 陈景明
+tags: ["源码解析", "协议"]
+description: >
+  Dubbo3 框架支持在单个端口发布多个不同的协议，比如可以同时发布 dubbo、triple 协议，本文介绍 Dubbo 是如何实现单端口多协议发布的。
 ---
 
 
-
-## 特性说明
 通过对protocol进行配置，dubbo3可以支持端口的协议复用。
 比如使用Triple协议启动端口复用后，可以在相同的端口上为服务增加
 Dubbo协议支持，以及Qos协议支持。这些协议的识别都是由一个统一的端口复用
@@ -132,45 +133,3 @@ reference.setProtocol(this.protocol);
 
 ![pu-server-imgs4](/imgs/blog/pu-server/reference-service.png)
 
-
-
-文档编写中...
-
-Dubbo3 HTTP 协议支持仍在建设中，目前最新的 3.3 开发分支已经有初版原型供体验。正式的生产可用版本预计会在 3.4/3.4 的某个正式版本发布。
-
-以下是 Dubbo3 HTTP 协议与编程模式计划支持的几种业务场景：
-* 调用 http 协议的微服务体系
-* 发布 http 协议的服务
-* 多协议发布，一个服务同时发布 http&dubbo 协议
-
-## 调用 http 协议的微服务体系
-一个典型的应用场景是 Dubbo 调用 Spring Cloud 开发的微服务体系。
-
-不同体系的互通，最关键的两点便是地址格式与编码协议的兼容，只要 Dubbo 能自动发现 SpringCloud 体系的地址并能基于 HTTP 协议进行通信即可。Dubbo3 可以做到：
-* 支持 SpringCloud 体系的服务发现地址格式
-* 支持 HTTP+JSON 的数据传输格式
-
-![img](/imgs/v3/tasks/protocol/http-usecase-1.png)
-
-基于以上分析，当我们需要调用 Spring Cloud 体系的服务时，只需要在 Dubbo 侧编写标准的 Dubbo Reference 服务引用就可以。同时，为了简化开发工作，**Dubbo 支持标准的 Spring Web 注解**，因此，如果你可以直接在 Dubbo 中复用 Spring Cloud 中的接口定义：
-
-Spring Cloud 侧的服务定义：
-```java
-interface SpringCloudRestService {
- //xxx
-}
-```
-
-在 Dubbo 侧唯一要做的工作就是定义 Dubbo Reference：
-
-```java
-@DubboReference
-private SpringCloudRestService restService;
-```
-
-## 发布 http 协议的服务
-
-
-## 多协议发布
-
-![img](/imgs/v3/tasks/protocol/http-usecase-1.png)
diff --git a/content/zh-cn/blog/java/proposals/_index.md b/content/zh-cn/blog/java/proposals/_index.md
@@ -0,0 +1,7 @@
+---
+title: "方案设计"
+linkTitle: "方案设计"
+weight: 30
+---
+
+
diff --git a/content/zh-cn/blog/java/proposals/service-discovery-migration.md b/content/zh-cn/blog/java/proposals/service-discovery-migration.md
diff --git a/content/zh-cn/overview/mannual/java-sdk/quick-start/deploy.md b/content/zh-cn/overview/mannual/java-sdk/quick-start/deploy.md
@@ -1,6 +1,6 @@
 ---
 description: 快速部署Dubbo应用
-linkTitle: 快速部署Dubbo应用
+linkTitle: 部署Dubbo应用
 title: 快速部署Dubbo应用
 type: docs
 weight: 3

diff --git a/...nt/zh-cn/overview/mannual/java-sdk/reference-manual/config/spring/annotation.md b/...nt/zh-cn/overview/mannual/java-sdk/reference-manual/config/spring/annotation.md
diff --git a/...t/zh-cn/overview/mannual/java-sdk/reference-manual/config/spring/spring-boot.md b/...t/zh-cn/overview/mannual/java-sdk/reference-manual/config/spring/spring-boot.md
@@ -13,7 +13,13 @@ weight: 3
 
 ## application.yaml
 
-`application.properties(application.yaml)` 支持的配置项与 [配置参考手册](../properties) 中描述的基本是一一对应的。
+以下是 Dubbo 框架支持的配置组件列表，可以在 Spring Boot 配置文件中指定所需配置：
+
+### 配置示例
+
+```yaml
+
+```
 
 ### dubbo
 * [**dubbo.application** - `org.apache.dubbo.config.ApplicationConfig`](../../properties#dubboapplication)
@@ -23,20 +29,20 @@ weight: 3
 * [**dubbo.protocol** - `org.apache.dubbo.config.ProtocolConfig`](../../properties#dubboprotocol)
 * [**dubbo.provider** - `org.apache.dubbo.config.ProviderConfig`](../../properties#dubboprovider)
 * [**dubbo.registry** - `org.apache.dubbo.config.RegistryConfig`](../../properties#dubboregistry)
+* [**dubbo.metrics** - `org.apache.dubbo.config.MetricsConfig`](../../properties#dubbometrics)
+* [**dubbo.tracing** - `org.apache.dubbo.config.TracingConfig`](../../properties#dubbotracing)
 * [**dubbo.ssl** - `org.apache.dubbo.config.SslConfig`](../../properties#dubbossl)
 * ~~[**dubbo.monitor** - `org.apache.dubbo.config.MonitorConfig`](../../properties#dubbomonitor)~~
 * ~~[**dubbo.module** - `org.apache.dubbo.config.ModuleConfig`](../../properties#dubbomodule)~~
 
 ### dubbo.metrics
-* [**dubbo.metrics** - `org.apache.dubbo.config.MetricsConfig`](../../properties#dubbometrics)
 * [**dubbo.metrics.aggregation** - `org.apache.dubbo.config.nested.AggregationConfig`](../../properties#dubbometricsaggregation)
 * [**dubbo.metrics.histogram** - `org.apache.dubbo.config.nested.HistogramConfig`](../../properties#dubbometricshistogram)
 * [**dubbo.metrics.prometheus** - `org.apache.dubbo.config.nested.PrometheusConfig`](../../properties#dubbometricsprometheus)
 * [**dubbo.metrics.prometheus.exporter** - `org.apache.dubbo.config.nested.PrometheusConfig$Exporter`](../../properties#dubbometricsprometheusexporter)
 * [**dubbo.metrics.prometheus.pushgateway** - `org.apache.dubbo.config.nested.PrometheusConfig$Pushgateway`](../../properties#dubbometricsprometheuspushgateway)
 
 ### dubbo.tracing
-* [**dubbo.tracing** - `org.apache.dubbo.config.TracingConfig`](../../properties#dubbotracing)
 * [**dubbo.tracing.baggage.correlation** - `org.apache.dubbo.config.nested.BaggageConfig$Correlation`](../../properties#dubbotracingbaggage.correlation)
 * [**dubbo.tracing.tracing-exporter.otlp-config** - `org.apache.dubbo.config.nested.ExporterConfig$OtlpConfig`](../../properties#dubbotracingtracing-exporterotlp-config)
 * [**dubbo.tracing.tracing-exporter.zipkin-config** - `org.apache.dubbo.config.nested.ExporterConfig$ZipkinConfig`](../../properties#dubbotracingtracing-exporterzipkin-config)
@@ -45,8 +51,6 @@ weight: 3
 * [**dubbo.tracing.sampling** - `org.apache.dubbo.config.nested.SamplingConfig`](../../properties#dubbotracingsampling)
 * [**dubbo.tracing.tracing-exporter** - `org.apache.dubbo.config.nested.ExporterConfig`](../../properties#dubbotracingtracing-exporter)
 
-
-
-## starters
+## starter列表
 
 starter 列表、版本、对应的组件版本
diff --git a/content/zh-cn/overview/mannual/java-sdk/reference-manual/faq/0/1.md b/content/zh-cn/overview/mannual/java-sdk/reference-manual/faq/0/1.md
@@ -10,9 +10,6 @@ weight: 1
 ---
 
 
-
-
-
 服务端的线程资源耗尽了。
 默认情况下，Dubbo 服务端的业务线程数是 200 个。如果多个并发请求量超过了 200，就会拒绝新的请求，抛出此错误。
 

diff --git a/content/zh-cn/overview/mannual/java-sdk/reference-manual/faq/0/2.md b/content/zh-cn/overview/mannual/java-sdk/reference-manual/faq/0/2.md
@@ -10,10 +10,6 @@ weight: 2
 ---
 
 
-
-
-
-
 ### 可能的原因
 这个提示是指用户配置的值与属性本身所需的数据类型并不匹配。比如 `dubbo.comsumer.threads` 属性只能接受数值属性，但是用户所输入的值混入了字母。
 

diff --git a/content/zh-cn/overview/mannual/java-sdk/reference-manual/protocol/triple.md b/content/zh-cn/overview/mannual/java-sdk/reference-manual/protocol/triple.md
@@ -126,7 +126,7 @@ Stream 分为以下三种。
 
 如果你记得 triple 协议原生支持 cURL 访问，即类似  `org.apache.dubbo.springboot.demo.idl.Greeter/greet` 的访问模式。通过增加以上注解后，即可为 triple 服务额外增加 REST 风格访问支持，如 `demo/greet` 的 GET 请求。
 
-### Spring Web
+### Spring Web注解
 Spring MVC 服务定义范例：
 ```java
 @RestController
@@ -137,7 +137,7 @@ public interface DemoService {
 }
 ```
 
-### JAX-RS
+### JAX-RS注解
 JAX-RS 服务定义范例：
 ```java
 @Path("/demo")
@@ -148,18 +148,165 @@ public interface DemoService {
 }
 ```
 
-## 性能指标
+## 异常类型传递
+Provider 端产生的业务异常需要作为响应值返回给 Consumer 客户端，消费端可以使用 `try catch` 捕获可能抛出的异常：
 
+```java
+try {
+	greeterProxy.echo(REQUEST_MSG);
+} catch (YourCustomizedException e) {
+	 e.printStackTrace();
+ } catch (RpcException e) {
+	e.printStackTrace();
+}
+```
+
+Dubbo 框架会在 provider 侧根据如下流程发送异常类型响应，不是所有业务异常都能原样返回，对于无法处理的异常类型，都会被框架封装成 `RpcException` 类型返回：
+
+![triple-exception](/imgs/blog/2022/12/19/triple/2.jpeg)
+
+## 附录
+### Protobuf与Java原生数据类型对比
+
+对于计划从 Java 接口完全迁移到 Protobuf 的用户而言，这里的信息可供参考，用以了解类型迁移可能面临的限制，Protobuf 描述语言是否能完全描述 Java 数据类型。
+
+本文对比了Protobuf和Java Interface这2种IDL的差异，帮助Dubbo协议开发者了解Protobuf，为后续转到Triple协议和Grpc协议做铺垫。
+
+#### 1. 数据类型
+
+##### 1.1. 基本类型
+
+| ptoto类型  | java类型 |
+| ---- | ---- |
+double | double
+float | float
+int32 | int
+int64 | long
+uint32 | int[注]
+uint64 | long[注]
+sint32 | int
+sint64 | long
+fixed32 | int[注]
+fixed64 | long[注]
+sfixed32 |  int
+sfixed64 | long
+bool | boolean
+string | String
+bytes | ByteString
+
+{{% alert title="注意" color="primary" %}}
+在Java中，无符号的32位和64位整数使用它们的有符号对数来表示，顶部位只存储在符号位中。
+{{% /alert %}}
+
+#### 2. 复合类型
+
+##### 2.1. 枚举
+
+* 原始pb代码
+
+```java.
+enum TrafficLightColor {
+    TRAFFIC_LIGHT_COLOR_INVALID = 0;
+    TRAFFIC_LIGHT_COLOR_UNSET = 1;
+    TRAFFIC_LIGHT_COLOR_GREEN = 2;
+    TRAFFIC_LIGHT_COLOR_YELLOW = 3;
+    TRAFFIC_LIGHT_COLOR_RED = 4;
+}
+```
+
+* 生成的java代码
+
+![image](/imgs/docs/advanced/protobufinterface/124234531-b96c2c80-db46-11eb-8155-a77dbe059f07.png)
+
+> 枚举是常量，因此采用大写
+##### 2.2. 数组
 
-## 协议实现
-列一些 java 实现中的细节内容，可以配置或调整的选项等。
+* 原始pb代码
 
-### 网络配置
-* 心跳检测
-* 网络传输包设置
-* 连接超时等
+```java
+message VipIDToRidReq {
+    repeated uint32 vipID = 1;
+}
+```
+
+* 生成的java代码
+
+![image](/imgs/docs/advanced/protobufinterface/124234564-c4bf5800-db46-11eb-94fc-a056af6089cb.png)
+
+> 底层实际上是1个ArrayList
+##### 2.3. 集合
+
+PB不支持无序、不重复的集合，只能 ``借用数组实现``，需要 ``自行去重``。
+
+##### 2.4. 字典
+
+* 原始pb代码
+
+```java
+message BatchOnlineRes {
+    map<uint32, uint32> onlineMap = 1;//在线状态
+}
+```
+
+* 生成的java代码
+
+![image](/imgs/docs/advanced/protobufinterface/124234654-e4568080-db46-11eb-9700-b30022ebee21.png)
+
+##### 2.5. 嵌套
+
+* 原始pb代码
+
+```java
+message BatchAnchorInfoRes {
+    map<uint32, AnchorInfo> list = 1; //用户信息map列表
+}
+/*
+* 对应接口的功能: 批量或单个获取用户信息
+*/
+message AnchorInfo {
+    uint32 ownerUid = 1 [json_name="uid"]; //用户id
+    string nickName = 2 [json_name="nn"]; //用户昵称
+    string smallAvatar = 3 [json_name="savt"]; //用户头像全路径-小
+    string middleAvatar = 4 [json_name="mavt"]; //用户头像全路径-中
+    string bigAvatar = 5 [json_name="bavt"]; //用户头像全路径-大
+    string avatar = 6 [json_name="avt"]; //用户头像
+}
+```
 
-### 线程模型
+* 生成的java代码
+
+![image](/imgs/docs/advanced/protobufinterface/124234723-f89a7d80-db46-11eb-82d0-a8aee5322098.png)
+
+#### 3. 字段默认值
+
+* 对于字符串，默认值为空字符串。
+* 对于字节，默认值为空字节。
+* 对于bools，默认值为false。
+* 对于数字类型，默认值为零。
+* 对于枚举，默认值为第一个定义的枚举值，它必须为0。
+* 对于消息字段，未设置字段。 它的确切值是语言相关的。 有关详细信息，请参阅生成的代码指南。
+
+#### 4. 整体结构
+
+|  Feature  |  Java Interface   | Protobuf  | 备注  |
+|  ----  | ----  | ----  | ----  |
+| 方法重载  | √ | × |  |
+| 泛型/模板化  | √ | × |  |
+| 方法继承  | √ | × |  |
+| 嵌套定义  | √ | 部分支持 | PB仅支持message和enum嵌套 |
+| import文件  | √ | √  |  |
+| 字段为null  | √ | × |  |
+| 多个入参  | √ | × | PB仅支持单入参 |
+| 0个入参  | √ | × | PB必须有入参 |
+| 0个出参  | √ | × | PB必须有出参 |
+| 入参/出参为抽象类  | √ | × | PB的入参/出参必须为具象类 |
+| 入参/出参为接口  | √ | × | PB的入参/出参必须为具象类 |
+| 入参/出参为基础类型  | √ | × | PB的入参/出参必须为结构体 |
+
+#### 5. 社区资料
+* 社区主页地址：https://developers.google.cn/protocol-buffers/
+* 社区开源地址：https://github.com/google/protobuf
+* 相关jar的maven：https://search.maven.org/search?q=com.google.protobuf
 
 
 
diff --git a/content/zh-cn/overview/mannual/java-sdk/reference-manual/routing-rule/_index.md b/content/zh-cn/overview/mannual/java-sdk/reference-manual/routing-rule/_index.md
@@ -1,7 +1,7 @@
 ---
-description: "Dubbo 路由规则详解，包括条件路由、动态配置、biaoqianluyou等"
-linkTitle: 单机运维命令(QOS)
-title: QOS 操作手册
+description: "Dubbo 路由规则详解，包括条件路由、动态配置、标签路由等，可以使用这些路由规则实现流量按比例转发、金丝雀发布、流量灰度、权重调整等能力。"
+linkTitle: 路由规则
+title: 路由规则
 type: docs
 weight: 99
 ---