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 e2c3c45727c Update idl usage document (#3041)
e2c3c45727c is described below
commit e2c3c45727c144db98f833f1344892ae44735cb4
Author: TomlongTK <[email protected]>
AuthorDate: Fri Oct 11 13:37:52 2024 +0800
Update idl usage document (#3041)
* Update idl usage document
* Update EN version
---
.../mannual/java-sdk/tasks/protocols/triple/idl.md | 230 ++++++++------------
.../mannual/java-sdk/tasks/protocols/triple/idl.md | 232 +++++++++------------
2 files changed, 183 insertions(+), 279 deletions(-)
diff --git a/content/en/overview/mannual/java-sdk/tasks/protocols/triple/idl.md
b/content/en/overview/mannual/java-sdk/tasks/protocols/triple/idl.md
index 2a1250f7bba..1471bac8a95 100644
--- a/content/en/overview/mannual/java-sdk/tasks/protocols/triple/idl.md
+++ b/content/en/overview/mannual/java-sdk/tasks/protocols/triple/idl.md
@@ -6,135 +6,28 @@ type: docs
weight: 2
---
-This example demonstrates how to define a service using Protocol Buffers and
publish it as an externally callable Triple protocol service. If you have
multi-language interoperability, gRPC interaction, or are familiar with and
prefer Protobuf development, you can use this approach; otherwise, consider the
previous Java interface-based triple development model.
-
-You can view the [full code for this
example](https://github.com/apache/dubbo-samples/tree/master/1-basic/dubbo-samples-api-idl).
-
-{{% alert title="Note" color="info" %}}
-The example used in this article is based on native API coding; here is a
[Spring Boot version of the
example](https://github.com/apache/dubbo-samples/tree/master/1-basic/dubbo-samples-spring-boot-idl)
for reference, which also follows the `protobuf+triple` model but includes
service discovery configuration.
-{{% /alert %}}
-
-## Run the Example
-
-First, download the example source code with the following command:
-```shell
-git clone --depth=1 https://github.com/apache/dubbo-samples.git
-```
-
-Change to the example source code directory:
-```shell
-cd dubbo-samples/1-basic/dubbo-samples-api-idl
-```
-
-Compile the project to generate code from the IDL, which calls the protoc
plugin provided by Dubbo to generate the corresponding service definition code:
-```shell
-mvn clean compile
-```
-
-The generated code is as follows:
-
-```text
-├── build
-│ └── generated
-│ └── source
-│ └── proto
-│ └── main
-│ └── java
-│ └── org
-│ └── apache
-│ └── dubbo
-│ └── samples
-│ └── tri
-│ └── unary
-│ ├── DubboGreeterTriple.java
-│ ├── Greeter.java
-│ ├── GreeterOuterClass.java
-│ ├── GreeterReply.java
-│ ├── GreeterReplyOrBuilder.java
-│ ├── GreeterRequest.java
-│ └──
GreeterRequestOrBuilder.java
-```
-
-### Start Server
-Run the following command to start the server.
-```shell
-mvn compile exec:java
-Dexec.mainClass="org.apache.dubbo.samples.tri.unary.TriUnaryServer"
-```
-
-### Access the Service
-There are two ways to access the Triple service:
-* Using standard HTTP tools
-* Using Dubbo client SDK
-
-#### cURL Access
-
-```shell
-curl \
- --header "Content-Type: application/json" \
- --data '{"name":"Dubbo"}' \
- http://localhost:50052/org.apache.dubbo.samples.tri.unary.Greeter/greet/
-```
-
-#### Dubbo Client Access
-Run the following command to start the Dubbo client and complete the service
call.
-```shell
-mvn compile exec:java
-Dexec.mainClass="org.apache.dubbo.samples.tri.unary.TriUnaryClient"
-```
-
-### Source Code Explanation
-
-### Project Dependencies
-Due to the use of the IDL development model, the dependencies such as dubbo,
protobuf-java must be added. Additionally, plugins like protobuf-maven-plugin
must be configured to generate the stub code.
-
-```xml
-<dependency>
- <groupId>org.apache.dubbo</groupId>
- <artifactId>dubbo</artifactId>
- <version>${dubbo.version}</version>
-</dependency>
-<dependency>
- <groupId>com.google.protobuf</groupId>
- <artifactId>protobuf-java</artifactId>
- <version>3.19.6</version>
-</dependency>
-<dependency>
- <groupId>com.google.protobuf</groupId>
- <artifactId>protobuf-java-util</artifactId>
- <version>3.19.6</version>
-</dependency>
-```
+## Usage
+### POM dependency
```xml
<plugin>
- <groupId>org.xolstice.maven.plugins</groupId>
- <artifactId>protobuf-maven-plugin</artifactId>
- <version>0.6.1</version>
- <configuration>
-
<protocArtifact>com.google.protobuf:protoc:${protoc.version}:exe:${os.detected.classifier}</protocArtifact>
-
<outputDirectory>build/generated/source/proto/main/java</outputDirectory>
- <protocPlugins>
- <protocPlugin>
- <id>dubbo</id>
- <groupId>org.apache.dubbo</groupId>
- <artifactId>dubbo-compiler</artifactId>
- <version>${dubbo.version}</version>
-
<mainClass>org.apache.dubbo.gen.tri.Dubbo3TripleGenerator</mainClass>
- </protocPlugin>
- </protocPlugins>
- </configuration>
- <executions>
- <execution>
- <goals>
- <goal>compile</goal>
- </goals>
- </execution>
- </executions>
+ <groupId>org.apache.dubbo</groupId>
+ <artifactId>dubbo-maven-plugin</artifactId>
+ <version>${dubbo.version}</version> <!-- Version 3.3.0 and above -->
+ <configuration>
+ <outputDir>build/generated/source/proto/main/java</outputDir> <!--
Refer to the following text for configurable parameters -->
+ </configuration>
</plugin>
```
+Configurable parameters
-{{% alert title="protoc Plugin Version Note" color="warning" %}}
-
-{{% /alert %}}
+| Parameter | Required |
Default value |
Description | Notes |
+|:-----------------:|:-------------:|:-------------------------------------------------------------------------------------------------:|:--------------------------------------------------:|:-------------------------------------:|
+| outputDir | false |
${project.build.directory}/generated-sources/protobuf/java
| Generated java file storage directory |
|
+| protoSourceDir | false |
${basedir}/src/main/proto |
proto file directory | |
+| protocArtifact | false |
com.google.protobuf:protoc:3.25.0:exe:Operating System Name:Operating System
Architecture | proto compiler component |
|
+| protocVersion | false |
3.25.0 | version
of protobuf-java | |
+| dubboGenerateType | false |
tri | Code
generation type | Can be filled with tri or tri_reactor |
### Service Definition
Define the Greeter service using Protocol Buffers.
@@ -215,7 +108,6 @@ public class TriUnaryClient {
}
}
```
-
## Frequently Asked Questions
### Protobuf Class Not Found
@@ -242,22 +134,7 @@ Additionally, to support direct access to
`application/json` format requests, th
### Generated Code Cannot Compile
When using Protobuf, ensure that the core Dubbo library version matches the
protoc plugin version and run `mvn clean compile` to regenerate the code.
-**1. After version 3.3.0**
-
-Starting from version 3.3.0+, configure the protoc plugin using
`dubbo-maven-plugin`. The version of `dubbo-maven-plugin` must match the core
dubbo version used:
-
-```xml
-<plugin>
- <groupId>org.apache.dubbo</groupId>
- <artifactId>dubbo-maven-plugin</artifactId>
- <version>${dubbo.version}</version>
- <configuration>
-
- </configuration>
-</plugin>
-```
-
-**2. Before version 3.3.0**
+**Before version 3.3.0**
Versions before 3.3.0 use `protobuf-maven-plugin` to configure the protoc
plugin, and the `dubbo-compiler` must match the core dubbo version used:
@@ -288,3 +165,76 @@ Versions before 3.3.0 use `protobuf-maven-plugin` to
configure the protoc plugin
</executions>
</plugin>
```
+## Run the Example
+This example demonstrates how to define a service using Protocol Buffers and
publish it as an externally callable Triple protocol service. If you have
multi-language interoperability, gRPC interaction, or are familiar with and
prefer Protobuf development, you can use this approach; otherwise, consider the
previous Java interface-based triple development model.
+
+You can view the [full code for this
example](https://github.com/apache/dubbo-samples/tree/master/1-basic/dubbo-samples-api-idl).
+
+{{% alert title="Note" color="info" %}}
+The example used in this article is based on native API coding; here is a
[Spring Boot version of the
example](https://github.com/apache/dubbo-samples/tree/master/1-basic/dubbo-samples-spring-boot-idl)
for reference, which also follows the `protobuf+triple` model but includes
service discovery configuration.
+{{% /alert %}}
+
+First, download the example source code with the following command:
+```shell
+git clone --depth=1 https://github.com/apache/dubbo-samples.git
+```
+
+Change to the example source code directory:
+```shell
+cd dubbo-samples/1-basic/dubbo-samples-api-idl
+```
+
+Compile the project to generate code from the IDL, which calls the protoc
plugin provided by Dubbo to generate the corresponding service definition code:
+```shell
+mvn clean compile
+```
+
+The generated code is as follows:
+
+```text
+├── build
+│ └── generated
+│ └── source
+│ └── proto
+│ └── main
+│ └── java
+│ └── org
+│ └── apache
+│ └── dubbo
+│ └── samples
+│ └── tri
+│ └── unary
+│ ├── DubboGreeterTriple.java
+│ ├── Greeter.java
+│ ├── GreeterOuterClass.java
+│ ├── GreeterReply.java
+│ ├── GreeterReplyOrBuilder.java
+│ ├── GreeterRequest.java
+│ └──
GreeterRequestOrBuilder.java
+```
+
+### Start Server
+Run the following command to start the server.
+```shell
+mvn compile exec:java
-Dexec.mainClass="org.apache.dubbo.samples.tri.unary.TriUnaryServer"
+```
+
+### Access the Service
+There are two ways to access the Triple service:
+* Using standard HTTP tools
+* Using Dubbo client SDK
+
+#### cURL Access
+
+```shell
+curl \
+ --header "Content-Type: application/json" \
+ --data '{"name":"Dubbo"}' \
+ http://localhost:50052/org.apache.dubbo.samples.tri.unary.Greeter/greet/
+```
+
+#### Dubbo Client Access
+Run the following command to start the Dubbo client and complete the service
call.
+```shell
+mvn compile exec:java
-Dexec.mainClass="org.apache.dubbo.samples.tri.unary.TriUnaryClient"
+```
diff --git
a/content/zh-cn/overview/mannual/java-sdk/tasks/protocols/triple/idl.md
b/content/zh-cn/overview/mannual/java-sdk/tasks/protocols/triple/idl.md
index a19bfe3e9f4..d0464426315 100644
--- a/content/zh-cn/overview/mannual/java-sdk/tasks/protocols/triple/idl.md
+++ b/content/zh-cn/overview/mannual/java-sdk/tasks/protocols/triple/idl.md
@@ -6,135 +6,29 @@ type: docs
weight: 2
---
-本示例演示如何使用 Protocol Buffers 定义服务，并将其发布为对外可调用的 triple
协议服务。如果你有多语言业务互调、gRPC互通，或者熟悉并喜欢 Protobuf 的开发方式，则可以使用这种模式，否则可以考虑上一篇基于Java接口的
triple 开发模式。
-
-可在此查看
[本示例的完整代码](https://github.com/apache/dubbo-samples/tree/master/1-basic/dubbo-samples-api-idl)。
-
-{{% alert title="注意" color="info" %}}
-本文使用的示例是基于原生 API 编码的，这里还有一个 [Spring Boot
版本的示例](https://github.com/apache/dubbo-samples/tree/master/1-basic/dubbo-samples-spring-boot-idl)
供参考，同样是 `protobuf+triple` 的模式，但额外加入了服务发现配置。
-{{% /alert %}}
-
-## 运行示例
-
-首先，可通过以下命令下载示例源码：
-```shell
-git clone --depth=1 https://github.com/apache/dubbo-samples.git
-```
-
-进入示例源码目录：
-```shell
-cd dubbo-samples/1-basic/dubbo-samples-api-idl
-```
-
-编译项目，由 IDL 生成代码，这会调用 dubbo 提供的 protoc 插件生成对应的服务定义代码：
-```shell
-mvn clean compile
-```
-
-生成代码如下
-
-```text
-├── build
-│ └── generated
-│ └── source
-│ └── proto
-│ └── main
-│ └── java
-│ └── org
-│ └── apache
-│ └── dubbo
-│ └── samples
-│ └── tri
-│ └── unary
-│ ├── DubboGreeterTriple.java
-│ ├── Greeter.java
-│ ├── GreeterOuterClass.java
-│ ├── GreeterReply.java
-│ ├── GreeterReplyOrBuilder.java
-│ ├── GreeterRequest.java
-│ └──
GreeterRequestOrBuilder.java
-```
-
-### 启动Server
-运行以下命令启动 server。
-```shell
-mvn compile exec:java
-Dexec.mainClass="org.apache.dubbo.samples.tri.unary.TriUnaryServer"
-```
-
-### 访问服务
-有两种方式可以访问 Triple 服务：
-* 以标准 HTTP 工具访问
-* 以 Dubbo client sdk 访问
-
-#### cURL 访问
-
-```shell
-curl \
- --header "Content-Type: application/json" \
- --data '{"name":"Dubbo"}' \
- http://localhost:50052/org.apache.dubbo.samples.tri.unary.Greeter/greet/
-```
-
-#### Dubbo client 访问
-运行以下命令，启动 Dubbo client 并完成服务调用
-```shell
-mvn compile exec:java
-Dexec.mainClass="org.apache.dubbo.samples.tri.unary.TriUnaryClient"
-```
-
-## 源码讲解
+## 使用方式
-### 项目依赖
-由于使用 IDL 开发模式，因此要添加 dubbo、protobuf-java 等依赖，同时还要配置 protobuf-maven-plugin
等插件，用于生成桩代码。
-
-```xml
-<dependency>
- <groupId>org.apache.dubbo</groupId>
- <artifactId>dubbo</artifactId>
- <version>${dubbo.version}</version>
-</dependency>
-<dependency>
- <groupId>com.google.protobuf</groupId>
- <artifactId>protobuf-java</artifactId>
- <version>3.19.6</version>
-</dependency>
-<dependency>
- <groupId>com.google.protobuf</groupId>
- <artifactId>protobuf-java-util</artifactId>
- <version>3.19.6</version>
-</dependency>
-```
+### POM依赖
```xml
<plugin>
- <groupId>org.xolstice.maven.plugins</groupId>
- <artifactId>protobuf-maven-plugin</artifactId>
- <version>0.6.1</version>
- <configuration>
-
<protocArtifact>com.google.protobuf:protoc:${protoc.version}:exe:${os.detected.classifier}</protocArtifact>
-
<outputDirectory>build/generated/source/proto/main/java</outputDirectory>
- <protocPlugins>
- <protocPlugin>
- <id>dubbo</id>
- <groupId>org.apache.dubbo</groupId>
- <artifactId>dubbo-compiler</artifactId>
- <version>${dubbo.version}</version>
-
<mainClass>org.apache.dubbo.gen.tri.Dubbo3TripleGenerator</mainClass>
- </protocPlugin>
- </protocPlugins>
- </configuration>
- <executions>
- <execution>
- <goals>
- <goal>compile</goal>
- </goals>
- </execution>
- </executions>
+ <groupId>org.apache.dubbo</groupId>
+ <artifactId>dubbo-maven-plugin</artifactId>
+ <version>${dubbo.version}</version> <!-- 3.3.0及以上版本 -->
+ <configuration>
+ <outputDir>build/generated/source/proto/main/java</outputDir> <!--
参考下文可配置参数 -->
+ </configuration>
</plugin>
```
+configuration可配置参数
-{{% alert title="protoc 插件版本说明" color="warning" %}}
-
-{{% /alert %}}
+| 参数 | 必填参数 | 默认值
| 说明 | 备注 |
+|:-----------------:|:------:|:----------------------------------------------------------:|:----------------:|:------------------:|
+| outputDir | 否 |
${project.build.directory}/generated-sources/protobuf/java | 生成的java文件存放目录 |
|
+| protoSourceDir | 否 | ${basedir}/src/main/proto
| proto文件目录 | |
+| protocArtifact | 否 |
com.google.protobuf:protoc:3.25.0:exe:操作系统名:操作系统架构 | proto编译器组件 |
|
+| protocVersion | 否 | 3.25.0
| protobuf-java的版本 | |
+| dubboGenerateType | 否 | tri
| 代码生成类型 | 可填tri或者tri_reactor |
### 服务定义
使用 Protocol Buffers 定义 Greeter 服务
@@ -242,22 +136,7 @@ public class TriUnaryClient {
### 生成的代码无法编译
在使用 Protobuf 时，请尽量保持 dubbo 核心库版本与 protoc 插件版本一致，并运行 `mvn clean compile` 重新生成代码。
-**1. 3.3.0 版本之后**
-
-3.3.0+ 版本开始使用 `dubbo-maven-plugin` 配置 protoc 插件，`dubbo-maven-plugin`
的版本必须保持和使用的内核 dubbo 版本一致：
-
-```xml
-<plugin>
- <groupId>org.apache.dubbo</groupId>
- <artifactId>dubbo-maven-plugin</artifactId>
- <version>${dubbo.version}</version>
- <configuration>
-
- </configuration>
-</plugin>
-```
-
-**2. 3.3.0 版本之前**
+**3.3.0 版本之前的POM依赖**
3.3.0 之前的版本使用 `protobuf-maven-plugin` 配置 protoc 插件，其中 `dubbo-compiler`
必须保持和使用的内核 dubbo 版本一致：
@@ -287,4 +166,79 @@ public class TriUnaryClient {
</execution>
</executions>
</plugin>
-```
\ No newline at end of file
+```
+
+## 运行示例
+
+本示例演示如何使用 Protocol Buffers 定义服务，并将其发布为对外可调用的 triple
协议服务。如果你有多语言业务互调、gRPC互通，或者熟悉并喜欢 Protobuf 的开发方式，则可以使用这种模式，否则可以考虑上一篇基于Java接口的
triple 开发模式。
+
+可在此查看
[本示例的完整代码](https://github.com/apache/dubbo-samples/tree/master/1-basic/dubbo-samples-api-idl)。
+
+{{% alert title="注意" color="info" %}}
+本文使用的示例是基于原生 API 编码的，这里还有一个 [Spring Boot
版本的示例](https://github.com/apache/dubbo-samples/tree/master/1-basic/dubbo-samples-spring-boot-idl)
供参考，同样是 `protobuf+triple` 的模式，但额外加入了服务发现配置。
+{{% /alert %}}
+
+首先，可通过以下命令下载示例源码：
+```shell
+git clone --depth=1 https://github.com/apache/dubbo-samples.git
+```
+
+进入示例源码目录：
+```shell
+cd dubbo-samples/1-basic/dubbo-samples-api-idl
+```
+
+编译项目，由 IDL 生成代码，这会调用 dubbo 提供的 protoc 插件生成对应的服务定义代码：
+```shell
+mvn clean compile
+```
+
+生成代码如下
+
+```text
+├── build
+│ └── generated
+│ └── source
+│ └── proto
+│ └── main
+│ └── java
+│ └── org
+│ └── apache
+│ └── dubbo
+│ └── samples
+│ └── tri
+│ └── unary
+│ ├── DubboGreeterTriple.java
+│ ├── Greeter.java
+│ ├── GreeterOuterClass.java
+│ ├── GreeterReply.java
+│ ├── GreeterReplyOrBuilder.java
+│ ├── GreeterRequest.java
+│ └──
GreeterRequestOrBuilder.java
+```
+
+### 启动Server
+运行以下命令启动 server。
+```shell
+mvn compile exec:java
-Dexec.mainClass="org.apache.dubbo.samples.tri.unary.TriUnaryServer"
+```
+
+### 访问服务
+有两种方式可以访问 Triple 服务：
+* 以标准 HTTP 工具访问
+* 以 Dubbo client sdk 访问
+
+#### cURL 访问
+
+```shell
+curl \
+ --header "Content-Type: application/json" \
+ --data '{"name":"Dubbo"}' \
+ http://localhost:50052/org.apache.dubbo.samples.tri.unary.Greeter/greet/
+```
+
+#### Dubbo client 访问
+运行以下命令，启动 Dubbo client 并完成服务调用
+```shell
+mvn compile exec:java
-Dexec.mainClass="org.apache.dubbo.samples.tri.unary.TriUnaryClient"
+```
