diff --git a/.htaccess b/.htaccess index 1e5538c77f22..673542e0b4f6 100644 --- a/.htaccess +++ b/.htaccess @@ -29,6 +29,6 @@ RewriteCond "%{HTTP:Accept-Language}" ^zh [NC] RewriteRule ^/?faq/?([\w\-/]+)?$ "/zh/docs3-v2/java-sdk/faq/$1" [L,R=302] - RewriteRule ^/?faq/?([\w\-/]+)?$ "/en/docs/java-sdk/faq/$1" [L,R=302] + RewriteRule ^/?faq/?([\w\-/]+)?$ "/en/docs3-v2/java-sdk/faq/$1" [L,R=302] diff --git a/content/en/_index.html b/content/en/_index.html index 8abfe73fbcdd..832c3e6d5ffb 100644 --- a/content/en/_index.html +++ b/content/en/_index.html @@ -6,10 +6,10 @@ {{< blocks/cover title="Apache Dubbo" image_anchor="top" height="auto" color="primary" >}}
- }}"> + }}"> LEARN MORE - + DOWNLOAD diff --git a/content/en/blog/releases/past-releases.md b/content/en/blog/releases/past-releases.md index 6c1aef84121a..fe2627e2056d 100644 --- a/content/en/blog/releases/past-releases.md +++ b/content/en/blog/releases/past-releases.md @@ -6,6 +6,9 @@ description: > This article will introduce you how to understand the details of each version and upgrade matters needing attention. --- +{{% pageinfo %}} This document is no longer maintained. You are currently viewing a snapshot version. If you want to see the latest version of the documentation, see [Latest Version](/en/release/). +{{% /pageinfo %}} + ## Verification you can follow these [procedures](https://www.apache.org/info/verification) and the [KEYS](https://downloads.apache.org/dubbo/KEYS) file to verify the download files diff --git a/content/en/community/_index.md b/content/en/community/_index.md index 95c7cbc6bf16..efe0dcd67205 100644 --- a/content/en/community/_index.md +++ b/content/en/community/_index.md @@ -1,8 +1,5 @@ --- title: Community -menu: - main: - weight: 40 --- diff --git a/content/en/docs/_index.md b/content/en/docs/_index.md index d93f8ef211da..703cca0682dc 100755 --- a/content/en/docs/_index.md +++ b/content/en/docs/_index.md @@ -3,9 +3,6 @@ title: "Documentation" linkTitle: "Documentation" weight: 20 -menu: - main: - weight: 20 --- Welcome to the Dubbo documentation site! diff --git a/content/en/docs3-v2/erlang-sdk/_index.md b/content/en/docs3-v2/erlang-sdk/_index.md index 3660ce639b4f..6641d6ff4f69 100755 --- a/content/en/docs3-v2/erlang-sdk/_index.md +++ b/content/en/docs3-v2/erlang-sdk/_index.md @@ -5,6 +5,5 @@ title: "Erlang" linkTitle: "Erlang" weight: 500 description: "Erlang SDK Manual" -manualLinkRelref: ../../../docs/v3.0/languages/erlang/ --- diff --git a/content/en/docs3-v2/golang-sdk/_index.md b/content/en/docs3-v2/golang-sdk/_index.md index cc53ed512bbf..618445df484e 100755 --- a/content/en/docs3-v2/golang-sdk/_index.md +++ b/content/en/docs3-v2/golang-sdk/_index.md @@ -5,6 +5,5 @@ title: "Golang" linkTitle: "Golang" weight: 20 description: "Go SDK Manual" -manualLinkRelref: ../../../docs/v3.0/languages/golang/ --- diff --git a/content/en/docs3-v2/java-sdk/_index.md b/content/en/docs3-v2/java-sdk/_index.md new file mode 100755 index 000000000000..341bf2830b76 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/_index.md @@ -0,0 +1,19 @@ + +--- +type: docs +title: "Java" +weight: 10 +no_list: true +hide_summary: true +description: "Java SDK Manual" +--- + +- Quick start: + - [Spring Boot Quick Development Dubbo Service](quick-start/spring-boot/) + - [Configuration Reference Manual](reference-manual/config/) +- Advanced features: + - [Extended Filter, Router to intercept traffic](concepts-and-architecture/service-invocation/) +- Reference book: + - [Registry Configuration Guide](reference-manual/registry/) +- Upgrades and Compatibility: + - [3.0 Migration Guide](upgrades-and-compatibility/) diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/_index.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/_index.md new file mode 100755 index 000000000000..75167223dfd7 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/_index.md @@ -0,0 +1,11 @@ + +--- +type: docs +title: "Advanced Features" +linkTitle: "Advanced Features" +weight: 4 +no_list: true +hide_summary: true +description: "The following is a list of all functions supported by Dubbo, browse directly on this page or view them by category on the left menu." +--- + diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/others/_index.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/others/_index.md new file mode 100755 index 000000000000..b469c5d75294 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/others/_index.md @@ -0,0 +1,8 @@ + +--- +type: docs +title: "Others" +linkTitle: "Others" +weight: 5 +--- + diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/others/dubbo-kubernetes-probe.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/others/dubbo-kubernetes-probe.md new file mode 100644 index 000000000000..9b612bb8a0a4 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/others/dubbo-kubernetes-probe.md @@ -0,0 +1,70 @@ +--- +type: docs +title: "Kubernetes Probe" +linkTitle: "Kubernetes Probe" +weight: 5 +description: "Understand the extension and application scenarios of Dubbo3 and Kubernetes life cycle alignment probe" +--- + +## Feature description +[Pod lifecycle](https://kubernetes.io/zh/docs/concepts/workloads/pods/pod-lifecycle/) is closely related to service scheduling. Through the implementation of official Kubernetes probes, Dubbo3 and even the entire application can The life cycle of the Pod and the life cycle of the Pod. In the entire life cycle of the Pod, only the health check part of the Pod is affected. We can configure the liveness probe (survival probe) and readiness probe (readability probe) to Affects the life cycle of the container. + +Through the SPI mechanism of Dubbo3, various "probes" are implemented internally, based on the HTTP service of the Dubbo3 QOS operation and maintenance module, so that the container probe can obtain the status of the corresponding probe in the application. In addition, the implementation mechanism of SPI is also conducive to users' self-expanding of internal "probes", so that the entire application life cycle can be more effectively controlled. + +**SPI interfaces corresponding to the three probes** + +- livenessProbe: `org.apache.dubbo.qos.probe.LivenessProbe` +- readinessProbe: `org.apache.dubbo.qos.probe.ReadinessProbe` +- startupProbe: `org.apache.dubbo.qos.probe.StartupProbe` + +The interface will automatically obtain the implementation of all SPIs of the current application, and the interface will return success if the SPI implementations of the corresponding interface are successfully ready. + +For an introduction to more extensions of Dubbo3 SPI, see [Dubbo SPI Extensions](/en/docs3-v2/java-sdk/reference-manual/spi/description/) + +## scenes to be used +- kubelet uses `liveness probe` to determine if your application is running, to see if it is alive. Generally speaking, if your program crashes, Kubernetes will immediately know that the program has terminated, and then restart the program. The purpose of our liveness probe is to capture that the current application has not terminated or crashed. If these situations occur, restart the container in this state so that the application can still continue in the presence of bugs run down. +- The kubelet uses `readiness probe` to determine if the container is ready to receive traffic. Is it ready and ready to work now. Only when the containers in the Pod are all in the ready state, the kubelet will consider the Pod to be in the ready state, because there may be multiple containers under a Pod. If the Pod is not ready, we will remove it from the Service's Endpoints list, so that our traffic will not be routed to the Pod. + +## How to use + +### Survival detection + +For the livenessProbe liveness detection, since the Dubbo3 framework itself cannot obtain the liveness status of the application, this interface has no default implementation and returns success by default. Developers can expand this SPI interface according to the SPI definition, and judge whether it is alive or not from the application level. + +About [liveness liveness probe](../../../reference-manual/spi/description/liveness/) extension example +### Readiness check + +For the readinessProbe readiness detection, Dubbo3 currently provides two detection dimensions by default. One is to judge whether the Dubbo3 service itself is started or stopped, and the other is to check whether all services have registered interfaces. If all services have been offline from the registration center (you can Operate via QOS Operations) will return Not Ready. + +About the [readiness readiness probe](../../../reference-manual/spi/description/readiness/) extended example + +### Start detection + +For startupProbe startup detection, Dubbo3 currently provides a detection dimension by default, which is to return to the ready state after all startup processes (interface exposure, registration center writing, etc.) are completed. + +About the [startup startup probe](../../../reference-manual/spi/description/startup/) extended example + +### Reference example +```yaml +livenessProbe: + httpGet: + path: /live + port: 22222 + initialDelaySeconds: 5 + periodSeconds: 5 +readinessProbe: + httpGet: + path: /ready + port: 22222 + initialDelaySeconds: 5 + periodSeconds: 5 +startupProbe: + httpGet: + path: /startup + port: 22222 + failureThreshold: 30 + periodSeconds: 10 +``` +> QOS When the computing node detects memory pressure, kuberentes will BestEffort -> Burstable -> Guaranteed to evict Pods in sequence. + +At present, all three probes have corresponding interfaces, and the path is the command in QOS. Please modify the port information according to the QOS configuration (the default port is 22222). For other parameters, please refer to [Kubernetes official documentation](https://kubernetes.io/zh/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/). \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/others/graceful-shutdown.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/others/graceful-shutdown.md new file mode 100644 index 000000000000..c7e7ec012c99 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/others/graceful-shutdown.md @@ -0,0 +1,50 @@ +--- +type: docs +title: "Graceful shutdown" +linkTitle: "Graceful shutdown" +weight: 2 +description: "Let the Dubbo service complete graceful shutdown" +--- + +## Feature description + +Graceful shutdown means that the service instance can be stopped safely and smoothly without affecting the ongoing business. +A Dubbo service may be both a service provider and a service consumer. When the service is stopped: +1. Consumers will no longer request stopped service instances +2. The request being processed by the service instance can be processed normally + +## scenes to be used + +1. Stop the service with `kill PID` +2. Stop the service through `/shutdown` of SpringBoot Actuator + +Dubbo 3.0 and above supports different types of Java applications, including SpringBoot applications, Spring applications, and non-Spring applications. + +## How to use + +Set the graceful shutdown timeout, the default timeout is 10 seconds, if it times out, it will be forced to shut down. +This parameter can be configured in the dubbo.properties file, for example: 30 seconds. +```properties +# Stop service waiting time, unit: milliseconds +dubbo.service.shutdown.wait=30000 +``` + +## Precautions + +1. Dubbo uses JDK's ShutdownHook to complete graceful shutdown, so if the user uses `kill -9 PID` and other forced shutdown commands, it will not execute graceful shutdown, and will only execute when `kill PID` is passed. + +2. Verify that Dubbo's ShutdownHook is executed. You can find the keyword in the log file: `Run shutdown hook now.` + +3. If Spring is used, please upgrade to version 4.2 and above, it is recommended to use version 5 or above + +4. If SpringBoot is used, Dubbo's ShutdownHook will be executed before SpringBoot's ShutdownHook, + If you use SpringBoot 2.3 and above, it is recommended to use it with SpringBoot's graceful shutdown, and configure it in the configuration file application.yml: +```yml +server: + shutdown: graceful +``` + +5. If the ShutdownHook does not take effect, you can call it yourself according to the specific scenario: +```java +ApplicationModel.defaultModel().destroy(); +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/others/logger-management.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/others/logger-management.md new file mode 100644 index 000000000000..3e664f9a3bae --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/others/logger-management.md @@ -0,0 +1,120 @@ +--- +type: docs +title: "Log Framework Adaptation and Runtime Management" +linkTitle: "Log framework adaptation and runtime management" +weight: 4 +description: "Adapt to the log framework in Dubbo and support dynamic switching of the log framework used at runtime" +--- +## Feature description +Adaptation of log frameworks. Since `2.2.1`, dubbo has built-in adaptation of log4j, slf4j, jcl, and jdk log frameworks. + +Log framework runtime management, starting from `3.0.10`, dubbo-qos runtime management supports query log configuration and dynamically modify the used log framework and log level. + +> The log configuration modified by dubbo-qos is not stored persistently, and will become invalid after the application is restarted. +## scenes to be used + +## How to use +## Log framework adaptation +The logging output policy can be explicitly configured in the following ways + +### 1. Command line + +```sh +java -Ddubbo.application.logger=log4j +``` + +### 2. Specify in `dubbo.properties` + +``` +dubbo.application.logger=log4j +``` + +### 3. Configuration in `dubbo.xml` + +```xml + +``` + +For custom extensions, please refer to [Log Adapter Extension](../../../reference-manual/spi/description/logger-adapter) + +## Logging framework runtime management +### 1. Query log configuration + +Command: `loggerInfo` + +**example** +```bash +> telnet 127.0.0.1 22222 +> loggerInfo +``` + +**output** +``` +Trying 127.0.0.1... +Connected to localhost. +Escape character is '^]'. + ___ __ __ ___ ___ ____ + / _ \ / / / // _ ) / _ ) / __ \ + / // // /_/ // _ |/ _ |/ /_/ / +/____/ \____//____//____/ \____/ +dubbo>loggerInfo +Available logger adapters: [jcl, jdk, log4j, slf4j]. Current Adapter: [log4j]. Log level: INFO +``` + +### 2. Modify log level + +Command: `switchLogLevel {level}` + +level: `ALL`, `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `OFF` + +**example** +```bash +> telnet 127.0.0.1 22222 +> switchLogLevel WARN +``` + +**output** +``` +Trying 127.0.0.1... +Connected to localhost. +Escape character is '^]'. + ___ __ __ ___ ___ ____ + / _ \ / / / // _ ) / _ ) / __ \ + / // // /_/ // _ |/ _ |/ /_/ / +/____/ \____//____//____/ \____/ +dubbo>loggerInfo +Available logger adapters: [jcl, jdk, log4j, slf4j]. Current Adapter: [log4j]. Log level: INFO +dubbo>switchLogLevel WARN +OK +dubbo>loggerInfo +Available logger adapters: [jcl, jdk, log4j, slf4j]. Current Adapter: [log4j]. Log level: WARN``` +``` + +### 3. Modify the log output framework + +Command: `switchLogger {loggerAdapterName}` + +loggerAdapterName: `slf4j`, `jcl`, `log4j`, `jdk`, `log4j2` + +**example** +```bash +> telnet 127.0.0.1 22222 +> switchLogger slf4j +``` + +**output** +``` +Trying 127.0.0.1... +Connected to localhost. +Escape character is '^]'. + ___ __ __ ___ ___ ____ + / _ \ / / / // _ ) / _ ) / __ \ + / // // /_/ // _ |/ _ |/ /_/ / +/____/ \____//____//____/ \____/ +dubbo>loggerInfo +Available logger adapters: [jcl, slf4j, log4j, jdk]. Current Adapter: [log4j]. Log level: INFO +dubbo>switchLogger slf4j +OK +dubbo>loggerInfo +Available logger adapters: [jcl, slf4j, log4j, jdk]. Current Adapter: [slf4j]. Log level: INFO +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/others/service-container.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/others/service-container.md new file mode 100644 index 000000000000..724749dae7af --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/others/service-container.md @@ -0,0 +1,60 @@ +--- +type: docs +title: "Custom Service Container" +linkTitle: "Custom service container" +weight: 1 +description: "Understand the service custom container type and usage in Dubbo 3" +--- + +## Feature description +The service container of Dubbo 3 is a standalone startup program, because the background service does not need the functions of web containers such as Tomcat or JBoss. If you insist on using the web container to load the service provider, it will increase complexity and waste resources. Therefore, services usually do not require the features of web containers such as Tomcat/JBoss, and there is no need to use web containers to load services. + +The Dubbo3 service container is just a simple Main method and loads a simple Spring container for exposing services. + +The loading content of the service container can be extended, and spring, jetty, log4j, etc. are built-in, and can be extended through [container extension point](../../../reference-manual/spi/description/container). The configuration is configured in the -D parameter of the java command or `dubbo.properties`. + +## scenes to be used +The web container is mainly used to respond to http requests and static pages. The Dubbo service provider only provides dubbo services externally. It is not suitable to use the web container. As a dubbo service provider alone, it only needs to load a simple spring container through a main method Expose the service. + +## How to use +### Spring Container +- Autoload all Spring configurations under the `META-INF/spring` directory. + +- Configure the spring configuration loading location: + + ```fallback + dubbo.spring.config=classpath*:META-INF/spring/*.xml +### Jetty Container +- Starts an embedded Jetty for reporting status. +- configuration: + - `dubbo.jetty.port=8080`: configure jetty startup port + - `dubbo.jetty.directory=/foo/bar`: Configure a directory that can be directly accessed through jetty to store static files + - `dubbo.jetty.page=log,status,system`: configure the displayed pages, all pages are loaded by default + +### Log4j Container + +- Automatically configure the configuration of log4j. When multiple processes are started, the log files are automatically divided into directories by process. +- configuration: + - `dubbo.log4j.file=/foo/bar.log`: configure log file path + - `dubbo.log4j.level=WARN`: configure log level + - `dubbo.log4j.subdirectory=20880`: Configure the log subdirectory for multi-process startup to avoid conflicts + + +### Container loading instructions +Only spring is loaded by default +```sh +java org.apache.dubbo.container.Main +``` +Pass in the container to be loaded through the main function parameter +```sh +java org.apache.dubbo.container.Main spring jetty log4j +``` +Pass in the container to be loaded through the JVM startup parameters + +```sh +java org.apache.dubbo.container.Main -Ddubbo.container=spring,jetty,log4j +``` +Pass in the container to be loaded through `dubbo.properties` configuration under the classpath +```fallback +dubbo.container=spring,jetty,log4j +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/others/set-host.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/others/set-host.md new file mode 100644 index 000000000000..7dba5c2b4e52 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/others/set-host.md @@ -0,0 +1,80 @@ +--- +type: docs +title: "Host Address Custom Exposure" +linkTitle: "Host address custom exposure" +weight: 3 +description: "Custom Dubbo service exposed host address" +--- + +## Feature description + +In Dubbo, Provider mainly does two things when it starts +- One is to start the server +- The second is to register the service with the registration center. When starting the server, the socket needs to be bound, and when the service is registered with the registration center, the unique service address of the socket needs to be sent. + +1. What is the default `host` when `host` is not set in `dubbo`? +2. How to specify the `host` of the service in `dubbo`, can we use hostname or domain instead of IP address as `host`? +3. When using docker, sometimes it is necessary to set port mapping. At this time, the socket bound when starting the server and the socket registered with the registration center use different port numbers. How to set it at this time? + +## scenes to be used +## How to use +### Default host when no host is set + +The general dubbo protocol configuration is as follows: +```xml + ... + + ... +``` + +It can be seen that only the port number is configured, and the host is not configured. What is the host set at this time? + +Looking at the code, it is found that in `org.apache.dubbo.config.ServiceConfig#findConfigedHosts()`, the default host is obtained through `InetAddress.getLocalHost().getHostAddress()`. Its return value is as follows: + +1. When not connected to the Internet, return 127.0.0.1 +2. In the Alibaba Cloud server, return the private address, such as: 172.18.46.234 +3. When testing locally, return the public address, such as: 30.5.10.11 + +### Specify the socket of the service + +Besides, you can configure `host` through `dubbo.protocol` or `dubbo.provider`’s `host` property, which supports IP address and domain name, as follows: + +```xml + ... + + ... +``` + +### socket uses a different port number + +See [dubbo set host by environment variable](https://github.com/apache/dubbo-samples/tree/master/2-advanced/dubbo-samples-docker) + +Some deployment scenarios need to dynamically specify the address of the service registration, such as the docker bridge network mode to specify the registration host ip to achieve external network communication. dubbo provides two pairs of system properties in the startup phase, which are used to set the ip and port addresses for external communication. + +* **DUBBO_IP_TO_REGISTRY**: Register to the ip address of the registration center +* **DUBBO_PORT_TO_REGISTRY**: Register to the port of the registry center +* **DUBBO_IP_TO_BIND**: Listening ip address +* **DUBBO_PORT_TO_BIND**: Listening port + +The above four configuration items are optional. If you do not configure dubbo, it will automatically obtain the ip and port. Please choose the configuration flexibly according to the specific deployment scenario. +dubbo supports multiple protocols. If an application exposes multiple different protocol services at the same time, and you need to specify an ip or port for each service separately, please add a protocol prefix before the above attributes. Such as: + +* **HESSIAN_DUBBO_PORT_TO_BIND**: port bound by hessian protocol +* **DUBBO_DUBBO_PORT_TO_BIND**: port bound by dubbo protocol +* **HESSIAN_DUBBO_IP_TO_REGISTRY**: ip registered by hessian protocol +* **DUBBO_DUBBO_IP_TO_REGISTRY**: ip registered by dubbo protocol + +PORT_TO_REGISTRY or IP_TO_REGISTRY will not be used as default PORT_TO_BIND or IP_TO_BIND, but the reverse is true. Such as: + +* Set `PORT_TO_REGISTRY=20881` and `IP_TO_REGISTRY=30.5.97.6`, then `PORT_TO_BIND` and `IP_TO_BIND` will not be affected +* Set `PORT_TO_BIND=20881` and `IP_TO_BIND=30.5.97.6`, then default `PORT_TO_REGISTRY=20881` and `IP_TO_REGISTRY=30.5.97.6` + +### Summarize + +1. You can configure `host` through the `host` attribute of `dubbo.protocol` or `dubbo.provider`, and support IP addresses and domain names. But at this time, the IP address registered to the registration center and the listening IP address are the same value +2. In order to solve the problem that the consumer cannot communicate with the provider in the virtual environment or LAN, you can set the IP address registered to the registration center and the listening IP address respectively through environment variables, and its priority is higher than `dubbo.protocol` or `dubbo. provider`s `host` configuration + +### refer to + +1. [Proposal: support hostname or domain in service discovery.](https://github.com/apache/dubbo/issues/2043) +2. [dubbo sets host through environment variables](https://github.com/apache/dubbo-samples/tree/master/2-advanced/dubbo-samples-docker) \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/performance/_index.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/performance/_index.md new file mode 100755 index 000000000000..d7c861b65991 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/performance/_index.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "Diagnostics and Tuning" +linkTitle: "Diagnostics" +weight: 3 +--- \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/performance/concurrency-control.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/performance/concurrency-control.md new file mode 100644 index 000000000000..295dd160f046 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/performance/concurrency-control.md @@ -0,0 +1,74 @@ +--- +type: docs +title: "Concurrency Control" +linkTitle: "Concurrency Control" +weight: 28 +description: "Concurrency Control in Dubbo" +--- + +## Configuration example + +### Example 1 + +To limit each method of `com.foo.BarService`, the concurrent execution on the server side (or the number of threads in the thread pool) cannot exceed 10: + +```xml + +``` + +### Example 2 + +To limit the `sayHello` method of `com.foo.BarService`, the concurrent execution on the server side (or the number of threads in the thread pool) cannot exceed 10: + +```xml + + + +``` +### Example 3 + +Limit each method of `com.foo.BarService` to no more than 10 concurrent executions per client (or the number of requests occupying a connection): + +```xml + +``` + +or + +```xml + +``` + +### Example 4 + +Limit the `sayHello` method of `com.foo.BarService` to no more than 10 concurrent executions (or the number of requests that occupy a connection) per client: + +```xml + + + +``` + +or + +```xml + + + +``` + +If both `` and `` are configured with actives, `` takes precedence, see: [Configuration override strategy](../../../reference- manual/config/principle/). + +## Load Balance + +The `loadbalance` attribute of the client side of the configuration service is `leastactive`, and this Loadbalance will call the Provider with the smallest number of concurrency (Consumer-side concurrency). + +```xml + +``` + +or + +```xml + +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/performance/config-connections.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/performance/config-connections.md new file mode 100644 index 000000000000..2013a87eb567 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/performance/config-connections.md @@ -0,0 +1,44 @@ +--- +type: docs +title: "Connection Control" +linkTitle: "Connection Control" +weight: 29 +description: "Connection control between server and client in Dubbo" +--- +## Feature description + +## scenes to be used + +## How to use +### Server connection control + +Limit the number of connections accepted by the server to no more than 10 [^1]: + +```xml + +``` + +or + +```xml + +``` + +### Client connection control + +Limit the client service to use no more than 10 connections [^2]: + +```xml + +``` + +or + +```xml + +``` + +If both `` and `` are configured with connections, `` takes precedence, see: [Configuration override strategy](../../../reference- manual/config/principle/) + +[^1]: Because it is connected to the Server, it is configured on the Provider +[^2]: If it is a long connection, such as the Dubbo protocol, connections indicates the number of long connections established by the service for each provider \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/performance/dump.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/performance/dump.md new file mode 100644 index 000000000000..a0dcb3360f0b --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/performance/dump.md @@ -0,0 +1,55 @@ +--- +type: docs +title: "Export thread stack" +linkTitle: "Export thread stack" +weight: 43 +description: "Automatically export thread stack in Dubbo to preserve the field" +--- +## Feature description +Dubbo automatically exports the thread stack through Jstack to keep the scene, which is convenient for troubleshooting. + +default policy + +* Export path: the user's home directory identified by user.home +* Export Interval: The shortest interval allows an export every 10 minutes +* Export switch: open by default + +## scenes to be used +When the business thread pool is full, we need to know which resources and conditions the threads are waiting for in order to find the bottleneck or abnormal point of the system. + +## How to use +### Export switch control +```properties +# dubbo.properties +dubbo.application.dump.enable=true +``` +```xml + +``` + +```yaml +dubbo: + application: + name: dubbo-springboot-demo-provider + dump-enable: false +``` + + + +### Specify the export path + +```properties +# dubbo.properties +dubbo.application.dump.directory=/tmp +``` + +```xml + +``` + +```yaml +dubbo: + application: + name: dubbo-springboot-demo-provider + dump-directory: /tmp +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/performance/lazy-connect.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/performance/lazy-connect.md new file mode 100644 index 000000000000..b9d6269cb491 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/performance/lazy-connect.md @@ -0,0 +1,18 @@ +--- +type: docs +title: "Delayed Connection" +linkTitle: "Delayed connection" +weight: 30 +description: "Configure delayed connection in Dubbo" +--- +## Feature description + +## scenes to be used +Delayed connections are used to reduce the number of long connections. When a call is initiated, create a persistent connection. + +## How to use +```xml + +``` + +> This configuration is only valid for the dubbo protocol that uses long connections. \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/performance/loadbalance.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/performance/loadbalance.md new file mode 100644 index 000000000000..e56624afc648 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/performance/loadbalance.md @@ -0,0 +1,105 @@ +--- +type: docs +title: "Load Balancing" +linkTitle: "Load Balancing" +weight: 3 +description: "Cluster load balancing strategy provided by Dubbo" +--- + +When cluster load balancing, Dubbo provides a variety of balancing strategies, the default is `random` random calls. + +In terms of specific implementation, Dubbo provides client load balancing, that is, the Consumer uses the load balancing algorithm to determine which Provider instance to submit the request to. + +You can expand the load balancing strategy by yourself, see: [Load Balance Extension](../../../reference-manual/spi/description/load-balance) + +## load balancing strategy +Currently Dubbo has the following built-in load balancing algorithms, which users can directly configure and use: + +| Algorithms | Features | Remarks | +| :-------------------------- | :-------------------- -- | :---------------------------------------------- | +| RandomLoadBalance | Weighted random | Default algorithm, same weight by default | +| RoundRobinLoadBalance | Weighted round-robin | Based on Nginx's smooth weighted round-robin algorithm, the default weight is the same, | +| LeastActiveLoadBalance | Least Active Priority + Weighted Random | Behind it is the idea that those who can do more work | +| ShortestResponseLoadBalance | Shortest Response First + Weighted Random | More focus on response speed | +| ConsistentHashLoadBalance | Consistent Hash | Definite input parameters, definite provider, suitable for stateful requests | + + + +### Random + +* **Weighted random**, set random probability by weight. +* The probability of collision on a section is high, but the greater the call volume, the more uniform the distribution, and the weight is also more uniform after using the probability, which is conducive to dynamically adjusting the provider weight. +* Disadvantages: There is a problem of accumulating requests from slow providers. For example: the second machine is very slow, but it is not hung up. When the request is transferred to the second machine, it is stuck there. Over time, all requests are stuck in the second machine. on stage. + +### RoundRobin +* **Weighted polling**, set the polling ratio according to the weight after the convention, and call the node cyclically +* Disadvantage: There is also the problem of accumulating requests for slow providers. + +During the weighted round-robin process, if the weight of a node is too large, there will be a problem of too concentrated calls within a certain period of time. +For example, ABC three nodes have the following weights: `{A: 3, B: 2, C: 1}` +Then according to the most primitive polling algorithm, the calling process will become: `A A A B B C` + +In this regard, Dubbo has optimized it by referring to Nginx's smooth weighted round-robin algorithm. The calling process can be abstracted into the following table: + +| Pre-round sum weight | Current round winner | Total weight | Post-round weight (winner minus total weight) | +| :------------------ | :------- | :------- | :---------- ----------------- | +| Starting round | \ | \ | `A(0), B(0), C(0)` | +| `A(3), B(2), C(1)` | A | 6 | `A(-3), B(2), C(1)` | +| `A(0), B(4), C(2)` | B | 6 | `A(0), B(-2), C(2)` | +| `A(3), B(0), C(3)` | A | 6 | `A(-3), B(0), C(3)` | +| `A(0), B(2), C(4)` | C | 6 | `A(0), B(2), C(-2)` | +| `A(3), B(4), C(-1)` | B | 6 | `A(3), B(-2), C(-1)` | +| `A(6), B(0), C(0)` | A | 6 | `A(0), B(0), C(0)` | + +We found that after the total weight (3+2+1) rounds, the cycle returns to the starting point, the node traffic is smooth throughout the process, and even in a short period of time, the probability is distributed according to expectations. + +If users have the requirement of weighted polling, they can use this algorithm with confidence. + +### LeastActive +* **Weighted least active call priority**, the lower the active number, the higher the priority call, the same active number will be weighted randomly. The active number refers to the count difference before and after the call (for a specific provider: the number of requests sent - the number of responses returned), which indicates the amount of tasks accumulated by a specific provider. The lower the active number, the stronger the processing capability of the provider. +* Make the slow provider receive fewer requests, because the slower the provider, the greater the count difference before and after the call; relatively, the node with the stronger processing capacity can handle more requests. + +###ShortestResponse +* **Weighted Shortest Response Priority**, in the latest sliding window, the shorter the response time, the higher the priority to call. The same response time is weighted randomly. +* Make providers with faster response times handle more requests. +* Disadvantage: It may cause traffic to be too concentrated on high-performance nodes. + +Response time here = the average response time of a provider within the window time, and the default window time is 30s. + + +###ConsistentHash +* **Consistent Hash**, requests with the same parameters are always sent to the same provider. +* When a certain provider is down, the request originally sent to the provider will be spread to other providers based on the virtual node, and will not cause drastic changes. +* Algorithm see: [Consistent Hashing | WIKIPEDIA](http://en.wikipedia.org/wiki/Consistent_hashing) +* By default only the first parameter Hash, if you want to modify, please configure `` +* 160 virtual nodes are used by default, if you want to modify, please configure `` + +## configuration + +### Server service level + +```xml + +``` + +### Client service level + +```xml + +``` + +### Server method level + +```xml + + + +``` + +### Client method level + +```xml + + + +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/performance/profiler.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/performance/profiler.md new file mode 100644 index 000000000000..f61faea1a520 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/performance/profiler.md @@ -0,0 +1,189 @@ +--- +type: docs +title: "Request time-consuming sampling" +linkTitle: "Request time-consuming sampling" +weight: 1 +description: "Dubbo 3 request time-consuming sampling" +--- + +## Function Description + +The performance sampling function can detect the time consumption of various parts of the Dubbo processing link. When a timeout occurs, `( usageTime / timeout > profilerWarnPercent * 100 )` records the time consumption of calls through logs. + +This function is divided into `simple profiler` and `detail profiler` two modes, where `simple profiler` mode is enabled by default, and `detail profiler` mode is disabled by default. +Compared with the `simple profiler` mode, the `detail profiler` collects more time-consuming processing of each filter, specific time-consuming protocols, etc. +In the `simple profiler` mode, if you find that there is a long time-consuming situation inside the Dubbo framework, you can enable the `detail profiler` mode to better troubleshoot the problem. + +## scenes to be used + +Scenarios that need to collect and analyze the precise time consumption of Dubbo requests, such as service timeouts for unknown reasons, etc. + +## How to use + +`simple profiler` is automatically enabled by default, and for requests whose processing time exceeds 3/4 of the timeout time, the slow call information will be printed out through the log. If you need to enable the `detail profiler` mode or modify the timeout alarm ratio, you can refer to the [performance sampling command](../../../reference-manual/qos/profiler/) document. + +### output example + +#### Log description + +The meaning of each field in the log is as follows: + +``` +[Dubbo-Consumer] execute service interface#method cost actual time-consuming, this invocation almost (maybe already) timeout. Timeout: timeout +invocation context: +request context +thread info: +Start time: start request time (nano time) ++-[ Offset: the start time of the current node; Usage: the total time spent on the current node, the time-consuming ratio of the current node ] Description of the current node + +-[ Offset: the start time of the current node; Usage: the total time spent on the current node, the time-consuming ratio of the current node ] Description of the current node +``` + +For the request time-consuming, here are two examples: + +``` +methodA() { + do something (1) + methodB (2) + do something (3) +} + +methodB() { + do something (4) + methodC (5) + do something (6) +} + +methodC() { + do something (7) +} + ++-[ Offset: 0 ms; Usage: (1) + (2) + (3) ms] execute methodA + +-[ Offset: (1) ms; Usage: (4) + (5) + (6) = (2) ms ] execute methodB + +-[ Offset: (1) + (4) ms; Usage: (7) = (5) ms ] execute methodC + +(1) (2) (3) ... are all time placeholders +``` + +``` +methodA() { + do something (1) + methodB (2) + methodE (3) + do something (4) +} + +methodB() { + do something (5) + methodC (6) + method D (7) + do something (8) +} + +methodC() { + do something (9) +} + +methodD() { + do something (10) +} + +methodE() { + do something (11) +} + ++-[ Offset: 0 ms; Usage: (1) + (2) + (3) + (4) ms] execute methodA + +-[ Offset: (1) ms; Usage: (5) + (6) + (7) + (8) = (2) ms ] execute methodB + +-[ Offset: (1) + (5) ms; Usage: (9) = (6) ms ] execute methodC + +-[ Offset: (1) + (5) + (6) ms; Usage: (10) = (7) ms ] execute methodD + +-[ Offset: (1) + (2) ms; Usage: (11) = (3) ms ] execute methodE + +(1) (2) (3) ... are all time placeholders +``` + +#### simple profiler + +Consumer side: +``` +[19/07/22 07:08:35:035 CST] main WARN proxy.InvokerInvocationHandler: [DUBBO] [Dubbo-Consumer] execute service org.apache.dubbo.samples.api.GreetingsService#sayHi cost 1003.015746 ms, this invocation almost (maybe already) timeout. Timeout: 1000ms +invocation context: +path=org.apache.dubbo.samples.api.GreetingsService; +remote.application=first-dubbo-consumer; +interface=org.apache.dubbo.samples.api.GreetingsService; +version=0.0.0; +timeout=1000; +thread info: +Start time: 285821581299853 ++-[ Offset: 0.000000ms; Usage: 1003.015746ms, 100% ] Receive request. Client invoke begin. ServiceKey: org.apache.dubbo.samples.api.GreetingsService MethodName:sayHi + +-[ Offset: 7.987015ms; Usage: 994.207928ms, 99% ] Invoker invoke. Target Address: xx.xx.xx.xx:20880, dubbo version: 3.0.10-SNAPSHOT, current host: xx.xx.xx. xx +``` + +Provider side: +``` +[19/07/22 07:08:35:035 CST] DubboServerHandler-30.227.64.173:20880-thread-2 WARN filter.ProfilerServerFilter: [DUBBO] [Dubbo-Provider] execute service org.apache.dubbo.samples.api .GreetingsService:0.0.0#sayHi cost 808.494672 ms, this invocation almost (maybe already) timeout. Timeout: 1000ms +client: xx.xx.xx.xx:51604 +invocation context: +input=281; +path=org.apache.dubbo.samples.api.GreetingsService; +remote.application=first-dubbo-consumer; +dubbo=2.0.2; +interface=org.apache.dubbo.samples.api.GreetingsService; +version=0.0.0; +timeout=1000; +thread info: +Start time: 285821754461125 ++-[ Offset: 0.000000ms; Usage: 808.494672ms, 100% ] Receive request. Server invoke begin. + +-[ Offset: 1.030912ms; Usage: 804.236342ms, 99% ] Receive request. Server biz impl invoke begin., dubbo version: 3.0.10-SNAPSHOT, current host: xx.xx.xx.xx +``` + +#### detail profiler + +Consumer side: +``` +[19/07/22 07:10:59:059 CST] main WARN proxy.InvokerInvocationHandler: [DUBBO] [Dubbo-Consumer] execute service org.apache.dubbo.samples.api.GreetingsService#sayHi cost 990.828336 ms, this invocation almost (maybe already) timeout. Timeout: 1000ms +invocation context: +path=org.apache.dubbo.samples.api.GreetingsService; +remote.application=first-dubbo-consumer; +interface=org.apache.dubbo.samples.api.GreetingsService; +version=0.0.0; +timeout=1000; +thread info: +Start time: 285965458479241 ++-[ Offset: 0.000000ms; Usage: 990.828336ms, 100% ] Receive request. Client invoke begin. ServiceKey: org.apache.dubbo.samples.api.GreetingsService MethodName:sayHi + +-[ Offset: 0.852044ms; Usage: 989.899439ms, 99% ] Filter org.apache.dubbo.rpc.cluster.filter.support.ConsumerContextFilter invoke. + +-[ Offset: 1.814858ms; Usage: 988.924876ms, 99% ] Filter org.apache.dubbo.rpc.protocol.dubbo.filter.FutureFilter invoke. + +-[ Offset: 1.853211ms; Usage: 988.877928ms, 99% ] Filter org.apache.dubbo.monitor.support.MonitorClusterFilter invoke. + +-[ Offset: 1.873243ms; Usage: 988.661708ms, 99% ] Filter org.apache.dubbo.rpc.cluster.router.RouterSnapshotFilter invoke. + +-[ Offset: 2.159140ms; Usage: 0.504939ms, 0% ] Router route. + +-[ Offset: 8.125823ms; Usage: 981.748366ms, 99% ] Cluster org.apache.dubbo.rpc.cluster.support.FailoverClusterInvoker invoke. + +-[ Offset: 8.258359ms; Usage: 981.612033ms, 99% ] Invoker invoke. Target Address: xx.xx.xx.xx:20880, dubbo version: 3.0.10-SNAPSHOT, current host: xx.xx.xx. xx +``` + +Provider side: +``` +[19/07/22 07:10:59:059 CST] DubboServerHandler-30.227.64.173:20880-thread-2 WARN filter.ProfilerServerFilter: [DUBBO] [Dubbo-Provider] execute service org.apache.dubbo.samples.api .GreetingsService:0.0.0#sayHi cost 811.017347 ms, this invocation almost (maybe already) timeout. Timeout: 1000ms +client: xx.xx.xx.xx:52019 +invocation context: +input=281; +path=org.apache.dubbo.samples.api.GreetingsService; +remote.application=first-dubbo-consumer; +dubbo=2.0.2; +interface=org.apache.dubbo.samples.api.GreetingsService; +version=0.0.0; +timeout=1000; +thread info: +Start time: 285965612316294 ++-[ Offset: 0.000000ms; Usage: 811.017347ms, 100% ] Receive request. Server invoke begin. + +-[ Offset: 1.096880ms; Usage: 809.916668ms, 99% ] Filter org.apache.dubbo.rpc.filter.EchoFilter invoke. + +-[ Offset: 1.133478ms; Usage: 809.866204ms, 99% ] Filter org.apache.dubbo.rpc.filter.ClassLoaderFilter invoke. + +-[ Offset: 1.157563ms; Usage: 809.838572ms, 99% ] Filter org.apache.dubbo.rpc.filter.GenericFilter invoke. + +-[ Offset: 1.202075ms; Usage: 809.736843ms, 99% ] Filter org.apache.dubbo.rpc.filter.ContextFilter invoke. + +-[ Offset: 1.433193ms; Usage: 809.504401ms, 99% ] Filter org.apache.dubbo.auth.filter.ProviderAuthFilter invoke. + +-[ Offset: 1.470760ms; Usage: 809.464291ms, 99% ] Filter org.apache.dubbo.rpc.filter.ExceptionFilter invoke. + +-[ Offset: 1.489103ms; Usage: 809.440183ms, 99% ] Filter org.apache.dubbo.monitor.support.MonitorFilter invoke. + +-[ Offset: 1.515757ms; Usage: 809.381893ms, 99% ] Filter org.apache.dubbo.rpc.filter.TimeoutFilter invoke. + +-[ Offset: 1.526632ms; Usage: 809.366553ms, 99% ] Filter org.apache.dubbo.rpc.protocol.dubbo.filter.TraceFilter invoke. + +-[ Offset: 1.536964ms; Usage: 809.335907ms, 99% ] Filter org.apache.dubbo.rpc.filter.ClassLoaderCallbackFilter invoke. + +-[ Offset: 1.558545ms; Usage: 804.276436ms, 99% ] Receive request. Server biz impl invoke begin., dubbo version: 3.0.10-SNAPSHOT, current host: xx.xx.xx.xx +``` + +Note: If the log is empty due to the mismatch of the log framework, you can refer to [Log Framework Adaptation and Runtime Management](../../others/logger-management/) to dynamically modify the log output framework. \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/performance/reference-config-cache.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/performance/reference-config-cache.md new file mode 100644 index 000000000000..0228901c1db9 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/performance/reference-config-cache.md @@ -0,0 +1,43 @@ +--- +type: docs +title: "Service Reference Configuration Object Cache" +linkTitle: "Service Reference Configuration Object Cache" +weight: 2 +description: "Cache ReferenceConfig in Dubbo3" +--- +## Feature description + +The `ReferenceConfig` instance is heavy, encapsulates the connection to the registry and the connection to the provider, and needs to be cached. Otherwise repeatedly generating `ReferenceConfig` may cause performance problems and have memory and connection leaks. It's easy to overlook this problem when programming in the API way. + +Therefore, since `2.4.0` version, dubbo provides a simple tool class `ReferenceConfigCache` for caching `ReferenceConfig` instances. +## scenes to be used + +There are scenarios such as gateways that dynamically create subscriptions. Because ReferenceConfig itself is very heavy, it will create a lot of intermediate objects, and proxy itself can be reused, so the properties of this part can be cached through ReferenceConfigCache. + +## How to use +### Eliminate and destroy +Eliminating the `ReferenceConfig` in the Cache will destroy the `ReferenceConfig` and release the corresponding resources. +```java +ReferenceConfig reference = new ReferenceConfig(); +reference.setInterface(XxxService.class); +reference.setVersion("1.0.0"); + … +ReferenceConfigCache cache = ReferenceConfigCache. getCache(); +// The reference object will be cached in the cache.get method, and the ReferenceConfig.get method will be called to start the ReferenceConfig +XxxService xxxService = cache. get(reference); +// Notice! The Cache will hold the ReferenceConfig, do not call the destroy method of the ReferenceConfig outside, causing the ReferenceConfig in the Cache to become invalid! +// Use the xxxService object +xxxService. sayHello(); +``` +```java +ReferenceConfigCache cache = ReferenceConfigCache. getCache(); +cache.destroy(reference); +``` +The default `ReferenceConfigCache` considers `ReferenceConfig` of the same service group, interface, and version to be the same, and caches a copy. That is, the service group, interface, and version are cached keys. + +### Modify strategy +You can modify this strategy to pass a `KeyGenerator` when `ReferenceConfigCache.getCache`. See methods of the `ReferenceConfigCache` class for details. +```java +KeyGenerator keyGenerator = new... +ReferenceConfigCache cache = ReferenceConfigCache. getCache(keyGenerator); +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/performance/result-cache.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/performance/result-cache.md new file mode 100644 index 000000000000..208b13ef2643 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/performance/result-cache.md @@ -0,0 +1,36 @@ +--- +type: docs +title: "Call Result Cache" +linkTitle: "Call result cache" +weight: 7 +description: "Speed up access by caching results" +--- +## Feature description + +#### cache type + +* `lru` deletes redundant caches based on the least recently used principle, keeping the hottest data cached. +* `threadlocal` The current thread cache, such as a page rendering, uses many portals, and each portal needs to check user information. Through thread caching, this redundant access can be reduced. +* `jcache` integrates with [JSR107](http://jcp.org/en/jsr/detail?id=107%27) to bridge various cache implementations. + +Cache Type Extensible [Cache Extensions](../../../reference-manual/spi/description/cache) + +About [sample code](https://github.com/apache/dubbo-samples/tree/master/2-advanced/dubbo-samples-cache) + +## scenes to be used + +The result cache is used to speed up access to popular data. Dubbo provides a declarative cache to reduce the workload of users adding cache. + +## How to use + +```xml + +``` + +or: + +```xml + + + +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/performance/router-snapshot.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/performance/router-snapshot.md new file mode 100644 index 000000000000..f82f1b76a39d --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/performance/router-snapshot.md @@ -0,0 +1,79 @@ +--- +type: docs +title: "Routing Status Collection" +linkTitle: "Routing Status Collection" +weight: 2 +description: "routing status collection" +--- +## Function Description +## scenes to be used + +Many of Dubbo's traffic management capabilities are implemented based on Router. In a production environment, if traffic results do not meet expectations, you can use the routing status command to check the routing status to locate possible problems. + +## How to use + +### View route cache status + +When Dubbo receives the address change, it will push the address information to all `Routers`, and these `Routers` can calculate the routing packets in advance at this stage and cache them to avoid the need to traverse all provider calculations when calling grouping parameters. +The `StateRouter` introduced in Dubbo 3 provides the ability to obtain the status of each route in real time through the qos command tool. + +The operation and maintenance personnel can obtain the status of the route through the `getRouterSnapshot` command. For specific commands, please refer to the [getRouterSnapshot command](../../../reference-manual/qos/router-snapshot/#getroutersnapshot-command) document. + +**Note: This feature only supports `StateRoute`, and `StateRouter` needs to implement the `doBuildSnapshot` interface based on `AbstractStateRouter`. ** + +### View the route calculation result of the actual request + +By default in Dubbo 3, the node status of route calculation is printed when the route filter is empty. Operation and maintenance personnel can judge whether the calculation result of each route meets expectations through logs. + +#### Log format + +``` +No provider available after route for the service service from registry registration center address on the consumer consumer IP using the dubbo version 3.0.7. Router snapshot is below: +[ Parent (Input: Number of input addresses of the current node) (Current Node Output: Number of calculation results of the current node) (Chain Node Output: Number of intersection results of the current node and subsequent nodes) ] Input: Examples of input addresses (up to 5 are displayed) -> Chain Node Output: Example of addresses output by the current node (up to 5 are displayed) + [Route name (Input: number of input addresses of the current node) (Current Node Output: number of calculation results of the current node) (Chain Node Output: number of intersection results of the current node and subsequent nodes) Router message: routing log] Current Node Output: current node Example of addresses output (up to 5 displayed) + [routing name (Input: current node input address number) (Current Node Output: current node calculation result number) (Chain Node Output: current node and subsequent node intersection result number) Router message: routing log] Current Node Output: current input Examples of addresses for (show up to 5) +``` + +#### Notice: +- The routing log needs to rely on the routing implementation to judge the `needToPrintMessage` parameter, and write the `messageHolder` routing log when needed +- Since the result of multi-level routing is the intersection of the results, the calculation result of the current node may be empty after the intersection with the subsequent level + +#### Log example + +``` +[19/07/22 07:42:46:046 CST] main WARN cluster.RouterChain: [DUBBO] No provider available after route for the service org.apache.dubbo.samples.governance.api.DemoService from registry 30.227.64.173 on the consumer 30.227.64.173 using the dubbo version 3.0.7. Router snapshot is below: +[ Parent (Input: 2) (Current Node Output: 2) (Chain Node Output: 0) ] Input: 30.227.64.173:20881,30.227.64.173:20880 -> Chain Node Output: Empty + [ MockInvokersSelector (Input: 2) (Current Node Output: 2) (Chain Node Output: 0) Router message: invocation.need.mock not set. Return normal Invokers. ] Current Node Output: 30.227.64.173:20881,30.223.64.17 :20880 + [ StandardMeshRuleRouter (Input: 2) (Current Node Output: 2) (Chain Node Output: 0) Router message: MeshRuleCache has not been built. Skip route. ] Current Node Output: 30.227.64.173:20881,30.227.624.1803: + [ TagStateRouter (Input: 2) (Current Node Output: 0) (Chain Node Output: 0) Router message: FAILOVER: return all Providers without any tags ] Current Node Output: Empty, dubbo version: 3.0.7, current host: 30.227 .64.173 +``` + +#### Open route full sampling + +In some special cases, the request may be called to the wrong server, but because the address selection is not empty, the process information of the route cannot be seen. At this time, you can [Enable full route sampling through qos](../../. ./reference-manual/qos/router-snapshot/). The latest routing snapshot can be obtained remotely through the `getRecentRouterSnapshot` command of qos. + +``` +dubbo>getRecentRouterSnapshot +1658224330156 - Router snapshot service com.dubbo.dubbointegration.BackendService from registry 172.18.111.184 on the consumer 172.18.111.184 using the dubbo version 3.0.9 is below: +[ Parent (Input: 2) (Current Node Output: 2) (Chain Node Output: 2) ] Input: 172.18.111.187:20880,172.18.111.183:20880 -> Chain Node Output: 172.18.111.187:20880.3172.18 :20880 + [ MockInvokersSelector (Input: 2) (Current Node Output: 2) (Chain Node Output: 2) Router message: invocation.need.mock not set. Return normal Invokers. ] Current Node Output: 172.18.111.187:20880,172.183.111. :20880 + [ StandardMeshRuleRouter (Input: 2) (Current Node Output: 2) (Chain Node Output: 2) Router message: MeshRuleCache has not been built. Skip route. ] Current Node Output: 172.18.111.187:20880,172.1803:1121.88 + [ TagStateRouter (Input: 2) (Current Node Output: 2) (Chain Node Output: 2) Router message: Disable Tag Router. Reason: tagRouterRule is invalid or disabled ] Current Node Output: 172.18.111.187:20880,172.183.111. 20880 + [ ServiceStateRouter (Input: 2) (Current Node Output: 2) (Chain Node Output: 2) Router message: Directly return. Reason: Invokers from previous router is empty or conditionRouters is empty. ] Current Node Output: 172.18.111.187:20880 ,172.18.111.183:20880 + [ AppStateRouter (Input: 2) (Current Node Output: 2) (Chain Node Output: 2) Router message: Directly return. Reason: Invokers from previous router is empty or conditionRouters is empty. ] Current Node Output: 172.18.111.187:20880 ,172.18.111.183:20880 + +1658224330156 - Router snapshot service com.dubbo.dubbointegration.BackendService from registry 172.18.111.184 on the consumer 172.18.111.184 using the dubbo version 3.0.9 is below: +[ Parent (Input: 2) (Current Node Output: 2) (Chain Node Output: 2) ] Input: 172.18.111.187:20880,172.18.111.183:20880 -> Chain Node Output: 172.18.111.187:20880.3172.18 :20880 + [ MockInvokersSelector (Input: 2) (Current Node Output: 2) (Chain Node Output: 2) Router message: invocation.need.mock not set. Return normal Invokers. ] Current Node Output: 172.18.111.187:20880,172.183.111. :20880 + [ StandardMeshRuleRouter (Input: 2) (Current Node Output: 2) (Chain Node Output: 2) Router message: MeshRuleCache has not been built. Skip route. ] Current Node Output: 172.18.111.187:20880,172.1803:1121.88 + [ TagStateRouter (Input: 2) (Current Node Output: 2) (Chain Node Output: 2) Router message: Disable Tag Router. Reason: tagRouterRule is invalid or disabled ] Current Node Output: 172.18.111.187:20880,172.183.111. 20880 + [ ServiceStateRouter (Input: 2) (Current Node Output: 2) (Chain Node Output: 2) Router message: Directly return. Reason: Invokers from previous router is empty or conditionRouters is empty. ] Current Node Output: 172.18.111.187:20880 ,172.18.111.183:20880 + [ AppStateRouter (Input: 2) (Current Node Output: 2) (Chain Node Output: 2) Router message: Directly return. Reason: Invokers from previous router is empty or conditionRouters is empty. ] Current Node Output: 172.18.111.187:20880 ,172.18.111.183:20880 + +··· + +dubbo> +``` + +#### Notice: +If the log is empty due to the mismatch of the log framework, you can refer to [Log Framework Adaptation and Runtime Management](../../others/logger-management/) to dynamically modify the log output framework. \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/performance/serialization.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/performance/serialization.md new file mode 100644 index 000000000000..b9cde28b6c66 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/performance/serialization.md @@ -0,0 +1,241 @@ +--- +type: docs +title: "Kryo and FST Serialization" +linkTitle: "Kryo and FST serialization" +weight: 46 +description: "Using efficient Java serialization (Kryo and FST) in Dubbo" +--- + +## Table of contents + +* Serialization talk +* Enable Kryo and FST +* Register the class to be serialized +* No parameter constructor and Serializable interface +* Serialization performance analysis and testing + * test environment + * Test script + * Comparison of byte sizes generated by different serializations in Dubbo RPC + * Comparison of response time and throughput of different serializations in Dubbo RPC +* future + + +## Serialization talk + +dubbo RPC is the core high-performance, high-throughput remote call method in the dubbo system. I like to call it a multiplexed TCP long connection call. Simply put: + +* Long connection: avoiding the need to create a new TCP connection each time, improving the response speed of the call +* Multiplexing: A single TCP connection can alternately transmit multiple request and response messages, reducing the waiting idle time of the connection, thereby reducing the number of network connections under the same concurrent number and improving system throughput. + +dubbo RPC is mainly used for remote calls between two dubbo systems, especially suitable for Internet scenarios with high concurrency and small data. + +Serialization also plays a vital role in the response speed, throughput, and network bandwidth consumption of remote calls, and is one of the most critical factors for us to improve the performance of distributed systems. + +In dubbo RPC, multiple serialization methods are supported at the same time, for example: + +1. Dubbo serialization: Ali has not yet developed a mature and efficient java serialization implementation, and Ali does not recommend using it in a production environment +1. Hessian2 serialization: Hessian is a cross-language efficient binary serialization method. But here is actually not the original hessian2 serialization, but the hessian lite modified by Ali, which is the default serialization method enabled by dubbo RPC +1. JSON serialization: There are currently two implementations, one is to use Ali's fastjson library, and the other is to use the simple json library implemented by dubbo, but the implementation is not particularly mature, and the text sequence of json The serialization performance is generally not as good as the above two binary serializations. +1. Java serialization: It is mainly implemented by using the Java serialization that comes with the JDK, and the performance is not ideal. + +In general, the performance of the four main serialization methods decreases from top to bottom. For dubbo RPC, which pursues high-performance remote calls, there are actually only two high-efficiency serialization methods, 1 and 2, that are more suitable, and the first dubbo serialization is still immature, so only 2 is actually available. So dubbo RPC uses hessian2 serialization by default. + +But hessian is an older serialization implementation, and it is cross-language, so it is not optimized for java alone. In fact, dubbo RPC is a remote call from Java to Java. In fact, there is no need to adopt cross-language serialization (of course, cross-language serialization is certainly not excluded). + +In recent years, various new efficient serialization methods have emerged one after another, constantly refreshing the upper limit of serialization performance, the most typical ones include: + +* Specifically for the Java language: Kryo, FST, etc. +* Cross-language: Protostuff, ProtoBuf, Thrift, Avro, MsgPack, etc. + +The performance of most of these serialization methods is significantly better than hessian2 (even including the immature dubbo serialization). + +In view of this, we introduce two efficient Java serialization implementations, Kryo and FST, for dubbo to gradually replace hessian2. + +Among them, Kryo is a very mature serialization implementation, which has been widely used in Twitter, Groupon, Yahoo and many famous open source projects (such as Hive and Storm). While FST is a newer serialization implementation, it still lacks enough mature use cases, but I think it is still very promising. + +In production-oriented applications, I recommend Kryo as the preferred choice for now. + +## Enable Kryo and FST + +Using Kryo and FST is very simple, just add the corresponding dependencies first: +More plugins: [Dubbo SPI Extensions](https://dubbo.apache.org/zh/release/dubbo-spi-extensions) + +```xml + + org.apache.dubbo.extensions + dubbo-serialization-kryo + 1.0.0 + +``` + +```xml + + org.apache.dubbo.extensions + dubbo-serialization-fst + 1.0.0 + +``` + +Then add an attribute in the XML configuration of dubbo RPC: + +```xml + +``` + +```xml + +``` + +## Register the class to be serialized + +To make Kryo and FST fully perform with high performance, it is best to register those classes that need to be serialized in the dubbo system. For example, we can implement the following callback interface: + +```java +public class SerializationOptimizerImpl implements SerializationOptimizer { + + public Collection getSerializableClasses() { + List classes = new LinkedList(); + classes.add(BidRequest.class); + classes. add(BidResponse. class); + classes. add(Device. class); + classes. add(Geo. class); + classes. add(Impression. class); + classes.add(SeatBid.class); + return classes; + } +} +``` + +Then add in XML configuration: + +```xml + +``` + +After registering these classes, serialization performance may be greatly improved, especially for small numbers of nested objects. + +Of course, when serializing a class, many classes may be cascaded, such as Java collection classes. In response to this situation, we have automatically registered common classes in the JDK, so you don't need to register them repeatedly (of course, there is no effect if you register repeatedly), including: + +``` +Gregorian Calendar +InvocationHandler +BigDecimal +BigInteger +pattern +BitSet +URIs +UUID +HashMap +ArrayList +LinkedList +HashSet +TreeSet +Hashtable +date +Calendar +ConcurrentHashMap +SimpleDateFormat +vector +BitSet +StringBuffer +String Builder +object +Object[] +String[] +byte[] +char[] +int[] +float[] +double[] +``` + +Since registering classes to be serialized is only for performance optimization purposes, it doesn't matter if you forget to register some classes. In fact, even without registering any classes, the performance of Kryo and FST is generally better than that of hessian and dubbo serialization. + +> Of course, someone may ask why not use configuration files to register these classes? This is because there are often a large number of classes to be registered, resulting in lengthy configuration files; and without good IDE support, writing and refactoring configuration files are much more troublesome than java classes; finally, these registered classes are generally It is not necessary to make dynamic modifications after the project is compiled and packaged. + +> In addition, some people will also think that manually registering the serialized class is a relatively cumbersome work, can it be marked with annotation, and then the system will automatically discover and register. But the limitation of annotation here is that it can only be used to mark classes that you can modify, and many classes referenced in serialization are likely to be things that you cannot modify (such as third-party libraries or JDK system classes or classes of other projects ). In addition, adding annotation after all slightly "polluted" the code, making the application code a little bit more dependent on the framework. + +> In addition to annotation, we can also consider other ways to automatically register serialized classes, such as scanning the class path, automatically discovering classes that implement the Serializable interface (even including Externalizable) and registering them. Of course, we know that there may be a lot of Serializable classes on the classpath, so we can also consider using package prefixes to limit the scanning range to a certain extent. + +> Of course, in the automatic registration mechanism, it is especially necessary to consider how to ensure that both the service provider and the consumer register classes in the same order (or ID) to avoid misalignment. After all, the number of classes that can be discovered and registered at both ends may be the same. are different. + +## No parameter constructor and Serializable interface + +If the class to be serialized does not contain a parameterless constructor, the performance of Kryo's serialization will be greatly reduced, because at this time we will use Java's serialization to transparently replace Kryo's serialization at the bottom layer. Therefore, it is a best practice to add a no-argument constructor for each serialized class as much as possible (of course, if a java class does not customize a constructor, it will have a no-argument constructor by default). + +In addition, Kryo and FST do not require the serialized class to implement the Serializable interface, but we still recommend that every serialized class implement it, because this can maintain compatibility with Java serialization and dubbo serialization. In addition It also makes it possible for us to adopt some of the above automatic registration mechanisms in the future. + +## Serialization performance analysis and testing + +In this article, we mainly discuss serialization, but when doing performance analysis and testing, we do not deal with each serialization method separately, but put them in dubbo RPC for comparison, because this is more realistic. + +### test environment + +Roughly as follows: + +* Two independent servers +* Quad-core Intel(R) Xeon(R) CPU E5-2603 0 @ 1.80GHz +* 8G memory +* The network between virtual machines passes through a 100M switch +* CentOS 5 +* JDK 7 +* Tomcat 7 +* JVM parameters -server -Xms1g -Xmx1g -XX:PermSize=64M -XX:+UseConcMarkSweepGC + +Of course, the test environment is limited, so the current test results may not be very authoritative and representative. + +### Test script + +Keeping close to dubbo's own benchmarks: + +10 concurrent clients continuously making requests: + +* Pass in a nested complex object (but the amount of individual data is small), do not do any processing, and return as it is +* Pass in 50K strings, do not do any processing, and return as they are (TODO: the result has not been listed yet) + +Run a 5-minute performance test. (Quoting dubbo's own test considerations: "It mainly examines the performance of serialization and network IO, so the server does not have any business logic. The reason for taking 10 concurrency is to consider that the rpc protocol may have a high CPU usage rate under high concurrency. to the bottleneck.") + +### Comparison of byte sizes generated by different serializations in Dubbo RPC + +The size of the number of bytes generated by serialization is a relatively deterministic indicator, which determines the network transmission time and bandwidth occupation of the remote call. + +The results for complex objects are as follows (lower numbers are better): + +| Serialization Implementation | Request Bytes | Response Bytes | +| ----------- | ------------- | ------------- | +| Kryo | 272 | 90 | +| FST | 288 | 96 | +| Dubbo Serialization | 430 | 186 | +| Hessian | 546 | 329 | +| FastJson | 461 | 218 | +| Json | 657 | 409 | +| Java Serialization | 963 | 630 | + + +### Comparison of different serialization response time and throughput in Dubbo RPC + +| Remote call method | Average response time | Average TPS (transactions per second) | +| ----------- | ------------- | ------------- | +| REST: Jetty + JSON | 7.806 | 1280 | +| REST: Jetty + JSON + GZIP | TODO | TODO | +| REST: Jetty + XML | TODO | TODO | +| REST: Jetty + XML + GZIP | TODO | TODO | +| REST: Tomcat + JSON | 2.082 | 4796 | +| REST: Netty + JSON | 2.182 | 4576 | +| Dubbo: FST | 1.211 | 8244 | +| Dubbo: kyro | 1.182 | 8444 | +| Dubbo: dubbo serialization | 1.43 | 6982 | +| Dubbo: hessian2 | 1.49 | 6701 | +| Dubbo: fastjson | 1.572 | 6352 | + +![rt](/imgs/user/rt.png) + +![tps](/imgs/user/tps.png) + +### Test Summary + +As far as the current results are concerned, we can see that Kryo and FST have significantly improved compared to the original serialization method in Dubbo RPC, regardless of the size of generated bytes, average response time and average TPS. + +## future + +In the future, when Kryo or FST is mature enough in dubbo, we will probably change the default serialization of dubbo RPC from hessian2 to one of them. \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/performance/simplify-registry-data.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/performance/simplify-registry-data.md new file mode 100644 index 000000000000..7d74c8e81a8e --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/performance/simplify-registry-data.md @@ -0,0 +1,255 @@ +--- +type: docs +title: "Registration Information Simplified" +linkTitle: "Registration Information Simplified" +weight: 3 +description: "Learn about dubbo3 to reduce the registration data of services on the registry" +--- + +## Feature description + +There are nearly [30 configuration items](/zh/docs/references/xml/dubbo-parameter) in the service configuration items in Dubbo provider. Excluding the need for registry service governance, a large part of configuration items are used by the provider itself and do not need to be transparently passed to consumers. This part of data does not need to enter the registry, but only needs to be stored persistently in the form of key-value. + +The configuration items in Dubbo consumer also have [20+ configuration items](/zh/docs/references/xml/dubbo-consumer). In the registration center, only a small amount of configuration such as application, version, group, ip, and dubbo version need to be concerned in the service consumer list, and other configurations can also be stored persistently in the form of key-value. +These data are registered into the registration center in the dimension of service, which leads to the expansion of the data volume, which in turn leads to an increase in the network overhead of the registration center (such as zookeeper) and a decrease in performance. + +#### Design goals and objectives +It is desirable to simplify the number of provider and consumer configurations that go into the registry. +It is expected that some configuration items will be stored in other forms. These configuration items need to be satisfied: not on the service call link, and these configuration items are not on the core link of the registration center (service query, service list). + +#### Configuration + +Simplify the configuration of the registry, only supported in versions after 2.7. +After enabling provider or consumer to simplify the configuration, the default reserved configuration items are as follows: + +provider: + +| 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 | | +| DUBBO_VERSION_KEY | dubbo | | +| RELEASE_KEY | release | | +| SIDE_KEY | side | | + + +consumer: + +| Constant Key | Key | remark | +| ------ | ------ | ------ | +| APPLICATION_KEY | application | | +| VERSION_KEY | version | | +| GROUP_KEY | group | | +| DUBBO_VERSION_KEY | dubbo | | + +Constant Key represents a field from the class org.apache.dubbo.common.Constants. + +The following introduces several commonly used methods. All samples, you can view [sample-2.7](https://github.com/dubbo/dubbo-samples/tree/master) + +## scenes to be used + +A large amount of data leads to an increase in the network overhead of the registration center and a decrease in performance. + +## How to use + +**EXISTING FUNCTIONALITY sample** A simple demonstration of the current state of affairs. Through this demonstration, analyze why simplified configuration is needed. + +Refer to the sample subproject: dubbo-samples-simplified-registry/dubbo-samples-simplified-registry-nosimple (before running the sample, first run ZKClean to clean up the configuration items) + +##### dubbo-provider.xml configuration: + +``` + + + + +``` + +After starting the provider's main method, view the content of the zookeeper leaf node (path: /dubbo/org.apache.dubbo.samples.simplified.registry.nosimple.api.DemoService/providers directory) as follows: + +``` +dubbo%3A%2F%2F30.5.124.158%3A20880%2Forg.apache.dubbo.samples.simplified.registry.nosimple.api.DemoService +%3Fanyhost%3Dtrue%26application%3Dsimplified-registry-xml-provider%26async%3Dtrue%26dubbo%3D +2.0.2%26executes%3D4500%26generic%3Dfalse%26group%3Ddubbo-simple%26interface%3D +org.apache.dubbo.samples.simplified.registry.nosimple.api.DemoService%26methods%3D +sayHello%26owner%3Dvict%26pid%3D2767%26retries%3D7%26revision%3D1.2.3%26side%3D +provider%26timeout%3D5300%26timestamp%3D1542361152795%26valid%3Dtrue%26version%3D1.2.3 +``` + +You can see that there are: `executes`, `retries`, `owner`, `timeout`. But not all these fields need to be passed to dubbo ops or dubbo consumer. Similarly, the consumer also has this problem, which can be viewed by starting the main method of the consumer in the example. + + + +### Method 1. Configure dubbo.properties + +The sample is under the dubbo-samples-simplified-registry/dubbo-samples-simplified-registry-xml project (before running the sample, first run ZKClean to clean up the configuration items) + +##### dubbo.properties + +```properties +dubbo.registry.simplified=true +dubbo.registry.extra-keys=retries,owner +``` +Compared with the **existing function sample** above, in the above sample, the four configuration items of executes, retries, owner, and timeout have all entered the registration center. But this example is not, the configuration is divided into: + +* Configuration: dubbo.registry.simplified=true, by default, timeout is in the default configuration item list, so it will still enter the registry; +* Configuration: dubbo.registry.extra-keys=retries,owner, so retries, owner will also enter the registry. + +configuration type: +- provider side configuration +- consumer side configuration + +#### Provider side configuration: + +```xml + + + + + + + + +``` +Get the value of the leaf node of zookeeper: +``` +dubbo%3A%2F%2F30.5.124.149%3A20880%2Forg.apache.dubbo.samples.simplified.registry.nosimple.api.DemoService%3F +application%3Dsimplified-registry-xml-provider%26dubbo%3D2.0.2%26group%3Ddubbo-simple%26owner%3D +vict%26retries%3D7%26timeout%3D5300%26timestamp%3D1542594503305%26version%3D1.2.3 +``` + +#### consumer side configuration +* Configuration: dubbo.registry.simplified=true +* Default: application, version, group, and dubbo are in the default configuration item list, so they will still enter the registration center. +```xml + + + + + + + + + + +``` +Get the value of the leaf node of zookeeper: +``` +consumer%3A%2F%2F30.5.124.149%2Forg.apache.dubbo.samples.simplified.registry.nosimple.api.DemoService%3F +actives%3D6%26application%3Dsimplified-registry-xml-consumer%26category%3D +consumers%26check%3Dfalse%26dubbo%3D2.0.2%26group%3Ddubbo-simple%26owner%3Dvvv%26version%3D1.2.3 +``` + +### Method 2. Configuration declaration spring bean + +The sample is under the dubbo-samples-simplified-registry/dubbo-samples-simplified-registry-annotation project (before running the sample, first run ZKClean to clean up the configuration items) + +The effect of dubbo.properties in the above sample is the same. + +* Default: timeout is in the default configuration item list, so it will still enter the registration center; +* Configuration: retries, owner enter the registry as an additional key, so retries, owner will also enter the registry. + +configuration type: + +-Provider configuration +-Consumer configuration + +#### Provider configuration + +##### private side bean configuration: +```java +// Equivalent to dubbo.properties configuration, configured in the form of @Bean +@Bean +public RegistryConfig registryConfig() { + RegistryConfig registryConfig = new RegistryConfig(); + registryConfig.setAddress("zookeeper://127.0.0.1:2181"); + registryConfig.setSimplified(true); + registryConfig.setExtraKeys("retries,owner"); + return registryConfig; +} +``` + +```java +// expose the service +@Service(version = "1.1.8", group = "d-test", executes = 4500, retries = 7, owner = "victanno", timeout = 5300) +public class AnnotationServiceImpl implements AnnotationService { + @Override + public String sayHello(String name) { + System.out.println("async provider received: " + name); + return "annotation: hello, " + name; + } +} +``` +#### Consumer configuration + +It is the same as **consumer side configuration** in the sample above. + +Default: application, version, group, and dubbo are in the default configuration item list, so they will still enter the registration center. + +##### consumer side bean configuration: +```java +@Bean +public RegistryConfig registryConfig() { + RegistryConfig registryConfig = new RegistryConfig(); + registryConfig.setAddress("zookeeper://127.0.0.1:2181"); + registryConfig.setSimplified(true); + return registryConfig; + } +``` + +Consumer Services: + +```java +@Component("annotationAction") +public class AnnotationAction { + + @Reference(version = "1.1.8", group = "d-test", owner = "vvvanno", retries = 4, actives = 6, timeout = 4500) + private AnnotationService annotationService; + public String doSayHello(String name) { + return annotationService.sayHello(name); + } +} +``` +#### Notice: +If there are both provider and consumer in an application, the configuration needs to be merged into: +```java +@Bean +public RegistryConfig registryConfig() { + RegistryConfig registryConfig = new RegistryConfig(); + registryConfig.setAddress("zookeeper://127.0.0.1:2181"); + registryConfig.setSimplified(true); + //Only valid for provider + registryConfig.setExtraKeys("retries,owner"); + return registryConfig; +} +``` + +#### hint: + +This version also retains a large number of configuration items, and in the next version, all configuration items will be gradually deleted. \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/performance/stickiness.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/performance/stickiness.md new file mode 100644 index 000000000000..9b35f4b2cbf3 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/performance/stickiness.md @@ -0,0 +1,26 @@ +--- +type: docs +title: "Stick Connection" +linkTitle: "Stick connection" +weight: 31 +description: "Configure sticky connections for stateful services" +--- +## Feature description + +## scenes to be used +Sticky connections are used for stateful services, so that the client always initiates calls to the same provider as much as possible, unless the provider hangs up and connects to another one. + +Sticky connection will automatically enable [Delayed Connection](../lazy-connect) to reduce the number of long connections. + +## How to use +```xml + +``` + +Dubbo supports method-level sticky connections, if you want more fine-grained control, you can also configure it like this. + +```xml + + + +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/performance/support-graalvm.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/performance/support-graalvm.md new file mode 100644 index 000000000000..7ce8373143f1 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/performance/support-graalvm.md @@ -0,0 +1,213 @@ +--- +type: docs +title: "Support Graal VM" +linkTitle: "Support Graal VM" +weight: 40 +description: "" +--- + +dubbo3.0 supports native-image document + +## Feature description +This document will introduce the process of connecting dubbo3.0 project to GraalVM and compiling native-image into binary. + +More information about GraalVm can be read https://www.graalvm.org/docs/getting-started/container-images/ this document. + +## scenes to be used + +## How to use +Before compiling our dubbo project, we need to make sure that we are based on the graalVm environment. + +### Install GraalVM +Go to https://www.graalvm.org/ official website and select the latest version to install according to your own system: + +![](/imgs/blog/dubbo3.0-graalvm-support/graalvmgw.jpg) + +After the installation is complete, modify the path to configure JAVA_HOME, and check the local jdk after it takes effect, you can see the following: + +![](/imgs/blog/dubbo3.0-graalvm-support/graalvm_env.jpg) +Here we use GraalVM based on jdk1.8 version. + +- To install native-image, just execute gu install native-image. + +1. Pull the dubbo code and switch to the [apache:3.0](https://github.com/apache/dubbo) branch. +2. Manually execute the generated SPI code. + +Since the current compilation of native-image does not support code dynamic generation and compilation, the part related to code dynamic generation needs to be generated manually. Here is a tool function: + +![](/imgs/blog/dubbo3.0-graalvm-support/code_generator.jpg) +Execute CodeGenerator to generate SPI code under the dubbo-native module. + +### Execute install in the root directory + +``` +MacdeMacBook-pro-3:incubator-dubbo mac$ pwd + +/Users/mac/Documents/Mi/project/incubator-dubbo + +MacdeMacBook-pro-3:incubator-dubbo mac$ mvn clean package install -Dmaven.test.skip=true +``` + +### Compile the demo project + +Here we provide a sample project that can be directly compiled, dubbo-demo/dubbo-demo-native. After the above steps are installed, first go to the provider of dubbo-demo-native and execute native-image compilation: + +``` + mvn clean package -P native -Dmaven.test.skip=true +``` + +Here, since we have introduced the native-image plug-in in maven, the plug-in can be executed directly -P native. + +![](/imgs/blog/dubbo3.0-graalvm-support/native_image_build.jpg) +After the compilation is successful, you can see the generated binary file under the target, start a zookeeper locally, and execute the binary directly. It can be seen that the startup is successful as follows: + +![](/imgs/blog/dubbo3.0-graalvm-support/run_provider.jpg) +The consumer side also executes compilation, and a binary file is also generated under the consumer target: demo-native-consumer. Execute this binary and you can see the result of the call as follows: + +![](/imgs/blog/dubbo3.0-graalvm-support/run_consumer.jpg) +### Specific steps + +In fact, we have done some work under this demo to ensure that the project can be compiled and executed. There are mainly the following steps + +- Introduce dubbo-native dependency + +``` + + + org.apache.dubbo + + dubbo-native + + ${project.version} + + +``` + +Under this module is the SPI code we generated. + +- Introduce native-image plugin + +``` + + + org.graalvm.nativeimage + + native-image-maven-plugin + + 21.0.0.2 + + + + + + + + native-image + + + + package + + + + + + + + false + + demo-native-provider + + org.apache.dubbo.demo.graalvm.provider.Application + + + + --no-fallback + + --initialize-at-build-time=org.slf4j.MDC + + --initialize-at-build-time=org.slf4j.LoggerFactory + + --initialize-at-build-time=org.slf4j.impl.StaticLoggerBinder + + --initialize-at-build-time=org.apache.log4j.helpers.Loader + + --initialize-at-build-time=org.apache.log4j.Logger + + --initialize-at-build-time=org.apache.log4j.helpers.LogLog + + --initialize-at-build-time=org.apache.log4j.LogManager + + --initialize-at-build-time=org.apache.log4j.spi.LoggingEvent + + --initialize-at-build-time=org.slf4j.impl.Log4jLoggerFactory + + --initialize-at-build-time=org.slf4j.impl.Log4jLoggerAdapter + + --initialize-at-build-time=org.eclipse.collections.api.factory.Sets + + --initialize-at-run-time=io.netty.channel.epoll.Epoll + + --initialize-at-run-time=io.netty.channel.epoll.Native + + --initialize-at-run-time=io.netty.channel.epoll.EpollEventLoop + + --initialize-at-run-time=io.netty.channel.epoll.EpollEventArray + + --initialize-at-run-time=io.netty.channel.DefaultFileRegion + + --initialize-at-run-time=io.netty.channel.kqueue.KQueueEventArray + + --initialize-at-run-time=io.netty.channel.kqueue.KQueueEventLoop + + --initialize-at-run-time=io.netty.channel.kqueue.Native + + --initialize-at-run-time=io.netty.channel.unix.Errors + + --initialize-at-run-time=io.netty.channel.unix.IovArray + + --initialize-at-run-time=io.netty.channel.unix.Limits + + --initialize-at-run-time=io.netty.util.internal.logging.Log4JLogger + + --initialize-at-run-time=io.netty.channel.unix.Socket + + --initialize-at-run-time=io.netty.channel.ChannelHandlerMask + + + + --report-unsupported-elements-at-runtime + + --allow-incomplete-classpath + + --enable-url-protocols=http + + -H:+ReportExceptionStackTraces + + + + + + +``` + +It defines the name of the generated image and some parameters for building the image. + +- mount native-image-agent + +Since we need to specify some reflection, JNI and other classes first, we need to use the agent to run it in a normal way to generate information in the form of json for these classes. + +In the startup parameters add: + +``` +-agentlib:native-image-agent=config-output-dir=/tmp/config/,config-write-period-secs=300,config-write-initial-delay-secs=5 +``` + +Start in the normal way, create a folder META-INF.native-image under the resources of the project, and paste the files generated in the local directory: + +![](/imgs/blog/dubbo3.0-graalvm-support/resources.jpg) +(There may be missing class information that is not generated, which needs to be added manually according to the error message when compiling or running.) + + + +** After completing the above steps, the project can be compiled. ** \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/performance/threading-model/_index.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/performance/threading-model/_index.md new file mode 100755 index 000000000000..63b5690e4d23 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/performance/threading-model/_index.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "Threading Model" +linkTitle: "Threading Model" +weight: 1 +--- \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/performance/threading-model/consumer.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/performance/threading-model/consumer.md new file mode 100644 index 000000000000..6a9d13466199 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/performance/threading-model/consumer.md @@ -0,0 +1,45 @@ +--- +type: docs +title: "Consumer Thread Model" +linkTitle: "Consumer thread model" +weight: 2 +description: "Dubbo Consumer Thread Pool Model Usage" +--- + +The 2.7.5 version has fully optimized the entire call link. According to the pressure test results, the overall QPS performance has been improved by nearly 30%, and the memory allocation overhead during the call process has also been reduced. One of the design points worth mentioning is that 2.7.5 introduces the concept of Servicerepository, which generates ServiceDescriptor and MethodDescriptor in advance in the service registration phase to reduce resource consumption caused by calculating the original information of the Service in the RPC call phase. + +## Consumer thread pool model optimization + +For Dubbo applications before version 2.7.5, especially some consumer-side applications, when faced with high-traffic scenarios that need to consume a large number of services and have a relatively large number of concurrency (typically such as gateway scenarios), the number of threads on the consumer side is often over-allocated. There are a lot of problems, for specific discussion, please refer to [Need a limited Threadpool in consumer side #2013](https://github.com/apache/dubbo/issues/2013) + +The improved consumer-side thread pool model solves this problem well by reusing the blocked threads on the business side. + +## The old thread pool model + +![Consumer thread pool.png](/imgs/user/consumer-threadpool0.png) + +Let's focus on the Consumer part: + +1. The business thread sends a request and gets a Future instance. +2. The business thread then calls future.get to block and wait for the business result to return. +3. When the business data is returned, it will be deserialized by the independent consumer-side thread pool, and future.set will be called to return the deserialized business results. +4. The business thread returns directly after getting the result + + + +## The thread pool model introduced in version 2.7.5 + +![Consumer thread pool new.png](/imgs/user/consumer-threadpool1.png) + +1. The business thread sends a request and gets a Future instance. +2. Before calling future.get(), call ThreadlessExecutor.wait() first, wait will make the business thread wait on a blocking queue until elements are added to the queue. +3. When the business data is returned, generate a Runnable Task and put it into the ThreadlessExecutor queue +4. The business thread takes out the Task and executes it in this thread: deserialize the business data and set it to Future. +5. The business thread returns directly after getting the result + +In this way, compared with the old thread pool model, the business thread itself is responsible for monitoring and parsing the returned results, eliminating the need for additional consumption-side thread pool overhead. + +Regarding performance optimization, it will continue to advance in the next version, mainly starting from the following two aspects: + +1. RPC call link. The points that can be seen so far include: further reducing the memory allocation of the execution link, improving the efficiency of protocol transmission under the premise of ensuring protocol compatibility, and improving the computing efficiency of Filter and Router. +2. Service governance link. Further reduce memory and cpu resource consumption caused by address push and service governance rule push. \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/performance/threading-model/provider.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/performance/threading-model/provider.md new file mode 100644 index 000000000000..52ebe33be068 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/performance/threading-model/provider.md @@ -0,0 +1,127 @@ +--- +type: docs +title: "Server Thread Model" +linkTitle: "Server-side threading model" +weight: 1 +description: "Dubbo service provides end-to-end thread pool model and usage" +--- + + + +The current threading models of the Dubbo protocol and the Triple protocol are not yet aligned. The threading models of the Triple protocol and the Dubbo protocol are introduced separately below. + +# Dubbo protocol - Provider-side threading model + +Before introducing the Provider-side threading model of the Dubbo protocol, it is introduced that Dubbo abstracts the operations on the channel into five behaviors: + +- Establish a connection: connected, the main responsibility is to record the time of read and write in the channel, and handle the callback logic after the connection is established. For example, dubbo supports a custom callback hook (onconnect) after disconnection, that is, in this operation implement. +- Disconnected: disconnected, the main responsibility is to remove the read and write time of the channel, and handle the callback logic after the connection is opened. For example, dubbo supports a custom callback hook (ondisconnect) after disconnection, that is, in in this operation. +- Send message: sent, including sending request and sending response. Record the write time. +- Received message: received, including receiving request and receiving response. Record the read time. +- Exception capture: caught, used to handle various exceptions that occur on the channel. + +The thread model of the Dubbo framework is closely related to the above five behaviors. The thread model of the Dubbo protocol Provider can be divided into five categories, namely AllDispatcher, DirectDispatcher, MessageOnlyDispatcher, ExecutionDispatcher, and ConnectionOrderedDispatcher. + +### All Dispatcher + +The following figure is an illustration of the threading model of All Dispatcher: + +![dubbo-provider-alldispatcher](/imgs/v3/feature/performance/threading-model/dubbo-provider-alldispatcher.png) + +- The operations performed in the IO thread are: + 1. The sent operation is executed on the IO thread. + 2. The serialized response is executed on the IO thread. +- The operations performed in the Dubbo thread are: + 1. Received, connected, disconnected, and caught are all executed on the Dubbo thread. + 2. The behavior of deserializing the request is done in Dubbo. + +### Direct Dispatcher + +The following figure is an illustration of the threading model of Direct Dispatcher: + +![dubbo-provider-directDispatcher](/imgs/v3/feature/performance/threading-model/dubbo-provider-directDispatcher.png) + +- The operations performed in the IO thread are: + 1. The received, connected, disconnected, caught, and sent operations are executed on the IO thread. + 2. The deserialization request and serialization response are executed on the IO thread. +- 1. It does not operate on Dubbo threads. + +### Execution Dispatcher + +The following figure is an illustration of the thread model of Execution Dispatcher: + +![dubbo-provider-ExecutionDispatcher](/imgs/v3/feature/performance/threading-model/dubbo-provider-executionDispatcher.png) + +- The operations performed in the IO thread are: + 1. The sent, connected, disconnected, and caught operations are executed on the IO thread. + 2. The serialized response is executed on the IO thread. +- The operations performed in the Dubbo thread are: + 1. Received is executed on the Dubbo thread. + 2. The behavior of deserializing the request is done in Dubbo. + +### Message Only Dispatcher + +On the Provider side, the threading models of Message Only Dispatcher and Execution Dispatcher are consistent, so the following figure is consistent with that of Execution Dispatcher, and the difference is on the Consumer side. See the threading model on the Consumer side below. + +The following figure is an illustration of the threading model of Message Only Dispatcher: + +![dubbo-provider-ExecutionDispatcher](/imgs/v3/feature/performance/threading-model/dubbo-provider-executionDispatcher.png) + +- The operations performed in the IO thread are: + 1. The sent, connected, disconnected, and caught operations are executed on the IO thread. + 2. The serialized response is executed on the IO thread. +- The operations performed in the Dubbo thread are: + 1. Received is executed on the Dubbo thread. + 2. The behavior of deserializing the request is done in Dubbo. + +### Connection Ordered Dispatcher + +The following figure is an illustration of the threading model of the Connection Ordered Dispatcher: + +![dubbbo-provider-connectionOrderedDispatcher](/imgs/v3/feature/performance/threading-model/dubbbo-provider-connectionOrderedDispatcher.png) + +- The operations performed in the IO thread are: + 1. The sent operation is executed on the IO thread. + 2. The serialized response is executed on the IO thread. +- The operations performed in the Dubbo thread are: + 1. Received, connected, disconnected, and caught are all executed on the Dubbo thread. But the two behaviors of connected and disconnected are isolated from the other two behaviors through the thread pool. And in Dubbo connected thread pool, link limit and warning light capabilities are provided. + 2. The behavior of deserializing the request is done in Dubbo. + +# Triple protocol——Provider-side threading model + +The following figure shows the threading model of the Provider side of the Triple protocol + +![triple-provider](/imgs/v3/feature/performance/threading-model/triple-provider.png) + +The provider thread model of the Triple protocol is relatively simple at present. Currently, the serialization and deserialization operations work on the Dubbo thread, while the IO thread does not carry these tasks. + + + +# How to adjust the threading model + +Take the yaml configuration method as an example: configure dispatcher: all under protocol to adjust the thread model of the dubbo protocol to All Dispatcher + +```yaml +dubbo: + application: + name: dubbo-springboot-demo-provider + protocol: + name: dubbo + port: -1 + dispatcher: all + registry: + id: zk-registry + address: zookeeper://127.0.0.1:2181 + config-center: + address: zookeeper://127.0.0.1:2181 + metadata-report: + address: zookeeper://127.0.0.1:2181 +``` + +Configuration values for each threading model: + +- All Dispatcher all + -Direct Dispatcher direct +- Execution Dispatcher execution +- Message Only Dispatcher: message +- Connection Ordered Dispatcher: connection \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/security/_index.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/security/_index.md new file mode 100755 index 000000000000..8532cb9ba4f2 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/security/_index.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "Improve service security" +linkTitle: "Improve Security" +weight: 4 +--- \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/security/auth.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/security/auth.md new file mode 100644 index 000000000000..e8c34b204722 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/security/auth.md @@ -0,0 +1,40 @@ +--- +type: docs +title: "Service Authentication" +linkTitle: "Service Authentication" +weight: 23 +description: "Understand dubbo3 service authentication" +--- + +## Feature description + +Security-sensitive businesses like payments may have a need to limit anonymous calls. In terms of security enhancement, 2.7.5 introduces the authentication and authentication mechanism based on the AK/SK mechanism, and introduces the authentication service center. The main principle is that when the consumer requests a service that requires authentication, it will pass SK, request Data, timestamps, parameters and other information to generate the corresponding request signature, which is carried to the peer end through Dubbo's Attahcment mechanism for signature verification, and business logic processing is performed only after the signature verification is passed. As shown below: + +![](/imgs/docsv2.7/user/examples/auth/auth.png) + + +## scenes to be used + +## How to use +### access method + +1. Users need to fill in their application information on the microservice site and generate a unique certificate for the application. + +2. Submit a work order on the management site to apply for the permission to use a certain sensitive business service, which will be approved by the corresponding business manager. After the approval is passed, the corresponding AK/SK will be generated and sent to the authentication service center. + +3. Import the certificate to the corresponding application and configure it. The configuration method is also very simple. Take the annotation method as an example: + + ### Service Provider + You only need to set `service.auth` to true, which means that the call of the service needs to pass the authentication. `param.sign` is `true`, which means that the parameter needs to be verified. + + ```java + @Service(parameters = {"service.auth","true","param.sign","true"}) + public class AuthDemoServiceImpl implements AuthService { + } + + ``` + + ### Service consumer + You only need to configure the corresponding certificate and other information, and then the signature operation will be automatically performed before invoking these interfaces that require authentication. Through the interaction with the authentication service, the user does not need to configure sensitive information such as AK/SK in the code , and refresh the AK/SK without restarting the application to achieve the purpose of dynamically issuing permissions. + +The solution has been submitted to the Dubbo open source community, and the basic framework has been merged. In addition to the AK/SK authentication method, the SPI mechanism supports user-customizable authentication and encryption that adapts to the company's internal infrastructure. key storage. \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/security/tls.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/security/tls.md new file mode 100644 index 000000000000..6f210740b250 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/security/tls.md @@ -0,0 +1,55 @@ +--- +type: docs +title: "TLS Support" +linkTitle: "TLS support" +weight: 1 +description: "Learn about TLS in dubbo3 for secure transport" +--- +## Feature description + +Both the built-in Dubbo Netty Server and the newly introduced gRPC protocol provide a TLS-based secure link transmission mechanism. + +There is a unified entry for TLS configuration. + +## scenes to be used + +Users who require encryption for the entire link can use TLS. + +## Reference use case + +[https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-ssl](https://github.com/apache/dubbo-samples/tree/master/4-governance/dubbo-samples-ssl) + +## How to use + +### Provider side +```java +SslConfig sslConfig = new SslConfig(); +sslConfig.setServerKeyCertChainPath("path to cert"); +sslConfig.setServerPrivateKeyPath(args[1]); +// If two-way cert authentication is enabled +if (mutualTls) { + sslConfig.setServerTrustCertCollectionPath(args[2]); +} + +ProtocolConfig protocolConfig = new ProtocolConfig("dubbo/grpc"); +protocolConfig.setSslEnabled(true); +``` +If you want to use the gRPC protocol, the protocol negotiation mechanism will be used when TLS is turned on, so you must use a Provider that supports the ALPN mechanism. The recommended one is netty-tcnative. For details, please refer to [Summary](https:/ /github.com/grpc/grpc-java/blob/master/SECURITY.md) + + +### Consumer side + +```java +if (!mutualTls) {} + sslConfig.setClientTrustCertCollectionPath(args[0]); +} else { + sslConfig.setClientTrustCertCollectionPath(args[0]); + sslConfig.setClientKeyCertChainPath(args[1]); + sslConfig.setClientPrivateKeyPath(args[2]); +} +``` + +In order to ensure the flexibility of application startup as much as possible, the specification of TLS Cert can also be dynamically specified during the startup phase according to the deployment environment through -D parameters or environment variables. Refer to Dubbo [Configuration Read Rules](/zh/docs/advanced /config-rule) + + +> On the security of service calls, Dubbo will continue to invest in subsequent versions, and the authentication mechanism for service discovery/calling is expected to meet you in the next version. \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/security/token-authorization.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/security/token-authorization.md new file mode 100644 index 000000000000..8d7f6ad43d75 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/security/token-authorization.md @@ -0,0 +1,48 @@ +--- +type: docs +title: "Access Control" +linkTitle: "Access Control" +weight: 2 +description: "Understand the configuration and use of dubbo3 permission control" +--- + +## Feature description +Control authority in the registration center through token verification to decide whether to issue tokens to consumers, +can prevent consumers from bypassing the registry to access the provider, +In addition, the authorization method can be flexibly changed through the registration center without modifying or upgrading the provider. + +![/user-guide/images/dubbo-token.jpg](/imgs/user/dubbo-token.jpg) + +## scenes to be used + +To a certain extent, the trusted authentication of the client and the server is realized, preventing any client from being able to access, and reducing the risk of security problems. + +## How to use +### Global Settings + +Enable token verification + +```xml + + +``` + +or + +```xml + + +``` +### Service Level Settings + +```xml + + +``` + +or + +```xml + + +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/_index.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/_index.md new file mode 100755 index 000000000000..4d9752c9a4ce --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/_index.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "Configuration Framework and Service Behavior" +linkTitle: "Framework and Services" +weight: 1 +--- \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/accesslog.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/accesslog.md new file mode 100644 index 000000000000..cf4187ca1ab0 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/accesslog.md @@ -0,0 +1,27 @@ +--- +type: docs +title: "Call Information Record" +linkTitle: "Call Information Record" +weight: 13 +description: "Understand dubbo3 call information records to configure and use through access logs" +--- +## Feature description + +The log in dubbo3 is divided into log adaptation and access log. If you want to record each request information, you can enable the access log, which is similar to the apache access log. + +## scenes to be used + +Based on audit needs, etc. similar to nginx accesslog output, etc. + +## How to use +### log4j log +Output access logs to the current application's log4j log +```xml + +``` +### specify the file +Output the access log to the specified file +```xml + +``` +> The log volume is relatively large, please pay attention to the disk capacity. \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/async-call.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/async-call.md new file mode 100644 index 000000000000..6ac0a377276d --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/async-call.md @@ -0,0 +1,177 @@ +--- +type: docs +title: "Asynchronous call" +linkTitle: "Asynchronous call" +weight: 3 +description: "Initiate an asynchronous call in Dubbo" +--- + +## Feature description +#### background + +Starting from 2.7.0, all asynchronous programming interfaces of Dubbo are based on [CompletableFuture](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletableFuture.html) + +Based on NIO's non-blocking implementation of parallel calls, the client does not need to start multi-threads to complete parallel calls to multiple remote services, and the overhead of multi-threading is relatively small. + +![/user-guide/images/future.jpg](/imgs/user/future.jpg) + +## Reference use case + +[https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-async](https://github.com/apache/dubbo-samples/tree/master/2-advanced/dubbo-samples-async) +## scenes to be used + +Send the user request content to the target request. When the target request encounters high traffic or needs to be processed for a long time, the asynchronous call function will allow the response to be returned to the user immediately, while the target request continues to process the request in the background. When the target request returns the result, the content will be sent displayed to the user. + +## How to use +### Interface signed with CompletableFuture + +For services that require service providers to define CompletableFuture signatures in advance, the interface definition guidelines are as follows: + +The asynchronous execution of the provider side switches the blocked business from Dubbo's internal thread pool to the business-defined thread, avoiding excessive occupation of the Dubbo thread pool, and helping to avoid the mutual influence between different services. Asynchronous execution is tantamount to saving resources or improving RPC response performance, because if business execution needs to be blocked, there is always a thread to be responsible for execution. + +> **Provider-side asynchronous execution and Consumer-side asynchronous call are independent of each other, any orthogonal combination of two configurations** +> - Consumer Synchronization - Provider Synchronization +> - Consumer asynchronous - Provider synchronous +> - Consumer synchronous - Provider asynchronous +> - Consumer asynchronous - Provider asynchronous + +### Define the interface of CompletableFuture signature + +service interface definition +```java +public interface AsyncService { + CompletableFuture sayHello(String name); +} +``` + +service realization +```java +public class AsyncServiceImpl implements AsyncService { + @Override + public CompletableFuture sayHello(String name) { + return CompletableFuture. supplyAsync(() -> { + System.out.println(name); + try { + Thread. sleep(5000); + } catch (InterruptedException e) { + e.printStackTrace(); + } + return "async response from provider."; + }); + } +} +``` + +Through `return CompletableFuture.supplyAsync()`, the business execution has been switched from the Dubbo thread to the business thread, avoiding the blocking of the Dubbo thread pool. + + + +### Using AsyncContext + +Dubbo provides an asynchronous interface `AsyncContext` similar to Servlet 3.0, which can also implement asynchronous execution on the Provider side without the CompletableFuture signature interface. + +service interface definition +```java +public interface AsyncService { + String sayHello(String name); +} +``` + +Service exposure, exactly the same as ordinary services +```xml + + +``` + +service realization +```java +public class AsyncServiceImpl implements AsyncService { + public String sayHello(String name) { + final AsyncContext asyncContext = RpcContext. startAsync(); + new Thread(() -> { + // If you want to use the context, it must be executed in the first sentence + asyncContext.signalContextSwitch(); + try { + Thread. sleep(500); + } catch (InterruptedException e) { + e.printStackTrace(); + } + // write back the response + asyncContext.write("Hello " + name + ", response from provider."); + }).start(); + return null; + } +} +``` + +Note that the return type of the interface is `CompletableFuture`. + +XML Reference Service +```xml + +``` + +call remote service +```java +// The call directly returns CompletableFuture +CompletableFuture future = asyncService.sayHello("async call request"); +// add callback +future. whenComplete((v, t) -> { + if (t != null) { + t. printStackTrace(); + } else { + System.out.println("Response: " + v); + } +}); +// earlier than the result output +System.out.println("Executed before response return."); +``` + +### Using RpcContext +Configure in consumer.xml +```xml + + + +``` + +calling code +```java +// this call returns null immediately +asyncService.sayHello("world"); +// Get the Future reference of the call, when the result is returned, it will be notified and set to this Future +CompletableFuture helloFuture = RpcContext.getServiceContext().getCompletableFuture(); +// add callback for Future +helloFuture. whenComplete((retValue, exception) -> { + if (exception == null) { + System.out.println(retValue); + } else { + exception. printStackTrace(); + } +}); +``` + +Alternatively, it is also possible to do this asynchronously by calling +```java +CompletableFuture future = RpcContext.getServiceContext().asyncCall( + () -> { + asyncService.sayHello("oneway call request1"); + } +); + +future. get(); +``` + + +**Asynchronous always does not wait for return**, you can also set whether to wait for the message to be sent +- `sent="true"` waits for the message to be sent, and an exception will be thrown if the message fails to be sent. +- `sent="false"` does not wait for the message to be sent, puts the message in the IO queue, and returns immediately. + +```xml + +``` + +If you just want to be asynchronous and completely ignore the return value, you can configure `return="false"` to reduce the cost of creating and managing Future objects +```xml + +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/async-execute-on-provider.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/async-execute-on-provider.md new file mode 100644 index 000000000000..18eb74ab01f5 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/async-execute-on-provider.md @@ -0,0 +1,98 @@ +--- +type: docs +title: "Asynchronous execution" +linkTitle: "Asynchronous execution" +weight: 21 +description: "Asynchronous execution of Dubbo service provider" +--- + +{{% pageinfo %}} This document is no longer maintained. You are currently viewing a snapshot version. If you want to see the latest version of the documentation, see [Latest Version](/en/docs3-v2/java-sdk/advanced-features-and-usage/service/attachment/). +{{% /pageinfo %}} + + +The asynchronous execution of the provider side switches the blocked business from Dubbo's internal thread pool to the business-defined thread, avoiding excessive occupation of the Dubbo thread pool, and helping to avoid the mutual influence between different services. Asynchronous execution is tantamount to saving resources or improving RPC response performance, because if business execution needs to be blocked, there is always a thread to be responsible for execution. + +{{% alert title="Attention" color="warning" %}} +The asynchronous execution on the Provider side and the asynchronous call on the Consumer side are independent of each other, and you can configure both ends in any orthogonal combination +- Consumer Synchronization - Provider Synchronization +- Consumer asynchronous - Provider synchronous +- Consumer synchronous - Provider asynchronous +- Consumer asynchronous - Provider asynchronous + {{% /alert %}} + + +## Define the interface of CompletableFuture signature + +Service interface definition: + +```java +public interface AsyncService { + CompletableFuture sayHello(String name); +} +``` + +Service implementation: + +```java +public class AsyncServiceImpl implements AsyncService { + @Override + public CompletableFuture sayHello(String name) { + RpcContext savedContext = RpcContext. getContext(); + // It is recommended to provide a custom thread pool for supplyAsync and avoid using the JDK public thread pool + return CompletableFuture. supplyAsync(() -> { + System.out.println(savedContext.getAttachment("consumer-key1")); + try { + Thread. sleep(5000); + } catch (InterruptedException e) { + e.printStackTrace(); + } + return "async response from provider."; + }); + } +} +``` + +Through `return CompletableFuture.supplyAsync()`, the business execution has been switched from the Dubbo thread to the business thread, avoiding the blocking of the Dubbo thread pool. + + + +## Using AsyncContext + +Dubbo provides an asynchronous interface `AsyncContext` similar to Servlet 3.0, which can also implement asynchronous execution on the Provider side without the CompletableFuture signature interface. + +Service interface definition: + +```java +public interface AsyncService { + String sayHello(String name); +} +``` + +Service exposure is exactly the same as ordinary services: + +```xml + + +``` + +Service implementation: + +```java +public class AsyncServiceImpl implements AsyncService { + public String sayHello(String name) { + final AsyncContext asyncContext = RpcContext. startAsync(); + new Thread(() -> { + // If you want to use the context, it must be executed in the first sentence + asyncContext.signalContextSwitch(); + try { + Thread. sleep(500); + } catch (InterruptedException e) { + e.printStackTrace(); + } + // write back the response + asyncContext.write("Hello " + name + ", response from provider."); + }).start(); + return null; + } +} +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/attachment.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/attachment.md new file mode 100644 index 000000000000..cbc173f7e2a4 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/attachment.md @@ -0,0 +1,103 @@ +--- +type: docs +title: "Call link to pass implicit parameters" +linkTitle: "Call link to pass implicit parameters" +weight: 5 +description: "Implicitly pass parameters between service consumers and providers through Attachment in Dubbo" +--- + +## Feature description + +Parameters can be implicitly passed between the service consumer and the provider through `setAttachment` and `getAttachment` on `RpcContext`. + +#### background + +Context information is a very important function of the RPC framework. Using RpcContext can specify different configurations for a single call. For example, in the distributed link tracking scenario, the implementation principle is to maintain a traceId in the context of the entire link. The Consumer and Provider connect an RPC call by passing the traceId. After reporting the logs respectively, they can be connected in series in the tracking system and display the complete call. process. In this way, it is easier to find abnormalities and locate problems. +RpcContext in Dubbo is a ThreadLocal temporary state recorder. When RPC requests are received or RPC requests are initiated, the state of RpcContext will change. For example: **A tunes B, B tunes C, then on machine B, before B tunes C, RpcContext records the information of A and B, after B tunes C, RpcContext records the information of B and C. ** + +In Dubbo 3, RpcContext is split into four major modules (ServerContext, ClientAttachment, ServerAttachment and ServiceContext). + +They bear different accusations respectively: +- ServiceContext: Used internally by Dubbo to pass parameter information on the call link, such as invoker objects, etc. +- ClientAttachment: Used on the client side, the parameters written in ClientAttachment will be passed to the server side +- ServerAttachment: Used on the Server side, the parameters read from ServerAttachment are passed from the Client +- ServerContext: It is used on both the client side and the server side, and is used to pass back from the server side to the client side. The parameters written by the server side to the ServerContext can be obtained from the ServerContext on the client side after the call ends + +![/imgs/v3/concepts/rpccontext.png](/imgs/v3/concepts/rpccontext.png) + +As shown in the figure above, when the consumer initiates an invocation, it can directly initiate a call to the remote service through Method Invoke, and at the same time, the data written by the consumer to RpcClientAttachment will be written into Invocation together with the parameter information of Invoke. +The Invocation on the consumer side is serialized and sent to the server through network transmission. The server parses the Invocation to generate the parameters of Method Invoke and RpcServerAttachment, and then initiates the real call. +After the processing on the server end, the Method Response result together with the RpcServiceContext will generate a Result object. +The Result object on the server is serialized and sent back to the consumer through network transmission. The consumer parses the Result to generate a Method Response result and RpcServiceContext, and returns the actual call result and context to the consumer. + +> path, group, version, dubbo, token, timeout several keys are reserved fields, please use other values. + +## scenes to be used + +How to transparently transmit traceId to the service provider when the internal system calls through Dubbo. + +## How to use + +> The KV pair set by `setAttachment` will be cleared after the following remote call is completed, that is, multiple remote calls need to be set multiple times. + +### Set implicit parameters on the service consumer side + +```java +RpcContext.getClientAttachment().setAttachment("index", "1"); // Implicit parameter passing, subsequent remote calls will implicitly send these parameters to the server, similar to cookies, used for framework integration, not recommended business use +xxxService.xxx(); // remote call +//... +``` + +### Obtain implicit parameters on the service provider side + +```java +public class XxxServiceImpl implements XxxService { + + public void xxx() { + // Obtain the parameters implicitly passed in by the client for framework integration, not recommended for general business use + String index = RpcContext.getServerAttachment().getAttachment("index"); + } +} +``` + +### Write return parameters in the service provider + +```java +public class XxxServiceImpl implements XxxService { + + public void xxx() { + String index = xxx; + RpcContext.getServerContext().setAttachment("result", index); + } +} +``` + +### Obtain the return parameters on the consumer side + +```java +xxxService.xxx(); // remote call +String result = RpcContext.getServerContext().getAttachment("result"); +//... +``` + +## Parameter transparent transmission problem + +In Dubbo 2.7, after the parameters set on the A side are called, if B continues to call C, the parameters originally set in A will also be brought to the C side, causing the problem of parameter pollution. +Dubbo 3 has refactored RpcContext to support optional parameter transparent transmission, and parameter transparent transmission is enabled by default. + +The following SPI is provided in Dubbo 3. There is no implementation by default. Users can define their own implementation. The result of `select` (you can get all the current parameters from RpcClientAttachment) will be passed to the next hop as a key-value pair that needs to be transparently transmitted. If Returning null means that parameters are not transparently passed. + +```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 select(); + +} +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/callback-parameter.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/callback-parameter.md new file mode 100644 index 000000000000..6e01d24ef5f6 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/callback-parameter.md @@ -0,0 +1,118 @@ +--- +type: docs +title: "The server makes a callback to the client" +linkTitle: "The server makes a callback to the client" +weight: 9 +description: "Call client-side logic from server-side via parameter callback" +--- +## Feature description +The parameter callback method is the same as calling a local callback or listener, you only need to declare which parameter is the callback type in the Spring configuration file. Dubbo will generate a reverse proxy based on the persistent connection, so that the client logic can be invoked from the server. You can refer to [sample code in the dubbo project](https://github.com/apache/dubbo-samples/tree/master/2-advanced/dubbo-samples-callback). + +## scenes to be used +The callback function notifies the client of the execution result, or sends a notification. When the method execution time is relatively long, it is similar to an asynchronous call, and the client approval result is called back in the approval workflow. + +## How to use +### Service interface example + +CallbackService.java +```java +package com. callback; + +public interface CallbackService { + void addListener(String key, CallbackListener listener); +} +``` + +CallbackListener.java +```java +package com. callback; + +public interface CallbackListener { + void changed(String msg); +} +``` + +### Service provider interface implementation example + +```java +package com.callback.impl; + +import java.text.SimpleDateFormat; +import java.util.Date; +import java.util.Map; +import java.util.concurrent.ConcurrentHashMap; + +import com.callback.CallbackListener; +import com.callback.CallbackService; + +public class CallbackServiceImpl implements CallbackService { + + private final Map listeners = new ConcurrentHashMap(); + + public CallbackServiceImpl() { + Thread t = new Thread(new Runnable() { + public void run() { + while(true) { + try { + for(Map.Entry entry : listeners.entrySet()){ + try { + entry.getValue().changed(getChanged(entry.getKey())); + } catch (Throwable t) { + listeners. remove(entry. getKey()); + } + } + Thread.sleep(5000); // Timely trigger change notification + } catch (Throwable t) { // defensive fault tolerance + t. printStackTrace(); + } + } + } + }); + t. setDaemon(true); + t. start(); + } + + public void addListener(String key, CallbackListener listener) { + listeners. put(key, listener); + listener.changed(getChanged(key)); // send change notification + } + + private String getChanged(String key) { + return "Changed: " + new SimpleDateFormat("yyyy-MM-dd HH:mm:ss").format(new Date()); + } +} +``` + +### Service provider configuration example + +```xml + + + + + + + + +``` + +### Service consumer configuration example + +```xml + +``` + +### Service consumer call example + +```java +ClassPathXmlApplicationContext context = new ClassPathXmlApplicationContext("classpath:consumer.xml"); +context. start(); + +CallbackService callbackService = (CallbackService) context. getBean("callbackService"); + +callbackService.addListener("foo.bar", new CallbackListener(){ + public void changed(String msg) { + System.out.println("callback1:" + msg); + } +}); +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/consistent-hash.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/consistent-hash.md new file mode 100644 index 000000000000..d64e683dcd2b --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/consistent-hash.md @@ -0,0 +1,47 @@ +--- +type: docs +title: "Consistent Hash Site Selection" +linkTitle: "Consistent Hash Site Selection" +weight: 6 +description: "Address selection based on consistent hash in the load balancing phase" +--- +## Feature description + +[Analysis of Dubbo Consistent Hash Load Balancing Implementation](/zh/blog/2019/05/01/dubbo-%E4%B8%80%E8%87%B4%E6%80%A7hash%E8%B4%9F%E8 %BD%BD%E5%9D%87%E8%A1%A1%E5%AE%9E%E7%8E%B0%E5%89%96%E6%9E%90/) + +## scenes to be used + +When there are multiple servers, the server is selected according to the consistent hashing of the request parameters. + +## How to use + +There are many ways to configure consistent hashing, the most common are: + +### Annotation configuration + +> @DubboReference(loadbalance = "consistenthash") + +### API configuration + +> referenceConfig.setLoadBalance("consistenthash"); + +### Properties configuration + +> dubbo.reference.loadbalance=consistenthash + +### XML configuration + +> + +By default, the first parameter is used as the hash key. If you need to switch parameters, you can specify the `hash.arguments` property + +```java +ReferenceConfig referenceConfig = new ReferenceConfig(); +// ...init +Map parameters = new HashMap(); +parameters. put("hash. arguments", "1"); +parameters. put("sayHello. hash. arguments", "0,1"); +referenceConfig.setParameters(parameters); +referenceConfig.setLoadBalance("consistenthash"); +referenceConfig. get(); +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/context.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/context.md new file mode 100644 index 000000000000..87271baf416e --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/context.md @@ -0,0 +1,49 @@ +--- +type: docs +title: "RPC call context" +linkTitle: "RPC call context" +weight: 6 +description: "Store the environment information required in the current calling process through the context" +--- +## Feature description +The context stores the environment information needed in the current calling process. All configuration information will be converted to URL parameters, see the **corresponding URL parameters** column in [schema configuration reference manual](../../../reference-manual/config/properties/). + +RpcContext is a temporary state recorder for ThreadLocal. When RPC requests are received or RPC requests are initiated, the state of RpcContext will change. For example: A tunes B, B then tunes C, then on machine B, before B tunes C, RpcContext records the information of A's tune to B, after B tunes C, RpcContext records the information of B's tune to C. + +## scenes to be used +Global link tracking and hiding parameters. + +## How to use + +### Service consumer +```java +// remote call +xxxService. xxx(); +// Whether this end is a consumer end, here will return true +boolean isConsumerSide = RpcContext.getServiceContext().isConsumerSide(); +// Get the provider IP address of the last call +String serverIP = RpcContext.getServiceContext().getRemoteHost(); +// Get the current service configuration information, all configuration information will be converted into URL parameters +String application = RpcContext.getServiceContext().getUrl().getParameter("application"); +// Note: Every time an RPC call is initiated, the context state will change +yyyService.yyy(); +``` + +### Service Provider +```java +public class XxxServiceImpl implements XxxService { + + public void xxx() { + // Whether this end is the provider end, here will return true + boolean isProviderSide = RpcContext.getServiceContext().isProviderSide(); + // Get the IP address of the caller + String clientIP = RpcContext.getServiceContext().getRemoteHost(); + // Get the current service configuration information, all configuration information will be converted into URL parameters + String application = RpcContext.getServiceContext().getUrl().getParameter("application"); + // Note: Every time an RPC call is initiated, the context state will change + yyyService.yyy(); + // At this point, the local end becomes the consumer end, and false will be returned here + boolean isProviderSide = RpcContext.getServiceContext().isProviderSide(); + } +} +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/delay-publish.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/delay-publish.md new file mode 100644 index 000000000000..49dd4fe16d75 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/delay-publish.md @@ -0,0 +1,59 @@ +--- +type: docs +title: "Delayed Exposure" +linkTitle: "Delayed Exposure" +weight: 27 +description: "Delayed exposure of Dubbo services" +--- + +If your service needs warm-up time, such as initializing the cache, waiting for related resources to be in place, etc., you can use delay for delayed exposure. In Dubbo version 2.6.5, we made minor adjustments to the service delay exposure logic, and postponed the countdown action for services that require delay exposure (delay > 0) until Spring initialization is complete. You will not feel this change while using Dubbo, so please feel free to use it. + +## Versions before Dubbo 2.6.5 + +Delay until Spring initialization completes before exposing services[^1] + +```xml + +``` + +Expose service with 5 second delay + +```xml + +``` + +## Dubbo 2.6.5 and later versions + +All services will be exposed after Spring initialization is complete. If you do not need to delay exposing services, you do not need to configure delay. + +Expose service with 5 second delay + +```xml + +``` + +## Spring 2.x initialization deadlock problem + +### Triggering conditions + +When Spring resolves to ``, the service has been exposed, and Spring is still initializing other beans. If a request comes in at this time, and there is a usage of calling `applicationContext.getBean()` in the implementation class of the service. + +1. The applicationContext.getBean() call of the requesting thread first synchronizes the singletonObjects to determine whether the Bean exists, and initializes the synchronization beanDefinitionMap if it does not exist, and then synchronizes the singletonObjects again to write the Bean instance cache. + + ![deadlock](/imgs/user/lock-get-bean.jpg) + +2. The Spring initialization thread, because it does not need to judge the existence of the bean, directly synchronizes the beanDefinitionMap to initialize, and synchronizes singletonObjects to write the bean instance cache. + + ![/user-guide/images/lock-init-context.jpg](/imgs/user/lock-init-context.jpg) + + This causes the getBean thread to lock singletonObjects first, then beanDefinitionMap, and singletonObjects again. + The Spring initialization thread first locks beanDefinitionMap and then singletonObjects. The reverse lock leads to thread deadlock, unable to provide services, and unable to start. + +### Workaround + +1. It is strongly recommended not to call applicationContext.getBean() in the service implementation class, and all use Spring beans by IoC injection. +2. If you really want to call getBean(), you can load the Dubbo configuration at the end of Spring. +3. If you don’t want to depend on the configuration order, you can use `` to make Dubbo expose the service after the Spring container is initialized. +4. If you use getBean() extensively, it is equivalent to degenerating Spring into a factory mode, and you can isolate Dubbo's services into a separate Spring container. + +[^1]: Trigger exposure based on Spring's ContextRefreshedEvent event \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/distributed-transaction.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/distributed-transaction.md new file mode 100644 index 000000000000..d04665669ced --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/distributed-transaction.md @@ -0,0 +1,15 @@ +--- +type: docs +title: "Distributed transaction support" +linkTitle: "Distributed transaction support" +weight: 42 +description: "Support for distributed transactions in Dubbo" +--- + +Distributed transactions are implemented based on the JTA/XA specification. + +**two-phase commit** + +![/user-guide/images/jta-xa.jpg](/imgs/user/jta-xa.jpg) + +In Dubbo, you can use [seata](/zh/blog/2019/01/17/How to use seata to ensure the consistency between dubbo microservices/) to complete the support for distributed transactions. \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/echo-service.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/echo-service.md new file mode 100644 index 000000000000..ba34d266f644 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/echo-service.md @@ -0,0 +1,36 @@ +--- +type: docs +title: "Echo Test" +linkTitle: "Echo Test" +weight: 12 +description: "Check whether Dubbo service is available by echo test" +--- + +## Feature description +The echo test is used to detect whether the service is available. The echo test is performed according to the normal request process. It can test whether the entire call is smooth and can be used for monitoring. + +## Reference use case +[https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-echo](https://github.com/apache/dubbo-samples/tree/master/2-advanced/dubbo-samples-echo) + +## scenes to be used + +## How to use +All services automatically implement the `EchoService` interface, just cast any service reference to `EchoService` to use it. + +### Spring configuration +```xml + +``` + +### code +```java +// remote service reference +MemberService memberService = ctx. getBean("memberService"); + +EchoService echoService = (EchoService) memberService; // Mandatory transformation to EchoService + +// echo test availability +String status = echoService. $echo("OK"); + +assert(status. equals("OK")); +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/events-notify.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/events-notify.md new file mode 100644 index 000000000000..c83e68522677 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/events-notify.md @@ -0,0 +1,108 @@ +--- +type: docs +title: "Call trigger event notification" +linkTitle: "Call trigger event notification" +weight: 8 +description: "Event notification when an exception occurs before and after the call" +--- +## Feature description +Before calling, after calling, and when an exception occurs, three events `oninvoke`, `onreturn`, and `onthrow` will be triggered. You can configure which method of which class to notify when an event occurs. + +## Reference use case + +[https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-notify](https://github.com/apache/dubbo-samples/tree/master/2-advanced/dubbo-samples-notify) + +## scenes to be used + +Before calling the service method, we can record the start time, and after the call ends, we can count the entire call cost. When an exception occurs, we can warn or print error logs, or record request logs and response logs before and after calling the service. + +## How to use + +### Service provider and consumer share service interface + +```java +interface IDemoService { + public Person get(int id); +} +``` +### Service provider implementation + +```java +class NormalDemoService implements IDemoService { + public Person get(int id) { + return new Person(id, "charles`son", 4); + } +} +``` + +### Service provider configuration + +```xml + + + + +``` +### Service consumer Callback interface + +```java +interface Notify { + public void onreturn(Person msg, Integer id); + public void onthrow(Throwable ex, Integer id); +} +``` + +### Service consumer Callback implementation + +```java +class NotifyImpl implements Notify { + public Map ret = new HashMap(); + public Map errors = new HashMap(); + + public void onreturn(Person msg, Integer id) { + System.out.println("onreturn:" + msg); + ret. put(id, msg); + } + + public void onthrow(Throwable ex, Integer id) { + errors. put(id, ex); + } +} +``` + +### Service consumer Callback configuration + +There are the following combinations of the two: + +* Asynchronous callback mode: `async=true onreturn="xxx"` +* Synchronous callback mode: `async=false onreturn="xxx"` +* Asynchronous without callback: `async=true` +* Synchronous without callback: `async=false` + +`callback` and `async` function are decomposed orthogonally, `async=true` indicates whether the result is returned immediately, `async=false` is the default, `onreturn` indicates whether a callback is required. +```xml + + + + +``` + + +### Test code + +```java +IDemoService demoService = (IDemoService) context. getBean("demoService"); +NotifyImpl notify = (NotifyImpl) context. getBean("demoCallback"); +int requestId = 2; +Person ret = demoService. get(requestId); +Assert.assertEquals(null, ret); +//for Test: It is only used to illustrate that the callback is called normally, and the specific implementation of the business is determined by itself. +for (int i = 0; i < 10; i++) { + if (!notify.ret.containsKey(requestId)) { + Thread. sleep(200); + } else { + break; + } +} +Assert.assertEquals(requestId, notify.ret.get(requestId).getId()); +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/explicit-target.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/explicit-target.md new file mode 100644 index 000000000000..7b12bb16d755 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/explicit-target.md @@ -0,0 +1,60 @@ +--- +type: docs +title: "Direct Connection Provider" +linkTitle: "Direct Link Provider" +weight: 5 +description: "Direct point-to-point connection in Dubbo" +--- + +{{% pageinfo %}} This document is no longer maintained. You are currently viewing a snapshot version. If you want to view the latest version of the documentation, see [Latest Version](/en/docs3-v2/java-sdk/advanced-features-and-usage/service/specify-ip/). +{{% /pageinfo %}} + +In the development and testing environment, it is often necessary to bypass the registration center and only test the specified service provider. At this time, point-to-point direct connection may be required. The point-to-point direct connection method will use the service interface as the unit and ignore the provider list of the registration center. A The point-to-point interface configuration does not affect the B interface to obtain the list from the registration center. + +![/user-guide/images/dubbo-directly.jpg](/imgs/user/dubbo-directly.jpg) + +## Configuration via XML + +If the online demand needs point-to-point, you can configure the url to point to the provider in ``, which will bypass the registration center. Multiple addresses are separated by semicolons, and the configuration is as follows: + +```xml + +``` + +{{% alert title="Prompt" color="primary" %}} +`1.0.6` and above version support +{{% /alert %}} + +## Specified by -D parameter + +Add the -D parameter mapping service address to the JVM startup parameters, such as: + +```sh +java -Dcom.alibaba.xxx.XxxService=dubbo://localhost:20890 +``` + +{{% alert title="Prompt" color="primary" %}} +The key is the service name, and the value is the service provider url. This configuration has the highest priority and is supported by `1.0.15` and above versions +{{% /alert %}} + +## By file mapping + +If there are many services, you can also use file mapping, use `-Ddubbo.resolve.file` to specify the mapping file path, this configuration has a higher priority than the configuration [^3] in ``, such as: + +```sh +java -Ddubbo.resolve.file=xxx.properties +``` + +Then add the configuration to the mapping file `xxx.properties`, where the key is the service name and the value is the service provider URL: + +```properties +com.alibaba.xxx.XxxService=dubbo://localhost:20890 +``` + +{{% alert title="Prompt" color="primary" %}} +`1.0.15` and above versions support, `2.0` and above versions automatically load the ${user.home}/dubbo-resolve.properties file, no configuration required +{{% /alert %}} + +{{% alert title="Attention" color="warning" %}} +In order to avoid complicating the online environment, do not use this feature online, it should only be used during the testing phase. +{{% /alert %}} \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/fault-tolerent-strategy.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/fault-tolerent-strategy.md new file mode 100644 index 000000000000..05bd79f3ba80 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/fault-tolerent-strategy.md @@ -0,0 +1,137 @@ +--- +type: docs +title: "Cluster Fault Tolerance" +linkTitle: "Cluster Fault Tolerance" +weight: 2 +description: "When the cluster call fails, the fault tolerance solution provided by Dubbo" +--- + +When the cluster call fails, Dubbo provides a variety of fault tolerance schemes, and the default is failover retry. + +![cluster](/imgs/user/cluster.jpg) + +Each node relationship: + +* Here `Invoker` is an abstraction of `Provider` that can call `Service`, `Invoker` encapsulates `Provider` address and `Service` interface information +* `Directory` represents multiple `Invoker`, which can be regarded as `List`, but different from `List`, its value may change dynamically, such as the registration center pushing changes +* `Cluster` disguises multiple `Invoker` in `Directory` as an `Invoker`, which is transparent to the upper layer. The masquerading process includes fault-tolerant logic. After the call fails, try another one +* `Router` is responsible for selecting subsets from multiple `Invoker` according to routing rules, such as read-write separation, application isolation, etc. +* `LoadBalance` is responsible for selecting a specific one from multiple `Invoker`s for this call. The selection process includes a load balancing algorithm. After the call fails, it needs to be re-selected + +## Cluster fault tolerance mode + +You can expand the cluster fault-tolerant strategy by yourself, see: [Cluster Expansion](../../../reference-manual/spi/description/cluster/) + +### Failover Cluster + +Automatic switching on failure, when a failure occurs, retry other servers. Usually used for read operations, but retries can introduce longer delays. The number of retries can be set by `retries="2"` (excluding the first time). + +The number of retries is configured as follows: + +```xml + +``` + +or + +```xml + +``` + +or + +```xml + + + +``` + +{{% alert title="Prompt" color="primary" %}} +This configuration is the default configuration +{{% /alert %}} + +### Failfast Cluster + +Fail fast, only one call is made, and an error will be reported immediately if it fails. Usually used for non-idempotent write operations, such as adding new records. + +### Failsafe Cluster + +Fail safe, when an exception occurs, just ignore it. Typically used for operations such as writing to audit logs. + +### Failback Cluster + +The failure is automatically recovered, and the failed request is recorded in the background and resent at regular intervals. Typically used for message notification operations. + +### Forking Cluster + +Call multiple servers in parallel, and return as long as one succeeds. It is usually used for read operations with high real-time requirements, but more service resources need to be wasted. The maximum parallelism can be set by `forks="2"`. + +### Broadcast Cluster + +Broadcast calls all providers one by one, and if any one reports an error, it will report an error. Usually used to notify all providers to update local resource information such as cache or logs. + +Now in the broadcast call, you can configure the failure ratio of the node call through broadcast.fail.percent. When this ratio is reached, the BroadcastClusterInvoker +No other nodes will be called, and an exception will be thrown directly. broadcast.fail.percent ranges from 0 to 100. By default, an exception is thrown when all calls fail. +broadcast.fail.percent only controls whether to continue to call other nodes after failure, and does not change the result (if any node reports an error, it will report an error). broadcast.fail.percent parameter +Effective in dubbo2.7.10 and above. + +Broadcast Cluster configuration broadcast.fail.percent. + +broadcast.fail.percent=20 means that when 20% of the nodes fail to call, an exception will be thrown, and no other nodes will be called. + +```text +@reference(cluster = "broadcast", parameters = {"broadcast. fail. percent", "20"}) +``` + + +{{% alert title="Prompt" color="primary" %}} +`2.1.0` started to support +{{% /alert %}} + +### Available Cluster + +Calls the currently available instance (only one is called), or throws an exception if no instance is currently available. Usually used in scenarios that do not require load balancing. + +### Mergeable Cluster + +Aggregate the call results in the cluster and return the result, usually used together with group. Aggregate the results by grouping and return the aggregated results, such as menu services, use group to distinguish multiple implementations of the same interface, now the consumer needs to call once from each group and return the results, and return the results after merging, so that You can implement aggregated menu items. + +### ZoneAware Cluster + +In the scenario of multi-registry subscription, load balancing between registry clusters. There are four strategies for address selection between multiple registries: + +1. Specify the priority: `preferred="true"`The address of the registration center will be selected first + +```xml + +``` + +2. Same center priority: check the area to which the current request belongs, and give priority to registration centers with the same area + +```xml + +``` + +3. Weight polling: distribute traffic according to the weight of each registry + +```xml + + + +``` + +4. Default: Select an available registry + +## Cluster mode configuration + +Follow the example below to configure cluster mode on the service provider and consumer + +```xml + +``` + +or + +```xml + +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/generic-reference.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/generic-reference.md new file mode 100644 index 000000000000..cae9beb30d03 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/generic-reference.md @@ -0,0 +1,376 @@ +--- +type: docs +linkTitle: "Generalized call" +title: "Generalization call (client generalization)" +weight: 4 +description: "RPC calls that do not require a server-side API" +--- + +## Feature description + +Generalized call refers to calling the server without the API (SDK) provided by the server, and the call result can be obtained normally. + +## scenes to be used + +The generalization call is mainly used to implement a general remote service mock framework, which can handle all service requests by implementing the GenericService interface. For example, the following scenario: + +1. Gateway service: If you want to build a gateway service, then the service gateway should be the calling end of all RPC services. However, the gateway itself should not depend on the interface API of the service provider (this will cause the code of the gateway to be modified and redeployed every time a new service is released), so support for generalization calls is required. + +2. Test platform: If you want to build a platform that can test RPC calls, the user can test the corresponding RPC service by inputting information such as group name, interface, method name, etc. Then, for the same reason (that is, every time a new service is released, the code of the gateway needs to be modified and redeployed), the platform itself should not depend on the interface API of the service provider. So support for generalized calls is needed. + +## How to use + +The demo can be seen [sample code in the dubbo project](https://github.com/apache/dubbo-samples/tree/master/2-advanced/dubbo-samples-generic) + +The API part uses this demo as an example to explain how to use it. + +### Service definition + +#### Service interface + +```java +public interface HelloService { + + String sayHello(String name); + + CompletableFuture sayHelloAsync(String name); + + CompletableFuture sayHelloAsyncComplex(String name); + + CompletableFuture> sayHelloAsyncGenericComplex(String name); +} + +``` + +#### Service implementation class + +```java +public class HelloServiceImpl implements HelloService { + + @Override + public String sayHello(String name) { + return "sayHello: " + name; + } + + @Override + public CompletableFuture sayHelloAsync(String name) { + CompletableFuture future = new CompletableFuture<>(); + new Thread(() -> { + try { + Thread. sleep(5000); + } catch (InterruptedException e) { + e.printStackTrace(); + } + future.complete("sayHelloAsync: " + name); + }).start(); + + return future; + } + + @Override + public CompletableFuture sayHelloAsyncComplex(String name) { + Person person = new Person(1, "sayHelloAsyncComplex: " + name); + CompletableFuture future = new CompletableFuture<>(); + new Thread(() -> { + try { + Thread. sleep(5000); + } catch (InterruptedException e) { + e.printStackTrace(); + } + future. complete(person); + }).start(); + + return future; + } + + @Override + public CompletableFuture> sayHelloAsyncGenericComplex(String name) { + Person person = new Person(1, "sayHelloAsyncGenericComplex: " + name); + GenericType genericType = new GenericType<>(person); + CompletableFuture> future = new CompletableFuture<>(); + new Thread(() -> { + try { + Thread. sleep(5000); + } catch (InterruptedException e) { + e.printStackTrace(); + } + future. complete(genericType); + }).start(); + + return future; + } +} + +``` + +### Using generic calls through the API + +#### Service initiator + +1. When setting `ServiceConfig`, use `setGeneric("true")` to enable generic calls + +2. When setting `ServiceConfig`, when using setRef to specify the implementation class, you must set a `GenericService` object. instead of the real service implementation class object + +3. Other settings are consistent with normal Api service startup + +```java +private static String zookeeperAddress = "zookeeper://" + System.getProperty("zookeeper.address", "127.0.0.1") + ":2181"; + + public static void main(String[] args) throws Exception { + new Embedded ZooKeeper(2181, false).start(); + + //Create ApplicationConfig + ApplicationConfig applicationConfig = new ApplicationConfig(); + applicationConfig.setName("generic-impl-provider"); + //Create registry configuration + RegistryConfig registryConfig = new RegistryConfig(); + registryConfig.setAddress(zookeeperAddress); + + //Create a new service implementation class, pay attention to use GenericService to receive + GenericService helloService = new GenericImplOfHelloService(); + + //Create service related configuration + ServiceConfig service = new ServiceConfig<>(); + service.setApplication(applicationConfig); + service.setRegistry(registryConfig); + service.setInterface("org.apache.dubbo.samples.generic.call.api.HelloService"); + service.setRef(helloService); + // Key point: set to generalization call + // Note: it is no longer recommended to use the setGeneric function whose parameter is a Boolean value + //should use referenceConfig.setGeneric("true") instead + service.setGeneric("true"); + service. export(); + + System.out.println("dubbo service started"); + + new CountDownLatch(1). await(); + } +} +``` + +#### Generalizing the caller +step: + +1. When setting `ReferenceConfig`, use `setGeneric("true")` to enable generic calls + +2. After configuring `ReferenceConfig`, use `referenceConfig.get()` to get the instance of the `GenericService` class + +3. Use its `$invoke` method to get the result + +4. Other settings are consistent with normal Api service startup + +```java + //Define generalized call service class + private static GenericService genericService; + public static void main(String[] args) throws Exception { + //Create ApplicationConfig + ApplicationConfig applicationConfig = new ApplicationConfig(); + applicationConfig.setName("generic-call-consumer"); + //Create registry configuration + RegistryConfig registryConfig = new RegistryConfig(); + registryConfig.setAddress("zookeeper://127.0.0.1:2181"); + //Create service reference configuration + ReferenceConfig referenceConfig = new ReferenceConfig<>(); + //Set the interface + referenceConfig.setInterface("org.apache.dubbo.samples.generic.call.api.HelloService"); + applicationConfig.setRegistry(registryConfig); + referenceConfig.setApplication(applicationConfig); + // Key point: set to generalization call + // Note: it is no longer recommended to use the setGeneric function whose parameter is a Boolean value + //should use referenceConfig.setGeneric("true") instead + referenceConfig.setGeneric(true); + //Set asynchronous, not necessary, it depends on the business. + referenceConfig.setAsync(true); + //Set the timeout + referenceConfig.setTimeout(7000); + + //Get the service, because it is a generalized call, so it must be of the GenericService type + genericService = referenceConfig. get(); + + //Using the $invoke method of the GenericService class object can be used instead of the original method + //The first parameter is the name of the method to call + //The second parameter is the parameter type array of the method to be called, which is a String array, and the full class name of the parameter is stored in it. + //The third parameter is the parameter array of the method to be called, which is an Object array, and the required parameters are stored in it. + Object result = genericService. $invoke("sayHello", new String[]{"java. lang. String"}, new Object[]{"world"}); + //Use CountDownLatch, if you use synchronous calls, you don't need to do this. + CountDownLatch latch = new CountDownLatch(1); + //Get the result + CompletableFuture future = RpcContext.getContext().getCompletableFuture(); + future. whenComplete((value, t) -> { + System.err.println("invokeSayHello(whenComplete): " + value); + latch. countDown(); + }); + // print the result + System.err.println("invokeSayHello(return): " + result); + latch. await(); + } +``` + +### Using generic calls with Spring +There are many ways to use service exposure and service discovery in Spring, such as xml and annotations. Take xml as an example here. +step: + +1. There is no need to change the producer side + +2. Add the attribute of `generic=true` to the original `dubbo:reference` tag on the consumer side. + +```xml + +``` + +3. Get the Bean container, and get the `GenericService` instance through the Bean container. + +4. Call the `$invoke` method to get the result + +```java + + private static GenericService genericService; + + public static void main(String[] args) throws Exception { + ClassPathXmlApplicationContext context = new ClassPathXmlApplicationContext("spring/generic-impl-consumer.xml"); + context. start(); + //The name of the bean corresponding to the service is determined by the id of the xml tag + genericService = context. getBean("helloService"); + //Get the result + Object result = genericService. $invoke("sayHello", new String[]{"java. lang. String"}, new Object[]{"world"}); + } +``` + + +### Protobuf object generalization call + +General generalization calls can only be used when the generated service parameters are POJOs, while GoogleProtobuf objects are abnormal POJOs generated based on Builder, which can be generalized and called through protobuf-json. + +GoogleProtobuf serialization-related Demo can refer to [protobuf-demo](https://github.com/apache/dubbo-samples/tree/master/3-extensions/serialization/dubbo-samples-protobuf) + +#### Generic calls to Google Protobuf objects through Spring + +Configure the declaration generic = "protobuf-json" in Spring + +```xml + +``` + +Get barService in Java code and start generalizing calls: + +```java +GenericService barService = (GenericService) applicationContext. getBean("barService"); +Object result = barService.$invoke("sayHello",new String[]{"org.apache.dubbo.protobuf.GooglePbBasic$CDubboGooglePBRequestType"}, new Object[]{"{\"double\":0.0,\"float \":0.0,\"bytesType\":\"Base64String\",\"int32\":0}"}); +``` + +#### Generalized calls to Google Protobuf objects through API + +```java +ReferenceConfig reference = new ReferenceConfig(); +// Weakly typed interface name +reference.setInterface(GenericService.class.getName()); +reference.setInterface("com.xxx.XxxService"); +// Declare as Protobuf-json +reference.setGeneric(Constants.GENERIC_SERIALIZATION_PROTOBUF); + +GenericService genericService = reference. get(); +Map person = new HashMap(); +person. put("fixed64", "0"); +person. put("int64", "0"); +// Referring to Google's official protobuf 3 syntax, only one POJO object is transmitted in each method of the service +// The generalized call of protobuf only allows passing a json object of type String to represent the request parameter +String requestString = new Gson().toJson(person); +// The return object is the json string of the GoolgeProtobuf response object. +Object result = genericService. $invoke("sayHello", new String[] { + "com.xxx.XxxService.GooglePbBasic$CDubboGooglePBRequestType"}, + new Object[] {requestString}); +``` + +#### Processing of GoogleProtobuf objects + +The GoogleProtobuf object is generated by the Protocol contract. For related knowledge, please refer to [ProtocolBuffers Documentation](https://developers.google.com/protocol-buffers/?hl=zh-CN). If there is the following Protobuf contract + +```proto +syntax = "proto3"; +package com.xxx.XxxService.GooglePbBasic.basic; +message CDubboGooglePBRequestType { + double double = 1; + float float = 2; + int32 int32 = 3; + bool bool = 13; + string string = 14; + bytes bytesType = 15; +} + +message CDubboGooglePBResponseType { + string msg = 1; +} + +service CDubboGooglePBService { + rpc sayHello (CDubboGooglePBRequestType) returns (CDubboGooglePBResponseType); +} +``` + +Then the corresponding request is constructed according to the following method + +```java +Map person = new HashMap<>(); +person. put("double", "1.000"); +person. put("float", "1.00"); +person. put("int32","1"); +person. put("bool","false"); +//String objects need to be base64 encoded +person. put("string","someBaseString"); +person. put("bytesType","150"); +``` + +#### GoogleProtobuf service metadata analysis + +Google Protobuf objects lack standard JSON formatting and the resulting service metadata information is incorrect. Please add the following dependencies that depend on metadata parsing. + +```xml + + org.apache.dubbo + dubbo-metadata-definition-protobuf + ${dubbo.version} + +``` + +It is also relatively easy to construct generalized call objects from service metadata. + + +## Precautions + +1. If the parameter is a basic type or Date, List, Map, etc., there is no need to convert it, just call it directly. + +2. If the parameter is another POJO, use Map instead. + +Such as: +```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; + } +} + +``` + +Should be converted to: + +```java +Map student = new HashMap(); +student. put("name", "xxx"); +student. put("age", "xxx"); +``` + +3. For other serialization formats, special configuration is required \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/generic-service.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/generic-service.md new file mode 100644 index 000000000000..e9154e2b64d0 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/generic-service.md @@ -0,0 +1,54 @@ +--- +type: docs +linkTitle: "Generalized call" +title: "Achieving generalization (server-side generalization)" +weight: 17 +description: "Implement a generic remote service Mock framework, which can handle all service requests by implementing the GenericService interface" +--- +## Feature description +The universal interface implementation method is mainly used when there is no API interface and model classifier on the server side. All POJOs in the parameters and return values are represented by Map, which is usually used for framework integration. For example, to implement a general remote service Mock framework, you can All service requests are handled by implementing the GenericService interface. + +## scenes to be used + +## How to use +Implement the `GenericService` interface in Java code + +```java +package com.foo; +public class MyGenericService implements GenericService { + + public Object $invoke(String methodName, String[] parameterTypes, Object[] args) throws GenericException { + if ("sayHello".equals(methodName)) { + return "Welcome " + args[0]; + } + } +} +``` + +### Exposing generic implementations via Spring + +Declare the implementation of the service in the Spring configuration + +```xml + + +``` + +### Expose the generalization implementation through the API + +```java +... +// Use org.apache.dubbo.rpc.service.GenericService to replace all interface implementations +GenericService xxxService = new XxxGenericService(); + +// This instance is very heavy, and it encapsulates all connections with the registry and service providers, please cache +ServiceConfig service = new ServiceConfig(); +// Weakly typed interface name +service.setInterface("com.xxx.XxxService"); +service.setVersion("1.0.0"); +// point to a generic service implementation +service.setRef(xxxService); + +// expose and register services +service. export(); +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/group-merger.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/group-merger.md new file mode 100644 index 000000000000..3c9772ace082 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/group-merger.md @@ -0,0 +1,69 @@ +--- +type: docs +title: "Group Aggregation" +linkTitle: "Group Aggregation" +weight: 1 +description: "Aggregate the results by grouping and return the aggregated results" +--- + +## Feature description +Aggregate the results by grouping and return the aggregated results, such as menu service, use group to distinguish multiple implementations of the same interface, now the consumer needs to call once from each group and return the result, and return the result after merging, so You can implement aggregated menu items. + +For relevant codes, please refer to [Samples in the dubbo project](https://github.com/apache/dubbo-samples/tree/master/2-advanced/dubbo-samples-merge) + +## scenes to be used + +Service Grouping and Multiple Versions + +## How to use + +### Search all groups + +```xml + +``` + +### Merge specified groups + +```xml + +``` +### Specify method merge + +Combine the results of the specified method, and other unspecified methods will only call one Group + +```xml + + + +``` +### A method is not merged + +One method does not combine results, others combine results + +```xml + + + +``` +### Specify merge strategy + +Specify the merge strategy, the default is to automatically match according to the return value type, if there are two combiners of the same type, you need to specify the name of the combiner [Merge result extension](../../../reference-manual/spi/ description/merger) + +```xml + + + +``` +### Specify merge method + +Specify the merge method to merge the specified method that returns the result of the call. The parameter type of the merge method must be the return result type itself + +```xml + + + +``` + +#### hint: +Supported since `2.1.0` version \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/isolation-executor.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/isolation-executor.md new file mode 100644 index 000000000000..bd6ef217b48d --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/isolation-executor.md @@ -0,0 +1,230 @@ +--- +type: docs +linkTitle: "Thread Pool Isolation" +title: "Thread Pool Isolation" +weight: 4 +description: "Provide a new thread pool management method for isolating thread pools between services" +--- + +## Feature description +A new thread pool management method enables the thread pools of each service in the provider application to be isolated and independent from each other. The exhaustion of the thread pool resources of a certain service will not affect other normal services. Support thread pool configurable, manually specified by the user. + +## scenes to be used + +## How to use + +Currently, it can be configured in the form of API, XML, and Annotation + +**Configuration parameters** +- `ApplicationConfig` adds `String executor-management-mode` parameter, the configuration values are `default` and `isolation`, and the default is `default`. + - `executor-management-mode = default` use the original **thread pool management mode with the protocol port as the granularity and sharing between services** + - `executor-management-mode = isolation` uses the newly added thread pool management method with **service triplet as granularity and isolation between services** +- `ServiceConfig` adds `Executor executor` parameter, **thread pool for isolation between services**, can be configured by the user to provide the thread pool you want, if not specified, it will be configured according to the protocol (` ProtocolConfig`) information to build a default thread pool for service isolation. + +> `ServiceConfig` adds the `Executor executor` configuration parameter to take effect only if `executor-management-mode = isolation` is specified. +### APIs +```java + public void test() { + // provider app + DubboBootstrap providerBootstrap = DubboBootstrap. newInstance(); + + ServiceConfig serviceConfig1 = new ServiceConfig(); + serviceConfig1.setInterface(DemoService.class); + serviceConfig1.setRef(new DemoServiceImpl()); + serviceConfig1.setVersion(version1); + // set executor1 for serviceConfig1, max threads is 10 + NamedThreadFactory threadFactory1 = new NamedThreadFactory("DemoService-executor"); + ExecutorService executor1 = Executors. newFixedThreadPool(10, threadFactory1); + serviceConfig1.setExecutor(executor1); + + ServiceConfig serviceConfig2 = new ServiceConfig(); + serviceConfig2.setInterface(HelloService.class); + serviceConfig2.setRef(new HelloServiceImpl()); + serviceConfig2.setVersion(version2); + // set executor2 for serviceConfig2, max threads is 100 + NamedThreadFactory threadFactory2 = new NamedThreadFactory("HelloService-executor"); + ExecutorService executor2 = Executors. newFixedThreadPool(100, threadFactory2); + serviceConfig2.setExecutor(executor2); + + ServiceConfig serviceConfig3 = new ServiceConfig(); + serviceConfig3.setInterface(HelloService.class); + serviceConfig3.setRef(new HelloServiceImpl()); + serviceConfig3.setVersion(version3); + // Because executor is not set for serviceConfig3, the default executor of serviceConfig3 is built using + // the threadpool parameter of the protocolConfig ( FixedThreadpool , max threads is 200) + serviceConfig3.setExecutor(null); + + // It takes effect only if [executor-management-mode=isolation] is configured + ApplicationConfig applicationConfig = new ApplicationConfig("provider-app"); + applicationConfig.setExecutorManagementMode("isolation"); + + providerBootstrap + .application(applicationConfig) + .registry(registryConfig) + // export with tri and dubbo protocol + .protocol(new ProtocolConfig("tri", 20001)) + .protocol(new ProtocolConfig("dubbo", 20002)) + .service(serviceConfig1) + .service(serviceConfig2) + .service(serviceConfig3); + + providerBootstrap.start(); + } +``` + +### XML +```xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +``` +### Annotation +```java +@Configuration +@EnableDubbo(scanBasePackages = "org.apache.dubbo.config.spring.isolation.spring.annotation.provider") +public class ProviderConfiguration { + @Bean + public RegistryConfig registryConfig() { + RegistryConfig registryConfig = new RegistryConfig(); + registryConfig.setAddress("zookeeper://127.0.0.1:2181"); + return registryConfig; + } + + // NOTE: we need config executor-management-mode="isolation" + @Bean + public ApplicationConfig applicationConfig() { + ApplicationConfig applicationConfig = new ApplicationConfig("provider-app"); + + applicationConfig.setExecutorManagementMode("isolation"); + return applicationConfig; + } + + // expose services with dubbo protocol + @Bean + public ProtocolConfig dubbo() { + ProtocolConfig protocolConfig = new ProtocolConfig("dubbo"); + return protocolConfig; + } + + // expose services with tri protocol + @Bean + public ProtocolConfig tri() { + ProtocolConfig protocolConfig = new ProtocolConfig("tri"); + return protocolConfig; + } + + // customized thread pool + @Bean("executor-demo-service") + public Executor demoServiceExecutor() { + return new DemoServiceExecutor(); + } + + // customized thread pool + @Bean("executor-hello-service") + public Executor helloServiceExecutor() { + return new HelloServiceExecutor(); + } +} +``` +```java +// customized thread pool +public class DemoServiceExecutor extends ThreadPoolExecutor { + public DemoServiceExecutor() { + super(10, 10, 60, TimeUnit. SECONDS, new LinkedBlockingDeque<>(), + new NamedThreadFactory("DemoServiceExecutor")); + } +} +``` + +```java +// customized thread pool +public class HelloServiceExecutor extends ThreadPoolExecutor { + public HelloServiceExecutor() { + super(100, 100, 60, TimeUnit. SECONDS, new LinkedBlockingDeque<>(), + new NamedThreadFactory("HelloServiceExecutor")); + } +} +``` +```java +// "executor-hello-service" is beanName +@DubboService(executor = "executor-demo-service", version = "1.0.0", group = "Group1") +public class DemoServiceImplV1 implements DemoService { + + @Override + public String sayName(String name) { + return "server name"; + } + + @Override + public Box getBox() { + return null; + } +} + +``` + +```java +// not set executor for this service, the default executor built using threadpool parameter of the protocolConfig +@DubboService(version = "3.0.0", group = "Group3") +public class HelloServiceImplV2 implements HelloService { + private static final Logger logger = LoggerFactory.getLogger(HelloServiceImplV2.class); + + @Override + public String sayHello(String name) { + return "server hello"; + } +} + +``` + +```java +@DubboService(executor = "executor-hello-service", version = "2.0.0", group = "Group2") +public class HelloServiceImplV3 implements HelloService { + private static final Logger logger = LoggerFactory.getLogger(HelloServiceImplV3.class); + + @Override + public String sayHello(String name) { + return "server hello"; + } +} +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/local-call.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/local-call.md new file mode 100644 index 000000000000..14aa6fb0100c --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/local-call.md @@ -0,0 +1,59 @@ +--- +type: docs +title: "Local call" +linkTitle: "Local call" +weight: 22 +description: "Local call in Dubbo" +--- + +## Feature description +The local call uses the injvm protocol, which is a pseudo-protocol. It does not open ports, does not initiate remote calls, and is only directly associated in the JVM, but executes Dubbo's Filter chain. + +## scenes to be used + +When we need to call a remote service, the remote service has not been developed yet, and similar services are implemented locally using the injvm protocol. When calling this service, we can call our local implementation service. + +## How to use + +### Define the injvm protocol +```xml + +``` + +### Set the default protocol + +```xml + +``` + +### Set service protocol + +```xml + +``` + +### Prioritize the use of injvm + +```xml + + +``` + +**or** + +```xml + + +``` + +#### Notice: +**Dubbo from `2.2.0`, each service will be exposed locally by default, and can be referenced locally without any configuration. If you do not want the service to be exposed remotely, you only need to set the protocol to injvm in the provider. ** + + +### Automatic exposure + +Starting with `2.2.0`, every service is exposed locally by default. When referencing services, local services are preferred by default. If you want to reference remote services, you can use the following configuration to force references to remote services. + +```xml + +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/local-mock.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/local-mock.md new file mode 100644 index 000000000000..fe40ed3bcdf1 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/local-mock.md @@ -0,0 +1,157 @@ +--- +type: docs +title: "Local Masquerade" +linkTitle: "Local camouflage" +weight: 10 +description: "Learn how to use local masquerade to achieve service degradation in Dubbo3" +--- + +## Feature description + +There is a mechanism in Dubbo3 to achieve lightweight service degradation, which is local masquerade[^1]. + +## scenes to be used + +Local masquerading is often used for service degradation. For example, for a verification service, when all the service providers hang up, if the service consumer initiates a remote call at this time, the call will fail and an `RpcException` will be thrown. + +In order to avoid such a situation where an exception is thrown directly, the client can use local masquerade to provide Mock data and return authorization failure. + +## How to use + +### Enable mock configuration + +Configured in the following way in the Spring XML configuration file: + +```xml + +``` + +or + +```xml + +``` + +Provide Mock implementation in the project [^2]: + +```java +package com.foo; +public class BarServiceMock implements BarService { + public String sayHello(String name) { + // You can fake fault-tolerant data, this method is only executed when RpcException occurs + return "fault tolerance data"; + } +} +``` + +### Use the return keyword to mock the return value + +Use `return` to return an object represented by a string as the return value of the Mock. Legal strings can be: +- *empty*: stands for empty, returns the default value of the basic type, the empty value of the collection class, and the empty object of the custom entity class [^3] +- *null*: return `null` +- *true*: returns `true` +- *false*: return `false` +- *JSON string*: returns the object obtained after deserializing the JSON string + +For example, if the consumer of the service often needs try-catch to catch exceptions, such as: + +```java +public class DemoService { + + public Offer findOffer(String offerId) { + Offer offer = null; + try { + offer = offerService. findOffer(offerId); + } catch (RpcException e) { + logger. error(e); + } + + return offer; + } +} +``` + +Then consider changing to a Mock implementation, and `return null` in the Mock implementation. If you just want to simply ignore exceptions, it is available in `2.0.11` and above: + +```xml + +``` + +### Use the throw keyword Mock to throw an exception + +Use `throw` to return an Exception object as the return value of the Mock. + +A default RPCException is thrown when the call fails: + +```xml + + +``` + +When an error occurs in the call, throw the specified Exception [^4]: + +```xml + + +``` + +### Use the force and fail keywords to configure the behavior of the Mock + +`force:` means to force the use of Mock behavior, in which case no remote calls will be made. + +`fail:` Consistent with the default behavior, the mock behavior is only used when an error occurs in the remote call. That is to say, it is actually possible not to use the `fail` keyword when configuring, but to use `throw` or `return` directly. + +Both `force:` and `fail:` are supported in combination with `throw` or `return`. + +Force a specified value to be returned: + +```xml + + +``` + +Force the specified exception to be thrown: + +```xml + + +``` + +The specified value is returned when the call fails: +```xml + + + + + +``` + +An exception is thrown when the call fails + +```xml + + + + + +``` + +### Configure Mock at method level + +Mock can be specified at the method level, assuming there are several methods on `com.foo.BarService`, we can specify Mock behavior for the `sayHello()` method separately. + +The specific configuration is as follows. In this example, whenever `sayHello()` is called, it is forced to return "fake": + +```xml + + + + +``` + +## Precautions + +[^1]: Mock is a subset of Stub, which is convenient for service providers to implement fault-tolerant logic on the client side. Because it is often necessary to perform fault-tolerant when RpcException (such as network failure, timeout, etc.) occurs, and when business exceptions (such as login Wrong username and password) does not require fault tolerance. If you use Stub, you may need to catch and rely on the RpcException class, but you can use Mock without relying on RpcException, because its agreement is to execute only when RpcException occurs. +[^2]: Next to the interface, put a Mock implementation that implements the BarService interface and has a no-argument constructor. At the same time, if the Mock class is not explicitly specified in the configuration file, then it is necessary to ensure that the fully qualified class name of the Mock class is in the form of `original fully qualified class name+Mock`, such as `com.foo.BarServiceMock`, otherwise it will be Mock will fail. +[^3]: If the return value is an entity class, then it will return an empty object with default values instead of `null`. +[^4]: Custom exceptions must have a constructor with `String` as the input parameter, which will be used to receive exception information. \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/local-stub.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/local-stub.md new file mode 100644 index 000000000000..9139d0faef52 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/local-stub.md @@ -0,0 +1,55 @@ +--- +type: docs +title: "Local Stub" +linkTitle: "Local Stub" +weight: 11 +description: "Understand the use of local stubs in Dubbo3 to execute part of the logic on the client" +--- +## Feature description: + +After the remote service, the client usually only has the interface, and the implementation is all on the server side, but the provider sometimes wants to execute some logic on the client side. + +![/user-guide/images/stub.jpg](/imgs/user/stub.jpg) + +## scenes to be used +Do ThreadLocal cache, verify parameters in advance, forge fault-tolerant data after call failure, etc. At this time, you need to bring a Stub in the API, and the client generates a Proxy instance, which will pass the Proxy to the Stub through the constructor [^1], and then pass the The Stub is exposed to the user, and the Stub can decide whether to call the Proxy. + +## How to use +### spring configuration file configuration + +```xml + +``` + +or + +```xml + +``` + +### Provide Stub implementation [^2] + +```java +package com.foo; +public class BarServiceStub implements BarService { + private final BarService barService; + + // The constructor passes in the real remote proxy object + public BarServiceStub(BarService barService){ + this. barService = barService; + } + + public String sayHello(String name) { + // This code is executed on the client side, you can do ThreadLocal local cache on the client side, or pre-verify whether the parameters are legal, etc. + try { + return barService.sayHello(name); + } catch (Exception e) { + // You are fault tolerant and can do any AOP interception + return "fault tolerance data"; + } + } +} +``` + +[^1]: Stub must have a constructor that can be passed to Proxy. +[^2]: Next to the interface put a Stub implementation that implements the BarService interface and has a constructor that passes in the remote BarService instance. \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/multi-protocols.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/multi-protocols.md new file mode 100644 index 000000000000..7fe2ca5a0ba5 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/multi-protocols.md @@ -0,0 +1,53 @@ +--- +type: docs +title: "Multi-protocol" +linkTitle: "Multi-protocol" +weight: 9 +description: "Configure multi-protocol in Dubbo" +--- +## Feature description +Dubbo allows multi-protocol configuration, supports different protocols on different services or supports multiple protocols on the same service at the same time. + +## scenes to be used + +## How to use + +### Different protocols for different services +Different services apply different protocols for transmission in terms of performance. For example, short connection protocols are used for large data, and long connection protocols are used for small data and large concurrency. + +```xml + + + + + + + + + + + + +``` + +### Multi-protocol exposed services +Needed to interoperate with http clients + +```xml + + + + + + + + + + +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/multi-registry.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/multi-registry.md new file mode 100644 index 000000000000..f5464bf998dc --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/multi-registry.md @@ -0,0 +1,87 @@ +--- +type: docs +title: "Multiple Registries" +linkTitle: "Multiple Registration Centers" +weight: 10 +description: "Register the same service to multiple registries in Dubbo" +--- +## Feature description +Dubbo supports the simultaneous registration of the same service to multiple registries, or the registration of different services to different registries, or even references to services with the same name registered on different registries at the same time. In addition, the registry is [^1] that supports custom extensions. +## scenes to be used + +## How to use +### Multi-registry registration + +For example: Some services of the Chinese website are too late to be deployed in Qingdao, and are only deployed in Hangzhou, while other applications in Qingdao need to reference this service, so the service can be registered to two registration centers at the same time. +```xml + + + + + + + + + +``` + +### Different services use different registries + +For example: some CRM services are specially designed for international websites, and some services are specially designed for Chinese websites. +```xml + + + + + + + + + + + +``` + +### Multiple Registry References + +For example: CRM needs to call the PC2 service of the Chinese station and the international station at the same time. PC2 is deployed in both the Chinese station and the international station. The interface and version number are the same, but the connected databases are different. +```xml + + + + + + + + + + + +``` + +If only the test environment temporarily needs to connect to two different registration centers, use vertical symbols to separate multiple different registration center addresses: + +```xml + + + + + + + + +``` + +[^1]: You can extend the registry by yourself, see: [Registry Extension](../../../reference-manual/spi/description/registry) \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/multi-versions.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/multi-versions.md new file mode 100644 index 000000000000..2554479c4896 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/multi-versions.md @@ -0,0 +1,50 @@ +--- +type: docs +title: "Service Version" +linkTitle: "Service version" +weight: 1 +description: "Configure multiple versions for the same service in Dubbo" +--- + +## Feature description +**Follow the steps below for version migration** + +1. During low-stress periods, first upgrade half of the providers to the new version +2. Upgrade all consumers to the new version +3. Then upgrade the remaining half of the providers to the new version + +#### Configuration +- Old and new versions of service providers +- New and old version service consumers + +## scenes to be used +When an interface is implemented and an incompatible upgrade occurs, the version number can be used for transition, and services with different version numbers do not refer to each other. + +## Reference use case + +[https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-version](https://github.com/apache/dubbo-samples/tree/master/2-advanced/dubbo-samples-version) + +## How to use +### service provider +Old version service provider configuration +```xml + +``` +New Version Service Provider Configuration +```xml + +``` +### Service Consumer +Old version service consumer configuration +```xml + +``` +New Version Service Consumer Configuration +```xml + +``` +### Does not distinguish between versions +If you don't need to distinguish between versions, you can configure it in the following way +```xml + +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/parameter-validation.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/parameter-validation.md new file mode 100644 index 000000000000..04dfb2414803 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/parameter-validation.md @@ -0,0 +1,196 @@ +--- +type: docs +title: "Parameter Validation" +linkTitle: "Parameter verification" +weight: 2 +description: "Parameter verification in dubbo3" +--- +## Feature description +The parameter verification function is implemented based on [JSR303](https://jcp.org/en/jsr/detail?id=303), users only need to identify the verification annotation of the JSR303 standard, and realize the verification by declaring the filter. + +#### Maven dependencies + +```xml + + javax.validation + validation-api + 1.0.0.GA + + + org.hibernate + hibernate-validator + 4.2.0.Final + +``` + +## scenes to be used + +When the server provides interface services to the outside, it solves various interface parameter verification problems. + +## Reference use case + +[https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-validation](https://github.com/apache/dubbo-samples/tree/master/2-advanced/dubbo-samples-validation) + +## How to use + +### Parameter annotation example + +```java +import java.io.Serializable; +import java.util.Date; + +import javax.validation.constraints.Future; +import javax.validation.constraints.Max; +import javax.validation.constraints.Min; +import javax.validation.constraints.NotNull; +import javax.validation.constraints.Past; +import javax.validation.constraints.Pattern; +import javax.validation.constraints.Size; + +public class ValidationParameter implements Serializable { + private static final long serialVersionUID = 7158911668568000392L; + + @NotNull // not allowed to be null + @Size(min = 1, max = 20) // length or size range + private String name; + + @NotNull(groups = ValidationService.Save.class) // It is not allowed to be empty when saving, and it is allowed to be empty when updating, indicating that the field will not be updated + @Pattern(regexp = "^\\s*\\w+(?:\\.{0,1}[\\w-]+)*@[a-zA-Z0-9]+(?:[- .][a-zA-Z0-9]+)*\\.[a-zA-Z]+\\s*$") + private String email; + + @Min(18) // minimum value + @Max(100) // maximum value + private int age; + + @Past // must be a past time + private Date loginDate; + + @Future // must be a future time + private Date expiryDate; + + public String getName() { + return name; + } + + public void setName(String name) { + this.name = name; + } + + public String getEmail() { + return email; + } + + public void setEmail(String email) { + this.email = email; + } + + public int getAge() { + return age; + } + + public void setAge(int age) { + this. age = age; + } + + public Date getLoginDate() { + return loginDate; + } + + public void setLoginDate(Date loginDate) { + this. loginDate = loginDate; + } + + public Date getExpiryDate() { + return expiryDate; + } + + public void setExpiryDate(Date expiryDate) { + this.expiryDate = expiryDate; + } +} +``` + +### Group verification example + +```java +public interface ValidationService { // By default, validation scenarios can be distinguished by service interface, such as: @NotNull(groups = ValidationService.class) + @interface Save{} // The interface with the same name as the method, the first letter is capitalized, used to distinguish validation scenarios, such as: @NotNull(groups = ValidationService.Save.class), optional + void save(ValidationParameter parameter); + void update(ValidationParameter parameter); +} +``` + +### Association Validation Example + +```java +import javax.validation.GroupSequence; + +public interface ValidationService { + @GroupSequence(Update.class) // Verify Update group rules at the same time + @interface Save{} + void save(ValidationParameter parameter); + + @interface Update{} + void update(ValidationParameter parameter); +} +``` + +### Parameter validation example + +```java +import javax.validation.constraints.Min; +import javax.validation.constraints.NotNull; + +public interface ValidationService { + void save(@NotNull ValidationParameter parameter); // validation parameter is not empty + void delete(@Min(1) int id); // directly verify the basic type parameters +} +``` + +### Validate parameters on the client side + +```xml + +``` + +### Validate parameters on the server side + +```xml + +``` + +> **Dubbo supports hibernate-validator version <=6.x by default, if you use hibernate-validator 7.x version, please declare the validation parameter as jvalidatorNew** + +### Verify exception information + +```java +import javax.validation.ConstraintViolationException; +import javax.validation.ConstraintViolationException; + +import org.springframework.context.support.ClassPathXmlApplicationContext; + +import org.apache.dubbo.examples.validation.api.ValidationParameter; +import org.apache.dubbo.examples.validation.api.ValidationService; +import org.apache.dubbo.rpc.RpcException; + +public class ValidationConsumer { + public static void main(String[] args) throws Exception { + String config = ValidationConsumer.class.getPackage().getName().replace('.', '/') + "/validation-consumer.xml"; + ClassPathXmlApplicationContext context = new ClassPathXmlApplicationContext(config); + context. start(); + ValidationService validationService = (ValidationService)context.getBean("validationService"); + // Error + try { + parameter = new ValidationParameter(); + validationService. save(parameter); + System.out.println("Validation ERROR"); + } catch (RpcException e) { // What is thrown is RpcException + ConstraintViolationException ve = (ConstraintViolationException) e.getCause(); // A ConstraintViolationException is embedded in it + Set> violations = ve.getConstraintViolations(); // You can get a collection of verification error details + System.out.println(violations); + } + } +} +``` + +> **The validation method can be extended, see [Validation Extension](../../../reference-manual/spi/description/validation) in the developer manual for the extension method** \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/port-unification.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/port-unification.md new file mode 100644 index 000000000000..66e9b3e6d275 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/port-unification.md @@ -0,0 +1,125 @@ +--- +type: docs +title: "Port Protocol Multiplexing" +linkTitle: "Port protocol multiplexing" +weight: 1 +description: "dubbo3 port protocol multiplexing, single port multi-protocol support" +--- +## Feature description +By configuring the protocol, dubbo3 can support port protocol multiplexing. +For example, after using the Triple protocol to enable port multiplexing, you can add +Dubbo protocol support, and Qos protocol support. These protocols are identified by a unified port multiplexing +It can be used for service protocol migration, which is processed by the server, and can save ports and related resources and reduce the complexity of operation and maintenance. + +![pu-server-image1](/imgs/blog/pu-server/pu-server-flow.png) + +- In the service creation phase, different Protocol objects are created for export by obtaining the protocol configuration exported by the service from the Config layer. in the process of exporting + In , if it is not the first time to create a server with port multiplexing, the Exchanger will save the data passed by the protocol layer to the server for subsequent processing of messages of this protocol type. + +- When the client's message is delivered, it will first be passed to the ProtocolDetector through the server. If the identification is completed, the client will be marked as the corresponding protocol. And configure the corresponding processing logic through WireProtocol, and finally hand it over to ChannelOperator to complete the binding of the underlying IO framework and the processing logic of the corresponding Dubbo framework. + +- After the above protocol identification is completed, the Channel has determined how to process the remote client message, and it can be processed through the corresponding ServerPipeline (the processing thread of the message will also be determined according to the configuration information during the processing). + + +## Reference use case +[https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-port-unification](https://github.com/apache/dubbo-samples/tree/master/3-extensions/ protocol/dubbo-samples-port-unification) + + +## configuration method + +For the configuration method supported by Dubbo, please refer to [Configuration Instructions](https://dubbo.apache.org/zh/docs3-v2/java-sdk/reference-manual/config/) + +### Service multi-protocol export + +The ext-protocol parameter supports configuring multiple different protocols, and the protocols are separated by ",". + +#### xml configuration + +```xml + + + + + + +``` + +#### API configuration + +```java +ProtocolConfig config = new ProtocolConfig(CommonConstants.TRIPLE, -1); + +config.setExtProtocol(CommonConstants.DUBBO+","); +``` + +#### yaml configuration + +```yaml +dubbo: + application: + name: dubbo-springboot-demo-provider + protocol: + name: tri + port: -1 + ext-protocol: dubbo, +``` + +#### properties configuration +```properties +dubbo.protocol.name=tri +dubbo.protocol.ext-protocol=dubbo, +dubbo.protocol.port=20880 +``` + +### Qos access + +#### Qos module import + +```xml + + org.apache.dubbo + dubbo-qos + +``` + +After importing the Qos module, related configuration items can be configured by referring to [Qos Operation Manual](https://dubbo.apache.org/zh/docs3-v2/java-sdk/reference-manual/qos/overview/) . + +By default, the Qos service based on port multiplexing is started after the module is imported. + +## How to use + +### Qos used + +When the Qos protocol is connected to the port multiplexing scenario, after the connection is established, the client needs to send a message to the server first. Compared with the Qos protocol that provides services through a single port, the port multiplexing version of the Qos protocol handles the telnet connection. In some cases, the user needs to perform some operations to complete the protocol identification (choose one of the two). + +1. Call the command directly + + The recognition can also be completed by directly calling the commands supported by telnet. If the user is not familiar with it, the help command can be called to complete the recognition. + + ![pu-server-image2](/imgs/blog/pu-server/qos-telnet-directcall.png) + +2. Send telnet command to identify + + After establishing a connection through the telnet command, perform the following steps: + + 1. Use crtl + "]" to enter the telnet interactive interface (telnet default escape character) + 2. Call "send ayt" to send a special identification field to the server (a special field of the telnet protocol) + 3. Press Enter to complete the message sending and enter the interactive interface of dubbo + + ![pu-server-imgs3](/imgs/blog/pu-server/qos-telnet-sendayt.png) + + +### Service reference + +Based on the example in [dubbo-samples-port-unification](https://github.com/apache/dubbo-samples/tree/master/3-extensions/protocol/dubbo-samples-port-unification), quote The configuration of services of different protocols and non-port multiplexing is consistent. Next, the URL information in the calling process is output through the InvokerListener on the Consumer side. + +```java +ReferenceConfig reference = new ReferenceConfig<>(); +reference.setInterface(GreetingService.class); +reference.setListener("consumer"); +reference.setProtocol(this.protocol); +// reference.setProtocol(CommonConstants.DUBBO); +// reference.setProtocol(CommonConstants.TRIPLE); +``` + +![pu-server-imgs4](/imgs/blog/pu-server/reference-service.png) \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/preflight-check.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/preflight-check.md new file mode 100644 index 000000000000..ae51b3bb4b06 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/preflight-check.md @@ -0,0 +1,67 @@ +--- +type: docs +title: "Check at startup" +linkTitle: "Check at startup" +weight: 1 +description: "Check that dependent services are available at startup" +--- +## Feature description +By default, Dubbo will check whether the dependent service is available at startup, and will throw an exception when it is unavailable, preventing Spring initialization from completing, so that problems can be detected early when going online. The default `check="true"`. + +Checking can be turned off by `check="false"`. For example, when testing, some services do not care, or there is a circular dependency, and one of them must be started first. + +In addition, if your Spring container is lazy-loaded, or if you delay the reference service through API programming, please turn off check, otherwise when the service is temporarily unavailable, an exception will be thrown and a null reference will be obtained. If `check="false"`, always Yes, it will return the reference, and when the service is restored, it can be connected automatically. + +## scenes to be used + +- One-way dependency: with dependency (recommended default setting) and without dependency (check=false can be set) +- Interdependence: that is, circular dependency, (it is not recommended to set check=false) +- Lazy loading handling + +> check is only used to check at startup, if there is no corresponding dependency at runtime, an error will still be reported. + +## How to use + +### via spring configuration file + +Turn off startup checks for a service + +```xml + +``` + +Turn off startup checks for all services + +```xml + +``` + +Turn off registry checks at startup + +```xml + +``` + +### via dubbo.properties + +```properties +dubbo.reference.com.foo.BarService.check=false +dubbo.consumer.check=false +dubbo.registry.check=false +``` + +### via the -D parameter + +```sh +java -Ddubbo.reference.com.foo.BarService.check=false +java -Ddubbo.consumer.check=false +java -Ddubbo.registry.check=false +``` + +## Meaning of configuration + +`dubbo.reference.com.foo.BarService.check`, overrides the check value of the reference of `com.foo.BarService`, even if there is a statement in the configuration, it will be overwritten. + +`dubbo.consumer.check=false` is the default value of `check` for setting reference. If there is an explicit statement in the configuration, such as: ``, it will not be affected influences. + +`dubbo.registry.check=false`, the first two means that the subscription is successful, but whether the provider list is empty or whether an error is reported, if the registration subscription fails, it is also allowed to start, you need to use this option, and will retry periodically in the background . \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/reactive.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/reactive.md new file mode 100644 index 000000000000..fd93a918bb4e --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/reactive.md @@ -0,0 +1,235 @@ +--- +type: docs +title: "Reactive Programming" +linkTitle: "Reactive Programming" +weight: 1 +description: "Using the Reactive API to operate Triple streaming calls" +--- + +## Feature description + +This feature is implemented based on the Triple protocol and Project Reactor, and is supported in versions above `3.1.0`. Users only need to write the IDL file and specify the corresponding Generator of the protobuf plug-in to generate and use the Stub code that supports the responsive API. + +There are four call modes, namely OneToOne, OneToMany, ManyToOne, and ManyToMany, corresponding to Unary calls, server streams, client streams, and bidirectional streams. In the implementation of Reactor, One corresponds to Mono, and Many corresponds to Flux. + +#### background + +Reactive Stream provides a set of standard asynchronous stream processing APIs. While allowing applications to write event-driven programs, it also ensures node stability through BackPressure. The Triple protocol adds support for streaming scenarios to the Dubbo framework at the communication protocol level. On this basis, it can realize the business requirements of the upper layer including large file transmission and push mechanisms. + +The combined mode of Dubbo + Reactive Stream Stub can bring users the most convenient way of streaming and improve the asynchronous performance of the whole link. + +## Reference use case + +[https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-triple-reactor](https://github.com/apache/dubbo-samples/tree/master/3-extensions/ protocol/dubbo-samples-triple-reactor) + +## scenes to be used + +The system needs to handle a large number of concurrent requests without overloading any servers. Systems with large numbers of users providing real-time data and want to ensure that the system can handle the load without crashing or slowing down. + +## How to use + +For Triple usage and configuration, please refer to [Using Triple in IDL](https://dubbo.apache.org/zh/docs3-v2/java-sdk/reference-manual/protocol/triple/idl/), and ensure that the Dubbo version> = 3.1.0. + +### Add the necessary dependencies + +To use Reactor Triple, you need to add the following additional dependencies. + +```xml + + org.reactivestreams + reactive-streams + + + io.projectreactor + reactor-core + +``` + +### Setup protobuf Maven plugin + +Just change mainClass to `org.apache.dubbo.gen.tri.reactive.ReactorDubbo3TripleGenerator` and make sure `${compiler.version}` >= 3.1.0 + +```xml + + + + org.xolstice.maven.plugins + protobuf-maven-plugin + 0.6.1 + + com.google.protobuf:protoc:${protoc.version}:exe:${os.detected.classifier} + + grpc-java + io.grpc:protoc-gen-grpc-java:${grpc.version}:exe:${os.detected.classifier} + + + + dubbo + org.apache.dubbo + dubbo-compiler + ${compiler.version} + org.apache.dubbo.gen.tri.reactive.ReactorDubbo3TripleGenerator + + + + + + + compile + + + + + + +``` + +### Write and compile the IDL file + +The writing of the IDL file is completely consistent with the native Triple protocol, and the corresponding code will be seen in the `target/generated-sources/protobuf/java` directory by default after compilation. + +```protobuf +syntax = "proto3"; + +option java_multiple_files = true; + +package org.apache.dubbo.samples.triple.reactor; + +// The request message containing the user's name. +message GreeterRequest { + string name = 1; +} + +// The response message containing the greetings +message GreeterReply { + string message = 1; +} + +service GreeterService { + + rpc greetOneToOne(GreeterRequest) returns (GreeterReply); + + rpc greetOneToMany(GreeterRequest) returns (stream GreeterReply); + + rpc greetManyToOne(stream GreeterRequest) returns (GreeterReply); + + rpc greetManyToMany(stream GreeterRequest) returns (stream GreeterReply); +} +``` + +### use + +1. Add server interface implementation + +```java +package org.apache.dubbo.samples.triple.reactor.impl; + +import org.apache.dubbo.samples.triple.reactor.DubboGreeterServiceTriple; +import org.apache.dubbo.samples.triple.reactor.GreeterReply; +import org.apache.dubbo.samples.triple.reactor.GreeterRequest; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; +import reactor.core.publisher.Flux; + +public class GreeterServiceImpl extends DubboGreeterServiceTriple.GreeterServiceImplBase { + + private static final Logger LOGGER = LoggerFactory. getLogger(GreeterServiceImpl. class); + + @Override + public Flux greetManyToMany(Flux request) { + return request.doOnNext(req -> LOGGER.info("greetManyToMany get data: {}", req)) + .map(req -> GreeterReply. newBuilder(). setMessage(req. getName() + " -> server get"). build()) + .doOnNext(res -> LOGGER.info("greetManyToMany response data: {}", res)); + } +} +``` + +2. Add the server interface startup class + +```java +package org.apache.dubbo.samples.triple.reactor; + +import org.apache.dubbo.common.constants.CommonConstants; +import org.apache.dubbo.config.ApplicationConfig; +import org.apache.dubbo.config.ProtocolConfig; +import org.apache.dubbo.config.RegistryConfig; +import org.apache.dubbo.config.ServiceConfig; +import org.apache.dubbo.config.bootstrap.DubboBootstrap; +import org.apache.dubbo.samples.triple.reactor.impl.GreeterServiceImpl; + +public class ReactorServer { + + private static final int PORT = 50052; + + public static void main(String[] args) { + ServiceConfig reactorService = new ServiceConfig<>(); + reactorService.setInterface(GreeterService.class); + reactorService.setRef(new GreeterServiceImpl()); + + DubboBootstrap bootstrap = DubboBootstrap. getInstance(); + bootstrap. application(new ApplicationConfig("tri-reactor-stub-server")) + .registry(new RegistryConfig("zookeeper://127.0.0.1:2181")) + .protocol(new ProtocolConfig(CommonConstants.TRIPLE, PORT)) + .service(reactorService) + .start(); + } +} +``` + +3. Add client startup class and consumer program + +```java +package org.apache.dubbo.samples.triple.reactor; + +import org.apache.dubbo.common.constants.CommonConstants; +import org.apache.dubbo.config.ApplicationConfig; +import org.apache.dubbo.config.ReferenceConfig; +import org.apache.dubbo.config.RegistryConfig; +import org.apache.dubbo.config.bootstrap.DubboBootstrap; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; +import reactor.core.publisher.Flux; +import reactor.core.publisher.Mono; + +import java.io.IOException; + +public class ReactorConsumer { + + private static final Logger LOGGER = LoggerFactory. getLogger(ReactorConsumer. class); + + private final GreeterService greeterService; + + public ReactorConsumer() { + ReferenceConfig referenceConfig = new ReferenceConfig<>(); + referenceConfig.setInterface(GreeterService.class); + referenceConfig.setProtocol(CommonConstants.TRIPLE); + referenceConfig.setProxy(CommonConstants.NATIVE_STUB); + referenceConfig.setTimeout(10000); + + DubboBootstrap bootstrap = DubboBootstrap. getInstance(); + bootstrap. application(new ApplicationConfig("tri-reactor-stub-server")) + .registry(new RegistryConfig("zookeeper://127.0.0.1:2181")) + .reference(referenceConfig) + .start(); + GreeterService greeterService = referenceConfig. get(); + } + + public static void main(String[] args) throws IOException { + ReactorConsumer reactorConsumer = new ReactorConsumer(); + reactorConsumer.consumeManyToMany(); + System.in.read(); + } + + private void consumeManyToMany() { + greeterService. greetManyToMany(Flux. range(1, 10) + .map(num-> + GreeterRequest.newBuilder().setName(String.valueOf(num)).build()) + .doOnNext(req -> LOGGER.info("consumeManyToMany request data: {}", req))) + .subscribe(res -> LOGGER.info("consumeManyToMany get response: {}", res)); + } +} +``` + +4. Start the server + +5. Start the consumer \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/registry-only.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/registry-only.md new file mode 100644 index 000000000000..1f4b818c96fc --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/registry-only.md @@ -0,0 +1,27 @@ +--- +type: docs +title: "Sign Up Only" +linkTitle: "Sign up only" +weight: 41 +description: "Only register but not subscribe" +--- +## Feature description +If there are two mirroring environments and two registries, one service is only deployed in one of the registries, and the other registry has not yet been deployed, and other applications in the two registries need to rely on this service. At this time, the service provider can only register the service to another registration center, but not subscribe to the service from another registration center. + + +## scenes to be used + +## How to use +### Disable subscription configuration + +```xml + + +``` + +**or** + +```xml + + +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/service-downgrade.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/service-downgrade.md new file mode 100644 index 000000000000..803f7e3514d3 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/service-downgrade.md @@ -0,0 +1,86 @@ +--- +type: docs +title: "Service Downgrade" +linkTitle: "Service Downgrade" +weight: 3 +description: "Downgrade Dubbo service" +--- + +## Feature description +It is recommended to use relevant current limiting and downgrading components (such as [Sentinel](https://sentinelguard.io/zh-cn/docs/open-source-framework-integrations.html)) to achieve the best experience. Reference example practice: [Microservice Governance/Limit and Downgrade](/zh/overview/tasks/ecosystem/rate-limit/) + +Service degradation refers to the emergency treatment of service degradation under abnormal circumstances. + +## scenes to be used + +- When the load of a certain service or interface exceeds the maximum carrying capacity range, downgrade emergency treatment is required to avoid system crash +- When a non-critical service or interface called is temporarily unavailable, simulated data or null is returned, and the business can continue to be available +- Downgrade non-core business services or interfaces, free up system resources, and try to ensure the normal operation of core business +- When an upstream basic service times out or is unavailable, execute a downgrade plan that can respond quickly to avoid the overall avalanche of services + +## How to use + +Take xml configuration as an example: (configuration through annotations is similar) + +### 1. Configure `mock="true"` +example: +```xml + +``` +This method requires an implementation class with the class name + `Mock` suffix under the same package, that is, there is a `DemoServiceMock` class under the `com.xxx.service` package. + +### 2. Configure `mock="com.xxx.service.DemoServiceMock"` +example: +```xml + +``` +This method specifies the full path of the Mock class. + +### 3. Configure `mock="[fail|force]return|throw xxx"` + +* The fail or force keyword is optional, indicating that the call fails or does not call to enforce the mock method, if no keyword is specified, the default is fail +* return indicates the specified return result, and throw indicates that the specified exception is thrown +* xxx is parsed according to the return type of the interface, you can specify the return value or throw a custom exception + +example: +```xml + +``` + +```xml + +``` + +```xml + +``` + +```xml + +``` + +```xml + +``` + +```xml + +``` + +### 4. Use with dubbo-admin + +* Introduce `dubbo-mock-admin`< /a>dependency + +* Set the JVM parameters when the application consumer starts, `-Denable.dubbo.admin.mock=true` + +* Start dubbo-admin, set the Mock rule under the service Mock->rule configuration menu + +Set rules in the dimension of service methods, set return mock data, and dynamically enable/disable rules + +## Precautions + +When Dubbo starts, it will check the configuration. When the configuration of the mock attribute value is wrong, it will fail to start. You can troubleshoot according to the error message + +- The configuration format is wrong, such as `return+null` will report an error, and it will be treated as a mock type. `return` can be omitted or followed by a space followed by the return value + +- Type not found error, such as custom mock class, throw custom exception, please check if the type exists or if there is a typo \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/service-group.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/service-group.md new file mode 100644 index 000000000000..e19de825b108 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/service-group.md @@ -0,0 +1,169 @@ +--- +type: docs +title: "Service Group" +linkTitle: "Service Group" +weight: 2 +description: "Use service groups to differentiate between different implementations of a service interface" +--- + +## Feature description +The same interface can use service grouping to distinguish different implementation methods for different business scenarios, different usage requirements, or different functional modules. At the same time, the services provided by these different implementations can coexist and support mutual calls. + +## scenes to be used +When an interface has multiple implementations, it can be distinguished by group. + +## Reference use case + +[https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-group](https://github.com/apache/dubbo-samples/tree/master/2-advanced/dubbo-samples-group) + +## How to use + +### Annotation configuration + +#### Service provider (annotation configuration) + +Use @DubboService annotation, add group parameter + +```java +@DubboService(group = "demo") +public class DemoServiceImpl implements DemoService { + ... +} + +@DubboService(group = "demo2") +public class Demo2ServiceImpl implements DemoService { + ... +} +``` + +Start the Dubbo service, and you can see services with the same service name and different groups in the registry. Taking Nacos as the registry as an example, the following content is displayed: + +![image-service-group-1.png](/imgs/blog/service-group-1.png) + +#### Service consumer (annotation configuration) + +Use @DubboReference annotation to add group parameter + +```java +@DubboReference(group = "demo") +private DemoService demoService; + +@DubboReference(group = "demo2") +private DemoService demoService2; + +//group value is *, the identifier matches any service group +@DubboReference(group = "*") +private DemoService demoService2; +``` + +After starting the Dubbo service, you can see the references of the same service name in different groups in the registration center. Taking Nacos as the registration center as an example, the following content is displayed: +![image-service-group-2.png](/imgs/blog/service-group-2.png) + +### xml configuration + +#### Service provider (xml configuration) + +Use tag, add group parameter + +```xml + + +... + + + +... + +``` + +Start the Dubbo service, and you can see services with the same service name and different groups in the registry. Taking Nacos as the registry as an example, the following content is displayed: + +![image-service-group-1.png](/imgs/blog/service-group-1.png) + +#### Service consumer (xml configuration) + +Use annotation to add group parameter + +```xml + + + ... + + + + + + + + ... + +``` + +After starting the Dubbo service, you can see the references of the same service name in different groups in the registration center. Taking Nacos as the registration center as an example, the following content is displayed: + +![image-service-group-2.png](/imgs/blog/service-group-2.png) + +### API configuration + +#### Service provider (API configuration) + +Use org.apache.dubbo.config.ServiceConfig class, add group parameter + +```java +// ServiceConfig is a heavy object, which internally encapsulates the connection with the registration center and opens the service port +// Please cache by yourself, otherwise it may cause memory and connection leaks +ServiceConfig service = new ServiceConfig<>(); +service.setInterface(DemoService.class); +service.setGroup("demo"); +... + +ServiceConfig service2 = new ServiceConfig<>(); +service.setInterface(DemoService.class); +service.setGroup("demo2"); +... +``` + +Start the Dubbo service, and you can see services with the same service name and different groups in the registry. Taking Nacos as the registry as an example, the following content is displayed: + +![image-service-group-1.png](/imgs/blog/service-group-1.png) + +#### Service consumer (API configuration) + +Use org.apache.dubbo.config.ReferenceConfig, add group parameter + +```java +// ReferenceConfig is a heavy object, which internally encapsulates the connection with the registration center and opens the service port +// Please cache by yourself, otherwise it may cause memory and connection leaks +ReferenceConfig reference = new ReferenceConfig<>(); +reference.setInterface(DemoService.class); +reference.setGroup("demo"); +... + +ReferenceConfig reference2 = new ReferenceConfig<>(); +reference2.setInterface(DemoService.class); +reference2.setGroup("demo2"); +... + +ReferenceConfig reference3 = new ReferenceConfig<>(); +reference3.setInterface(DemoService.class); +reference3.setGroup("*"); +... + +``` +After starting the Dubbo service, you can see the references of the same service name in different groups in the registration center. Taking Nacos as the registration center as an example, the following content is displayed: +![image-service-group-2.png](/imgs/blog/service-group-2.png) + + +> Always *call** only one available group implementation \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/specify-ip.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/specify-ip.md new file mode 100644 index 000000000000..93c7ac87f4fc --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/specify-ip.md @@ -0,0 +1,103 @@ +--- +type: docs +title: "Dynamic IP call" +linkTitle: "Dynamic IP call at runtime" +weight: 5 +description: "Specify the target IP of this call before initiating a Dubbo call" +--- +## Feature description +Use the extension of Dubbo to realize the specified IP call. + +## scenes to be used + +When initiating a request, you need to specify the server for this call, such as message callback, traffic isolation, etc. + +## How to use + +### Plugin dependencies + +Adapt to Dubbo 3 version + +```xml + + org.apache.dubbo.extensions + dubbo-cluster-specify-address-dubbo3 + 1.0.0 + +``` + +Adapt to Dubbo 2 version + +```xml + + org.apache.dubbo.extensions + dubbo-cluster-specify-address-dubbo2 + 1.0.0 + +``` + +### call example + +```java +ReferenceConfig referenceConfig = new ReferenceConfig<>(); +// ...init +DemoService demoService = referenceConfig. get(); + +// for invoke +// 1. find 10.10.10.10:20880 exist +// 2. if not exist, create a invoker to 10.10.10.10:20880 if `needToCreate` is true (only support in Dubbo 3.x's implementation) +UserSpecifiedAddressUtil.setAddress(new Address("10.10.10.10", 20880, true)); +demoService.sayHello("world"); + + +// for invoke +// 1. find 10.10.10.10:any exist +// 2. if not exist, create a invoker to 10.10.10.10:20880 if `needToCreate` is true (only support in Dubbo 3.x's implementation) +UserSpecifiedAddressUtil.setAddress(new Address("10.10.10.10", 0, true)); +demoService.sayHello("world"); +``` + +### Parameter Description + +Parameters specifying an IP call wrap around an `Address` object. The parameter type reference is as follows: + +```java +package org.apache.dubbo.rpc.cluster.specifyaddress; + +public class Address implements Serializable { + // ip - priority: 3 + private String ip; + + // ip+port - priority: 2 + private int port; + + // address - priority: 1 + private URL urlAddress; + + private boolean needToCreate = false; + + // ignore setter and getter +} +``` + +1. `urlAddress` is the highest priority, if the URL address of the target is specified, it will be used first. (no longer matches follow-up) +2. ip + port (non-0 port) is the second priority, and will be matched from the addresses that have been pushed by the registration center. (no longer matches follow-up) +3. IP is the third priority, and it will be matched from the addresses that have been pushed by the registration center. + +In particular, if `needToCreate` is specified as `true`, an invoker will be automatically built according to the parameters passed in. For addresses specified by specifying ip ( + port ), +It will automatically use the parameter of the first address in the registry to create the template; if there is no address, it will be automatically created based on the Dubbo protocol. +To customize the logic of creating invoker, please implement `org.apache.dubbo.rpc.cluster.specifyaddress.UserSpecifiedServiceAddressBuilder` SPI interface. (This function is only supported by **Dubbo 3 implementation**) + +Pass the `UserSpecifiedAddressUtil` tool class to the Dubbo framework before constructing the `Address` parameter for each request. + +```java +package org.apache.dubbo.rpc.cluster.specifyaddress; + +public class UserSpecifiedAddressUtil { + + public static void setAddress(Address address) { ... } + +} +``` + +> **Must be set every time, and the call must be initiated immediately after setting**, if there is an interceptor error (remove this value in the Dubbo framework is performed during the address selection process), it is recommended to set null to avoid ThreadLocal memory leaks that will affect the follow-up transfer. \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/streaming.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/streaming.md new file mode 100644 index 000000000000..3e0f865302ca --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/streaming.md @@ -0,0 +1,9 @@ +--- +type: docs +title: "Stream Communication" +linkTitle: "Stream Communication" +weight: 4 +description: "Stream communication based on Triple protocol" +--- + +TBD \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/subscribe-only.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/subscribe-only.md new file mode 100644 index 000000000000..3113ec6848ca --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/subscribe-only.md @@ -0,0 +1,27 @@ +--- +type: docs +title: "Subscription Only" +linkTitle: "Subscription Only" +weight: 6 +description: "Only subscribe without registration" +--- +## Feature description + +In order to facilitate development and testing, a registration center that is available for all services is often shared offline. At this time, if a service provider under development registers, it may affect the normal operation of consumers. + +The service provider developer can only subscribe to the service (the developed service may depend on other services), without registering the service under development, and test the service under development through direct connection. + +![/user-guide/images/subscribe-only.jpg](/imgs/user/subscribe-only.jpg) +## scenes to be used +## How to use + +### Disable registration configuration + +```xml + +``` +**or** + +```xml + +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/transaction.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/transaction.md new file mode 100644 index 000000000000..8e64c895f3c8 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/service/transaction.md @@ -0,0 +1,397 @@ +--- +type: docs +title: "Distributed Transactions" +linkTitle: "Distributed Transaction" +weight: 1 +description: "Use distributed transactions in Dubbo" +--- + +## How to use + +### **First step** + +First visit: [https://seata.io/zh-cn/blog/download.html](https://seata.io/zh-cn/blog/download.html) + +Download the seata1.5.2 service we need to use + +### **Second step** + +1. Add the undo_log table to your database participating in global transactions (TCC, SAGA, XA can skip this step) + +```sql +-- for AT mode you must to init this sql for you business database. the seata server not need it. +CREATE TABLE IF NOT EXISTS `undo_log` +( + `branch_id` BIGINT(20) NOT NULL COMMENT 'branch transaction id', + `xid` VARCHAR(100) NOT NULL COMMENT 'global transaction id', + `context` VARCHAR(128) NOT NULL COMMENT 'undo_log context, such as serialization', + `rollback_info` LONGBLOB NOT NULL COMMENT 'rollback info', + `log_status` INT(11) NOT NULL COMMENT '0: normal status,1: defense status', + `log_created` DATETIME(6) NOT NULL COMMENT 'create datetime', + `log_modified` DATETIME(6) NOT NULL COMMENT 'modify datetime', + UNIQUE KEY `ux_undo_log` (`xid`, `branch_id`) +) ENGINE = InnoDB + AUTO_INCREMENT = 1 + DEFAULT CHARSET = utf8 COMMENT = 'AT transaction mode undo table'; +``` + +2. Create a library named seata in your mysql database, and use the following sql + +```sql +-- -------------------------------- The script used when storeMode is 'db' ------- ------------------------- +-- the table to store GlobalSession data +CREATE TABLE IF NOT EXISTS `global_table` +( + `xid` VARCHAR(128) NOT NULL, + `transaction_id` BIGINT, + `status` TINYINT NOT NULL, + `application_id` VARCHAR(32), + `transaction_service_group` VARCHAR(32), + `transaction_name` VARCHAR(128), + `timeout` INT, + `begin_time` BIGINT, + `application_data` VARCHAR(2000), + `gmt_create` DATETIME, + `gmt_modified` DATETIME, + PRIMARY KEY (`xid`), + KEY `idx_gmt_modified_status` (`gmt_modified`, `status`), + KEY `idx_transaction_id` (`transaction_id`) +) ENGINE = InnoDB + DEFAULT CHARSET = utf8; + +-- the table to store BranchSession data +CREATE TABLE IF NOT EXISTS `branch_table` +( + `branch_id` BIGINT NOT NULL, + `xid` VARCHAR(128) NOT NULL, + `transaction_id` BIGINT, + `resource_group_id` VARCHAR(32), + `resource_id` VARCHAR(256), + `branch_type` VARCHAR(8), + `status` TINYINT, + `client_id` VARCHAR(64), + `application_data` VARCHAR(2000), + `gmt_create` DATETIME(6), + `gmt_modified` DATETIME(6), + PRIMARY KEY (`branch_id`), + KEY `idx_xid` (`xid`) +) ENGINE = InnoDB + DEFAULT CHARSET = utf8; + +-- the table to store lock data +CREATE TABLE IF NOT EXISTS `lock_table` +( + `row_key` VARCHAR(128) NOT NULL, + `xid` VARCHAR(96), + `transaction_id` BIGINT, + `branch_id` BIGINT NOT NULL, + `resource_id` VARCHAR(256), + `table_name` VARCHAR(32), + `pk` VARCHAR(36), + `gmt_create` DATETIME, + `gmt_modified` DATETIME, + PRIMARY KEY (`row_key`), + KEY `idx_branch_id` (`branch_id`) +) ENGINE = InnoDB + DEFAULT CHARSET = utf8; +``` + +### **third step** + +Introduce seata dependency into your project + +spring-boot application: + +``` + + io.seata + seata-spring-boot-starter + 1.5.2 + +``` + +spring application: + +``` + + io.seata + seata-all + 1.5.2 + +``` + +### **the fourth step** + +spring-boot application: + +Reference [seata/script/client/spring at develop seata/seata (github.com)](https://github.com/seata/seata/tree/develop/script/client/spring) + +Add it to your project's application.yml. + +```yaml +seata: + enabled: true + application-id: applicationName + tx-service-group: my_test_tx_group + enable-auto-data-source-proxy: true #Only AT and XA modes need to be true, and the data source will be automatically proxied after opening + data-source-proxy-mode: AT #Optional AT&XA + config: + type: nacos + nacos: + #namespace: If the configuration is created in a non-default namespace, please fill in the id of the namespace here + serverAddr: 127.0.0.1:8848 + group: SEATA_GROUP + username: "nacos" + password: "nacos" + data-id: seata.properties + registry: + type: nacos + nacos: + application: seata-server + server-addr: 127.0.0.1:8848 + group: SEATA_GROUP + #namespace: If the configuration is created in a non-default namespace, please fill in the id of the namespace here + username: "nacos" + password: "nacos" +``` + +spring application: + +Add [seata/script/client/conf at develop · seata/seata (github.com)](https://github.com/seata/seata/tree/develop/script/client/conf) under registry.conf, because High-availability deployment uses a third-party configuration center, so file.conf is not required + +``` +registry { + # file, nacos, eureka, redis, zk, consul, etcd3, sofa, custom + type = "nacos" + nacos { + application = "seata-server" + serverAddr = "127.0.0.1:8848" + group = "SEATA_GROUP" + namespace = "" + username = "" + password = "" + ##if use MSE Nacos with auth, mutex with username/password attribute + #accessKey = "" + #secretKey = "" + ##if use Nacos naming meta-data for SLB service registry, specify nacos address pattern rules here + #slbPattern = "" + } +} + +config { + # file, nacos, apollo, zk, consul, etcd3, springCloudConfig, custom + type = "nacos" + nacos { + serverAddr = "127.0.0.1:8848" + namespace = "" + group = "SEATA_GROUP" + username = "" + password = "" + ##if use MSE Nacos with auth, mutex with username/password attribute + #accessKey = "" + #secretKey = "" + dataId = "seata.properties" + } +} +``` + +### **the fifth step** + +Run the nacos you downloaded, and refer to [https://github.com/seata/seata/tree/develop/script/config-center](https://gitee.com/link?target=https%3A%2F% 2Fgithub.com%2Fseata%2Fseata%2Ftree%2Fdevelop%2Fscript%2Fconfig-center) and modify the config.txt + +```properties +#Only used by client +#The transaction group is called my_test_tx_group and the corresponding seata-server cluster is default +service.vgroupMapping.my_test_tx_group=default +#The following are only used by server +store.mode=db +store.db.datasource=druid +store.db.dbType=mysql +store.db.driverClassName=com.mysql.jdbc.Driver +store.db.url=jdbc:mysql://127.0.0.1:3306/seata?useUnicode=true +store.db.user=username +store.db.password=password +store.db.minConn=5 +store.db.maxConn=30 +store.db.globalTable=global_table +store.db.branchTable=branch_table +store.db.queryLimit=100 +store.db.lockTable=lock_table +store.db.maxWait=5000 +``` + +Open the nacos console, create a configuration whose dataId is seata.properties under the corresponding namespace, fill in the group as SEATA_GROUP, and fill in the above content and select the type as properties to save +Dingtalk_20220724021635.jpg.png + +### **Step 6** + +Change application.yml in server + +```yaml +server: + port: 7091 + +spring: + application: + name: seata-server + +record: + config: classpath:logback-spring.xml + file: + path: ${user.home}/logs/seata + +console: + user: + username: seata + password: seata + +seata: + config: + # support: nacos, consul, apollo, zk, etcd3 + type: nacos + nacos: + server-addr: 127.0.0.1:8848 + #namespace: If the configuration is created in a non-default namespace, please fill in the id of the namespace here + group: SEATA_GROUP + username: + password: + ##if use MSE Nacos with auth, mutex with username/password attribute + #access-key: "" + #secret-key: "" + data-id: seata.properties + registry: + # support: nacos, eureka, redis, zk, consul, etcd3, sofa + type: nacos + nacos: + application: seata-server + server-addr: 127.0.0.1:8848 + group: SEATA_GROUP + namespace: + cluster: default + #namespace: If the configuration is created in a non-default namespace, please fill in the id of the namespace here + password: + ##if use MSE Nacos with auth, mutex with username/password attribute + #access-key: "" + #secret-key: "" +# server: +# service-port: 8091 #If not configured, the default is '${server.port} + 1000' + security: + secretKey: SeataSecretKey0c382ef121d778043159209298fd40bf3850a017 + tokenValidityInMilliseconds: 1800000 + ignore: + urls: /,/**/*.css,/**/*.js,/**/*.html,/**/*.map,/**/*.svg,/**/*. png, /**/*.ico, /console-fe/public/**, /api/v1/auth/login +``` + +### **Step Seven** + +An example of adding @GlobalTransactional to the interface of the global transaction caller (the service that initiates the global transaction) is as follows: + +```java +@GetMapping(value = "testCommit") +@GlobalTransactional +public Object testCommit(@RequestParam(name = "id",defaultValue = "1") Integer id, + @RequestParam(name = "sum", defaultValue = "1") Integer sum) { + Boolean ok = productService. reduceStock(id, sum); + if (ok) { + LocalDateTime now = LocalDateTime.now(); + Orders orders = new Orders(); + orders.setCreateTime(now); + orders.setProductId(id); + orders. setReplaceTime(now); + orders. setSum(sum); + orderService. save(orders); + return "ok"; + } else { + return "fail"; + } +} +``` + +Spring applications need to manually proxy the data source to select the transaction mode and initialize the transaction scanner when using AT or XA mode + +```java +@Primary +@Bean("dataSource") +public DataSource dataSource(DataSource druidDataSource) { + //AT agent choose one of the two + return new DataSourceProxy(druidDataSource); + //XA Proxy + return new DataSourceProxyXA(druidDataSource) +} +``` + +```java + @Bean + public GlobalTransactionScanner globalTransactionScanner() { + return new GlobalTransactionScanner("application name", "my_test_tx_group"); + } +``` + +If you use tcc mode, you need to additionally define two-stage try and confirm(commit) cancel(rollback) in the serviceimpl of the corresponding provider + +The spring-boot application needs to close the data source proxy + +```yaml +seata: + enable-auto-data-source-proxy: false +``` + +```java +/** + * Define two-phase commit name = the bean name of the tcc, globally unique commitMethod = commit is the two-phase confirmation method rollbackMethod = rollback is the two-phase cancellation method + * useTCCFence=true is to enable anti-hanging + * BusinessActionContextParameter annotation to pass parameters to the second stage + * + * @param params - input parameters + * @return String + */ +@TwoPhaseBusinessAction(name = "beanName", commitMethod = "commit", rollbackMethod = "rollback", useTCCFence = true) +public void insert(@BusinessActionContextParameter(paramName = "params") Map params) { + logger.info("You can reserve resources here, or use the characteristics of tcc to mix with AT. In the second stage, use the messages stored here in the first stage and send them out through the second stage, such as redis, mq and other operations"); +} + +/** + * The confirmation method can be named otherwise, but it must be consistent with the commitMethod. The context can pass the parameters of the try method + * + * @param context context + * @return boolean + */ +public void commit(BusinessActionContext context) { + logger.info("Reserved resources are actually processed, or send mq messages and redis storage"); +} + +/** + * Two-stage cancellation method + * + * @param context context + * @return boolean + */ +public void rollback(BusinessActionContext context) { + logger.info("Release reserved resources, or clear the message cache sent when the first phase is ready to be submitted by the second phase"); +} +``` + +linux/macos + +```shell +cd bin + +sh seata-server.sh +``` + +windows + +```shell +cd bin +./seata-server.bat +``` + +Run seata-server, after success, run your own service dubbo provider&consumer + + + +### **The eighth step is to build a highly available Seata-server** + +Since seata-server supports the separation mode of computing and storage, and supports exposing service addresses to multiple registration centers, it only needs to be configured according to the sixth step and then expanded horizontally + +For details, please visit: https://seata.io/ \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/traffic/_index.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/traffic/_index.md new file mode 100755 index 000000000000..35b08d27a470 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/traffic/_index.md @@ -0,0 +1,37 @@ +--- +type: docs +title: "Traffic Governance Rules" +linkTitle: "Traffic Governance" +weight: 2 +no_list: true +hide_summary: true +--- + + + +### Traffic Management + +The essence of traffic management is to distribute requests to application services according to established routing rules, as shown in the following figure: + +![What is traffic control](/imgs/v3/concepts/what-is-traffic-control.png) + +in: ++ There can be multiple routing rules, and different routing rules have priorities. Such as: Router(1) -> Router(2) -> ... -> Router(n) ++ A routing rule can route to multiple different application services. For example: Router(2) can route to Service(1) or Service(2) ++ Multiple different routing rules can route to the same application service. For example: both Router(1) and Router(2) can route to Service(2) ++ Routing rules can also not route to any application service. For example: Router(m) is not routed to any Service, all requests hitting Router(m) will cause errors because there is no corresponding application service processing ++ Application service can be a single instance or an application cluster. + +### Dubbo Mesh format traffic management introduction + +Dubbo provides a traffic management strategy that supports the mesh method, which can easily implement [A/B testing](./mesh-style/ab-testing-deployment/), [canary release](./mesh-style/canary -deployment/), [blue-green deployment](./mesh-style/blue-green-deployment/) and other capabilities. + +Dubbo divides the entire traffic management into two parts: [VirtualService](./mesh-style/virtualservice/) and [DestinationRule](./mesh-style/destination-rule/). When Consumer receives a request, it will follow [DubboRoute](./mesh-style/virtualservice/#dubboroute) and [DubboRouteDetail](./mesh- style/virtualservice/#dubboroutedetail) is matched to the corresponding subnet in [DubboDestination](./mesh-style/virtualservice/#dubbodestination), and finally according to the configuration in [DestinationRule](./mesh-style/destination-rule/) The labels in [subnet](./mesh-style/destination-rule/#subset) information find the corresponding Provider cluster that needs specific routing. in: + ++ [VirtualService](./mesh-style/virtualservice/) mainly deals with rules for inbound traffic diversion, and supports service-level and method-level diversion. ++ [DubboRoute](./mesh-style/virtualservice/#dubboroute) mainly solves the problem of service level shunting. At the same time, it also provides retry mechanism, timeout, fault injection, mirroring traffic and other capabilities. ++ [DubboRouteDetail](./mesh-style/virtualservice/#dubboroutedetail) mainly solves the method-level shunt problem in a service. Supports shunting capabilities in various dimensions such as method name, method parameters, number of parameters, parameter types, headers, etc. At the same time, it also supports method-level retry mechanism, timeout, fault injection, mirroring traffic and other capabilities. ++ [DubboDestination](./mesh-style/virtualservice/#dubbodestination) is used to describe the destination address of routing traffic, and supports host, port, subnet and other methods. ++ [DestinationRule](./mesh-style/destination-rule/) mainly deals with destination address rules, which can be associated with Provider clusters through hosts, subnet, etc. At the same time, load balancing can be achieved through [trafficPolicy](./mesh-style/destination-rule/#trafficpolicy). + +This design concept solves the coupling problem between traffic diversion and destination address very well. Not only simplifies the configuration rules to effectively avoid the problem of configuration redundancy, but also supports any combination of [VirtualService](./mesh-style/virtualservice/) and [DestinationRule](./mesh-style/destination-rule/), It can flexibly support various business usage scenarios. \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/traffic/config-rule.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/traffic/config-rule.md new file mode 100644 index 000000000000..3078b58750aa --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/traffic/config-rule.md @@ -0,0 +1,172 @@ +--- +type: docs +title: "Configuration Rules" +linkTitle: "Configuration Rules" +weight: 34 +description: "Configure application-level governance rules and service-level governance rules in Dubbo" +--- +## override rules +Overriding rules is a capability designed by Dubbo to dynamically adjust the behavior of RPC calls without restarting the application. Starting from version 2.7.0, dynamic configuration adjustments are supported at two granularities of **service** and **application**. + +### Overview + +Please view or modify override rules in the service governance console. + +**Application Granularity** + +```yaml +# Change the weight of all services (scope:application) provided by the application demo (key:demo) on port 20880 (side:provider) to 1000 (weight:1000). +--- +configVersion: v2.7 +scope: application +key: demo +enabled: true +configs: +- addresses: ["0.0.0.0:20880"] + side: provider + parameters: + weight: 1000 + ... +``` + +**Service Granularity** + +```yaml +# All consumer (side:consumer) DemoService service (key:org.apache.dubbo.samples.governance.api.DemoService) application instance (addresses:[0.0.0.0]), the timeout is changed to 6000ms +--- +configVersion: v2.7 +scope: service +key: org.apache.dubbo.samples.governance.api.DemoService +enabled: true +configs: +- addresses: [0.0.0.0] + side: consumer + parameters: + timeout: 6000 + ... +``` + +## Detailed Rules + +### Configuration template + +```yaml +--- +configVersion: v2.7 +scope: application/service +key: app-name/group+service+version +enabled: true +configs: +- addresses: ["0.0.0.0"] + providerAddresses: ["1.1.1.1:20880", "2.2.2.2:20881"] + side: consumer + applications/services: [] + parameters: + timeout: 1000 + cluster: failfase + loadbalance: random +- addresses: ["0.0.0.0:20880"] + side: provider + applications/services: [] + parameters: + threadpool: fixed + threads: 200 + iothreads: 4 + dispatcher: all + weight: 200 +... +``` + +in: +- `configVersion` means dubbo version +- `scope` indicates the scope of configuration, which is the granularity of application or service. **Required**. +- `key` specifies which service or application the rule body acts on. **Required**. + - When scope=service, the key value is a combination of [{group}:]{service}[:{version}] +- When scope=application, the key value is the application name +- `enabled=true` Whether the overriding rule is valid, it can be left blank, and it is valid by default. +- `configs` defines specific coverage rule content, and n (n>=1) rule bodies can be specified. **Required**. + - side, + - applications + - services + -parameters + - addresses + - providerAddresses + +**For most configuration scenarios, you only need to clarify the following questions to know how to write the configuration:** +1. Whether you want to modify the configuration of the entire application or a service. + - Application: `scope: application, key: app-name` (you can also use `services` to specify certain services). + - Service: `scope: service, key:group+service+version`. + +2. Whether the modification is applied to the consumer or the provider. + - Consumer: `side: consumer`, when acting on the consumer side (you can further use `providerAddress`, `applications` to select specific provider examples or applications). + - Provider: `side: provider`. + +3. Whether the configuration takes effect only for certain specific instances. + - All instances: `addresses: ["0.0.0.0"]` or `addresses: ["0.0.0.0:*"]` depends on the side value. + - Specified instances: `addersses[list of instance addresses]`. + +4. Which property is to be modified. + +### Example + +**1. Disable provider: (Usually used to temporarily kick off a provider machine, similarly, please use routing rules to prohibit consumer access)** + + ```yaml + --- + configVersion: v2.7 + scope: application + key: demo-provider + enabled: true + configs: + - addresses: ["10.20.153.10:20880"] + side: provider + parameters: + disabled: true + ... + ``` + +**2. Adjust the weight: (usually used for capacity evaluation, the default weight is 200)** + + ```yaml + --- + configVersion: v2.7 + scope: application + key: demo-provider + enabled: true + configs: + - addresses: ["10.20.153.10:20880"] + side: provider + parameters: + weight: 200 + ... + ``` + +**3. Adjust the load balancing strategy: (the default load balancing strategy is random)** + + ```yaml + --- + configVersion: v2.7 + scope: application + key: demo-consumer + enabled: true + configs: + - side: consumer + parameters: + loadbalance: random + ... + ``` + +**4. Service downgrade: (Usually used to temporarily shield a non-critical service that has an error)** + + ```yaml + --- +configVersion: v2.7 +scope: service +key: org.apache.dubbo.samples.governance.api.DemoService +enabled: true +configs: +- side: consumer + parameters: + force: return null + ... + ``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/traffic/mesh-style/_index.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/traffic/mesh-style/_index.md new file mode 100644 index 000000000000..7d82636e40c1 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/traffic/mesh-style/_index.md @@ -0,0 +1,268 @@ +--- +type: docs +title: "Mesh Routing Rules" +linkTitle: "Mesh Routing Rules" +weight: 40 +description: "Dubbo supports Mesh routing types and cooperation methods" +--- + +### Basic idea +Based on the routing chain, the Pipeline processing method is adopted, as shown in the following figure: + +![route-rule1.png](/imgs/user/route-rule1.png) + + +The logic of the routing chain can be simply understood as target = rn(...r3(r2(r1(src)))). For the internal logic of each router, it can be abstracted as n disjoint address pools addrs-pool-1 ... addrs-pool- n According to the implementation-defined rules, the intersection is taken as the output addrs-out. By analogy, the calculation of the entire routing chain is completed. + +![route-rule2.png](/imgs/user/route-rule2.png) + +On the other hand, if router(n) needs to execute fallback logic, then the fallback logic should be determined after router(n) + + +### fallback processing principle + +After multiple conditional components between multiple routers, it is easy for the address to be filtered to be empty, so we need to perform fallback processing for this situation to ensure that the business can successfully find a valid address under the premise of correctness. + +First we look at the following rules + +```yaml +apiVersion: service.dubbo.apache.org/v1alpha1 +kind: VirtualService +metadata: + name: demo-route +spec: + hosts: + - demo // Uniformly defined as the application name + dubbo: + - service: + - exact: com.taobao.hsf.demoService:1.0.0 + - exact: com.taobao.hsf.demoService:2.0.0 + route details: + - name: sayHello-String-method-route + match: + -method: + name_match: + exact: "sayHello" + ..... + argp: + - string + route: + -destination: + host: demo + subset: v1 + fallback: + destination: + host: demo + subset: v2 + fallback: + destination: + host: demo + subset: v3 + + - name: sayHello-method-route + match: + -method: + name_match: + exact: "s-method" + route: + -destination: + host: demo + subset: v2 + fallback: + destination: + host: demo + subset: v3 + + - name: interface-route + route: + -destination: + host: demo + subset: v3 + + - service: + + .... +--- +apiVersion: service.dubbo.apache.org/v1alpha1 +kind: DestinationRule +metadata: + name: demo-route +spec: + host: demo + subsets: + - name: v1 + labels: + sigma.ali/mg: v1-host + + - name: v2 + labels: + sigma.ali/mg: v2-host + + - name: v3 + labels: + sigma.ali/mg:v3-host + +``` + +Let's take script routing as an example. The matching conditions of this script routing follow a principle, that is, the matching range is a process from precise to broad. In this example, it is sayHello(string) parameter -> sayHello method -> A matching lookup process for interface-level routing. + +So if we have met a certain condition, but the selected subset address is empty, how will we perform fallback processing? + +Take the condition of matching sayHello(string) parameters as an example. We selected the v1 subset. If it is empty, we can go up to the next level to find the address, that is, to find the address at the method level. The specific configuration is as follows + +```yaml + - name: sayHello-String-method-route + match: + -method: + name_match: + exact: "sayHello" + ..... + argp: + - string + route: + -destination: + host: demo + subset: v1 + fallback: + destination: + host: demo + subset: v2 + fallback: + destination: + host: demo + subset: v3 +``` + +At this time, the address we selected is the v2 method-level address. If v2 still has no address, according to the definition of the rules, we can fallback to the v3 interface level. + +Suppose we have a method matching, if there is no address, we need to report an error directly without fallback, we can configure it like this + + +```yaml +apiVersion: service.dubbo.apache.org/v1alpha1 +kind: VirtualService +metadata: + name: demo-route +spec: + hosts: + - demo // Uniformly defined as the application name + dubbo: + - service: + - exact: com.taobao.hsf.demoService:1.0.0 + - exact: com.taobao.hsf.demoService:2.0.0 + route details: + - name: sayHello-String-method-route + match: + -method: + name_match: + exact: "sayHello" + ..... + argp: + - string + route: + -destination: + host: demo + subset: v1 + fallback: + destination: + host: demo + subset: v2 + fallback: + destination: + host: demo + subset: v3 + + - name: sayHello-method-route + match: + -method: + name_match: + exact: "s-method" + route: + -destination: + host: demo + subset: v2 + fallback: + destination: + host: demo + subset: v3 + - name: some-method-route + match: + -method: + name_match: + exact: "some-method" + route: + -destination: + host: demo + subset: v4 + + - name: interface-route + route: + -destination: + host: demo + subset: v3 + + - service: + + .... +--- +apiVersion: service.dubbo.apache.org/v1alpha1 +kind: DestinationRule +metadata: + name: demo-route +spec: + host: demo + subsets: + - name: v1 + labels: + sigma.ali/mg: v1-host + + - name: v2 + labels: + sigma.ali/mg: v2-host + + - name: v3 + labels: + sigma.ali/mg:v3-host +``` + +From this rule, we can see that when the some-method condition is matched, it corresponds to the v4 subset, then when v4 is empty, because no fallback is configured, an error will be reported directly at this time + +#### Summary of fallback processing principles + +- We should configure the fallback processing logic of Destination in the VirtualService route +- In fallback subset, if the corresponding subset is also configured with fallback subset, it should also be processed recursively; the relationship between fallback subsets should also be from specific to broad +- When we write matching conditions, we should follow the principle of moving from specific conditions to broad conditions + +### Assembly mode of RouteChain (currently not implemented) + +![route-rule3.png](/imgs/user/route-rule3.png) + + +We see the above figure, in the routing process, we are the processing method of Pipeline, the Router nodes of Pipeline exist in order, and each Router has a unique corresponding VirtualService and **multiple** corresponding DestinationRules for description . + +Take the routing rule configuration stored on Nacos as an example, the format of the configuration is as follows: + +```yaml +DataId: Demo.rule.yaml +GROUP: HSF + +content: + +Virtual Service A +--- +DestinationRule A1 +--- +DestinationRule A2 +--- +Virtual Service B +--- +DestinationRule B +--- +VirtualServiceC +--- +DestinationRule C +--- +... +``` + +`VirtualService A` and `DestinationRule A1`, `DestinationRule A2` form a Router A, `VirtualService B` and `DestinationRule B` form a Router B, and so on to complete the assembly of the entire router chain. \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/traffic/mesh-style/ab-testing-deployment.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/traffic/mesh-style/ab-testing-deployment.md new file mode 100644 index 000000000000..e551cf4251ca --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/traffic/mesh-style/ab-testing-deployment.md @@ -0,0 +1,19 @@ +--- +type: docs +title: "Ab Test" +linkTitle: "Ab Test" +weight: 30 +description: "On the premise that the old version on the line continues to run, deploy the new version directly and then test it. When the new version passes the test, switch the traffic to the new version, and finally upgrade the old version to the new version." +--- + +### Scene Description +Describe the current IDC, service deployment, service information, desired effects, etc. +### Operation process + ++ step 1 + + routing configuration + + authentication scheme + ++ step 2 + + routing configuration + + authentication scheme \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/traffic/mesh-style/blue-green-deployment.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/traffic/mesh-style/blue-green-deployment.md new file mode 100644 index 000000000000..9ee61cd78774 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/traffic/mesh-style/blue-green-deployment.md @@ -0,0 +1,19 @@ +--- +type: docs +title: "Blue-Green Deployment" +linkTitle: "Blue-green deployment" +weight: 20 +description: "On the premise that the old version on the line continues to run, deploy the new version directly and then test it. When the new version passes the test, switch the traffic to the new version, and finally upgrade the old version to the new version." +--- + +### Scene Description +Describe the current IDC, service deployment, service information, desired effects, etc. +### Operation process + ++ step 1 + + routing configuration + + authentication scheme + ++ step 2 + + routing configuration + + authentication scheme \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/traffic/mesh-style/canary-deployment.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/traffic/mesh-style/canary-deployment.md new file mode 100644 index 000000000000..cf47bd273b3c --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/traffic/mesh-style/canary-deployment.md @@ -0,0 +1,20 @@ +--- +type: docs +title: "Canary" +linkTitle: "Canary" +weight: 40 +--- + +### Scene Description + +Describe the current IDC, service deployment, service information, desired effects, etc. + +### Operation process + ++ step 1 + + routing configuration + + authentication scheme + ++ step 2 + + routing configuration + + authentication scheme \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/traffic/mesh-style/demo-rule-deployment.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/traffic/mesh-style/demo-rule-deployment.md new file mode 100644 index 000000000000..f3ef2d6ad312 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/traffic/mesh-style/demo-rule-deployment.md @@ -0,0 +1,349 @@ +--- +type: docs +title: "Use Case" +linkTitle: "Use Case" +weight: 18 +description: "Make routing rules based on the actual situation." +--- + +### Application Services + +```yaml +com.taobao.hsf.DemoService:1.0.0 +``` + +### service address + +```yaml +10.0.0.1:12200?_p=hessian2&APP=demo&st=na61&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=CENTER +10.0.0.2:12200?_p=hessian2&APP=demo&st=na62&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=CENTER +10.0.0.3:12200?_p=hessian2&APP=demo&st=na610&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=CENTER +10.0.0.4:12200?_p=hessian2&APP=demo&st=na620&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=CENTER + + +10.0.0.4:12200?_p=hessian2&APP=demo&st=et12&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=UNSH +10.0.0.5:12200?_p=hessian2&APP=demo&st=et12&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=UNSH + +10.0.0.6:12200?_p=hessian2&APP=demo&st=SA128&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=UNSZ +10.0.0.7:12200?_p=hessian2&APP=demo&st=SA128&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=UNSZ + +10.0.0.8:12200?_p=hessian2&APP=demo&st=na62&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=UNZBMIX +10.0.0.9:12200?_p=hessian2&APP=demo&st=na62&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=UNZBMIX +10.0.0.10:12200?_p=hessian2&APP=demo&st=na62&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=UNZBMIX + +``` +### Routing rules + +```yaml +apiVersion: service.dubbo.apache.org/v1alpha1 +kind: VirtualService +metadata: + name: demo/UnitRouter +spec: + hosts: + - demo + dubbo: + - name: UnitServiceRoute + services: + - exact: com.taobao.hsf.DemoService:1.0.0 + route details: + - name: center-env + match: + - context: + hsfcontext: + user_unit: + exact: CENTER + route: + -destination: + host: demo + subset: CENTER + fallback: // There is no fallback in unitization, and an error is reported directly + - name: unsh-env + match: + - context: + hsfcontext: + user_unit: + exact: UNSH + route: + -destination: + host: demo + subset: UNSH + - name: unsz-env + match: + - context: + hsfcontext: + user_unit: + exact: UNSZ + route: + -destination: + host: demo + subset: UNSZ + - name: zbmix-env + match: + - context: + hsfcontext: + user_unit: + exact: ZBMIX + route: + -destination: + host: demo + subset: ZBMIX + +---- + + +apiVersion: service.dubbo.apache.org/v1alpha1 +kind: DestinationRule +metadata: + name: demo/UnitRouter +spec: + host: demo // This is consistent with the above + subsets: + - name: CENTER + labels: + sigma.ali/unit: CENTER + - name: UNSH + labels: + sigma.ali/unit: UNSH + - name: UNSZ + labels: + sigma.ali/unit: UNSZ + - name: ZBMIX + labels: + sigma.ali/unit: ZBMIX + + +---- + +apiVersion: service.dubbo.apache.org/v1alpha1 +kind: VirtualService +metadata: + name: demo/MachineRouter +spec: + hosts: + - demo + dubbo: + - name: MachineRoomRouteDefault // same machine room + services: + - regex: * + route details: + - name: na61-samesite-route // Send traffic from na61 computer room to na61, na610 computer room + match: + - sourceables: + sigma.ali/site:na61 + route: + -destination: + host: demo + subset: na61 + -destination: + host: demo + subset: na610 + weight: 40 + - name: na62-samesite-route // Send traffic from na62 computer room to na62 computer room + match: + - sourceables: + sigma.ali/site: na62 + route: + -destination: + host: demo + subset: na62 + - name: default // Bottom line routing, traffic from other computer rooms can be sent at will + route: + -destination: + host: demo + ..... + +---- + +---- + +apiVersion: service.dubbo.apache.org/v1alpha1 +kind: DestinationRule +metadata: + name: demo/MachineRouter +spec: + host: demo// This is consistent with the above + subsets: + - name: na61 + labels: + sigma.ali/site:na61 + - name: na610 + labels: + sigma.ali/site:na610 + - name: na62 + labels: + sigma.ali/site:na62 + - name: na620 + labels: + sigma.ali/site: na620 + ..... + +``` + +### Case Description + +Taking the above configuration as an example, assuming that the consumer is in the na62 computer room marked by CENTER, the user_unit in the request context belongs to CENTER + +Then we have the following routing flow: + +As we pass through the UnitRouter, the address is divided into four parts + ++CENTER: + +```yaml +10.0.0.1:12200?_p=hessian2&APP=demo&st=na61&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=CENTER +10.0.0.2:12200?_p=hessian2&APP=demo&st=na62&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=CENTER +10.0.0.3:12200?_p=hessian2&APP=demo&st=na610&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=CENTER +10.0.0.4:12200?_p=hessian2&APP=demo&st=na620&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=CENTER + +``` + + ++ UNSH + +```yaml +10.0.0.4:12200?_p=hessian2&APP=demo&st=et12&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=UNSH +10.0.0.5:12200?_p=hessian2&APP=demo&st=et12&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=UNSH + +``` + ++ UNSZ + +```yaml +10.0.0.6:12200?_p=hessian2&APP=demo&st=SA128&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=UNSZ +10.0.0.7:12200?_p=hessian2&APP=demo&st=SA128&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=UNSZ + +``` + ++ UNZBMIX + +```yaml +10.0.0.8:12200?_p=hessian2&APP=demo&st=na62&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=UNZBMIX +10.0.0.9:12200?_p=hessian2&APP=demo&st=na62&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=UNZBMIX +10.0.0.10:12200?_p=hessian2&APP=demo&st=na62&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=UNZBMIX + +``` + +Because user_unit belongs to CENTER, we choose the part of CENTER as the address input of MachineRoomRouter, which is + +CENTER + +```yaml +10.0.0.1:12200?_p=hessian2&APP=demo&st=na61&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=CENTER +10.0.0.2:12200?_p=hessian2&APP=demo&st=na62&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=CENTER +10.0.0.3:12200?_p=hessian2&APP=demo&st=na610&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=CENTER +10.0.0.4:12200?_p=hessian2&APP=demo&st=na620&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=CENTER + +``` + +In the second step, MachineRoomRoute can be divided into five parts + + +na61 + +```yaml +10.0.0.1:12200?_p=hessian2&APP=demo&st=na61&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=CENTER + +``` + + +na610 + +```yaml +10.0.0.3:12200?_p=hessian2&APP=demo&st=na610&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=CENTER + +``` + +na62 + +```yaml +10.0.0.2:12200?_p=hessian2&APP=demo&st=na62&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=CENTER +10.0.0.8:12200?_p=hessian2&APP=demo&st=na62&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=UNZBMIX +10.0.0.9:12200?_p=hessian2&APP=demo&st=na62&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=UNZBMIX +10.0.0.10:12200?_p=hessian2&APP=demo&st=na62&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=UNZBMIX + +``` + +na620 + +```yaml +10.0.0.4:12200?_p=hessian2&APP=demo&st=na620&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=CENTER + +``` + +##### fallback + +```yaml +10.0.0.1:12200?_p=hessian2&APP=demo&st=na61&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=CENTER +10.0.0.2:12200?_p=hessian2&APP=demo&st=na62&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=CENTER +10.0.0.3:12200?_p=hessian2&APP=demo&st=na610&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=CENTER +10.0.0.4:12200?_p=hessian2&APP=demo&st=na620&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=CENTER + + +10.0.0.4:12200?_p=hessian2&APP=demo&st=et12&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=UNSH +10.0.0.5:12200?_p=hessian2&APP=demo&st=et12&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=UNSH + +10.0.0.6:12200?_p=hessian2&APP=demo&st=SA128&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=UNSZ +10.0.0.7:12200?_p=hessian2&APP=demo&st=SA128&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=UNSZ + +10.0.0.8:12200?_p=hessian2&APP=demo&st=na62&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=UNZBMIX +10.0.0.9:12200?_p=hessian2&APP=demo&st=na62&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=UNZBMIX +10.0.0.10:12200?_p=hessian2&APP=demo&st=na62&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=UNZBMIX + +``` + +Since the consumer initiates the call in the na62 computer room, it matches + +```yaml + - name: na62-samesite-route // Send traffic from na62 computer room to na62 computer room + match: + - sourceables: + sigma.ali/site: na62 + route: + -destination: + host: demo + subset: na62 + +``` + + +This rule, then, is to choose + +na62 + +```yaml +10.0.0.2:12200?_p=hessian2&APP=demo&st=na62&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=CENTER +10.0.0.8:12200?_p=hessian2&APP=demo&st=na62&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=UNZBMIX +10.0.0.9:12200?_p=hessian2&APP=demo&st=na62&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=UNZBMIX +10.0.0.10:12200?_p=hessian2&APP=demo&st=na62&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=UNZBMIX + +``` + +The input of UnitRouter to MachineRoomRouter is + +CENTER + +```yaml +10.0.0.1:12200?_p=hessian2&APP=demo&st=na61&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=CENTER +10.0.0.2:12200?_p=hessian2&APP=demo&st=na62&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=CENTER +10.0.0.3:12200?_p=hessian2&APP=demo&st=na610&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=CENTER +10.0.0.4:12200?_p=hessian2&APP=demo&st=na620&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=CENTER + +``` + + +The result of the intersection of the two is + +```yaml + 10.0.0.2:12200?_p=hessian2&APP=demo&st=na62&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=CENTER + +``` + +This result will be used as the output of the next route, repeating the previous actions; + +If this routing rule has ended, the address of the call will be + +```yaml +10.0.0.2:12200?_p=hessian2&APP=demo&st=na62&v=2.0&_TIMEOUT=3000&_ih2=y&mg=demohost&_CONNECTTIMEOUT=1000&_SERIALIZETYPE=hessian&ut=CENTER + +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/traffic/mesh-style/destination-rule.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/traffic/mesh-style/destination-rule.md new file mode 100644 index 000000000000..3ea88d7151aa --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/traffic/mesh-style/destination-rule.md @@ -0,0 +1,94 @@ +--- +type: docs +title: "DestinationRule" +linkTitle: "DestinationRule" +weight: 40 +description: "Destination address rule" +--- + + +### DestinationRule +`DestinationRule` is used to process the rules of the target address, and `ServiceEntry`, `WorkloadEntry` and other definitions related to `DestinationRule` are consistent with open source ++ Example of use + +```yaml +apiVersion: service.dubbo.apache.org/v1alpha1 +kind: DestinationRule +metadata: + name: demo-route +spec: + host: demo + subsets: + trafficPolicy: +``` ++ property description + +| Field | Type | Description | Required | +| --- | --- | --- | --- | +| name | string | The name of the rule, easy to identify the purpose of the rule | YES | +| host | string | The corresponding key value in the registry, now it is the interface name | YES | +| trafficPolicy | TrafficPolicy | traffic policy | NO | +| subsets | Subset[] | naming of single or multiple versions of the service | YES | + +### Subset +The name of the `Subset` application service, which can be single or multiple versions ++ Example of use + +```yaml +apiVersion: service.dubbo.apache.org/v1alpha1 +kind: DestinationRule +metadata: + name: demo-route +spec: + subsets: #Subnet[] + - name: + labels: +``` ++ property description + +| Field | Type | Description | Required | +| --- | --- | --- | --- | +| name | string | service version name | YES | +| labels | map | labels on the service | YES | + +### TrafficPolicy +`TrafficPolicy` represents the load balancing policy ++ Example of use + +```yaml +apiVersion: service.dubbo.apache.org/v1alpha1 +kind: DestinationRule +metadata: + name: demo-route +spec: + trafficPolicy: #TrafficPolicy + loadBalancer: +``` ++ property description + +| Field | Type | Description | Required | +| --- | --- | --- | --- | +| loadBalancer | LoadBalancerSettings | Load Balancer Settings | YES | + +### LoadBalancerSettings +`LoadBalancerSettings` is used to represent the configuration related to load balancing ++ Example of use + +```yaml +apiVersion: service.dubbo.apache.org/v1alpha1 +kind: DestinationRule +metadata: + name: demo-route +spec: + trafficPolicy: + loadBalancer: #LoadBalancerSettings + simple: + consistentHash: +``` ++ property description + +| Field | Type | Description | Required | +| --- | --- | --- | --- | +| simple | string | load balancing strategy, including: `ROUND_ROBIN`, `LEAST_CONN`, `RANDOM`, `PASSTHROUGH` | YES | +| consistentHash | ConsistentHashLB | Consistent Hash strategy (not implemented) NO +| NO | \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/traffic/mesh-style/dynamic-rule-deployment.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/traffic/mesh-style/dynamic-rule-deployment.md new file mode 100644 index 000000000000..2f066328e967 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/traffic/mesh-style/dynamic-rule-deployment.md @@ -0,0 +1,78 @@ +--- +type: docs +title: "Dynamic Routing" +linkTitle: "Dynamic Routing" +weight: 15 +description: "Dynamic routing for groovy scripts." +--- + +```yaml +apiVersion: service.dubbo.apache.org/v1alpha1 +kind: VirtualService +metadata: + name: demo/StandardRouter +spec: + hosts: + - demo + dubbo: + - services: + - exact: com.taobao.hsf.demoservice:1.0.0 + route details: + - name: sayHello-route + match: + -method: + name_match: + exact: "s-method" + argc: 5 + args: + - index: 2 + type: double + num_value: + oneof: + - range: + start: 100.1 + - index: 1 + type: string + str_value: + oneof: + - regex: "*abc*" + - exact: parameter-1 + - index: 3 + type: bool + - index: 4 + type: int + num_value: + oneof: + - range: + start: 1 + end: 100 + - sourceables: + sigma.ali/appName: "ump2" + route: + -destination: + host: demo + subset: v1 + fallback: + host: demo + subset: v2 + + - name: default-route + route: + -destination: + host: demo + subset: v2 +--- +apiVersion: service.dubbo.apache.org/v1alpha1 +kind: DestinationRule +metadata: + name: reviews-route +spec: + host: demo + subsets: + - name: v1 + labels: + sigma.ali/mg: v1-host + - name: v2 + labels: + sigma.ali/mg: v2-host +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/traffic/mesh-style/virtualservice.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/traffic/mesh-style/virtualservice.md new file mode 100644 index 000000000000..74048444c4b5 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/traffic/mesh-style/virtualservice.md @@ -0,0 +1,481 @@ +--- +type: docs +title: "VirtualService" +linkTitle: "VirtualService" +weight: 30 +description: "Rules for inbound traffic" +--- + +### VirtualService +`VirtualService` is a rule used to process inbound traffic, that is to say, it is used to describe which inbound traffic applies to this routing rule. ++ Example of use +```yaml +apiVersion: service.dubbo.apache.org/v1alpha1 +kind: VirtualService +metadata: + name: demo/StandardRouter +spec: + hosts: + dubbo: +``` ++ property description + +| Field | Type | Description | Required | +| --- | --- | --- | --- | +| name | string | should be named in the form of `application name/router type`. The `name` attribute is determined once the Router type is defined | YES | +| hosts | string[] | generally refers to the application name | NO | +| dubbo | DubboRoute[] | dubbo routing rules, executed sequentially, return immediately when conditions are met | NO | + ++ Router types are as follows: + +| name | Description | +| --- | --- | +| StandardRouter | A Router that fully uses the standard VirtualService description | +| to be added | to be added | + + +### DubboRoute +`DubboRoute` is an attribute in `VirtualService`, which is used to describe the boundary of the routing strategy. ++ Example of use +```yaml +apiVersion: service.dubbo.apache.org/v1alpha1 +kind: VirtualService +metadata: + name: demo/StandardRouter +spec: + hosts: + dubbo: #DubboRoute + - name: + service: + fault: + mirror: + retries: + timeout: + route details: +``` ++ property description + +| Field | Type | Description | Required | +| --- | --- | --- | --- | +| name | string | The name of the rule, easy to identify the purpose of the rule | NO | +| services | StringMatch[] | A list of service names for which the rule takes effect. You can use a specific service name or a regular * to match; if it is not configured by default, it means that all services are valid | | +| fault | dubboFaultInject[] | fault injection (not implemented) | NO | +| mirror | Destination | mirror traffic (not implemented) | NO | +| retries | DubboRetry[] | Retry related (unimplemented) | NO | +| timeout | DubboTimeout[] | timeout related (unimplemented) | NO | +| routedetail | DubboRouteDetail[] | Specific traffic rules, executed sequentially, return immediately when conditions are met | YES | + +### DubboRouteDetail +`DubboRouteDetail` is used to describe detailed routing rules ++ Example of use +```yaml +apiVersion: service.dubbo.apache.org/v1alpha1 +kind: VirtualService +metadata: + name: demo/StandardRouter +spec: + hosts: + dubbo: + - routedetail: #DubboRouteDetail + - name: + match: + route: + mirror: + retries: + timeout: +``` ++ property description + +| Field | Type | Description | Required | +| --- | --- | --- | --- | +| name | string | The name of the rule details, easy to identify the purpose of the rule | NO | +| match | DubboMatchRequest[] | matching condition | YES | +| route | DubboRouteDestination[] | the actual destination address of the qualified traffic | YES | +| mirror | Destination | mirror traffic (not implemented) | NO | +| retries | DubboRetry[] | Retry related (unimplemented) | NO | +| timeout | DubboTimeout[] | timeout related (unimplemented) | NO | + + +### DubboMatchRequest +`DubboMatchRequest` is used to describe the matching rules of the request ++ Example of use +```yaml +apiVersion: service.dubbo.apache.org/v1alpha1 +kind: VirtualService +metadata: + name: demo/StandardRouter +spec: + hosts: + dubbo: + - route detail: + - match: #DubboMatchRequest + - name: + method: + sourceLabels: + attachments: + headers: + threshold: +``` ++ property description + +| Field | Type | Description | Required | +| --- | --- | --- | --- | +| name | string | matching rule name | YES | +| method | DubboMethodMatch | method related matching | YES | +| sourceLabels | map\ | Related labels typed by the caller, including application name, machine group, machine environment variable information, etc.; for HSF-JAVA, you can get the corresponding key from the reported URL/ value | YES | +| attachments | DubboAttachmentMatch | Other information attached to the request, such as HSF request context, Eagleeye context, etc. | NO | +| headers | map\ | Common request protocol fields, etc., such as interface name, method name, timeout, etc. | NO | +| threshold | DoubleMatch | The machines in the called subset list account for the threshold of the entire host | NO | + +Since there may be duplication of fields among headers, attachmes, and methods, TODO further refines + +### DubboMethodMatch +`DubboMethodMatch` is used to achieve method matching ++ Example of use +```yaml +apiVersion: service.dubbo.apache.org/v1alpha1 +kind: VirtualService +metadata: + name: demo/StandardRouter +spec: + hosts: + dubbo: + - route detail: + - match: + - method: #DubboMethodRequest + - name_match: + argc: + args: + argp: + headers: +``` ++ property description + +| Field | Type | Description | Required | +| --- | --- | --- | --- | +| name_match | StringMatch | match the calling method name in the request | YES | +| argc | int | The number of parameters matching the request | NO | +| args | DubboMethodArg[]| is an array of DubboMethodArg type, indicating the condition that each parameter value needs to meet | NO | +| argp | StringMatch[] | match request parameter type | NO | +| headers | map\ | reserved | NO | + +### DubboMethodArg +`DubboMethodArg` is used to match method parameters ++ Example of use +```yaml +apiVersion: service.dubbo.apache.org/v1alpha1 +kind: VirtualService +metadata: + name: demo/StandardRouter +spec: + hosts: + dubbo: + - route detail: + - match: + -method: + - args: #DubboMethodArg + - index: + str_value: + type: + num_value: + bool_value: + reserve: +``` ++ property description + +| Field | Type | Description | Required | +| --- | --- | --- | --- | +| index | uint32 | The position of the matching parameter, the index field starts from 1 (that is, the $index parameter) | YES | +| type | string | The type of the matching parameter, taking the string type of java as an example, the value of this field is java.lang.String, and the default value of this field is java.lang.String | YES | +| str_value | ListStringMatch | The value of the matching parameter, parsed according to $type ListStringMatcher: match java.lang.String) | NO | +| num_value | ListDoubleMatch | Numeric type match | NO | +| bool_value | BoolMatch | bool value type match | NO | +| reserve | reserve | Complex type matching, not defined for now | NO | + + +### DubboAttachmentMatch +`DubboAttachmentMatch` is used to fully match any object ++ Example of use +```yaml +apiVersion: service.dubbo.apache.org/v1alpha1 +kind: VirtualService +metadata: + name: demo/StandardRouter +spec: + hosts: + dubbo: + - route detail: + - match: + - attachments: #DubboAttachmentMatch + eagleeyecontext: + dubbo context: +``` ++ property description + +| Field | Type | Description | Required | +| --- | --- | --- | --- | +| eagleeyecontext| map\ | eagleeye context | NO | +| dubbocontext| map\ | Dubbo request context | NO | + +### ListStringMatch +`ListStringMatch` is a set of `StringMatch` collections, any `StringMatch` matches ++ Example of use +```yaml +apiVersion: service.dubbo.apache.org/v1alpha1 +kind: VirtualService +metadata: + name: demo/StandardRouter +spec: + hosts: + dubbo: + - route detail: + - match: + -method: + - args: + - index: 1 + str_value: #ListStringMatch + oneof: + - regex: "*abc*" + - exact: parameter-1 +``` + ++ property description + +| Field | Type | Description | Required | +| --- | --- | --- | --- | +| oneof | StringMatch[] | matches if any `StringMatch` matches | NO | + +### StringMatch +`StringMatch` is used to describe string matching rules ++ Example of use +```yaml +apiVersion: service.dubbo.apache.org/v1alpha1 +kind: VirtualService +metadata: + name: demo/StandardRouter +spec: + hosts: + dubbo: + - service: #StringMatch + - exact: org.apache.dubbo.demoService:1.0.0 + - prefix: org.apache.dubbo.hello + - regex: org.apache.dubbo.*Service:2.0.0 +``` ++ property description + +| Field | Type | Description | Required | +| --- | --- | --- | --- | +| exact | string (oneof) | exact match | NO | +| prefix | string (oneof) | prefix match | NO | +| regex | string (oneof) | [regular match](https://github.com/google/re2/wiki/Syntax) | NO | +| noempty | string (oneof) | non-empty character match | NO | +| empty | string (oneof) | empty character match | NO | + + +### ListDoubleMatch +`ListDoubleMatch` is a set of `DoubleMatch` collections, any `DoubleMatch` match matches the parameters ++ Example of use +```yaml +apiVersion: service.dubbo.apache.org/v1alpha1 +kind: VirtualService +metadata: + name: demo/StandardRouter +spec: + hosts: + dubbo: + - route detail: + - match: + -method: + - args: + - index: 1 + type: java.lang.Double + num_value: #ListDoubleMatch + oneof: + - range: + start: 1 + end: 100 + +``` ++ property description + +| Field | Type | Description | Required | +| --- | --- | --- | --- | +| oneof | DoubleMatch[] | matches if any `DoubleMatch` matches | NO | + +### DoubleMatch +`DoubleMatch` is used to match values of type `int`, `long`, `double` + ++ Example of use +```yaml +apiVersion: service.dubbo.apache.org/v1alpha1 +kind: VirtualService +metadata: + name: demo/StandardRouter +spec: + hosts: + dubbo: + - route detail: + - match: + -method: + - args: + - index: 1 + type: java.lang.Double + num_value: + oneof: #DoubleMatch[] + - range: + start: 1 + end: 100 + #Assume that the parameter value of the currently input Double type is x, + #The meaning of the following expression is: x%mode=exact, + #That is, it matches only when x%10=6 + - exact: 6 + mode: 10 + +``` ++ property description + +| Field | Type | Description | Required | +| --- | --- | --- | --- | +| exact | double(oneof) | exact value match | NO | +| range | DoubleRangeMatch(oneof) | value range matching | NO | +| mode | double | Modulo operation, it needs to be configured together with the above two semantics | NO | + +### DoubleRangeMatch +`DoubleRangeMatch` is to match the range of `double` values ++ Example of use +```yaml +apiVersion: service.dubbo.apache.org/v1alpha1 +kind: VirtualService +metadata: + name: demo/StandardRouter +spec: + hosts: + dubbo: + - route detail: + - match: + -method: + - args: + - index: 1 + type: java.lang.Double + num_value: + oneof: + - range: #DoubleRangeMatch + start: 1.2 + end: 1000.5 + +``` ++ property description + +| Field | Type | Description | Required | +| --- | --- | --- | --- | +| start | double | value greater than or equal to | YES | +| end | double | value less than | YES | + + +### BoolMatch +`BoolMatch` is used to match `true`, `false` exactly ++ Example of use +```yaml +apiVersion: service.dubbo.apache.org/v1alpha1 +kind: VirtualService +metadata: + name: demo/StandardRouter +spec: + hosts: + dubbo: + - route detail: + - match: + -method: + - args: + - index: 1 + type: java.lang.Boolean + bool_value: #BoolMatch + - exact: true +``` ++ property description + +| Field | Type | Description | Required | +| --- | --- | --- | --- | +| exact | bool(oneof) | `true`, `false`, exact match | | + +### ObjectMatch (not implemented) +`ObjectMatch` for an exact match on any object ++ Example of use +```yaml +apiVersion: service.dubbo.apache.org/v1alpha1 +kind: VirtualService +metadata: + name: demo/StandardRouter +spec: + hosts: + dubbo: + - route detail: + - match: + -method: + - args: + - index: 1 + type: java.lang.String + str_value: + oneof: + - regex: "*abc*" + - exact: parameter-1 +``` ++ property description + +| Field | Type | Description | Required | +| --- | --- | --- | --- | +| type | string | The type of the matching parameter, taking the string type of java as an example, the value of this field is java.lang.String, and the default value of this field is java.lang.String | YES | +| str_value | ListStringMatch | The value of the matching parameter, parsed according to $type ListStringMatcher: match java.lang.String) | NO | +| num_value | ListDoubleMatch | | NO | +| bool_value | BoolMatch | | NO | + +### DubboRouteDestination +`DubboRouteDestination` is used to describe the strategy of traffic to the destination address ++ Example of use +```yaml +apiVersion: service.dubbo.apache.org/v1alpha1 +kind: VirtualService +metadata: + name: demo/StandardRouter +spec: + hosts: + dubbo: + - route detail: + - route: #DubboRouteDestination + destination: + weight: 50 +``` ++ property description + +| Field | Type | Description | Required | +| --- | --- | --- | --- | +| destination | DubboDestination | routing destination Destination | YES | +| weight | int | routing weight | NO | + +### DubboDestination +`DubboDestination` is used to describe the destination address of routing traffic ++ Example of use +```yaml +apiVersion: service.dubbo.apache.org/v1alpha1 +kind: VirtualService +metadata: + name: demo/StandardRouter +spec: + hosts: + dubbo: + - route detail: + - route: #DubboRouteDestination + destination: + host: + subnet: + port: + fallback: +``` ++ property description + +| Field | Type | Description | Required | +| --- | --- | --- | --- | +| host | string | The corresponding `key` value in the registry, now it is the interface name |YES| +| subset | string | address list | YES | +| port | int| port number | YES | +| fallback | DubboDestination | another address list for fallback | NO | \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/traffic/mesh-style/weight-rule-deployment.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/traffic/mesh-style/weight-rule-deployment.md new file mode 100644 index 000000000000..11865d6ef6a2 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/traffic/mesh-style/weight-rule-deployment.md @@ -0,0 +1,47 @@ +--- +type: docs +title: "Weight Routing" +linkTitle: "Weight Routing" +weight: 16 +description: "Realize routing function based on user-defined weight." +--- + +```yaml +apiVersion: service.dubbo.apache.org/v1alpha1 +kind: VirtualService +metadata: + name: reviews-route +spec: + hosts: + - reviews.prod.svc.cluster.local + dubbo: + - name: weightRoute + route details: + - name: weight + route: + -destination: + host: reviews.prod.svc.cluster.local + subset: v1 + weight: 60 + + -destination: + host: reviews.prod.svc.cluster.local + subset: v2 + weight: 40 + + +--- +apiVersion: service.dubbo.apache.org/v1alpha1 +kind: DestinationRule +metadata: + name: reviews-route +spec: + host: reviews.prod.svc.cluster.local + subsets: + - name: v1 + labels: + version: v1 + - name: v2 + labels: + version: v2 +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/traffic/routing-rule.md b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/traffic/routing-rule.md new file mode 100644 index 000000000000..66aea5700729 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/traffic/routing-rule.md @@ -0,0 +1,254 @@ +--- +type: docs +title: "Routing Rules" +linkTitle: "Routing Rules" +weight: 33 +description: "Service governance through routing rules in Dubbo" +--- + +Routing rules play a role in filtering the address of the target server before initiating an RPC call, and the filtered address list will be used as an alternative address for the consumer to finally initiate an RPC call. + +- Conditional routing. Supports configuring routing rules at the granularity of services or consumer applications. +- Label routing. Configure routing rules at the granularity of Provider applications. + +In the future, we plan to continue to enhance the script routing function based on the 2.6.x version. + +## Conditional Routing + +You can write routing rules in the service management console [Dubbo-Admin](https://github.com/apache/dubbo-admin) at any time + +### Introduction + +- Application granularity + + ```yaml + # The consumer of app1 can only consume all service instances with port 20880 + # The consumers of app2 can only consume all service instances with port 20881 + --- + scope: application + force: true + runtime: true + enabled: true + key: governance-conditionrouter-consumer + conditions: + - application=app1 => address=*:20880 + - application=app2 => address=*:20881 + ... + ``` + +- Service Granularity + + ```yaml + # The sayHello method of DemoService can only consume all service instances with port 20880 + # The sayHi method of DemoService can only consume all service instances with port 20881 + --- + scope: service + force: true + runtime: true + enabled: true + key: org.apache.dubbo.samples.governance.api.DemoService + conditions: + - method=sayHello => address=*:20880 + - method=sayHi => address=*:20881 + ... + ``` + + + +### Detailed rules + +#### The meaning of each field + +- `scope` indicates the granularity of routing rules, and the value of scope will determine the value of key. **Required**. + - service service granularity + - application application granularity +- `Key` specifies which service or application the rule body acts on. **Required**. + - When scope=service, the key value is a combination of [{group}:]{service}[:{version}] + - When scope=application, the key value is the application name +- `enabled=true` Whether the current routing rule is valid, it can be left blank, and it is valid by default. +- `force=false` When the routing result is empty, whether to enforce it, if not enforced, the routing rule with an empty routing result will automatically fail, you can leave it blank, the default is `false`. +- Whether `runtime=false` executes the routing rules every time it is called, otherwise it only pre-executes and caches the results when the provider address list changes, and directly obtains the routing results from the cache when calling. If parameter routing is used, it must be set to `true`. It should be noted that the setting will affect the performance of the call. It can be left blank. The default is `false`. +- `priority=1` is the priority of routing rules, used for sorting, the higher the priority, the higher the execution, it can be left blank, the default is `0`. +- `conditions` defines specific routing rule content. **Required**. + +#### Conditions rule body + + The `conditions` part is the main body of the rule, which consists of 1 to any number of rules. Below we describe the configuration syntax of each rule in detail: + +1. **Format** + +- Before `=>` is the consumer matching condition, all parameters are compared with the consumer’s URL, and when the consumer meets the matching condition, the following filtering rules will be executed for the consumer. +- After `=>`, it is the filter condition of the provider's address list. All parameters are compared with the provider's URL, and consumers only get the filtered address list in the end. +- If the matching condition is empty, it means to apply to all consumers, such as: `=> host != 10.20.153.11` +- If the filter condition is empty, access is prohibited, such as: `host = 10.20.153.10 =>` + +2. **Expression** + +Parameter support: + +- Service call information, such as: method, argument, etc., currently does not support parameter routing +- Fields of the URL itself, such as: protocol, host, port, etc. +- and all parameters on the URL, such as: application, organization, etc. + +Conditional support: + +- The equal sign `=` means "match", such as: `host = 10.20.153.10` +- The inequality sign `!=` means "no match", such as: `host != 10.20.153.10` + +Value support: + +- Separate multiple values with comma `,`, such as: `host != 10.20.153.10,10.20.153.11` +- End with an asterisk `*`, which means wildcard, such as: `host != 10.20.*` +- Start with a dollar sign `$`, which means to quote consumer parameters, such as: `host = $host` + +3. **Condition Example** + +- Exclude pre-release machines: + +``` +=> host != 172.22.3.91 +``` + +- whitelist: + +``` +register.ip != 10.20.153.10,10.20.153.11 => +``` + +{{% alert title="Attention" color="warning" %}} +A service can only have one whitelist rule, otherwise the two rules will be filtered out +{{% /alert %}} + +- Blacklist: + +``` +register.ip = 10.20.153.10,10.20.153.11 => +``` + +- The service is hosted on the application, and only a part of the machine is exposed to prevent the entire cluster from hanging: + +``` +=> host = 172.22.3.1*,172.22.3.2* +``` + +- Additional machines for important applications: + +``` +application != kylin => host != 172.22.3.95,172.22.3.96 +``` + +- Read and write separation: + +``` +method = find*,list*,get*,is* => host = 172.22.3.94,172.22.3.95,172.22.3.96 +method != find*,list*,get*,is* => host = 172.22.3.97,172.22.3.98 +``` + +- Separation of front and back: + +``` +application = bops => host = 172.22.3.91,172.22.3.92,172.22.3.93 +application != bops => host = 172.22.3.94,172.22.3.95,172.22.3.96 +``` + +- Isolate network segments in different computer rooms: + +``` +host != 172.22.3.* => host != 172.22.3.* +``` + +- The provider and consumer are deployed in the same cluster, and the local machine only accesses the local service: + +``` +=> host = $host +``` + + + +## Label Routing Rules + +### Introduction + +Label routing divides one or more service providers into the same group and constrains traffic to flow only in the specified group, so as to achieve the purpose of traffic isolation, which can be used as the capability basis for scenarios such as blue-green release and grayscale release. + +#### Provider + +Tags mainly refer to the grouping of provider-side application instances. Currently, there are two ways to complete instance grouping, namely `dynamic rule marking` and `static rule marking`, where dynamic rules have a higher priority than static rules , and when two rules exist at the same time and conflict occurs, the dynamic rule will prevail. + +-Dynamic rule marking, you can issue label grouping rules in the **Service Governance Console** at any time + + ```yaml + # The governance-tagrouter-provider application adds two tag groups tag1 and tag2 + # tag1 contains an instance 127.0.0.1:20880 + # tag2 contains an instance 127.0.0.1:20881 + --- + force: false + runtime: true + enabled: true + key: governance-tagrouter-provider + tags: + - name: tag1 + addresses: ["127.0.0.1:20880"] + - name: tag2 + addresses: ["127.0.0.1:20881"] + ... + ``` + + + +- static marking + + ```xml + + ``` + + or + + ```xml + + ``` + + or + + ```properties + java -jar xxx-provider.jar -Ddubbo.provider.tag={the tag you want, may come from OS ENV} + ``` + + + +#### Consumer + +```java +RpcContext.getContext().setAttachment(Constants.TAG_KEY,"tag1"); +``` + +The scope of the request tag is each invocation. Use attachment to pass the request tag. Note that the value stored in the attachment will continue to be passed in a complete remote call. Thanks to this feature, we only need to call , through the setting of one line of code, the continuous transmission of tags is achieved. + +> Currently only supports hardcoding to set dubboTag. Note that RpcContext is thread-bound and use the TagRouter feature elegantly. It is recommended to set dubboTag through servlet filter (in web environment) or custom SPI filter. + + + +### Detailed rules + +#### Format + +- `Key` specifies which application the rule body applies to. **Required**. +- `enabled=true` Whether the current routing rule is valid, it can be left blank, and it is valid by default. +- `force=false` When the routing result is empty, whether to enforce it, if not enforced, the routing rule with an empty routing result will automatically fail, you can leave it blank, the default is `false`. +- Whether `runtime=false` executes the routing rules every time it is called, otherwise it only pre-executes and caches the results when the provider address list changes, and directly obtains the routing results from the cache when calling. If parameter routing is used, it must be set to `true`. It should be noted that the setting will affect the performance of the call. It can be left blank. The default is `false`. +- `priority=1` is the priority of routing rules, used for sorting, the higher the priority, the higher the execution, it can be left blank, the default is `0`. +- `tags` defines specific tag grouping content, can define any n (n>=1) tags and specify an instance list for each tag. **Required**. + - name, label name +- addresses, the list of instances contained in the current label + + + +#### Downgrading Conventions + +1. When `dubbo.tag=tag1`, the provider marked with `tag=tag1` is preferred. If there is no service corresponding to the request tag in the cluster, the provider with an empty request tag will be downgraded by default; if you want to change this default behavior, that is, no provider matching tag1 will return an exception, you need to set `dubbo.force.tag= true`. + +2. When `dubbo.tag` is not set, only the provider whose tag is empty will be matched. Even if there is an available service in the cluster, if the tag does not match, it cannot be called. This is different from Convention 1. Requests with tags can be downgraded to untagged services, but requests without tags/with other types of tags can never be accessed to other tabbed services. + +{{% alert title="Prompt" color="primary" %}} +Custom routing reference [routing extension](/en/docs3-v2/java-sdk/reference-manual/spi/description/router/) +{{% /alert %}} \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/concepts-and-architecture/_index.md b/content/en/docs3-v2/java-sdk/concepts-and-architecture/_index.md new file mode 100755 index 000000000000..3abffcbaa4a2 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/concepts-and-architecture/_index.md @@ -0,0 +1,8 @@ + +--- +type: docs +title: "Concepts and Architecture" +linkTitle: "Concepts and Architecture" +weight: 3 +--- + diff --git a/content/en/docs3-v2/java-sdk/concepts-and-architecture/code-architecture.md b/content/en/docs3-v2/java-sdk/concepts-and-architecture/code-architecture.md new file mode 100644 index 000000000000..27822c0a2bb0 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/concepts-and-architecture/code-architecture.md @@ -0,0 +1,103 @@ +--- +type: docs +title: "Code Architecture" +linkTitle: "Code Architecture" +weight: 2 +--- + + +## overall design + +![/dev-guide/images/dubbo-framework.jpg](/imgs/dev/dubbo-framework.jpg) + +illustration: + +* The light blue background on the left in the figure is the interface used by the service consumer, the light green background on the right is the interface used by the service provider, and the interface on the central axis is the interface used by both parties. +* The figure is divided into ten layers from bottom to top. Each layer is one-way dependent. The black arrow on the right represents the dependency relationship between layers. Each layer can be reused by stripping the upper layer. Among them, the Service and Config layers are API , the other layers are SPI. +* The small green block in the figure is the extension interface, and the small blue block is the implementation class. Only the implementation class used to associate each layer is shown in the figure. +* The blue dotted line in the figure is the initialization process, that is, the assembly chain at startup, the red solid line is the method call process, that is, the runtime call chain, and the purple triangle arrow is inheritance. You can regard the subclass as the same node of the parent class, and the line The text above is the method to call. + +## Description of each layer + +* **Config configuration layer**: external configuration interface, centered on `ServiceConfig`, `ReferenceConfig`, can directly initialize configuration classes, or generate configuration classes through spring parsing configuration +* **Proxy service proxy layer**: service interface transparent proxy, generating service client Stub and server Skeleton, with `ServiceProxy` as the center, the extended interface is `ProxyFactory` +* **Registry registration center layer**: Encapsulates the registration and discovery of service addresses, centered on service URLs, and the extended interfaces are `RegistryFactory`, `Registry`, `RegistryService` +* **Cluster routing layer**: Encapsulate the routing and load balancing of multiple providers, and bridge the registration center, with `Invoker` as the center, and the extended interfaces are `Cluster`, `Directory`, `Router`, `LoadBalance` +* **Monitor monitoring layer**: RPC call times and call time monitoring, centered on `Statistics`, extended interfaces are `MonitorFactory`, `Monitor`, `MonitorService` +* **Protocol remote call layer**: Encapsulates RPC calls, centered on `Invocation`, `Result`, extended interfaces are `Protocol`, `Invoker`, `Exporter` +* **Exchange information exchange layer**: encapsulation request response mode, synchronous to asynchronous, centered on `Request`, `Response`, extended interfaces are `Exchanger`, `ExchangeChannel`, `ExchangeClient`, `ExchangeServer` +* **Transport network transport layer**: Abstract mina and netty as a unified interface, with `Message` as the center, and extended interfaces as `Channel`, `Transporter`, `Client`, `Server`, `Codec` +* **Serialize data serialization layer**: some reusable tools, the extended interfaces are `Serialization`, `ObjectInput`, `ObjectOutput`, `ThreadPool` + +## Relationship description + +* In RPC, Protocol is the core layer, that is, as long as there is Protocol + Invoker + Exporter, non-transparent RPC calls can be completed, and then Filter interception points on the main process of Invoker. +* The Consumer and Provider in the picture are abstract concepts, just to let the viewer understand more intuitively which classes belong to the client and server. The reason for not using Client and Server is that Dubbo uses Provider, Consumer, Registry in many scenarios , Monitor divides logical topology nodes and maintains a unified concept. +* Cluster is a peripheral concept, so the purpose of Cluster is to disguise multiple Invokers as one Invoker, so that other people only need to pay attention to the Protocol layer Invoker. Adding Cluster or removing Cluster will not affect other layers, because there is only one Provider, Cluster is not required. +* The Proxy layer encapsulates the transparent proxy of all interfaces, and the Invoker is the center in other layers. Only when it is exposed to the user, the Proxy is used to convert the Invoker into an interface, or convert the interface implementation into an Invoker, that is, remove Proxy layer RPC can be run, but it is not so transparent, and it does not look like calling remote services like calling local services. +* The Remoting implementation is the implementation of the Dubbo protocol. If you choose the RMI protocol, the entire Remoting will not be used. The Remoting is divided into the Transport transport layer and the Exchange information exchange layer. The Transport layer is only responsible for one-way message transmission. , Netty, Grizzly's abstraction, it can also extend UDP transmission, and the Exchange layer encapsulates the Request-Response semantics above the transport layer. +* Registry and Monitor are actually not considered a layer, but an independent node, just for a global overview, drawn together in layers. + +## Module Subpackage + +![/dev-guide/images/dubbo-modules.jpg](/imgs/dev/dubbo-modules.jpg) + +Module description: + +* **dubbo-common public logic module**: including Util class and common model. +* **dubbo-remoting remote communication module**: equivalent to the implementation of the Dubbo protocol, if the RPC uses the RMI protocol, this package does not need to be used. +* **dubbo-rpc remote call module**: abstracts various protocols and dynamic proxy, only includes one-to-one calls, and does not care about cluster management. +* **dubbo-cluster cluster module**: Disguise multiple service providers as one provider, including: load balancing, fault tolerance, routing, etc. The address list of the cluster can be statically configured, or it can be configured by the registration center send. +* **dubbo-registry registration center module**: based on the clustering method issued by the registration center, and the abstraction of various registration centers. +* **dubbo-monitor monitoring module**: Statistics of service call times, call time, and call chain tracking services. +* **dubbo-config configuration module**: Dubbo’s external API, users use Dubbo through Config, hiding all details of Dubbo. +* **dubbo-container container module**: It is a Standlone container, loaded with a simple Main to start Spring, because services usually do not require the features of web containers such as Tomcat/JBoss, there is no need to use web containers to load services. + +On the whole, subcontracting is carried out according to the hierarchical structure. The difference from the layering is: + +* Container is a service container, which is used to deploy and run services, and is not drawn in the layer. +* Both the Protocol layer and the Proxy layer are placed in the rpc module. These two layers are the core of rpc. When there is no need for a cluster, that is, there is only one provider, you can use only these two layers to complete the rpc call. +* Both the Transport layer and the Exchange layer are placed in the remoting module, which is the communication basis for rpc calls. +* The Serialize layer is placed in the common module for greater reuse. + +## Dependencies + +![/dev-guide/images/dubbo-relation.jpg](/imgs/dev/dubbo-relation.jpg) + +illustration: + +* The small squares in the figure Protocol, Cluster, Proxy, Service, Container, Registry, Monitor represent layers or modules, the blue ones indicate that they interact with the business, and the green ones only interact with Dubbo internally. +* The background squares Consumer, Provider, Registry, Monitor in the figure represent the deployment logic topology nodes. +* The blue dotted line in the figure is the call at initialization, the red dotted line is the asynchronous call at runtime, and the red solid line is the synchronous call at runtime. +* Only the RPC layer is included in the figure, and the Remoting layer is not included. Remoting is implicitly included in the Protocol as a whole. + +## call chain + +Expand the red call chain of the general design diagram, as follows: + +![/dev-guide/images/dubbo-extension.jpg](/imgs/dev/dubbo-extension.jpg) + +## Expose service timing + +Expand the blue initialization chain of the exposed service of the service provider on the right side of the general design diagram, and the sequence diagram is as follows: + +![/dev-guide/images/dubbo-export.jpg](/imgs/dev/dubbo-export.jpg) + +## Reference service timing + +Expand the green initialization chain of the service consumer reference service on the left side of the general design diagram, and the sequence diagram is as follows: + +![/dev-guide/images/dubbo-refer.jpg](/imgs/dev/dubbo-refer.jpg) + +## Domain Model + +In Dubbo's core domain model: + +* Protocol is the service domain, which is the main function entry exposed and referenced by Invoker, and it is responsible for the life cycle management of Invoker. +* Invoker is an entity domain, it is the core model of Dubbo, other models are close to it, or converted to it, it represents an executable body, can initiate an invoke call to it, it may be a local implementation, or it may be Is a remote implementation, and possibly a cluster implementation. +* Invocation is a session domain, which holds variables in the calling process, such as method names, parameters, etc. + +## Basic Design Principles + +* Adopt Microkernel + Plugin mode, Microkernel is only responsible for assembling Plugin, and Dubbo's own functions are also realized through extension points, that is, all function points of Dubbo can be replaced by user-defined extensions. +* URL is used as the unified format of configuration information, and all extension points carry configuration information by passing URL. \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/concepts-and-architecture/mesh.md b/content/en/docs3-v2/java-sdk/concepts-and-architecture/mesh.md new file mode 100644 index 000000000000..b69e4d2110cc --- /dev/null +++ b/content/en/docs3-v2/java-sdk/concepts-and-architecture/mesh.md @@ -0,0 +1,71 @@ +--- +type: docs +title: "Dubbo Mesh" +linkTitle: "Dubbo Mesh" +weight: 5 +--- + +From the design concept, Dubbo Mesh emphasizes the unified control, standardization and governance capabilities of the control plane, while giving more choices on the data plane, including deployment modes such as Sidecar Mesh and Proxyless Mesh. Multiple deployment models provide enterprises with more choices. Through the hybrid deployment model, while realizing the sharing of the service governance control plane, it can better respond to the deployment requirements of different scenarios (performance, deployment complexity, etc.), and adapt to complex infrastructure environment and improve the availability of the architecture as a whole. + +## background +In the context of cloud native, if we understand Service Mesh as the underlying infrastructure, in the Mesh architecture, some of the capabilities of microservice governance that were previously coupled in the business process are being taken over by Mesh. The traditional microservice framework pays more attention to RPC protocols and programming. Model. The following is an architecture diagram of the popular Mesh product Istio: + +![istio](/imgs/v3/mesh/istio.jpg) + +Under the Mesh architecture +* The unified control plane provides certificate management, observability, traffic governance and other capabilities +* Sidecar makes the SDK lighter and less intrusive, better implementing transparent upgrades, traffic interception, etc. + +## Dubbo Mesh Overall Architecture + +![istio](/imgs/v3/mesh/dubbo-mesh-arc.png) + +* The data plane performs RPC communication based on the Triple protocol; +* The address discovery model adopts application-level service discovery to support ultra-large-scale instance clusters while providing richer service governance capabilities; +* The Dubbo Mesh control plane is based on the industry's mainstream Istio extension, supports Dubbo service discovery customization solutions, and provides richer traffic control capabilities; +* The data plane supports two modes: ThinSDK + Sidecar (such as Envoy) and Proxyless; + + +> For old Dubbo2 users or users who have upgraded Dubbo3 but have not yet migrated new features, you can consider referring to Dubbo solutions provided by other Mesh open source communities (such as Aeraki). +> However, some functions may be limited, and there will be certain performance and capacity bottlenecks. + +### Dubbo Sidecar Mesh +Dubbo provides a ThinSDK deployment mode. In this mode, Dubbo ThinSDK will only provide business application-oriented programming APIs and RPC transmission and communication capabilities, and the rest of the service management +Including address discovery, load balancing, routing addressing, etc., all sink to Sidecar, and Sidecar is responsible for direct communication with the control plane and receiving various traffic control rules. The following is a basic deployment architecture diagram. Dubbo ThinSDK and Sidecar are deployed in the same pod or container. By deploying an independent control plane on the periphery, unified control of traffic and governance is achieved. The control plane and Sicecar are configured and distributed through the xDS protocol shown in the dotted line in the figure, and the communication between Dubbo processes is no longer a direct connection mode, but instead passes through the Sidecar proxy, which intercepts all incoming and outgoing traffic and completes routing and addressing, etc. Service governance tasks. + +![dubbo-sidecar](/imgs/v3/mesh/dubbo-sidecar.png) + +The community recommends Envoy as a sidecar, and the communication protocol uses Triple for better gateway penetration and performance experience. For users who are still using the Dubbo2 protocol who cannot upgrade Triple temporarily, they can refer to the Dubbo2 protocol support solutions provided by Envoy and Aeraki Mesh. + +The Mesh architecture of the ThinSDK + Sidecar mode has many advantages, such as smooth upgrade, multi-language, and small business intrusion, but it also brings some additional problems, such as: +* Sidecar communication brings additional performance loss, which will become especially obvious in network calls with complex topologies. +* The existence of Sidecar makes the life cycle management of the application more complicated. +* The deployment environment is limited, not all environments can meet the requirements of Sidecar deployment and request interception. + +For detailed scheme design and examples, please refer to +* [Dubbo ThinSDK Proposal](/zh/overview/tasks/mesh/dubbo-mesh) +* [Example of use](/zh/overview/tasks/mesh/dubbo-mesh) + +### Dubbo Proxyless Mesh +As a supplement to the ThinSDK + Sidecar model, the Dubbo community has conceived and thought about the direct connection of Dubbo to the control plane since a long time ago, which is currently called the Proxyless Mesh model. The Proxyless mode brings microservices back to the deployment architecture of the 2.x era. As shown in the figure below, it is very similar to the Dubbo classic service governance model we saw above, so this model is not new. Dubbo has been such a design model from the very beginning. However, compared with the Mesh architecture, Dubbo2 does not emphasize the unified management and control of the control plane, which is exactly what Service Mesh emphasizes. It emphasizes the standardized management, control and governance of traffic, observability, certificates, etc., which is also an advanced part of the Mesh concept. . + +![dubbo-proxyless](/imgs/v3/mesh/dubbo-proxyless.png) + +Through the Dubbo3 SDK of different language versions, the xDS protocol analysis can be directly realized, and the Dubbo process can directly communicate with the control plane (Control Plane), so as to realize the unified control of traffic control, service governance, observability, security, etc. of the control plane, avoiding the Sidecar mode The resulting performance loss and complexity of the deployment architecture. + +> Proxyless mode supports both Dubbo2 and Triple protocols, but only supports the address model of application-level service discovery. + +In the Dubbo3 Proxyless architecture mode, the Dubbo process will directly communicate with the control plane, and the Dubbo process will continue to maintain a direct communication mode. We can see the advantages of the Proxyless architecture: +* There is no additional proxy loss, so it is more suitable for performance-sensitive applications +* More conducive to smooth migration of legacy systems +* Simple architecture, easy operation and maintenance deployment +* Suitable for almost all deployment environments + +For detailed scheme design and examples, please refer to +* [Dubbo Proxyless Mesh](/zh/overview/tasks/mesh/dubbo-mesh) +* [Example of use](/zh/overview/tasks/mesh/dubbo-mesh) + +### Dubbo Control Plane Governance Rules +TBD + +Dubbo SDK provides very flexible configurations to control service governance behaviors, such as interface granular service address discovery capabilities, interface granular configuration synchronization, etc. These capabilities make application development and deployment more flexible. However, some advanced functions may be limited under the general Mesh deployment scheme or product, which generally affects the ease of use and flexibility. To this end, Dubbo plans to provide self-developed control surface products to maximize the capabilities of Dubbo3 in the Mesh system. \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/concepts-and-architecture/overall-architecture.md b/content/en/docs3-v2/java-sdk/concepts-and-architecture/overall-architecture.md new file mode 100644 index 000000000000..f1aadd0eb72a --- /dev/null +++ b/content/en/docs3-v2/java-sdk/concepts-and-architecture/overall-architecture.md @@ -0,0 +1,72 @@ +--- +type: docs +title: "Overall Architecture" +linkTitle: "Overall Architecture" +weight: 1 +--- + + +![dubbo-architecture](/imgs/user/dubbo-architecture.jpg) + +##### Node role description + +| Node | Role Description | +| ------------- | ------------- | +| `Provider` | The service provider of the exposed service | +| `Consumer` | The service consumer who invokes the remote service | +| `Registry` | Registry for service registration and discovery | +| `Monitor` | A monitoring center that counts service calls and call times | +| `Container` | service running container | + +##### Description of calling relationship + +0. The service container is responsible for starting, loading, and running the service provider. +1. When the service provider starts, it registers the services it provides with the registration center. +2. When a service consumer starts, it subscribes to the registration center for the services it needs. +3. The registration center returns the service provider address list to the consumer. If there is a change, the registration center will push the change data to the consumer based on the long connection. +4. The service consumer, from the provider address list, selects a provider to call based on the soft load balancing algorithm, and if the call fails, select another provider to call. +5. Service consumers and providers accumulate the number of invocations and invocation time in memory, and regularly send statistical data to the monitoring center every minute. + +The Dubbo architecture has the following characteristics, namely connectivity, robustness, scalability, and upgradeability to future architectures. + +## Connectivity + +* The registration center is responsible for the registration and search of service addresses, which is equivalent to directory services. Service providers and consumers only interact with the registration center at startup. The registration center does not forward requests, and the pressure is less +* The monitoring center is responsible for counting the number of service calls, call time, etc., and the statistics are first summarized in the memory and sent to the monitoring center server every minute, and displayed in reports +* The service provider registers the services it provides with the registration center, and reports the call time to the monitoring center, which does not include network overhead +* The service consumer obtains the address list of the service provider from the registration center, and directly calls the provider according to the load algorithm, and reports the calling time to the monitoring center, which includes network overhead +* The registration center, service provider, and service consumer are all long connections, except for the monitoring center +* The registration center perceives the existence of the service provider through a long connection, and if the service provider goes down, the registration center will immediately push the event to notify the consumer +* The registration center and monitoring center are all down, and the running providers and consumers are not affected. Consumers cache the list of providers locally +* Both registration center and monitoring center are optional, and service consumers can directly connect to service providers + +## Robustness + +* The downtime of the monitoring center does not affect the use, but part of the sampling data is lost +* After the database is down, the registration center can still provide service list query through the cache, but cannot register new services +* Registration center peer-to-peer cluster, when any one goes down, it will automatically switch to another +* After the registration center is completely down, the service provider and the service consumer can still communicate through the local cache +* The service provider is stateless, and if any one goes down, it will not affect the use +* After the service provider is all down, the service consumer application will be unavailable and will reconnect infinitely waiting for the service provider to recover + +## Scalability + +* The registration center is a peer-to-peer cluster, which can dynamically increase machine deployment instances, and all clients will automatically discover the new registration center +* The service provider is stateless and can dynamically increase machine deployment instances, and the registration center will push new service provider information to consumers + +## Upgradability + +When the scale of service clusters is further expanded and the IT governance structure is further upgraded, it is necessary to realize dynamic deployment and perform flow computing, and the existing distributed service architecture will not bring resistance. The following figure is a possible architecture in the future: + +![dubbo-architecture-futures](/imgs/user/dubbo-architecture-future.jpg) + +##### Node role description + +| Node | Role Description | +| ------------- | ------------- | +| `Deployer` | A local proxy for auto-deployment services | +| `Repository` | The warehouse is used to store the service application release package | +| `Scheduler` | The scheduling center automatically increases or decreases service providers based on access pressure | +| `Admin` | Unified Admin Console | +| `Registry` | Registry for service registration and discovery | +| `Monitor` | A monitoring center that counts service calls and call times | \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/concepts-and-architecture/service-discovery.md b/content/en/docs3-v2/java-sdk/concepts-and-architecture/service-discovery.md new file mode 100644 index 000000000000..21017e978d07 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/concepts-and-architecture/service-discovery.md @@ -0,0 +1,59 @@ +--- +type: docs +title: "Service Discovery" +linkTitle: "Service Discovery" +weight: 3 +--- +Service discovery, that is, the ability of the consumer to automatically discover the list of service addresses, is a key capability that the microservice framework needs to have. With the help of automated service discovery, microservices can be implemented without knowing the deployment location and IP address of the peer. communication. + +### Method to realize +There are many ways to realize service discovery. Dubbo provides a Client-Based service discovery mechanism. Usually, additional third-party registry components need to be deployed to coordinate the service discovery process, such as commonly used Nacos, Consul, Zookeeper, etc. Dubbo itself also provides the connection to various registry components, and users can choose flexibly. + +### working principle +Dubbo is based on the automatic service discovery capability of the consumer, and its basic working principle is as follows: + +![//imgs/architecture.png](/imgs/architecture.png) + +A core component of service discovery is the registry, Provider registers addresses to the registry, and Consumer reads and subscribes to the Provider address list from the registry. +Therefore, to enable service discovery, you need to add registry configuration to Dubbo: + +Take dubbo-spring-boot-starter as an example, add registry configuration + +```properties +# application.properties +dubbo + registry + address: zookeeper://127.0.0.1:2181 +``` + +### Introduction to application-level service discovery +In summary, the application-level service discovery introduced by Dubbo3 mainly has the following advantages +* Adapt to cloud-native microservice changes. The infrastructure capabilities in the cloud-native era are continuously released upwards. Platforms such as Kubernetes integrate the conceptual abstraction of microservices. Dubbo3's application-level service discovery is a general model for adapting various microservice systems. +* Improved performance and scalability. The service governance that supports ultra-large-scale clusters has always been Dubbo's advantage. By introducing an application-level service discovery model, it essentially solves the storage and push pressure of the registry address data, and the corresponding address calculation pressure on the consumer side also drops by an order of magnitude. ; The cluster size has also become predictable and assessable (it has nothing to do with the number of RPC interfaces, but only with the instance deployment scale). + +The following figure shows the service discovery model of Dubbo2: Provider registers the service address, Consumer coordinates with the registration center and discovers the service address, and then initiates communication with the address. This is the classic service discovery process used by most microservice frameworks. The special feature of Dubbo2 is that it also integrates the information of "RPC interface" into the address discovery process, and this part of information is often closely related to specific business definitions. + +![//imgs/v3/concepts/servicediscovery_old.png](/imgs/v3/concepts/servicediscovery_old.png) + +After accessing the cloud-native infrastructure, the infrastructure incorporates the abstraction of the concept of microservices, and the process of orchestrating and scheduling containerized microservices completes the registration at the infrastructure level. As shown in the figure below, the infrastructure not only assumes the responsibility of the registration center, but also completes the service registration action, and the information of the "RPC interface", because it is related to specific businesses, is impossible and unsuitable to be hosted by the infrastructure. + +![//imgs/v3/concepts/servicediscovery_k8s.png](/imgs/v3/concepts/servicediscovery_k8s.png) + +In such a scenario, there are two requirements for Dubbo3's service registration discovery mechanism: +Dubbo3 needs to abstract a common address mapping model that has nothing to do with business logic in the original service discovery process, and ensure that this part of the model is reasonable enough to support entrusting the registration behavior and storage of addresses to the underlying infrastructure +Dubbo3's unique business interface synchronization mechanism is an advantage that Dubbo3 needs to retain. It needs to be resolved through its own mechanism within the framework on top of the new address model defined in Dubbo3. + +The new service discovery model designed in this way brings greater advantages to Dubbo3 in terms of architecture compatibility and scalability. + +![//imgs/v3/concepts/servicediscovery_mem.png](/imgs/v3/concepts/servicediscovery_mem.png) + +In terms of architectural compatibility, as mentioned above, it is possible for Dubbo3 to reuse the service abstraction capabilities of the underlying infrastructure; on the other hand, other microservice solutions in the industry such as Spring Cloud also follow this model. +After opening the address discovery, it becomes possible for users to explore using Dubbo to connect heterogeneous microservice systems. + +The Dubbo3 service discovery model is more suitable for building a scalable service system. How to understand this? +Here is a simple example to intuitively compare the data flow changes in the address discovery process between Dubbo2 and Dubbo3: Suppose a microservice application defines 100 interfaces (services in Dubbo), +You need to register 100 services in the registry. If this application is deployed on 100 machines, then these 100 services will generate a total of 100 * 100 = 10000 virtual nodes; and the same application, +For Dubbo3, the new registration discovery model only needs 1 service (only related to the application and has nothing to do with the interface), and only registers 1 * 100 = 100 virtual nodes equal to the number of machine instances to the registration center. +In this simple example, the number of addresses registered by Dubbo has dropped to 1/100 of the original, which greatly relieves the storage pressure on the registration center and subscribers. more importantly, +The address discovery capacity is completely decoupled from the business RPC definition, and the capacity evaluation of the entire cluster will become more transparent for operation and maintenance: as many machines are deployed as there are loads, it will not be like Dubbo2. +Because business RPC reconstruction will affect the stability of the entire cluster service discovery. \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/concepts-and-architecture/service-invocation.md b/content/en/docs3-v2/java-sdk/concepts-and-architecture/service-invocation.md new file mode 100644 index 000000000000..c5b731acb549 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/concepts-and-architecture/service-invocation.md @@ -0,0 +1,155 @@ +--- +type: docs +title: "Service Call Extension Point" +linkTitle: "Service Call" +weight: 4 +description: "This article will introduce how to customize the core extension points on the call link in Dubbo 3 to meet your needs." +--- + +![dubbo-architecture](/imgs/v3/concepts/invoke-arch.jpg) + +As shown in the figure above, from the perspective of service invocation, Dubbo provides a wealth of extension points in the link, covering load balancing methods, interceptors before and after site selection, and server-side processing interceptors. +To put it simply, when Dubbo initiates a remote call, the main workflow can be divided into two parts: the consumer side and the server side. + +The workflow on the consumer side is as follows: +- Receive requests from users through Stub and encapsulate them in `Invocation` object +- Pass the `Invocation` object to `ClusterFilter` (**extension point**) for request preprocessing before site selection, such as conversion of request parameters, request logging, current limiting and other operations are carried out at this stage +- Pass the `Invocation` object to `Cluster` (**extension point**) for decision-making of cluster invocation logic, such as fast failure mode, safe failure mode and other decisions are made at this stage + - `Cluster` calls `Directory` to get all available server address information + - `Directory` calls `StateRouter` (**extension point**, recommended) and `Router` (**extension point**) to filter the address information of the server. This stage is mainly from the full amount of address information Filter out the targets that are allowed to be called in this call, such as marking-based traffic routing is carried out at this stage + - After `Cluster` obtains the available server information provided by `Directory`, it will call `LoadBalance` (**extension point**) to select a target for this call from multiple addresses, such as random call, polling Strategies such as calling and consistent hashing are carried out at this stage + - `Cluster` obtains the `Invoker` of the target, and then passes `Invocation` to the corresponding `Invoker`, and waits for the result to be returned, and executes the corresponding decision if an error occurs (such as fast failure, safety failure, etc.) +- After the above processing, the `Invoker` with the target address information is obtained, and `Filter` (**extension point**) will be called to process the request after the address selection (due to the `Filter` created on the consumer side The magnitude is the same as that of the server address. If there is no special need, it is recommended to use `ClusterFilter` for extended interception to improve performance) +- Finally `Invocation` will be sent to the server over the network + +The workflow of the server is as follows: +- After the server communication layer receives the request, it will pass the request to the protocol layer to construct `Invocation` +- Pass the `Invocation` object to `Filter` (**extension point**) to pre-process the server request, such as server authentication, logging, current limiting and other operations are performed at this stage +- Pass the `Invocation` object to the dynamic proxy to make the real server call + +## Filter (interceptor) + +The interceptor can implement the interception of the call process of the service provider and the service consumer. Most of Dubbo's own functions are implemented based on this extension point. Every time the remote method is executed, the interception will be executed. Please pay attention to the impact on performance. +Among them, on the consumer side, `ClusterFilter` is used for interception before location selection and `Filter` is used for interception after location selection. If there is no special need, use `ClusterFilter` for extended interception to improve performance. + +![filter-architecture](/imgs/v3/concepts/filter-arch.jpg) + +In Dubbo 3, the interface signatures of `Filter` and `ClusterFilter` are unified and abstracted into `BaseFilter`, and developers can implement the interfaces of `Filter` or `ClusterFilter` respectively to implement their own interceptors. +If you need to intercept the return status, you can directly implement the `BaseFilter.Listener` interface, and Dubbo will automatically recognize and call it. + +```java +package org.apache.dubbo.rpc; + +public interface BaseFilter { + + Result invoke(Invoker invoker, Invocation invocation) throws RpcException; + + interface Listener { + + void onResponse(Result appResponse, Invoker invoker, Invocation invocation); + + void onError(Throwable t, Invoker invoker, Invocation invocation); + } +} +``` + +```java +package org.apache.dubbo.rpc; + +@SPI(scope = ExtensionScope. MODULE) +public interface Filter extends BaseFilter { +} +``` + +```java +package org.apache.dubbo.rpc.cluster.filter; + +@SPI(scope = ExtensionScope. MODULE) +public interface ClusterFilter extends BaseFilter { +} +``` + +In particular, if `Filter` or `ClusterFilter` needs to be effective on the Consumer side, the `@Activate` annotation needs to be added, and the value of `group` needs to be `consumer`. + +```java +@Activate(group = CommonConstants. CONSUMER) +``` + +If `Filter` or `ClusterFilter` needs to be effective on the Provider side, the `@Activate` annotation needs to be added, and the value of `group` needs to be `provider`. + +```java +@Activate(group = CommonConstants. PROVIDER) +``` + +Please refer to [Reference](../../reference-manual/spi/description/filter/) for specific call interception extension methods + +## Router (routing address selection) + +Routing address selection provides the ability to select a batch of target providers that meet the conditions from multiple service providers to call. +Dubbo's routing mainly needs to implement 3 interfaces, which are the `route` method responsible for each call screening, the `notify` method responsible for caching after the address is pushed, and the `stop` method for destroying the route. +It is recommended to implement the `StateRouter` interface in Dubbo 3, which can provide high-performance routing address selection. + +```java +package org.apache.dubbo.rpc.cluster.router.state; + +public interface StateRouter { + + BitList> route(BitList> invokers, URL url, Invocation invocation, + boolean needToPrintMessage, Holder> nodeHolder) throws RpcException; + + void notify(BitList> invokers); + + void stop(); +} +``` + +```java +package org.apache.dubbo.rpc.cluster; + +public interface Router extends Comparable { + + @Deprecated + List> route(List> invokers, URL url, Invocation invocation) throws RpcException; + + RouterResult> route(List> invokers, URL url, Invocation invocation, + boolean needToPrintMessage) throws RpcException; + + void notify(List> invokers); + + void stop(); +} +``` + +Please refer to [Reference](../../reference-manual/spi/description/router/) for specific routing address selection expansion methods + +## Cluster (cluster rules) + +Cluster rules provide capabilities such as result aggregation and fault tolerance when there are multiple service providers. + +```java +package org.apache.dubbo.rpc.cluster.support; + +public abstract class AbstractClusterInvoker implements ClusterInvoker { + + protected abstract Result doInvoke(Invocation invocation, List> invokers, + LoadBalance loadbalance) throws RpcException; +} +``` + + +Please refer to [Reference](../../reference-manual/spi/description/cluster/) for specific cluster rule extension methods + +## LoadBalance + +Load balancing provides the ability to select **one** target provider to call from multiple service providers. + +```java +package org.apache.dubbo.rpc.cluster; + +public interface LoadBalance { + + Invoker select(List> invokers, URL url, Invocation invocation) throws RpcException; +} +``` + +Please refer to [Reference](../../reference-manual/spi/description/load-balance/) for specific call interception extension methods \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/concepts-and-architecture/triple.md b/content/en/docs3-v2/java-sdk/concepts-and-architecture/triple.md new file mode 100644 index 000000000000..76630a550226 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/concepts-and-architecture/triple.md @@ -0,0 +1,24 @@ +--- +type: docs +title: "Triple Protocol" +linkTitle: "Triple Protocol" +weight: 6 +--- +### Protocol Description +Triple is an HTTP2-based open protocol proposed by Dubbo3, which aims to solve the interoperability problems brought about by Dubbo2's private protocol. Compared with the original Dubbo2 protocol, Triple has the following advantages: + +1. Interoperability between native and gRPC protocols. Open up the gRPC ecology and reduce the migration cost from gRPC to Dubbo. +2. Enhance multilingual ecology. Avoid the problem of difficulty in business selection and adaptation due to insufficient capabilities of Dubbo SDK in CPP/C#/RUST and other languages. +3. Gateway friendly. The gateway does not need to participate in serialization, which is convenient for users to upgrade from the traditional HTTP to generalized Dubbo call gateway to the open source or cloud vendor's Ingress solution. +4. Perfect asynchronous and streaming support. It brings performance improvement from the underlying protocol to the upper-layer business, and it is easy to build a full-link asynchronous streaming service that strictly guarantees the order of messages. + +**Currently, the Dubbo SDK for Java and Go fully supports the Triple protocol. ** In Alibaba, the Triple protocol is widely used for cross-environment, cross-language, and cross-ecology interoperability, and hundreds of thousands of containers have been used in production. + +### Support methods +Java SDK supports [IDL Generate Stub](/en/docs3-v2/java-sdk/quick-start/idl) +and [Java Interface](/en/docs3-v2/java-sdk/quick-start/idl), the IDL method is recommended for multi-language, ecological interoperability, and streaming requirements, and the smooth upgrade of existing services is recommended +Interface method. + +- How old Dubbo2 users can upgrade from existing protocol to Triple(TBD) +- New user or business reference [Dubbo3 Triple Quick Start](/en/docs3-v2/java-sdk/quick-start/idl/) +- In-depth understanding of the Triple protocol: [Dubbo3 Triple Protocol Design and Principles](https://github.com/apache/dubbo-awesome/blob/master/proposals/D0-triple.md) \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/0/1.md b/content/en/docs3-v2/java-sdk/faq/0/1.md new file mode 100644 index 000000000000..d949839e278d --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/0/1.md @@ -0,0 +1,22 @@ +--- +type: docs +title: "0-1 - thread pool resource exhausted" +linkTitle: "0-1 - thread pool resources exhausted" +weight: 1 +--- +The server's thread resources are exhausted. +By default, the number of business threads on the Dubbo server is 200. If the number of concurrent requests exceeds 200, new requests will be rejected and this error will be thrown. + +### possible reason +1. The amount of concurrent requests from the Consumer is too large, causing the number of threads created on the Provider to exceed the limit. +2. It is possible that when the Provider side executes the business, the thread is blocked because the business calls the external application interface, which makes the thread pool unable to recycle the thread. + +### Troubleshooting and resolution steps +* Enable Dubbo's access log function to check whether there are a large number of calls to RPC services in a short period of time. +* Check the status of each thread in the thread pool through the `jps` and `jstack` instructions to see if there is any business calling the external application interface to cause blocking. +* If the amount of concurrent requests from the Consumer is too large, then adjust the `dubbo.provider.threads` parameter on the Provider side to increase the number of Dubbo thread pools. +* If the QPS of the Provider business is too large to be handled by the current number of servers, then increase the number of Provider-side servers so that more servers can share the pressure. + + +> The FAQ page of this error code refers to ["Dubbo Common Errors and Solutions"](https://github.com/StabilityMan/StabilityGuide/blob/master/docs/diagnosis/plugin/rpc/%E7%B3%BB%E7%BB%9F%E7%A8%B3%E5%AE%9A%E6%80%A7%E2%80%94%E2%80%94Dubbo%E5%B8%B8%E8%A7%81%E9%94%99%E8%AF%AF%E5%8F%8A%E8%A7%A3%E5%86%B3%E6%96%B9%E6%B3%95.md). +Articles cited are compiled under license [CC-BY-4.0](http://creativecommons.org/licenses/by/4.0/). Thanks to the original author here. \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/0/10.md b/content/en/docs3-v2/java-sdk/faq/0/10.md new file mode 100644 index 000000000000..a2d36298954a --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/0/10.md @@ -0,0 +1,17 @@ +--- +type: docs +title: "0-10 - The current call is no longer supported" +linkTitle: "0-10 - The current call is no longer supported" +weight: 10 +--- + + +### possible reason + +The currently called method may have been deprecated or declared `@Deprecated`, which does not affect the execution result. + +### Troubleshooting and resolution steps + +Please use other alternative API methods. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/0/11.md b/content/en/docs3-v2/java-sdk/faq/0/11.md new file mode 100644 index 000000000000..cf97f1660136 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/0/11.md @@ -0,0 +1,17 @@ +--- +type: docs +title: "0-11 - Service stop failed" +linkTitle: "0-11 - Service stop failure" +weight: 11 +--- + + +### possible reason + +The connection is not closed in time or the memory is insufficient, causing some exceptions when the service stops. + +### Troubleshooting and resolution steps + +Close the connection after the response content is completed. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/0/12.md b/content/en/docs3-v2/java-sdk/faq/0/12.md new file mode 100644 index 000000000000..5e01ce184d02 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/0/12.md @@ -0,0 +1,17 @@ +--- +type: docs +title: "0-12 - Unknown exception" +linkTitle: "0-12 - Unknown exception" +weight: 12 +--- +Unknown exception, usually API usage or configuration exception + +### possible reason + +Such as: transcoding exception, unsupported encryption and decryption methods, etc. + +### Troubleshooting and resolution steps + +The business code line can be located according to the stack information. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/0/13.md b/content/en/docs3-v2/java-sdk/faq/0/13.md new file mode 100644 index 000000000000..db3aea50ed9b --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/0/13.md @@ -0,0 +1,17 @@ +--- +type: docs +title: "0-13 - An exception occurred in the metrics collector" +linkTitle: "0-13 - An exception occurred in the metrics collector" +weight: 13 +--- + + +### possible reason + +An error occurred during the push process of the indicator data, the pushed server could not be connected or some configuration errors were made. Prometheus is currently supported. + +### Troubleshooting and resolution steps + +Please refer to the configuration item reference manual[configuration item reference manual](/en/docs3-v2/java-sdk/reference-manual/config/properties/#metrics). + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/0/14.md b/content/en/docs3-v2/java-sdk/faq/0/14.md new file mode 100644 index 000000000000..7c6534b15f4c --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/0/14.md @@ -0,0 +1,19 @@ +--- +type: docs +title: "0-14 - Monitoring exception" +linkTitle: "0-14 - Monitoring exception" +weight: 14 +--- +It is used to count the number of RPC calls and the call time. The extension interface is MonitorFactory, and the corresponding implementation class is DubboMonitorFactroy. + + +### possible reason + +Users can implement the MonitorFactory extension interface of this layer to implement custom monitoring statistics strategies. +In the implementation class of the custom monitoring statistics strategy, an exception occurred during business runtime. + +### Troubleshooting and resolution steps + +Check the business class of `org.apache.dubbo.monitor.MonitorFactory` interface, there may be code logic errors in the implementation method. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/0/15.md b/content/en/docs3-v2/java-sdk/faq/0/15.md new file mode 100644 index 000000000000..bd9588dc224d --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/0/15.md @@ -0,0 +1,19 @@ +--- +type: docs +title: "0-15 - An exception occurred while loading the extension class" +linkTitle: "0-15 - An exception occurred while loading the extension class" +weight: 15 +--- + + +### possible reason + +1. The `clazz` class does not implement the interface class of the current extension point. +2. The extension may be an interface or not exist. + +### Troubleshooting and resolution steps + +1. Check the extension class declaration, and there is no matching extension implementation class. +2. The extension implementation class needs to implement the extension point interface class and method. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/0/16.md b/content/en/docs3-v2/java-sdk/faq/0/16.md new file mode 100644 index 000000000000..06885d4b1e8b --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/0/16.md @@ -0,0 +1,17 @@ +--- +type: docs +title: "0-16 - No actuators available" +linkTitle: "0-16 - No actuators available" +weight: 16 +--- + + +### possible reason + +The internal executor is not available and null is returned at this time. + +### Troubleshooting and resolution steps + +No need to intervene, dubbo will execute the `createExecutorIfAbsent` method internally to construct a new executor. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/0/17.md b/content/en/docs3-v2/java-sdk/faq/0/17.md new file mode 100644 index 000000000000..4bca06c6465f --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/0/17.md @@ -0,0 +1,17 @@ +--- +type: docs +title: "0-17 - Actuator encountered an unknown exception while shutting down" +linkTitle: "0-17 - An unknown exception occurred while the actuator was shutting down" +weight: 17 +--- + + +### possible reason + +A custom executor may be used, and an exception was generated when writing the destruction method. + +### Troubleshooting and resolution steps + +Check whether `org.apache.dubbo.common.threadpool.manager.ExecutorRepository` is custom implemented, and check the custom `shutdown` method. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/0/18.md b/content/en/docs3-v2/java-sdk/faq/0/18.md new file mode 100644 index 000000000000..321aedafeadd --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/0/18.md @@ -0,0 +1,17 @@ +--- +type: docs +title: "0-18 - thread pool executor is misused" +linkTitle: "0-18 - thread pool executor is misused" +weight: 18 +--- + + +### possible reason + +The number of threads is customized, and an unknown exception occurs inside the system. + +### Troubleshooting and resolution steps + +You can use some third-party tools or `jstack [PID] > jstack.log` to analyze the stack information and locate it. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/0/19.md b/content/en/docs3-v2/java-sdk/faq/0/19.md new file mode 100644 index 000000000000..4f08a9ffe01e --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/0/19.md @@ -0,0 +1,17 @@ +--- +type: docs +title: "0-19 - An exception occurred while processing the task" +linkTitle: "0-19 - An exception occurred while processing the task" +weight: 19 +--- + + +### possible reason + +The custom business class processing logic is improper. + +### Troubleshooting and resolution steps + +You can use some third-party tools or `jstack [PID] > jstack.log` to analyze the stack information and locate it. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/0/2.md b/content/en/docs3-v2/java-sdk/faq/0/2.md new file mode 100644 index 000000000000..bba3159fd3f6 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/0/2.md @@ -0,0 +1,14 @@ +--- +type: docs +title: "0-2 - Illegal property value" +linkTitle: "0-2 - Illegal attribute value" +weight: 2 +--- + +### possible reason +This hint means that the value configured by the user does not match the data type required by the attribute itself. For example, the `dubbo.comsumer.threads` attribute can only accept numeric attributes, but the value entered by the user is mixed with letters. + +### Troubleshooting and resolution steps +According to the [Configuration Item Reference Manual](../../../reference-manual/config/properties), find the wrong configuration item, check the type specified by the item, and check whether there is a type inconsistency. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/0/20.md b/content/en/docs3-v2/java-sdk/faq/0/20.md new file mode 100644 index 000000000000..f1effdc0d242 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/0/20.md @@ -0,0 +1,20 @@ +--- +type: docs +title: "0-20 - An exception occurred while storing stack information" +linkTitle: "0-20 - An exception occurred while storing stack information" +weight: 20 +--- + + +### possible reason + +1. The JVM has set the parameter `-XX:+DisableAttachMechanism` +2. Set a stack dump path that does not exist in the system. If it does not exist, the system will try to create it. A `SecurityException` occurs during creation. + May not have permission. + +### Troubleshooting and resolution steps + +1. Check whether the JVM has set the above parameters. +2. Check whether the account currently starting the service has permission to create folders. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/0/21.md b/content/en/docs3-v2/java-sdk/faq/0/21.md new file mode 100644 index 000000000000..68dd1a1d933a --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/0/21.md @@ -0,0 +1,16 @@ +--- +type: docs +title: "0-21 - Too many instances built" +linkTitle: "0-21 - Too many instances built" +weight: 21 +--- + +### possible reason + +Generally, it means that `org.apache.dubbo.common.timer.HashedWheelTimer` creates too many instances. + +### Troubleshooting and resolution steps + +It does not affect the construction of the instance, and there may be a risk of memory leaks. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/0/22.md b/content/en/docs3-v2/java-sdk/faq/0/22.md new file mode 100644 index 000000000000..4898239ce63f --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/0/22.md @@ -0,0 +1,23 @@ +--- +type: docs +title: "0-22 - I/O stream exception" +linkTitle: "0-22 - I/O stream exception" +weight: 22 +--- + + +### possible reason + +1. Read a local file that is no longer available. +2. Attempt to read/write the file but do not have permission. +3. An attempt was made to write a file but disk space is no longer available. + +### Troubleshooting and resolution steps + +1. Check if the local file exists. +2. Check the file permissions. +3. Check the disk space. + +You can use some third-party tools or `jstack [PID] > jstack.log` to analyze the stack information and locate it. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/0/23.md b/content/en/docs3-v2/java-sdk/faq/0/23.md new file mode 100644 index 000000000000..e2b0278747ce --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/0/23.md @@ -0,0 +1,21 @@ +--- +type: docs +title: "0-23 - Serialized data conversion exception" +linkTitle: "0-23 - Serialized data conversion exception" +weight: 23 +--- + + +### possible reason + +1. There is a circular reference in the data to be serialized, resulting in a stack overflow. +2. The version of the referenced jar package is low or there is a compatibility problem. + +### Troubleshooting and resolution steps + +1. If using FastJson, remove `SerializerFeature.DisableCircularReferenceDetect` +2. Check or upgrade the version to try. + +You can use some third-party tools or `jstack [PID] > jstack.log` to analyze the stack information and locate it. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/0/24.md b/content/en/docs3-v2/java-sdk/faq/0/24.md new file mode 100644 index 000000000000..822f1cbd3c6e --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/0/24.md @@ -0,0 +1,19 @@ +--- +type: docs +title: "0-24 - Override field value exception" +linkTitle: "0-24 - Override field value exception" +weight: 24 +--- + + +### possible reason + +1. The entity class does not have a setter/getter method. +2. There may be nested attributes. + +### Troubleshooting and resolution steps + +1. Check the entity class and set the setter/getter method. +2. According to the stack information, check whether nested annotations are used. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/0/25.md b/content/en/docs3-v2/java-sdk/faq/0/25.md new file mode 100644 index 000000000000..e7dea0fce7ec --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/0/25.md @@ -0,0 +1,18 @@ +--- +type: docs +title: "0-25 - Error loading map" +linkTitle: "0-25 - Error loading map" +weight: 25 +--- + + +### possible reason + +Insufficient file access rights + +### Troubleshooting and resolution steps + +Check file permissions. +You can use some third-party tools or `jstack [PID] > jstack.log` to analyze the stack information and locate it. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/0/26.md b/content/en/docs3-v2/java-sdk/faq/0/26.md new file mode 100644 index 000000000000..e8e10aacb7f8 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/0/26.md @@ -0,0 +1,16 @@ +--- +type: docs +title: "0-26 - Warning message when metadata is published to the service" +linkTitle: "0-26 - Warning message when metadata publishing service" +weight: 26 +--- + +### possible reason + +When the metadata stores the mapping relationship between the interface and the application, the reminder message displayed. + +### Troubleshooting and resolution steps + +Generally, it can be analyzed according to the stack information, or it can not be processed. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/0/27.md b/content/en/docs3-v2/java-sdk/faq/0/27.md new file mode 100644 index 000000000000..9fbe91fdc65e --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/0/27.md @@ -0,0 +1,16 @@ +--- +type: docs +title: "0-27 - Thread pool isolation configuration exception" +linkTitle: "0-27 - Thread pool isolation configuration exception" +weight: 27 +--- + +### possible reason + +The thread pool isolation capability of the application is not enabled, but the isolated thread pool information is configured in `ServiceConfig`. + +### Troubleshooting and resolution steps + +Configure and enable the thread pool isolation capability of the application: `dubbo.application.executor-management-mode=isolation` + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/0/3.md b/content/en/docs3-v2/java-sdk/faq/0/3.md new file mode 100644 index 000000000000..5aca400e828c --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/0/3.md @@ -0,0 +1,31 @@ +--- +type: docs +title: "0-3 - Unable to access cache path" +linkTitle: "0-3 - Unable to access cache path" +weight: 3 +--- + +Other modules reuse the file-based caching mechanism of the Common layer (currently the metadata module), and the file caching mechanism of the Common layer cannot access the directory it specifies. + +``` +2022-08-29 00:35:00,189 ERROR [org.apache.dubbo.common.cache.FileCacheStoreFactory:?] - [DUBBO] Cache store path can't be created: , dubbo version: , current host: 10.0.1.1 , error code: 0-3. This may be caused by inaccessible of cache path, go to https://dubbo.apache.org/faq/0/3 to find instructions. +java.nio.file.FileAlreadyExistsException: [Path] +at java.base/sun.nio.fs.WindowsException.translateToIOException(WindowsException.java:87) +at java.base/sun.nio.fs.WindowsException.rethrowAsIOException(WindowsException.java:103) +at java.base/sun.nio.fs.WindowsException.rethrowAsIOException(WindowsException.java:108) +at java.base/sun.nio.fs.WindowsFileSystemProvider.createDirectory(WindowsFileSystemProvider.java:521) +at java.base/java.nio.file.Files.createDirectory(Files.java:700) +at java.base/java.nio.file.Files.createAndCheckIsDirectory(Files.java:807) +at java.base/java.nio.file.Files.createDirectories(Files.java:753) +at org.apache.dubbo.common.cache.FileCacheStoreFactory.getInstance(FileCacheStoreFactory.java:90) +... +``` + +### possible reason +1. Multiple Dubbo processes (or other Java processes) use the same cache file. +2. Due to the file system permission problem of the directory where the cache file is located, reading and writing fails. + +### Troubleshooting and resolution steps +1. According to the actual exception shown below, find the directory that cannot be accessed, and determine its file access permission. +2. Determine whether other Dubbo instances are accessing this path. +3. Try to configure **Java System Property (Java system properties configured with -D)** `dubbo.meta.cache.filePath` and `dubbo.mapping.cache.filePath`, specify it as a current user can completely under the control directory. \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/0/4.md b/content/en/docs3-v2/java-sdk/faq/0/4.md new file mode 100644 index 000000000000..27c5afa17d72 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/0/4.md @@ -0,0 +1,48 @@ +--- +type: docs +title: "0-4 - cache entry exceeded" +linkTitle: "0-4 - Cache entry limit exceeded" +weight: 4 +--- +Other modules reuse the common layer's file-based caching mechanism (currently the metadata module), and the common layer's file caching mechanism "sees" that the entry limit is exceeded. + + +### possible reason +User improperly configured **Java System Property** (Java system property configured with -D) `dubbo.mapping.cache.entrySize` or `dubbo.meta.cache.entrySize` + +**Defaults** + + + + + + + + + + + + +
dubbo.mapping.cache.entrySizedubbo.meta.cache.entrySize
10000100
+ +### Troubleshooting and resolution steps +1. Try reconfiguring the above **Java System Property (Java System Property configured with -D)**. +2. If these **System Property** are not configured, please go to [GitHub Issue Tracker](https://github.com/apache/dubbo/issues) to issue an Issue. \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/0/5.md b/content/en/docs3-v2/java-sdk/faq/0/5.md new file mode 100644 index 000000000000..51f058e8838b --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/0/5.md @@ -0,0 +1,23 @@ +--- +type: docs +title: "0-5 - Cache file size exceeded" +linkTitle: "0-5 - Cache file size exceeded" +weight: 5 +--- +Other modules reuse the file-based caching mechanism of the Common layer (currently the metadata module), and the file caching mechanism of the Common layer "discovers" that the file size exceeds the limit. + + +### possible reason +1. The user has unreasonably configured the Java System Property (the Java system property configured with -D) `dubbo.mapping.cache.maxFileSize` or `dubbo.meta.cache.maxFileSize` +2. The cache file is corrupted due to file system or disk errors. + + +> `dubbo.mapping.cache.maxFileSize` and `dubbo.meta.cache.maxFileSize` do not show default values, +The default value of the maximum file size found according to the logic of `org.apache.dubbo.common.cache.FileCacheStore.LimitedLengthBufferedWriter` is: `Long.MAX_VALUE` ( 263-1 ). + + + +### Troubleshooting and resolution steps +1. Try reconfiguring the above **Java System Property (Java System Property configured with -D)**. +2. Delete the cache folder and restart **Provider** and **Consumer** (the location of the cache folder is usually `~/.dubbo`. If `dubbo.meta.cache.filePath` and `dubbo.mapping` are configured .cache.filePath` is that path). +3. If these **System Property** are not configured, please go to [GitHub Issue Tracker](https://github.com/apache/dubbo/issues) to issue an Issue. \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/0/6.md b/content/en/docs3-v2/java-sdk/faq/0/6.md new file mode 100644 index 000000000000..756c803af489 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/0/6.md @@ -0,0 +1,18 @@ +--- +type: docs +title: "0-6 - Thread interruption exception" +linkTitle: "0-6 - Thread interruption exception" +weight: 6 +--- + + +### possible reason + +When a running thread is in `wait, sleep, join`, it is explicitly called `interrupt()` + +### Troubleshooting and resolution steps + +After a normal running thread calls the `interrupt()` method, the interrupt status of the current thread will be set to true, but the execution of the thread will not be affected. +You can operate according to the actual situation or check whether the business code is used incorrectly. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/0/7.md b/content/en/docs3-v2/java-sdk/faq/0/7.md new file mode 100644 index 000000000000..0aa31d79028d --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/0/7.md @@ -0,0 +1,19 @@ +--- +type: docs +title: "0-7 - Reflection class not found" +linkTitle: "0-7 - Reflection class not found" +weight: 7 +--- + + +### possible reason + +1. Generally, when `Class.forName(className)` executes this method, the current class of `className` cannot be found. +2. The business code shows that the current `className` class is excluded, so it is not found when loading. + +### Troubleshooting and resolution steps + +1. Check whether `className` exists in `Class.forName(className)`. +2. Check the business code to see whether some classes or packages have been excluded by using the configuration or scanning annotation `exclude`. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/0/8.md b/content/en/docs3-v2/java-sdk/faq/0/8.md new file mode 100644 index 000000000000..c4e25115ac37 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/0/8.md @@ -0,0 +1,17 @@ +--- +type: docs +title: "0-8 - reflection failed" +linkTitle: "0-8 - reflection failed" +weight: 8 +--- + + +### possible reason + +When a method is called by reflection, the correct parameter type value is not set for the current method, that is, the parameter type does not match. + +### Troubleshooting and resolution steps + +Check for matching type values that are not set correctly. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/0/9.md b/content/en/docs3-v2/java-sdk/faq/0/9.md new file mode 100644 index 000000000000..a90e92d07877 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/0/9.md @@ -0,0 +1,17 @@ +--- +type: docs +title: "0-9 - Failed to notify event" +linkTitle: "0-9 - Failed to notify event" +weight: 9 +--- + + +### possible reason + +A custom listener that generated a runtime exception during processing. + +### Troubleshooting and resolution steps + +Check the business class that implements the `org.apache.dubbo.rpc.ExporterListener` interface. There may be code logic errors in the implementation method. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/0/_index.md b/content/en/docs3-v2/java-sdk/faq/0/_index.md new file mode 100644 index 000000000000..11534c905ef9 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/0/_index.md @@ -0,0 +1,8 @@ +--- +type: docs +title: "0 - Common" +linkTitle: "0 - Common" +weight: 1 +--- + +This is mainly used to indicate errors that occur on components that are common to each layer. \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/1/1.md b/content/en/docs3-v2/java-sdk/faq/1/1.md new file mode 100644 index 000000000000..032442cc1333 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/1/1.md @@ -0,0 +1,17 @@ +--- +type: docs +title: "1-1 - Address Illegal" +linkTitle: "1-1 - Illegal address" +weight: 1 +--- +Service version or grouping mismatch. + +### possible reason +1. The `service.group` configured on the Provider side does not match the `reference.group` configured on the Consumer side (that is, the configuration of the service group). +2. The `service.version` configured on the Provider side does not match the `reference.version` configured on the Consumer side (that is, the configuration of the service version). + +### Troubleshooting and resolution steps +1. Make sure that the service group configurations on the Provider and Consumer side correspond. +2. Make sure that the service version configurations on the Provider and Consumer side correspond. + +> See also the [Configuration Items Reference Manual](../../../reference-manual/config/properties) \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/1/10.md b/content/en/docs3-v2/java-sdk/faq/1/10.md new file mode 100644 index 000000000000..7090be8bcb13 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/1/10.md @@ -0,0 +1,16 @@ +--- +type: docs +title: "1-10 - Failed to read and write registry service cache" +linkTitle: "1-10 - Failed to read and write registry service cache" +weight: 10 +--- + +### possible reason +1. Multiple Dubbo processes use the same cache file. +2. In the case of multiple registries, multiple registries are specified to use the same file storage. + +### Troubleshooting and resolution steps +This error often occurs with errors 1-9. Check whether multiple Dubbo processes use the same cache file or specify multiple registries to use the same cache file. + +> see also +[Reference Manual for Registry Configuration Items](https://dubbo.apache.org/zh/docs3-v2/java-sdk/reference-manual/config/properties/#registry) \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/1/11.md b/content/en/docs3-v2/java-sdk/faq/1/11.md new file mode 100644 index 000000000000..f6e842d8b482 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/1/11.md @@ -0,0 +1,14 @@ +--- +type: docs +title: "1-11 - Registration service instance creation failed" +linkTitle: "1-11 - Registration service instance creation failed" +weight: 11 +--- + +### possible reason +It may be caused by Registry's SPI/IOC configuration error. +### Troubleshooting and resolution steps +This error is an internal error of Dubbo. If you encounter it, you can create an Issue on github and provide the error information and steps to reproduce it. We will help you solve the problem. + +> see also +[Dubbo Community](https://github.com/apache/dubbo) \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/1/12.md b/content/en/docs3-v2/java-sdk/faq/1/12.md new file mode 100644 index 000000000000..12df41645f16 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/1/12.md @@ -0,0 +1,15 @@ +--- +type: docs +title: "1-12 - Instances of \"Registry Service\" have been destroyed" +linkTitle: "1-12 - Instances of \"Registration Service\" have been destroyed" +weight: 12 +--- + +### possible reason +During the graceful shutdown of Dubbo, unregister by calling `destroyAll` of `AbstractRegistryFactory`. + +During the process of destroying the `unexport` of `Registryprotocol`, the `getRegistry` of `AbstractRegistryFactory` will be used to try to obtain the registry that has been destroyed, which leads to the destruction of all instances of the "registry service". + +### Troubleshooting and resolution steps +> see also +[Configuration item reference manual](../../../reference-manual/config/properties) \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/1/13.md b/content/en/docs3-v2/java-sdk/faq/1/13.md new file mode 100644 index 000000000000..d80814ca2f9a --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/1/13.md @@ -0,0 +1,14 @@ +--- +type: docs +title: "1-13 - Failed to execute task retry" +linkTitle: "1-13 - Failed to execute retry task" +weight: 13 +--- + +### possible reason +1. The registry is offline. + +### Troubleshooting and resolution steps + +1. Check if the registry is working properly. +2. Check whether the server where the registration center is located and its network are working normally. \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/1/14.md b/content/en/docs3-v2/java-sdk/faq/1/14.md new file mode 100644 index 000000000000..1df9ec73ea65 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/1/14.md @@ -0,0 +1,15 @@ +--- +type: docs +title: "1-14 - Dynamic configuration recognition failed" +linkTitle: "1-14 - Dynamic configuration recognition failed" +weight: 14 +--- + +### possible reason +When using the service management function of dubbo admin for dynamic configuration, if the content or format of the configuration file is incorrect, the content of the dynamic configuration cannot be parsed, resulting in 1-14 errors. +### Troubleshooting and resolution steps +Please check whether the content or format of the dynamic configuration file is correct. + + +### See also +> [Configuration Reference Manual](../../../reference-manual/config/properties) \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/1/15.md b/content/en/docs3-v2/java-sdk/faq/1/15.md new file mode 100644 index 000000000000..d32a297ebf7e --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/1/15.md @@ -0,0 +1,15 @@ +--- +type: docs +title: "1-15 - Failed to destroy service" +linkTitle: "1-15 - Failed to destroy service" +weight: 15 +--- + +### possible reason +Throwing an exception while destroying all invokers in the RegistryDirectory may trigger errors 1-15. + +### Troubleshooting and resolution steps +This error is an internal error of Dubbo. If you encounter it, you can create an Issue on github and provide the error information and steps to reproduce it. We will help you solve the problem. + + +> See also [Dubbo Community](https://github.com/apache/dubbo) \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/1/16.md b/content/en/docs3-v2/java-sdk/faq/1/16.md new file mode 100644 index 000000000000..331dd293db9c --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/1/16.md @@ -0,0 +1,19 @@ +--- +type: docs +title: "1-16 - There are unsupported categories" +linkTitle: "1-16 - There are unsupported categories" +weight: 16 +--- + +## possible reason +When the registration center changes, the corresponding listener will be notified. If the category is illegal during notify, 1-16 errors will be generated. + + +## Troubleshooting and resolution steps +This error is an internal error of Dubbo. If you encounter it, you can create an Issue on github and provide the error information and steps to reproduce it. We will help you solve the problem. + + +## Dubbo Community +[github](https://github.com/apache/dubbo) + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/1/17.md b/content/en/docs3-v2/java-sdk/faq/1/17.md new file mode 100644 index 000000000000..dde96105485f --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/1/17.md @@ -0,0 +1,18 @@ +--- +type: docs +title: "1-17 - Metadata Server Failure" +linkTitle: "1-17 - Metadata Server failure" +weight: 17 +--- + +## possible reason +It may be that there is a problem with the parameter configuration of metadata, especially `metadataServiceProtocol` and `metadataServicePort`. + +## Troubleshooting and resolution steps +1. Check whether it occurs at the same time as 1-18 error, if it occurs at the same time, first try to solve 1-18 +2. Check whether the `metadataServicePort` port number conflicts. If the ports configured by Provider and Consumer are in conflict at the same time, a 1-17 error will be generated. + +## see also +[Configuration item reference manual](../../../reference-manual/config/properties) + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/1/18.md b/content/en/docs3-v2/java-sdk/faq/1/18.md new file mode 100644 index 000000000000..8283ad8787da --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/1/18.md @@ -0,0 +1,18 @@ +--- +type: docs +title: "1-18 - metadata service port not provided" +linkTitle: "1-18 - metadata service port not provided" +weight: 18 +--- + +## possible reason +It may be that `metadataType` is in local mode, and `metadataServicePort` is configured incorrectly. + +## Troubleshooting and resolution steps +1. Check the `metadataType` attribute value on the Provider side. +2. Check whether the configuration of `metadataServicePort` on the Provider side is correct, and pay special attention to whether there is any conflict with other application ports. + +## see also +[Configuration item reference manual](../../../reference-manual/config/properties) + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/1/19.md b/content/en/docs3-v2/java-sdk/faq/1/19.md new file mode 100644 index 000000000000..06f4abd3ce3a --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/1/19.md @@ -0,0 +1,18 @@ +--- +type: docs +title: "1-19 - K8S monitoring exception" +linkTitle: "1-19 - K8S monitoring exception" +weight: 19 +--- + +## possible reason + +1. K8S custom resource type, the configuration has been modified or removed by the container. +2. The K8S container is disconnected from the service. + +## Troubleshooting and resolution steps + +1. Check whether the custom resource type is correctly configured. For syntax, please refer to the official documentation of K8S. +2. Check whether the network is normal or the port mapping is correct. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/1/20.md b/content/en/docs3-v2/java-sdk/faq/1/20.md new file mode 100644 index 000000000000..8ea48e67aba1 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/1/20.md @@ -0,0 +1,16 @@ +--- +type: docs +title: "1-20 - K8S Pod does not exist" +linkTitle: "1-20 - K8S Pod does not exist" +weight: 20 +--- + +## possible reason + +Pods may not exist or have been removed by containers. + +## Troubleshooting and resolution steps + +You can use some third-party tools or `jstack [PID] > jstack.log` to analyze the stack information and locate it. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/1/21.md b/content/en/docs3-v2/java-sdk/faq/1/21.md new file mode 100644 index 000000000000..326b0c0c0e73 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/1/21.md @@ -0,0 +1,17 @@ +--- +type: docs +title: "1-21 - K8S No Service Available" +linkTitle: "1-21 - No service available for K8S" +weight: 21 +--- + +## possible reason + +1. The current service is not loaded correctly. +2. The configured Pod does not exist in the current instance service. + +## Troubleshooting and resolution steps + +You can use some third-party tools or `jstack [PID] > jstack.log` to analyze the stack information and locate it. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/1/22.md b/content/en/docs3-v2/java-sdk/faq/1/22.md new file mode 100644 index 000000000000..d06704962cf0 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/1/22.md @@ -0,0 +1,16 @@ +--- +type: docs +title: "1-22 - K8S configuration address error" +linkTitle: "1-22 - K8S configuration address error" +weight: 22 +--- + +## possible reason + +The K8S url is configured incorrectly and cannot be accessed normally. + +## Troubleshooting and resolution steps + +Check the K8S url configuration information to ensure that the port mapping can also be accessed normally. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/1/23.md b/content/en/docs3-v2/java-sdk/faq/1/23.md new file mode 100644 index 000000000000..78e2f336a1c2 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/1/23.md @@ -0,0 +1,18 @@ +--- +type: docs +title: "1-23 - Unable to download files via url" +linkTitle: "1-23 - Unable to download files via url" +weight: 23 +--- + +## possible reason + +1. The url mapping file does not exist. +2. The URL cannot be connected. + +## Troubleshooting and resolution steps + +1. Check whether the url mapping file exists. +2. Whether it can be accessed normally through a browser or other tools. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/1/24.md b/content/en/docs3-v2/java-sdk/faq/1/24.md new file mode 100644 index 000000000000..38750c732e3f --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/1/24.md @@ -0,0 +1,20 @@ +--- +type: docs +title: "1-24 - ZK startup exception" +linkTitle: "1-24 - ZK startup exception" +weight: 24 +--- + +## possible reason + +1. There is an incompatibility between the zk server version and the client version, and the connection cannot be made. +2. The zk service is not started normally or the firewall cannot provide external services. + +## Troubleshooting and resolution steps + +1. Confirm that the client version is consistent with the server version. +2. zk can start normally or provide normal external services. + +You can use some third-party tools or `jstack [PID] > jstack.log` to analyze the stack information and locate it. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/1/25.md b/content/en/docs3-v2/java-sdk/faq/1/25.md new file mode 100644 index 000000000000..fa193201d92a --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/1/25.md @@ -0,0 +1,17 @@ +--- +type: docs +title: "1-25 - ZK destruction exception" +linkTitle: "1-25 - ZK destruction exception" +weight: 25 +--- + +## possible reason + +The current instance has been destroyed. +The network may be disconnected. + +## Troubleshooting and resolution steps + +You can use some third-party tools or `jstack [PID] > jstack.log` to analyze the stack information and locate it. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/1/26.md b/content/en/docs3-v2/java-sdk/faq/1/26.md new file mode 100644 index 000000000000..b04c8a65f0e1 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/1/26.md @@ -0,0 +1,16 @@ +--- +type: docs +title: "1-26 - xDS certificate generation failed" +linkTitle: "1-26 - xDS certificate generation failed" +weight: 26 +--- + +## possible reason + +The system may not support algorithms `secp256r1` and `RSA` to generate certificates. + +## Troubleshooting and resolution steps + +Check if the operating system supports `secp256r1` and `RSA` algorithms. Need to download the dll file or lib for + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/1/27.md b/content/en/docs3-v2/java-sdk/faq/1/27.md new file mode 100644 index 000000000000..52a5eb457c3b --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/1/27.md @@ -0,0 +1,16 @@ +--- +type: docs +title: "1-27 - K8S monitoring exception" +linkTitle: "1-27 - K8S monitoring exception" +weight: 27 +--- + +## possible reason + +The system may not support algorithms `secp256r1` and `RSA` to generate certificates. + +## Troubleshooting and resolution steps + +Check if the operating system supports `secp256r1` and `RSA` algorithms. Need to download the dll file or lib for + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/1/28.md b/content/en/docs3-v2/java-sdk/faq/1/28.md new file mode 100644 index 000000000000..614fad229e88 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/1/28.md @@ -0,0 +1,16 @@ +--- +type: docs +title: "1-28 - xDS Stub Error" +linkTitle: "1-28 - xDS stub error" +weight: 28 +--- + +## possible reason + +The current pod may be down. + +## Troubleshooting and resolution steps + +You can use some third-party tools or `jstack [PID] > jstack.log` to analyze the stack information and locate it. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/1/29.md b/content/en/docs3-v2/java-sdk/faq/1/29.md new file mode 100644 index 000000000000..2af97010547c --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/1/29.md @@ -0,0 +1,17 @@ +--- +type: docs +title: "1-29 - xDS failed to read file" +linkTitle: "1-29 - xDS failed to read file" +weight: 29 +--- + +## possible reason + +The network is disconnected or the target file is corrupted at this time. + +## Troubleshooting and resolution steps + +1. Whether the network is normal. +2. You can use some third-party tools or `jstack [PID] > jstack.log` to analyze the stack information and locate it. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/1/3.md b/content/en/docs3-v2/java-sdk/faq/1/3.md new file mode 100644 index 000000000000..64ce7e3a0111 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/1/3.md @@ -0,0 +1,13 @@ +--- +type: docs +title: "1-3 - URL destruction failed" +linkTitle: "1-3 - URL destruction failed" +weight: 3 +--- + +### possible reason +When `FrameworkExecutorRepository` is destroyed, calling `CacheableFailbackRegistry.evictURLCache` will cause the destruction to fail and generate an error code. + +### Troubleshooting and resolution steps + +> See also the [Configuration Items Reference Manual](../../../reference-manual/config/properties) \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/1/30.md b/content/en/docs3-v2/java-sdk/faq/1/30.md new file mode 100644 index 000000000000..692ecf456227 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/1/30.md @@ -0,0 +1,20 @@ +--- +type: docs +title: "1-30 - xDS request failed" +linkTitle: "1-30 - xDS request failed" +weight: 30 +--- + +## possible reason + +1. Versions may be inconsistent or incompatible. +2. Timeout while reading data. +3. There is a problem with parameter configuration. + +## Troubleshooting and resolution steps + +1. It can be adapted according to the introduction of the third-party official website. +2. Check whether the timeout setting is too short or there is a problem on the server. +3. Check whether the port mapping relationship is correct. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/1/31.md b/content/en/docs3-v2/java-sdk/faq/1/31.md new file mode 100644 index 000000000000..06005200202a --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/1/31.md @@ -0,0 +1,18 @@ +--- +type: docs +title: "1-31 - xDS Response Failed" +linkTitle: "1-31 - xDS Response Failed" +weight: 31 +--- + +## possible reason + +1. The client service has disconnected from the server. +2. The server is unavailable or offline. + +## Troubleshooting and resolution steps + +1. Check whether the server is offline or the network of the client is disconnected. +2. Check whether the service on the server side is normal, and the interface request can be made through the network. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/1/32.md b/content/en/docs3-v2/java-sdk/faq/1/32.md new file mode 100644 index 000000000000..1c60d929d95f --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/1/32.md @@ -0,0 +1,20 @@ +--- +type: docs +title: "1-32 - xDS Channel initialization failed" +linkTitle: "1-32 - xDS Channel initialization failed" +weight: 32 +--- + +## possible reason + +1. Versions may be inconsistent or incompatible. +2. Timeout while reading data. +3. There is a problem with parameter configuration. + +## Troubleshooting and resolution steps + +1. It can be adapted according to the introduction of the third-party official website. +2. Check whether the timeout setting is too short or there is a problem on the server. +3. Check whether the port mapping relationship is correct. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/1/33.md b/content/en/docs3-v2/java-sdk/faq/1/33.md new file mode 100644 index 000000000000..e0912e0b1ad1 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/1/33.md @@ -0,0 +1,18 @@ +--- +type: docs +title: "1-33 - xDS service discovery initialization failed" +linkTitle: "1-33 - xDS service discovery initialization failed" +weight: 33 +--- + +## possible reason + +1. The address configuration of the registration center in xDS mode is wrong. +2. The firewall and third-party protection software make it impossible to provide external connections. + +## Troubleshooting and resolution steps + +1. Check whether the xDS configuration is correct and whether the Istio status is normal. +2. Check the firewall configuration or use the `ping` command of cmd for basic detection. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/1/34.md b/content/en/docs3-v2/java-sdk/faq/1/34.md new file mode 100644 index 000000000000..e2bdc26393d4 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/1/34.md @@ -0,0 +1,16 @@ +--- +type: docs +title: "1-34 - Error parsing xDS" +linkTitle: "1-34 - Error parsing xDS" +weight: 34 +--- + +## possible reason + +There is an error in the xDS protocol content. + +## Troubleshooting and resolution steps + +The cause can be located according to the Endpoints List printed by the stack. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/1/35.md b/content/en/docs3-v2/java-sdk/faq/1/35.md new file mode 100644 index 000000000000..47bcd31cb50f --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/1/35.md @@ -0,0 +1,18 @@ +--- +type: docs +title: "1-35 - ZK Anomaly" +linkTitle: "1-35 - ZK Anomaly" +weight: 35 +--- + +## possible reason + +1. ZK cannot connect or the connection times out. +2. The ZNode already exists at the time of creation. + +## Troubleshooting and resolution steps + +1. Check whether ZK configuration IP and port number are correct. Connection testing can be done using the third-party tool ZooInspector +2. According to the stack reminder ZNode information, judge whether the current node can be cleaned up. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/1/36.md b/content/en/docs3-v2/java-sdk/faq/1/36.md new file mode 100644 index 000000000000..ac47edbc9d2d --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/1/36.md @@ -0,0 +1,15 @@ +--- +type: docs +title: "1-36 - Unknown exception" +linkTitle: "1-36 - Unknown exception" +weight: 36 +--- + +## possible reason + + +## Troubleshooting and resolution steps + +You can use some third-party tools or `jstack [PID] > jstack.log` to analyze the stack information and locate it. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/1/37.md b/content/en/docs3-v2/java-sdk/faq/1/37.md new file mode 100644 index 000000000000..7da9842b7e13 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/1/37.md @@ -0,0 +1,16 @@ +--- +type: docs +title: "1-37 - Nacos Anomaly" +linkTitle: "1-37 - Nacos Anomaly" +weight: 37 +--- + +## possible reason + +Nacos configuration information is not configured correctly. + +## Troubleshooting and resolution steps + +Check whether the ip and port number configured for Nacos are correct. If the security authentication of Nacos is enabled, check whether the user name and password are configured correctly. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/1/38.md b/content/en/docs3-v2/java-sdk/faq/1/38.md new file mode 100644 index 000000000000..b0c65e57f678 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/1/38.md @@ -0,0 +1,17 @@ +--- +type: docs +title: "1-38 - Socket connection exception" +linkTitle: "1-38 - Socket connection exception" +weight: 38 +--- + +## possible reason + +1. Connection refused. +2. The connection has been closed. + +## Troubleshooting and resolution steps + +You can use some third-party tools or `jstack [PID] > jstack.log` to analyze the stack information and locate it. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/1/39.md b/content/en/docs3-v2/java-sdk/faq/1/39.md new file mode 100644 index 000000000000..38a26abf8c99 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/1/39.md @@ -0,0 +1,18 @@ +--- +type: docs +title: "1-39 - Failed to fetch metadata" +linkTitle: "1-39 - Failed to get metadata" +weight: 39 +--- + +## possible reason + +1. Metadata Center has been disconnected from App Service. +2. The data in the metadata center may have been modified. + +## Troubleshooting and resolution steps + +1. Check whether the network communication is normal, you can use some simple cmd commands to detect, such as `ping` and so on. +2. Connect and view content through third-party tools. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/1/4.md b/content/en/docs3-v2/java-sdk/faq/1/4.md new file mode 100644 index 000000000000..69293aa3e23e --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/1/4.md @@ -0,0 +1,18 @@ +--- +type: docs +title: "1-4 - Empty address" +linkTitle: "1-4 - Empty address" +weight: 4 +--- + +### possible reason +1. Errors 1-4 in registry.integration.RegistryDirectory are caused by the null invokerUrls in the refreshInvoker process, which can be ignored. +2. The 1-4 errors in registry.support.CacheableFailbackRegistry may be caused by the mismatch between consumer and provider, and the "null protection" is turned off. + +### Troubleshooting and resolution steps +1. Make sure that the service group configurations on the Provider and Consumer side correspond. +2. Make sure that the service version configurations on the Provider and Consumer side correspond. +3. Check whether `enable-empty-protection` of the registration center is true (the default is true). + +> see also +[Configuration item reference manual](../../../reference-manual/config/properties) \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/1/40.md b/content/en/docs3-v2/java-sdk/faq/1/40.md new file mode 100644 index 000000000000..326d8e644656 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/1/40.md @@ -0,0 +1,18 @@ +--- +type: docs +title: "1-40 - Route waiting too long" +linkTitle: "1-40 - Route waiting too long" +weight: 40 +--- + +## possible reason + +The route calculation time is too long, so the address notification cannot wait for an appropriate time to update the address. + +## Troubleshooting and resolution steps + +1. Check the application QPS, if the QPS is very high, this is the expected log +2. Check the implementation of custom routes, and check whether there are abnormal implementations, such as deadlocks, infinite loops, etc. +3. You can use some third-party tools or `jstack [PID] > jstack.log` to analyze the stack information and locate it. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/1/41.md b/content/en/docs3-v2/java-sdk/faq/1/41.md new file mode 100644 index 000000000000..204cc0e54089 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/1/41.md @@ -0,0 +1,16 @@ +--- +type: docs +title: "1-41 - Istio exceptions" +linkTitle: "1-41 - Istio exception" +weight: 41 +--- + +## possible reason + +Failed to fetch configuration file for istio + +## Troubleshooting and resolution steps + +1. Check whether the application is deployed in the Kubernetes Pod environment, currently does not support VM deployment + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/1/5.md b/content/en/docs3-v2/java-sdk/faq/1/5.md new file mode 100644 index 000000000000..75c16e63dbe4 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/1/5.md @@ -0,0 +1,14 @@ +--- +type: docs +title: "1-5 - URL received without any parameters" +linkTitle: "1-5 - URL received without any parameters" +weight: 5 +--- + +### possible reason +When calling `CacheableFailbackRegistry.toUrlsWithoutEmpty`, if there is a provider in `Collectionproviders` that does not have any parameters, the URL without any parameters will be received. +### Troubleshooting and resolution steps +This error is an internal error of Dubbo. If you encounter it, you can create an Issue on github and provide the error information and steps to reproduce it. We will help you solve the problem. + +> see also +[Dubbo Community](https://github.com/apache/dubbo) \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/1/6.md b/content/en/docs3-v2/java-sdk/faq/1/6.md new file mode 100644 index 000000000000..abfe19ee3bf1 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/1/6.md @@ -0,0 +1,15 @@ +--- +type: docs +title: "1-6 - Error clearing URL cache" +linkTitle: "1-6 - Error clearing URL cache" +weight: 6 +--- + +### possible reason +An error while clearing the url cache in `CacheableFailbackRegistry.RemovalTask` will trigger an error in clearing the URL cache. + +### Troubleshooting and resolution steps +This error is an internal error of Dubbo, if you encounter it, you can create **issues** on github and provide the error information and steps to reproduce, we will help you solve the problem. + +> see also +[Dubbo Community](https://github.com/apache/dubbo) \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/1/7.md b/content/en/docs3-v2/java-sdk/faq/1/7.md new file mode 100644 index 000000000000..92548ea53933 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/1/7.md @@ -0,0 +1,15 @@ +--- +type: docs +title: "1-7 - Notification registration event failed" +linkTitle: "1-7 - Failed to read and write registry service cache" +weight: 7 +--- + +### possible reason + +1. When applied to related platforms based on the xDS protocol, when metadata is updated, consumers need to be notified. If a consumer is offline, the notification will fail and the listener of the corresponding consumer will be removed. + +### Troubleshooting and resolution steps + +> see also +[Registration Center - Configuration Item Reference Manual](https://dubbo.apache.org/zh/docs3-v2/java-sdk/reference-manual/config/properties/#registry) \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/1/8.md b/content/en/docs3-v2/java-sdk/faq/1/8.md new file mode 100644 index 000000000000..b39a38b5b169 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/1/8.md @@ -0,0 +1,18 @@ +--- +type: docs +title: "1-8 - Unregister (unsubscribe) address failed on destroy" +linkTitle: "1-8 - Unregister (unsubscribe) address failed on destroy" +weight: 8 +--- + +### possible reason +1. An error may occur when the consumer logs out or unsubscribes due to the downtime of the registration center. +2. It may be that the corresponding provider has not been released successfully. + +### Troubleshooting and resolution steps +1. Check whether the registration center is running normally. +2. Check whether the provider is released successfully. +3. Check whether the provider’s registry-related parameters such as `registry` `config-center` `metadata-report` are configured correctly. + +> see also +[Configuration item reference manual](../../../reference-manual/config/properties) \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/1/9.md b/content/en/docs3-v2/java-sdk/faq/1/9.md new file mode 100644 index 000000000000..f07b1ac641ce --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/1/9.md @@ -0,0 +1,25 @@ +--- +type: docs +title: "1-9 - Failed to read and write registry service cache" +linkTitle: "1-9 - Failed to read and write registry service cache" +weight: 9 +--- + +### possible reason +1. Multiple Dubbo processes (or other Java processes) use the same cache file. +2. Due to the file system permission problem of the directory where the cache file is located, reading and writing fails. +3. The value of `dubbo.registry.file` is entered incorrectly. +4. Accidentally specify two registries to use the same file store. + +> **Hint:** +If `dubbo.registry.file` is not specified, the registry service cache path defaults to the `~/.dubbo` directory +(where `~` is the user's HOME directory) + +### Troubleshooting and resolution steps +1. Check the value of `dubbo.registry.file` for typos. +2. Check whether other processes use the same cache file. +3. If `dubbo.registry.file` is specified, check its permissions in the file system. +4. Check whether the situation of "two registration centers use the same file storage" occurs, and adjust if it occurs. + +> see also +[Reference Manual for Registry Configuration Items](https://dubbo.apache.org/zh/docs3-v2/java-sdk/reference-manual/config/properties/#registry) \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/1/_index.md b/content/en/docs3-v2/java-sdk/faq/1/_index.md new file mode 100755 index 000000000000..20479b62549a --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/1/_index.md @@ -0,0 +1,8 @@ +--- +type: docs +title: "1 - Registry" +linkTitle: "1 - Registry" +weight: 1 +--- + +This is mainly used to indicate errors that occurred on the registry layer. \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/2/1.md b/content/en/docs3-v2/java-sdk/faq/2/1.md new file mode 100644 index 000000000000..c85708371220 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/2/1.md @@ -0,0 +1,8 @@ +--- +type: docs +title: "2-1 - Routing execution failed" +linkTitle: "2-1 - Execution of routing address selection failed" +weight: 1 +--- + +## Routing address execution failed \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/2/10.md b/content/en/docs3-v2/java-sdk/faq/2/10.md new file mode 100644 index 000000000000..43bf871dae4e --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/2/10.md @@ -0,0 +1,21 @@ +--- +type: docs +title: "2-10 - Failed to call service provider" +linkTitle: "2-10 - Failed to call service provider" +weight: 10 +--- + +## possible reason + +* Dubbo failed to call the service provider and started retrying. +* Dubbo retries to call the service provider and continues to fail. +* Dubbo retries calling the service provider reaches the upper limit. + +## Troubleshooting and resolution steps +1. Check network resources such as time-consuming network connections between consumers and providers. +2. Check whether the corresponding port of the provider can respond normally through telnet or other means. +3. Check that the provider program is functioning properly. + + + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/2/11.md b/content/en/docs3-v2/java-sdk/faq/2/11.md new file mode 100644 index 000000000000..41c709c00afa --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/2/11.md @@ -0,0 +1,18 @@ +--- +type: docs +title: "2-11 - Label Routing Rules Illegal" +linkTitle: "2-11 - Label routing rules are invalid" +weight: 2 +--- + +## possible reason + +* The label routing rule configured by the user is invalid. +* The label routing address configured by the user is invalid. + +## Troubleshooting and resolution steps +1. Refer to the community label routing configuration specification, and check the label routing configuration ["label routing example"](https://dubbo.apache.org/zh/overview/tasks/traffic-management/traffic-condition/). + + + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/2/12.md b/content/en/docs3-v2/java-sdk/faq/2/12.md new file mode 100644 index 000000000000..da6e9076c8da --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/2/12.md @@ -0,0 +1,16 @@ +--- +type: docs +title: "2-12 - Label route acquisition provider application name is empty" +linkTitle: "2-12 - Label route acquisition provider application name is empty" +weight: 2 +--- + +## possible reason + +* The label route obtains the provider application name from the push provider address list and is empty. + +## Troubleshooting and resolution steps +1. This exception is an exception of the Dubbo framework itself. Please file an issue in the community and provide the environment site information and reproduction steps. + + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/2/13.md b/content/en/docs3-v2/java-sdk/faq/2/13.md new file mode 100644 index 000000000000..35a8024a2744 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/2/13.md @@ -0,0 +1,17 @@ +--- +type: docs +title: "2-13 - Failed to receive and load mesh routing rules" +linkTitle: "2-13 - Failed to receive and load mesh routing rules" +weight: 2 +--- + +## possible reason + +* The rules of the mesh routing configuration are illegal, and the loading is abnormal. + +## Troubleshooting and resolution steps +1. Check the mesh routing rule configuration. ["Mesh Example"](https://dubbo.apache.org/zh/overview/tasks/mesh/). + + + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/2/14.md b/content/en/docs3-v2/java-sdk/faq/2/14.md new file mode 100644 index 000000000000..d8242016e5bb --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/2/14.md @@ -0,0 +1,18 @@ +--- +type: docs +title: "2-15 - Script route execution failed" +linkTitle: "2-15 - Script route execution failed" +weight: 2 +--- + +## possible reason + +* Script routing rules are illegal, resulting in rule parsing failure. +* Dubbo framework failed to execute the script. + +## Troubleshooting and resolution steps +1. Check that the script is written according to the specification. + + + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/2/15.md b/content/en/docs3-v2/java-sdk/faq/2/15.md new file mode 100644 index 000000000000..d758d4d0c9e5 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/2/15.md @@ -0,0 +1,17 @@ +--- +type: docs +title: "2-15 - Routing rule parsing failed" +linkTitle: "2-15 - Routing rule parsing failed" +weight: 2 +--- + +## possible reason + +* The routing rule configured by the user is invalid. + +## Troubleshooting and resolution steps +1. Check the configured routing rules. + + + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/2/16.md b/content/en/docs3-v2/java-sdk/faq/2/16.md new file mode 100644 index 000000000000..5c6de3ae226b --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/2/16.md @@ -0,0 +1,17 @@ +--- +type: docs +title: "2-16 - Request retries failed multiple times" +linkTitle: "2-16 - Request retries failed multiple times" +weight: 2 +--- + +## possible reason + +* The provider is abnormal, causing the consumer to retry and fail many times. + +## Troubleshooting and resolution steps +1. Check the health status of the provider. + + + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/2/17.md b/content/en/docs3-v2/java-sdk/faq/2/17.md new file mode 100644 index 000000000000..99473534181e --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/2/17.md @@ -0,0 +1,19 @@ +--- +type: docs +title: "2-17 - mock request failed" +linkTitle: "2-17 - Mock request failed" +weight: 2 +--- + +## possible reason + +* Configured mandatory mock, suggestive log. +* Executing the mock request is abnormal. + +## Troubleshooting and resolution steps +1. Check whether mandatory mock is configured. +2. Check whether the mock response is normal. + + + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/2/18.md b/content/en/docs3-v2/java-sdk/faq/2/18.md new file mode 100644 index 000000000000..5fa4af4b32bf --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/2/18.md @@ -0,0 +1,17 @@ +--- +type: docs +title: "2-18 - Mesh routing rules are not monitored" +linkTitle: "2-18 - Mesh routing rules are not monitored" +weight: 2 +--- + +## possible reason + +* Mesh delivered routing rules, but the rules were not monitored. + +## Troubleshooting and resolution steps +1. Check whether the mesh routing rule configuration complies with the specification. + + + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/2/19.md b/content/en/docs3-v2/java-sdk/faq/2/19.md new file mode 100644 index 000000000000..7ff06b74b0b2 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/2/19.md @@ -0,0 +1,19 @@ +--- +type: docs +title: "2-19 - Asynchronous request failed" +linkTitle: "2-19 - Asynchronous request failed" +weight: 2 +--- + +## possible reason + +* The provider is abnormal, causing the asynchronous request of the consumer to fail. +* The network is abnormal, causing the asynchronous request of the consumer to fail. + +## Troubleshooting and resolution steps +1. Check the health status of the provider. +1. Check the network status. + + + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/2/2.md b/content/en/docs3-v2/java-sdk/faq/2/2.md new file mode 100644 index 000000000000..079ad01160c1 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/2/2.md @@ -0,0 +1,27 @@ +--- +type: docs +title: "2-2 - No Provider available (address not found)" +linkTitle: "2-2 - No Provider available (address not found)" +weight: 2 +--- + +## possible reason +There may be several situations at this time: + +* The Provider service is not started, or the registration center (such as ZooKeeper, Nacos, Consul) is down. +* There is an error in the service configuration of Dubbo, you must ensure that the service name, group (default is Dubbo), and version are all correct. +* The accessed environment is wrong: Usually we have multiple environments such as development environment, test environment, and online production environment. Sometimes the published service goes to the test environment, but the development environment goes away when the access call is made. + +## Troubleshooting and resolution steps +1. Visit the Ops system of the registration center to check whether there is a provider list for the corresponding service; at the same time, check the log of the server where the caller application is located (generally, the client of each registered service will have corresponding log records) to check whether there is address information push/pull records. +2. If not, it means that the publisher failed to publish the service. Check whether the publisher's application starts successfully. +3. If there is a service, check the registration center that the caller application is connected to, and confirm that it matches the expected environment. +4. If there is no problem with the above, check whether the routing filtering rules are configured. + +## Acknowledgments +The FAQ page of this error code refers to ["Dubbo Common Errors and Solutions"](https://github.com/StabilityMan/StabilityGuide/blob/master/docs/diagnosis/plugin/rpc/%E7%B3%BB%E7%BB%9F%E7%A8%B3%E5%AE%9A%E6%80%A7%E2%80%94%E2%80%94Dubbo%E5%B8%B8%E8%A7%81%E9%94%99%E8%AF%AF%E5%8F%8A%E8%A7%A3%E5%86%B3%E6%96%B9%E6%B3%95.md). + +Articles cited are compiled under license [CC-BY-4.0](http://creativecommons.org/licenses/by/4.0/). Thanks to the original author here. + + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/2/20.md b/content/en/docs3-v2/java-sdk/faq/2/20.md new file mode 100644 index 000000000000..fa7d753b64d3 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/2/20.md @@ -0,0 +1,16 @@ +--- +type: docs +title: "2-20 - Failed to get grouped results merged" +linkTitle: "2-20 - Failed to get grouped results combined" +weight: 20 +--- + +## possible reason + +1. Failed to get grouped results merged. + +## Troubleshooting and resolution steps + +1. When the result is returned, there may be runtime exceptions in business logic, which can be traced according to the number of lines of code specified in the console. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/2/3.md b/content/en/docs3-v2/java-sdk/faq/2/3.md new file mode 100644 index 000000000000..2112b0060fd1 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/2/3.md @@ -0,0 +1,17 @@ +--- +type: docs +title: "2-3 - Routing shutdown failed" +linkTitle: "2-3 - Routing shutdown failed" +weight: 3 +--- + +## possible reason + +* User-defined routes are not written according to the specification. + +## Troubleshooting and resolution steps +1. Refer to the community SPI extension manual to check user-defined routes, ["SPI Extension User Manual"](https://dubbo.apache.org/zh/docs3-v2/java-sdk/reference-manual/spi/ ). + + + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/2/4.md b/content/en/docs3-v2/java-sdk/faq/2/4.md new file mode 100644 index 000000000000..39f6ec7e8ae0 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/2/4.md @@ -0,0 +1,17 @@ +--- +type: docs +title: "2-4 - Merger interface failed to load" +linkTitle: "2-4 - Merger interface failed to load" +weight: 4 +--- + +## possible reason + +* Dubbo provides an SPI extension Merger interface that aggregates the responses of all downstream providers. When Dubbo loads the user-defined extension Merger interface, the loading configuration fails. + +## Troubleshooting and resolution steps +1. Refer to the community SPI extension manual to check the implementation of the user-defined extension Merger interface, ["SPI Extension User Manual"](https://dubbo.apache.org/zh/docs3-v2/java-sdk/reference-manual /spi/). + + + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/2/5.md b/content/en/docs3-v2/java-sdk/faq/2/5.md new file mode 100644 index 000000000000..a23a8f0019f6 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/2/5.md @@ -0,0 +1,18 @@ +--- +type: docs +title: "2-5 - Filter Provider Failed" +linkTitle: "2-5 - Screening providers failed" +weight: 5 +--- + +## possible reason + +* Dubbo will finally select a provider from the provider list to initiate a call during load balancing. During the selection process, the provider list changes, and read-write conflicts occur, resulting in screening exceptions. +* When the Dubbo retry mechanism fails to call the provider, it will re-screen another provider to initiate the call, and an exception occurs during the re-screening process. + +## Troubleshooting and resolution steps +1. Check the registry provider list and the availability of the corresponding provider. +2. Raise an issue in the community, provide environmental site information and reproduction steps. + + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/2/6.md b/content/en/docs3-v2/java-sdk/faq/2/6.md new file mode 100644 index 000000000000..29c67b450086 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/2/6.md @@ -0,0 +1,18 @@ +--- +type: docs +title: "2-6 - Conditional routing filter provider list is empty" +linkTitle: "2-6 - Conditional routing filter provider list is empty" +weight: 6 +--- + +## possible reason + +* Conditional routing provider filter condition is empty. +* Conditional routing filter provider list remains empty under forced downgrade. + +## Troubleshooting and resolution steps +1. Refer to the community request routing example to adjust the conditional routing configuration, ["Request Routing Example"](https://dubbo.apache.org/zh/overview/tasks/traffic-management/traffic-routing/). + + + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/2/7.md b/content/en/docs3-v2/java-sdk/faq/2/7.md new file mode 100644 index 000000000000..a538091a5dbc --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/2/7.md @@ -0,0 +1,17 @@ +--- +type: docs +title: "2-7 - Conditional routing execution exception" +linkTitle: "2-7 - Conditional routing execution exception" +weight: 7 +--- + +## possible reason + +* Conditional routing rules are not configured according to the specification, resulting in exceptions when executing conditional routing filtering. + +## Troubleshooting and resolution steps +1. Refer to the community request routing example to adjust the conditional routing configuration, ["Request Routing Example"](https://dubbo.apache.org/zh/overview/tasks/traffic-management/traffic-routing/). + + + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/2/8.md b/content/en/docs3-v2/java-sdk/faq/2/8.md new file mode 100644 index 000000000000..9382abb79790 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/2/8.md @@ -0,0 +1,17 @@ +--- +type: docs +title: "2-8 - The provider returned an abnormal response" +linkTitle: "2-8 - The provider returned an abnormal response" +weight: 8 +--- + +## possible reason + +* The provider's own processing result throws an exception. + +## Troubleshooting and resolution steps +1. Check whether the provider program is normal. + + + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/2/9.md b/content/en/docs3-v2/java-sdk/faq/2/9.md new file mode 100644 index 000000000000..5e33b7b55b80 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/2/9.md @@ -0,0 +1,17 @@ +--- +type: docs +title: "2-9 - Increase timeout check task failed" +linkTitle: "2-9 - Increase timeout check task failed" +weight: 9 +--- + +## possible reason + +* The Dubbo framework will add a timeout check task to the request call, and the added timeout check task fails. + +## Troubleshooting and resolution steps +1. This exception is an exception of the Dubbo framework itself. Please file an issue in the community and provide the environment site information and reproduction steps. + + + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/2/_index.md b/content/en/docs3-v2/java-sdk/faq/2/_index.md new file mode 100644 index 000000000000..bcb55b62f53e --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/2/_index.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "2 - Routing" +linkTitle: "2 - Routing" +weight: 2 +--- \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/3/1.md b/content/en/docs3-v2/java-sdk/faq/3/1.md new file mode 100644 index 000000000000..89180dfde8dc --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/3/1.md @@ -0,0 +1,22 @@ +--- +type: docs +title: "3-1 - Failed to convert address to Invoker" +linkTitle: "3-1 - Failed to convert address to Invoker" +weight: 1 +--- + +## possible reason + +1. The protocol configured on the client side does not match the protocol configured on the server side. (For example, the protocol configured by the client is the Dubbo protocol, but the server can only provide services of the Rest protocol.) + + +2. The registration center (or configuration center) is unreliable and pushes illegal data. + + + +## Troubleshooting and resolution steps + +1. Check the protocol configuration of both the provider and the consumer. +2. Update the version of the registry. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/3/2.md b/content/en/docs3-v2/java-sdk/faq/3/2.md new file mode 100644 index 000000000000..65a809d168dc --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/3/2.md @@ -0,0 +1,19 @@ +--- +type: docs +title: "3-2 - Publish or push service failed" +linkTitle: "3-2 - Publish or push service failed" +weight: 2 +--- + +## possible reason + +1. The registration center cannot be connected. +2. The registration center cannot provide external services. + +## Troubleshooting and resolution steps + +1. Whether the service and registration center network is normal. +2. Whether the registration center starts normally and can be connected through third-party tools. +3. Whether there is a version compatibility problem between the version referenced by the service and the version of the registration center. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/3/3.md b/content/en/docs3-v2/java-sdk/faq/3/3.md new file mode 100644 index 000000000000..86385193a99e --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/3/3.md @@ -0,0 +1,16 @@ +--- +type: docs +title: "3-3 - Failed to generate bytecode via Javassist" +linkTitle: "3-3 - Failed to generate bytecode through Javassist" +weight: 3 +--- + +## possible reason + +Generation of bytecode via Javassist fails. + +## Troubleshooting and resolution steps + +Generally, it is an internal reminder error in dubbo, or it is not supported by Javassist. It will try to use the JDK agent. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/3/4.md b/content/en/docs3-v2/java-sdk/faq/3/4.md new file mode 100644 index 000000000000..63ebca6a6d00 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/3/4.md @@ -0,0 +1,19 @@ +--- +type: docs +title: "3-4 - Client sending request timed out" +linkTitle: "3-4 - Client sending request timed out" +weight: 4 +--- + +## possible reason + +1. The number of client connections is too high, the response is slow, and the request cannot be sent to the server in time. +2. Some reasons for the network. + +## Troubleshooting and resolution steps + +1. Whether the network is normal. +2. You can use some third-party tools or `jstack [PID] > jstack.log` to analyze the stack information and locate it. + + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/3/5.md b/content/en/docs3-v2/java-sdk/faq/3/5.md new file mode 100644 index 000000000000..461b07f8beec --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/3/5.md @@ -0,0 +1,18 @@ +--- +type: docs +title: "3-5 - An exception occurred in the asynchronous response" +linkTitle: "3-5 - An exception occurred in the asynchronous response" +weight: 5 +--- + +## possible reason + +1. The business logic does have a runtime exception. +2. The connection is refused due to network reasons. + +## Troubleshooting and resolution steps + +1. For the business code, please trace back and check according to the prompt line of the stack. +2. Check whether the network of the service provider is normal. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/3/6.md b/content/en/docs3-v2/java-sdk/faq/3/6.md new file mode 100644 index 000000000000..51bf4bb4a11b --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/3/6.md @@ -0,0 +1,18 @@ +--- +type: docs +title: "3-6 - An exception occurred in the proxy execution service" +linkTitle: "3-6 - An exception occurred in the proxy execution service" +weight: 6 +--- + +## possible reason + +1. The current service parameters have been displayed as `deprecated`. +2. This reminder may appear for generic declaration classes. + +## Troubleshooting and resolution steps + +1. Confirm whether there is a display parameter `deprecated=true` in the URL +2. If this error occurs in the generic declaration class, it will try to create a proxy without the actual interface class. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/3/7.md b/content/en/docs3-v2/java-sdk/faq/3/7.md new file mode 100644 index 000000000000..bcdd18457b37 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/3/7.md @@ -0,0 +1,21 @@ +--- +type: docs +title: "3-7 - Server response timed out" +linkTitle: "3-7 - Server response timed out" +weight: 7 +--- +The server did not get a response within the time set by the client. + +## possible reason + +1. The business processing logic of the server is complex and cannot respond within the effective time. +2. The connection between the server and the client is disconnected, and the network packet is lost. +3. The server load is too high. + +## Troubleshooting and resolution steps + +1. Check whether there is indeed a performance bottleneck in the business processing capability of the server. +2. Whether the network is normal. +3. You can use some third-party tools or `jstack [PID] > jstack.log` to analyze the stack information and locate it. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/3/8.md b/content/en/docs3-v2/java-sdk/faq/3/8.md new file mode 100644 index 000000000000..cb06c6869500 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/3/8.md @@ -0,0 +1,22 @@ +--- +type: docs +title: "3-8 - Proxy Failure" +linkTitle: "3-8 - Agent failed" +weight: 8 +--- + +Failed to generate dynamic proxy. + +## possible reason + +1. There is dynamic class loading +2. Class format exception + +## Troubleshooting and resolution steps + +1. If `Fallback to use JDK proxy success` is displayed in the log, + It means that Dubbo has successfully created a dynamic proxy after automatically falling back to the JDK proxy. If the program is running normally, you can ignore it +2. If the log shows `Fallback to use JDK proxy is also failed`, + Please check whether the corresponding class loading is normal according to the exception stack information, you can use tools such as arthas to assist in troubleshooting + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/3/_index.md b/content/en/docs3-v2/java-sdk/faq/3/_index.md new file mode 100644 index 000000000000..6f7d0bd424de --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/3/_index.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "3 - Proxy" +linkTitle: "3 - Proxy" +weight: 3 +--- \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/4/1.md b/content/en/docs3-v2/java-sdk/faq/4/1.md new file mode 100644 index 000000000000..2a4a1a8e85ad --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/4/1.md @@ -0,0 +1,21 @@ +--- +type: docs +title: "4-1 - Unsupported protocol" +linkTitle: "4-1 - Unsupported protocol" +weight: 1 +--- + +## possible reason +This situation may occur in the scenario of custom Protocol. Dubbo's SPI mechanism cannot find the Protocol specified in the URL. + + +## Troubleshooting and resolution steps +1. Make sure that the Consumer has dependencies on the Protocol used by the server. +2. Make sure that the name of the SPI configuration file of the Protocol's dependent package is correct. + +## see also +[Dubbo SPI Overview](https://dubbo.apache.org/zh/docs3-v2/java-sdk/reference-manual/spi/overview/) + +[Protocol Extension Description](https://dubbo.apache.org/zh/docs3-v2/java-sdk/reference-manual/spi/description/protocol/) + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/4/10.md b/content/en/docs3-v2/java-sdk/faq/4/10.md new file mode 100644 index 000000000000..794767898c90 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/4/10.md @@ -0,0 +1,17 @@ +--- +type: docs +title: "4-10 - Triple serialization result failed" +linkTitle: "4-10 - Triple serialization result failed" +weight: 10 +--- + +## possible reason + +Usually an internal error. + +## Troubleshooting and resolution steps + +You can use some third-party tools or `jstack [PID] > jstack.log` to analyze the stack information and locate it. +At the same time, please submit an issue in the community. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/4/11.md b/content/en/docs3-v2/java-sdk/faq/4/11.md new file mode 100644 index 000000000000..bdecc55d20de --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/4/11.md @@ -0,0 +1,20 @@ +--- +type: docs +title: "4-11 - Failed to initiate request" +linkTitle: "4-11 - Failed to initiate the request" +weight: 11 +--- + +## possible reason + +1. The server is closed. +2. The IP of the caller is not in the whitelist of the server. +3. The requested specific address service does not exist. + +## Troubleshooting and resolution steps + +1. Check the startup and operation of the server. +2. Check or use a third-party tool to test whether the network environment can be connected normally. +3. According to the serviceName of the stack, check or simulate the call in the management platform to see if it is normal. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/4/12.md b/content/en/docs3-v2/java-sdk/faq/4/12.md new file mode 100644 index 000000000000..287df9e0a672 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/4/12.md @@ -0,0 +1,17 @@ +--- +type: docs +title: "4-12 - Failed to create Triple stream" +linkTitle: "4-12 - Failed to create Triple stream" +weight: 12 +--- + +## possible reason + +Usually an internal error. + +## Troubleshooting and resolution steps + +You can use some third-party tools or `jstack [PID] > jstack.log` to analyze the stack information and locate it. +At the same time, please submit an issue in the community. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/4/13.md b/content/en/docs3-v2/java-sdk/faq/4/13.md new file mode 100644 index 000000000000..79e80e5fcfa9 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/4/13.md @@ -0,0 +1,20 @@ +--- +type: docs +title: "4-13 - Server Timeout" +linkTitle: "4-13 - Server Timeout" +weight: 13 +--- + +## possible reason + +1. Server-side logic processing is relatively time-consuming. +2. The server load request is too high to respond. +3. The current timeout parameter setting threshold is quite different from the actual situation. + +## Troubleshooting and resolution steps + +1. Check whether there is time-consuming processing based on the interface name. +2. It can monitor the status of the server and the service calls invoked by the server. +3. Try increasing the timeout parameter. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/4/14.md b/content/en/docs3-v2/java-sdk/faq/4/14.md new file mode 100644 index 000000000000..5c60b684719d --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/4/14.md @@ -0,0 +1,18 @@ +--- +type: docs +title: "4-14 - Response Result Failed" +linkTitle: "4-14 - Response result failed" +weight: 14 +--- + +## possible reason + +1. The server pipeline may be temporarily disconnected due to network reasons. +2. The currently used version is lower or you can check the current parameter configuration to see if `send.reconnect=true` is enabled, and the higher version defaults to true. + +## Troubleshooting and resolution steps + +1. Check whether the directly connected network is smooth and whether there is any packet loss. +2. Check the above parameter values, or try to use a higher version. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/4/15.md b/content/en/docs3-v2/java-sdk/faq/4/15.md new file mode 100644 index 000000000000..16d9096f3781 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/4/15.md @@ -0,0 +1,15 @@ +--- +type: docs +title: "4-15 - Client Stream Listener" +linkTitle: "4-15 - Client Stream Listener" +weight: 15 +--- + +## possible reason + +After receiving the response from the server, the client stream listener will output this information for reminder. + +## Troubleshooting and resolution steps + + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/4/16.md b/content/en/docs3-v2/java-sdk/faq/4/16.md new file mode 100644 index 000000000000..a3f2d102c361 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/4/16.md @@ -0,0 +1,16 @@ +--- +type: docs +title: "4-16 - Service Closed" +linkTitle: "4-16 - Service is closed" +weight: 16 +--- + +## possible reason + +Incorrect use of internal `org.apache.dubbo.rpc.protocol.tri.service.TriHealthImpl#enterTerminalState` + +## Troubleshooting and resolution steps + +Calling the above method multiple times will remind you. Generally only used for unit testing. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/4/17.md b/content/en/docs3-v2/java-sdk/faq/4/17.md new file mode 100644 index 000000000000..778c5ef658d0 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/4/17.md @@ -0,0 +1,17 @@ +--- +type: docs +title: "4-17 - Error closing all callers" +linkTitle: "4-17 - Error closing all callers" +weight: 17 +--- + +## possible reason + +Usually an internal error. + +## Troubleshooting and resolution steps + +You can use some third-party tools or `jstack [PID] > jstack.log` to analyze the stack information and locate it. +At the same time, please submit an issue in the community. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/4/18.md b/content/en/docs3-v2/java-sdk/faq/4/18.md new file mode 100644 index 000000000000..76d5f2b64efa --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/4/18.md @@ -0,0 +1,15 @@ +--- +type: docs +title: "4-18 - Unable to get service model from call" +linkTitle: "4-18 - Unable to get service model from call" +weight: 18 +--- + +## possible reason + +Currently only used in unit test scenarios, the service model will be initialized by default. + +## Troubleshooting and resolution steps + + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/4/19.md b/content/en/docs3-v2/java-sdk/faq/4/19.md new file mode 100644 index 000000000000..822121babcb2 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/4/19.md @@ -0,0 +1,19 @@ +--- +type: docs +title: "4-19 - Parameter values may be wrong" +linkTitle: "4-19 - Parameter values may be wrong" +weight: 19 +--- + +## Important Reminder +The meaning of this error code has been adjusted. For Dubbo 3.1.4, 3.2.0-beta.3 and previous versions of this error code, please refer to Error Code [0-2](https://cn.dubbo.apache.org/zh/docs3-v2/java-sdk/faq/0/2/). + +## possible reason +This error code indicates that the parameter value may no longer be correct. + +At present, it appears that the same protocol is listening to multiple ports at the same time. Due to design limitations, a single protocol can only listen on one port, otherwise the port configuration will be overwritten. + +## Troubleshooting and resolution steps +Adjust the monitoring relationship between protocols and ports. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/4/2.md b/content/en/docs3-v2/java-sdk/faq/4/2.md new file mode 100644 index 000000000000..2292c26e2332 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/4/2.md @@ -0,0 +1,16 @@ +--- +type: docs +title: "4-2 - Serialization optimizer initial error" +linkTitle: "4-2 - Serialization optimizer initial error" +weight: 2 +--- + +## possible reason + +The serialization configuration of Kryo and FST is currently used. + +## Troubleshooting and resolution steps + +Please refer to [Kryo and FST serialization](/en/docs3-v2/java-sdk/advanced-features-and-usage/performance/serialization/) + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/4/20.md b/content/en/docs3-v2/java-sdk/faq/4/20.md new file mode 100644 index 000000000000..cde7bdb03465 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/4/20.md @@ -0,0 +1,16 @@ +--- +type: docs +title: "4-20 - Data decoding failed" +linkTitle: "4-20 - Data decoding failed" +weight: 20 +--- + +## possible reason + +Version mismatch between server and caller. + +## Troubleshooting and resolution steps + +Check the currently used dubbo version, and try to keep a consistent or backward compatible high version. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/4/3.md b/content/en/docs3-v2/java-sdk/faq/4/3.md new file mode 100644 index 000000000000..3144d05ae151 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/4/3.md @@ -0,0 +1,16 @@ +--- +type: docs +title: "4-3 - Interface reference call failed" +linkTitle: "4-3 - Interface reference call failed" +weight: 3 +--- + +## possible reason + +No exposed service interface or method was found based on the specified protocol parameter. + +## Troubleshooting and resolution steps + +You can confirm whether the server exists according to the interface URL and method name. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/4/4.md b/content/en/docs3-v2/java-sdk/faq/4/4.md new file mode 100644 index 000000000000..65346ddd1cd7 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/4/4.md @@ -0,0 +1,16 @@ +--- +type: docs +title: "4-4 - Non-safe serialization method" +linkTitle: "4-4 - Non-safe serialization method" +weight: 4 +--- + +## possible reason + +Currently using an unsafe serializer, which is not recommended. The specific configuration is: `serialization="java"` + +## Troubleshooting and resolution steps + +Modify the parameter value of the setting. Change the serialization parameter value in the protocol to other. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/4/5.md b/content/en/docs3-v2/java-sdk/faq/4/5.md new file mode 100644 index 000000000000..89d937c8e620 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/4/5.md @@ -0,0 +1,16 @@ +--- +type: docs +title: "4-5 - Stream closed exception" +linkTitle: "4-5 - Stream closed exception" +weight: 5 +--- + +## possible reason + +The prompt information does not affect the execution result of the program. + +## Troubleshooting and resolution steps + +You can use some third-party tools or `jstack [PID] > jstack.log` to analyze the stack information and locate it. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/4/6.md b/content/en/docs3-v2/java-sdk/faq/4/6.md new file mode 100644 index 000000000000..ebcb9746a9ed --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/4/6.md @@ -0,0 +1,16 @@ +--- +type: docs +title: "4-6 - Deserialization failed" +linkTitle: "4-6 - Deserialization failed" +weight: 6 +--- + +## possible reason + +There is a logic error in the custom SPI `org.apache.dubbo.common.serialize.Serialization` serialization method. + +## Troubleshooting and resolution steps + +You can use some third-party tools or `jstack [PID] > jstack.log` to analyze the stack information and locate it. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/4/7.md b/content/en/docs3-v2/java-sdk/faq/4/7.md new file mode 100644 index 000000000000..a3e5742f7029 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/4/7.md @@ -0,0 +1,15 @@ +--- +type: docs +title: "4-7 - An error occurred while closing the client" +linkTitle: "4-7 - An error occurred while closing the client" +weight: 7 +--- + +## possible reason + + +## Troubleshooting and resolution steps + +You can use some third-party tools or `jstack [PID] > jstack.log` to analyze the stack information and locate it. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/4/8.md b/content/en/docs3-v2/java-sdk/faq/4/8.md new file mode 100644 index 000000000000..c66f8d6fce3c --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/4/8.md @@ -0,0 +1,15 @@ +--- +type: docs +title: "4-8 - An error occurred while closing the server" +linkTitle: "4-8 - An error occurred while closing the server" +weight: 8 +--- + +## possible reason + + +## Troubleshooting and resolution steps + +You can use some third-party tools or `jstack [PID] > jstack.log` to analyze the stack information and locate it. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/4/9.md b/content/en/docs3-v2/java-sdk/faq/4/9.md new file mode 100644 index 000000000000..51a070cda20f --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/4/9.md @@ -0,0 +1,16 @@ +--- +type: docs +title: "4-9 - Parse failed" +linkTitle: "4-9 - Parse failed" +weight: 9 +--- + +## possible reason + +Generally, the parameter value does not conform to the rules, and an error occurs during forced conversion. + +## Troubleshooting and resolution steps + +Modify the configuration according to the key name prompted by the stack information. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/4/_index.md b/content/en/docs3-v2/java-sdk/faq/4/_index.md new file mode 100644 index 000000000000..df259aff6502 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/4/_index.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "4 - Protocol" +linkTitle: "4 - Protocol" +weight: 4 +--- \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/5/1.md b/content/en/docs3-v2/java-sdk/faq/5/1.md new file mode 100644 index 000000000000..488e8c38c0f6 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/5/1.md @@ -0,0 +1,21 @@ +--- +type: docs +title: "5-1 - Failed to connect to configuration center" +linkTitle: "5-1 - Failed to connect to the configuration center" +weight: 1 +--- + +## possible reason + +1. The server where the configuration center is located is shut down or down. +2. Wrong IP or port number. +3. The firewall blocked the port of the configuration center by mistake. + + +## Troubleshooting and resolution steps + +1. Check configuration center IP and port configuration. +2. Check whether the server is turned on and works normally. +3. Check whether the port used by the configuration center is allowed by the firewall or not. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/5/10.md b/content/en/docs3-v2/java-sdk/faq/5/10.md new file mode 100644 index 000000000000..e295b8b1962a --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/5/10.md @@ -0,0 +1,16 @@ +--- +type: docs +title: "5-10 - Registration interface application mapping failed for service" +linkTitle: "5-10 - Service's registration interface application mapping failed" +weight: 10 +--- + +## possible reason + +The service metadata exposed by the service does not match the application, or has been tampered with. + +## Troubleshooting and resolution steps + +Check that the metadata content in the configuration center matches that in the application. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/5/11.md b/content/en/docs3-v2/java-sdk/faq/5/11.md new file mode 100644 index 000000000000..9f147adfe832 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/5/11.md @@ -0,0 +1,20 @@ +--- +type: docs +title: "5-11 - Registration Instance Error" +linkTitle: "5-11 - Registration instance error" +weight: 11 +--- + +## possible reason + +1. The service of the configuration center cannot be connected. +2. The configured protocol, IP, and port are incorrect. +3. The client version of the configuration center conflicts with the server version, and a valid connection cannot be established. + +## Troubleshooting and resolution steps + +1. Check whether the service status of the configuration center is normal. +2. Check that the configured protocol, IP, and port are incorrect. +3. Check whether the version of the configuration center client used is compatible with the version of the server. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/5/12.md b/content/en/docs3-v2/java-sdk/faq/5/12.md new file mode 100644 index 000000000000..b80356a3e5fb --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/5/12.md @@ -0,0 +1,20 @@ +--- +type: docs +title: "5-12 - Refresh instance and metadata errors" +linkTitle: "5-12 - Refresh instance and metadata errors" +weight: 12 +--- + +## possible reason + +1. The service of the configuration center cannot be connected. +2. The configured protocol, IP, and port are incorrect. +3. The client version of the configuration center conflicts with the server version, and a valid connection cannot be established. + +## Troubleshooting and resolution steps + +1. Check whether the service status of the configuration center is normal. +2. Check that the configured protocol, IP, and port are incorrect. +3. Check whether the version of the configuration center client used is compatible with the version of the server. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/5/13.md b/content/en/docs3-v2/java-sdk/faq/5/13.md new file mode 100644 index 000000000000..e0a8c0aae99a --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/5/13.md @@ -0,0 +1,16 @@ +--- +type: docs +title: "5-13 - Model cannot be destroyed" +linkTitle: "5-13 - Model cannot be destroyed" +weight: 13 +--- + +## possible reason + +There is an exception in the business processing of the custom destruction method. + +## Troubleshooting and resolution steps + +Check the custom destruction method and business processing logic for runtime exceptions. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/5/14.md b/content/en/docs3-v2/java-sdk/faq/5/14.md new file mode 100644 index 000000000000..33ae51dfd2d0 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/5/14.md @@ -0,0 +1,18 @@ +--- +type: docs +title: "5-14 - Model startup error" +linkTitle: "5-14 - Model startup error" +weight: 14 +--- + +## possible reason + +1. The connection is disconnected while the service is waiting to publish or subscribe. +2. The network connection timed out. + +## Troubleshooting and resolution steps + +1. Check whether the connection between the application server and the configuration center is normal. +2. Check whether there is a timeout in the network connection, etc. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/5/15.md b/content/en/docs3-v2/java-sdk/faq/5/15.md new file mode 100644 index 000000000000..3ad664187326 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/5/15.md @@ -0,0 +1,16 @@ +--- +type: docs +title: "5-15 - Model Reference Error" +linkTitle: "5-15 - Model Reference Error" +weight: 15 +--- + +## possible reason + +The method of Dubbo core processing class is misused or tampered with. + +## Troubleshooting and resolution steps + +Check for misuse or decompiled modifications on the application. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/5/16.md b/content/en/docs3-v2/java-sdk/faq/5/16.md new file mode 100644 index 000000000000..a8787e62eaa5 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/5/16.md @@ -0,0 +1,19 @@ +--- +type: docs +title: "5-16 - Unable to find any valid agreements" +linkTitle: "5-16 - Unable to find any valid agreements" +weight: 16 +--- + +## possible reason + +The configured protocol is not supported. + +## Troubleshooting and resolution steps + +Currently supported protocols are dubbo, rmi, hessian, http, webservice, thrift, redis, etc. + +## see also +[Configuration item reference manual](https://dubbo.apache.org/zh/docs3-v2/java-sdk/reference-manual/config/) + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/5/17.md b/content/en/docs3-v2/java-sdk/faq/5/17.md new file mode 100644 index 000000000000..1e250d2ae94d --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/5/17.md @@ -0,0 +1,18 @@ +--- +type: docs +title: "5-17 - Parameter value format error" +linkTitle: "5-17 - Parameter value format error" +weight: 17 +--- + +## possible reason + +1. The attribute configuration value is too long, generally set within 200 characters. +2. The format of the attribute configuration value is wrong, currently supports numbers, -, _, etc. + +## Troubleshooting and resolution steps + +1. Check whether the content of the attribute configuration value is too long, and modify it according to the prompt information. +2. Check whether the attribute configuration value contains special characters, such as @#$%^&, etc. For details, please refer to the prompt information to modify. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/5/18.md b/content/en/docs3-v2/java-sdk/faq/5/18.md new file mode 100644 index 000000000000..397bebb4c3f0 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/5/18.md @@ -0,0 +1,18 @@ +--- +type: docs +title: "5-18 - Notification registration event failed" +linkTitle: "5-18 - Notification registration event failed" +weight: 18 +--- + +## possible reason + +1. The notification has been sent, and an unexpected error occurred in the business processing logic. +2. The configuration center cannot be connected, timeout error. + +## Troubleshooting and resolution steps + +1. Check the custom business logic implementation, whether there is a runtime exception. +2. Check whether the configuration center can be connected normally. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/5/19.md b/content/en/docs3-v2/java-sdk/faq/5/19.md new file mode 100644 index 000000000000..31215bbc03e3 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/5/19.md @@ -0,0 +1,22 @@ +--- +type: docs +title: "5-19 - Embedded ZooKeeper running abnormally" +linkTitle: "5-19 - The embedded ZooKeeper runs abnormally" +weight: 19 +--- + +## possible reason + +1. The ZooKeeper service is running abnormally or down. +2. The Zookeeper client version is incompatible with the server startup version and cannot be connected. +3. The connection between the application server and the ZooKeeper service is interrupted. +4. Restricted firewall or third-party protection tools. + +## Troubleshooting and resolution steps + +1. Check the ZooKeeper service and the health status of the server where it resides. +2. Check whether there is a compatibility problem between the Zookeeper client version and the server startup version, and keep the versions consistent. +3. Check whether the ports of the application server and the ZooKeeper service are unblocked. +4. Check the firewall or third-party protection tool settings to see if it is disabled. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/5/2.md b/content/en/docs3-v2/java-sdk/faq/5/2.md new file mode 100644 index 000000000000..dd719b264e3a --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/5/2.md @@ -0,0 +1,16 @@ +--- +type: docs +title: "5-2 - Failed to register/unregister shutdown hook method" +linkTitle: "5-2 - Failed to register/unregister shutdown hook method" +weight: 2 +--- + +## possible reason + +There are exceptions in the custom hook method and business processing logic. + +## Troubleshooting and resolution steps + +Check the custom hook method and business processing logic for runtime exceptions. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/5/20.md b/content/en/docs3-v2/java-sdk/faq/5/20.md new file mode 100644 index 000000000000..0d3f7286d88b --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/5/20.md @@ -0,0 +1,18 @@ +--- +type: docs +title: "5-20 - Error occurred while stopping dubbo module" +linkTitle: "5-20 - An error occurred while stopping the dubbo module" +weight: 20 +--- + +## possible reason + +1. Customize the implementation of the destruction method, and there may be exceptions when the business logic is running. +2. The service has not been gracefully stopped, and there may be cases where the business logic has not been processed. + +## Troubleshooting and resolution steps + +1. Check the custom implementation of the destruction method and business logic. +2. Check whether there is time-consuming business processing logic when the service is stopped. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/5/21.md b/content/en/docs3-v2/java-sdk/faq/5/21.md new file mode 100644 index 000000000000..683cb69fc2bf --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/5/21.md @@ -0,0 +1,18 @@ +--- +type: docs +title: "5-21 - An exception occurred when the service was destroyed" +linkTitle: "5-21 - An exception occurred when the service was destroyed" +weight: 21 +--- + + +## possible reason + +The service discovery instance has been destroyed + +Attachment: The current method has been discontinued in version 3.1 + +## Troubleshooting and resolution steps + + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/5/22.md b/content/en/docs3-v2/java-sdk/faq/5/22.md new file mode 100644 index 000000000000..06200ee58147 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/5/22.md @@ -0,0 +1,21 @@ +--- +type: docs +title: "5-22 - An error occurred while initializing the registry" +linkTitle: "5-22 - An error occurred while initializing the registry" +weight: 22 +--- + + +## possible reason + +1. The address configuration of the registration center is wrong. +2. The configured address information cannot be connected through the network normally. +3. The version of the configuration center client does not match the version of the actual server, and there is a compatibility exception. + +## Troubleshooting and resolution steps + +1. Check whether the configured address is correct. +2. Check whether the network is smooth and can be connected through a third-party client. +3. Check whether there is a compatibility matching problem, you can refer to the third-party website for version adaptation. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/5/23.md b/content/en/docs3-v2/java-sdk/faq/5/23.md new file mode 100644 index 000000000000..3fefad467c39 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/5/23.md @@ -0,0 +1,19 @@ +--- +type: docs +title: "5-23 - Waiting for export/reference service exception" +linkTitle: "5-23 - Waiting for export/reference service exception" +weight: 23 +--- + + +## possible reason + +When exporting/referencing services, the registration center stops abnormally or fails to provide normal services externally. + +## Troubleshooting and resolution steps + +Check whether the registration center can be connected normally, and check whether the current client version is compatible with the server. + +Attachment: The exception is handled in the export/quote method, and theoretically this exception will not be thrown. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/5/24.md b/content/en/docs3-v2/java-sdk/faq/5/24.md new file mode 100644 index 000000000000..67904d12a634 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/5/24.md @@ -0,0 +1,17 @@ +--- +type: docs +title: "5-24 - An exception occurred while asynchronously waiting for the reference service" +linkTitle: "5-24 - An exception occurred while asynchronously waiting for the reference service" +weight: 24 +--- + + +## possible reason + +The registration center stops abnormally or cannot provide normal services to the outside world. + +## Troubleshooting and resolution steps + +Check whether the registration center can be connected normally, and check whether the current client version is compatible with the server. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/5/25.md b/content/en/docs3-v2/java-sdk/faq/5/25.md new file mode 100644 index 000000000000..184e5e2bcee6 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/5/25.md @@ -0,0 +1,16 @@ +--- +type: docs +title: "5-25 - Undefined exception from custom implementation" +linkTitle: "5-25 - Undefined exception from custom implementation" +weight: 25 +--- + +## possible reason + +The custom implemented `org.apache.dubbo.rpc.Protocol` protocol has a business logic exception when the method calls destroy. + +## Troubleshooting and resolution steps + +Check the `destory` method of the custom implementation class code. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/5/26.md b/content/en/docs3-v2/java-sdk/faq/5/26.md new file mode 100644 index 000000000000..f770432c0e84 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/5/26.md @@ -0,0 +1,15 @@ +--- +type: docs +title: "5-26 - Metadata Exported" +linkTitle: "5-26 - Metadata exported" +weight: 26 +--- + +## possible reason + +Metadata has been exported in the current JVM. + +## Troubleshooting and resolution steps + + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/5/27.md b/content/en/docs3-v2/java-sdk/faq/5/27.md new file mode 100644 index 000000000000..f4de0b104582 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/5/27.md @@ -0,0 +1,16 @@ +--- +type: docs +title: "5-27 - Inner class API is misused" +linkTitle: "5-27 - Inner class API is misused" +weight: 27 +--- + +## possible reason + +`org.apache.dubbo.config.ReferenceConfig` and `org.apache.dubbo.common.config.ReferenceCache` may be defined as non-singleton mode. + +## Troubleshooting and resolution steps + +Check custom annotations or configurations, define the core application class as a non-singleton mode, check `scope` configuration. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/5/28.md b/content/en/docs3-v2/java-sdk/faq/5/28.md new file mode 100644 index 000000000000..c924d1177107 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/5/28.md @@ -0,0 +1,16 @@ +--- +type: docs +title: "5-28 - No available annotation found" +linkTitle: "5-28 - No available annotation found" +weight: 28 +--- + +## possible reason + +No reliable annotations were found under the scan package configuration. Mainly `@DubboService` or `@Service` + +## Troubleshooting and resolution steps + +Check the current version, `@Service` annotation will be scanned before 2.7.7, and `@DubboService` after that + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/5/29.md b/content/en/docs3-v2/java-sdk/faq/5/29.md new file mode 100644 index 000000000000..998cc0700dcc --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/5/29.md @@ -0,0 +1,16 @@ +--- +type: docs +title: "5-29 - Scan package not configured" +linkTitle: "5-29 - Scan package not configured" +weight: 29 +--- + +## possible reason + +`@EnableDubbo.scanBasePackages` annotation parameter value is not configured + +## Troubleshooting and resolution steps + +`@EnableDubbo.scanBasePackages` can be configured. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/5/3.md b/content/en/docs3-v2/java-sdk/faq/5/3.md new file mode 100644 index 000000000000..dae9d53ba1c9 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/5/3.md @@ -0,0 +1,16 @@ +--- +type: docs +title: "5-3 - An unexpected error occurred while destroying a method call" +linkTitle: "5-3 - An unexpected error occurred while destroying a method call" +weight: 3 +--- + +## possible reason + +There is an exception in the business processing of the custom destruction method. + +## Troubleshooting and resolution steps + +Check the custom destruction method and business processing logic for runtime exceptions. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/5/30.md b/content/en/docs3-v2/java-sdk/faq/5/30.md new file mode 100644 index 000000000000..3690794a4a2c --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/5/30.md @@ -0,0 +1,16 @@ +--- +type: docs +title: "5-30 - Duplicate bean definition" +linkTitle: "5-30 - Duplicate bean definition" +weight: 30 +--- + +## possible reason + +Duplicate object id or name declared. + +## Troubleshooting and resolution steps + +According to the fully qualified class name output by the console, the name can only be modified to be unique. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/5/31.md b/content/en/docs3-v2/java-sdk/faq/5/31.md new file mode 100644 index 000000000000..01c0aa9745dd --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/5/31.md @@ -0,0 +1,16 @@ +--- +type: docs +title: "5-31 - Status Check Error" +linkTitle: "5-31 - Status check error" +weight: 31 +--- + +## possible reason + +Currently running server status, system CPU usage is too high or memory and other indicators are too low + +## Troubleshooting and resolution steps + +Check the memory usage status of the current server, and other indicators such as CPU usage, there may be a danger of downtime. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/5/32.md b/content/en/docs3-v2/java-sdk/faq/5/32.md new file mode 100644 index 000000000000..2b5c5742a8f6 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/5/32.md @@ -0,0 +1,16 @@ +--- +type: docs +title: "5-32 - Apollo disconnected with an error" +linkTitle: "5-32 - Apollo disconnected with an error" +weight: 32 +--- + +## possible reason + +The Apollo Config Center may be down or disconnected from the network. + +## Troubleshooting and resolution steps + +Check the service status of the Apollo server and whether the network can communicate normally. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/5/33.md b/content/en/docs3-v2/java-sdk/faq/5/33.md new file mode 100644 index 000000000000..1db98f36767c --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/5/33.md @@ -0,0 +1,16 @@ +--- +type: docs +title: "5-33 - An exception occurred in the Apollo configuration update event" +linkTitle: "5-33 - An exception occurred in the Apollo configuration update event" +weight: 33 +--- + +## possible reason + +The Apollo configuration API is used incorrectly. + +## Troubleshooting and resolution steps + +Please refer to the description about Apollo in the Dynamic Configuration Center Documentation. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/5/34.md b/content/en/docs3-v2/java-sdk/faq/5/34.md new file mode 100644 index 000000000000..c2d055cd7808 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/5/34.md @@ -0,0 +1,16 @@ +--- +type: docs +title: "5-34 - NACOS Error" +linkTitle: "5-34 - NACOS went wrong" +weight: 34 +--- + +## possible reason + +NACOS configuration API usage error. + +## Troubleshooting and resolution steps + +Please refer to the description about NACOS in the Dynamic Configuration Center Documentation. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/5/35.md b/content/en/docs3-v2/java-sdk/faq/5/35.md new file mode 100644 index 000000000000..2ea322597d06 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/5/35.md @@ -0,0 +1,17 @@ +--- +type: docs +title: "5-35 - Container initialization failed" +linkTitle: "5-35 - Container initialization failed" +weight: 35 +--- + +## possible reason + +The `org.apache.dubbo.container.Container` SPI implementation of the undefined interface. + +P.S. It is currently tested and used in `org.apache.dubbo.container.Main` class. + +## Troubleshooting and resolution steps + + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/5/36.md b/content/en/docs3-v2/java-sdk/faq/5/36.md new file mode 100644 index 000000000000..21de14f8374f --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/5/36.md @@ -0,0 +1,16 @@ +--- +type: docs +title: "5-36 - An error occurred during filter validation" +linkTitle: "5-36 - An error occurred during filter validation" +weight: 36 +--- + +## possible reason + +The `invoke` method rewritten in the custom filter extension class has a business code exception. + +## Troubleshooting and resolution steps + +You can use some third-party tools or `jstack [PID] > jstack.log` to analyze the stack information and locate it. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/5/37.md b/content/en/docs3-v2/java-sdk/faq/5/37.md new file mode 100644 index 000000000000..c062c9f2abf9 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/5/37.md @@ -0,0 +1,17 @@ +--- +type: docs +title: "5-37 - An error occurred in the processing of dynamic configuration monitoring" +linkTitle: "5-37 - An error occurred in the processing of dynamic configuration monitoring" +weight: 37 +--- +When the file changes, the listening event processing fails + +## possible reason + +File permissions changed or directory permissions changed. + +## Troubleshooting and resolution steps + +The code can be located according to the stack information of the console. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/5/38.md b/content/en/docs3-v2/java-sdk/faq/5/38.md new file mode 100644 index 000000000000..4eeef8baeb3e --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/5/38.md @@ -0,0 +1,16 @@ +--- +type: docs +title: "5-38 - Configuration parameter undefined" +linkTitle: "5-38 - Configuration parameter undefined" +weight: 38 +--- + +## possible reason + +configuration parameter is undefined + +## Troubleshooting and resolution steps + +It is mostly used in test cases, and parameters can be set according to the prompt details. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/5/39.md b/content/en/docs3-v2/java-sdk/faq/5/39.md new file mode 100644 index 000000000000..2a67465f1af6 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/5/39.md @@ -0,0 +1,17 @@ +--- +type: docs +title: "5-39 - An error occurred in the Dubbo configuration bean initializer" +linkTitle: "5-39 - An error occurred in the Dubbo configuration bean initializer" +weight: 39 +--- + +## possible reason + +source code or modified + +## Troubleshooting and resolution steps + +Check that the business code does not modify the source code or load sequence of the core class. +Such as: org.apache.dubbo.config.spring.context.DubboConfigBeanInitializer + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/5/4.md b/content/en/docs3-v2/java-sdk/faq/5/4.md new file mode 100644 index 000000000000..36c3d94d6511 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/5/4.md @@ -0,0 +1,18 @@ +--- +type: docs +title: "5-4 - Method not found in service interface" +linkTitle: "5-4 - Method not found in service interface" +weight: 4 +--- + +## possible reason + +1. The interface name#method called by the consumer does not exist. +2. The server does not expose the current interface correctly. + +## Troubleshooting and resolution steps + +1. Check whether the interface name# method called by the consumer exists. +2. Check whether it exists in the service list exposed by the server. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/5/40.md b/content/en/docs3-v2/java-sdk/faq/5/40.md new file mode 100644 index 000000000000..fa0b09608a2b --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/5/40.md @@ -0,0 +1,17 @@ +--- +type: docs +title: "5-40 - Dubbo configuration bean not found" +linkTitle: "5-40 - Dubbo configuration bean not found" +weight: 40 +--- + +## possible reason + +source code or modified + +## Troubleshooting and resolution steps + +Check that the business code does not modify the source code or load sequence of the core class. +Such as: org.apache.dubbo.config.spring.context.DubboConfigBeanInitializer + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/5/5.md b/content/en/docs3-v2/java-sdk/faq/5/5.md new file mode 100644 index 000000000000..96a2ba883963 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/5/5.md @@ -0,0 +1,16 @@ +--- +type: docs +title: "5-5 - Unable to get env variables" +linkTitle: "5-5 - Unable to get env variables" +weight: 5 +--- + +## possible reason + +Environment variable could not be obtained. + +## Troubleshooting and resolution steps + +Check the prompted variable name, whether it is configured and can be read and loaded normally. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/5/6.md b/content/en/docs3-v2/java-sdk/faq/5/6.md new file mode 100644 index 000000000000..fc16373e3ff3 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/5/6.md @@ -0,0 +1,16 @@ +--- +type: docs +title: "5-6 - Attribute Conflict of Interface Type" +linkTitle: "5-6 - Attribute Conflict of Interface Type" +weight: 6 +--- + +## possible reason + +The generalization definition is not configured correctly. + +## Troubleshooting and resolution steps + +Check that the generalization definition is correct. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/5/7.md b/content/en/docs3-v2/java-sdk/faq/5/7.md new file mode 100644 index 000000000000..e1fed2dabfc6 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/5/7.md @@ -0,0 +1,20 @@ +--- +type: docs +title: "5-7 - An unexpected error occurred while canceling the export" +linkTitle: "5-7 - An unexpected error occurred while canceling the export" +weight: 7 +--- + +## possible reason + +1. The service of the configuration center cannot be connected. +2. The configured protocol, IP, and port are incorrect. +3. The client version of the configuration center conflicts with the server version, and a valid connection cannot be established. + +## Troubleshooting and resolution steps + +1. Check whether the service status of the configuration center is normal. +2. Check that the configured protocol, IP, and port are incorrect. +3. Check whether the version of the configuration center client used is compatible with the version of the server. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/5/8.md b/content/en/docs3-v2/java-sdk/faq/5/8.md new file mode 100644 index 000000000000..007b32e4539e --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/5/8.md @@ -0,0 +1,16 @@ +--- +type: docs +title: "5-8 - The protocol will use a random available port" +linkTitle: "5-8 - The protocol will use a random available port" +weight: 8 +--- + +## possible reason + +The port specified by the protocol is occupied, and the port is randomly selected for startup. + +## Troubleshooting and resolution steps + +Check whether the currently configured port is occupied by other applications. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/5/9.md b/content/en/docs3-v2/java-sdk/faq/5/9.md new file mode 100644 index 000000000000..13b2665cd4fd --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/5/9.md @@ -0,0 +1,20 @@ +--- +type: docs +title: "5-9 - Service Configuration Export Failed" +linkTitle: "5-9 - Service configuration export failed" +weight: 9 +--- + +## possible reason + +1. The service of the configuration center cannot be connected. +2. The configured protocol, IP, and port are incorrect. +3. The client version of the configuration center conflicts with the server version, and a valid connection cannot be established. + +## Troubleshooting and resolution steps + +1. Check whether the service status of the configuration center is normal. +2. Check that the configured protocol, IP, and port are incorrect. +3. Check whether the version of the configuration center client used is compatible with the version of the server. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/5/_index.md b/content/en/docs3-v2/java-sdk/faq/5/_index.md new file mode 100644 index 000000000000..7350301f1891 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/5/_index.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "5 - Config Center" +linkTitle: "5 - Config Center" +weight: 5 +--- \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/6/1.md b/content/en/docs3-v2/java-sdk/faq/6/1.md new file mode 100644 index 000000000000..1cdcca8790e2 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/6/1.md @@ -0,0 +1,18 @@ +--- +type: docs +title: "6-1 - Server Connection Failed" +linkTitle: "6-1 - Server connection failed" +weight: 1 +--- +Network communication layer, failed to connect to the service provider service + +## possible reason + +The service provider's network is abnormally disconnected or blocked by firewalls and third-party tools, and cannot provide external services. + +## Troubleshooting and resolution steps + +1. If it is a rest connection, check whether the requested server configuration is correct. +2. Check whether the network communication is normal, you can use some simple cmd commands to detect, such as `ping` and so on. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/6/10.md b/content/en/docs3-v2/java-sdk/faq/6/10.md new file mode 100644 index 000000000000..6aeb879f30a6 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/6/10.md @@ -0,0 +1,16 @@ +--- +type: docs +title: "6-10 - Payload Limit Exceeded Exception" +linkTitle: "6-10 - Payload Limit Exceeded Exception" +weight: 10 +--- +The default `payload=8M`, please check the configuration + +## possible reason + + +## Troubleshooting and resolution steps + +For the specific configuration items and meanings supported by each component, please refer to [Configuration Item Manual](/en/docs3-v2/java-sdk/reference-manual/config/properties/) + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/6/11.md b/content/en/docs3-v2/java-sdk/faq/6/11.md new file mode 100644 index 000000000000..ee213510a0e9 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/6/11.md @@ -0,0 +1,16 @@ +--- +type: docs +title: "6-11 - Character set not supported" +linkTitle: "6-11 - Character set not supported" +weight: 11 +--- +Default `UTF-8` charset + +## possible reason + + +## Troubleshooting and resolution steps + +The result will end up being processed in the `UTF-8` character set. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/6/12.md b/content/en/docs3-v2/java-sdk/faq/6/12.md new file mode 100644 index 000000000000..dca5d0d8a906 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/6/12.md @@ -0,0 +1,18 @@ +--- +type: docs +title: "6-12 - An error occurred when the ZK client was destroyed" +linkTitle: "6-12 - An error occurred when the ZK client was destroyed" +weight: 12 +--- + + +## possible reason + +The connection between the client and the server has been refused +When the client is being destroyed, the server may be performing elections or other operations, resulting in an exception. + +## Troubleshooting and resolution steps + +The shutdown method can be used to query stack information. Generally do not deal with. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/6/13.md b/content/en/docs3-v2/java-sdk/faq/6/13.md new file mode 100644 index 000000000000..d25c3ecddd5e --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/6/13.md @@ -0,0 +1,17 @@ +--- +type: docs +title: "6-13 - Stream closed exception" +linkTitle: "6-13 - Stream closed exception" +weight: 13 +--- + + +## possible reason + +`Stream is closed` or the stream is closed while other threads are reading + +## Troubleshooting and resolution steps + +Generally, the order in which the code closes the streams is reversed. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/6/14.md b/content/en/docs3-v2/java-sdk/faq/6/14.md new file mode 100644 index 000000000000..fb8be05966ff --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/6/14.md @@ -0,0 +1,16 @@ +--- +type: docs +title: "6-14 - Server response failed" +linkTitle: "6-14 - Server response failed" +weight: 14 +--- + +## possible reason + +When the server interacts with the client to generate data, the client closes abnormally. + +## Troubleshooting and resolution steps + +The client terminated abnormally or the server crashed. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/6/15.md b/content/en/docs3-v2/java-sdk/faq/6/15.md new file mode 100644 index 000000000000..9c34721388a8 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/6/15.md @@ -0,0 +1,15 @@ +--- +type: docs +title: "6-15 - Skip unread stream data" +linkTitle: "6-15 - Skip unread stream data" +weight: 15 +--- +When decoding, if there is unread data in the stream, the unread stream will be skipped + +## possible reason + +## Troubleshooting and resolution steps + +When decoding, all the data will be read at one time + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/6/16.md b/content/en/docs3-v2/java-sdk/faq/6/16.md new file mode 100644 index 000000000000..ed8c982cc746 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/6/16.md @@ -0,0 +1,17 @@ +--- +type: docs +title: "6-16 - An exception occurred during reconnection" +linkTitle: "6-16 - An exception occurred during reconnection" +weight: 16 +--- +Prompt every time a reconnection occurs + +## possible reason + +Delayed reconnection caused by network instability. + +## Troubleshooting and resolution steps + +Check for network packet loss. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/6/2.md b/content/en/docs3-v2/java-sdk/faq/6/2.md new file mode 100644 index 000000000000..da32deab14b7 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/6/2.md @@ -0,0 +1,27 @@ +--- +type: docs +title: "6-2 - Client Timeout" +linkTitle: "6-2 - Client Timeout" +weight: 2 +--- +Timeout occurs when the caller fails to obtain the corresponding response within the specified time after the request is sent. + +## possible reason +1. The server is really slow in processing and cannot return the result within the specified time. The caller will automatically return a timeout exception response to end the call. +2. If the server responds quickly, but when the client load is high and the load pressure is high, it will time out due to problems such as the client request not being sent out or the response stuck in the TCP Buffer. Because the client receives the data sent by the server or requests the data from the server, it will be queued at the system level. If the system load is relatively high, the time spent in the kernel state will increase, causing the client to time out when it gets the value. . +3. Usually the business processing is too slow, and it can be executed on the service provider machine: `jstack [PID] > jstack.log` to analyze which method calls the threads are stuck on, which is the reason for the slowness. If performance tuning is not an option, increase the timeout threshold. + + +## Troubleshooting and resolution steps + +1. There may be GC on both sides. Check the GC logs of the server and client. A GC that takes a long time will cause a timeout. The occurrence of a timeout probably means that the resource (CPU, memory, or network) of the caller or server has a bottleneck. It is necessary to check whether the problem is on the server or the caller to rule out suspicions such as GC jitter. +2. Check the network quality of the server, such as the retransmission rate to rule out network suspicions. +3. With the help of link tracking analysis services (such as Ali's [ARMS](https://help.aliyun.com/document_detail/63796.html), the open source [OpenTracing](https://github.com/opentracing/ opentracing-java) + System implementation [Zipkin](https://github.com/openzipkin/zipkin), [SkyWalking](https://github.com/apache/skywalking) etc.) to analyze the time-consuming situation of each point. + +## Acknowledgments +The FAQ page of this error code refers to ["Dubbo Common Errors and Solutions"](https://github.com/StabilityMan/StabilityGuide/blob/master/docs/diagnosis/plugin/rpc/%E7%B3%BB%E7%BB%9F%E7%A8%B3%E5%AE%9A%E6%80%A7%E2%80%94%E2%80%94Dubbo%E5%B8%B8%E8%A7%81%E9%94%99%E8%AF%AF%E5%8F%8A%E8%A7%A3%E5%86%B3%E6%96%B9%E6%B3%95.md). + +Articles cited are compiled under license [CC-BY-4.0](http://creativecommons.org/licenses/by/4.0/). Thanks to the original author here. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/6/3.md b/content/en/docs3-v2/java-sdk/faq/6/3.md new file mode 100644 index 000000000000..c59731aab5b1 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/6/3.md @@ -0,0 +1,17 @@ +--- +type: docs +title: "6-3 - Failed to close network connection" +linkTitle: "6-3 - Failed to close the network connection" +weight: 3 +--- +Network connection close failed + +## possible reason + +Non-graceful shutdown of the service. At this time, the server may not complete the external output stream. + +## Troubleshooting and resolution steps + +Generally, it is a prompt warning message, which does not affect subsequent program execution. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/6/4.md b/content/en/docs3-v2/java-sdk/faq/6/4.md new file mode 100644 index 000000000000..9f1e918155bd --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/6/4.md @@ -0,0 +1,19 @@ +--- +type: docs +title: "6-4 - Network communication layer unknown exception" +linkTitle: "6-4 - Unknown exception in the network communication layer" +weight: 4 +--- +Common exception codes in the network communication layer + +## possible reason + +Generally, it is due to configuration item errors or network reasons + +## Troubleshooting and resolution steps + +You can use some third-party tools or `jstack [PID] > jstack.log` to analyze the stack information and locate it. + +For the specific configuration items and meanings supported by each component, please refer to [Configuration Item Manual](/en/docs3-v2/java-sdk/reference-manual/config/properties/) + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/6/5.md b/content/en/docs3-v2/java-sdk/faq/6/5.md new file mode 100644 index 000000000000..7416bad390a4 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/6/5.md @@ -0,0 +1,17 @@ +--- +type: docs +title: "6-5 - Network disconnection failed" +linkTitle: "6-5 - Network disconnection failed" +weight: 5 +--- +Timeout occurs when the caller fails to obtain the corresponding response within the specified time after the request is sent. + +## possible reason + +Client actively disconnects + +## Troubleshooting and resolution steps + +Generally, it is a prompt warning message, which does not affect subsequent program execution. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/6/6.md b/content/en/docs3-v2/java-sdk/faq/6/6.md new file mode 100644 index 000000000000..5fa61c299dd8 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/6/6.md @@ -0,0 +1,19 @@ +--- +type: docs +title: "6-6 - Unsupported message" +linkTitle: "6-6 - Unsupported message" +weight: 6 +--- + + +## possible reason + +The returned data is serialized incorrectly, or exceeds the serialization maximum + +## Troubleshooting and resolution steps + +You can use some third-party tools or `jstack [PID] > jstack.log` to analyze the stack information and locate it. + +For the specific configuration items and meanings supported by each component, please refer to [Configuration Item Manual](/en/docs3-v2/java-sdk/reference-manual/config/properties/) + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/6/7.md b/content/en/docs3-v2/java-sdk/faq/6/7.md new file mode 100644 index 000000000000..f0a130742948 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/6/7.md @@ -0,0 +1,17 @@ +--- +type: docs +title: "6-7 - Thread Connection Exceeded Warning" +linkTitle: "6-7 - Server connection failed" +weight: 7 +--- +Reminder message when the number of connections exceeds the limit + +## possible reason + +A warning reminder that the configuration or the number of connections exceeds the configured number. + +## Troubleshooting and resolution steps + +The default configuration item `connect.queue.warning.size=1000` can be adjusted through configuration. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/6/8.md b/content/en/docs3-v2/java-sdk/faq/6/8.md new file mode 100644 index 000000000000..95dd2fd190f5 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/6/8.md @@ -0,0 +1,17 @@ +--- +type: docs +title: "6-8 - Return data decoding failed" +linkTitle: "6-8 - Return data decoding failed" +weight: 8 +--- + + +## possible reason + +Return data format error or decoding failed + +## Troubleshooting and resolution steps + +Through the debug/warn log mode, the specific service class name and the returned message and stack information can be output. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/6/9.md b/content/en/docs3-v2/java-sdk/faq/6/9.md new file mode 100644 index 000000000000..3fa17b042ab0 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/6/9.md @@ -0,0 +1,20 @@ +--- +type: docs +title: "6-9 - There are duplicate serial number IDs" +linkTitle: "6-9 - Server connection failed" +weight: 9 +--- + + +## possible reason + +1. An empty object is returned. +2. The custom serial number class, `org.apache.dubbo.common.serialize.Serialization#getContentTypeId` is duplicated with the built-in system, + At this time, when loading, the first loaded SPI instance shall prevail. Other items will be skipped. + +## Troubleshooting and resolution steps + +1. Check the return result. +2. The built-in value can refer to the class `org.apache.dubbo.common.serialize.Constants` + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/6/_index.md b/content/en/docs3-v2/java-sdk/faq/6/_index.md new file mode 100644 index 000000000000..9757a07c6690 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/6/_index.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "6 - Transport" +linkTitle: "6 - Transport" +weight: 6 +--- \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/7/1.md b/content/en/docs3-v2/java-sdk/faq/7/1.md new file mode 100644 index 000000000000..46a3dc2a95dc --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/7/1.md @@ -0,0 +1,16 @@ +--- +type: docs +title: "7-1 - QOS OFF" +linkTitle: "7-1 - QOS is off" +weight: 1 +--- + +## possible reason + +QOS is off + +## Troubleshooting and resolution steps + + +Please refer to [QOS Operation Manual](/en/docs3-v2/java-sdk/reference-manual/qos/). +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/7/2.md b/content/en/docs3-v2/java-sdk/faq/7/2.md new file mode 100644 index 000000000000..57e85e847776 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/7/2.md @@ -0,0 +1,16 @@ +--- +type: docs +title: "7-2 - QOS is on" +linkTitle: "7-2 - QOS is on" +weight: 2 +--- + +## possible reason + +QOS is enabled, and it is enabled by default. + +## Troubleshooting and resolution steps + + +Please refer to [QOS Operation Manual](/en/docs3-v2/java-sdk/reference-manual/qos/). +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/7/3.md b/content/en/docs3-v2/java-sdk/faq/7/3.md new file mode 100644 index 000000000000..ff3629e68cc0 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/7/3.md @@ -0,0 +1,16 @@ +--- +type: docs +title: "7-3 - Set warning percentage value for timeout" +linkTitle: "7-3 - Set warning percentage value for timeout" +weight: 3 +--- + +## possible reason + +The warning percentage value of QOS setting timeout time, the default is 0.75. After modification, the console prints this message. + +## Troubleshooting and resolution steps + + +Please refer to QOS Operation Manual [Performance Sampling Command](/en/docs3-v2/java-sdk/reference-manual/qos/profiler/). +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/7/4.md b/content/en/docs3-v2/java-sdk/faq/7/4.md new file mode 100644 index 000000000000..5e7bb6f298b1 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/7/4.md @@ -0,0 +1,16 @@ +--- +type: docs +title: "7-4 - QOS service failed to start" +linkTitle: "7-4 - QOS service failed to start" +weight: 4 +--- + +## possible reason + +The QOS parameter value is not set correctly. The main parameters are `qos.host` and `qos.port` + +## Troubleshooting and resolution steps + + +Please refer to the QOS Operation Manual [QOS Overview](/en/docs3-v2/java-sdk/reference-manual/qos/overview/). +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/7/5.md b/content/en/docs3-v2/java-sdk/faq/7/5.md new file mode 100644 index 000000000000..e03f919041f4 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/7/5.md @@ -0,0 +1,17 @@ +--- +type: docs +title: "7-5 - QOS command not found" +linkTitle: "7-5 - QOS command not found" +weight: 5 +--- + +## possible reason + +1. The QOS command is misspelled. + +## Troubleshooting and resolution steps + +1. QOS command does not exist. + +Please refer to QOS Operation Manual [Basic Command Manual](/en/docs3-v2/java-sdk/reference-manual/qos/command/). +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/7/6.md b/content/en/docs3-v2/java-sdk/faq/7/6.md new file mode 100644 index 000000000000..75be8dd3e84c --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/7/6.md @@ -0,0 +1,18 @@ +--- +type: docs +title: "7-6 - Unknown exception occurred in QOS" +linkTitle: "7-6 - Unknown exception occurred in QOS" +weight: 6 +--- + +## possible reason + +1. An unknown exception occurred in QOS + +## Troubleshooting and resolution steps + +1. Check whether the currently requested service can be accessed normally. +2. Perhaps for some reason, the `CommandContext` instance was not properly loaded or returned. You can troubleshoot and locate according to the error reminder information on the console. + + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/7/7.md b/content/en/docs3-v2/java-sdk/faq/7/7.md new file mode 100644 index 000000000000..888ff12f167c --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/7/7.md @@ -0,0 +1,17 @@ +--- +type: docs +title: "7-7 - QOS Unprivileged Access" +linkTitle: "7-7 - QOS Unprivileged Access" +weight: 7 +--- + +## possible reason + +This QoS request does not have permission to access the corresponding resources, which usually occurs in a malicious attack scenario + +## Troubleshooting and resolution steps + +Check whether the request is expected, if not, please check whether there is a malicious attack source, +If it is expected, please refer to [QoS Security](/en/docs3-v2/java-sdk/reference-manual/qos/overview/#safety) to configure the corresponding permission information . + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/7/_index.md b/content/en/docs3-v2/java-sdk/faq/7/_index.md new file mode 100644 index 000000000000..6f1fd4fd0450 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/7/_index.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "7 - QoS" +linkTitle: "7 - QoS" +weight: 7 +--- \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/99/0.md b/content/en/docs3-v2/java-sdk/faq/99/0.md new file mode 100644 index 000000000000..ba0c58f7131a --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/99/0.md @@ -0,0 +1,16 @@ +--- +type: docs +title: "99-0 - Internal Unknown Error" +linkTitle: "99-0 - Internal unknown error" +weight: 0 +--- +Unknown error inside Dubbo. + +### possible reason +unknown mistake +### Troubleshooting and resolution steps +1. Protect the site. Save the log file, and record as much as possible the situation at the time of the failure. +2. If there are other error code log records before this error code, please check the record of that error code first. +3. Check whether the configuration file is correct. +4. If the error was introduced by modifying the code, try to roll back to the previous version. +5. If nothing is resolved, please make a minimal demo that reproduces the problem as much as possible, and then issue an issue to [GitHub Issue Tracker](https://github.com/apache/dubbo/issues). \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/99/1.md b/content/en/docs3-v2/java-sdk/faq/99/1.md new file mode 100644 index 000000000000..85630c352ca7 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/99/1.md @@ -0,0 +1,17 @@ +--- +type: docs +title: "99-1 - Program Interrupted" +linkTitle: "99-1 - Program interrupted" +weight: 1 +--- +Unknown error inside Dubbo. + +### possible reason + +The program receives an interrupt notification from the JVM level and is forced to stop blocking and waiting + +### Troubleshooting and resolution steps + +This exception usually occurs when the thread pool is closed or the application is closed. +Please check whether the normal use of the business is affected. If there is no impact, it can be ignored. If there is an impact, please refer to the corresponding troubleshooting manual. +For more troubleshooting ideas, please refer to [90-0](../0/). \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/99/_index.md b/content/en/docs3-v2/java-sdk/faq/99/_index.md new file mode 100644 index 000000000000..06eb93998d84 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/99/_index.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "99 - Unknown" +linkTitle: "99 - Unknown" +weight: 99 +--- \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/_index.md b/content/en/docs3-v2/java-sdk/faq/_index.md new file mode 100755 index 000000000000..238089b95528 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/_index.md @@ -0,0 +1,9 @@ + +--- +type: docs +title: "FAQ" +linkTitle: "FAQ" +weight: 7 +--- + +The main purpose here is to provide the possible causes and solutions of various error codes in the Java SDK. \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/faq/intro.md b/content/en/docs3-v2/java-sdk/faq/intro.md new file mode 100644 index 000000000000..a60ae7ec0354 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/faq/intro.md @@ -0,0 +1,40 @@ +--- +type: docs +title: "Introduction to Error Code Mechanism" +linkTitle: "Introduction to Error Code Mechanism" +weight: 0 +--- + +## background +The Logger abstraction layer that Dubbo relies on internally provides log output capabilities, but most of the exception logs do not come with troubleshooting instructions, resulting in users being unable to handle the exception after seeing it. + +In order to solve this problem, since Dubbo version 3.1, an error code mechanism has been introduced. It connects the error code FAQ in the official documentation with the logging framework. When the abstract output of the log is abnormal, a link to the official website document corresponding to the output is attached to guide the user to conduct independent investigation. + +## Error code format +`[Cat]-[X]` + +Both spaces are numbers. The first number is the category, and the second number is the specific error code. + +## The format of the prompt display +``` +This may be caused by ..., go to https://dubbo.apache.org/faq/[Cat]/[X] to find instructions. +``` +In addition, supplementary information (ie extendedInformation) can be specified after this sentence. + +## Displayed examples +`[31/07/22 02:43:07:796 CST] main WARN support.AbortPolicyWithReport: [DUBBO] Thread pool is EXHAUSTED! Thread Name: Test, Pool Size: 0 (active: 0, core: 1, max: 1, largest: 0), Task: 0 (completed: 0), Executor status:(isShutdown:false, isTerminated:false, isTerminating:false), in dubbo://10.20.130.230:20880!, dubbo version: , current host: 10.20.130.230, error code: 0-1. This may be caused by too much client requesting provider, go to https://dubbo.apache.org/faq/0/1 to find instructions.` + +Users only need to click on the link to find the reason according to the error code. + +## Logger interface support +To ensure compatibility, Dubbo 3.1 builds a new interface `ErrorTypeAwareLogger` based on the original Logger abstraction. It extends the method of warn level as follows: +``` +void warn(String code, String cause, String extendedInformation, String msg); +void warn(String code, String cause, String extendedInformation, String msg, Throwable e); +``` + +Among them, code refers to the error code, cause refers to the possible reason (that is, the text followed by caused by...), extendedInformation is used as supplementary information, and is directly attached to the sentence caused by. + +The same extension is done for the error level. + +

\ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/quick-start/_index.md b/content/en/docs3-v2/java-sdk/quick-start/_index.md new file mode 100755 index 000000000000..070e342d1592 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/quick-start/_index.md @@ -0,0 +1,8 @@ + +--- +type: docs +title: "Quick Start" +linkTitle: "Quick Start" +weight: 2 +description: "" +--- diff --git a/content/en/docs3-v2/java-sdk/quick-start/idl.md b/content/en/docs3-v2/java-sdk/quick-start/idl.md new file mode 100755 index 000000000000..45df435c4789 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/quick-start/idl.md @@ -0,0 +1,232 @@ +--- +type: docs +title: "IDL defines cross-language services" +linkTitle: "IDL Defines" +weight: 2 +description: "Demo from zero how to define Dubbo service based on IDL and use Triple protocol" +--- + +Using IDL to define services has better cross-language friendliness. For new users of Dubbo3, we recommend this method. +However, the Triple protocol is not strongly bound to IDL. You can also use Java Interface + Pojo to define services and enable the Triple protocol. For details, see [Example](https://github.com/apache/dubbo-samples/tree/master/3-extensions/protocol/dubbo-samples-triple/src/main/java/org/apache/dubbo/sample/tri/pojo). + +For more usage of Triple and IDL, please refer to [official samples](https://github.com/apache/dubbo-samples/tree/master/3-extensions/protocol/dubbo-samples-triple) + +### precondition +- [JDK](https://jdk.java.net/) version >= 8 +- Installed [Maven](https://maven.apache.org/) + +### Create project +1. First create an empty maven project + ``` + $ mvn archetype:generate \ + -DgroupId=org.apache.dubbo \ + -DartifactId=tri-stub-demo \ + -DarchetypeArtifactId=maven-archetype-quickstart \ + -DarchetypeVersion=1.4 \ + -DarchetypeGroupId=org.apache.maven.archetypes \ + -Dversion=1.0-SNAPSHOT + ``` +2. Switch to the project directory + ``` + $ cd tri-stub-demo + ``` +3. Set JDK version in `pom.xml`, add Dubbo dependencies and plugins + ```xml + + UTF-8 + 1.8 + 1.8 + + + + + junit + junit + 4.13 + test + + + org.apache.dubbo + dubbo + 3.0.8 + + + org.apache.dubbo + dubbo-dependencies-zookeeper-curator5 + pom + 3.0.8 + + + com.google.protobuf + protobuf-java + 3.19.4 + + + + + + + kr.motd.maven + os-maven-plugin + 1.6.1 + + + + + org.xolstice.maven.plugins + protobuf-maven-plugin + 0.6.1 + + com.google.protobuf:protoc:3.19.4:exe:${os.detected.classifier} + + + dubbo + org.apache.dubbo + dubbo-compiler + 0.0.4.1-SNAPSHOT + org.apache.dubbo.gen.tri.Dubbo3TripleGenerator + + + + + + + compile + + + + + + + ``` +4. Add the interface definition file `src/main/proto/hello.proto`, Dubbo uses [Protobuf](https://developers.google.com/protocol-buffers) as IDL + ```protobuf + syntax = "proto3"; + + option java_multiple_files = true; + option java_package = "org.apache.dubbo.hello"; + option java_outer_classname = "HelloWorldProto"; + option objc_class_prefix = "HLW"; + + package helloworld; + + message HelloRequest { + string name = 1; + } + + message HelloReply { + string message = 1; + } + service Greeter{ + rpc greet(HelloRequest) returns (HelloReply); + } + + ``` +5. Compile the IDL + ``` + $ mvn clean install + ``` + After the compilation is successful, you can see that the code file is generated in the `target/generated-sources/protobuf/java` directory + ``` + $ ls org/apache/dubbo/hello/ + DubboGreeterTriple.java HelloReply.java HelloRequest.java HelloWorldProto.java + Greeter.java HelloReplyOrBuilder.java HelloRequestOrBuilder.java + ``` + +6. Add server interface implementation `src/main/java/org/apache/dubbo/GreeterImpl.java` + ```java + package org.apache.dubbo; + + import org.apache.dubbo.hello.DubboGreeterTriple; + import org.apache.dubbo.hello.HelloReply; + import org.apache.dubbo.hello.HelloRequest; + + public class GreeterImpl extends DubboGreeterTriple. GreeterImplBase { + @Override + public HelloReply greet(HelloRequest request) { + return HelloReply. newBuilder() + .setMessage("Hello," + request.getName() + "!") + .build(); + } + } + ``` +7. Add server startup class `src/main/java/org/apache/dubbo/MyDubboServer.java` + ```java + package org.apache.dubbo; + + import org.apache.dubbo.common.constants.CommonConstants; + import org.apache.dubbo.config.ApplicationConfig; + import org.apache.dubbo.config.ProtocolConfig; + import org.apache.dubbo.config.RegistryConfig; + import org.apache.dubbo.config.ServiceConfig; + import org.apache.dubbo.config.bootstrap.DubboBootstrap; + import org.apache.dubbo.hello.Greeter; + + import java.io.IOException; + + public class MyDubboServer { + + public static void main(String[] args) throws IOException { + ServiceConfig service = new ServiceConfig<>(); + service.setInterface(Greeter.class); + service.setRef(new GreeterImpl()); + + DubboBootstrap bootstrap = DubboBootstrap. getInstance(); + bootstrap. application(new ApplicationConfig("tri-stub-server")) + .registry(new RegistryConfig("multicast://127.0.0.1:2181")) + .protocol(new ProtocolConfig(CommonConstants.TRIPLE, 50051)) + .service(service) + .start(); + System.out.println("Dubbo triple stub server started"); + System.in.read(); + } + } + ``` + +8. Add the client startup class `src/main/java/org/apache/dubbo/MyDubboClient.java` + ```java + package org.apache.dubbo; + + import org.apache.dubbo.common.constants.CommonConstants; + import org.apache.dubbo.config.ApplicationConfig; + import org.apache.dubbo.config.ReferenceConfig; + import org.apache.dubbo.config.RegistryConfig; + import org.apache.dubbo.config.bootstrap.DubboBootstrap; + import org.apache.dubbo.hello.Greeter; + import org.apache.dubbo.hello.HelloReply; + import org.apache.dubbo.hello.HelloRequest; + + public class MyDubboClient { + public static void main(String[] args) { + DubboBootstrap bootstrap = DubboBootstrap. getInstance(); + ReferenceConfig ref = new ReferenceConfig<>(); + ref. setInterface(Greeter. class); + ref.setProtocol(CommonConstants.TRIPLE); + ref.setProxy(CommonConstants.NATIVE_STUB); + ref. setTimeout(3000); + bootstrap. application(new ApplicationConfig("tri-stub-client")) + .registry(new RegistryConfig("zookeeper://127.0.0.1:2181")) + .reference(ref) + .start(); + + Greeter greeter = ref. get(); + HelloRequest request = HelloRequest.newBuilder().setName("Demo").build(); + HelloReply reply = greeter. greet(request); + System.out.println("Received reply:" + reply); + } + } + ``` +9. Compile the code + ``` + $ mvn clean install + ``` +10. Start the server + ``` + $ mvn org.codehaus.mojo:exec-maven-plugin:3.0.0:java -Dexec.mainClass="org.apache.dubbo.MyDubboServer" + Dubbo triple stub server started + ``` +11. Open a new terminal and start the client + ``` + $ mvn org.codehaus.mojo:exec-maven-plugin:3.0.0:java -Dexec.mainClass="org.apache.dubbo.MyDubboClient" + Received reply: message: "Hello, Demo!" + ``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/quick-start/spring-boot.md b/content/en/docs3-v2/java-sdk/quick-start/spring-boot.md new file mode 100755 index 000000000000..03a28be04d6e --- /dev/null +++ b/content/en/docs3-v2/java-sdk/quick-start/spring-boot.md @@ -0,0 +1,183 @@ +--- +type: docs +title: "Spring Boot Development Services" +linkTitle: "Spring Boot" +weight: 1 +description: "The sample demonstrates how to use Spring Boot to quickly develop Dubbo applications." +--- + +> Dubbo also provides a variety of startup and access including [XML](../../reference-manual/config/xml), [API](../../reference-manual/config/api) For more development methods and configuration details, please refer to [Configuration Manual](../../reference-manual/config/). + +## Download sample code +The complete sample code is in [dubbo-samples](https://github.com/apache/dubbo-samples/tree/master/1-basic/dubbo-samples-spring-boot). + +1. Download the source code +```shell script +git clone -b master https://github.com/apache/dubbo-samples.git +``` +2. Enter the example directory +```shell script +cd dubbo-samples/1-basic/dubbo-samples-spring-boot +ls # view directory structure +``` + +## Quick run example + +1. Compile Provider + Execute the maven command in the dubbo-samples-spring-boot directory +```shell script +mvn clean package +``` + +2. Run Provider + Enter the dubbo-samples-spring-boot-provider/target directory and start the java process +```shell script +cd ./dubbo-samples-spring-boot-provider +java -jar ./target/dubbo-samples-spring-boot-provider-1.0-SNAPSHOT.jar +``` + +3. Run the consumer + Enter the dubbo-samples-spring-boot-consumer directory and start the java process +```shell script +java -jar ./target/dubbo-samples-spring-boot-consumer-1.0-SNAPSHOT.jar +``` + +4. View the results + The following information will be output on the consumer side: +``` +result: hello world +``` +On the provider side, the following information will be output: +``` +Hello World, request from consumer: xxx.xxx.xxx.xxx +``` + +So far, the basic functions of Dubbo have been realized, and more development can be carried out on the basis of Dubbo. + +## Example core process + +For a more detailed interpretation of the examples, please refer to [Annotation Configuration](../../reference-manual/config/annotation/) + +### 1. Define service interface + +dubbo-samples-spring-boot-interface/DemoService.java + +```java +package org.apache.dubbo.samples.basic.api; + +public interface DemoService { + String sayHello(String name); +} +``` + +### 2. The provider implements the interface and exposes the service + +dubbo-samples-spring-boot-provider/DemoServiceImpl.java + +```java +@DubboService +public class DemoServiceImpl implements DemoService { + @Override + public String sayHello(String name) { + System.out.println("Hello " + name + ", request from consumer: " + RpcContext.getContext().getRemoteAddress()); + return "Hello " + name; + } +} +``` + +### 3. Configure the application.yml file + +dubbo-samples-spring-boot-provider/resources/application.yml + +```yaml +dubbo: + application: + name: dubbo-springboot-demo-provider + protocol: + name: dubbo + port: -1 + registry: + id: zk-registry + address: zookeeper://127.0.0.1:2181 + config-center: + address: zookeeper://127.0.0.1:2181 + metadata-report: + address: zookeeper://127.0.0.1:2181 +``` + +### 4. Define Spring Boot main function + +dubbo-samples-spring-boot-provider/ProviderApplication.java + +```java +@SpringBootApplication +@EnableDubbo +public class ProviderApplication { + public static void main(String[] args) throws Exception { + new Embedded ZooKeeper(2181, false).start(); + + SpringApplication.run(ProviderApplication.class, args); + System.out.println("dubbo service started"); + new CountDownLatch(1). await(); + } +} +``` +Among them, `@EnableDubbo` must be configured. + +### 5. Reference remote service + +dubbo-samples-spring-boot-consumer/ConsumerApplication.java + +```java +public class ConsumerApplication { + @DubboReference + private DemoService demoService; +} +``` + +### 6. Define application.yml + +dubbo-samples-spring-boot-consumer/application.yml + +```yaml +dubbo: + application: + name: dubbo-springboot-demo-consumer + protocol: + name: dubbo + port: -1 + registry: + id: zk-registry + address: zookeeper://127.0.0.1:2181 + config-center: + address: zookeeper://127.0.0.1:2181 + metadata-report: + address: zookeeper://127.0.0.1:2181 +``` + +### 7. Load Spring configuration and call remote service + +dubbo-samples-spring-boot-consumer/ConsumerApplication.java + +```java +@SpringBootApplication +@Service +@EnableDubbo +public class ConsumerApplication { + @DubboReference + private DemoService demoService; + + public String doSayHello(String name) { + return demoService.sayHello(name); + } + + public static void main(String[] args) { + ConfigurableApplicationContext context = SpringApplication.run(ConsumerApplication.class, args); + ConsumerApplication application = context. getBean(ConsumerApplication. class); + String result = application. doSayHello("world"); + System.out.println("result: " + result); + } +} +``` + +Among them, `@EnableDubbo` must be configured. \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/_index.md b/content/en/docs3-v2/java-sdk/reference-manual/_index.md new file mode 100755 index 000000000000..056f3032b615 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/_index.md @@ -0,0 +1,8 @@ + +--- +type: docs +title: "Reference Manual" +linkTitle: "Reference Manual" +weight: 5 +--- + diff --git a/content/en/docs3-v2/java-sdk/reference-manual/config-center/_index.md b/content/en/docs3-v2/java-sdk/reference-manual/config-center/_index.md new file mode 100644 index 000000000000..c4b367820feb --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/config-center/_index.md @@ -0,0 +1,22 @@ +--- +type: docs +title: "Configuration Center" +linkTitle: "Configuration Center" +weight: 7 +description: "" +--- + +The configuration center (config-center) can undertake two types of responsibilities in Dubbo: + +1. [Externalized configuration](../config/principle/#33-externalized configuration): Centralized storage of startup configuration (simply understood as externalized storage of dubbo.properties). +2. Storage of traffic governance rules + +Please refer to the specific extension implementation to learn how to enable the configuration center. + +It is worth noting that the Dubbo dynamic configuration center defines two different levels of isolation options, namely namespce and group. +* namespace - configuration namespace, the default value is `dubbo`. Namespaces are usually used for multi-tenant isolation, that is, to logically isolate different users, different environments, or a series of configurations that are completely unrelated. The point of difference from physical isolation is whether different namespaces are used or the same physical cluster. +* group - configuration grouping, default value `dubbo`. `group` is usually used to classify a group of configuration items of the same type/purpose, which is a further isolation of configuration items under `namespace`. + +Refer to [Configuration Instructions - Configuration Item Manual](../config/properties/#config-center) for more configuration items opened by config-center other than namespce and group. + +> In order to be compatible with the 2.6.x version configuration, when Zookeeper is used as the registration center and the configuration center is not displayed, the Dubbo framework will use this Zookeeper as the configuration center by default, but it will only be used for service governance. \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/config-center/apollo.md b/content/en/docs3-v2/java-sdk/reference-manual/config-center/apollo.md new file mode 100644 index 000000000000..407a6e834ae9 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/config-center/apollo.md @@ -0,0 +1,115 @@ +--- +type: docs +title: "Apollo" +linkTitle: "Apollo" +weight: 4 +description: "The basic usage and working principle of Apollo Configuration Center." +--- + +## 1 precondition +* Understand [Dubbo basic development steps](../../../quick-start/spring-boot/) +* Install and start [Apollo](https://www.apolloconfig.com/#/zh/README) + +## 2 Instructions for use +Check here [full sample code](https://github.com/apache/dubbo-samples/tree/master/3-extensions/configcenter/dubbo-samples-configcenter-apollo) + +### 2.1 Add Maven dependency + +```xml + + org.apache.dubbo + dubbo + 3.0.9 + + + com.ctrip.framework.apollo + apollo-openapi + 2.0.0 + + + com.ctrip.framework.apollo + apollo-client + 2.0.0 + +``` + +### 2.2 Enable Apollo Configuration Center +```xml + +``` + +or + +```yaml +dubbo + config-center + address: apollo://localhost:8080 +``` + +or + +```properties +dubbo.config-center.address=apollo://localhost:8080 +``` + +or + +```java +ConfigCenterConfig configCenter = new ConfigCenterConfig(); +configCenter.setAddress("apollo://localhost:8080"); +``` + +## 3 Advanced configuration +A core concept in Apollo is the namespace - namespace, which is different from the namespace concepts of Zookeeper and Nacos above, so the usage method is also special. It is recommended to read the following documents after fully understanding the usage of Apollo itself. + +But in general, for the adaptation of Apollo: +* namespace is specially used for isolation of traffic governance rules, see 3.1 +* group is specially used for isolation of externalized configuration, see 3.2 + +### 3.1 External configuration + +```xml + +``` + +The `group` of config-center determines where Apollo reads the externalized configuration `dubbo.properties` file: +1. If the group is empty, the configuration will be read from the `dubbo` namespace by default, and the user must write the externalized configuration under the `dubbo` namespace. +2. If group is not empty + 2.1 If the group value is the application name, the configuration is read from the current namespace of the application, and the user must write the externalized configuration under the default namespace of the application automatically designated by Apollo. + 2.2 If the group value is any value, the configuration is read from the corresponding namespace, and the user must write the externalized configuration under the namespace. + +For example, the following example uses the default global externalization configuration of group='dubbo', that is, the configuration can be read by all applications. +![apollo-configcenter-dubbo.png](/imgs/user/apollo-configcenter-dubbo.png) + +If the configuration group='application name' is an application-specific configuration, only this application can read it. + +> Regarding externalized file configuration hosting, it is equivalent to storing the contents of the `dubbo.properties` configuration file in Apollo. Each application can inherit the public configuration by associating with the shared `dubbo` namespace, and then can override individual configuration items individually. + +### 3.2 Traffic Governance Rules +**Traffic governance rules must be shared globally, so the namespace configuration in each application should be consistent. ** + +```xml + +``` + +The `namespace` of config-center determines where Apollo accesses `traffic governance rules`: +1. If the namespace is empty, the configuration will be accessed from the `dubbo` namespace by default, and the governance rules must be written under the `dubbo` namespace. +2. If the namespace is not empty, read the rules from the corresponding namespace value, and the governance rules must be written under this namespace. + +For example, the following example puts the traffic governance rules under the `governance` namespace through `namespace='governance'`. +![apollo-configcenter-governance-dubbo.png](/imgs/user/apollo-configcenter-governance-dubbo.png) + +### 3.3 More Apollo-specific configurations +Currently Dubbo is adapted to env, apollo.meta, apollo.cluster, apollo.id and other unique configuration items, which can be configured through the extended parameters of config-center. + +Such as +```properties +dubbo.config-center.address=apollo://localhost:8080 +``` + +or + +```properties +dubbo.config-center.prameters.apollo.meta=xxx +dubbo.config-center.prameters.env=xxx +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/config-center/nacos.md b/content/en/docs3-v2/java-sdk/reference-manual/config-center/nacos.md new file mode 100644 index 000000000000..71bccf8e5d29 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/config-center/nacos.md @@ -0,0 +1,112 @@ +--- +type: docs +title: "Nacos" +linkTitle: "Nacos" +weight: 3 +description: "The basic usage and working principle of Nacos Configuration Center." +--- + +## 1 precondition +* Understand [Dubbo basic development steps](../../../quick-start/spring-boot/) +* Install and start [Nacos](https://nacos.io/zh-cn/docs/quick-start.html) +> When Dubbo uses `3.0.0` and above, it needs to use Nacos `2.0.0` and above. + +## 2 Instructions for use + +### 2.1 Add Maven dependency +If the project has enabled Nacos as the registration center, no additional configuration is required. + +If the Nacos registry is not enabled, please refer to [Adding Nacos dependencies to the registry](../../registry/nacos/#21-Add dependencies). + +### 2.2 Enable Nacos Configuration Center +```xml + +``` + +or + +```yaml +dubbo + config-center + address: nacos://127.0.0.1:8848 +``` + +or + +```properties +dubbo.config-center.address=nacos://127.0.0.1:8848 +``` + +or + +```java +ConfigCenterConfig configCenter = new ConfigCenterConfig(); +configCenter.setAddress("nacos://127.0.0.1:8848"); +``` + +For `address` format, please refer to [Nacos Registry - Enable Configuration](../../registry/nacos/#22-configure and enable-nacos) + +## 3 Advanced configuration +To enable authentication authentication, please refer to [Nacos Registry - Enable Authentication Authentication](../../registry/nacos/#31-authentication) + +### 3.1 External configuration +#### 3.1.1 Global externalization configuration +**1. The application opens config-center configuration** +```yaml +dubbo + config-center + address: nacos://127.0.0.1:2181 + config-file: dubbo.properties # optional +``` +`config-file` - global externalized configuration file key value, default `dubbo.properties`. `config-file` represents the key value corresponding to the file in the configuration center when the Dubbo configuration file is stored in the remote registration center, and it is generally not recommended to modify this configuration item. + +**2. Add configuration to Nacos Server** + +![nacos-configcenter-global-properties.png](/imgs/user/nacos-configcenter-global-properties.png) + +dataId is `dubbo.properties`, group grouping is consistent with config-center, if not set, `dubbo` will be filled by default. + +#### 3.1.2 Application-specific externalization configuration + +**1. The application opens config-center configuration** +```yaml +dubbo + config-center + address: nacos://127.0.0.1:2181 + app-config-file: dubbo.properties # optional +``` + +`app-config-file` - The current application-specific externalization configuration file key value, such as `app-name-dubbo.properties`, only configured when it needs to override the global externalization configuration file `config-file`. + +**2. Add configuration to Nacos Server** + +![nacos-configcenter-application-properties.png](/imgs/user/nacos-configcenter-application-properties.png) + +The dataId is `dubbo.properties`, and the group is set to the application name, namely `demo-provider`. + +### 3.2 Set group and namespace +```yaml +dubbo + config-center + address: zookeeper://127.0.0.1:2181 + group: dubbo-cluster1 + namespace: dev1 +``` + +For the configuration center, `group` and `namespace` should be unified across the company (cluster), and different applications should be prevented from using different values. + +### 3.3 Nacos extended configuration +For more parameter configurations supported by Nacos sdk/server, please refer to [Nacos Registry - More Configurations](../../registry/nacos/#35-More Configurations) + +## 4 Traffic Governance Rules +For Nacos, all traffic governance rules and external configurations should be globally visible, so applications in the same logical cluster must use the same namespace and group. Among them, the default value of namespace is `public`, and the default value of group is `dubbo`. The application should not modify the namespace and group without authorization, unless it can maintain global consistency. + +It is recommended to add, delete, and modify traffic governance rules through dubbo-admin. For more information, please refer to the traffic governance capabilities supported by Dubbo. + +![nacos-configcenter-governance.jpg](/imgs/user/nacos-configcenter-governance.png) + +There are many types of traffic governance rules, and the suffixes of dataId for different types of rules are different: + +- configurators, [override rules](../../../advanced-features-and-usage/traffic/config-rule/) +- tag-router, [tag routing](../../../advanced-features-and-usage/traffic/routing-rule/#tag routing rule) +- condition-router, [conditional routing](../../../advanced-features-and-usage/traffic/routing-rule/#conditional routing) \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/config-center/zookeeper.md b/content/en/docs3-v2/java-sdk/reference-manual/config-center/zookeeper.md new file mode 100644 index 000000000000..9249cd6aeca8 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/config-center/zookeeper.md @@ -0,0 +1,94 @@ +--- +type: docs +title: "Zookeeper" +linkTitle: "Zookeeper" +weight: 2 +description: "The basic usage and working principle of the Zookeeper configuration center." +--- + +## 1 precondition +* Understand [Dubbo basic development steps](../../../quick-start/spring-boot/) +* Install and start [Zookeeper](https://zookeeper.apache.org/) + +## 2 Instructions for use +View [full sample code](https://github.com/apache/dubbo-samples/tree/master/3-extensions/configcenter/dubbo-samples-configcenter-annotation) here + +### 2.1 Add Maven dependency +If the project has enabled Zookeeper as the registry, no additional configuration is required. + +If the Zookeeper registry is not used, please refer to [Add Zookeeper-related dependencies for the registry](../../registry/zookeeper/#21-add-maven-dependency). + +### 2.2 Enable Zookeeper Configuration Center +```xml + +``` + +or + +```yaml +dubbo + config-center + address: zookeeper://127.0.0.1:2181 +``` + +or + +```properties +dubbo.config-center.address=zookeeper://127.0.0.1:2181 +``` + +or + +```java +ConfigCenterConfig configCenter = new ConfigCenterConfig(); +configCenter.setAddress("zookeeper://127.0.0.1:2181"); +``` + +For `address` format, please refer to [zookeeper registry - enable configuration](../../registry/zookeeper/#22-configure and enable-zookeeper) + +## 3 Advanced configuration +To enable authentication, please refer to [zookeeper registry - enable authentication](../../registry/zookeeper/#31-authentication and authentication) + +### 3.1 Customize external configuration key +**1. Enable external configuration and specify key** +```yaml +dubbo + config-center + address: zookeeper://127.0.0.1:2181 + config-file: dubbo.properties +``` + +`config-file` - externalized configuration file key value, default `dubbo.properties`. `config-file` represents the key value corresponding to the file in the configuration center when the Dubbo configuration file is stored in the remote registration center, and it is generally not recommended to modify this configuration item. + +**2. Add configuration to Zookeeper configuration center** +The storage structure of the externalized configuration is shown in the figure below + +![zk-configcenter.jpg](/imgs/user/zk-configcenter.jpg) + +- namespace, used for environment isolation of different configurations. +- config, a fixed node agreed by Dubbo, cannot be changed, and all configuration and traffic governance rules are stored under this node. +- dubbo and application are used to isolate global configuration and application-level configuration respectively: dubbo is the default group value, and application corresponds to the application name +- dubbo.properties, the node value of this node stores the specific configuration content + +> Here is to explain the working principle, it is recommended to use dubbo-admin for configuration management. + +### 3.2 Set group and namespace +```yaml +dubbo + config-center + address: zookeeper://127.0.0.1:2181 + group: dubbo-cluster1 + namespace: dev1 +``` + +For the configuration center, `group` and `namespace` should be unified across the company (cluster), avoid using different values for different applications, and external configuration and governance rules should also be stored in the corresponding group and namespace. + +## 4 Traffic Governance Rules +All traffic governance rules are stored under the `/dubbo/config` node by default. The specific node structure diagram is as follows. It is recommended to add, delete, and modify traffic governance rules through dubbo-admin. For more information, please refer to the specific traffic governance capabilities supported by Dubbo + +![zk-configcenter-governance](/imgs/user/zk-configcenter-governance.jpg) + +- namespace, used for environment isolation of different configurations. +- config, a fixed node agreed by Dubbo, cannot be changed, and all configuration and traffic governance rules are stored under this node. +- dubbo, all service governance rules are global, dubbo is the default node +- configurators/tag-router/condition-router/migration, different service governance rule types, node value stores specific rule content \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/config/_index.md b/content/en/docs3-v2/java-sdk/reference-manual/config/_index.md new file mode 100644 index 000000000000..b18a80924bad --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/config/_index.md @@ -0,0 +1,8 @@ +--- +type: docs +title: "Configuration Manual" +linkTitle: "Configuration instructions" +weight: 1 +description: "Dubbo abstracts a series of structured configurations. For different users, it can not only quickly start services with minimal configuration, but also precisely control service behavior through complex configurations when needed; + In addition to the basic usage of API + Properties, Dubbo also supports SpringBoot, Annotation, XML, YAML, etc. in the form of configuration through the integration with Spring. " +--- \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/config/annotation.md b/content/en/docs3-v2/java-sdk/reference-manual/config/annotation.md new file mode 100644 index 000000000000..3863690c889d --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/config/annotation.md @@ -0,0 +1,209 @@ +--- +type: docs +title: "Annotation configuration" +linkTitle: "Annotation Configuration" +weight: 3 +description: "Develop Dubbo application with Annotation and Spring Boot" +--- + +This article uses the Spring Boot + Annotation mode to describe Dubbo application development. Check out the Spring Annotation development mode without Spring Boot here [complete example](https://github.com/apache/dubbo-samples/tree/master/1-basic/ dubbo-samples-annotation) + +In Dubbo Spring Boot development, you only need to add a few annotations and configure the `application.properties` or `application.yml` file to complete the Dubbo service definition: +* Annotations include `@DubboService`, `@DubboReference` and `EnableDubbo`. Among them, `@DubboService` and `@DubboReference` are used to mark Dubbo services, and `EnableDubbo` starts Dubbo-related configuration and specifies the Spring Boot scanning package path. +* Configuration file `application.properties` or `application.yml` + +For complete examples of the following content, please refer to [dubbo-samples](https://github.com/apache/dubbo-samples/tree/master/1-basic/dubbo-samples-spring-boot) + +## Add Maven dependency + +Use Dubbo Spring Boot Starter to first introduce the following Maven dependencies +```xml + + + + + org.springframework.boot + spring-boot-dependencies + ${spring-boot.version} + pom + import + + + + org.apache.dubbo + dubbo-bom + ${dubbo.version} + pom + import + + + + + org.apache.dubbo + dubbo-dependencies-zookeeper + ${dubbo.version} + pom + + + +``` + +Then add it to the pom of the corresponding module +```xml + + + + org.apache.dubbo + dubbo + + + org.apache.dubbo + dubbo-dependencies-zookeeper + pom + + + + + org.apache.dubbo + dubbo-spring-boot-starter + + + + + org.springframework.boot + spring-boot-starter + + + org.springframework.boot + spring-boot-autoconfigure + + +``` +> Distinguish between ** and ** above + +## application.yml or application.properties + +Components other than service and reference can be set in the application.yml file. If you want to extend the annotation configuration of service or reference, you need to add `dubbo.properties` configuration file or use other non-annotation methods such as Java Config. For details, please See [Extended Annotation Configuration](#Extended Annotation Configuration) below. + +Service and reference components can also be associated with global components in the application through `id`, take the following configuration as an example: + +```yaml +dubbo: + application: + name: dubbo-springboot-demo-provider + protocol: + name: dubbo + port: -1 + registry: + id: zk-registry + address: zookeeper://127.0.0.1:2181 + config-center: + address: zookeeper://127.0.0.1:2181 + metadata-report: + address: zookeeper://127.0.0.1:2181 +``` + +Associate the service with the specific registry defined above via annotations +```java +@DubboService(registry="zk-registry") +public class DemoServiceImpl implements DemoService {} +``` + +The same is true for association through Java Config configuration +```java +@Configuration +public class ProviderConfiguration { + @Bean + public ServiceConfig demoService() { + ServiceConfig service = new ServiceConfig(); + service.setRegistry("zk-registry"); + return service; + } +} +``` +## Annotation +### @DubboService annotation + +> The `@Service` annotation has been deprecated since version 3.0, use `@DubboService` to distinguish it from Spring's `@Service` annotation + +After defining the Dubbo service interface, provide the implementation logic of the service interface and mark it with `@DubboService` annotation to realize the service exposure of Dubbo + +```java +@DubboService +public class DemoServiceImpl implements DemoService {} +``` + +If you want to set service parameters, `@DubboService` also provides a way to set common parameters. If you have more complex parameter setting requirements, you can consider using other setting methods +```java +@DubboService(version = "1.0.0", group = "dev", timeout = 5000) +public class DemoServiceImpl implements DemoService {} +``` + +### @DubboReference annotation + +> The `@Reference` annotation has been deprecated since version 3.0, use `@DubboReference` to distinguish it from Spring's `@Reference` annotation + +```java +@Component +public class DemoClient { + @DubboReference + private DemoService demoService; +} +``` + +The `@DubboReference` annotation will be automatically injected as a Dubbo service proxy instance, and remote service calls can be initiated using demoService + +### @EnableDubbo annotation +The `@EnableDubbo` annotation must be configured, otherwise the service defined by the Dubbo annotation will not be loaded, `@EnableDubbo` can be defined on the main class + +```java +@SpringBootApplication +@EnableDubbo +public class ProviderApplication { + public static void main(String[] args) throws Exception { + SpringApplication.run(ProviderApplication.class, args); + } +} +``` + +Spring Boot annotations will only scan the package where the main class is located by default. If the service is defined in other packages, you need to add the configuration `EnableDubbo(scanBasePackages = {"org.apache.dubbo.springboot.demo.provider"})` + +### Extended annotation configuration +Although the configuration parameters can be adjusted through `@DubboService` and `DubboReference` (as shown in the code snippet below), overall the configuration items provided by annotations are still very limited. In this case, if there are more complex parameter setting requirements, you can use `Java Config` or `dubbo.properties` two ways. + +```java +@DubboService(version = "1.0.0", group = "dev", timeout = 5000) +@DubboReference(version = "1.0.0", group = "dev", timeout = 5000) +``` + +### Use Java Config instead of annotations + +Note that Java Config is an alternative to `DubboService` or `DubboReference`, which is recommended for services with complex configuration requirements. + +```java +@Configuration +public class ProviderConfiguration { + @Bean + public ServiceConfig demoService() { + ServiceConfig service = new ServiceConfig(); + service.setInterface(DemoService.class); + service.setRef(new DemoServiceImpl()); + service.setGroup("dev"); + service.setVersion("1.0.0"); + Map parameters = new HashMap<>(); + service. setParameters(parameters); + return service; + } +} +``` + +### Supplementary configuration through dubbo.properties +For scenarios using `DubboService` or `DubboReference`, you can use dubbo.properties as a configuration supplement, [specific format](../principle/#1-configuration format) is explained in more detail here. + +```properties +dubbo.service.org.apache.dubbo.springboot.demo.DemoService.timeout=5000 +dubbo.service.org.apache.dubbo.springboot.demo.DemoService.parameters=[{myKey:myValue},{anotherKey:anotherValue}] +dubbo.reference.org.apache.dubbo.springboot.demo.DemoService.timeout=6000 +``` + +> Properties format configuration is currently not very structural, for example, the key field is more redundant, and support for yaml format will be considered in the future. \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/config/api.md b/content/en/docs3-v2/java-sdk/reference-manual/config/api.md new file mode 100644 index 000000000000..e62df7d8a017 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/config/api.md @@ -0,0 +1,311 @@ +--- +type: docs +title: "API Configuration" +linkTitle: "API Configuration" +weight: 2 +description: "Use API to configure your Dubbo application" +--- + +Assemble configuration, start Dubbo, publish and subscribe services through API coding. This method can support dynamic creation of ReferenceConfig/ServiceConfig, combined with generalized calls to meet the needs of API Gateway or test platform. + +> Reference [API Samples](https://github.com/apache/dubbo-samples/tree/master/1-basic/dubbo-samples-api) + +## service provider + +Expose the service interface through ServiceConfig, and publish the service interface to the registration center. + +> Note: In order to better support Dubbo3 application-level service discovery, it is recommended to use the new [DubboBootstrap API](#bootstrap-api). + +```java +import org.apache.dubbo.config.ApplicationConfig; +import org.apache.dubbo.config.RegistryConfig; +import org.apache.dubbo.config.ProviderConfig; +import org.apache.dubbo.config.ServiceConfig; +import com.xxx.DemoService; +import com.xxx.DemoServiceImpl; + +public class DemoProvider { + public static void main(String[] args) { + // service implementation + DemoService demoService = new DemoServiceImpl(); + + // current application configuration + ApplicationConfig application = new ApplicationConfig(); + application.setName("demo-provider"); + + // connect registry configuration + RegistryConfig registry = new RegistryConfig(); + registry.setAddress("zookeeper://10.20.130.230:2181"); + + // service provider protocol configuration + ProtocolConfig protocol = new ProtocolConfig(); + protocol.setName("dubbo"); + protocol.setPort(12345); + protocol.setThreads(200); + + // Note: ServiceConfig is a heavy object, which internally encapsulates the connection with the registration center and opens the service port + // The service provider exposes the service configuration + ServiceConfig service = new ServiceConfig(); // This instance is very heavy and encapsulates the connection with the registration center, please cache it yourself, otherwise it may cause memory and connection leaks + service. setApplication(application); + service.setRegistry(registry); // Multiple registries can use setRegistries() + service.setProtocol(protocol); // multiple protocols can use setProtocols() + service.setInterface(DemoService.class); + service.setRef(demoService); + service.setVersion("1.0.0"); + + // expose and register services + service. export(); + + // Suspend waiting (to prevent the process from exiting) + System.in.read(); + } +} +``` + +## Service Consumer + +Reference the remote service through ReferenceConfig, and subscribe to the service interface from the registry. + +> Note: In order to better support Dubbo3 application-level service discovery, it is recommended to use the new [DubboBootstrap API](#bootstrap-api). + +```java +import org.apache.dubbo.config.ApplicationConfig; +import org.apache.dubbo.config.RegistryConfig; +import org.apache.dubbo.config.ConsumerConfig; +import org.apache.dubbo.config.ReferenceConfig; +import com.xxx.DemoService; + +public class DemoConsumer { + public static void main(String[] args) { + // current application configuration + ApplicationConfig application = new ApplicationConfig(); + application.setName("demo-consumer"); + + // connect registry configuration + RegistryConfig registry = new RegistryConfig(); + registry.setAddress("zookeeper://10.20.130.230:2181"); + + // Note: ReferenceConfig is a heavy object, which internally encapsulates the connection with the registry and the connection with the service provider + // reference the remote service + ReferenceConfig reference = new ReferenceConfig(); // This instance is very heavy and encapsulates the connection with the registry and the provider, please cache it yourself, otherwise it may cause memory and connection leaks + reference.setApplication(application); + reference.setRegistry(registry); // Multiple registries can use setRegistries() + reference.setInterface(DemoService.class); + reference.setVersion("1.0.0"); + + // use demoService like local bean + // Note: This proxy object internally encapsulates all communication details, the object is heavy, please cache and reuse + DemoService demoService = reference. get(); + demoService.sayHello("Dubbo"); + } +} +``` + +## Bootstrap API + +DubboBootstrap API can reduce repeated configuration, better control the startup process, support batch publishing/subscribing service interfaces, and better support Dubbo3's application-level service discovery. + +```java +import org.apache.dubbo.config.bootstrap.DubboBootstrap; +import org.apache.dubbo.config.ApplicationConfig; +import org.apache.dubbo.config.RegistryConfig; +import org.apache.dubbo.config.ProviderConfig; +import org.apache.dubbo.config.ServiceConfig; +import com.xxx.DemoService; +import com.xxx.DemoServiceImpl; + +public class DemoProvider { + public static void main(String[] args) { + + ConfigCenterConfig configCenter = new ConfigCenterConfig(); + configCenter.setAddress("zookeeper://127.0.0.1:2181"); + + // service provider protocol configuration + ProtocolConfig protocol = new ProtocolConfig(); + protocol.setName("dubbo"); + protocol.setPort(12345); + protocol.setThreads(200); + + // Note: ServiceConfig is a heavy object, which internally encapsulates the connection with the registration center and opens the service port + // The service provider exposes the service configuration + ServiceConfig demoServiceConfig = new ServiceConfig<>(); + demoServiceConfig.setInterface(DemoService.class); + demoServiceConfig.setRef(new DemoServiceImpl()); + demoServiceConfig.setVersion("1.0.0"); + + // Second service configuration + ServiceConfig fooServiceConfig = new ServiceConfig<>(); + fooServiceConfig.setInterface(FooService.class); + fooServiceConfig.setRef(new FooServiceImpl()); + fooServiceConfig.setVersion("1.0.0"); + + ... + + // Use DubboBootstrap to simplify configuration assembly and control the startup process + DubboBootstrap. getInstance() + .application("demo-provider") // application configuration + .registry(new RegistryConfig("zookeeper://127.0.0.1:2181")) // registry configuration + .protocol(protocol) // global default protocol configuration + .service(demoServiceConfig) // add ServiceConfig + .service(fooServiceConfig) + .start() // start Dubbo + .await(); // suspend waiting (to prevent the process from exiting) + } +} +``` + +```java +import org.apache.dubbo.config.bootstrap.DubboBootstrap; +import org.apache.dubbo.config.ApplicationConfig; +import org.apache.dubbo.config.RegistryConfig; +import org.apache.dubbo.config.ProviderConfig; +import org.apache.dubbo.config.ServiceConfig; +import com.xxx.DemoService; +import com.xxx.DemoServiceImpl; + +public class DemoConsumer { + public static void main(String[] args) { + + // reference the remote service + ReferenceConfig demoServiceReference = new ReferenceConfig(); + demoServiceReference.setInterface(DemoService.class); + demoServiceReference.setVersion("1.0.0"); + + ReferenceConfig fooServiceReference = new ReferenceConfig(); + fooServiceReference.setInterface(FooService.class); + fooServiceReference.setVersion("1.0.0"); + + // Use DubboBootstrap to simplify configuration assembly and control the startup process + DubboBootstrap bootstrap = DubboBootstrap. getInstance(); + bootstrap.application("demo-consumer") // application configuration + .registry(new RegistryConfig("zookeeper://127.0.0.1:2181")) // registry configuration + .reference(demoServiceReference) // add ReferenceConfig + .service(fooServiceReference) + .start(); // Start Dubbo + + ... + + // use demoService like local bean + // Obtain the remote service interface proxy through Interface, without relying on the ReferenceConfig object + DemoService demoService = DubboBootstrap.getInstance().getCache().get(DemoService.class); + demoService.sayHello("Dubbo"); + + FooService fooService = DubboBootstrap.getInstance().getCache().get(FooService.class); + fooService. greeting("Dubbo"); + } + +} + +``` + +## Other configuration + +- basic configuration +- Method level configuration +- Point-to-point direct connection + +The API provides the most flexible and rich configuration capabilities, the following are some examples of configurable components. + +#### basic configuration + +Global basic configuration can be set in DubboBootstrap, including application configuration, protocol configuration, registration center, configuration center, metadata center, module, monitoring, SSL, provider configuration, consumer configuration, etc. + +```java +// registry +RegistryConfig registry = new RegistryConfig(); +registry.setAddress("zookeeper://192.168.10.1:2181"); +... + +// service provider protocol configuration +ProtocolConfig protocol = new ProtocolConfig(); +protocol.setName("dubbo"); +protocol.setPort(12345); +protocol.setThreads(200); +... + +// configuration center +ConfigCenterConfig configCenter = new ConfigCenterConfig(); +configCenter.setAddress("zookeeper://192.168.10.2:2181"); +... + +// metadata center +MetadataReportConfig metadataReport = new MetadataReportConfig(); +metadataReport.setAddress("zookeeper://192.168.10.3:2181"); +... + +// Metrics +MetricsConfig metrics = new MetricsConfig(); +metrics.setProtocol("dubbo"); +... + +// SSL +SslConfig ssl = new SslConfig(); +ssl.setServerKeyCertChainPath("/path/ssl/server-key-cert-chain"); +ssl.setServerPrivateKeyPath("/path/ssl/server-private-key"); +... + +// Provider configuration (ServiceConfig default configuration) +ProviderConfig provider = new ProviderConfig(); +provider.setGroup("demo"); +provider.setVersion("1.0.0"); +... + +// Consumer configuration (ReferenceConfig default configuration) +ConsumerConfig consumer = new ConsumerConfig(); +consumer.setGroup("demo"); +consumer.setVersion("1.0.0"); +consumer.setTimeout(2000); +... + +DubboBootstrap. getInstance() + .application("demo-app") + .registry(registry) + .protocol(protocol) + .configCenter(configCenter) + .metadataReport(metadataReport) + .module(new ModuleConfig("module")) + .metrics(metrics) + .ssl (ssl) + .provider(provider) + .consumer(consumer) + ... + .start(); + +``` + +#### Method level settings + +```java +... + +// method-level configuration +List methods = new ArrayList(); +MethodConfig method = new MethodConfig(); +method. setName("sayHello"); +method.setTimeout(10000); +method. setRetries(0); +methods. add(method); + +// reference the remote service +ReferenceConfig reference = new ReferenceConfig(); // This instance is very heavy and encapsulates the connection with the registry and the provider, please cache it yourself, otherwise it may cause memory and connection leaks +... +reference.setMethods(methods); // Set method-level configuration + +... +``` + +#### Point-to-point direct connection + +```java + +... + +// This instance is very heavy, it encapsulates the connection with the registry and the provider, please cache it yourself, otherwise it may cause memory and connection leaks +ReferenceConfig reference = new ReferenceConfig(); +// If point-to-point direct connection, you can use reference.setUrl() to specify the target address. After setting the url, the registration center will be bypassed. +// Among them, the protocol corresponds to the value of provider.setProtocol(), and the port corresponds to the value of provider.setPort(). +// The path corresponds to the value of service.setPath(). If no path is set, the default path is the interface name +reference.setUrl("dubbo://10.20.130.230:20880/com.xxx.DemoService"); + +... +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/config/overview.md b/content/en/docs3-v2/java-sdk/reference-manual/config/overview.md new file mode 100644 index 000000000000..94ad2dffc206 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/config/overview.md @@ -0,0 +1,166 @@ +--- +type: docs +title: "Configuration Overview" +linkTitle: "Configuration Overview" +weight: 1 +description: "A general overview of the overall design and working principle of Dubbo configuration, including configuration components, configuration sources, configuration methods, and configuration loading processes." +--- +Quickly jump to the content you care about through the following links: +* [Use Spring Boot to quickly develop Dubbo applications](../../../quick-start/spring-boot/) +* [Configuration item reference manual to know what configuration items are available](../properties) +* [How configuration loading and overriding works](../principle) + +## Configuration components + +In order to better manage various configurations, Dubbo abstracts a set of structured configuration components. Each component is generally divided by purpose and controls the behavior of different scopes. + +![dubbo-config](/imgs/user/dubbo-config.jpg) + +Component Name | Description | Scope | Required +------ | ------ | ------ | ------ +application | Specify the application-level information such as the application name | Only one application is allowed in an application | Required +service | Declare a common interface or implementation class as a Dubbo service | There can be 0 or more services in an application | At least one service/reference +reference | Declare a common interface as a Dubbo service | There can be 0 or more references in an application | At least one service/reference +protocol | The RPC protocol to be exposed and related configurations such as port numbers, etc. | One application can be configured with multiple, one protocol can be used for a set of service&reference | optional, default dubbo +registry | Registry type, address and related configuration | Multiple configurations can be made in one application, and one registry can be applied to a group of service&references | Mandatory +config-center | configuration center type, address and related configurations | multiple configurations in one application, shared by all services | optional +metadata-report | metadata center type, address and related configuration | multiple configurations in one application, shared by all services | optional +Consumer | The default configuration shared between references | Multiple configurations can be configured in one application, and one consumer can act on a group of references | Optional +Provider | The default configuration shared between services | Multiple configurations can be configured in one application, and one provider can be used for a group of services | Optional +monitor | monitoring system type and address | only one can be configured in an application | optional +metrics | related configuration of the data acquisition module | only one configuration is allowed in an application | optional +ssl | ssl/tls security link-related certificate configuration | Only one configuration is allowed in an application | optional +method | specifies method-level configuration | subconfigurations for service and reference | optional +argument | parameter configuration of a method | subconfiguration of method | optional + + +> 1. From the perspective of implementation principle, all configuration items of Dubbo will be assembled into the URL in the end, and the URL will be used as the carrier to pass during subsequent startup and RPC calls, thereby controlling the behavior of the framework. For more information, please refer to the Dubbo source code analysis series of documents or [Blog](/zh/blog/2019/10/17/dubbo-in-url-unified model/#rpc call). +> 2. For the specific configuration items supported by each component and their meanings, please refer to [Configuration Item Manual](../properties) + +### service and reference +`service` and `reference` are the two most basic configuration items of Dubbo, they are used to register a specified interface or implementation class as a Dubbo service, and control the behavior of the service through configuration items. +* `service` is used on the service provider side, the interface and implementation class configured by `service` will be defined as a standard Dubbo service, so as to provide external RPC request services. +* `reference` is used for service consumers, the interface configured by `reference` will be defined as a standard Dubbo service, and the generated proxy can initiate an RPC request to the remote end. + +Any number of `service` and `reference` can be configured in an application. + +### consumer and provider +* When there are multiple `reference` configurations in the application, `consumer` specifies the default values shared by these `reference`s, such as shared timeouts, etc. to simplify cumbersome configurations, such as setting configurations separately in a `reference` Item value, the configuration in this `reference` takes precedence. +* When there are multiple `service` configurations in the application, `provider` specifies the default value shared by these `service`, if a configuration item value is set separately in a `service`, the configuration priority in the `service` higher. + +> The consumer component can also carry out virtual grouping of references, and references under different groups can have different consumer default value settings; for example, in XML format configuration, the tag can be nested in Implement grouping within tags. The same effect can also be achieved between provider and service. + +## configuration method + +According to the driving mode, it can be divided into the following five modes: + +### API configuration +The configuration is organized in the form of Java coding, including Raw API and Bootstrap API. For details, please refer to [API configuration](../api). + +```java +public static void main(String[] args) throws IOException { + ServiceConfig service = new ServiceConfig<>(); + service.setApplication(new ApplicationConfig("first-dubbo-provider")); + service.setRegistry(new RegistryConfig("multicast://224.5.6.7:1234")); + service.setInterface(GreetingsService.class); + service.setRef(new GreetingsServiceImpl()); + service. export(); + System.out.println("first-dubbo-provider is running."); + System.in.read(); +} +``` + +### XML configuration +Configure various components in XML and support seamless integration with Spring. For details, please refer to [XML Configuration](../xml). + +```xml + + + + + + + + + + + +``` + +### Annotation configuration +Expose services and reference service interfaces in the form of annotations, and support seamless integration with Spring. For details, please refer to [Annotation Configuration](../annotation). + +```java + // AnnotationService service implementation + + @DubboService + public class AnnotationServiceImpl implements AnnotationService { + @Override + public String sayHello(String name) { + System.out.println("async provider received: " + name); + return "annotation: hello, " + name; + } + } +``` + +```properties +## dubbo.properties + +dubbo.application.name=annotation-provider +dubbo.registry.address=zookeeper://127.0.0.1:2181 +dubbo.protocol.name=dubbo +dubbo.protocol.port=20880 +``` + +### Spring Boot +Use Spring Boot to reduce unnecessary configuration, and combine Annotation and application.properties/application.yml to develop Dubbo applications. For details, please refer to [Annotation Configuration](../annotation). + +```properties +## application.properties + +# Spring boot application +spring.application.name=dubbo-externalized-configuration-provider-sample + +# Base packages to scan Dubbo Component: @com.alibaba.dubbo.config.annotation.Service +dubbo.scan.base-packages=com.alibaba.boot.dubbo.demo.provider.service + +# Dubbo Application +## The default value of dubbo.application.name is ${spring.application.name} +## dubbo.application.name=${spring.application.name} + +#Dubbo Protocol +dubbo.protocol.name=dubbo +dubbo.protocol.port=12345 + +## Dubbo Registry +dubbo.registry.address=N/A + +## DemoService version +demo.service.version=1.0.0 +``` + +### Property configuration +Generate configuration components according to the attribute Key-value, similar to SpringBoot's ConfigurationProperties, please refer to [property configuration](../properties) for details. + +Another important feature of property configuration is [property override](../principle/#32-property override), which overrides the created configuration component property with the value of an external property. + +If you want to put the attribute configuration in an external configuration center, please refer to [Externalized Configuration](../principle/#33-Externalized Configuration). + +In addition to the differences in peripheral drive methods, Dubbo's configuration reading generally follows the following principles: + +1. Dubbo supports multi-level configuration, and automatically realizes the coverage between configurations according to the predetermined priority. Finally, all configurations are summarized into the data bus URL to drive subsequent service exposure, reference and other processes. +2. The configuration format is mainly Properties, and the configuration content follows the agreed `path-based`[naming convention](../principle/#1-configuration format) + + +## Configure the loading process + +### Configuration specifications and sources + +Dubbo follows a [path-based configuration specification](../principle/), and each configuration component can be expressed in this way. In terms of configuration sources, a total of 6 configuration sources are supported, that is, Dubbo will try to load configuration data from the following locations: + +- JVM System Properties, JVM -D parameter +- System environment, the environment variable of the JVM process +- Externalized Configuration, [externalized configuration] (../principle/#33-externalized configuration), read from the configuration center +- Application Configuration, application attribute configuration, extract the attribute set starting with "dubbo" from the Spring application Environment +- The configuration collected by programming interfaces such as API/XML/annotation can be understood as a kind of configuration source, which is a configuration collection method directly oriented to user programming +- Read configuration file dubbo.properties from classpath \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/config/principle.md b/content/en/docs3-v2/java-sdk/reference-manual/config/principle.md new file mode 100644 index 000000000000..c914fa64b2eb --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/config/principle.md @@ -0,0 +1,374 @@ +--- +type: docs +title: "How Configuration Works" +linkTitle: "How configuration works" +weight: 5 +description: "An in-depth interpretation of Dubbo configuration methods and working principles, including configuration formats, design ideas, sources, loading processes, etc." +--- + +The following is an example of Dubbo property configuration [dubbo-spring-boot-samples](https://github.com/apache/dubbo-spring-boot-project/tree/master/dubbo-spring-boot-samples) + +```properties + ## application.properties + + # Spring boot application + spring.application.name=dubbo-externalized-configuration-provider-sample + + # Base packages to scan Dubbo Component: @com.alibaba.dubbo.config.annotation.Service + dubbo.scan.base-packages=com.alibaba.boot.dubbo.demo.provider.service + + # Dubbo Application + ## The default value of dubbo.application.name is ${spring.application.name} + ## dubbo.application.name=${spring.application.name} + + #Dubbo Protocol + dubbo.protocol.name=dubbo + dubbo.protocol.port=12345 + + ## Dubbo Registry + dubbo.registry.address=N/A + + ## service default version + dubbo.provider.version=1.0.0 +``` +Next, around this example, we analyze the working principle of Dubbo configuration from three aspects: configuration format, configuration source, and loading process. + +## 1 configuration format + +All configurations currently supported by Dubbo are in `.properties` format, including `-D`, `Externalized Configuration`, etc. All configuration items in `.properties` follow a `path-based` configuration format. + +In the Spring application, you can also put the attribute configuration in `application.yml`, and the tree hierarchy is more readable. + +```properties +# Application-level configuration (no id) +dubbo.{config-type}.{config-item}={config-item-value} + +# Instance-level configuration (specify id or name) +dubbo.{config-type}s.{config-id}.{config-item}={config-item-value} +dubbo.{config-type}s.{config-name}.{config-item}={config-item-value} + +# Service interface configuration +dubbo.service.{interface-name}.{config-item}={config-item-value} +dubbo.reference.{interface-name}.{config-item}={config-item-value} + +# method configuration +dubbo.service.{interface-name}.{method-name}.{config-item}={config-item-value} +dubbo.reference.{interface-name}.{method-name}.{config-item}={config-item-value} + +# Method argument configuration +dubbo.reference.{interface-name}.{method-name}.{argument-index}.{config-item}={config-item-value} + +``` + +### 1.1 Application-level configuration (no id) + +The format of application-level configuration is: configuration type singular prefix, no id/name. +```properties +# Application-level configuration (no id) +dubbo.{config-type}.{config-item}={config-item-value} +``` + +Similar to `application`, `monitor`, `metrics`, etc. are all application-level components, so only a single instance is allowed to be configured; while `protocol`, `registry`, etc. allow to configure multiple components, when only singleton configuration is required , in the format described in this section. Common examples are as follows: + +```properties +dubbo.application.name=demo-provider +dubbo.application.qos-enable=false + +dubbo.registry.address=zookeeper://127.0.0.1:2181 + +dubbo.protocol.name=dubbo +dubbo.protocol.port=-1 +``` + +### 1.2 Instance-level configuration (specify id or name) + +The attribute configuration for an instance needs to specify an id or name, and its prefix format is: configuration type plural prefix + id/name. Applicable to `protocol`, `registry` and other components that support multiple configurations. + +```properties +# Instance-level configuration (specify id or name) +dubbo.{config-type}s.{config-id}.{config-item}={config-item-value} +dubbo.{config-type}s.{config-name}.{config-item}={config-item-value} +``` + +* If there is no instance of the id or name, the framework will create a configuration component instance based on the properties listed here. +* If an instance with the same id or name already exists, the framework will use the attributes listed here as a supplement to the existing instance configuration. For details, please refer to [Attribute Override](../principle#32-Attribute Override). +* Please refer to the [single and plural configuration comparison table] (../principle#17-single and plural configuration item comparison table) + +Configuration example: + +```properties +dubbo.registries.unit1.address=zookeeper://127.0.0.1:2181 +dubbo.registries.unit2.address=zookeeper://127.0.0.1:2182 + +dubbo.protocols.dubbo.name=dubbo +dubbo.protocols.dubbo.port=20880 + +dubbo.protocols.hessian.name=hessian +dubbo.protocols.hessian.port=8089 +``` + +### 1.3 Service interface configuration + +```properties +dubbo.service.org.apache.dubbo.samples.api.DemoService.timeout=5000 +dubbo.reference.org.apache.dubbo.samples.api.DemoService.timeout=6000 +``` + +### Method configuration + +Method configuration format: + +```properties +# method configuration +dubbo.service.{interface-name}.{method-name}.{config-item}={config-item-value} +dubbo.reference.{interface-name}.{method-name}.{config-item}={config-item-value} + +# Method argument configuration +dubbo.reference.{interface-name}.{method-name}.{argument-index}.{config-item}={config-item-value} +``` + +Example method configuration: +```properties +dubbo.reference.org.apache.dubbo.samples.api.DemoService.sayHello.timeout=7000 +dubbo.reference.org.apache.dubbo.samples.api.DemoService.sayHello.oninvoke=notifyService.onInvoke +dubbo.reference.org.apache.dubbo.samples.api.DemoService.sayHello.onreturn=notifyService.onReturn +dubbo.reference.org.apache.dubbo.samples.api.DemoService.sayHello.onthrow=notifyService.onThrow +dubbo.reference.org.apache.dubbo.samples.api.DemoService.sayHello.0.callback=true +``` + +Equivalent to XML configuration: + +```xml + + + + + +``` + +### 1.4 Parameter configuration + +The parameters parameter is a map object, which supports configuration in the form of xxx.parameters=[{key:value},{key:value}]. +```properties +dubbo.application.parameters=[{item1:value1},{item2:value2}] +dubbo.reference.org.apache.dubbo.samples.api.DemoService.parameters=[{item3:value3}] +``` + +### 1.5 Transport layer configuration + +The triple protocol uses Http2 as the underlying communication protocol, allowing users to customize [6 settings parameters] of Http2 (https://datatracker.ietf.org/doc/html/rfc7540#section-6.5.2) + +The configuration format is as follows: + +```properties +# Notify the peer header of the upper limit of compressed index tables +dubbo.rpc.tri.header-table-size=4096 + +# Enable server-side push function +dubbo.rpc.tri.enable-push=false + +# Notify the peer of the maximum number of concurrent streams allowed +dubbo.rpc.tri.max-concurrent-streams=2147483647 + +# Declare the window size of the sender +dubbo.rpc.tri.initial-window-size=1048576 + +# Set the maximum number of bytes for the frame +dubbo.rpc.tri.max-frame-size=32768 + +# Notify the peer of the maximum number of uncompressed bytes in the header +dubbo.rpc.tri.max-header-list-size=8192 +``` + +Equivalent to yml configuration: + +```yaml +dubbo: + rpc: + tri: + header-table-size: 4096 + enable-push: false + max-concurrent-streams: 2147483647 + initial-window-size: 1048576 + max-frame-size: 32768 + max-header-list-size: 8192 +``` + + + +### 1.6 Attribute and XML configuration mapping rules + +The xml tag name and attribute name can be combined, separated by '.'. One attribute per line. + +* `dubbo.application.name=foo` is equivalent to `` +* `dubbo.registry.address=10.20.153.10:9090` is equivalent to ` ` + +If there is more than one tag in xml configuration, then you can use 'id' to differentiate. If you don't specify an id, it will apply to all tags. + +* `dubbo.protocols.rmi.port=1099` is equivalent to ` ` +* `dubbo.registries.china.address=10.20.153.10:9090` is equivalent to `` + +### 1.7 Single and plural comparison table for configuration items +Plural configurations are named in the same way as regular words are pluralized: + +1. When the letter y ends, remove y and change to ies +2. At the end of the letter s, add es +3. Others add s + +| Config Type | Singular Configuration | Plural Configuration | +| ------------------------------------ | --------------- ------------------------------------------------ | ---- ---------------------------------- | +| application | dubbo.application.xxx=xxx | dubbo.applications.{id}.xxx=xxx
dubbo.applications.{name}.xxx=xxx | +| protocol | dubbo.protocol.xxx=xxx | dubbo.protocols.{id}.xxx=xxx
dubbo.protocols.{name}.xxx=xxx | +| module | dubbo.module.xxx=xxx | dubbo.modules.{id}.xxx=xxx
dubbo.modules.{name}.xxx=xxx | +| registry | dubbo.registry.xxx=xxx | dubbo.registries.{id}.xxx=xxx | +| monitor | dubbo.monitor.xxx=xxx | dubbo.monitors.{id}.xxx=xxx | +| config-center | dubbo.config-center.xxx=xxx | dubbo.config-centers.{id}.xxx=xxx | +| metadata-report | dubbo.metadata-report.xxx=xxx | dubbo.metadata-reports.{id}.xxx=xxx | +| ssl | dubbo.ssl.xxx=xxx | dubbo.ssls.{id}.xxx=xxx | +| metrics | dubbo.metrics.xxx=xxx | dubbo.metricses.{id}.xxx=xxx | +| provider | dubbo.provider.xxx=xxx | dubbo.providers.{id}.xxx=xxx | +| consumer | dubbo.consumer.xxx=xxx | dubbo.consumers.{id}.xxx=xxx | +| service | dubbo.service.{interfaceName}.xxx=xxx | None | +| reference | dubbo.reference.{interfaceName}.xxx=xxx | None | +| method | dubbo.service.{interfaceName}.{methodName}.xxx=xxx
dubbo.reference.{interfaceName}.{methodName}.xxx=xxx | None | +| argument | dubbo.service.{interfaceName}.{methodName}.{arg-index}.xxx=xxx | None | + + +## 2 Configure sources + +Dubbo supports 6 configuration sources by default: + +- JVM System Properties, JVM -D parameter +- System environment, the environment variable of the JVM process +- Externalized Configuration, [externalized configuration] (#33-externalized configuration), read from the configuration center +- Application Configuration, application attribute configuration, extract the attribute set starting with "dubbo" from the Spring application Environment +- The configuration collected by programming interfaces such as API/XML/annotation can be understood as a kind of configuration source, which is a configuration collection method directly oriented to user programming +- Read configuration file dubbo.properties from classpath + +About the dubbo.properties attribute: + +1. If there is more than one dubbo.properties file under the classpath, for example, two jar packages each contain dubbo.properties, dubbo will randomly select one to load and print an error log. +2. Dubbo can automatically load dubbo.properties in the root directory of the classpath, but you can also use JVM parameters to specify the path: `-Ddubbo.properties.file=xxx.properties`. + +### 2.1 Coverage relationship + +If the same configuration item is specified through multiple configuration sources, configuration items will overlap each other. Please refer to the next section for specific coverage relationship and priority. + +## 3 Configuration loading process + +### 3.1 Processing flow + +Dubbo configuration loading is roughly divided into two stages: + +![Configuration loading process](/imgs/v3/config/config-load.svg) + +* The first stage is before the initialization of DubboBootstrap, parse and process the XML configuration/annotation configuration/Java-config or execute the API configuration code when the Spring context starts, create a config bean and add it to the ConfigManager. +* The second stage is the DubboBootstrap initialization process, which reads the external configuration from the configuration center, processes instance-level attribute configuration and application-level attribute configuration in turn, and finally refreshes the attributes of all configuration instances, that is, [property override](../principle#32 -property override). + +### 3.2 Property Override + +There may be two situations where property overriding occurs, and the two may occur at the same time: +1. The same configuration item is configured in different configuration sources +2. The same configuration source, but the same configuration item is specified at different levels + +#### 3.2.1 Different configuration sources + +![Override relationship](/imgs/blog/configuration.jpg) + +#### 3.2.1 Same configuration source + +Property override refers to overriding the properties of the config bean instance with the configured property values, similar to Spring [PropertyOverrideConfigurer](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/beans/ factory/config/PropertyOverrideConfigurer.html) . + +> Property resource configurer that overrides bean property values in an application context definition. It pushes values from a properties file into bean definitions. +Configuration lines are expected to be of the following form: +> +> beanName.property=value + +But the difference from `PropertyOverrideConfigurer` is that Dubbo's property override has multiple matching formats, and the priority from high to low is: + +```properties +#1. Instance-level configuration of the specified id +dubbo.{config-type}s.{config-id}.{config-item}={config-item-value} + +#2. Specify the instance-level configuration of the name +dubbo.{config-type}s.{config-name}.{config-item}={config-item-value} + +#3. Application-level configuration (singular configuration) +dubbo.{config-type}.{config-item}={config-item-value} +``` + +Attribute override processing flow: + +Search in order of priority from high to low. If an attribute starting with this prefix is found, use this prefix to extract the attribute and ignore the subsequent configuration. + +![Properties Override Process](/imgs/v3/config/properties-override.svg) + +### 3.3 Externalization configuration + +One of the purposes of external configuration is to achieve centralized management of configuration. There are already many mature professional configuration systems in this part of the industry, such as Apollo, Nacos, etc. What Dubbo does is mainly to ensure that it can work with these systems. + +There is no difference in content and format between externalized configuration and other local configurations. It can be simply understood as the externalized storage of `dubbo.properties`. The configuration center is more suitable for extracting some public configurations such as registration centers and metadata center configurations for future use. centralized management. + +```properties +# Centralized management of registration center address, metadata center address and other configurations can achieve a unified environment and reduce development-side perception. +dubbo.registry.address=zookeeper://127.0.0.1:2181 +dubbo.registry.simplified=true + +dubbo.metadata-report.address=zookeeper://127.0.0.1:2181 + +dubbo.protocol.name=dubbo +dubbo.protocol.port=20880 + +dubbo.application.qos.port=33333 +``` + +- priority + By default, the externalized configuration has a higher priority than the local configuration, so the content configured here will override the local configuration value. There is a separate chapter explaining the [Override Relationship] (#21-Override Relationship) between various configuration forms. + +- scope + There are two levels of external configuration: global and application. The global configuration is shared by all applications. The application-level configuration is maintained by each application and is only visible to itself. Currently supported extensions include Zookeeper, Apollo, and Nacos. + +#### 3.3.1 How to use external configuration + +1. Add config-center configuration + +```xml + +``` + +2. Add global configuration items in the corresponding configuration center (zookeeper, Nacos, etc.), take Nacos as an example as follows: + +![nacos-extenal-properties](/imgs/v3/config-center/nacos-extenal-properties.png) + +After the external configuration is enabled, global configurations such as registry, metadata-report, protocol, and qos theoretically no longer need to be configured in the application. The application development side focuses on business service configuration, and some globally shared global configurations are transferred to O&M. The personnel are uniformly configured in the remote configuration center. + +The effect of this is that the application only needs to care about: +* Service exposure, subscription configuration +* Configuration center address + When deployed to different environments, other configurations can be automatically read from the corresponding configuration center. + +For example, only the following Dubbo-related configurations in each application may be sufficient, and the rest are hosted in the configuration center in the corresponding environment: + +```yaml +dubbo + application + name: demo + config-center + address: nacos://127.0.0.1:8848 +``` + +#### 3.3.2 Load external configuration by itself + +The so-called Dubbo's support for the configuration center is essentially to pull `.properties` from the remote to the local, and then integrate it with the local configuration. In theory, as long as the Dubbo framework can get the required configuration, it can start normally. It doesn't care whether these configurations are loaded by itself or directly inserted by the application, so Dubbo also provides the following APIs to allow users to organize themselves. The configuration is stuffed into the Dubbo framework (the configuration loading process is to be completed by the user), so that the Dubbo framework no longer directly interacts with Apollo or Zookeeper to read the configuration. + +```java +// The application loads its own configuration +Map dubboConfigurations = new HashMap<>(); + dubboConfigurations.put("dubbo.registry.address", "zookeeper://127.0.0.1:2181"); + dubboConfigurations.put("dubbo.registry.simplified", "true"); + +//Throw the organized configuration into the Dubbo framework + ConfigCenterConfig configCenter = new ConfigCenterConfig(); + configCenter.setExternalConfig(dubboConfigurations); +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/config/properties.md b/content/en/docs3-v2/java-sdk/reference-manual/config/properties.md new file mode 100644 index 000000000000..391489cd3640 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/config/properties.md @@ -0,0 +1,558 @@ +--- +type: docs +title: "Configuration Item Reference Manual" +linkTitle: "Configuration Item Manual" +weight: 6 +description: "Contains all configuration components supported by Dubbo and all configuration items supported by each configuration component" +--- + +## Configuration Details + +### application + +Each application must have one and only one application configuration, corresponding configuration class: `org.apache.dubbo.config.ApplicationConfig` + +| Attribute | Corresponding URL parameter | Type | Required | Default | +| --- | --- | ---- | --- | --- | --- | --- | --- | +| name | application | string | Required | | Service Governance| The name of the current application, which is used by the registry to calculate dependencies between applications. Note: the consumer and provider application names should not be the same, this parameter is not Matching conditions, you can fill in the name of your current project, which has nothing to do with the role of the provider and consumer. For example, if the kylin application calls the service of the morgan application, the kylin project will be kylin, and the morgan project will be morgan. Maybe kylin also provides other The service is used by others, but the kylin project will always be dubbed kylin, so the registry will show that kylin depends on morgan | version 2.7 .0 or later | +compiler | compiler | string | optional | javassist | performance optimization | Java bytecode compiler, used to generate dynamic classes, optional: jdk or javassist | version 2.7.0 or later | +| logger | logger | string | optional | slf4j | performance optimization | log output method, optional: slf4j, jcl, log4j, log4j2, jdk | version 2.7.0 or later | +| owner | owner | string | Optional | | Service Governance | The person in charge of the application, used for service governance, please fill in the email prefix of the person in charge | Version above 2.0.5 | +| organization | organization | string | Optional | | Service Governance | Organization name (BU or department), which is used by the registration center to distinguish service sources. It is recommended not to use autoconfig for this configuration item, and write it directly in the configuration, such as china, intl, itu, crm, asc, dw, aliexpress, etc. | Version 2.0.0 and above | +| architecture
| architecture
| string | optional | | Service Governance | . Different architectures use different layers. | Version 2.0. 7 and above | +| environment | environment | string | Optional | | Service Governance | Application environment, such as: develop/test/product, different environments use different default values, and it is only used as a restriction for developing and testing functions | 2.0.0 and above version | +| version | application.version | string | optional | | service governance | current application version | version 2.7.0 or later | +| dumpDirectory | dump.directory | string | Optional | | Service Governance | When the process has a problem such as the thread pool is full, the storage path of the framework's automatic dump file | Version 2.7.0 or later | +| qosEnable | qos.enable | boolean | Optional | | Service governance | Whether to enable the qos operation and maintenance port | Version 2.7.0 or later | +| qosHost | qos.host | string | Optional | | Service Governance | Network interface address to monitor, default 0.0.0.0 | Version 2.7.3 or later | +| qosPort | qos.port | int | optional | | service governance | network port to monitor | version 2.7.0 or later | +| qosAcceptForeignIp | qos.accept.foreign.ip | boolean | Optional | | Service Governance | Security configuration, whether to accept external requests except localhost local access | Version 2.7.0 or later | +| shutwait | dubbo.service.shutdown.wait | string | optional | | service governance | shutdown waiting time (ms) during graceful shutdown | version 2.7.0 or later | +| hostname | | string | optional | local hostname | service governance | hostname | version 2.7.5 or later | +| registerConsumer | registerConsumer | boolean | optional | true | service governance | whether to register the instance to the registry. Only set to `false` when the instance is a pure consumer | Version 2.7.5 and above | +| repository | application.version | string | optional | | service governance | current application version | version 2.7.6 or later | +| enableFileCache | file.cache | boolean | optional | true | service governance | whether to enable local cache | version 3.0.0 or later | +| protocol | | string | optional | dubbo | service governance | preferred protocol, applicable when the preferred protocol cannot be determined | version 3.0.0 or later | +| metadataType | metadata-type |String| Optional | local | Service Governance | Application-level service discovery The metadata delivery method is from the perspective of Provider, and the configuration on the Consumer side is invalid. The optional values are:
* remote - Provider Put the metadata in the remote registry, and the Consumer gets it from the registry;
* local - Provider puts the metadata locally, and the Consumer gets it directly from the Provider; | Version 2.7.5 and above | +| +| metadataServicePort | metadata-service-port | int | Optional | | Service Governance | If metadataType is configured as local, this property sets the port number used by the MetadataService service | Version 2.7.9 or later | +| livenessProbe | liveness-probe | string | optional | | service governance | concept and format corresponding to k8s system liveness probe | version 3.0.0 or later | +| readinessProbe | readiness-probe | string | optional | | service governance | concept and format corresponding to k8s system readiness probe | version 3.0.0 or later | +| startupProbe | startup-probe | string | Optional | | Service Governance | The concept and format correspond to the k8s system startup probe | Version 3.0.0 or later | +| registerMode | register-mode | string | Optional | all | Service Governance | Control address registration behavior, used for application-level service discovery and migration.
* instance only registers application-level addresses;
* interface only registers interface-level addresses;
* all (default) registers both application-level and interface-level addresses; | Version 3.0.0 and above | +| enableEmptyProtection | enable-empty-protection | boolean | Optional | true | Service Governance | Whether to enable the protection of the empty address list on the consumer side globally. After enabling it, the empty address push from the registration center will be ignored. The default is true | Version 3.0.0 or later | +| parameters | None | Map | Optional | | Service Governance | Reserved for extensions, any parameters can be extended and defined, and all extended parameters will be reflected in the URL configuration as they are | Version 2.7.0 and above | + + +### service + +A service provider exposes service configuration. Corresponding configuration class: `org.apache.dubbo.config.ServiceConfig` + +| Attribute | Corresponding URL parameter | Type | Required | Default | +| --- | --- | ---- | --- | --- | --- | --- | --- | +| interface | | class | required | | service discovery | service interface name | version 1.0.0 or later | +| ref | | object | required | | service discovery | service object implementation reference | version 1.0.0 or later | +| version | version | string | optional | 0.0.0 | service discovery | service version, it is recommended to use a two-digit version, such as: 1.0, usually the version number needs to be upgraded when the interface is not compatible | version 1.0.0 or later | +| group | group | string | optional | | service discovery | service grouping, when an interface has multiple implementations, they can be distinguished by grouping | version 1.0.7 or later | +| path | | string | optional | default interface name | service discovery | service path (note: 1.0 does not support custom path, always use the interface name, if there is 1.0 to 2.0, the configuration service path may not be Compatible) | Version 1.0.12+ | +| delay | delay | int | Optional | 0 | Performance tuning | Delayed registration service time (milliseconds), when set to -1, it means that the service is delayed until the initialization of the Spring container is completed | Version 1.0.14 and above | +timeout | timeout | int | optional | 1000 | performance tuning | remote service call timeout (milliseconds) | version 2.0.0 or later | +| retries | retries | int | Optional | 2 | Performance tuning | The number of remote service call retries, excluding the first call, please set it to 0 if you don't need to retry | Version 2.0.0 or later | +connections | connections | int | optional | 100 | performance tuning | the maximum number of connections for each provider, short connection protocols such as rmi, http, and hessian indicate the limit on the number of connections, and long connection agreements such as dubbo indicate the established long connections Number | Version 2.0.0 or above | +loadbalance | loadbalance | string | optional | random | performance tuning | load balancing strategy, optional values:
* random - random;
* roundrobin - polling;
* leastactive - Least active calls; br/>* consistenthash - consistent hash (2.1.0+);
* shortestresponse - shortest response (2.7.7+);| 2.0.0+| +| async | async | boolean | Optional | false | Performance tuning | Whether to execute asynchronously by default, unreliable asynchronous, just ignore the return value, do not block the execution thread | Version above 2.0.0 | +| local | local | class/boolean | optional | false | service governance | set to true, means to use the default proxy class name, that is: interface name + Local suffix, obsolete, please use stub| 2.0.0 or above | +| stub | stub | class/boolean | Optional | false | Service Governance | Set to true, which means to use the default proxy class name, that is: interface name + Stub suffix, the local proxy class name of the service interface client, used in the client The client executes local logic, such as local cache, etc. The constructor of the local proxy class must allow remote proxy objects to be passed in, such as: public XxxServiceStub(XxxService xxxService) | Version 2.0.0 or later | +| mock | mock | class/boolean | Optional | false | Service Governance | Set to true, which means to use the default Mock class name, that is: interface name + Mock suffix, if the service interface fails to call the Mock implementation class , the Mock class must have A no-argument constructor, the difference from Local is that Local is always executed, while Mock is only executed when non-business exceptions (such as timeouts, network exceptions, etc.) occur, Local is executed before remote calls, and Mock is executed after remote calls . | Version 2.0.0 and above | +| token | token | string/boolean | Optional | false | service governance | Consumers bypass the registration center for direct access to ensure that the authorization function of the registration center is valid. If point-to-point calls are used, the token function must be turned off | version 2.0.0 or later | +| registry | | string | optional | default registration to all registries | configuration association | registration to the specified registry, used in multiple registries, the value is the id attribute of , used for multiple registries IDs Separated by commas, If you don't want to register the service to any registry, you can set the value to N/A | Version 2.0.0 or later | +| provider | | string | optional | the first provider configuration is used by default | configuration association | specify the provider, the value is the id attribute of | version above 2.0.0 | +| deprecated | deprecated | boolean | Optional | false | Service Governance | Whether the service is deprecated, if set to true, the consumer will print the service deprecated warning error log | 2.0.5 or later | +| dynamic | dynamic | boolean | Optional | true | Service Governance | Whether the service is dynamically registered, if it is set to false, the disabled status will be displayed after registration, and it needs to be manually enabled, and the registration will not be canceled automatically when the service provider stops , need to be disabled manually. | Version 2.0.5 and above | +| accesslog | accesslog | string/boolean | optional | false | service management | set to true, the access log will be output to the logger, and the access log file path can also be filled in to output the access log directly to the specified file | 2.0.5 and above version | +| owner | owner | string | optional | | service governance | +| document | document | string | optional | | service governance | service document URL | version 2.0.5 or later | +| weight | weight | int | optional | | performance tuning | service weight | version 2.0.5 or later | +| executes | executes | int | optional | 0 | performance tuning | the maximum number of parallel execution requests per service and method of a service provider | version 2.0.5 or later | +actives | actives | int | optional | 0 | performance tuning | maximum number of concurrent calls per service consumer per service per method | version 2.0.5 or later | +proxy | proxy | string | optional | javassist | performance tuning | generate dynamic proxy, optional: jdk/javassist | version 2.0.5 or later | +cluster | cluster | string | optional | failover | performance tuning | cluster mode, optional: failover/failfast/failsafe/failback/forking/available/mergeable (2.1. )/zone-aware (version 2.7.5 or later) | version 2.0 .5 or later | +filter | service.filter | string | optional | default | performance tuning | service provider remote call process interceptor name, multiple names separated by commas | version 2.0.5 or later | +| listener | exporter.listener | string | optional | default | performance tuning | service provider export service listener name, multiple names separated by commas | | +| protocol | | string | optional | | configuration association | use the specified protocol to expose the service, used in multi-protocol, the value is the id attribute of , multiple protocol IDs are separated by commas | version 2.0 .5 or later | +| layer | layer | string | optional | | service governance | the layer where the service provider resides. Such as: biz, dao, intl:web, china:acton. | Version 2.0.7 and above | +| register | register | boolean | optional | true | service governance | whether the service of this protocol is registered to the registry | version 2.0.8 or later | +| validation | validation | string | optional | | service governance | whether to enable JSR303 standard annotation validation, if enabled, the annotations on the method parameters will be validated | version 2.7.0 or later | +| parameters | None | Map | Optional | | Service Governance | Reserved for extensions, any parameters can be extended and defined, and all extended parameters will be reflected in the URL configuration as they are | Version 2.0.0 and above | + +### reference + + +A service consumer references a service configuration. Corresponding configuration class: `org.apache.dubbo.config.ReferenceConfig` + +| Attribute | Corresponding URL parameter | Type | Required | Default | +| --- | --- | ---- | --- | --- | --- | --- | --- | +| id | | string | required | | configuration association | service reference BeanId | version 1.0.0 or later | +| interface | | class | required | | service discovery | service interface name | version 1.0.0 or later | +| version | version | string | optional | | service discovery | service version, consistent with the version of the service provider | version above 1.0.0 | +| group | group | string | optional | | service discovery | service grouping, when an interface has multiple implementations, they can be distinguished by grouping, must be consistent with the service provider | version 1.0.7 or later | +| timeout | timeout | long | optional | timeout of is used by default | performance tuning | service method call timeout (milliseconds) | version 1.0.5 or later | +retries | retries | int | optional | retries of are used by default | performance tuning | retries of remote service calls, excluding the first call, please set to 0 | 2.0. Version 0 and above | +connections | connections | int | optional | default connections of | performance tuning | the maximum number of connections for each provider, rmi, http, hessian and other short connection protocols indicate the limit of the number of connections, dubbo The equal-length connection association indicates the number of established long connections | Version 2.0.0 or later | +| loadbalance | loadbalance | string | optional | default loadbalance of | performance tuning | load balancing strategy, optional values:
* random - random;
* roundrobin - round
* leastactive - least active call;
* consistenthash - consistent hash (version 2.1.0 and above);
* shortestresponse - shortest response (version 2.7.7 and above); | 2.0 .0+ version | +| async | async | boolean | optional | async of is used by default | performance tuning | whether to execute asynchronously, unreliable and asynchronous, just ignore the return value and not block the execution thread | version 2.0.0 or later | +| generic | generic | boolean | optional | default generic | service governance | whether to default the generic interface, if it is a generic interface, it will return GenericService | version 2.0.0 or later | +| check | check | boolean | optional | default check of | service governance | check whether the provider exists at startup, true will report an error, false will ignore | version 2.0.0 or later | +| url | url | string | optional | | service governance | point-to-point direct connection service provider address, will bypass the registration center | version 1.0.6 or later | +| stub | stub | class/boolean | Optional | | Service Governance | The name of the service interface client's local proxy class, which is used to execute local logic on the client, such as local cache, etc. The constructor of the local proxy class must allow input Remote proxy object, constructor such as: public XxxServiceLocal(XxxService xxxService) | version 2.0.0 or later | +| mock | mock | class/boolean | Optional | | Service Governance | Service interface call failure Mock implementation class name, the Mock class must have a no-argument constructor, the difference from Local is that Local is always executed, while Mock Execute only When a non-business exception occurs (such as timeout, network exception, etc.), Local is executed before the remote call, and Mock is executed after the remote call. | Supported by Dubbo1.0.13 and above | +| cache | cache | string/boolean | Optional | | Service Governance | The call parameter is used as the key to cache the returned result, optional: lru, threadlocal, jcache, etc. | Supported by Dubbo2.1.0 and above | +| validation | validation | boolean | optional | | service governance | whether to enable JSR303 standard annotation validation, if enabled, the annotations on the method parameters will be validated | Dubbo2.1.0 and above versions support | +proxy | proxy | boolean | optional | javassist | performance tuning | choose dynamic proxy implementation strategy, optional: javassist, jdk | version above 2.0.2 | +| client | client | string | optional | | performance tuning | client transport type setting, such as netty or mina of Dubbo protocol. | Supported by Dubbo2.0.0 and above | +| registry | | string | optional | By default, the service list will be obtained from all registries and the results will be merged | Configuration Association | Register to obtain the service list from the specified registry, used when there are multiple registries, the value is The id attribute, multiple registration center IDs are separated by commas | Version 2.0.0 or later | +| owner | owner | string | Optional | | Service Governance | To call the person in charge of the service for service governance, please fill in the email prefix of the person in charge | Version above 2.0.5 | +actives | actives | int | optional | 0 | performance tuning | maximum number of concurrent calls per service consumer per service per method | version 2.0.5 or later | +cluster | cluster | string | optional | failover | performance tuning | cluster mode, optional: failover/failfast/failsafe/failback/forking/available/mergeable (2.1. )/zone-aware (version 2.7.5 or later) | version 2.0 .5 or later | +connections | connections | int | optional | 100 | performance tuning | the maximum number of connections for each provider, short connection protocols such as rmi, http, and hessian indicate the limit on the number of connections, and long connection agreements such as dubbo indicate the established long connections Number | Version 2.0.0 or above | +filter | reference.filter | string | optional | default | performance tuning | service consumer remote call process interceptor name, multiple names separated by commas | version 2.0.5 or later | +listener | invoker.listener | string | optional | default | performance tuning | The service consumer quotes the name of the service listener, and multiple names are separated by commas | Version 2.0.5 or later | +| layer | layer | string | optional | | service governance | the layer where the service caller resides. Such as: biz, dao, intl:web, china:acton. | Version 2.0.7 and above | +| init | init | boolean | optional | false | Performance tuning | Whether to starvely initialize the reference when afterPropertiesSet(), otherwise wait until someone injects or references the instance before initializing. | Version 2.0.10 and above | +| protocol | protocol | string | optional | | service governance | only call the service provider of the specified protocol, and ignore other protocols. | Version 2.7.0 and above | +client | client | string | optional | dubbo protocol defaults to netty | service discovery | protocol client implementation type, such as: dubbo protocol mina, netty, etc. | version 2.7.0 or later | +| providerPort | provider-port | int | Optional | | Service Mesh | When dubbo.consumer.meshEnable=true, Dubbo will convert the request to K8S standard format by default, and combine VirtualService and DestinationRule for traffic management. At this time, the consumer can perceive to provider. If you don't want to use VirtualService and DestinationRule, please set providerPort to make the consumer aware of the service port exposed by the provider | Version 3.1.0 and above | +| unloadClusterRelated | unloadClusterRelated | boolean | Optional | false | Service Mesh | When dubbo.consumer.meshEnable=true, in Service Mesh mode, set it to true to unload the Directory, Router and Load Balance related to the Cluster in the current call , Delegate retry, load balancing, timeout and other traffic management functions to Sidecar, use VirtualService and DestinationRule for traffic management | Version 3.1.0 and above | +| parameters | None | Map | Optional | | Service Governance | Reserved for extensions, any parameters can be extended and defined, and all extended parameters will be reflected in the URL configuration as they are | Version 2.0.0 and above | +| providedBy | provided-by | string | Optional | | Service Mesh | When dubbo.consumer.meshEnable=true, Dubbo will convert the request to K8S standard format by default, and combine VirtualService and DestinationRule for traffic management. At this time, the consumer can perceive to provider. The value should be consistent with the declared `k8s service` | Version 3.1.0 or later | +| providerNamespace | provider-namespace | string | Optional | | Service Mesh | When dubbo.consumer.meshEnable=true, Dubbo will convert the request into K8S standard format by default, and combine VirtualService and DestinationRule for traffic management. At this time, the Consumer can perceive to provider. Please set the providerNamespace so that the consumer can address the provider dns according to this configuration, the default `default` | version 3.1.2 or later | + + +### registry + +Registry configuration. Corresponding configuration class: `org.apache.dubbo.config.RegistryConfig`. At the same time, if there are multiple different registries, you can declare multiple `` tags, and specify the registry to use in the `registry` attribute of `` or `` . + +| Attribute | Corresponding URL parameter | Type | Required | Default | +| --- | --- | ---- | --- | --- | --- | --- | --- | +| id | | string | optional | | configuration association | the registration center references the BeanId, which can be referenced in or | version 1.0.16 or later | +| address | | string | Required | | Service discovery| The address of the registration center server. If the address has no port, the default is 9090. Multiple addresses in the same cluster are separated by commas. Such as: ip:port, ip:port, registry centers of different clusters, please configure multiple tags | Version 1.0.16 or later | +| protocol | | string | optional | dubbo | service discovery | registry address protocol, support `dubbo`, `multicast`, `zookeeper`, `redis`, `consul(2.7. .2)`, `etcd( 2.7.2)`, `nacos(2.7.2)` and other protocols | Version 2.0.0 and above | +| port | | int | optional | 9090 | service discovery | the default port of the registry, when the address does not have a port, use this port as the default value | version 2.0.0 or later | +| username | | string | Optional | | Service Governance | Username for logging in to the registration center, if the registration center does not require verification, it can be left blank | Version 2.0.0 or later | +| password | | string | Optional | | Service Governance | Password for logging in to the registration center, if the registration center does not require verification, you can leave it blank | Version 2.0.0 or later | +transport | registry.transporter | string | optional | netty | performance tuning | network transport mode, optional mina, netty | version 2.0.0 or later | +| timeout | registry.timeout | int | optional | 5000 | performance tuning | registry center request timeout (milliseconds) | version 2.0.0 or later | +| session | registry.session | int | optional | 60000 | Performance tuning | Registry session timeout (milliseconds), used to detect dirty data after abnormal disconnection of the provider, such as the implementation of heartbeat detection, this time It is the heartbeat interval , which is different for different registration centers. | Version 2.1.0 and above | +| zone | zone | string | optional | | service governance | the region to which the registry belongs, usually used for traffic isolation | version 2.7.5 or later +| file | registry.file | string | Optional | | Service Governance | Use a file to cache the registry address list and service provider list. When the application is restarted, it will be restored based on this file. Note: two registries cannot use the same file storage | Version 2.0.0 or later | +| wait | registry.wait | int | optional | 0 | performance tuning | wait notification completion time (milliseconds) when stopping | version 2.0.0 or later | +| check | check | boolean | optional | true | service governance | whether to report an error when the registration center does not exist | version 2.0.0 or later | +| register | register | boolean | Optional | true | Service Governance | Whether to register the service with this registry, if set to false, it will only subscribe and not register | Version 2.0.5 and above | +| subscribe | subscribe | boolean | optional | true | service governance | whether to subscribe to this registry service, if set to false, it will only register, not subscribe | version 2.0.5 or later | +| dynamic | dynamic | boolean | Optional | true | Service Governance | Whether the service is dynamically registered, if it is set to false, it will be displayed as disabled after registration, it needs to be manually enabled, and when the service provider stops , it will not be automatically unregistered , need to be disabled manually. | Version 2.0.5 and above | +| group | group | string | Optional | dubbo | Service Governance | Service registration grouping, cross-group services will not affect each other, and cannot call each other, suitable for environment isolation. | Version 2.0.5 and above | +| version | version | string | optional | | service discovery | service version | version above 1.0.0 | +| simplified | simplified | boolean | optional | false | service governance | whether the URL registered to the registration center is in simplified mode (compatible with lower versions) | version 2.7.0 or later | +| extra-keys | extraKeys | string | Optional | | Service Governance | When simplified=true, extraKeys allows you to put extra keys in the URL besides the default parameters, in the format: "interface,key1,key2". | Version 2.7 .0 and above | +| useAsConfigCenter | | boolean | optional | | service governance | whether the registry is used as a configuration center | version 2.7.5 or later | +| useAsMetadataCenter | | boolean | optional | | service governance | whether the registry is used as a metadata center | version 2.7.5 or later | +| accepts | accepts | string | Optional | | Service Governance | The registry receives a list of rpc protocols, multiple protocols are separated by commas, such as dubbo, rest | version 2.7.5 or later | +| preferred | preferred | boolean | optional | | service governance | whether to be the preferred registry. When subscribing to multiple registries, if set to true, the registries will be preferred | Version 2.7.5 and above | +| weight | weight | int | optional | | performance tuning | registration traffic weight. When using multiple registries, you can use this value to adjust the distribution of registration traffic. This value does not take effect when setting the preferred registry | Version 2.7. 5 or later | +| registerMode | register-mode | string | Optional | all | Service Governance | Control address registration behavior, used for application-level service discovery and migration.
* instance only registers application-level addresses;
* interface only registers interface-level addresses;
* all (default) registers both application-level and interface-level addresses; | Version 3.0.0 and above | +| enableEmptyProtection | enable-empty-protection | boolean | Optional | true | Service Governance | Whether to enable the protection of the empty address list on the consumer side globally. After enabling it, the empty address push from the registration center will be ignored. The default is true | Version 3.0.0 or later | +| parameters | None | Map | Optional | | Service Governance | Reserved for extensions, any parameters can be extended and defined, and all extended parameters will be reflected in the URL configuration as they are | Version 2.0.0 and above | + +### config-center + +configuration center. Corresponding configuration class: `org.apache.dubbo.config.ConfigCenterConfig` + +| Attribute | Corresponding URL parameter | Type | Required | Default | Description | Compatibility | +| ---------------- | ---------------------- | --------- ---------- | -------- | ---------------- | ------------- -------------------------------------------------- | -- ---- | +| protocol | protocol | string | optional | zookeeper | Which configuration center to use: apollo, zookeeper, nacos, etc.
Take zookeeper as an example
1. If the protocol is specified, the address can be simplified to `127.0.0.1:2181`;
2. If the protocol is not specified, the address value will be `zookeeper:// 127.0.0.1:2181` | Version 2.7.0 or higher | +| address | address | string | Mandatory | | Configuration center address.
See the protocol description for the value | Version 2.7.0 and above | +| highestPriority | highest-priority| boolean | optional | true | The configuration item from the configuration center has the highest priority, that is, the local configuration item will be overwritten. | Version 2.7.0 and above | +| namespace | namespace | string | optional | dubbo | Usually used for multi-tenant isolation, the actual meaning depends on the specific configuration center.
Such as:
zookeeper - environment isolation, the default value is ` dubbo`;
apollo - distinguishes configuration sets in different domains, using `dubbo` and `application` by default | Version 2.7.0 and above | +| cluster | cluster | string | optional | | The meaning depends on the selected configuration center.
It is used to distinguish different configuration clusters in Apollo | Version 2.7.0 and above | +group | group | string | optional | dubbo | The meaning depends on the selected configuration center.
nacos - isolate different configuration sets
zookeeper - isolate different configuration sets | Version 2.7.0 and above | +| check | check | boolean | optional | true | Whether to terminate the application startup when the connection to the configuration center fails. | Version 2.7.0 and above | +| configFile | config-file | string | optional | dubbo.properties | the key to which the global configuration file is mapped
zookeeper - default path /dubbo/config/dubbo/dubbo.properties
apollo - dubbo dubbo.properties key in namespace | Version 2.7.0 or later | +| appConfigFile | app-config-file | string | optional | | "configFile" is shared globally. This item is restricted to properties configured by this application | 2.7.0+ | +| timeout | timeout | int | optional | 3000ms | get the configured timeout | version 2.7.0 or later | +| username | username | string | optional | | If the configuration center needs to be verified, the username
Apollo is not enabled yet | Version 2.7.0 or later | +| password | password | string | Optional | | If the configuration center needs to be verified, the password
Apollo is not enabled yet | Version 2.7.0 or later | +| parameters | parameters | Map | Optional | | Extended parameters, used to support customized configuration parameters of different configuration centers | Version 2.7.0 or later | +| includeSpringEnv |include-spring-env| boolean | Optional | false | Supported when using the Spring framework. When true, the configuration will be automatically read from the Spring Environment.
By default,
key is dubbo .properties configuration
key is Dubbo.properties PropertySource | Version 2.7.0 or above | + +### metadata-report-config + +metadata center. Corresponding configuration class: `org.apache.dubbo.config.MetadataReportConfig` + +| Attribute | Corresponding URL parameter | Type | Required | Default | Description | Compatibility | +| --------------- | --------- | ------ | -------- | ------- -- | ----------------------------------------------- ------------- | ------ | +| address | address | string | required | | metadata center address. | Version 2.7.0 and above | +protocol | protocol | string | optional | zookeeper | metadata center protocol: zookeeper, nacos, redis, etc.
Take zookeeper as an example
1. If the protocol is specified, the address can be simplified to `127.0.0.1:2181`;
2. If the protocol is not specified, the address value will be `zookeeper:// 127.0.0.1:2181` | Version 2.7.13 and above | +| port | port | int | optional | | metadata center port number. Specify the port, then the address can be simplified, no need to configure the port number | Version 2.7.13 or later | +| username | username | string | optional | | metadata center needs to be verified, username
Apollo is not enabled yet | version 2.7.0 or later | +| password | password | string | Optional | | The metadata center needs to be verified, and the password
Apollo is not enabled yet | Version 2.7.0 or later | +| timeout | timeout | int | optional | | get metadata timeout (ms) | version 2.7.0 or later | +| group | group | string | optional | dubbo | Metadata grouping, suitable for environment isolation. It has the same meaning as the registration center group | Version 2.7.0 and above | +| retryTimes | retry-times | int | optional | 100 | number of retries | version 2.7.0 or later | +| retryPeriod | retry-period | int | optional | 3000ms | retry interval (ms) | version 2.7.0 or later | +| cycleReport | cycle-report | boolean| optional | true | Whether to update full metadata every day | Version 2.7.0 and above | +| syncReport | sync-report | boolean| optional | false | whether to update metadata synchronously, the default is asynchronous | version 2.7.0 or later | +| cluster | cluster | string | optional | | The meaning depends on the selected metadata center.
It is used to distinguish different configuration clusters in Apollo | Version 2.7.0 and above | +| file | file | string | optional | | use the file cache metadata center list, when the application is restarted, it will be restored based on this file, note: two metadata centers cannot use the same file storage | version 2.7.0 or later | +| check | check | boolean | optional | true | Whether to terminate the application startup when the metadata center connection fails. | Version 3.0.0 and above | +| reportMetadata | report-metadata | boolean | Optional | false | Whether to upload the interface configuration report metadata in the address discovery, `dubbo.application.metadata-type=remote` If the configuration does not work, it will be reported, `dubbo. Whether to report when application.metadata-type=local` is determined by the configuration value | Version 3.0.0 or later | +| reportDefinition | report-definition | boolean | Optional | true | Whether to report metadata for service operation and maintenance | Version 3.0.0 or later | +| reportConsumerDefinition | report-consumer-definition | boolean | Optional | true | Whether to report metadata for service operation and maintenance on the consumer side | Version 3.0.0 or later | +| parameters | parameters | Map | Optional | | Extended parameters, used to support customized configuration parameters of different metadata centers | Version 2.7.0 or later | + +### protocol + +Service provider protocol configuration. Corresponding configuration class: `org.apache.dubbo.config.ProtocolConfig`. At the same time, if you need to support multiple protocols, you can declare multiple `` tags, and specify the used protocol through the `protocol` attribute in ``. + +| Attribute | Corresponding URL parameter | Type | Required | Default | +| --- | --- | ---- | --- | --- | --- | --- | --- | +| id | | string | optional | dubbo | configuration association | protocol BeanId, you can refer to this ID in , if the ID is not filled, the default is the same as the value of the name attribute, and if it is repeated, it will be in the name followed by the serial number. | Version 2.0.5 and above | +| name | | string | Required | dubbo | Performance tuning | Protocol name | Version above 2.0.5 | +| port | | int | optional | The default port of dubbo protocol is 20880, the default port of rmi protocol is 1099, the default port of http and hessian protocol is 80; if no port is configured, The default port will be used automatically, if configured as -1, an unoccupied port will be allocated. For Dubbo 2.4.0+, the allocated port is increased on the basis of the default port of the protocol to ensure that the port segment is controllable. | Service Discovery | Service Port | Version 2.0.5 and above | +| host | | string | Optional | Automatically find local IP | Service discovery | - Service host name, used when selecting multiple network cards or specifying VIP and domain name, if it is empty, it will automatically find local IP, - it is recommended not to configure , let Dubbo automatically obtain the local IP | version 2.0.5 or later | +| threadpool | threadpool | string | optional | fixed | performance tuning | thread pool type, optional: fixed/cached/limit (above 2.5.3)/eager (above 2.6.x) | version 2.0.5 or above | +| threadname | threadname | string | optional | | performance tuning | thread pool name | version 2.7.6 or later | +| threads | threads | int | optional | 200 | performance tuning | service thread pool size (fixed size) | version 2.0.5 or later | +| corethreads | corethreads | int | optional | 200 | performance tuning | thread pool core thread size | version 2.0.5 or later | +| iothreads | threads | int | optional | number of cpus + 1 | performance tuning | io thread pool size (fixed size) | version 2.0.5 or later | +| accepts | accepts | int | optional | 0 | +| payload | payload | int | optional | 8388608(=8M) | performance tuning | request and response packet size limit, unit: byte | version 2.0.5 or later | +| codec | codec | string | optional | dubbo | performance tuning | protocol encoding | version 2.0.5 or later | +| serialization | serialization | string | optional | dubbo protocol defaults to hessian2, rmi protocol defaults to java, http protocol defaults to json | performance tuning | protocol serialization method, used when the protocol supports multiple serialization methods , such as: dubbo, hessian2, java, compactedjava of dubbo protocol, and json of http protocol, etc. | Version 2.0.5 and above | +| accesslog | accesslog | string/boolean | Optional | | Service Governance| Set to true, the access log will be output to the logger, you can also fill in the access log file path, directly output the access log to the specified file | Version 2.0.5 or later | +| path | | string | optional | | service discovery | provider context path, prefix of service path | version 2.0.5 or later | +| transporter | transporter | string | optional | dubbo protocol defaults to netty | performance tuning | protocol server and client implementation types, such as: dubbo protocol mina, netty, etc., can be split into server and client configuration | Version 2.0.5 and above | +| server | server | string | Optional | Dubbo protocol defaults to netty, http protocol defaults to servlet | Performance tuning | The server-side implementation type of the protocol, such as: mina, netty of dubbo protocol, etc., jetty of http protocol, servlet, etc. | Version 2.0.5 and above | +| client | client | string | Optional | Dubbo protocol defaults to netty | Performance tuning | Protocol client implementation type, such as: dubbo protocol mina, netty, etc. | Version 2.0.5 or later | +| dispatcher | dispatcher | string | optional | dubbo protocol defaults to all | performance tuning | protocol message distribution method, used to specify the thread model, such as: all, direct, message, execution, connection, etc. of dubbo protocol | 2.1 .0+ version | +| queues | queues | int | optional | 0 | performance tuning | thread pool queue size, when the thread pool is full, the size of the queue waiting to be executed, it is recommended not to set, when the thread pool is full, it should fail immediately, and retry other Serving provisioning machines, rather than queuing, unless there is a special need. | Version 2.0.5 and above | +| charset | charset | string | optional | UTF-8 | performance tuning | serialization encoding | version 2.0.5 or later | +| buffer | buffer | int | optional | 8192 | performance tuning | network read and write buffer size | version 2.0.5 or later | +| heartbeat | heartbeat | int | Optional | 0 | Performance Tuning| A heartbeat is required to help check if a connection is broken | 2.0.10+ | +| telnet | telnet | string | Optional | | Service Governance | Supported telnet commands, separated by commas | Version 2.0.5 and above | +| register | register | boolean | optional | true | service governance | whether the service of this protocol is registered to the registry | version 2.0.8 or later | +| contextpath | contextpath | String | optional | default is empty string | service governance | context path | version 2.0.6 or later | +| sslEnabled | ssl-enabled | boolean | optional | false | service governance | whether to enable ssl | version 2.7.5 or later | +| parameters | parameters | Map | optional | | extended parameters | version 2.0.0 or later | + +### provider + +Service provider default configuration. Corresponding configuration class: `org.apache.dubbo.config.ProviderConfig`. At the same time, this tag is the default value setting of `` and `` tags. + +| Attribute | Corresponding URL parameter | Type | Required | Default | +| --- | --- | ---- | --- | --- | --- | --- | --- | +| id | | string | optional | dubbo | configuration association | protocol BeanId, you can refer to this ID in | version above 1.0.16 | +| protocol | | string | optional | dubbo | performance tuning | protocol name | version 1.0.16 or later | +| host | | string | Optional | Automatically search for local IP | Service discovery | Service host name, used when selecting multiple network cards or specifying VIP and domain name, if it is empty, it will automatically search for local IP. Dubbo automatically obtains the local IP | version 1.0.16 or later | +| threads | threads | int | optional | 200 | performance tuning | service thread pool size (fixed size) | version 1.0.16 or later | +| payload | payload | int | optional | 8388608(=8M) | performance tuning | request and response packet size limit, unit: byte | version above 2.0.0 | +| path | | string | optional | | service discovery | provider context path, prefix of service path | version 2.0.0 or later | +| transporter | transporter | string | optional | dubbo protocol defaults to netty | performance tuning | protocol server and client implementation types, such as: dubbo protocol mina, netty, etc., can be split into server and client configuration | Version 2.0.5 and above | +| server | server | string | Optional | Dubbo protocol defaults to netty, http protocol defaults to servlet | Performance tuning | The server-side implementation type of the protocol, such as: mina, netty of dubbo protocol, etc., jetty of http protocol, servlet, etc. | Version 2.0.0 and above | +| client | client | string | Optional | Dubbo protocol defaults to netty | Performance tuning | Protocol client implementation type, such as: dubbo protocol mina, netty, etc. | Version 2.0.0 or later | +| dispatcher | dispatcher | string | optional | dubbo protocol defaults to all | performance tuning | protocol message distribution method, used to specify the thread model, such as: all, direct, message, execution, connection, etc. of dubbo protocol | 2.1 .0+ version | +| codec | codec | string | optional | dubbo | performance tuning | protocol encoding | version 2.0.0 or later | +| serialization | serialization | string | optional | dubbo protocol defaults to hessian2, rmi protocol defaults to java, http protocol defaults to json | performance tuning | protocol serialization method, used when the protocol supports multiple serialization methods , such as: dubbo, hessian2, java, compactedjava of the dubbo protocol, and json, xml of the http protocol | Version 2.0.5 and above | +| default | | boolean | optional | false | configuration association | whether it is the default protocol, used for multi-protocol | version 1.0.16 or later | +| filter | service.filter | string | optional | | performance tuning | service provider remote call process interceptor name, multiple names separated by commas | version 2.0.5 or later | +| listener | exporter.listener | string | optional | | performance tuning | service provider export service listener name, multiple names separated by commas | version 2.0.5 or later | +| threadpool | threadpool | string | optional | fixed | performance tuning | thread pool type, optional: fixed/cached/limit (above 2.5.3)/eager (above 2.6.x) | version 2.0.5 or above | +| threadname | threadname | string | optional | | performance tuning | thread pool name | version 2.7.6 or later | +| accepts | accepts | int | optional | 0 | +| version | version | string | optional | 0.0.0 | service discovery | service version, it is recommended to use a two-digit version, such as: 1.0, usually the version number needs to be upgraded when the interface is incompatible | version 2.0.5 or later | +| group | group | string | optional | | service discovery | service grouping, when an interface has multiple implementations, they can be distinguished by grouping | version 2.0.5 or later | +| delay | delay | int | Optional | 0 | Performance tuning | Delayed registration service time (milliseconds) - When set to -1, it means that the service is delayed until the initialization of the Spring container is completed | Version 2.0.5 and above | +| timeout | default.timeout | int | optional | 1000 | performance tuning | remote service call timeout (milliseconds) | version 2.0.5 or later | +| retries | default.retries | int | optional | 2 | Performance tuning | The number of remote service call retries, excluding the first call, please set it to 0 if you don't need to retry | Version 2.0.5 or later | +| connections | default.connections | int | optional | 0 | performance tuning | the maximum number of connections for each provider, short connection protocols such as rmi, http, and hessian indicate the limit on the number of connections, long connection agreements such as dubbo indicate the established The number of long connections | Version 2.0.5 and above | +| loadbalance | default.loadbalance | string | optional | random | performance tuning | load balancing strategy, optional values:
* random - random;
* roundrobin - round robin; leastactive - least active call;
* consistenthash - consistent hash (2.1.0+);
* shortestresponse - shortest response (2.7.7+); | 2.0.5+ | +| async | default.async | boolean | optional | false | performance tuning | whether to execute asynchronously by default, unreliable and asynchronous, just ignore the return value and not block the execution thread | Version 2.0.5 and above | +| stub | stub | boolean | Optional | false | Service Governance | If set to true, it means to use the default proxy class name, namely: interface name + Local suffix. | Version 2.0.5 and above | +| mock | mock | boolean | Optional | false | Service Governance | Set to true to use the default Mock class name, namely: interface name + Mock suffix. | Version 2.0.5 and above | +| token | token | boolean | Optional | false | Service Governance | Token verification, empty means not enabled, if true, means randomly generated dynamic tokens | Version 2.0.5 and above | +| registry | registry | string | optional | register with all registries by default | configuration association | register with the specified registry, used when there are multiple registries, the value is the id attribute of , multiple registry IDs Separated by commas, if you do not want to register the service to any registry, you can set the value to N/A | Version 2.0.5 or later | +| dynamic | dynamic | boolean | Optional | true | Service Governance | Whether the service is dynamically registered, if it is set to false, the disabled status will be displayed after registration, and it needs to be manually enabled, and the registration will not be canceled automatically when the service provider stops , need to be disabled manually. | Version 2.0.5 and above | +| accesslog | accesslog | string/boolean | optional | false | service management | set to true, the access log will be output to the logger, and the access log file path can also be filled in to output the access log directly to the specified file | 2.0.5 and above version | +| owner | owner | string | optional | | service governance | +| document | document | string | optional | | service governance | service document URL | version 2.0.5 or later | +| weight | weight | int | optional | | performance tuning | service weight | version 2.0.5 or later | +| executes | executes | int | optional | 0 | performance tuning | the maximum number of parallel execution requests per service and method of a service provider | version 2.0.5 or later | +| actives | default.actives | int | optional | 0 | performance tuning | maximum number of concurrent calls per service consumer per service per method | version 2.0.5 or later | +proxy | proxy | string | optional | javassist | performance tuning | generate dynamic proxy, optional: jdk/javassist | version 2.0.5 or later | +| cluster | default.cluster | string | optional | failover | performance tuning | cluster mode, optional: failover/failfast/failsafe/failback/forking | version above 2.0.5 | +| deprecated | deprecated | boolean | Optional | false | Service Governance | Whether the service is deprecated, if set to true, the consumer will print the service deprecated warning error log | 2.0.5 or later | +| queues | queues | int | optional | 0 | performance tuning | thread pool queue size, when the thread pool is full, the size of the queue waiting to be executed, it is recommended not to set, when the thread pool is full, it should fail immediately, and retry other Serving provisioning machines, rather than queuing, unless there is a special need. | Version 2.0.5 and above | +| charset | charset | string | optional | UTF-8 | performance tuning | serialization encoding | version 2.0.5 or later | +| buffer | buffer | int | optional | 8192 | performance tuning | network read and write buffer size | version 2.0.5 or later | +| iothreads | iothreads | int | Optional | CPU + 1 | Performance tuning | IO thread pool, receive network read and write interrupts, serialize and deserialize, do not process business, business thread pool see threads configuration, this thread pool It is related to the CPU and is not recommended to be configured. | Version 2.0.5 and above | +| alive | alive | int | optional | | service management | thread pool keepAliveTime, the default unit is ms | version 2.0.5 or later | +| telnet | telnet | string | Optional | | Service Governance | Supported telnet commands, separated by commas | Version 2.0.5 and above | +| wait | wait | int | Optional | | Service Governance | Waiting time when stopping the service | +| contextpath | contextpath | String | optional | default is empty string | service governance | context path | version 2.0.6 or later | +| layer | layer | string | optional | | service governance | the layer where the service provider resides. Such as: biz, dao, intl:web, china:acton. | Version 2.0.7 and above | +| parameters | parameters | Map | optional | | service governance | extended parameters | version 2.0.0 or later | + +### consumer + +Service consumer default configuration. Configuration class: `org.apache.dubbo.config.ConsumerConfig`. At the same time, this tag is the default value setting of the `` tag. + +| Attribute | Corresponding URL parameter | Type | Required | Default | +| --- | --- | ---- | --- | --- | --- | --- | --- | +| timeout | default.timeout | int | optional | 1000 | performance tuning | remote service call timeout (milliseconds) | version 1.0.16 or later | +| retries | default.retries | int | optional | 2 | Performance tuning | The number of remote service call retries, excluding the first call, please set it to 0 if you do not need to retry, it is only valid when the cluster is failback/failover | Version 1.0.16 and above | +| loadbalance | default.loadbalance | string | optional | random | performance tuning | load balancing strategy, optional values:
* random - random;
* roundrobin - round robin; leastactive - least active call;
* consistenthash - consistent hash (2.1.0+);
* shortestresponse - shortest response (2.7.7+); | 1.0.16+ | +| async | default.async | boolean | optional | false | performance tuning | whether to execute asynchronously by default, unreliable and asynchronous, just ignore the return value and not block the execution thread | Version 2.0.0 or later | +| sent | default.sent | boolean | optional | true | service governance | when calling asynchronously, when the flag sent=true, it means that the network has sent data | version 2.0.6 or later | +| connections | default.connections | int | optional | 100 | performance tuning | the maximum number of connections for each service to each provider, rmi, http, hessian and other short connection protocols support this configuration, dubbo protocol long connection does not support This configuration | 1.0.16+ version | +| generic | generic | boolean | optional | false | service governance | whether to default the generic interface, if it is a generic interface, it will return GenericService | version above 2.0.0 | +| check | check | boolean | Optional | true | Service Governance | Check whether the provider exists at startup, true reports an error, false ignores | version 1.0.16 and above | +proxy | proxy | string | optional | javassist | performance tuning | generate dynamic proxy, optional: jdk/javassist | version 2.0.5 or later | +| owner | owner | string | Optional | | Service Governance | To call the person in charge of the service for service governance, please fill in the email prefix of the person in charge | Version above 2.0.5 | +| actives | default.actives | int | optional | 0 | performance tuning | maximum number of concurrent calls per service consumer per service per method | version 2.0.5 or later | +| cluster | default.cluster | string | optional | failover | performance tuning | cluster mode, optional: failover/failfast/failsafe/failback/forking/available/mergeable (2.1. above)/zone-aware(2.7.5 above) | 2.0.5 above | +| filter | reference.filter | string | optional | | performance tuning | service consumer remote call process interceptor name, multiple names separated by commas | version 2.0.5 or later | +| listener | invoker.listener | string | optional | | performance tuning | the service consumer quotes the name of the service listener, multiple names are separated by commas | version 2.0.5 or later | +| registry | | string | optional | default registration to all registries | configuration association | registration to the specified registry, used in multiple registries, the value is the id attribute of , used for multiple registries IDs Separated by commas, if you do not want to register the service to any registry, you can set the value to N/A | Version 2.0.5 or later | +| layer | layer | string | optional | | service governance | the layer where the service caller resides. Such as: biz, dao, intl:web, china:acton. | Version 2.0.7 and above | +| init | init | boolean | optional | false | Performance tuning | Whether to starvely initialize the reference when afterPropertiesSet(), otherwise wait until someone injects or references the instance before initializing. | Version 2.0.10 and above | +| cache | cache | string/boolean | Optional | | Service Governance | The call parameter is used as the key to cache the returned result, optional: lru, threadlocal, jcache, etc. | Supported by version 2.1.0 and above | +| validation | validation | boolean | optional | | service governance | whether to enable JSR303 standard annotation validation, if enabled, the annotations on the method parameters will be validated | 2.1.0 and above version support | +| version | version | string | optional | | service governance | configure multiple versions for the same service in Dubbo | 2.2.0 and above versions support | +| client | client | string | Optional | Dubbo protocol defaults to netty | Performance tuning | Protocol client implementation type, such as: dubbo protocol mina, netty, etc. | Version 2.0.0 or later | +| threadpool | threadpool | string | optional | fixed | performance tuning | thread pool type, optional: fixed/cached/limit (above 2.5.3)/eager (above 2.6.x) | version 2.0.5 or above | +| corethreads | corethreads | int | optional | 200 | performance tuning | thread pool core thread size | version 2.0.5 or later | +| threads | threads | int | optional | 200 | performance tuning | service thread pool size (fixed size) | version 2.0.5 or later | +| queues | queues | int | optional | 0 | performance tuning | thread pool queue size, when the thread pool is full, the size of the queue waiting to be executed, it is recommended not to set, when the thread pool is full, it should fail immediately, and retry other Serving provisioning machines, rather than queuing, unless there is a special need. | Version 2.0.5 and above | +| shareconnections | shareconnections | int | optional | 1 | performance tuning | number of shared connections. When the connection parameter is set to 0, the shared mode connection will be enabled, and there is only one connection by default. Only supports dubbo protocol | version 2.7.0 and above | +| referThreadNum | | int | optional | | performance optimization | thread pool size for asynchronous calls | version 3.0.0 or later | +| meshEnable | mesh-enable| boolean | optional | false | Service Mesh | Dubbo Mesh mode switch. After it is turned on, it can adapt to the SideCar mode and convert Dubbo service calls to K8S standard calls. Only supports the Triple protocol and is compatible with GRPC. After setting to true, the native docking K8S, no third-party registration center is required, just set dubbo.registry.address=N/A | Version 3.1.0 or later | +| parameters | parameters | Map | optional | | service governance | extended parameters | version 2.0.0 or later | + +### metrics + +Indicator configuration. Configuration class: `org.apache.dubbo.config.MetricsConfig` + +| Attribute | Corresponding URL parameter | Type | Required | Default | +| --- | --- | ---- | --- | --- | --- | --- | --- | +| protocol | protocol | string | optional | prometheus | performance tuning | protocol name, prometheus is used by default | version 3.0.0 or later | +| prometheus | | PrometheusConfig | optional | | configuration association | prometheus related configuration | version 3.0.0 or later | +| aggregation | | AggregationConfig | Optional | | Configuration association | Indicator aggregation related configuration | Version 3.0.0 or later | + +- PrometheusConfig corresponding class: `org.apache.dubbo.config.nested.PrometheusConfig` + +| Attribute | Type | Required | Default | Description | +| --- | --- | ---- | --- | --- | +| exporter.enabled | boolean | optional | | whether to enable prometheus exporter | +| exporter.enableHttpServiceDiscovery | boolean | optional | | whether to enable http service discovery | +| exporter.httpServiceDiscoveryUrl | string | optional | | http service discovery URL | +| exporter.metricsPort | int | optional | | port number to expose when using the pull method | +| exporter.metricsPath | string | optional | | path to expose metrics when using pull method | +| pushgateway.enabled | boolean | optional | | whether to publish metrics through the Pushgateway of prometheus | +| pushgateway.baseUrl | string | optional | | Pushgateway address | +| pushgateway.username | string | optional | | Pushgateway username | +| pushgateway.password | string | optional | | Pushgateway password | +| pushgateway.pushInterval | int | optional | | push indicator interval time | + +- AggregationConfig corresponding class: `org.apache.dubbo.config.nested.AggregationConfig` + +| Attribute | Type | Required | Default | Description | +| --- | --- | ---- | --- | --- | +| enabled | boolean | optional | | Whether to enable the local indicator aggregation function | +| bucketNum | int | optional | | the number of time window buckets | +| timeWindowSeconds | int | optional | | time window duration (s) | + + +### ssl + +TLS authentication configuration. Configuration class: `org.apache.dubbo.config.SslConfig` + +| Attribute | Corresponding URL parameter | Type | Required | Default | +| --- | --- | ---- | --- | --- | --- | --- | --- | +| serverKeyCertChainPath | server-key-cert-chain-path | string | optional | | security configuration | +| serverPrivateKeyPath | server-private-key-path | string | optional | | security configuration | server private key path | version 2.7.5 or later | +| serverKeyPassword | server-key-password | string | optional | | security configuration | server key password | version 2.7.5 or later | +| serverTrustCertCollectionPath | server-trust-cert-collection-path | string | optional | | security configuration | server trust certificate path | version 2.7.5 or later | +| clientKeyCertChainPath | client-key-cert-chain-path | string | optional | | security configuration | client signature certificate path | version 2.7.5 or later | +| clientPrivateKeyPath | client-private-key-path | string | optional | | security configuration | client private key path | version 2.7.5 or later | +| clientKeyPassword | client-key-password | string | optional | | security configuration | client key password | version 2.7.5 or later | +| clientTrustCertCollectionPath | client-trust-cert-collection-path | string | optional | | security configuration | client trust certificate path | version 2.7.5 or later | + +### module + +Module information configuration. The corresponding configuration class `org.apache.dubbo.config.ModuleConfig` + +| Attribute | Corresponding URL parameter | Type | Required | Default | +| --- | --- | ---- | --- | --- | --- | --- | --- | +| name | module | string | Required | | Service Governance | Current module name, used by the registry to calculate dependencies between modules | Version 2.2.0 or later | +| version | module.version | string | optional | | service governance | current module version | version 2.2.0 or later | +| owner | module.owner | string | Optional | | Service Governance | The person in charge of the module, used for service governance, please fill in the email prefix of the person in charge | Version above 2.2.0 | +| organization | module.organization | string | Optional | | Service Governance | Organization name (BU or department), which is used by the registration center to distinguish service sources. It is recommended not to use autoconfig for this configuration item, and write it directly in the configuration, such as China, intl, itu, crm, asc, dw, aliexpress, etc. | Version 2.2.0 and above | +| background | background | boolean | optional | | performance tuning | whether to enable the background startup mode. If enabled, there is no need to wait for the spring ContextRefreshedEvent event to complete | Version 3.0.0 and above | +| referAsync | referAsync | boolean | Optional | | Performance tuning | Whether to enable asynchronous calls on the consumer side | Version 3.0.0 or later | +| referThreadNum | referThreadNum | int | optional | | performance tuning | thread pool size for asynchronous calls | version 3.0.0 or later | +| exportAsync | exportAsync | boolean | Optional | | Performance tuning | Whether export is enabled on the server | Version 3.0.0 or later | +| exportThreadNum | exportThreadNum | int | optional | | asynchronous export thread pool size | | version 3.0.0 or later | + +### monitor + +Monitoring center configuration. Corresponding configuration class: `org.apache.dubbo.config.MonitorConfig` + +| Attribute | Corresponding URL parameter | Type | Required | Default | +| --- | --- | ---- | --- | --- | --- | --- | --- | +| protocol | protocol | string | optional | dubbo | service governance | monitoring center protocol, if it is protocol="registry", it means that the address of the monitoring center is found from the registry, otherwise it is directly connected to the monitoring center. | Version 2.0.9 and above | +| address | | string | Optional | | Service Governance | Directly connected to the monitoring center server address, address="10.20.130.230:12080" | Version 1.0.16 or later | +| username | username | string | optional | | service governance | monitoring center username | version 2.0.9 or later | +| password | password | string | optional | | service governance | monitoring center password | version 2.0.9 or later | +| group | group | string | optional | | service governance | grouping | version 2.0.9 or later | +| version | version | string | optional | | service governance | version number | version 2.0.9 or later | +| interval | interval | string | optional | | service governance | interval time | version 2.0.9 or later | +| parameters | parameters | Map | optional | | custom parameters | version 2.0.0 or later | + +### method + +Method-level configuration. Corresponding configuration class: `org.apache.dubbo.config.MethodConfig`. At the same time, this tag is a sub-tag of `service` or `reference`, which is used to control to the method level. + +for example: + +```xml + + + +``` + +| Attribute | Corresponding URL parameter | Type | Required | Default | +| --- | --- | ---- | --- | --- | --- | --- | --- | +| name | | string | required | | logo | method name | version 1.0.8 or later | +| timeout | .timeout | int | optional | default is timeout | performance tuning | method call timeout (milliseconds) | version 1.0.8 or later | +| retries | .retries | int | optional | The default is retries of | Performance tuning | The number of retries for remote service calls, excluding the first call, please set it to 0 | Version 2.0.0 or higher | +| loadbalance | .loadbalance | string | optional | default is loadbalance | performance tuning | load balancing strategy, optional values:
* random - random;
* roundrobin - polling ;
* leastactive - least active call;
* consistenthash - consistent hash (version 2.1.0+);
* shortestresponse - shortest response (version 2.7.7+); | 2.0. Version 0 and above | +| async | .async | boolean | Optional | The default is async of | Performance tuning | Whether to execute asynchronously, unreliable and asynchronous, just ignore the return value and not block the execution thread | 1.0.9 above version | +| sent | .sent | boolean | Optional | true | Performance tuning | When calling asynchronously, when the mark sent=true, it means that the network has sent data | Version 2.0.6 or later | +| actives | .actives | int | optional | 0 | performance tuning | maximum concurrent call limit for each service consumer | version 2.0.5 or later | +| executes | .executes | int | optional | 0 | performance tuning | the maximum number of threads used per service and method - -, this attribute is only used when is used as a subtag of Valid | Version 2.0.5 and above | +| deprecated | .deprecated | boolean | Optional | false | Service Governance | Whether the service method is deprecated, this attribute is only valid when is used as a subtag of | Version above 2.0.5 | +| sticky | .sticky | boolean | optional | false | service governance | set true All methods on this interface use the same provider. If you need more complex rules, please use routing | 2.0.6 or later | +| return | .return | boolean | Optional | true | Performance tuning | Whether the method call needs to return a value. It will take effect only when async is set to true. If it is set to true, it will return future, or call back methods such as onreturn. If set to false, Null will be returned directly after the request is sent successfully | Versions above 2.0.6 | +| oninvoke | attribute attribute, not reflected in the URL | String | Optional | | Performance tuning | Intercept before instance execution | Version 2.0.6 or later | +| onreturn | attribute attribute, not reflected in the URL | String | Optional | | Performance tuning | Intercept after instance execution returns | +| onthrow | attribute attribute, not reflected in the URL | String | optional | | performance tuning | exception interception in instance execution | +| oninvokeMethod | attribute attribute, not reflected in the URL | String | Optional | | Performance tuning | Intercept before method execution | Version 2.0.6 or later | +| onreturnMethod | attribute attribute, not reflected in the URL | String | Optional | | Performance tuning | Intercept after method execution returns | Version above 2.0.6 | +| onthrowMethod | attribute attribute, not reflected in the URL | String | Optional | | Performance tuning | Method execution has exception interception | Version 2.0.6 or later | +| cache | .cache | string/boolean | Optional | | Service Governance | Use the call parameter as the key to cache the returned result, optional: lru, threadlocal, jcache, etc. | Version above 2.1.0 | +| validation | .validation | boolean | Optional | | Service Governance | Whether to enable JSR303 standard annotation validation, if enabled, the annotations on method parameters will be validated | Version 2.1.0 or later | + +### argument + +Method parameter configuration. Corresponding configuration class: `org.apache.dubbo.config.ArgumentConfig`. This tag is a sub-tag of `method`, which is used to describe the characteristics of method parameters, such as XML format: + +```xml + + + +``` + +| Attribute | Corresponding URL parameter | Type | Required | Default | +| --- | --- | ---- | --- | --- | --- | --- | --- | +| index | | int | required | | identifier | parameter index | version 2.0.6 or later | +| type | | String | choose one of index and index | | identification | find parameter index by parameter type | version 2.0.6 or later | +| callback | .callback | boolean | optional | | service governance | whether the parameter is a callback interface, if it is callback, the service provider will generate a reverse proxy, and the consumer can be reversely called from the service provider , usually used for event push. | Versions above 2.0.6 | + +### parameter + +Option parameter configuration. Corresponding configuration class: `java.util.Map`. At the same time, the label is a sub-label of `protocol` or `service` or `provider` or `reference` or `consumer` or `monitor` or `registry` or `metadata-config` or `config-center`, used for configuration Custom parameters, this configuration item will be used as an extension point to set custom parameters. + +for example: + +```xml + + + +``` + +You can also: + +```xml + +``` + +| Attribute | Corresponding URL parameter | Type | Required | Default | +| --- | --- | ---- | --- | --- | --- | --- | --- | +| key | key | string | Required | | Service governance | Routing parameter key | Version 2.0.0 or later | +| value | value | string | Required | | Service governance | Routing parameter value | Version 2.0.0 or later | + +### Environment variables +The supported keys are the following two: + +1. `dubbo.labels`, specify a list of key-value pairs configured in the URL, usually through JVM -D or system environment variables. + + Add the following configuration: + + ```properties + # JVM + -Ddubbo.labels = "tag1=value1; tag2=value2" + # environment variables + DUBBO_LABELS = "tag1=value1; tag2=value2" + ``` + + The final generated URL will contain two keys tag1 and tag2: `dubbo://xxx?tag1=value1&tag2=value2` + +2. `dubbo.env.keys`, specify the environment variable key value, Dubbo will try to load each key from the environment variable + + ```properties + # JVM + -Ddubbo.env.keys="DUBBO_TAG1, DUBBO_TAG2" + # environment variables + DUBBO_ENV_KEYS = "DUBBO_TAG1, DUBBO_TAG2" + ``` + + The final generated URL will contain two keys DUBBO_TAG1 and DUBBO_TAG2: `dubbo://xxx?DUBBO_TAG1=value1&DUBBO_TAG2=value2` +### Other configuration +#### config-mode +**background** + +Some types of configuration class instances can only appear once in each dubbo application (such as `ApplicationConfig`, `MonitorConfig`, `MetricsConfig`, `SslConfig`, `ModuleConfig`), and some can appear multiple times (such as `RegistryConfig` , `ProtocolConfig`, etc.). + +If the application accidentally scans multiple unique configuration class instances (for example, the user misconfigures two `ApplicationConfig` in a dubbo application), which strategy should be used to deal with this situation? Is it throwing an exception directly? Is it to keep the former and ignore the latter? Is it to ignore the former and keep the latter? Or does it allow a certain form of coexistence (such as the attributes of the latter overriding the former)? + +Currently, the only configuration class type in dubbo and the configuration modes/strategies allowed by finding multiple instances of a unique configuration type are as follows. + +**Unique configuration class type** + +`ApplicationConfig`, `MonitorConfig`, `MetricsConfig`, `SslConfig`, `ModuleConfig`. + +The first four belong to the application level, and the last one belongs to the module level. + +**configuration mode** + +- `strict`: Strict mode. Throw an exception directly. +- `override`: override mode. Ignore the former and keep the latter. +- `ignore`: ignore pattern. Ignore the latter and keep the former. +- `override_all`: attribute override mode. No matter whether the attribute value of the former is empty or not, the attribute of the latter is overwritten/set on the former. +- `override_if_absent`: attribute override mode if absent. Only when the corresponding attribute value of the former is empty, can the attribute of the latter be overwritten/set on the former. + +Note: The latter two also affect property overrides for configuration instances. Because dubbo has multiple configuration methods, that is, there are multiple configuration sources, and the configuration sources also have priorities. For example, a `ServiceConfig` is configured through xml and the attribute `version=1.0.0` is specified. At the same time, we configure `dubbo.service.{interface}.version=2.0.0` in the external configuration (configuration center), Before the `config-mode` configuration item is introduced, according to the original configuration source priority, `version=2.0.0` of the final instance. However, after the `config-mode` configuration item is introduced, the configuration priority rules are no longer so strict, that is, if `config-mode is override_all` is specified, it is `version=2.0.0`, if `config-mode is override_if_absent` If it is `version=1.0.0`, if `config-mode` is other values, the property setting/overwriting will follow the original configuration priority. + +**Configuration method** + +The configured key is `dubbo.config.mode`, the configured values are as described above, and the default policy value is `strict`. A sample configuration is shown below + +```properties +# JVM -D +-Ddubbo.config.mode=strict + +# environment variables +DUBBO_CONFIG_MODE=strict + +# External configuration (configuration center), Environment of Spring application, dubbo.properties +dubbo.config.mode=strict +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/config/xml.md b/content/en/docs3-v2/java-sdk/reference-manual/config/xml.md new file mode 100644 index 000000000000..c5aafac1ce70 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/config/xml.md @@ -0,0 +1,115 @@ +--- +type: docs +title: "XML Configuration" +linkTitle: "XML Configuration" +weight: 4 +description: "Develop Dubbo application with Spring XML" +--- + +Dubbo has custom configuration components based on Spring Schema extensions, and the configuration capabilities that can be achieved using XML are generally equivalent to [Configuration Reference Manual](../properties). + + +For complete examples of the following content, please refer to [dubbo-samples](https://github.com/apache/dubbo-samples/tree/master/1-basic/dubbo-samples-basic) + +## service provider + + +### Define service interface + +DemoService.java: + +```java +package org.apache.dubbo.demo; + +public interface DemoService { + String sayHello(String name); +} +``` + +### Implement the interface on the service provider side + +DemoServiceImpl.java: + +```java +package org.apache.dubbo.demo.provider; +import org.apache.dubbo.demo.DemoService; + +public class DemoServiceImpl implements DemoService { + public String sayHello(String name) { + return "Hello " + name; + } +} +``` + +### Expose services with Spring configuration declarations + +```xml + + + + + + + + + + + + + + + +``` + +### Load Spring configuration + +```java +public class DemoServiceImpl implements DemoService { + @Override + public String sayHello(String name) { + System.out.println("[" + new SimpleDateFormat("HH:mm:ss").format(new Date()) + "] Hello " + name + + ", request from consumer: " + RpcContext. getContext(). getRemoteAddress()); + return "Hello " + name + ", response from provider: " + RpcContext.getContext().getLocalAddress(); + } +} +``` + +## Service Consumer + +### Reference remote services through Spring configuration + +```xml + + + + + + + + + + + +``` + +### Load Spring configuration and call remote service + +```java +public class BasicConsumer { + public static void main(String[] args) { + ClassPathXmlApplicationContext context = new ClassPathXmlApplicationContext("spring/dubbo-demo-consumer.xml"); + context. start(); + DemoService demoService = (DemoService) context. getBean("demoService"); + String hello = demoService.sayHello("world"); + System.out.println(hello); + } +} +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/graalvm/_index.md b/content/en/docs3-v2/java-sdk/reference-manual/graalvm/_index.md new file mode 100644 index 000000000000..e553b2025449 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/graalvm/_index.md @@ -0,0 +1,216 @@ +--- +type: docs +title: "Dubbo Integration Graalvm Reference Manual" +linkTitle: "Dubbo Integration Graalvm Reference Manual" +toc_hide: true +hide_summary: true +weight: 9 +description: "" +--- + +dubbo3.0 supports native-image document + +## Overview + +This document will introduce the process of connecting dubbo3.0 project to GraalVM and compiling native-image into binary. + +More information about GraalVm can be read https://www.graalvm.org/docs/getting-started/container-images/ this document. + +## Use the example + +Before compiling our dubbo project, we need to make sure that we are based on the graalVm environment. + +1. Install GraalVM + +Go to https://www.graalvm.org/ official website and select the latest version to install according to your own system: + +![](/imgs/blog/dubbo3.0-graalvm-support/graalvmgw.jpg) + +After the installation is complete, modify the path to configure JAVA_HOME, and check the local jdk after it takes effect, you can see the following: + +![](/imgs/blog/dubbo3.0-graalvm-support/graalvm_env.jpg) +Here we use GraalVM based on jdk1.8 version. + +- To install native-image, just execute gu install native-image. + +1. Pull the dubbo code and switch to the [apache:3.0](https://github.com/apache/dubbo) branch. +2. Manually execute the generated SPI code. + +Since the current compilation of native-image does not support code dynamic generation and compilation, the part related to code dynamic generation needs to be generated manually. Here is a tool function: + +![](/imgs/blog/dubbo3.0-graalvm-support/code_generator.jpg) +Execute CodeGenerator to generate SPI code under the dubbo-native module. + +1. Execute install in the root directory + +``` +MacdeMacBook-pro-3:incubator-dubbo mac$ pwd + +/Users/mac/Documents/Mi/project/incubator-dubbo + +MacdeMacBook-pro-3:incubator-dubbo mac$ mvn clean package install -Dmaven.test.skip=true +``` + +1. Compile the demo project + +Here we provide a sample project that can be directly compiled, dubbo-demo/dubbo-demo-native. After the above steps are installed, first go to the provider of dubbo-demo-native and execute native-image compilation: + +``` + mvn clean package -P native -Dmaven.test.skip=true +``` + +Here, since we have introduced the native-image plug-in in maven, the plug-in can be executed directly -P native. + +![](/imgs/blog/dubbo3.0-graalvm-support/native_image_build.jpg) +After the compilation is successful, you can see the generated binary file under the target, start a zookeeper locally, and execute the binary directly. It can be seen that the startup is successful as follows: + +![](/imgs/blog/dubbo3.0-graalvm-support/run_provider.jpg) +The consumer side also executes compilation, and a binary file is also generated under the consumer target: demo-native-consumer. Execute this binary and you can see the result of the call as follows: + +![](/imgs/blog/dubbo3.0-graalvm-support/run_consumer.jpg) +### Specific steps + +In fact, we have done some work under this demo to ensure that the project can be compiled and executed. There are mainly the following steps + +- Introduce dubbo-native dependency + +``` + + + org.apache.dubbo + + dubbo-native + + ${project.version} + + +``` + +Under this module is the SPI code we generated. + +- Introduce native-image plugin + +``` + + + org.graalvm.nativeimage + + native-image-maven-plugin + + 21.0.0.2 + + + + + + + + native-image + + + + package + + + + + + + + false + + demo-native-provider + + org.apache.dubbo.demo.graalvm.provider.Application + + + + --no-fallback + + --initialize-at-build-time=org.slf4j.MDC + + --initialize-at-build-time=org.slf4j.LoggerFactory + + --initialize-at-build-time=org.slf4j.impl.StaticLoggerBinder + + --initialize-at-build-time=org.apache.log4j.helpers.Loader + + --initialize-at-build-time=org.apache.log4j.Logger + + --initialize-at-build-time=org.apache.log4j.helpers.LogLog + + --initialize-at-build-time=org.apache.log4j.LogManager + + --initialize-at-build-time=org.apache.log4j.spi.LoggingEvent + + --initialize-at-build-time=org.slf4j.impl.Log4jLoggerFactory + + --initialize-at-build-time=org.slf4j.impl.Log4jLoggerAdapter + + --initialize-at-build-time=org.eclipse.collections.api.factory.Sets + + --initialize-at-run-time=io.netty.channel.epoll.Epoll + + --initialize-at-run-time=io.netty.channel.epoll.Native + + --initialize-at-run-time=io.netty.channel.epoll.EpollEventLoop + + --initialize-at-run-time=io.netty.channel.epoll.EpollEventArray + + --initialize-at-run-time=io.netty.channel.DefaultFileRegion + + --initialize-at-run-time=io.netty.channel.kqueue.KQueueEventArray + + --initialize-at-run-time=io.netty.channel.kqueue.KQueueEventLoop + + --initialize-at-run-time=io.netty.channel.kqueue.Native + + --initialize-at-run-time=io.netty.channel.unix.Errors + + --initialize-at-run-time=io.netty.channel.unix.IovArray + + --initialize-at-run-time=io.netty.channel.unix.Limits + + --initialize-at-run-time=io.netty.util.internal.logging.Log4JLogger + + --initialize-at-run-time=io.netty.channel.unix.Socket + + --initialize-at-run-time=io.netty.channel.ChannelHandlerMask + + + + --report-unsupported-elements-at-runtime + + --allow-incomplete-classpath + + --enable-url-protocols=http + + -H:+ReportExceptionStackTraces + + + + + + +``` + +It defines the name of the generated image and some parameters for building the image. + +- mount native-image-agent + +Since we need to specify some reflection, JNI and other classes first, we need to use the agent to run it in a normal way to generate information in the form of json for these classes. + +In the startup parameters add: + +``` +-agentlib:native-image-agent=config-output-dir=/tmp/config/,config-write-period-secs=300,config-write-initial-delay-secs=5 +``` + +Start in the normal way, create a folder META-INF.native-image under the resources of the project, and paste the files generated in the local directory: + +![](/imgs/blog/dubbo3.0-graalvm-support/resources.jpg) +(There may be missing class information that is not generated, which needs to be added manually according to the error message when compiling or running.) + + + +** After completing the above steps, the project can be compiled. ** \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/metadata-center/_index.md b/content/en/docs3-v2/java-sdk/reference-manual/metadata-center/_index.md new file mode 100644 index 000000000000..a2a1166e8a92 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/metadata-center/_index.md @@ -0,0 +1,7 @@ +--- +type: docs +title: "Metadata Center" +linkTitle: "Metadata Center" +weight: 6 +description: "" +--- \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/metadata-center/nacos.md b/content/en/docs3-v2/java-sdk/reference-manual/metadata-center/nacos.md new file mode 100644 index 000000000000..e9a6ab83edc8 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/metadata-center/nacos.md @@ -0,0 +1,114 @@ +--- +type: docs +title: "Nacos" +linkTitle: "Nacos" +weight: 2 +description: "Basic use and working principle of Nacos metadata center" +--- + +## 1 Preparations +- Understand [Dubbo basic development steps](/en/docs3-v2/java-sdk/quick-start/spring-boot/) +- Refer to [Nacos Quick Start](https://nacos.io/zh-cn/docs/quick-start.html) to start the Nacos server + +> When Dubbo uses `3.0.0` and above, it needs to use Nacos `2.0.0` and above + +## 2 Instructions for use +The operation steps for Dubbo to integrate Nacos into a metadata center are very simple, roughly divided into two steps: `adding Maven dependencies` and `configuring the metadata center`. +> If the metadata address (dubbo.metadata-report.address) is not configured, the address of the registration center will be used as the metadata center. + +### 2.1 Add Maven dependency +If the project has enabled Nacos as the registration center, no additional configuration is required. + +If the Nacos registry is not enabled, please refer to [Adding Nacos dependencies to the registry](../../registry/nacos/#21-Add dependencies). + +### 2.2 Enable Nacos Configuration Center +```xml + +``` + +or + +```yaml +dubbo + metadata-report + address: nacos://127.0.0.1:8848 +``` + +or + +```properties +dubbo.metadata-report.address=nacos://127.0.0.1:8848 +``` + +or + +```java +MetadataReportConfig metadataConfig = new MetadataReportConfig(); +metadataConfig.setAddress("nacos://127.0.0.1:8848"); +``` + +For `address` format, please refer to [Nacos Registry - Enable Configuration](../../registry/nacos/#22-configure and enable-nacos) + +## 3 Advanced configuration + +For complete configuration parameters, please refer to [metadata-report-config](../../config/properties/#metadata-report-config). + +## 4 How it works + +### 4.1 [Service Operation and Maintenance Metadata](../overview/#2-Service Operation and Maintenance Metadata) + +On the Nacos console, you can see the metadata information related to the service operation and maintenance registered by the service provider and consumer: + +![image-dubbo-metadata-nacos-1.png](/imgs/blog/dubbo-metadata-nacos-1.png) + +In Nacos, the concept of configuration center itself exists, which happens to be used for metadata storage. In the scenario of the configuration center, there is a concept of namespace - namespace, and under the namespace, there is also the concept of group. That is, locate a configuration item through namespace, group, and dataId. If no namespace is specified, ```public``` is used as the default namespace by default. + +```properties +Provider: namespace: 'public', dataId: '{service name}:{version}:{group}:provider:{application name}', group: 'dubbo' +Consumer: namespace: 'public', dataId: '{service name}:{version}:{group}:consumer:{application name}', group: 'dubbo' +``` +`:` remains when version or group does not exist: +```properties +Provider: namespace: 'public', dataId: '{service name}:::provider:{application name}', group: 'dubbo' +Consumer: namespace: 'public', dataId: '{service name}:::consumer:{application name}', group: 'dubbo' +``` + +Providers interface metadata details (use `report-definition=true` to control whether this part of data needs to be reported): + +![image-dubbo-metadata-nacos-3.png](/imgs/blog/dubbo-metadata-nacos-3.png) + +Consumers interface meta information details (whether reporting is controlled by `report-consumer-definition=true`, the default is false): + +![image-dubbo-metadata-nacos-4.png](/imgs/blog/dubbo-metadata-nacos-4.png) + +### 4.2 [Address Discovery - Interface-Application Mapping](../overview//#11-Interface---Application Mapping Relationship) +As mentioned above, service name and application name may be one-to-many. In nacos, a single key-value is used for storage, and multiple application names are separated by English commas `,`. Since a single key-value is used to save data, there may be a problem of concurrent coverage in the case of multiple clients. Therefore, we use the ability of publishConfigCas in nacos to solve this problem. In nacos, using publishConfigCas will allow the user to pass a parameter casMd5, which means the md5 value of the previous configuration content. Before updating, different clients first check the content value of nacos, calculate the md5 value, and use it as a local certificate. When updating, pass the md5 of the credential to the server to compare the md5 value. If it is inconsistent, it means that it has been modified by other clients during this period. Re-obtain the credential and try again (CAS). At present, if the 6 retries fail, the update mapping behavior is abandoned. + +Nacos api: +```java +ConfigService configService = ... +configService.publishConfigCas(key, group, content, ticket); +``` + +The mapping information is located in namespace: 'public', dataId: '{service name}', group: 'mapping'. + +![nacos-metadata-report-service-name-mapping.png](/imgs/user/nacos-metadata-report-service-name-mapping.png) + +### 4.3 [Address Discovery - Interface Configuration Metadata](../overview/#12-Interface Configuration Metadata) + +To enable remote interface configuration metadata registration, the following configuration needs to be added to the application, because by default Dubbo3 application-level service discovery will enable service introspection mode and will not register data to the metadata center. + +```properties + dubbo.application.metadata-type=remote + ``` + +Alternatively, still enable centralized metadata registration in introspection mode + +```properties +dubbo.application.metadata-type=local +dubbo.metadata-report.report-metadata=true +``` + +The details of metadata information in Nacos server are as follows: + +![image-dubbo-metadata-nacos-2.png](/imgs/blog/dubbo-metadata-nacos-2.png) \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/metadata-center/overview.md b/content/en/docs3-v2/java-sdk/reference-manual/metadata-center/overview.md new file mode 100644 index 000000000000..846359851992 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/metadata-center/overview.md @@ -0,0 +1,212 @@ +--- +type: docs +title: "Overview of Metadata Center" +linkTitle: "Overview of Metadata Center" +weight: 1 +--- + +The metadata center provides access to two types of metadata in Dubbo: +- 1 address discovery metadata + - 1.1 'Interface-Application' mapping relationship + - 1.2 Interface configuration data +- 2 Service operation and maintenance metadata + - 2.1 Interface definition description data + - 2.2 Consumers subscribe to relational data + +For how to configure and open the metadata center, please refer to the specific implementation document. + +## 1 Address Discovery Metadata +[Application-level service discovery mechanism](/en/docs3-v2/java-sdk/concepts-and-architecture/service-discovery/#Application-level service discovery introduction) is introduced in Dubbo3 to solve the problem of heterogeneous microservice system interoperability and For performance issues in large-scale cluster practice, application-level service discovery will fully replace interface-level service discovery in the 2.x era. +At the same time, in order to maintain Dubbo's service/interface-oriented ease of use and flexibility of service governance, Dubbo has built a set of metadata mechanisms around application-level service discovery, namely `interface-application mapping relationship` and `interface configuration metadata`. + +### 1.1 Interface - application mapping relationship +Dubbo has always been able to achieve precise address discovery, that is, only subscribe to the services and related address lists that the Consumer declares to care about. Compared with pulling/subscribing to the full address list, this has a good performance advantage. +In the application-level service discovery model, it is not easy to subscribe to precise addresses, because Dubbo Consumer only declares the list of interfaces to be consumed, and Consumers need to be able to convert interfaces into Provider application names to subscribe to precise services. + +For this reason, Dubbo needs to maintain the corresponding relationship of `interface name->application name` in the metadata center, and Dubbo3 actively reports to the metadata center when it is started through the provider. +The mapping relationship between interface (service name) and application (Provider application name) can be one-to-many, that is, one service name may correspond to multiple different application names. + +Taking zookeeper as an example, the mapping relationship is stored in the following locations: + +```shell +$ ./zkCli.sh +$ get /dubbo/mapping/org.apache.dubbo.demo.DemoService +$ demo-provider, two-demo-provider, dubbo-demo-annotation-provider +``` + +1. The node path is `/dubbo/mapping/{interface name}` +2. Multiple application names are separated by English commas `,` + +### 1.2 Interface Configuration Metadata + +`Interface-level configuration metadata` is a supplement to address discovery. Compared with address discovery models such as Spring Cloud, which can only synchronize ip and port information, Dubbo's service discovery mechanism can synchronize information such as interface list, interface definition, and interface-level parameter configuration. . +This part of the content is calculated based on the current application's own information and interface information, and from a performance perspective, a revision is also generated based on metadata to achieve metadata aggregation between different machine instances. + +Taking Zookeeper as an example, the interface configuration metadata is stored in the following locations. If multiple instances generate the same revision, they will eventually share the same metadata configuration: + +/dubbo/metadata/{application name}/{revision} + +```shell script +[zk: localhost:2181(CONNECTED) 33] get /dubbo/metadata/demo-provider/da3be833baa2088c5f6776fb7ab1a436 +``` + +```json +{ + "app": "demo-provider", + "revision": "da3be833baa2088c5f6776fb7ab1a436", + "services": { + "org.apache.dubbo.demo.DemoService:dubbo":{ + "name": "org.apache.dubbo.demo.DemoService", + "protocol": "dubbo", + "path": "org.apache.dubbo.demo.DemoService", + "params": { + "side": "provider", + "release": "", + "methods": "sayHello, sayHelloAsync", + "deprecated": "false", + "dubbo": "2.0.2", + "pid": "38298", + "interface": "org.apache.dubbo.demo.DemoService", + "service-name-mapping": "true", + "timeout": "3000", + "generic": "false", + "metadata-type": "remote", + "delay": "5000", + "application": "demo-provider", + "dynamic": "true", + "REGISTRY_CLUSTER": "registry1", + "anyhost": "true", + "timestamp":"1626887121829" + } + }, + "org.apache.dubbo.demo.RestDemoService:1.0.0:rest":{ + "name": "org.apache.dubbo.demo.RestDemoService", + "version": "1.0.0", + "protocol": "rest", + "path": "org.apache.dubbo.demo.RestDemoService", + "params": { + "side": "provider", + "release": "", + "methods": "getRemoteApplicationName, sayHello, hello, error", + "deprecated": "false", + "dubbo": "2.0.2", + "pid": "38298", + "interface": "org.apache.dubbo.demo.RestDemoService", + "service-name-mapping": "true", + "version": "1.0.0", + "timeout": "5000", + "generic": "false", + "revision": "1.0.0", + "metadata-type": "remote", + "delay": "5000", + "application": "demo-provider", + "dynamic": "true", + "REGISTRY_CLUSTER": "registry1", + "anyhost": "true", + "timestamp": "1626887120943" + } + } + } +} +``` + +## 2 Service operation and maintenance metadata + +The service operation and maintenance metadata reported by Dubbo is usually used by various operation and maintenance systems, such as service testing, gateway data mapping, service static dependency analysis, etc. Various third-party systems can directly read and use this part of the data. For specific connection methods, please refer to the third-party systems mentioned in this chapter. + +### 2.1 Metadata reported by Provider +The metadata content stored on the provider side is as follows: + +```json +{ + "parameters": { + "side": "provider", + "methods": "sayHello", + "dubbo": "2.0.2", + "threads": "100", + "interface": "org.apache.dubbo.samples.metadatareport.configcenter.api.AnnotationService", + "threadpool": "fixed", + "version": "1.1.1", + "generic": "false", + "revision": "1.1.1", + "valid": "true", + "application": "metadatareport-configcenter-provider", + "default.timeout": "5000", + "group": "d-test", + "anyhost": "true" + }, + "canonicalName": "org.apache.dubbo.samples.metadatareport.configcenter.api.AnnotationService", + "codeSource": "file:/Users/cvictory/workspace/work-mw/dubbo-samples/dubbo-samples-metadata-report/dubbo-samples-metadata-report-configcenter/target/classes/", + "methods": [{ + "name": "sayHello", + "parameterTypes": ["java. lang. String"], + "returnType": "java.lang.String" + }], + "types": [{ + "type": "java. lang. String", + "properties": { + "value": { + "type": "char[]" + }, + "hash": { + "type": "int" + } + } + }, { + "type": "int" + }, { + "type": "char" + }] +} +``` + +There are two main parts: +* `parameters` is the service configuration and parameter details. +* `types` defines information for the service. + +##### Metadata reported by Consumer: + +```json +{ + "valid": "true", + "side": "consumer", + "application": "metadatareport-configcenter-consumer", + "methods": "sayHello", + "default.timeout": "6666", + "dubbo": "2.0.2", + "interface": "org.apache.dubbo.samples.metadatareport.configcenter.api.AnnotationService", + "version": "1.1.1", + "revision": "1.1.1", + "group": "d-test" +} +``` + +Configuration metadata used by the Consumer process when subscribing. + +## 3 Metadata reporting mechanism + +Metadata reporting is an asynchronous process by default. In order to better control the asynchronous behavior, the metadata configuration component (metadata-report) opens up two configuration items: +* Retry on failure +* Refresh regularly every day + +### 3.1 retrytimes failed retry +Failure retries can be set through retrytimes (retry times, default 100), retryperiod (retry period, default 3000ms). + +### 3.2 Timing Refresh +It is enabled by default and can be disabled by setting cycleReport=false. + +### 3.3 Complete configuration items + +```properties +dubbo.metadata-report.address=zookeeper://127.0.0.1:2181 +dubbo.metadata-report.username=xxx ##Not required +dubbo.metadata-report.password=xxx ##Not required +dubbo.metadata-report.retry-times=30 ##Non-required, default value 100 +dubbo.metadata-report.retry-period=5000 ##Not required, default value is 3000 +dubbo.metadata-report.cycle-report=false ##Not required, default value is true +dubbo.metadata-report.sync.report=false ##Not required, the default value is false +``` +> If the metadata address (dubbo.metadata-report.address) is not configured, it will judge whether the protocol of the registration center supports the metadata center. If yes, the address of the registration center will be used as the metadata center. + +## 4 Learn how to extend +See [Extending metadata-report](../../spi/description/metadata-report/) for how to extend custom third-party implementations. \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/metadata-center/redis.md b/content/en/docs3-v2/java-sdk/reference-manual/metadata-center/redis.md new file mode 100644 index 000000000000..a351e5f274ec --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/metadata-center/redis.md @@ -0,0 +1,8 @@ +--- +type: docs +title: "Redis" +linkTitle: "Redis" +weight: 4 +description: "Basic use and working principle of Redis metadata center" +--- +Not yet supported \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/metadata-center/zookeeper.md b/content/en/docs3-v2/java-sdk/reference-manual/metadata-center/zookeeper.md new file mode 100644 index 000000000000..72683ec9ff67 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/metadata-center/zookeeper.md @@ -0,0 +1,173 @@ +--- +type: docs +title: "Zookeeper" +linkTitle: "Zookeeper" +weight: 3 +description: "Basic use and working principle of Zookeeper metadata center" +--- + +## 1 Preparations +- Understand [Dubbo basic development steps](/en/docs3-v2/java-sdk/quick-start/spring-boot/) +- Install and start [Zookeeper](https://zookeeper.apache.org/) + +## 2 Instructions for use + +### 2.1 Add Maven dependency +If the project has enabled Zookeeper as the registry, no additional configuration is required. + +If the Zookeeper registry is not used, please refer to [Add Zookeeper-related dependencies for the registry](../../registry/zookeeper/#21-add-maven-dependency). + +### 2.2 Enable Zookeeper Configuration Center +```xml + +``` + +or + +```yaml +dubbo + metadata-report + address: zookeeper://127.0.0.1:2181 +``` + +or + +```properties +dubbo.metadata-report.address=zookeeper://127.0.0.1:2181 +``` + +or + +```java +MetadataReportConfig metadataConfig = new MetadataReportConfig(); +metadataConfig.setAddress("zookeeper://127.0.0.1:2181"); +``` + +For `address` format, please refer to [zookeeper registry - enable configuration](../../registry/zookeeper/#22-configure and enable-zookeeper) + +## 3 Advanced configuration + +For complete configuration parameters, please refer to [metadata-report-config](../../config/properties/#metadata-report-config). + +## 4 How it works + +### 4.1 [Service Operation and Maintenance Metadata](../overview/#2-Service Operation and Maintenance Metadata) + +Zookeeper stores data based on a tree structure, and its metadata information is located in the following nodes: +```text +Provider: /dubbo/metadata/{interface name}/{version}/{group}/provider/{application name} +Consumer: /dubbo/metadata/{interface name}/{version}/{group}/consumer/{application name} +``` + +When the version or group does not exist, the version path and group path will be canceled, the paths are as follows: +```text +Provider: /dubbo/metadata/{interface name}/provider/{application name} +Consumer: /dubbo/metadata/{interface name}/consumer/{application name} +``` + +View data via the zkCli get operation. + +Provider node: +```shell script +[zk: localhost:2181(CONNECTED) 8] get /dubbo/metadata/org.apache.dubbo.demo.DemoService/provider/demo-provider +{"parameters":{"side":"provider","interface":"org.apache.dubbo.demo.DemoService","metadata-type":"remote","application":"demo-provider", "dubbo":"2.0.2","release":"","anyhost":"true","delay":"5000","methods":"sayHello,sayHelloAsync","deprecated":"false" ,"dynamic":"true","timeout":"3000","generic":"false"},"canonicalName":"org.apache.dubbo.demo.DemoService","codeSource":"file:/ Users/apple/IdeaProjects/dubbo/dubbo-demo/dubbo-demo-interface/target/classes/","methods":[{"name":"sayHelloAsync","parameterTypes":["java.lang.String" ],"returnType":"java.util.concurrent.CompletableFuture"},{"name":"sayHello","parameterTypes":["java.lang.String"],"returnType":"java.lang.String "}],"types":[{"type":"java.util.concurrent.CompletableFuture","properties":{"result":"java.lang.Object","stack":"java.util. concurrent.CompletableFuture.Completion"}},{"type":"java.lang.Object"},{"type":"java.lang.String"},{"type":"java.util.concurrent.CompletableFuture .Completion","properties":{"next":"java.util.concurrent.Co mpletableFuture. Completion", "status": "int"}}, {"type": "int"}]} +cZxid = 0x25a9b1 +ctime = Mon Jun 28 21:35:17 CST 2021 +mZxid = 0x25a9b1 +mtime = Mon Jun 28 21:35:17 CST 2021 +pZxid = 0x25a9b1 +cversion = 0 +dataVersion = 0 +aclVersion = 0 +ephemeralOwner = 0x0 +dataLength = 1061 +numChildren = 0 +``` + +Consumer node: +```shell script +[zk: localhost:2181(CONNECTED) 10] get /dubbo/metadata/org.apache.dubbo.demo.DemoService/consumer/demo-consumer +{"side":"consumer","interface":"org.apache.dubbo.demo.DemoService","metadata-type":"remote","application":"demo-consumer","dubbo":" 2.0.2","release":"","sticky":"false","check":"false","methods":"sayHello,sayHelloAsync"} +cZxid = 0x25aa24 +ctime = Mon Jun 28 21:57:43 CST 2021 +mZxid = 0x25aa24 +mtime = Mon Jun 28 21:57:43 CST 2021 +pZxid = 0x25aa24 +cversion = 0 +dataVersion = 0 +aclVersion = 0 +ephemeralOwner = 0x0 +dataLength = 219 +numChildren = 0 +``` + +### 4.2 [Address Discovery - Interface-Application Name Mapping](../overview/#11-Interface---Application Mapping Relationship) +In Dubbo 3.0, the service introspection mechanism is used by default to realize service discovery. For service introspection, please refer to [Service Introspection](https://mercyblitz.github.io/2020/05/11/Apache-Dubbo-%E6%9C%8D%E5%8A%A1%E8%87%AA%E7%9C%81%E6%9E%B6%E6%9E%84%E8%AE%BE%E8%AE%A1/) + +In short, the service introspection mechanism needs to be able to find the corresponding application name through the interface name. This relationship can be one-to-many, that is, one service name may correspond to multiple different application names. In 3.0, the metadata center provides this mapping capability. + + +##### Zookeeper +As mentioned above, service name and application name may be one-to-many. In zookeeper, a single key-value is used for storage, and multiple application names are separated by English commas`,`. Since a single key-value is used to save data, there may be a problem of concurrent coverage in the case of multiple clients. Therefore, we use the version mechanism version in zookeeper to solve this problem. In zookeeper, every time the data is modified, the dataVersion will increase. We can use the version mechanism to solve the concurrent problem of multiple clients updating the mapping at the same time. Before updating, different clients check the version once and use it as a local certificate. When updating, pass the credential version to the server to compare the version. If it is inconsistent, it means that it has been modified by other clients during this period. Re-obtain the credential and try again (CAS). At present, if the 6 retries fail, the update mapping behavior is abandoned. + +Curator api. +```java +CuratorFramework client = ... +client.setData().withVersion(ticket).forPath(path, dataBytes); +``` + +Mapping information is located at: +```text +/dubbo/mapping/{service name} +``` + +View data via the zkCli get operation. + +```shell script +[zk: localhost:2181(CONNECTED) 26] get /dubbo/mapping/org.apache.dubbo.demo.DemoService +demo-provider, two-demo-provider, dubbo-demo-annotation-provider +cZxid = 0x25a80f +ctime = Thu Jun 10 01:36:40 CST 2021 +mZxid = 0x25a918 +mtime = Fri Jun 11 18:46:40 CST 2021 +pZxid = 0x25a80f +cversion = 0 +dataVersion = 2 +aclVersion = 0 +ephemeralOwner = 0x0 +dataLength = 62 +numChildren = 0 +``` + +### 4.3 [Address Discovery - Interface Configuration Metadata](../overview/#12-Interface Configuration Metadata) + +To enable remote interface configuration metadata registration, the following configuration needs to be added to the application, because by default Dubbo3 application-level service discovery will enable service introspection mode and will not register data to the metadata center. + +```properties + dubbo.application.metadata-type=remote + ``` + +Alternatively, still enable centralized metadata registration in introspection mode + +```properties +dubbo.application.metadata-type=local +dubbo.metadata-report.report-metadata=true +``` + +Zookeeper's application level metadata is located at /dubbo/metadata/{application name}/{revision} + +```shell script +[zk: localhost:2181(CONNECTED) 33] get /dubbo/metadata/demo-provider/da3be833baa2088c5f6776fb7ab1a436 +{"app":"demo-provider","revision":"da3be833baa2088c5f6776fb7ab1a436","services":{"org.apache.dubbo.demo.DemoService:dubbo":{"name":"org.apache.dubbo. demo.DemoService","protocol":"dubbo","path":"org.apache.dubbo.demo.DemoService","params":{"side":"provider","release":""," methods":"sayHello,sayHelloAsync","deprecated":"false","dubbo":"2.0.2","pid":"38298","interface":"org.apache.dubbo.demo.DemoService" ,"service-name-mapping":"true","timeout":"3000","generic":"false","metadata-type":"remote","delay":"5000","application" :"demo-provider","dynamic":"true","REGISTRY_CLUSTER":"registry1","anyhost":"true","timestamp":"1626887121829"}},"org.apache.dubbo.demo. RestDemoService:1.0.0:rest":{"name":"org.apache.dubbo.demo.RestDemoService","version":"1.0.0","protocol":"rest","path":"org .apache.dubbo.demo.RestDemoService","params":{"side":"provider","release":"","methods":"getRemoteApplicationName,sayHello,hello,error","deprecated":"false ","dubbo":"2.0.2","pid":"38298","interface":"org.apache.dubbo.demo .RestDemoService","service-name-mapping":"true","version":"1.0.0","timeout":"5000","generic":"false","revision":"1.0.0 ","metadata-type":"remote","delay":"5000","application":"demo-provider","dynamic":"true","REGISTRY_CLUSTER":"registry1","anyhost": "true","timestamp":"1626887120943"}}}} +cZxid = 0x25b336 +ctime = Thu Jul 22 01:05:55 CST 2021 +mZxid = 0x25b336 +mtime = Thu Jul 22 01:05:55 CST 2021 +pZxid = 0x25b336 +cversion = 0 +dataVersion = 0 +aclVersion = 0 +ephemeralOwner = 0x0 +dataLength = 1286 +numChildren = 0 +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/performance/_index.md b/content/en/docs3-v2/java-sdk/reference-manual/performance/_index.md new file mode 100755 index 000000000000..551396298188 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/performance/_index.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "Performance Reference Manual" +linkTitle: "Performance Reference Manual" +weight: 8 +--- \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/performance/benchmarking.md b/content/en/docs3-v2/java-sdk/reference-manual/performance/benchmarking.md new file mode 100644 index 000000000000..97ae6f8302ee --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/performance/benchmarking.md @@ -0,0 +1,48 @@ +--- +type: docs +title: "Application-Level Service Discovery Benchmark" +linkTitle: "Application-Level Service Discovery Benchmark" +weight: 1 +description: "" +--- + + +## 1 Benchmark Conclusion + +Compared with 2.x version, Dubbo3 version + +- Significantly improved service discovery resource utilization. + - Compared with interface-level services, it is found that the resident memory of a single machine is reduced by 50%, and the GC consumption during the address change period is reduced by an order of magnitude (hundred times -> ten times) + - Comparing application-level services, it is found that the resident memory of a single machine is reduced by 75%, and the number of GCs tends to zero + + +The following is the detailed pressure measurement process and data + +## 2 Application-level service discovery (address push link) + +This part of the stress test data is given by the ICBC Dubbo team based on internal production data. The stress test process simulates the service discovery architecture of "production environment address + zookeeper". + +### 2.1 Environment + +| | Description | +| ------------ | ------------------------------------ ------------------------ | +| **Pressure test data** | Provider
500 running instances✖️8interface✖️5protocol, that is, each provider registers 40 URLs with the registration center, a total of 20,000 URLs, and the length of each URL is about 1k characters.

Registration center
2 independent zookeeper registration centers, service providers and consumers adopt parallel configuration.

Consumer
Configure 1c2g, xmx=768, enable GC, subscribe from 2 registries, and call the service every 5 seconds. Run for 20 hours. | +| **Pressure test environment** | Java version "1.8.0"
Java(TM) SE Runtime Environment (build pxa6480sr3fp12-20160919_01(SR3 FP12))
IBM J9 VM (Build 2.8, JRE 1.8 .0 Linux amd64-64 Compressed References 20160915_318796, JIT enabled, AOT enabled) | + + +### 2.2 Data Analysis + +![//imgs/v3/performance/registry-mem.svg](/imgs/v3/performance/registry-mem.svg) + +
Figure 1 Changes in memory usage of the service discovery model

+ +- Dubbo3 interface-level service discovery model, the resident memory is reduced by about 50% compared with version 2.x +- Dubbo3 application-level service discovery model, the resident memory is reduced by about 75% compared with version 2.x + + +![//imgs/v3/performance/registry-gc.svg](/imgs/v3/performance/registry-gc.svg) + +
Figure 2 Service Discovery Model GC Changes

+ +- Dubbo3 interface-level service discovery model, the number of YGC times in version 2.x has dropped significantly, from hundreds of times to more than a dozen times +- Dubbo3 application-level service discovery model, the number of FGC times in version 2.x has dropped significantly, from hundreds of times to zero \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/performance/rpc-benchmarking.md b/content/en/docs3-v2/java-sdk/reference-manual/performance/rpc-benchmarking.md new file mode 100644 index 000000000000..0519f2e279af --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/performance/rpc-benchmarking.md @@ -0,0 +1,55 @@ +--- +type: docs +title: "RPC Protocol Triple&Dubbo Benchmark" +linkTitle: "RPC Benchmark" +weight: 1 +description: "" +--- + +- The _Dubbo protocol_ implementation of Dubbo3 is basically the same as the Dubbo2 version in terms of performance. +- Since the Triple protocol itself is built based on HTTP/2, the RPC call on a single link is not improved compared with TCP-based Dubbo2, but has a certain decline in some call scenarios. But the greater advantage of the _Triple protocol _ lies in the gateway penetration, versatility, and overall throughput improvement brought about by the Stream communication model. +- Triple is expected to have better performance in the gateway proxy scenario. In view of the current stress testing environment, this round of benchmarks has not yet been provided. + +## 1.1 Environment + + +| | Description | +| ------------ | ------------------------------------ ------------------------ | +| **Machine** | 4C8G Linux JDK 1.8 (Provider) 4C8G Linux JDK 1.8 (Consumer) | +| **Pressure test case** | RPC method types include: no parameters and no return value, normal pojo return value, pojo list return value

2.7 version Dubbo protocol (Hessian2 serialization)
Version 3.0 Dubbo protocol (Hessian2 serialization)
3.0 version Dubbo protocol (Protobuf serialization)
3.0 version Triple protocol (Protobuf serialization)
3.0 version Triple protocol (Protobuf sets Hessian2 serialization) | +| **Pressure test method** | In a single-link scenario, the consumer starts 32 concurrent threads (the current machine configuration qps rt has a more balanced number of concurrency), and collects the pressure test data after continuous pressure
The pressure test data passes https: //github.com/apache/dubbo-benchmark Get | + +
+ +## 1.2 Data Analysis + +| | **Dubbo + Hessian2
2.7** | **Dubbo + Hessian2
3.0** | **Dubbo + Protobuf
3.0** | **Triple + Protobuf
3.0** | **Triple + Protobuf(Hessian)
3.0** | +| ------------------ | ----------------------------- | ----------------------------- | -------------------- --------- | ------------------------------ | --------- --------------------------------- | +| **No parameter method** | 30333 ops/s
2.5ms P99 | 30414 ops/s
2.4ms P99 | 24123 ops/s
3.2ms P99 | 7016 ops/s< br />8.7ms P99 | 6635 ops/s
9.1ms P99 | +| **pojo return value** | 8984 ops/s
6.1 ms P99 | 12279 ops/s
5.7 ms P99 | 21479 ops/s
3.0 ms P99 | 6255 ops/s< br />8.9 ms P99 | 6491 ops/s
10 ms P99 | +| **pojo list return value** | 1916 ops/s
34 ms P99 | 2037 ops/s
34 ms P99 | 12722 ops/s
7.7 ms P99 | 6920 ops/s
9.6 ms P99 | 2833 ops/s
27 ms P99 | + +### 1.2.1 Comparison of different versions of Dubbo protocol + +![//imgs/v3/performance/rpc-dubbo.svg](/imgs/v3/performance/rpc-dubbo.svg) + +
Figure 3 Comparison of implementations of the Dubbo protocol in different versions
+ +- As far as the default combination of Dubbo RPC + Hessian is concerned, the performance of Dubbo3 and Dubbo2 is basically the same in different calling scenarios + +### 1.2.2 Dubbo protocol vs Triple protocol + +![//imgs/v3/performance/rpc-triple.svg](/imgs/v3/performance/rpc-triple.svg) + +
Figure 4 Triple vs Dubbo
+ +- Simply looking at the point-to-point calls of Consumer <-> Provider, it can be seen that the Triple protocol itself is not dominant. Also using the Protobuf serialization method, the overall performance of the Dubbo RPC protocol is still better than Triple.

+- Triple implementation will continue to be optimized in version 3.0, but it cannot completely change the situation where "RPC protocol based on HTTP/2" is at a disadvantage compared to "RPC protocol based on TCP" in some scenarios + +### 1.2.3 Supplementary gateway scenarios + +TBD

+ +### 1.2.4 Simulate the throughput improvement of the Stream communication scenario + +TBD \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/protocol/_index.md b/content/en/docs3-v2/java-sdk/reference-manual/protocol/_index.md new file mode 100755 index 000000000000..8f99ba5944f8 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/protocol/_index.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "RPC protocol" +linkTitle: "RPC Protocol" +weight: 4 +--- \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/protocol/dubbo.md b/content/en/docs3-v2/java-sdk/reference-manual/protocol/dubbo.md new file mode 100644 index 000000000000..994c2bab578a --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/protocol/dubbo.md @@ -0,0 +1,125 @@ +--- +type: docs +title: "Dubbo protocol" +linkTitle: "Dubbo protocol" +weight: 2 +--- + +## Feature description +Dubbo's default protocol uses a single long connection and NIO asynchronous communication, which is suitable for small data volume and large concurrent service calls, and the situation where the number of service consumer machines is much larger than the number of service provider machines. + +Conversely, Dubbo's default protocol is not suitable for services that transmit large amounts of data, such as file transfers, video transfers, etc., unless the request volume is very low. + +![dubbo-protocol.jpg](/imgs/user/dubbo-protocol.jpg) + +* Transporter: mina, netty, grizzy +* Serialization: dubbo, hessian2, java, json +* Dispatcher: all, direct, message, execution, connection +* ThreadPool: fixed, cached + + +Default protocol, using tbremoting interaction based on netty `3.2.5.Final` and hessian2 `3.2.1-fixed-2(Alibaba embed version)`. + +* Number of connections: single connection +* Connection method: long connection +* Transport protocol: TCP +* Transmission method: NIO asynchronous transmission +* Serialization: Hessian binary serialization +* Scope of application: The incoming and outgoing parameter data packets are small (recommended to be less than 100K), the number of consumers is more than that of the provider, and a single consumer cannot fill the provider. Try not to use the dubbo protocol to transfer large files or very large strings. +* Applicable scenario: regular remote service method call + +**constraint** + +* Parameters and return values need to implement `Serializable` interface +* Parameters and return values cannot be customized to implement `List`, `Map`, `Number`, `Date`, `Calendar` and other interfaces, only the implementations that come with JDK can be used, because hessian will do special processing and customize the implementation All attribute values in the class are lost. +* Hessian serialization, only pass member attribute values and value types, do not pass methods or static variables, compatibility **provided by Wu Yajun** + +| Data communication | Situation | Results | +| ------------- | ------------- | ------------- | +| A->B | Class A has one more attribute (or class B has one less attribute) | No exception is thrown, the value of the attribute with more A, B does not, and the others are normal | +| A->B | enumeration A has one more enumeration (or B has one less enumeration) | A uses the extra enumeration for transmission | throws exception | +| A->B | Enumeration A has one more enumeration (or B has one less enumeration) | A does not use the extra enumeration for transmission | No exception is thrown, B receives data normally | +| A->B | The attributes of A and B have the same name but different types | Throw an exception | +| A->B | The serialId is different | Normal transmission | + +The method added to the interface has no impact on the client. If the method is not required by the client, the client does not need to redeploy. The addition of attributes in input parameters and result sets has no effect on the client. If the client does not need new attributes, there is no need to redeploy. + +Changes in input parameters and result set attribute names have no impact on client serialization, but if the client is not redeployed, regardless of input or output, the attribute values with changed attribute names cannot be obtained. + +**Summarize** +- The server and the client do not need to be completely consistent with the domain objects, but follow the principle of maximum matching. +- An exception will be thrown: one more type of enumeration value and one less type, just use a different one, or the attribute name is the same, but the type is different. + + +## scenes to be used + +It is suitable for service calls with large concurrent and small data volumes, and the service consumer is much larger than the service provider. + +## How to use + +### Configuration protocol + +```xml + +``` + +### Set the default protocol + +```xml + +``` + +### Set the protocol of a service + +```xml + +``` + +### Multiport + +```xml + + +``` + +### Configure protocol options + +```xml + +``` + +### Multi-connection configuration + +By default, the Dubbo protocol uses a single long connection per service, per provider and per consumer. If the amount of data is large, multiple connections can be used. + +```xml + + +``` + +* `` or `` means that the service uses JVM shared persistent connection. **default** +* `` or `` means that the service uses independent persistent connections. +* `` or `` means that the service uses two independent persistent connections. + +In order to prevent being hung up by a large number of connections, the maximum number of receiving connections can be limited on the service provider to achieve self-protection of the service provider. + +```xml + +``` + +## common problem + +### Q1 +Why should there be more consumers than providers? + +Because the dubbo protocol uses a single long connection, assuming that the network is a gigabit network card **1024Mbit=128MByte**, according to the test experience data, each connection can only be filled up to 7MByte (different environments may be different, for reference), theoretically 1 A service provider needs 20 service consumers to fill up the network card. + +### Q2 +Why can't I send large packets? + +Because the dubbo protocol uses a single long connection, if the data packet size of each request is 500KByte, assuming that the network is a Gigabit network card**1024Mbit=128MByte**, each connection can be up to 7MByte (different environments may be different), a single service provides The maximum TPS (transactions per second) of the latter is: 128MByte / 500KByte = 262. The maximum TPS (transactions per second) for a single consumer to call a single service provider is: 7MByte / 500KByte = 14. If acceptable, you can consider using it, otherwise the network will become a bottleneck. + +### Q3 +Why use asynchronous single long connection? + +Because the current situation of the service is that there are few service providers, usually only a few machines, but many service consumers, the entire website may be accessing the service. For example, Morgan’s provider has only 6 providers, but there are hundreds of consumers. Or, there are 150 million calls per day. If the conventional Hessian service is used, the service provider is easily overwhelmed. Through a single connection, it is guaranteed that a single consumer will not overwhelm the provider, long-term connection, reducing connection handshake verification, etc. And use asynchronous IO, reuse thread pool, prevent C10K problem. \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/protocol/grpc.md b/content/en/docs3-v2/java-sdk/reference-manual/protocol/grpc.md new file mode 100644 index 000000000000..3b13c58e1db3 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/protocol/grpc.md @@ -0,0 +1,34 @@ +--- +type: docs +title: "gRPC Protocol" +linkTitle: "gRPC Protocol" +weight: 5 +--- + + +## Feature description +Dubbo has supported the gRPC protocol since version 2.7.5. For developers who plan to use HTTP/2 communication, or want to take advantage of the capabilities of Stream, backpressure, and Reactive programming brought by gRPC, +You can consider enabling the gRPC protocol. + +#### Benefits of supporting gRPC +* Bring service governance capabilities to users who expect to use the gRPC protocol, and facilitate access to the Dubbo system +* Users can use Dubbo-style, interface-based programming style to define and use remote services + +## scenes to be used + +- Synchronous backend microservice-to-microservice communication that requires an immediate response to continue processing. +- Requires a Polyglot environment that supports mixed programming platforms. +- Low latency and high throughput communications where performance is critical. +- Peer-to-peer real-time communication - gRPC pushes messages in real time without polling and has excellent support for bidirectional streaming. +- Network Constrained Environments - Binary gRPC messages are always smaller than equivalent text-based JSON messages. + +## How to use +### Using gRPC in Dubbo +[Example](https://github.com/apache/dubbo-samples/tree/master/3-extensions/protocol/dubbo-samples-grpc) + +### steps +1. Define a service using IDL +2. Configure the compiler plug-in, precompile locally +3. Configure to expose/reference Dubbo service + +> In addition to the native StreamObserver interface type, Dubbo also supports [RxJava](https://github.com/apache/dubbo-samples/tree/master/3-extensions/protocol/dubbo-samples-grpc/dubbo-samples-rxjava), [Reactor](https://github.com/apache/dubbo-samples/tree/master/3-extensions/protocol/dubbo-samples-grpc/dubbo-samples-reactor) programming style API. \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/protocol/hessian.md b/content/en/docs3-v2/java-sdk/reference-manual/protocol/hessian.md new file mode 100644 index 000000000000..f9d18ca317af --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/protocol/hessian.md @@ -0,0 +1,80 @@ +--- +type: docs +title: "Hessian Agreement" +linkTitle: "Hessian Protocol" +weight: 10 +--- + + +## Feature description +The Hessian protocol is used to integrate Hessian's services. The bottom layer of Hessian uses Http communication and Servlet to expose services. Dubbo's default embedded Jetty is implemented as a server. + +[Hessian](http://hessian.caucho.com) is an open source RPC framework of Caucho, whose communication efficiency is higher than the serialization that comes with WebService and Java. + +* Number of connections: multiple connections +* Connection method: short connection +* Transmission protocol: HTTP +* Transmission method: synchronous transmission +* Serialization: Hessian binary serialization +* Scope of application: The incoming and outgoing parameter data packets are large, the number of providers is larger than that of consumers, the pressure on providers is high, and files can be transferred. +* Applicable scenarios: page transfer, file transfer, or interoperability with native Hessian services. + +Dubbo's Hessian protocol can interoperate with native Hessian services, namely: + +* The provider uses Dubbo's Hessian protocol to expose the service, and the consumer directly uses the standard Hessian interface to call, +* Or the provider uses the standard Hessian to expose the service, and the consumer uses Dubbo's Hessian protocol to call. + +#### Constraints +* Parameters and return values need to implement `Serializable` interface. +* Parameters and return values cannot be customized to implement `List`, `Map`, `Number`, `Date`, `Calendar` and other interfaces, only the implementations that come with JDK can be used, because hessian will do special processing and customize the implementation All attribute values in the class are lost. + +## scenes to be used +Hessian is a lightweight RPC service implemented based on the Binary-RPC protocol, serializing and deserializing instances. + + +## How to use + +### Dependencies + +Starting from Dubbo 3, the Hessian protocol is no longer embedded in Dubbo, and an independent [module](/zh/release/dubbo-spi-extensions/#dubbo-rpc) needs to be introduced separately. +```xml + + org.apache.dubbo.extensions + dubbo-rpc-hessian + 1.0.0 + +``` + +```xml + + com.caucho + hessian + 4.0.7 + +``` + +### Define the hessian protocol +```xml + +``` + +### Set the default protocol +```xml + +``` + +### Set service protocol +```xml + +``` + +### Multiport +```xml + + +``` + +### direct connection +```xml + +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/protocol/http.md b/content/en/docs3-v2/java-sdk/reference-manual/protocol/http.md new file mode 100644 index 000000000000..75c49e22af90 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/protocol/http.md @@ -0,0 +1,69 @@ +--- +type: docs +title: "HTTP protocol" +linkTitle: "HTTP protocol" +weight: 6 +--- + + +## Feature description +HTTP form-based remote invocation protocol, implemented by Spring's HttpInvoker, supported by versions above `2.3.0`. + +* Number of connections: multiple connections +* Connection method: short connection +* Transmission protocol: HTTP +* Transmission method: synchronous transmission +* Serialization: form serialization +* Scope of application: The size of incoming and outgoing parameter data packets is mixed, the number of providers is more than that of consumers, it can be viewed with a browser, and parameters can be passed in by form or URL, and file transfer is not supported for now. +* Applicable scenarios: services that need to be used by both application and browser JS. + +#### Constraints +* Parameters and return values must conform to the Bean specification + +## scenes to be used + +HTTP short connection, standardized and easy-to-read protocol, easy to connect to external systems, suitable for upper-level business modules. + +## How to use + +Starting from Dubbo 3, the Http protocol is no longer embedded in Dubbo, and an independent [module](/zh/release/dubbo-spi-extensions/#dubbo-rpc) needs to be introduced separately. +```xml + + org.apache.dubbo.extensions + dubbo-rpc-http + 1.0.0 + +``` + +### Configuration protocol +```xml + +``` + +### Configure Jetty Server (default) +```xml + +``` + +### Configure Servlet Bridge Server (recommended) +```xml + +``` + +### Configure DispatcherServlet + +```xml + + dubbo + org.apache.dubbo.remoting.http.servlet.DispatcherServlet + 1 + + + dubbo + /* + +``` + +> If a servlet is used to dispatch the request +> * The protocol port `` must be the same as the port of the servlet container, +> * The context path of the protocol `` must be the same as the context path of the servlet application. \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/protocol/memcached.md b/content/en/docs3-v2/java-sdk/reference-manual/protocol/memcached.md new file mode 100644 index 000000000000..3c3cdfdde5f3 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/protocol/memcached.md @@ -0,0 +1,60 @@ +--- +type: docs +title: "Memcached protocol" +linkTitle: "Memcached protocol" +weight: 12 +--- +## Feature description +RPC protocol implemented based on memcached. `2.3.0` and above are supported. + +[Memcached](http://memcached.org/) is an efficient KV cache server. + +## scenes to be used +Relieve database pressure, improve interaction speed, etc. + +## How to use +### Import dependencies + +Starting from Dubbo 3, the Memcached protocol is no longer embedded in Dubbo, and an independent [module](/zh/release/dubbo-spi-extensions/#dubbo-rpc) needs to be introduced separately. +```xml + + org.apache.dubbo.extensions + dubbo-rpc-memcached + 1.0.0 + +``` + +### Register the address of memcached service +```java +RegistryFactory registryFactory = ExtensionLoader.getExtensionLoader(RegistryFactory.class).getAdaptiveExtension(); +Registry registry = registryFactory.getRegistry(URL.valueOf("zookeeper://10.20.153.10:2181")); +registry.register(URL.valueOf("memcached://10.20.153.11/com.foo.BarService?category=providers&dynamic=false&application=foo&group=member&loadbalance=consistenthash")); +``` + +### Referenced on the client side +**Do not need to be aware of the address of Memcached** + +use on client side + +```xml + +``` + +Or point-to-point direct connection + +```xml + +``` + +You can also use a custom interface +```xml + +``` + +Where "p:xxx" is the standard p tag of spring +```xml + +``` +If the method name is different from the standard method name of memcached, you need to configure the mapping relationship; + +The method name is recommended to be the same as the standard method name of memcached, namely: get(key), set(key, value), delete(key). \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/protocol/overview.md b/content/en/docs3-v2/java-sdk/reference-manual/protocol/overview.md new file mode 100644 index 000000000000..6ce31a3a1f08 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/protocol/overview.md @@ -0,0 +1,200 @@ +--- +type: docs +title: "Protocol Overview" +linkTitle: "Protocol Overview" +weight: 1 +--- + +Dubbo3 provides Triple (Dubbo3) and Dubbo2 protocols, which are native protocols of the Dubbo framework. In addition, Dubbo3 also integrates many third-party protocols and incorporates them into Dubbo's programming and service governance system. +Including gRPC, Thrift, JsonRPC, Hessian2, REST, etc. The following focuses on the Triple and Dubbo2 protocols. + +## protocol description + +The Triple protocol is the main protocol launched by Dubbo3. Triple means the third generation. Through the evolution of the Dubbo1.0/Dubbo2.0 two-generation protocol and the wave of technology standardization brought by cloud native, the new Dubbo3 protocol Triple came into being. + +### Select the RPC protocol + +The protocol is the core of RPC, which regulates the content and format of data transmission in the network. In addition to the necessary request and response data, it usually contains additional control data, such as the serialization method of a single request, timeout period, compression method, and authentication information. + +The content of the agreement consists of three parts +- Data exchange format: Define the byte stream content of RPC request and response objects in network transmission, also known as serialization mode +- Protocol structure: defines the list of fields, the semantics of each field, and the arrangement of different fields +- Protocols define how data is transmitted across networks by defining rules, formats, and semantics. A successful RPC requires both ends of the communication to be able to read and write network byte streams and convert objects according to the protocol. If the two ends cannot reach an agreement on the protocol used, there will be chickens talking with ducks, which cannot meet the needs of long-distance communication. + +![Protocol Selection](/imgs/v3/concepts/triple-protocol.png) + +The design of the RPC protocol needs to consider the following: +- Versatility: Unified binary format, cross-language, cross-platform, multi-transport layer protocol support +- Extensibility: protocol adds fields, upgrades, supports user extensions and additional business metadata +- Performance: As fast as it can be +- Penetration: can be identified and forwarded by various terminal devices: gateways, proxy servers, etc. + Generally, versatility and high performance cannot be achieved at the same time, and protocol designers need to make certain trade-offs. + +### HTTP/1.1 protocol + +Compared with the private RPC protocol directly built on the TCP transport layer, the remote call solution built on HTTP will have better versatility, such as WebServices or REST architecture, using HTTP + JSON can be said to be a de facto standard solution . + +Choosing to build on top of HTTP has two biggest advantages: + +- The semantics and scalability of HTTP well meet the requirements of RPC calls. +- Versatility, the HTTP protocol is supported by almost all devices on the network, and has good protocol penetration. + +But there are also obvious problems: + +- In a typical Request-Response model, there can only be one waiting Request request on a link at a time. HOL will be generated. +- Human Readable Headers, using a more general, human-readable header transfer format, but with considerably poorer performance +- No direct Server Push support, need to use workarounds such as Polling Long-Polling + +### gRPC protocol +The above mentioned the advantages and disadvantages of building the RPC protocol on top of the HTTP and TCP protocols. Compared with Dubbo built on the TCP transport layer, Google chose to define gRPC directly on top of the HTTP/2 protocol. +The advantages of gRPC are inherited from HTTP2 and Protobuf. + +- The HTTP2-based protocol is simple enough, with low learning costs for users, and naturally has server push/multiplexing/flow control capabilities +- Protobuf-based multi-language cross-platform binary compatibility, providing powerful unified cross-language capabilities +- The ecology based on the protocol itself is relatively rich, the natural support protocol of components such as k8s/etcd, and the de facto protocol standard of cloud native + +But there are also some problems + +- The support for service governance is relatively basic, and it is more inclined to the basic RPC function. The protocol layer lacks the necessary unified definition, and it is not easy for users to use it directly. +- The serialization method of strong binding protobuf requires high learning cost and transformation cost. For the existing monolingual users, the migration cost cannot be ignored + +### Finally choose the Triple protocol +In the end, we chose to be compatible with gRPC and use HTTP2 as the transport layer to build a new protocol, which is Triple. + +The rise of containerized applications and microservices has led to the development of techniques optimized for workload content. The traditional communication protocols (RESTFUL or other HTTP-based custom protocols) used in the client are difficult to meet the convenience requirements of the application in terms of performance, maintainability, scalability, and security. A cross-language, modular protocol will gradually become a new application development protocol standard. Since the gRPC protocol became a CNCF project in 2017, more and more infrastructure and businesses including k8s and etcd have begun to use the gRPC ecosystem. As a cloud-native microservice framework, Dubbo's new protocol is also perfectly compatible with gRPC . Moreover, Triple will also enhance and supplement some imperfect parts of the gRPC protocol. + +So, does the Triple protocol solve the series of problems we mentioned above? + +- In terms of performance: The Triple protocol adopts the strategy of separating metadata and payload, so that intermediate devices, such as gateways, can be avoided to parse and deserialize payload, thereby reducing response time. +- In terms of routing support, since metadata supports users to add custom headers, users can more conveniently divide clusters or perform routing according to headers, so that when publishing, there is more flexibility in switching grayscale or disaster recovery. +- In terms of security, it supports encrypted transmission capabilities such as two-way TLS authentication (mTLS). +- In terms of ease of use, in addition to supporting Protobuf serialization recommended by native gRPC, Triple supports other serializations such as Hessian/JSON in a general way, allowing users to upgrade to the Triple protocol more conveniently. For the original Dubbo service, modifying or adding the Triple protocol only needs to add a line of protocol configuration in the code block declaring the service, and the transformation cost is almost zero. + +## Triple protocol + +![Triple protocol communication method](/imgs/v3/concepts/triple.png) + +status quo + +- 1. Fully compatible with grpc, client/server can connect with native grpc client + +- 2. At present, it has been verified by large-scale production practice and has reached the production level + +Features and advantages + +- 1. Capable of cross-language intercommunication. Both the traditional multi-language multi-SDK mode and the Mesh cross-language mode require a more general and scalable data transmission format. + +- 2. Provide a more complete request model. In addition to the Request/Response model, it should also support Streaming and Bidirectional. + +- 3. Easy to expand, high penetration, including but not limited to Tracing / Monitoring and other support, should also be recognized by devices at all levels, gateway facilities, etc. can identify data packets, friendly to Service Mesh deployment, and reduce the difficulty of understanding for users. + +- 4. Multiple serialization methods support and smooth upgrade + +- 5. Support Java users to upgrade without awareness, no need to define cumbersome IDL files, and only need to simply modify the protocol name to easily upgrade to the Triple protocol + +### Triple protocol content introduction + +Further extension based on the grpc protocol + +- Service-Version → "tri-service-version" {Dubbo service version} +- Service-Group → "tri-service-group" {Dubbo service group} +- Tracing-ID → "tri-trace-traceid" {tracing id} +- Tracing-RPC-ID → "tri-trace-rpcid" {_span id _} +- Cluster-Info → "tri-unit-info" {cluster infomation} + +Among them, Service-Version and Service-Group respectively identify the version and group information of the Dubbo service, because the path of grpc declares the service name and method name, compared with the Dubbo protocol, it lacks version and group information; Tracing-ID, Tracing- RPC-ID is used for full-link tracking capabilities, which respectively represent tracing id and span id information; Cluster-Info represents cluster information, which can be used to build some flexible service management capabilities related to routing such as cluster division. + +### Triple Streaming + +Compared with the traditional unary method, the Triple protocol has more streaming RPC capabilities currently provided + +- What scenario is Streaming used for? + +In some application scenarios such as large file transmission and live broadcast, the consumer or provider needs to transmit a large amount of data with the peer. Since the amount of data in these cases is very large, there is no way to transmit it in one RPC packet. Transmission, so for these data packets, we need to fragment the data packets and transmit them through multiple RPC calls. If we transmit these split RPC data packets in parallel, then the relevant data packets after reaching the peer end It is unordered, and the received data needs to be sorted and spliced, and the related logic will be very complicated. But if we serially transmit the split RPC packets, the corresponding network transmission RTT and data processing delay will be very large. + +In order to solve the above problems, and to transmit a large amount of data between the consumer and the provider in a pipelined manner, the Streaming RPC model came into being. + +Through the Streaming RPC method of the Triple protocol, multiple user-mode long connections, Stream, will be established between the consumer and the provider. Multiple Streams can exist on the same TCP connection at the same time, and each Stream is identified by a StreamId, and the data packets on a Stream will be read and written sequentially. + +### Summarize + +In the world of APIs, the most important trend is the rise of standardized technologies. The Triple protocol is the main protocol launched by Dubbo3. It adopts a layered design, and its data exchange format is developed based on the Protobuf (Protocol Buffers) protocol, which has excellent serialization/deserialization efficiency. Of course, it also supports multiple serialization methods and many development languages. In the transport layer protocol, Triple chose HTTP/2, which has greatly improved its transmission efficiency compared with HTTP/1.1. In addition, as a mature open standard, HTTP/2 has rich security and flow control capabilities, and has good interoperability. Triple can not only be used for server-side service calls, but also support the interaction between browsers, mobile apps, and IoT devices and back-end services. At the same time, the Triple protocol seamlessly supports all service management capabilities of Dubbo3. + +Under the trend of Cloud Native, the interoperability requirements between cross-platform, cross-vendor, and cross-environment systems will inevitably give rise to RPC technology based on open standards, and gRPC conforms to the historical trend and has been more and more widely used. In the field of microservices, the proposal and implementation of the Triple protocol is a big step for Dubbo3 to move towards cloud-native microservices. + +##Dubbo2 + +### Protocol SPEC + +![/dev-guide/images/dubbo_protocol_header.jpg](/imgs/dev/dubbo_protocol_header.png) + + +- Magic - Magic High & Magic Low (16 bits) + + Identifies dubbo protocol with value: 0xdabb + +- Req/Res (1 bit) + + Identifies this is a request or response. Request - 1; Response - 0. + +- 2 Way (1 bit) + + Only useful when Req/Res is 1 (Request), expect for a return value from server or not. Set to 1 if need a return value from server. + +-Event (1 bit) + +Identifies an event message or not, for example, heartbeat event. Set to 1 if this is an event. + +-Serialization ID (5 bits) + +Identifies serialization type: the value for fastjson is 6. + +- Status (8 bits) + + Only useful when Req/Res is 0 (Response), identifies the status of response + + - 20 - OK + - 30 - CLIENT_TIMEOUT + - 31 - SERVER_TIMEOUT + - 40 - BAD_REQUEST + - 50 - BAD_RESPONSE + - 60 - SERVICE_NOT_FOUND + - 70 - SERVICE_ERROR + - 80 - SERVER_ERROR + - 90 - CLIENT_ERROR + - 100 - SERVER_THREADPOOL_EXHAUSTED_ERROR + +- Request ID (64 bits) + + Identifies an unique request. Numeric (long). + +- Data Length (32) + + Length of the content (the variable part) after serialization, counted by bytes. Numeric (integer). + +-Variable Part + +Each part is a byte[] after serialization with specific serialization type, identifies by Serialization ID. + +Every part is a byte[] after serialization with specific serialization type, identifies by Serialization ID + +1. If the content is a Request (Req/Res = 1), each part consists of the content, in turn is: + - Dubbo version + - Service name + - Service version + -Method name + -Method parameter types + -Method arguments + -Attachments + +1. If the content is a Response (Req/Res = 0), each part consists of the content, in turn is: + - Return value type, identifies what kind of value returns from server side: RESPONSE_NULL_VALUE - 2, RESPONSE_VALUE - 1, RESPONSE_WITH_EXCEPTION - 0. + - Return value, the real value returns from server. + + +> For the (Variable Part) variable length part, when the current version of the dubbo framework uses json serialization, an extra line break is added between each part of the content as a separator. Please add an extra line break after each part of the Variable Part, such as : + +``` +Dubbo version bytes (line break) +Service name bytes (newline) +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/protocol/redis.md b/content/en/docs3-v2/java-sdk/reference-manual/protocol/redis.md new file mode 100644 index 000000000000..94d5ae1e86b5 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/protocol/redis.md @@ -0,0 +1,61 @@ +--- +type: docs +title: "Redis protocol" +linkTitle: "Redis Protocol" +weight: 9 +--- + + +## Feature description +RPC protocol implemented based on Redis. `2.3.0` and above are supported. + +[Redis](http://redis.io) is an efficient KV storage server. + +## scenes to be used + +Caching, current limiting, distributed locks, etc. + +## How to use + +### Import dependencies + +Starting from Dubbo 3, the Redis protocol is no longer embedded in Dubbo, and an independent [module](/zh/release/dubbo-spi-extensions/#dubbo-rpc) needs to be introduced separately. +```xml + + org.apache.dubbo.extensions + dubbo-rpc-redis + 1.0.0 + +``` + + +### Register the address of the redis service +```java +RegistryFactory registryFactory = ExtensionLoader.getExtensionLoader(RegistryFactory.class).getAdaptiveExtension(); +Registry registry = registryFactory.getRegistry(URL.valueOf("zookeeper://10.20.153.10:2181")); +registry.register(URL.valueOf("redis://10.20.153.11/com.foo.BarService?category=providers&dynamic=false&application=foo&group=member&loadbalance=consistenthash")); +``` + +### Referenced on the client side +Does not need to be aware of Redis addresses + +On the client side use: +```xml + +``` +Or point-to-point direct connection: +```xml + +``` +It is also possible to use a custom interface: +```xml + +``` + +Where "p:xxx" is the standard p tag of spring +```xml + +``` +The method name is suggested to be the same as the standard method name of redis, namely: get(key), set(key, value), delete(key). + +If the method name is different from the standard method name of redis, you need to configure the mapping relationship: \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/protocol/rest.md b/content/en/docs3-v2/java-sdk/reference-manual/protocol/rest.md new file mode 100644 index 000000000000..e20537a33ba7 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/protocol/rest.md @@ -0,0 +1,742 @@ +--- +type: docs +title: "Rest protocol" +linkTitle: "Rest protocol" +weight: 4 +--- + +Support for REST calls based on the standard Java REST API - JAX-RS 2.0 (short for Java API for RESTful Web Services) + +### Quick Start + +It is relatively simple to develop a REST-style service in dubbo. Let's take a simple service for registered users as an example. + +The function of this service is to provide the following URL (note: this URL is not fully in line with REST style, but it is simpler and more practical) +``` +http://localhost:8080/users/register +``` +And any client can POST a JSON string containing user information to the above URL to complete user registration. + +First, develop the interface of the service + +```java +public class UserService { + void registerUser(User user); +} +``` + +Then, develop the implementation of the service + +```java +@Path("users") +public class UserServiceImpl implements UserService { + + @POST + @Path("register") + @Consumes({MediaType. APPLICATION_JSON}) + public void registerUser(User user) { + // save the user... + } +} +``` +The above implementation is very simple, but since the REST service is to be published to a specified URL for access by clients of any language or even browsers, several standard annotations of JAX-RS are added here for related configuration. + +@Path("users"): Specifies that the relative path of the URL to access UserService is /users, ie http://localhost:8080/users + +@Path("register"): Specifies that the relative path of the URL to access the registerUser() method is /register, combined with the path specified by the previous @Path for UserService, the full path to call UserService.register() is http://localhost :8080/users/register + +@POST: Specifies to access registerUser() with the HTTP POST method + +@Consumes({MediaType.APPLICATION_JSON}): Specifies that registerUser() receives data in JSON format. The REST framework will automatically deserialize the JSON data into a User object + +Finally, add this service in the spring configuration file to complete all service development work + + ```xml + + + + + + + + +``` + +### Detailed explanation of REST service provider + +Next, we expand the UserService in the "Quick Start" to further demonstrate the development points of the REST service provider in dubbo. + +### Implementation of HTTP POST/GET + +In the REST service, although it is recommended to use the four standard methods POST, DELETE, PUT, and GET in the HTTP protocol to implement common "addition, deletion, modification and query" respectively, in practice, we generally use POST directly to implement "addition and modification", and GET to implement Just implement "delete check" (DELETE and PUT will even be blocked by some firewalls). + +The implementation of POST has been briefly demonstrated before. Here, we add a function of obtaining registered user information to UserService to demonstrate the implementation of GET. + +This function is to enable the client to obtain user profiles with different IDs by accessing the following URLs + +``` +http://localhost:8080/users/1001 +http://localhost:8080/users/1002 +http://localhost:8080/users/1003 +``` + +Of course, user profiles with different IDs can also be accessed through other forms of URLs, for example + +``` +http://localhost:8080/users/load?id=1001 +``` + +JAX-RS natively supports all of these forms. But the above form of including query parameters in the URL path (http://localhost:8080/users/1001) is more in line with the general habits of REST, so it is recommended for everyone to use. Next, we will add a getUser() method to UserService to achieve this form of URL access + +```java +@GET +@Path("{id : \\d+}") +@Produces({MediaType. APPLICATION_JSON}) +public User getUser(@PathParam("id") Long id) { + //... +} +``` + +@GET: Specifies to use the HTTP GET method to access + +@Path("{id : \\d+}"): According to the functional requirements above, the URL to access getUser() should be "http://localhost:8080/users/ + any number", and this number should be made Pass the getUser() method as a parameter. In the annotation configuration here, {id: xxx} in the middle of @Path specifies that the URL relative path contains a parameter named id, and its value will be automatically passed to the method parameter modified with @PathParam("id") below id. {id: followed by \\d+ is a regular expression, specifying that the id parameter must be a number. + +@Produces({MediaType.APPLICATION_JSON}): Specify getUser() to output data in JSON format. The framework will automatically serialize the User object into JSON data. + +### Annotation is placed in the interface class or the implementation class + +The development of REST services in Dubbo is mainly configured through JAX-RS annotations. In the above examples, we put the annotations in the service implementation class. But in fact, we can also put the annotation on the interface of the service. The two methods are completely equivalent, for example: + +```java +@Path("users") +public interface UserService { + + @GET + @Path("{id : \\d+}") + @Produces({MediaType. APPLICATION_JSON}) + User getUser(@PathParam("id") Long id); +} +``` + +In general applications, we recommend placing the annotation in the service implementation class, so that the location of the annotation and the java implementation code are closer, making it easier to develop and maintain. In addition, more importantly, we generally tend to avoid pollution of the interface, and maintain the purity and wide applicability of the interface. + +However, as mentioned later, if we want to use the consumer directly developed by dubbo to access this service, the annotation must be placed on the interface. + +If annotations are added to both the interface and the implementation class, the annotation configuration of the implementation class will take effect, and the annotation on the interface will be ignored directly. + +### Support for multiple data formats such as JSON and XML + +The REST service developed in dubbo can support the transmission of data in multiple formats at the same time to provide clients with maximum flexibility. Among them we currently have added extra functionality especially for the most commonly used formats JSON and XML. + +For example, if we want the getUser() method in the above example to support returning data in JSON and XML formats, we only need to include both formats in the annotation + +```java +@Produces({MediaType. APPLICATION_JSON, MediaType. TEXT_XML}) +User getUser(@PathParam("id") Long id); +``` + +Or you can directly use strings (wildcards are also supported) to represent MediaType + +```java +@Produces({"application/json", "text/xml"}) +User getUser(@PathParam("id") Long id); +``` + +If all methods support the same type of input and output data format, we don't need to configure each method, just add annotation to the service class + +```java +@Path("users") +@Consumes({MediaType. APPLICATION_JSON, MediaType. TEXT_XML}) +@Produces({MediaType. APPLICATION_JSON, MediaType. TEXT_XML}) +public class UserServiceImpl implements UserService { + //... +} + +``` + +In the case that a REST service supports multiple data formats at the same time, according to the JAX-RS standard, the MIME header (content-type and accept) in HTTP is generally used to specify which format data is currently wanted. + +But in dubbo, we also automatically support the method commonly used in the industry at present, that is, use a URL suffix (.json and .xml) to specify the desired data format. For example, after adding the above annotation, direct access to http://localhost:8888/users/1001.json means to use json format, and direct access to http://localhost:8888/users/1002.xml means to use xml format, Simpler and more intuitive than using HTTP Header. The REST APIs of Twitter, Weibo, etc. all use this method. +If you add neither HTTP header nor suffix, dubbo's REST will give priority to the data format that ranks first in the above annotation definition. + +> Note: To support XML format data here, you can use MediaType.TEXT_XML or MediaType.APPLICATION_XML in annotation, but TEXT_XML is more commonly used, and if you want to use the above URL suffix method to specify the data format, you can only use Only when it is configured as TEXT_XML can it take effect. + +### Chinese character support + +In order to output Chinese characters normally in dubbo REST, like usual Java web applications, we need to set the contentType of the HTTP response to UTF-8 encoding. + +Based on the standard usage of JAX-RS, we only need to do the following annotation configuration: + +```java +@Produces({"application/json; charset=UTF-8", "text/xml; charset=UTF-8"}) +User getUser(@PathParam("id") Long id); +``` + +For the convenience of users, we directly added a support class in dubbo REST to define the above constants, which can be used directly to reduce the possibility of errors. + +```java +@Produces({ContentType. APPLICATION_JSON_UTF_8, ContentType. TEXT_XML_UTF_8}) +User getUser(@PathParam("id") Long id); +``` + +### Additional requirements for XML data format + +Since the implementation of JAX-RS generally uses the standard JAXB (Java API for XML Binding) to serialize and deserialize XML format data, we need to add a class-level JAXB annotation for each object to be transmitted in XML, Otherwise serialization will report an error. For example, add the following to the User returned in getUser() + +```java +@XmlRootElement +public class User implements Serializable { + //... +} +``` + +In addition, if the return values in the service method are Java primitive types (such as int, long, float, double, etc.), it is best to add a layer of wrapper objects for them, because JAXB cannot directly serialize primitive types. + +For example, we want the aforementioned registerUser() method to return the ID number generated by the server for the user: + +```java +long registerUser(User user); +``` + +Since primitive types are not supported by JAXB serialization, add a wrapper object: + +```java +@XmlRootElement +public class RegistrationResult implements Serializable { + + private Long id; + + public RegistrationResult() { + } + + public RegistrationResult(Long id) { + this.id = id; + } + + public Long getId() { + return id; + } + + public void setId(Long id) { + this.id = id; + } +} +``` + +And modify the service method: + +```java +RegistrationResult registerUser(User user); +``` + +This not only solves the problem of XML serialization, but also makes the returned data conform to the specifications of XML and JSON. For example, in JSON, the return would be of the form + +```javascript +{"id": 1001} +``` + +If no wrapper is added, the JSON return value will be directly + +``` +1001 +``` + +In XML, the return value after adding wrapper will be: + +```xml + + 1002 + +``` + +This kind of wrapper object actually uses the so-called Data Transfer Object (DTO) pattern, and using DTO can also do more useful customizations for the transferred data. + +### Custom serialization + +As mentioned above, the underlying implementation of REST will automatically serialize/deserialize between service objects and JSON/XML data formats. However, in some scenarios, if you feel that this automatic conversion does not meet the requirements, you can customize it. + +The REST implementation in Dubbo uses JAXB for XML serialization and Jackson for JSON serialization, so you can customize the mapping by adding JAXB or Jackson annotations to objects. + +For example, custom object properties map to XML element names: + +```java +@XmlRootElement +@XmlAccessorType(XmlAccessType.FIELD) +public class User implements Serializable { + + @XmlElement(name="username") + private String name; +} +``` + +Map custom object properties to JSON field names: + +```java +public class User implements Serializable { + + @JsonProperty("username") + private String name; +} +``` + +For more information, please refer to the official documentation of JAXB and Jackson, or google yourself. + +### Configure the implementation of REST Server + +Currently in dubbo, we support the implementation of 5 embedded rest servers, and at the same time support the implementation of the rest server using an external application server. The rest server can be implemented through the following configuration: + +```xml + +``` + +The above configuration uses the embedded jetty as the rest server. At the same time, if the server attribute is not configured, the rest protocol also uses jetty by default. jetty is a very mature java servlet container, and has been well integrated with dubbo (currently, among the five embedded servers, only jetty and tomcat and tjws described later have seamlessly integrated with dubbo monitoring system), Therefore, if your dubbo system is a separate startup process, you can directly use jetty by default. + + +```xml + +``` + +The above configuration uses the embedded tomcat as the rest server. On the embedded tomcat, the performance of REST is much better than that on jetty (see the benchmark test later), it is recommended to use tomcat in the scenario that requires high performance. + +```xml + +``` + +The above configuration uses embedded netty as the rest server. (TODO more contents to add) + +```xml + (tjws is now deprecated) + +``` + +The above configuration uses the embedded tjws or Sun HTTP server as the rest server. These two server implementations are very lightweight, very convenient for quick start-up in integration tests, and of course they can also be used in production environments with low load. Note: tjws is currently deprecated because it doesn't work well with the servlet 3.1 API. + +If your dubbo system is not a separate startup process, but is deployed in a Java application server, it is recommended that you use the following configuration + +```xml + +``` + +By setting the server as a servlet, dubbo will use the servlet container of the external application server as the rest server. At the same time, add the following configuration to the web.xml of the dubbo system + +```xml + + + contextConfigLocation + /WEB-INF/classes/META-INF/spring/dubbo-demo-provider.xml + + + + org.apache.dubbo.remoting.http.servlet.BootstrapListener + + + + org.springframework.web.context.ContextLoaderListener + + + + dispatcher + org.apache.dubbo.remoting.http.servlet.DispatcherServlet + 1 + + + + dispatcher + /* + + +``` + +That is, dubbo's BootstrapListener and DispatherServlet must be added to web.xml to complete the integration of dubbo's REST function with the external servlet container. + +> Note: If you use spring's ContextLoaderListener to load spring, you must ensure that BootstrapListener is configured before ContextLoaderListener, otherwise dubbo initialization will fail. + +In fact, you can still use the embedded server in this scenario, but the servlet container of the external application server is often more powerful than the embedded server (especially if you are deploying to a more robust and scalable WebLogic, WebSphere, etc.), and Sometimes it is also convenient for unified management, monitoring, etc. on the application server. + +### Get context information + +In the remote call, there may be many kinds of context information worth obtaining. Here, the client IP is taken as an example. + +In dubbo's REST, we have two ways to get client IP. + +The first way, using JAX-RS standard @Context annotation + +```java +public User getUser(@PathParam("id") Long id, @Context HttpServletRequest request) { + System.out.println("Client address is " + request.getRemoteAddr()); +} +``` + +After modifying a method parameter of getUser() with Context, you can inject the current HttpServletRequest into it, and then directly call the servlet api to obtain the IP. + +> Note: This method can only work when the server is set to tjws, tomcat, jetty or servlet, because only these server implementations provide a servlet container. In addition, the standard JAX-RS also supports using @Context to modify an instance field of the service class to obtain HttpServletRequest, but we do not support this in dubbo. + +The second way, use RpcContext commonly used in dubbo + +```java +public User getUser(@PathParam("id") Long id) { + System.out.println("Client address is " + RpcContext.getContext().getRemoteAddressString()); +} +``` + +> Note: This method can only work when setting server="jetty" or server="tomcat" or server="servlet" or server="tjws". In addition, currently dubbo's RpcContext is a relatively intrusive usage, and we are likely to refactor it in the future. + +If you want to keep your project compatible with JAX-RS and run without dubbo in the future, please choose the first method. If you want a more elegant service interface definition, please choose the second way. + +In addition, in the latest dubbo rest, it is also supported to obtain HttpServletRequest and HttpServletResponse through RpcContext to provide greater flexibility for users to implement some complex functions, such as accessing HTTP Header in dubbo standard filter. An example of usage is as follows + +```java +if (RpcContext.getContext().getRequest() != null && RpcContext.getContext().getRequest() instanceof HttpServletRequest) { + System.out.println("Client address is " + ((HttpServletRequest) RpcContext.getContext().getRequest()).getRemoteAddr()); +} + +if (RpcContext.getContext().getResponse() != null && RpcContext.getContext().getResponse() instanceof HttpServletResponse) { + System.out.println("Response object from RpcContext: " + RpcContext.getContext().getResponse()); +} +``` + +> Note: In order to maintain the neutrality of the protocol, RpcContext.getRequest() and RpcContext.getResponse() return only an Object class, and may be null. So, you have to do null and type checking yourself. + +> Note: Only when server="jetty" or server="tomcat" or server="servlet" is set, can you get HttpServletRequest and HttpServletResponse correctly through the above method, because only these servers implement the servlet container. + +In order to simplify programming, you can also use generics to directly obtain specific types of request/response: + +```java +if (RpcContext. getContext(). getRequest(HttpServletRequest. class) != null) { + System.out.println("Client address is " + RpcContext.getContext().getRequest(HttpServletRequest.class).getRemoteAddr()); +} + +if (RpcContext. getContext(). getResponse(HttpServletResponse. class) != null) { + System.out.println("Response object from RpcContext: " + RpcContext.getContext().getResponse(HttpServletResponse.class)); +} +``` + +If the request/response does not conform to the specified type, null will also be returned here. + +### Configure port number and Context Path + +The rest protocol in dubbo will use port 80 by default. If you want to modify the port, configure it directly: + +```xml + +``` + +In addition, as mentioned earlier, we can use @Path to configure the URL relative path of a single rest service. But in fact, we can also set a basic relative path that is applicable to all rest services, that is, the context path that is often said in java web applications. + +Just add the following contextpath attribute: + +```xml + +``` + +Take the previous code as an example: + +```java +@Path("users") +public class UserServiceImpl implements UserService { + + @POST + @Path("register") + @Consumes({MediaType. APPLICATION_JSON}) + public void registerUser(User user) { + // save the user... + } +} +``` + +Now the full access path of registerUser() + +``` +http://localhost:8888/services/users/register +``` + +Note: If you choose an external application server as the rest server, that is, configure + +```xml + +``` + +You must ensure that the port and contextpath set here are consistent with the port of the external application server and the context path of DispatcherServlet (that is, webapp path plus servlet url pattern). For example, for an application deployed as the tomcat ROOT path, the contextpath here must be exactly the same as `` of DispacherServlet in web.xml: + +```xml + + dispatcher + /services/* + +``` + +### Configure the number of threads and IO threads + +Thread pool size can be configured for rest services + +```xml + +``` + +> Note: The current thread pool settings only take effect when server="netty" or server="jetty" or server="tomcat". In addition, if server="servlet", since the external application server is enabled as the rest server at this time, it is not controlled by dubbo, so the thread pool setting here is also invalid. + +If you choose netty server, you can also configure the number of IO worker threads of Netty + +```xml + +``` + +### Configure long connection + +The rest service in Dubbo is accessed by http long connection by default, if you want to switch to short connection, configure it directly + +```xml + +``` + +> Note: This configuration is currently only valid for server="netty" and server="tomcat". + +### Configure the maximum number of HTTP connections + +The maximum number of HTTP connections that the server provider can receive at the same time can be configured to prevent the REST server from being overwhelmed by too many connections, as a basic self-protection mechanism + +```xml + +``` + +Of course, since this configuration is effective for the consumer side, it can also be configured on the consumer side + +```xml + +``` + +However, in general we recommend configuration to provide such configuration on the service provider side. According to dubbo's official documentation: "Providers should be configured with as many properties as possible on the Consumer side, so that Provider implementers can think about Provider service characteristics and service quality issues from the very beginning." + +> Note: If dubbo's REST service is published to non-dubbo clients, the configuration on `` here is completely invalid, because such clients are not controlled by dubbo. + + +### Replace part of Spring XML configuration with Annotation + +All the above discussions are based on the xml configuration of dubbo in spring. However, dubbo/spring itself also supports the use of annotations for configuration, so we can also follow the steps in dubbo's official documentation to add related annotations to the implementation of REST services to replace some xml configurations, for example + +```java +@Service(protocol = "rest") +@Path("users") +public class UserServiceImpl implements UserService { + + @Autowired + private UserRepository userRepository; + + @POST + @Path("register") + @Consumes({MediaType. APPLICATION_JSON}) + public void registerUser(User user) { + // save the user + userRepository. save(user); + } +} +``` + +The configuration of annotation is simpler and more precise, and it is usually easier to maintain (of course, modern IDEs can support such as class name refactoring in xml, so in terms of specific use cases here, xml is also very maintainable). And xml is less intrusive to the code, especially conducive to dynamic modification of configuration, especially if you want to configure connection timeout, maximum number of connections per client, cluster strategy, weight, etc. for a single service. In addition, especially for complex applications or modules, xml provides a central point to cover all components and configurations, which is more clear at a glance and generally more convenient for long-term project maintenance. + +Of course, there is no absolute advantage or disadvantage in choosing which configuration method to choose, and it has nothing to do with personal preference. + +### Add custom Filter, Interceptor, etc. + +Dubbo's REST also supports JAX-RS standard Filter and Interceptor to facilitate customized interception of REST request and response processes. + +Among them, Filter is mainly used to access and set HTTP request and response parameters, URI, etc. For example, to set the cache header of an HTTP response: + +```java +public class CacheControlFilter implements ContainerResponseFilter { + + public void filter(ContainerRequestContext req, ContainerResponseContext res) { + if (req. getMethod(). equals("GET")) { + res.getHeaders().add("Cache-Control", "someValue"); + } + } +} +``` + +Interceptor is mainly used to access and modify input and output byte streams, for example, manually add GZIP compression + +```java +public class GZIPWriterInterceptor implements WriterInterceptor { + + @Override + public void aroundWriteTo(WriterInterceptorContext context) + throws IOException, WebApplicationException { + OutputStream outputStream = context. getOutputStream(); + context.setOutputStream(new GZIPOutputStream(outputStream)); + context. proceed(); + } +} +``` + +In standard JAX-RS applications, we generally add @Provider annotations for Filter and Interceptor, and then JAX-RS runtime will automatically discover and enable them. In dubbo, we register Filter and Interceptor by adding XML configuration: + +```xml + +``` + +Here, we can add all three types of objects, Filter, Interceptor and DynamicFeature, to the `extension` attribute, and separate them with commas. (DynamicFeature is another interface, which can facilitate us to enable Filter and Interceptor more dynamically. If you are interested, please google yourself.) + +Of course, dubbo itself also supports the concept of Filter, but the Filter and Interceptor we discuss here are closer to the bottom layer of the protocol implementation. Compared with Dubbo's filter, it can be customized at a lower level. + +> Note: The XML attribute here is called extension, not interceptor or filter, because in addition to Interceptor and Filter, we will add more extension types in the future. + +If the consumer side of REST is also a dubbo system (see the discussion below), you can also configure Interceptor and Filter for the consumer side in a similar way. But note that the consumer-side Filter and the provider-side Filter in JAX-RS are two different interfaces. For example, in the previous example, the server is the ContainerResponseFilter interface, while the consumer corresponds to the ClientResponseFilter: + +```java +public class LoggingFilter implements ClientResponseFilter { + + public void filter(ClientRequestContext reqCtx, ClientResponseContext resCtx) throws IOException { + System.out.println("status: " + resCtx.getStatus()); +System.out.println("date: " + resCtx.getDate()); +System.out.println("last-modified: " + resCtx.getLastModified()); +System.out.println("location: " + resCtx.getLocation()); +System.out.println("headers:"); +for (Entry> header : resCtx. getHeaders(). entrySet()) { + System.out.print("\t" + header.getKey() + " :"); +for (String value : header. getValue()) { +System.out.print(value + ", "); +} +System.out.print("\n"); +} +System.out.println("media-type: " + resCtx.getMediaType().getType()); + } +} +``` + +### Add custom Exception handling + +Dubbo's REST also supports JAX-RS standard ExceptionMapper, which can be used to customize the HTTP response that should be returned after a specific exception occurs. + +```java +public class CustomExceptionMapper implements ExceptionMapper { + + public Response toResponse(NotFoundException e) { + return Response.status(Response.Status.NOT_FOUND).entity("Oops! the requested resource is not found!").type("text/plain").build(); + } +} +``` + +Similar to Interceptor and Filter, it can be enabled by adding it to the XML configuration file + +```xml + +``` + +### Configure HTTP log output + +Dubbo rest supports outputting header fields and body message bodies in all HTTP requests/responses. + +Add the following built-in REST filter in the XML configuration: + +```xml + +``` + +Then configure to turn on INFO level log output for at least org.apache.dubbo.rpc.protocol.rest.support in the logging configuration, for example, configure in log4j.xml + +```xml + + + + +``` + +Of course, you can also directly open INFO level log output in ROOT logger + +```xml + + + + +``` + +Then something similar to the following will be output in the log + +``` +The HTTP headers are: +accept: application/json;charset=UTF-8 +accept-encoding: gzip, deflate +connection: Keep-Alive +content-length: 22 +content-type: application/json +host: 192.168.1.100:8888 +user-agent: Apache-HttpClient/4.2.1 (java 1.5) +``` + +``` +The contents of request body are: +{"id":1,"name":"dang"} +``` + +After HTTP log output is enabled, in addition to the performance overhead of normal log output, additional overhead will be generated when parsing HTTP requests, for example, because additional memory buffers need to be established to prepare data for log output. + +### Validation of input parameters + +Dubbo's rest supports Java standard bean validation annotation (JSR 303) for input validation http://beanvalidation.org/ + +In order to be consistent with other dubbo remote call protocols, the annotation for verification in rest must be placed on the service interface, for example + +```java +public interface UserService { + + User getUser(@Min(value=1L, message="User ID must be greater than 1") Long id); +} + +``` + +Of course, in many other bean validation application scenarios, the annotation is placed on the implementation class instead of the interface. At least one advantage of putting the annotation on the interface is that dubbo clients can share the information of this interface, and dubbo can complete the input verification locally without even making remote calls. + +Then open the validation in the XML configuration according to dubbo's standard way: + +```xml + +``` + +In many other remote call protocols of dubbo, if the input verification fails, `RpcException` is directly thrown to the client, but in rest, since the client is often a non-dubbo or even non-java system, it is inconvenient to directly throw a Java exception . Therefore, currently we return validation errors as XML + +```xml + + + getUserArgument0 + User ID must be greater than 1 + 0 + + +``` + +Return values in other data formats will be supported later. As for how to internationalize the validation error message, just refer to the relevant documents of bean validation. + +If you think that the default validation error return format does not meet your requirements, you can add a custom ExceptionMapper to freely customize the error return format as described in the above section. It should be noted that this ExceptionMapper must use a generic declaration to catch dubbo's RpcException, in order to successfully override the default exception handling strategy of dubbo rest. In order to simplify the operation, in fact, the easiest way here is to directly inherit the RpcExceptionMapper of dubbo rest, and override the method of handling verification exceptions + +```java +public class MyValidationExceptionMapper extends RpcExceptionMapper { + + protected Response handleConstraintViolationException(ConstraintViolationException cve) { + ViolationReport report = new ViolationReport(); + for (ConstraintViolation cv : cve. getConstraintViolations()) { + report.addConstraintViolation(new RestConstraintViolation( + cv.getPropertyPath().toString(), + cv. getMessage(), + cv.getInvalidValue() == null ? "null" : cv.getInvalidValue().toString())); + } + // Use json output instead of xml output + return Response.status(Response.Status.INTERNAL_SERVER_ERROR).entity(report).type(ContentType.APPLICATION_JSON_UTF_8).build(); + } +} +``` + +Then add this ExceptionMapper to the XML configuration: + +```xml + +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/protocol/rmi.md b/content/en/docs3-v2/java-sdk/reference-manual/protocol/rmi.md new file mode 100644 index 000000000000..74fa79f7bbf9 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/protocol/rmi.md @@ -0,0 +1,96 @@ +--- +type: docs +title: "Rmi agreement" +linkTitle: "Rmi Agreement" +weight: 8 +--- + +## Feature description +The RMI protocol is implemented using the JDK standard `java.rmi.*`, using blocking short connections and JDK standard serialization. + +* Number of connections: multiple connections +* Connection method: short connection +* Transport protocol: TCP +* Transmission method: synchronous transmission +* Serialization: Java standard binary serialization +* Scope of application: Incoming and outgoing parameter packets are mixed in size, the number of consumers and providers is similar, and files can be transferred. +* Applicable scenarios: regular remote service method calls, interoperability with native RMI services + +#### Constraints + +* Parameters and return values need to implement `Serializable` interface +* The timeout in dubbo configuration is invalid for RMI, you need to use the java startup parameter setting: `-Dsun.rmi.transport.tcp.responseTimeout=3000`, see the following RMI configuration + + +## scenes to be used + +It is a set of Java APIs that supports the development of distributed applications, and realizes the method calling of programs between different operating systems. + +## How to use + +### Import dependencies + +Starting from Dubbo 3, the RMI protocol is no longer embedded in Dubbo, and an independent [module](/zh/release/dubbo-spi-extensions/#dubbo-rpc) needs to be introduced separately. +```xml + + org.apache.dubbo.extensions + dubbo-rpc-rmi + 1.0.0 + +``` + +```sh +java -Dsun.rmi.transport.tcp.responseTimeout=3000 +``` +For more RMI optimization parameters, please see [JDK Documentation](https://docs.oracle.com/javase/6/docs/technotes/guides/rmi/sunrmiproperties.html) + +### Interface Description +If the service interface inherits the `java.rmi.Remote` interface, it can interoperate with native RMI, namely: + +* The provider uses Dubbo's RMI protocol to expose the service, and the consumer directly uses the standard RMI interface to call, +* Or the provider uses standard RMI to expose the service, and the consumer uses Dubbo's RMI protocol to call. + +If the service interface does not extend the `java.rmi.Remote` interface: + +* By default, Dubbo will automatically generate a `com.xxx.XxxService$Remote` interface, inherit the `java.rmi.Remote` interface, and expose the service through this interface, +* But if `` is set, the `$Remote` interface will not be generated, and the service will be exposed using Spring’s `RmiInvocationHandler` interface, which is compatible with Spring. + +**Define the RMI protocol** + +```xml + +``` + +**SET DEFAULT PROTOCOL** + +```xml + +``` + +**Set the protocol of a service** + +```xml + +``` + +**Multiple ports** + +```xml + + + + +``` + +**Spring Compatibility** + +```xml + +``` + + +> - **If you are using RMI to provide services for external access,** there should be no risk of attack in the company's intranet environment. + +> - **At the same time, if the application relies on the old common-collections package,** dubbo will not depend on this package. Please check whether your application has used it. + +> - ** There is a deserialization security risk. ** Please check the application: Please upgrade commons-collections3 to [3.2.2](https://commons.apache.org/proper/commons-collections/release_3_2_2.html); Please upgrade commons-collections4 to [4.1](https://commons.apache.org/proper/commons-collections/release_4_1.html). The new version of commons-collections solves this problem. \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/protocol/thrift.md b/content/en/docs3-v2/java-sdk/reference-manual/protocol/thrift.md new file mode 100644 index 000000000000..b8f07fb91a6d --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/protocol/thrift.md @@ -0,0 +1,51 @@ +--- +type: docs +title: "Thrift protocol" +linkTitle: "Thrift protocol" +weight: 7 +--- + + +## Feature description +The thrift protocol currently supported by dubbo is an extension of the thrift native protocol, adding some additional header information on the basis of the native protocol, such as service name, magic number, etc. `2.3.0` and above are supported. + +[Thrift](http://thrift.apache.org) is an RPC framework donated by Facebook to Apache. + +Using the dubbo thrift protocol also needs to use thrift's idl compiler to compile and generate the corresponding java code, and some enhancements will be made in this regard in subsequent versions. + +## scenes to be used + +For SOA standard RPC framework. + +## How to use +### Dependencies + +Starting from Dubbo 3, the Thrift protocol is no longer embedded in Dubbo, and an independent [module](/zh/release/dubbo-spi-extensions/#dubbo-rpc) needs to be introduced separately. +```xml + + org.apache.dubbo.extensions + dubbo-rpc-native-thrift + 1.0.0 + +``` + + +```xml + + org.apache.thrift + libthrift + 0.8.0 + +``` + +### All services share one port + +Incompatible with native Thrift +```xml + +``` + +[Example code in dubbo project](https://github.com/apache/dubbo/tree/master/dubbo-rpc/dubbo-rpc-thrift/src/test/java/org/apache/dubbo/rpc/protocol /thrift) + + +> Thrift does not support null values, ie: you cannot pass null values in the protocol \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/protocol/triple/_index.md b/content/en/docs3-v2/java-sdk/reference-manual/protocol/triple/_index.md new file mode 100755 index 000000000000..e46f7bd5288f --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/protocol/triple/_index.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "Triple Protocol" +linkTitle: "Triple Protocol" +weight: 3 +--- \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/protocol/triple/guide.md b/content/en/docs3-v2/java-sdk/reference-manual/protocol/triple/guide.md new file mode 100644 index 000000000000..b90e4d63c842 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/protocol/triple/guide.md @@ -0,0 +1,278 @@ +--- +type: docs +title: "Instructions for Use" +linkTitle: "Instructions for use" +weight: 2 +--- + +The Triple protocol is the main protocol of Dubbo3, fully compatible with gRPC over HTTP/2, and has expanded load balancing and flow control related mechanisms at the protocol level. This document is intended to guide users to use the Triple protocol correctly. + +Before starting, you need to decide the serialization method used by the service. If it is a new service, it is recommended to use protobuf as the default serialization, which will have better performance and cross-language effects. If the original service wants to upgrade the protocol, the Triple protocol already supports other serialization methods, such as Hessian / JSON, etc. + + + +### Protobuf + +1. Write the IDL file + ```protobuf + syntax = "proto3"; + + option java_multiple_files = true; + option java_package = "org.apache.dubbo.hello"; + option java_outer_classname = "HelloWorldProto"; + option objc_class_prefix = "HLW"; + + package helloworld; + + // The request message containing the user's name. + message HelloRequest { + string name = 1; + } + + // The response message containing the greetings + message HelloReply { + string message = 1; + } + ``` + +2. Add the extension and plugin for compiling protobuf (take maven as an example) + ```xml + + + kr.motd.maven + os-maven-plugin + 1.6.1 + + + + + org.xolstice.maven.plugins + protobuf-maven-plugin + 0.6.1 + + com.google.protobuf:protoc:3.7.1:exe:${os.detected.classifier} + triple-java + build/generated/source/proto/main/java + + + + + compile + test-compile + + + + + + ``` + +3. Build/compile to generate protobuf Message class + ```shell + $ mvn clean install + ``` + +### Unary way + +4. Writing the Java interface + ```java + import org.apache.dubbo.hello.HelloReply; + import org.apache.dubbo.hello.HelloRequest; + + public interface IGreeter { + /** + * 
+         * Sends a greeting
+         *
+ */ + HelloReply sayHello(HelloRequest request); + + } + ``` + +5. Create a Provider + ```java + public static void main(String[] args) throws InterruptedException { + ServiceConfig service = new ServiceConfig<>(); + service.setInterface(IGreeter.class); + service.setRef(new IGreeter1Impl()); + // Here you need to show that the protocol used by the declaration is triple + service.setProtocol(new ProtocolConfig(CommonConstants.TRIPLE, 50051)); + service.setApplication(new ApplicationConfig("demo-provider")); + service.setRegistry(new RegistryConfig("zookeeper://127.0.0.1:2181")); + service. export(); + System.out.println("dubbo service started"); + new CountDownLatch(1). await(); + } + + ``` + + +6. Create Consumer + + ```java + public static void main(String[] args) throws IOException { + ReferenceConfig ref = new ReferenceConfig<>(); + ref. setInterface(IGreeter. class); + ref. setCheck(false); + ref.setProtocol(CommonConstants.TRIPLE); + ref. setLazy(true); + ref. setTimeout(100000); + ref. setApplication(new ApplicationConfig("demo-consumer")); + ref.setRegistry(new RegistryConfig("zookeeper://127.0.0.1:2181")); + final IGreeter iGreeter = ref. get(); + + System.out.println("dubbo ref started"); + try { + final HelloReply reply = iGreeter.sayHello(HelloRequest.newBuilder() + .setName("name") + .build()); + TimeUnit. SECONDS. sleep(1); + System.out.println("Reply:" + reply); + } catch (Throwable t) { + t. printStackTrace(); + } + System.in.read(); + } + ``` + +7. Run Provider and Consumer, you can see that the request returns normally + > Reply: message: "name" + +### stream mode + +8. Writing Java Interfaces + ```java + import org.apache.dubbo.hello.HelloReply; + import org.apache.dubbo.hello.HelloRequest; + + public interface IGreeter { + /** + * 
+     * Sends greeting by stream
+     *
+ */ +StreamObserver sayHello(StreamObserver replyObserver); + + } + ``` + +9. Write the implementation class + ```java +public class IStreamGreeterImpl implements IStreamGreeter { + +@Override +public StreamObserver sayHello(StreamObserver replyObserver) { + +return new StreamObserver() { +private List replyList = new ArrayList<>(); + +@Override +public void onNext(HelloRequest helloRequest) { +System.out.println("onNext receive request name:" + helloRequest.getName()); +replyList.add(HelloReply.newBuilder() +.setMessage("receive name:" + helloRequest.getName()) +.build()); +} + +@Override +public void onError(Throwable cause) { +System.out.println("onError"); +replyObserver.onError(cause); +} + +@Override +public void onCompleted() { +System.out.println("onComplete receive request size:" + replyList.size()); +for (HelloReply reply : replyList) { +replyObserver.onNext(reply); +} +replyObserver.onCompleted(); +} +}; +} +} +``` + +10. Create a Provider + + ```java +public class StreamProvider { +public static void main(String[] args) throws InterruptedException { +ServiceConfig service = new ServiceConfig<>(); +service.setInterface(IStreamGreeter.class); +service.setRef(new IStreamGreeterImpl()); +service.setProtocol(new ProtocolConfig(CommonConstants.TRIPLE, 50051)); +service.setApplication(new ApplicationConfig("stream-provider")); +service.setRegistry(new RegistryConfig("zookeeper://127.0.0.1:2181")); +service. export(); +System.out.println("dubbo service started"); +new CountDownLatch(1). await(); +} +} +``` + +11. Create Consumer + + ```java +public class StreamConsumer { +public static void main(String[] args) throws InterruptedException, IOException { +ReferenceConfig ref = new ReferenceConfig<>(); +ref. setInterface(IStreamGreeter. class); +ref. setCheck(false); +ref.setProtocol(CommonConstants.TRIPLE); +ref. setLazy(true); +ref. setTimeout(100000); +ref. setApplication(new ApplicationConfig("stream-consumer")); +ref.setRegistry(new RegistryConfig("zookeeper://mse-6e9fda00-p.zk.mse.aliyuncs.com:2181")); +final IStreamGreeter iStreamGreeter = ref. get(); + +System.out.println("dubbo ref started"); +try { + +StreamObserver streamObserver = iStreamGreeter.sayHello(new StreamObserver() { +@Override +public void onNext(HelloReply reply) { +System.out.println("onNext"); +System.out.println(reply.getMessage()); +} + +@Override +public void onError(Throwable throwable) { +System.out.println("onError:" + throwable.getMessage()); +} + +@Override +public void onCompleted() { +System.out.println("onCompleted"); +} +}); + +streamObserver.onNext(HelloRequest.newBuilder() +.setName("tony") +.build()); + +streamObserver.onNext(HelloRequest.newBuilder() +.setName("nick") +.build()); + +streamObserver.onCompleted(); +} catch (Throwable t) { +t. printStackTrace(); +} +System.in.read(); +} +} +``` + +12. Run Provider and Consumer, you can see that the request returns normally + > onNext\ + > receive name:tony\ + > onNext\ + > receive name:nick\ + > onCompleted + +### Other serialization methods +Omit steps 1-3 above, and specify the protocol used by Provider and Consumer to complete the protocol upgrade. + +### Example program +The sample program of this article can be found in [triple-samples](https://github.com/apache/dubbo-samples/tree/master/3-extensions/protocol/dubbo-samples-triple) \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/protocol/triple/idl.md b/content/en/docs3-v2/java-sdk/reference-manual/protocol/triple/idl.md new file mode 100644 index 000000000000..e44ae5b172a4 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/protocol/triple/idl.md @@ -0,0 +1,237 @@ +--- +type: docs +title: "Using Triple in IDL" +linkTitle: "Using Triple in IDL" +weight: 2 +--- + +This tutorial will demonstrate how to use Dubbo Triple based on IDL by building a simple project from scratch + +## precondition +- [JDK](https://jdk.java.net/) version >= 8 +- Installed [Maven](https://maven.apache.org/) +- Installed and started [Zookeeper](https://zookeeper.apache.org/) + +## Create project +### 1. Create an empty maven project + ``` +$ mvn archetype:generate \ + -DgroupId=org.apache.dubbo\ + -DartifactId=tri-stub-demo \ + -DarchetypeArtifactId=maven-archetype-quickstart \ + -DarchetypeVersion=1.4 \ + -DarchetypeGroupId=org.apache.maven.archetypes \ + -Dversion=1.0-SNAPSHOT +``` +### 2. Switch to the project directory +``` + $ cd tri-stub-demo +``` +### 3. Add Dubbo dependencies and plugins + +Set JDK version in `pom.xml` +```xml + + UTF-8 + 1.8 + 1.8 + + + + + junit + junit + 4.13 + test + + + org.apache.dubbo + dubbo + 3.0.8 + + + org.apache.dubbo + dubbo-dependencies-zookeeper-curator5 + pom + 3.0.8 + + + com.google.protobuf + protobuf-java + 3.19.4 + + + + + + + kr.motd.maven + os-maven-plugin + 1.6.1 + + + + + org.xolstice.maven.plugins + protobuf-maven-plugin + 0.6.1 + + com.google.protobuf:protoc:3.19.4:exe:${os.detected.classifier} + + + dubbo + org.apache.dubbo + dubbo-compiler + 0.0.4.1-SNAPSHOT + org.apache.dubbo.gen.tri.Dubbo3TripleGenerator + + + + + + + compile + + + + + + +``` +### 4. Add interface definition file + +`src/main/proto/hello.proto`, Dubbo uses [Protobuf](https://developers.google.com/protocol-buffers) as IDL +```protobuf + syntax = "proto3"; + + option java_multiple_files = true; + option java_package = "org.apache.dubbo.hello"; + option java_outer_classname = "HelloWorldProto"; + option objc_class_prefix = "HLW"; + + package helloworld; + + message HelloRequest { + string name = 1; + } + + message HelloReply { + string message = 1; + } + service Greeter{ + rpc greet(HelloRequest) returns (HelloReply); + } + +``` +### 5. Compile IDL +``` + $ mvn clean install +``` +After the compilation is successful, you can see that the code file is generated in the `target/generated-sources/protobuf/java` directory +``` + $ ls org/apache/dubbo/hello/ + DubboGreeterTriple.java HelloReply.java HelloRequest.java HelloWorldProto.java + Greeter.java HelloReplyOrBuilder.java HelloRequestOrBuilder.java +``` + +### 6. Add server interface implementation + +`src/main/java/org/apache/dubbo/GreeterImpl.java` +```java + package org.apache.dubbo; + + import org.apache.dubbo.hello.DubboGreeterTriple; + import org.apache.dubbo.hello.HelloReply; + import org.apache.dubbo.hello.HelloRequest; + + public class GreeterImpl extends DubboGreeterTriple. GreeterImplBase { + @Override + public HelloReply greet(HelloRequest request) { + return HelloReply. newBuilder() + .setMessage("Hello," + request.getName() + "!") + .build(); + } + } +``` +### 7. Add server startup class +`src/main/java/org/apache/dubbo/MyDubboServer.java` +```java + package org.apache.dubbo; + + import org.apache.dubbo.common.constants.CommonConstants; + import org.apache.dubbo.config.ApplicationConfig; + import org.apache.dubbo.config.ProtocolConfig; + import org.apache.dubbo.config.RegistryConfig; + import org.apache.dubbo.config.ServiceConfig; + import org.apache.dubbo.config.bootstrap.DubboBootstrap; + import org.apache.dubbo.hello.Greeter; + + import java.io.IOException; + + public class MyDubboServer { + + public static void main(String[] args) throws IOException { + ServiceConfig service = new ServiceConfig<>(); + service.setInterface(Greeter.class); + service.setRef(new GreeterImpl()); + + DubboBootstrap bootstrap = DubboBootstrap. getInstance(); + bootstrap. application(new ApplicationConfig("tri-stub-server")) + .registry(new RegistryConfig("zookeeper://127.0.0.1:2181")) + .protocol(new ProtocolConfig(CommonConstants.TRIPLE, 50051)) + .service(service) + .start(); + System.out.println("Dubbo triple stub server started"); + System.in.read(); + } + } +``` + +### 8. Add client startup class +`src/main/java/org/apache/dubbo/MyDubboClient.java` +```java + package org.apache.dubbo; + + import org.apache.dubbo.common.constants.CommonConstants; + import org.apache.dubbo.config.ApplicationConfig; + import org.apache.dubbo.config.ReferenceConfig; + import org.apache.dubbo.config.RegistryConfig; + import org.apache.dubbo.config.bootstrap.DubboBootstrap; + import org.apache.dubbo.hello.Greeter; + import org.apache.dubbo.hello.HelloReply; + import org.apache.dubbo.hello.HelloRequest; + + public class MyDubboClient { + public static void main(String[] args) { + DubboBootstrap bootstrap = DubboBootstrap. getInstance(); + ReferenceConfig ref = new ReferenceConfig<>(); + ref. setInterface(Greeter. class); + ref.setProtocol(CommonConstants.TRIPLE); + ref.setProxy(CommonConstants.NATIVE_STUB); + ref. setTimeout(3000); + bootstrap. application(new ApplicationConfig("tri-stub-client")) + .registry(new RegistryConfig("zookeeper://127.0.0.1:2181")) + .reference(ref) + .start(); + + Greeter greeter = ref. get(); + HelloRequest request = HelloRequest.newBuilder().setName("Demo").build(); + HelloReply reply = greeter. greet(request); + System.out.println("Received reply:" + reply); + } + } +``` +### 9. Compile the code +``` +$ mvn clean install +``` +### 10. Start the server +``` +$ mvn org.codehaus.mojo:exec-maven-plugin:3.0.0:java -Dexec.mainClass="org.apache.dubbo.MyDubboServer" +Dubbo triple stub server started +``` +### 11. Open a new terminal and start the client +``` +$ mvn org.codehaus.mojo:exec-maven-plugin:3.0.0:java -Dexec.mainClass="org.apache.dubbo.MyDubboClient" +Received reply: message: "Hello, Demo!" +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/protocol/triple/migration.md b/content/en/docs3-v2/java-sdk/reference-manual/protocol/triple/migration.md new file mode 100644 index 000000000000..b6d2cf77321e --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/protocol/triple/migration.md @@ -0,0 +1,83 @@ +--- +type: docs +title: "Dubbo2 Protocol Migration" +linkTitle: "Dubbo2 Protocol Migration" +weight: 10 +--- + +## Dubbo2 protocol migration process + +Dubbo2 users use dubbo protocol + custom serialization, such as hessian2 to complete remote calls. + +By default, Grpc only supports Protobuf serialization, and it cannot support multi-parameter and method overloading in the Java language. + +At the beginning of Dubbo3, one goal was to be perfectly compatible with Dubbo2. Therefore, in order to ensure the smooth upgrade of Dubbo2, the Dubbo framework has done a lot of work to ensure that the upgrade is seamless. Currently, the default serialization is consistent with Dubbo2 as `hessian2`. + +Therefore, if you decide to upgrade to the `Triple` protocol of Dubbo3, you only need to modify the protocol name in the configuration to `tri` (note: not triple). + +Next we use a [project] (https://github.com/apache/dubbo-samples/tree/master/3-extensions/protocol/dubbo-samples-triple/src/main/java/ org/apache/dubbo/sample/tri/migration) as an example, how to upgrade safely step by step. + +1. Only use the `dubbo` protocol to start `provider` and `consumer`, and complete the call. +2. Use `dubbo` and `tri` protocols to start `provider`, use `dubbo` protocol to start `consumer`, and complete the call. +3. Start `provider` and `consumer` using only `tri` protocol, and complete the call. + +### Define the service + +1. Define the interface +```java +public interface IWrapperGreeter { + + //... + + /** + * This is a normal interface, not serialized using pb + */ + String sayHello(String request); + +} +``` + +2. The implementation class is as follows +```java +public class IGreeter2Impl implements IWrapperGreeter { + + @Override + public String sayHello(String request) { + return "hello," + request; + } +} +``` + +### Only use dubbo protocol + +To ensure compatibility, we first upgrade some providers to the `dubbo3` version and use the `dubbo` protocol. + +Start a [`Provider`] using the `dubbo` protocol (https://github.com/apache/dubbo-samples/tree/master/3-extensions/protocol/dubbo-samples-triple/src/main/java/org /apache/dubbo/sample/tri/migration/ApiMigrationDubboProvider.java) and [`Consumer`](https://github.com/apache/dubbo-samples/tree/master/3-extensions/protocol/dubbo-samples-triple/src/main/java/org/apache/dubbo/sample/tri/migration/ApiMigrationDubboConsumer.java), complete the call, the output is as follows: +![result](/imgs/v3/migration/tri/dubbo3-tri-migration-dubbo-dubbo-result.png) + +### Use dubbo and triple protocol at the same time + +For the upgrade of online services, it is impossible to complete the provider and consumer upgrades at the same time. It needs to be operated step by step to ensure business stability. +In the second step, the provider provides a dual-protocol way to support dubbo + tri clients at the same time. + +The structure is shown in the figure: +![trust](/imgs/v3/migration/tri/migrate-dubbo-tri-strust.png) + +> According to the recommended upgrade steps, the provider already supports the tri protocol, so the consumer of dubbo3 can directly use the tri protocol + +Start [`Provider`] using `dubbo` protocol and `triple` protocol (https://github.com/apache/dubbo-samples/tree/master/3-extensions/protocol/dubbo-samples-triple/src/main /java/org/apache/dubbo/sample/tri/migration/ApiMigrationBothProvider.java) and [`Consumer`](https://github.com/apache/dubbo-samples/tree/master/3-extensions/protocol/ dubbo-samples-triple/src/main/java/org/apache/dubbo/sample/tri/migration/ApiMigrationBothConsumer.java), complete the call, the output is as follows: + +![result](/imgs/v3/migration/tri/dubbo3-tri-migration-both-dubbo-tri-result.png) + + +### Only use triple protocol + +When all consuemr are upgraded to a version that supports the `Triple` protocol, the provider can be switched to only use the `Triple` protocol to start + +The structure is shown in the figure: +![trust](/imgs/v3/migration/tri/migrate-only-tri-strust.png) + +[Provider](https://github.com/apache/dubbo-samples/tree/master/3-extensions/protocol/dubbo-samples-triple/src/main/java/org/apache/dubbo/sample/tri/ migration/ApiMigrationTriProvider.java) +and [Consumer](https://github.com/apache/dubbo-samples/tree/master/3-extensions/protocol/dubbo-samples-triple/src/main/java/org/apache/dubbo/sample/tri /migration/ApiMigrationTriConsumer.java) to complete the call, the output is as follows: + +![result](/imgs/v3/migration/tri/dubbo3-tri-migration-tri-tri-result.png) \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/protocol/triple/overview.md b/content/en/docs3-v2/java-sdk/reference-manual/protocol/triple/overview.md new file mode 100644 index 000000000000..735e7b5b9d6a --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/protocol/triple/overview.md @@ -0,0 +1,39 @@ +--- +type: docs +title: "Protocol Overview" +linkTitle: "Protocol Overview" +weight: 1 +--- + +## Triple overview + +For the format and principle of the `Triple` protocol, please refer to [RPC Communication Protocol](/zh/docs/concepts/rpc-protocol/) + +According to the goal of Triple design, the `Triple` protocol has the following advantages + +- Capable of cross-language interaction. Both the traditional multi-language and multi-SDK mode and the Mesh cross-language mode require a more general and scalable data transmission protocol. +- Provide a more complete request model. In addition to supporting the traditional Request/Response model (Unary one-way communication), it also supports Stream (streaming communication) and Bidirectional (two-way communication). +- Easy to expand, high penetration, including but not limited to Tracing / Monitoring and other support, should also be recognized by devices at all levels, gateway facilities, etc. can identify data packets, friendly to Service Mesh deployment, and reduce the difficulty of understanding for users. +- Fully compatible with grpc, the client/server can communicate with the native grpc client. +- Components in the existing grpc ecosystem can be reused to meet cross-language, cross-environment, and cross-platform intercommunication requirements in cloud-native scenarios. + +For Dubbo users currently using other protocols, the framework provides migration capabilities compatible with existing serialization methods. Without affecting existing online businesses, the cost of migrating protocols is almost zero. +### grpc docking +Dubbo users who need to add grpc services can directly use the Triple protocol to get through, without the need to introduce grpc client separately to complete, not only can retain the existing ease of use of Dubbo, but also reduce the complexity of the program and development and maintenance Cost, it can be connected to the existing ecology without additional adaptation and development. +### Gateway Access +For Dubbo users who need gateway access, the Triple protocol provides a more native way to make gateway development or use open source grpc gateway components easier. The gateway can choose not to parse the payload, which greatly improves the performance. When using the Dubbo protocol, the language-related serialization method is a big pain point for the gateway, and the traditional HTTP-to-Dubbo method is almost powerless for cross-language serialization. At the same time, since Triple's protocol metadata is stored in the request header, the gateway can easily implement customized requirements, such as routing and current limiting. + + +## common problem + +### protobuf class not found + +Since the bottom layer of the Triple protocol needs to rely on the protobuf protocol for transmission, even if the defined service interface does not use protobuf, it is necessary to introduce protobuf dependencies into the environment. + +```xml + + com.google.protobuf + protobuf-java + 3.19.4 + +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/protocol/triple/pojo.md b/content/en/docs3-v2/java-sdk/reference-manual/protocol/triple/pojo.md new file mode 100644 index 000000000000..b18d34fbfb72 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/protocol/triple/pojo.md @@ -0,0 +1,189 @@ +--- +type: docs +title: "POJO way to use Triple" +linkTitle: "POJO way to use Triple" +weight: 2 +--- + +This tutorial will demonstrate how to use Dubbo Triple based on POJO by building a simple project from scratch, and upgrade to the Triple protocol while the application does not change the existing interface definition. + + +### Implementation principle + +Through the upgrade process described above, we can easily complete the upgrade by modifying the protocol type. How does the framework help us do this? + +Through the introduction of the `Triple` protocol, we know that the data type of `Triple` in Dubbo3 is a `protobuf` object, so why non-`protobuf` java objects can also be transmitted normally. + +Here Dubbo3 uses an ingenious design, first judge whether the parameter type is a `protobuf` object, if not. Use a `protobuf` object to wrap `request` and `response`, which shields the complexity brought by other serialization. Declare the serialization type inside the `wrapper` object to support serialization extensions. + +The IDL of `protobuf` of wrapper is as follows: +```proto +syntax = "proto3"; + +package org.apache.dubbo.triple; + +message TripleRequestWrapper { + //hessian4 + // json + string serializeType = 1; + repeated bytes args = 2; + repeated string argTypes = 3; +} + +message TripleResponseWrapper { + string serializeType = 1; + bytes data = 2; + string type = 3; +} +``` + +For requests, use `TripleRequestWrapper` for wrapping, and for responses, use `TripleResponseWrapper` for wrapping. + +> For request parameters, you can see that args is modified by `repeated`, this is because multiple parameters of the java method need to be supported. Of course, serialization can only be one. The implementation of serialization follows the spi implemented by Dubbo2 + +### precondition +- [JDK](https://jdk.java.net/) version >= 8 +- Installed [Maven](https://maven.apache.org/) +- Installed and started [Zookeeper](https://zookeeper.apache.org/) + +### Create project +1. First create an empty maven project + ``` + $ mvn archetype:generate \ + -DgroupId=org.apache.dubbo\ + -DartifactId=tri-pojo-demo\ + -DarchetypeArtifactId=maven-archetype-quickstart \ + -DarchetypeVersion=1.4 \ + -DarchetypeGroupId=org.apache.maven.archetypes \ + -Dversion=1.0-SNAPSHOT + ``` +2. Switch to the project directory + ``` + $ cd tri-pojo-demo + ``` +3. Set JDK version in `pom.xml`, add Dubbo dependencies and plugins + ```xml + + UTF-8 + 1.8 + 1.8 + + + + + junit + junit + 4.13 + test + + + org.apache.dubbo + dubbo + 3.0.8 + + + org.apache.dubbo + dubbo-dependencies-zookeeper-curator5 + pom + 3.0.8 + + + com.google.protobuf + protobuf-java + 3.19.4 + + + ``` +4. Add interface definition `src/main/java/org/apache/dubbo/Greeter.java` + ```java + package org.apache.dubbo; + + public interface Greeter { + String sayHello(String name); + } + ``` +5. Add server-side interface implementation `src/main/java/org/apache/dubbo/GreeterImpl.java` + ```java + package org.apache.dubbo; + + public class GreeterImpl implements Greeter { + @Override + public String sayHello(String name) { + return "Hello," + name + "!"; + } + } + ``` +6. Add server startup class `src/main/java/org/apache/dubbo/MyDubboServer.java` + ```java + package org.apache.dubbo; + + import org.apache.dubbo.common.constants.CommonConstants; + import org.apache.dubbo.config.ApplicationConfig; + import org.apache.dubbo.config.ProtocolConfig; + import org.apache.dubbo.config.RegistryConfig; + import org.apache.dubbo.config.ServiceConfig; + import org.apache.dubbo.config.bootstrap.DubboBootstrap; + + import java.io.IOException; + + public class MyDubboServer { + + public static void main(String[] args) throws IOException { + ServiceConfig service = new ServiceConfig<>(); + service.setInterface(Greeter.class); + service.setRef(new GreeterImpl()); + + DubboBootstrap bootstrap = DubboBootstrap. getInstance(); + bootstrap. application(new ApplicationConfig("tri-pojo-server")) + .registry(new RegistryConfig("zookeeper://127.0.0.1:2181")) + .protocol(new ProtocolConfig(CommonConstants.TRIPLE, 50051)) + .service(service) + .start(); + System.out.println("Dubbo triple pojo server started"); + System.in.read(); + } + } + ``` + +7. Add the client startup class `src/main/java/org/apache/dubbo/MyDubboClient.java` + ```java + package org.apache.dubbo; + + import org.apache.dubbo.common.constants.CommonConstants; + import org.apache.dubbo.config.ApplicationConfig; + import org.apache.dubbo.config.ReferenceConfig; + import org.apache.dubbo.config.RegistryConfig; + import org.apache.dubbo.config.bootstrap.DubboBootstrap; + + public class MyDubboClient { + public static void main(String[] args) { + DubboBootstrap bootstrap = DubboBootstrap. getInstance(); + ReferenceConfig ref = new ReferenceConfig<>(); + ref. setInterface(Greeter. class); + ref.setProtocol(CommonConstants.TRIPLE); + ref. setTimeout(3000); + bootstrap. application(new ApplicationConfig("tri-pojo-client")) + .registry(new RegistryConfig("zookeeper://127.0.0.1:2181")) + .reference(ref) + .start(); + + Greeter greeter = ref. get(); + String reply = greeter. sayHello("pojo"); + System.out.println("Received reply:" + reply); + } + } + ``` +8. Compile the code + ``` + $ mvn clean install + ``` +9. Start the server + ``` + $ mvn org.codehaus.mojo:exec-maven-plugin:3.0.0:java -Dexec.mainClass="org.apache.dubbo.MyDubboServer" + Dubbo triple pojo server started + ``` +10. Open a new terminal and start the client + ``` + $ mvn org.codehaus.mojo:exec-maven-plugin:3.0.0:java -Dexec.mainClass="org.apache.dubbo.MyDubboClient" + Received reply: message: "Hello, Demo!" + ``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/protocol/triple/streaming.md b/content/en/docs3-v2/java-sdk/reference-manual/protocol/triple/streaming.md new file mode 100644 index 000000000000..fc48e3288a55 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/protocol/triple/streaming.md @@ -0,0 +1,153 @@ +--- +type: docs +title: "Streaming Communication" +linkTitle: "Streaming communication" +weight: 10 +--- +## Implementation principle of stream + +Stream mode for the `Triple` protocol + +- From the perspective of the protocol layer, `Triple` is built on the basis of `HTTP2`, so it directly has all the capabilities of `HTTP2`, so it has the ability to split `stream` and full-duplex. + +- In terms of the framework layer, `StreamObserver` is provided to users as a stream interface to provide stream processing for input and output parameters. The framework makes corresponding interface calls when sending and receiving stream data, so as to ensure the integrity of the life cycle of the stream. + +## Enable new features of Triple +### Stream stream +Stream is a new call type provided by Dubbo3. It is recommended to use stream in the following scenarios: + +- The interface needs to send a large amount of data. These data cannot be placed in an RPC request or response, and need to be sent in batches. However, if the application layer cannot solve the order and performance problems in the traditional multiple RPC method, if the order needs to be guaranteed , it can only be sent serially +- In streaming scenarios, data needs to be processed in the order they are sent, and the data itself has no definite boundary +- In push scenarios, multiple messages are sent and processed in the context of the same call + +Stream is divided into the following three types: +- SERVER_STREAM (server stream) + ![SERVER_STREAM](/imgs/v3/migration/tri/migrate-server-stream.png) +- CLIENT_STREAM (client stream) + ![CLIENT_STREAM](/imgs/v3/migration/tri/migrate-client-stream.png) +- BIDIRECTIONAL_STREAM (bidirectional stream) + ![BIDIRECTIONAL_STREAM](/imgs/v3/migration/tri/migrate-bi-stream.png) + +> Due to the limitations of the `java` language, the implementation of BIDIRECTIONAL_STREAM and CLIENT_STREAM is the same. + +In Dubbo3, the stream interface is declared and used as `SteamObserver`, and users can use and implement this interface to send and handle stream data, exceptions, and end. + +> For Dubbo2 users, they may be unfamiliar with StreamObserver, which is a stream type defined by Dubbo3. There is no Stream type in Dubbo2, so it has no impact on migration scenarios. + +Stream Semantic Guarantees +- Provide message boundaries, which can easily process messages separately +- Strictly ordered, the order of the sender is consistent with the order of the receiver +- Full duplex, no need to wait for sending +- Support cancellation and timeout + +## Non-PB serialized stream +### APIs +```java +public interface IWrapperGreeter { + + StreamObserver sayHelloStream(StreamObserver response); + + void sayHelloServerStream(String request, StreamObserver response); +} +``` + +> The method input parameters and return values of the Stream method are strictly agreed. In order to prevent problems caused by writing errors, the Dubbo3 framework side checks the parameters, and throws an exception if there is an error. +> For `BIDIRECTIONAL_STREAM`, it should be noted that `StreamObserver` in the parameter is the response stream, and `StreamObserver` in the return parameter is the request stream. +### Implementation class +```java +public class WrapGreeterImpl implements WrapGreeter { + + //... + + @Override + public StreamObserver sayHelloStream(StreamObserver response) { + return new StreamObserver() { + @Override + public void onNext(String data) { + System.out.println(data); + response.onNext("hello,"+data); + } + + @Override + public void onError(Throwable throwable) { + throwable. printStackTrace(); + } + + @Override + public void onCompleted() { + System.out.println("onCompleted"); + response.onCompleted(); + } + }; + } + + @Override + public void sayHelloServerStream(String request, StreamObserver response) { + for (int i = 0; i < 10; i++) { + response.onNext("hello," + request); + } + response.onCompleted(); + } +} +``` + +### Call method +```java +delegate.sayHelloServerStream("server stream", new StreamObserver() { + @Override + public void onNext(String data) { + System.out.println(data); + } + + @Override + public void onError(Throwable throwable) { + throwable. printStackTrace(); + } + + @Override + public void onCompleted() { + System.out.println("onCompleted"); + } +}); + + +StreamObserver request = delegate.sayHelloStream(new StreamObserver() { + @Override + public void onNext(String data) { + System.out.println(data); + } + + @Override + public void onError(Throwable throwable) { + throwable. printStackTrace(); + } + + @Override + public void onCompleted() { + System.out.println("onCompleted"); + } +}); +for (int i = 0; i < n; i++) { + request.onNext("stream request" + i); +} +request.onCompleted(); +``` + +## Serialized stream using Protobuf + +For the `Protobuf` serialization method, it is recommended to write `IDL` and use the `compiler` plugin to compile and generate. The generated code is roughly as follows: +```java +public interface PbGreeter { + + static final String JAVA_SERVICE_NAME = "org.apache.dubbo.sample.tri.PbGreeter"; + static final String SERVICE_NAME = "org.apache.dubbo.sample.tri.PbGreeter"; + + static final boolean inited = PbGreeterDubbo.init(); + + //... + + void greetServerStream(org.apache.dubbo.sample.tri.GreeterRequest request, org.apache.dubbo.common.stream.StreamObserver responseObserver); + + org.apache.dubbo.common.stream.StreamObserver greetStream(org.apache.dubbo.common.stream.StreamObserver responseObserver); +} +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/protocol/webservice.md b/content/en/docs3-v2/java-sdk/reference-manual/protocol/webservice.md new file mode 100644 index 000000000000..c2521fdcd6b4 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/protocol/webservice.md @@ -0,0 +1,112 @@ +--- +type: docs +title: "Webservice protocol" +linkTitle: "Webservice protocol" +weight: 11 +--- + + +## Feature description +WebService-based remote invocation protocol, implemented based on `frontend-simple` and `transports-http` of [Apache CXF](http://cxf.apache.org). `2.3.0` and above are supported. + +CXF is an open source RPC framework of Apache, which is merged from Xfire and Celtix. +* Number of connections: multiple connections +* Connection method: short connection +* Transmission protocol: HTTP +* Transmission method: synchronous transmission +* Serialization: SOAP text serialization +* Applicable scenarios: system integration, cross-language call + +It can interoperate with native WebService services, namely: + +* The provider uses Dubbo's WebService protocol to expose the service, and the consumer directly uses the standard WebService interface to call, +* Or the provider uses the standard WebService to expose the service, and the consumer uses Dubbo's WebService protocol to call. +#### Constraints +* Parameters and return values need to implement `Serializable` interface +* Parameters try to use basic types and POJO + +## scenes to be used +To publish a service (internal/external), regardless of client type or performance, it is recommended to use webservice. The server has determined to use webservice, the client cannot choose, and must use webservice. +## How to use +### Dependencies + +Starting from Dubbo 3, the Webservice protocol is no longer embedded in Dubbo, and an independent [module](/zh/release/dubbo-spi-extensions/#dubbo-rpc) needs to be introduced separately. +```xml + + org.apache.dubbo.extensions + dubbo-rpc-webservice + 1.0.0 + +``` + +```xml + + org.apache.cxf + cxf-rt-frontend-simple + 2.6.1 + + + org.apache.cxf + cxf-rt-transports-http + 2.6.1 + +``` + +### Configuration protocol +```xml + +``` + +### Configure the default protocol +```xml + +``` + +### Configure service protocol +```xml + +``` + +### Multiport +```xml + + +``` + +### direct connection +```xml + +``` + +###WSDL +``` +http://10.20.153.10:8080/com.foo.HelloWorld?wsdl +``` + +### Jetty Server (default) + +```xml + +``` + +### Servlet Bridge Server (recommended) +```xml + +``` + +### Configure DispatcherServlet +```xml + + dubbo + org.apache.dubbo.remoting.http.servlet.DispatcherServlet + 1 + + + dubbo + /* + +``` + +> If a servlet is used to dispatch the request +> * The protocol port `` must be the same as the port of the servlet container. +> * The context path of the protocol `` must be the same as the context path of the servlet application. \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/qos/_index.md b/content/en/docs3-v2/java-sdk/reference-manual/qos/_index.md new file mode 100755 index 000000000000..bacf7fa4a229 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/qos/_index.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "QOS Operation Manual" +linkTitle: "QOS Operation Manual" +weight: 3 +--- \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/qos/command.md b/content/en/docs3-v2/java-sdk/reference-manual/qos/command.md new file mode 100644 index 000000000000..8f711acd03e6 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/qos/command.md @@ -0,0 +1,48 @@ +--- +type: docs +title: "Basic Command Manual" +linkTitle: "Basic command manual" +weight: 2 +description: "Basic command manual" +--- + + +## help command + +``` +// list all commands +dubbo>help + +//List the specific usage of a single command +dubbo>help online ++--------------+---------------------------------- ------------------------------------------------+ +| COMMAND NAME | online | ++--------------+---------------------------------- ------------------------------------------------+ +| EXAMPLE | online dubbo | +| | online xx.xx.xxx.service | ++--------------+---------------------------------- ------------------------------------------------+ + +dubbo> +``` + +## version command + +Display the version number of the currently running Dubbo + +``` +dubbo>version +dubbo version "3.0.10-SNAPSHOT" + +dubbo> +``` + +## quit command + +exit command state + +``` +dubbo>quit +BYE! +Connection closed by foreign host. + +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/qos/logger-management.md b/content/en/docs3-v2/java-sdk/reference-manual/qos/logger-management.md new file mode 100644 index 000000000000..d73600c44b08 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/qos/logger-management.md @@ -0,0 +1,94 @@ +--- +type: docs +title: "Logging framework runtime management" +linkTitle: "Logging framework runtime management" +weight: 5 +description: "Dynamically switch the log framework used when running in Dubbo" +--- + +## Logging framework runtime management + +Starting from `3.0.10`, dubbo-qos runtime control supports querying log configuration and dynamically modifying the used log framework and log level. + +Note: The log configuration modified by dubbo-qos is not stored persistently and will become invalid after the application is restarted. + +### 1. Query log configuration + +Command: `loggerInfo` + +Example: +```bash +> telnet 127.0.0.1 22222 +> loggerInfo +``` + +output: +``` +Trying 127.0.0.1... +Connected to localhost. +Escape character is '^]'. + ___ __ __ ___ ___ ____ + / _ \ / / / // _ ) / _ ) / __ \ + / // // /_/ // _ |/ _ |/ /_/ / +/____/ \____//____//____/ \____/ +dubbo>loggerInfo +Available logger adapters: [jcl, jdk, log4j, slf4j]. Current Adapter: [log4j]. Log level: INFO +``` + +### 2. Modify log level + +Command: `switchLogLevel {level}` + +level: `ALL`, `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `OFF` + +Example: +```bash +> telnet 127.0.0.1 22222 +> switchLogLevel WARN +``` + +output: +``` +Trying 127.0.0.1... +Connected to localhost. +Escape character is '^]'. + ___ __ __ ___ ___ ____ + / _ \ / / / // _ ) / _ ) / __ \ + / // // /_/ // _ |/ _ |/ /_/ / +/____/ \____//____//____/ \____/ +dubbo>loggerInfo +Available logger adapters: [jcl, jdk, log4j, slf4j]. Current Adapter: [log4j]. Log level: INFO +dubbo>switchLogLevel WARN +OK +dubbo>loggerInfo +Available logger adapters: [jcl, jdk, log4j, slf4j]. Current Adapter: [log4j]. Log level: WARN``` +``` + +### 3. Modify the log output framework + +Command: `switchLogger {loggerAdapterName}` + +loggerAdapterName: `slf4j`, `jcl`, `log4j`, `jdk`, `log4j2` + +Example: +```bash +> telnet 127.0.0.1 22222 +> switchLogger slf4j +``` + +output: +``` +Trying 127.0.0.1... +Connected to localhost. +Escape character is '^]'. + ___ __ __ ___ ___ ____ + / _ \ / / / // _ ) / _ ) / __ \ + / // // /_/ // _ |/ _ |/ /_/ / +/____/ \____//____//____/ \____/ +dubbo>loggerInfo +Available logger adapters: [jcl, slf4j, log4j, jdk]. Current Adapter: [log4j]. Log level: INFO +dubbo>switchLogger slf4j +OK +dubbo>loggerInfo +Available logger adapters: [jcl, slf4j, log4j, jdk]. Current Adapter: [slf4j]. Log level: INFO +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/qos/overview.md b/content/en/docs3-v2/java-sdk/reference-manual/qos/overview.md new file mode 100644 index 000000000000..35dbdd2a127c --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/qos/overview.md @@ -0,0 +1,212 @@ +--- +type: docs +title: "QOS Overview" +linkTitle: "QOS Overview" +weight: 1 +description: The new version of dubbo 2.5.8 adds QOS module and provides new telnet command support. +--- + +## Description of related parameters +QoS provides some startup parameters to configure startup, they mainly include: + +| Parameters | Description | Default | +|---------------------------------|----------------|-----------| +| qos-enable | Whether to enable QoS | true | +| qos-port | Enable QoS binding port | 22222 | +| qos-accept-foreign-ip | Whether to allow remote access | false | +| qos-accept-foreign-ip-whitelist | Supported remote host ip address (segment) | (none) | +| qos-anonymous-access-permission-level | Permission level for anonymous access supported | PUBLIC(1) | + +> Note, starting from 2.6.4/2.7.0, the default configuration of qos-accept-foreign-ip is changed to false. If qos-accept-foreign-ip is set to true, it may bring security risks, please evaluate carefully Open. + +## QoS parameter configuration + +* system properties +* dubbo.properties +* XML method +* Spring-boot automatic assembly method + +Among them, the priority order of the above methods is system properties > dubbo.properties > XML/Spring-boot automatic assembly method. + + +## port +The port of the new version of telnet is different from the port of the dubbo protocol, the default is `22222` + +It can be modified through the configuration file `dubbo.properties`: +``` +dubbo.application.qos-port=33333 +``` +or +You can set the JVM parameter: +``` +-Ddubbo.application.qos-port=33333 +``` + +## Safety +By default, dubbo accepts commands initiated by any host + +It can be modified through the configuration file `dubbo.properties`: +``` +dubbo.application.qos-accept-foreign-ip=false +``` +or + +You can set the JVM parameter: +``` +-Ddubbo.application.qos-accept-foreign-ip=false +``` +Reject commands issued by the remote host, and only allow the service to execute locally. + +At the same time, you can specify the supported remote host ip addresses (segments) by setting `qos-accept-foreign-ip-whitelist`, and separate multiple ip addresses (segments) with **comma**, such as: +> Configuration file `dubbo.properties` +``` +dubbo.application.qos-accept-foreign-ip-whitelist=123.12.10.13, 132.12.10.13/24 +``` +> Set JVM parameters: +``` +-Ddubbo.application.qos-accept-foreign-ip-whitelist=123.12.10.13,132.12.10.13/24 +``` + +## Permissions +In order to support the life cycle probe by default, QoS provides the ability to access anonymously and set the permission level. The currently supported permission levels are: +- PUBLIC(1) + By default, the command permission level of anonymous access is supported. Currently, only commands related to lifecycle probes are supported. +- PROTECTED(2) + command default privilege level +- PRIVATE(3) + The highest privilege level reserved, currently unsupported +- NONE + The lowest privilege level, i.e. anonymous access is not supported + +> Privilege level `PRIVATE`> `PROTECTED`> `PUBLIC`> `NONE`, high-level permissions can access commands of the same level and low-level permissions. +Currently the permissions of the following commands are `PUBLIC`, and the default permissions of other commands are `PROTECTED`. + +| command | privilege level | +|------------------------------------------|-------------------| +| Live | PUBLIC (1) | +| Startup | PUBLIC (1) | +| Ready | PUBLIC (1) | +| Quit | PUBLIC (1)| + +By default, dubbo allows anonymous hosts to initiate anonymous access, only commands with `PUBLIC` permission level can be executed, and other commands with higher permissions will be rejected. + +**Turn off anonymous access** +Anonymous access can be turned off by setting `qos-anonymous-access-permission-level=NONE`. + +**SET PERMISSION LEVEL** +It can be modified through the configuration file `dubbo.properties`: +``` +dubbo.application.qos-anonymous-access-permission-level=PROTECTED +``` +or +You can set the JVM parameter: +``` +-Ddubbo.application.qos-anonymous-access-permission-level=PROTECTED +``` +to allow anonymous access to higher-level privileged commands. + +## agreement +### telnet and http protocols + +The telnet module now supports both the http protocol and the telnet protocol, which is convenient for use in various situations +Example: +``` +➜ ~ telnet localhost 22222 +Trying ::1... +telnet: connect to address ::1: Connection refused +Trying 127.0.0.1... +Connected to localhost. +Escape character is '^]'. + ████████▄ ███ █▄ ▀█████████▄ ▀█████████▄ ▄██████▄ + ███ ▀███ ███ ███ ███ ███ ███ ███ ███ ███ + ███ ███ ███ ███ ███ ███ ███ ███ ███ ███ + ███ ███ ███ ███ ▄███▄▄▄██▀ ▄███▄▄▄██▀ ███ ███ + ███ ███ ███ ███ ▀▀███▀▀▀██▄ ▀▀███▀▀▀██▄ ███ ███ + ███ ███ ███ ███ ███ ██▄ ███ ██▄ ███ ███ + ███ ▄███ ███ ███ ███ ███ ███ ███ ███ ███ + ████████▀ ████████▀ ▄█████████▀ ▄█████████▀ ▀██████▀ + + +dubbo>ls +As Provider side: ++----------------------------------+---+ +| Provider Service Name |PUB| ++----------------------------------+---+ +|org.apache.dubbo.demo.DemoService|N| ++----------------------------------+---+ +As Consumer side: ++---------------------+---+ +|Consumer Service Name|NUM| ++---------------------+---+ + +dubbo> +``` + + +``` +➜ ~ curl "localhost:22222/ls?arg1=xxx&arg2=xxxx" +As Provider side: ++----------------------------------+---+ +| Provider Service Name |PUB| ++----------------------------------+---+ +|org.apache.dubbo.demo.DemoService|N| ++----------------------------------+---+ +As Consumer side: ++---------------------+---+ +|Consumer Service Name|NUM| ++---------------------+---+ +``` +## Use configuration +### Use system properties to configure +``` +-Ddubbo.application.qos-enable=true +-Ddubbo.application.qos-port=33333 +-Ddubbo.application.qos-accept-foreign-ip=false +-Ddubbo.application.qos-accept-foreign-ip-whitelist=123.12.10.13,132.12.10.13/24 +-Ddubbo.application.qos-anonymous-access-permission-level=PUBLIC +``` + +### Use dubbo.properties file configuration +Add the dubbo.properties file in the `src/main/resources` directory of the project, the content is as follows: +``` +dubbo.application.qos-enable=true +dubbo.application.qos-port=33333 +dubbo.application.qos-accept-foreign-ip=false +dubbo.application.qos-accept-foreign-ip-whitelist=123.12.10.13, 132.12.10.13/24 +dubbo.application.qos-anonymous-access-permission-level=PUBLIC +``` + +### Use the XML method to configure +If you want to configure the QoS-related parameters of the response through XML, you can configure them as follows: +```xml + + + + + + + + + + + + + + +``` + +### Use spring-boot automatic assembly configuration +If it is a spring-boot application, it can be configured on `application.properties` or `application.yml`: + +``` +dubbo.application.qos-enable=true +dubbo.application.qos-port=33333 +dubbo.application.qos-accept-foreign-ip=false +dubbo.application.qos-accept-foreign-ip-whitelist=123.12.10.13, 132.12.10.13/24 +dubbo.application.qos-anonymous-access-permission-level=NONE +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/qos/probe.md b/content/en/docs3-v2/java-sdk/reference-manual/qos/probe.md new file mode 100644 index 000000000000..086a30da4fa4 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/qos/probe.md @@ -0,0 +1,42 @@ +--- +type: docs +title: "Frame State Command" +linkTitle: "Frame State Command" +weight: 4 +description: "Frame State Command" +--- + +Reference document: [Kubernetes Lifecycle Probe](../../../advanced-features-and-usage/others/dubbo-kubernetes-probe/) + +## startup command + +Check if the current framework has been started + +``` +dubbo>startup +true + +dubbo> +``` + +## ready command + +Detect whether the current framework can provide services normally (may be temporarily offline) + +``` +dubbo>ready +true + +dubbo> +``` + +## live command + +Check if the current framework is running normally (possibly a permanent exception) + +``` +dubbo>live +true + +dubbo> +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/qos/profiler.md b/content/en/docs3-v2/java-sdk/reference-manual/qos/profiler.md new file mode 100644 index 000000000000..a05d627ca100 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/qos/profiler.md @@ -0,0 +1,74 @@ +--- +type: docs +title: "Performance Sampling Command" +linkTitle: "Performance Sampling Command" +weight: 7 +description: "Performance Sampling Command" +--- + +The performance sampling function can detect the time consumption of various parts of the Dubbo processing link. When a timeout occurs, `( usageTime / timeout > profilerWarnPercent * 100 )` records the time consumption of calls through logs. + +This function is divided into `simple profiler` and `detail profiler` two modes, where `simple profiler` mode is enabled by default, and `detail profiler` mode is disabled by default. +Compared with the `simple profiler` mode, the `detail profiler` collects more time-consuming processing of each filter, specific time-consuming protocols, etc. +In the `simple profiler` mode, if you find that there is a long time-consuming situation inside the Dubbo framework, you can enable the `detail profiler` mode to better troubleshoot the problem. + +Reference link: [Request time-consuming sampling](../../../advanced-features-and-usage/performance/profiler/) + +## enableSimpleProfiler command + +Enable `simple profiler` mode, enabled by default + +``` +dubbo>enableSimpleProfiler +OK + +dubbo> +``` + +## disableSimpleProfiler command + +Turn off the `simple profiler` mode, and the `detail profiler` will not be enabled after it is turned off + +``` +dubbo>disableSimpleProfiler +OK + +dubbo> +``` + +## enableDetailProfiler command + +Enable the `detail profiler` mode, which is disabled by default, you need to enable the `simple profiler` mode to actually enable it + +``` +dubbo>enableDetailProfiler +OK. This will cause performance degradation, please be careful! + +dubbo> +``` + +## disableDetailProfiler command + +Turn off `detail profiler` mode, it will not affect `simple profiler` + +``` +dubbo>disableDetailProfiler +OK + +dubbo> +``` + +## setProfilerWarnPercent command + +Set the warning percentage for the timeout + +Command: `setProfilerWarnPercent {profilerWarnPercent}` + +profilerWarnPercent: The warning percentage of the timeout period, the value range is 0.0 ~ 1.0, and the default value is 0.75 + +``` +dubbo>setProfilerWarnPercent 0.75 +OK + +dubbo> +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/qos/router-snapshot.md b/content/en/docs3-v2/java-sdk/reference-manual/qos/router-snapshot.md new file mode 100644 index 000000000000..2295e27a89e4 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/qos/router-snapshot.md @@ -0,0 +1,110 @@ +--- +type: docs +title: "Routing Status Command" +linkTitle: "Routing Status Command" +weight: 8 +description: "Route Status Command" +--- + +Many of Dubbo's traffic management capabilities are implemented based on Router. In a production environment, if traffic results do not meet expectations, you can use the routing status command to check the routing status to locate possible problems. + +Reference link: [routing status collection](../../../advanced-features-and-usage/performance/router-snapshot/) + +## getRouterSnapshot command + +Get the current grouping status of each layer of routing. (Only supports StateRouter) + +Command: `getRouterSnapshot {serviceName}` + +`serviceName` is the name of the service to be collected, which supports matching + +``` +dubbo>getRouterSnapshot com.dubbo.dubbointegration.BackendService +com.dubbo.dubbointegration.BackendService@2c2e824a +[ All Invokers: 2 ] [ Valid Invokers: 2 ] + +MockInvokersSelector Total: 2 +[ Mocked -> Empty (Total: 0) ] +[ Normal -> 172.18.111.187:20880,172.18.111.183:20880 (Total: 2) ] + ↓ +StandardMeshRuleRouter not support + ↓ +TagStateRouter not support + ↓ +ServiceStateRouter not support + ↓ +AppStateRouter not support + ↓ +TailStateRouterEnd + + +dubbo> +``` + +## enableRouterSnapshot command + +Enable routing result collection mode + +Command: `enableRouterSnapshot {serviceName}` + +`serviceName` is the name of the service to be collected, which supports matching + +``` +dubbo>enableRouterSnapshot com.dubbo.* +OK. Found service count: 1. This will cause performance degradation, please be careful! + +dubbo> +``` + +## disableRouterSnapshot command + +Disable routing result collection mode + +Command: `disableRouterSnapshot {serviceName}` + +`serviceName` is the name of the service to be collected, which supports matching + +``` +dubbo>disableRouterSnapshot com.dubbo.* +OK. Found service count: 1 + +dubbo> +``` + +## getEnabledRouterSnapshot command + +Get the services that are currently collecting + +``` +dubbo>getEnabledRouterSnapshot +com.dubbo.dubbointegration.BackendService + +dubbo> +``` + +## getRecentRouterSnapshot command + +Obtain the historical routing status through the qos command. (up to 32 results stored) + +``` +dubbo>getRecentRouterSnapshot +1658224330156 - Router snapshot service com.dubbo.dubbointegration.BackendService from registry 172.18.111.184 on the consumer 172.18.111.184 using the dubbo version 3.0.9 is below: +[ Parent (Input: 2) (Current Node Output: 2) (Chain Node Output: 2) ] Input: 172.18.111.187:20880,172.18.111.183:20880 -> Chain Node Output: 172.18.111.187:20880.3172.18 :20880 + [ MockInvokersSelector (Input: 2) (Current Node Output: 2) (Chain Node Output: 2) Router message: invocation.need.mock not set. Return normal Invokers. ] Current Node Output: 172.18.111.187:20880,172.183.111. :20880 + [ StandardMeshRuleRouter (Input: 2) (Current Node Output: 2) (Chain Node Output: 2) Router message: MeshRuleCache has not been built. Skip route. ] Current Node Output: 172.18.111.187:20880,172.1803:1121.88 + [ TagStateRouter (Input: 2) (Current Node Output: 2) (Chain Node Output: 2) Router message: Disable Tag Router. Reason: tagRouterRule is invalid or disabled ] Current Node Output: 172.18.111.187:20880,172.183.111. 20880 + [ ServiceStateRouter (Input: 2) (Current Node Output: 2) (Chain Node Output: 2) Router message: Directly return. Reason: Invokers from previous router is empty or conditionRouters is empty. ] Current Node Output: 172.18.111.187:20880 ,172.18.111.183:20880 + [ AppStateRouter (Input: 2) (Current Node Output: 2) (Chain Node Output: 2) Router message: Directly return. Reason: Invokers from previous router is empty or conditionRouters is empty. ] Current Node Output: 172.18.111.187:20880 ,172.18.111.183:20880 + +1658224330156 - Router snapshot service com.dubbo.dubbointegration.BackendService from registry 172.18.111.184 on the consumer 172.18.111.184 using the dubbo version 3.0.9 is below: +[ Parent (Input: 2) (Current Node Output: 2) (Chain Node Output: 2) ] Input: 172.18.111.187:20880,172.18.111.183:20880 -> Chain Node Output: 172.18.111.187:20880.3172.18 :20880 + [ MockInvokersSelector (Input: 2) (Current Node Output: 2) (Chain Node Output: 2) Router message: invocation.need.mock not set. Return normal Invokers. ] Current Node Output: 172.18.111.187:20880,172.183.111. :20880 + [ StandardMeshRuleRouter (Input: 2) (Current Node Output: 2) (Chain Node Output: 2) Router message: MeshRuleCache has not been built. Skip route. ] Current Node Output: 172.18.111.187:20880,172.1803:1121.88 + [ TagStateRouter (Input: 2) (Current Node Output: 2) (Chain Node Output: 2) Router message: Disable Tag Router. Reason: tagRouterRule is invalid or disabled ] Current Node Output: 172.18.111.187:20880,172.183.111. 20880 + [ ServiceStateRouter (Input: 2) (Current Node Output: 2) (Chain Node Output: 2) Router message: Directly return. Reason: Invokers from previous router is empty or conditionRouters is empty. ] Current Node Output: 172.18.111.187:20880 ,172.18.111.183:20880 + [ AppStateRouter (Input: 2) (Current Node Output: 2) (Chain Node Output: 2) Router message: Directly return. Reason: Invokers from previous router is empty or conditionRouters is empty. ] Current Node Output: 172.18.111.187:20880 ,172.18.111.183:20880 + +··· + +dubbo> +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/qos/service-management.md b/content/en/docs3-v2/java-sdk/reference-manual/qos/service-management.md new file mode 100644 index 000000000000..dff83efdf452 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/qos/service-management.md @@ -0,0 +1,74 @@ +--- +type: docs +title: "Service Management Commands" +linkTitle: "Service Management Command" +weight: 3 +description: "Service Management Command" +--- + + +## ls command + +List consumers and providers + +``` +dubbo>ls +As Provider side: ++------------------------------------------------- -----------------------+---------------------+ +| Provider Service Name | PUB | ++------------------------------------------------- -----------------------+---------------------+ +|DubboInternal - UserRead/org.apache.dubbo.metadata.MetadataService:1.0.0| | ++------------------------------------------------- -----------------------+---------------------+ +| com.dubbo.dubbointegration.UserReadService |nacos-A(Y)/nacos-I(Y)| ++------------------------------------------------- -----------------------+---------------------+ +As Consumer side: ++-----------------------------------------+------- ----------+ +| Consumer Service Name | NUM | ++-----------------------------------------+------- ----------+ +|com.dubbo.dubbointegration.BackendService|nacos-AF(I-2,A-2)| ++-----------------------------------------+------- ----------+ + +``` + +List the services provided and consumed by dubbo, as well as the number of service addresses consumed. + +Note: +- Services prefixed with `DubboInternal` are built-in services of Dubbo, and are not registered with the registry by default. +- The first part of `nacos-A(Y)` in the service publishing status is the corresponding registry name, and the second part is the registration mode (`A` stands for application-level address registration, `I` stands for interface-level address registration), The third part represents whether the corresponding mode has been registered +- The first part of `nacos-AF(I-2,A-2)` in the service subscription status is the corresponding registration center name, and the second part is the subscription mode (`AF` stands for dual subscription mode, `FA` stands for only Application-level subscription, `FI` stands for interface-level subscription only), the first half of the third part represents the source of the address mode (`A` stands for application-level address, `I` stands for interface-level address), and the second half represents the corresponding number of addresses + +## online + +### online commands + +Online online service command + +When using the delayed release function (by setting org.apache.dubbo.config.AbstractServiceConfig#register to false), when you need to go online later, you can use the Online command +``` +//Online all services +dubbo>online +OK + +//According to the rules, launch some services +dubbo>online com.* +OK +``` + +## log off + + +### offline command + +Offline service command + +Due to failure and other reasons, it is necessary to temporarily go offline to maintain the site, and you can use the Offline offline command. + +``` +//Offline all services +dubbo>offline +OK + +//According to the rules, some services are offline +dubbo>offline com.* +OK +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/registry/_index.md b/content/en/docs3-v2/java-sdk/reference-manual/registry/_index.md new file mode 100644 index 000000000000..e01cd5ce8995 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/registry/_index.md @@ -0,0 +1,7 @@ +--- +type: docs +title: "Registration Center Description" +linkTitle: "Description of Registration Center" +weight: 5 +description: "The design and working method of the Dubbo registration center covers the mainstream registration centers adapted by Dubbo such as Zookeeper and Nacos" +--- \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/registry/multicast/_index.md b/content/en/docs3-v2/java-sdk/reference-manual/registry/multicast/_index.md new file mode 100644 index 000000000000..8b161351fc63 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/registry/multicast/_index.md @@ -0,0 +1,52 @@ +--- +type: docs +title: "Multicast" +linkTitle: "Multicast" +weight: 4 +description: "Multicast broadcast registration center (use only in development stage)." +--- + +The Multicast registration center does not need to start any central nodes, as long as the broadcast address is the same, they can discover each other. + +![/user-guide/images/multicast.jpg](/imgs/user/multicast.jpg) + +## 1 Instructions for use + +```xml + +``` + +or + +```xml + +``` +#### Notice: +In order to reduce the amount of broadcasting, Dubbo uses unicast to send provider address information to consumers by default. +If multiple consumer processes are started on a machine at the same time, the consumer must declare `unicast=false`, otherwise only one consumer can receive the message; when the server and the consumer run on the same machine, the consumer It is also necessary to declare `unicast=false`, otherwise the consumer cannot receive the message, resulting in No provider available for the service exception: + +```xml + + + +``` + +or + +```xml + + + +``` + + +## 2 How it works + +### 2.1 Basic process +0. The provider broadcasts its own address when it starts +1. Broadcast subscription request when consumer starts +2. When the provider receives the subscription request, it will unicast its own address to the subscribers. If `unicast=false` is set, it will broadcast to the subscribers +3. When the consumer receives the provider's address, it connects to the address to make an RPC call. + +### 2.2 Restrictions on Use +Multicast is limited by the network structure and is only suitable for small-scale applications or development stages. Multicast address segment: 224.0.0.0 - 239.255.255.255 \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/registry/multiple-registry/_index.md b/content/en/docs3-v2/java-sdk/reference-manual/registry/multiple-registry/_index.md new file mode 100644 index 000000000000..0c7a737fddea --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/registry/multiple-registry/_index.md @@ -0,0 +1,187 @@ +--- +type: docs +title: "Multiple Registries" +linkTitle: "Multiple Registration Centers" +weight: 6 +description: "This article introduces Dubbo's multi-registry support and usage scenarios, how to implement cross-regional service deployment and service migration through multi-registration/multi-subscription, and also describes the implementation of traffic scheduling across computer rooms with limited access to the same computer room." +--- + +## 1 Associated service and multiple registration centers + +### 1.1 Global Default Registration Center + +The Dubbo registry and services are configured independently. Usually, developers do not need to set the relationship between services and registry components. The Dubbo framework will automatically perform the following actions: +* For all Service services, register the service address with all global default registries. +* For all Reference services, subscribe service addresses from all global default registries. + +```yml +# application.yml (Spring Boot) +dubbo + registries + beijing Registry + address: zookeeper://localhost:2181 + shanghai Registry + address: zookeeper://localhost:2182 +``` + +```java +@DubboService +public class DemoServiceImpl implements DemoService {} + +@DubboService +public class HelloServiceImpl implements HelloService {} +``` + +The above takes Spring Boot development as an example (XML and API methods are similar) to configure two global default registries, beijingRegistry and shanghaiRegistry, and the services DemoService and HelloService will be registered to the two default registries respectively. + +In addition to the framework mentioned above to automatically set the global registry for the service, there are two ways to flexibly adjust the association between the service and multiple registry. + +### 1.2 Set the global default registration center +```yml +# application.yml (Spring Boot) +dubbo + registries + beijing Registry + address: zookeeper://localhost:2181 + default: true + shanghai Registry + address: zookeeper://localhost:2182 + default: false +``` + +`default` is used to set the global default registry, the default value is `true` which is regarded as the global registry. Services that do not specify a registry id will automatically register or subscribe to the global default registry. + +### 1.3 Display associated services and registry + +By adding the registry configuration to the Dubbo service definition component, the service is associated with the registry. + +```java +@DubboServiceregistry = {"beijingRegistry"} +public class DemoServiceImpl implements DemoService {} + +@DubboServiceregistry = {"shanghaiRegistry"} +public class HelloServiceImpl implements HelloService {} +``` + +After adding the above configuration, DemoService will only be registered to beijingRegistry, and HelloService will be registered to shanghaiRegistry. + +## 2 Multi-registry subscription + +Since service subscription involves address aggregation and routing address selection, the logic will be more complicated. From the perspective of a single service subscription, if there is a multi-registry subscription, it can be divided into two scenarios according to whether the addresses between the registries are aggregated. + +### 2.1 Multi-registry addresses are not aggregated + +```xml + + +``` + +For the independently configured registry component shown above, the address list is completely isolated on the consumer side by default, and the load balancing address selection needs to go through two steps: +1. Site selection among the registration center clusters, select a cluster +2. Select the address in the registration center cluster, and perform address screening in the cluster + +![multi-registris-no-aggregation](/imgs/v3/registry/no-aggregation.png) + +Below we will focus on how to control **Registration center inter-cluster site selection**, the optional strategies are as follows +**random** +Each request is randomly assigned to a registry cluster + +> There will be an availability check in the random process, that is, each cluster must ensure that at least one address is available before it can be selected. + +**preferred priority** +```xml + + +``` +If there is a registry cluster configured with `preferred="true"`, all traffic will be routed to this cluster. + +**weighted** +```xml + + +``` + +Based on weighted random load balancing, there will be about 10:1 traffic distribution among the above clusters. + +**same zone priority** +```xml + + +``` + +```java +RpcContext.getContext().setAttachment("registry_zone", "qingdao"); +``` + +According to the traffic parameters carried in the Invocation or the parameters set through the context context on the current node, the traffic will be accurately guided to the corresponding cluster. + +### 2.2 Multi-registry address aggregation +```xml + +``` + +Here, a registration center starting with a special multiple protocol is added, where: +* `multiple://127.0.0.1:2181` has no specific meaning, it is just a placeholder in a specific format, and the address can be specified at will +* `reference-registry` specifies the list of registry clusters to be aggregated. In the example, there are two clusters, `zookeeper://address11?backup=address12,address13` and `zookeeper://address21?backup=address22` ,address23`, which also specifies the cluster separator `separator=";"` + +As shown in the figure below, the addresses of different registration center clusters will be aggregated into one address pool for load balancing or routing address selection on the consumer side. + +![multi-registris-aggregation](/imgs/v3/registry/aggregation.png) + +In version 3.1.0 and later, it is also supported to set specific attachments attributes on each registry cluster to achieve specific marking of addresses under the registry cluster, and then cooperate with Router component extensions such as TagRouter to realize cross-machine rooms traffic management capabilities. + +```xml + +``` + +After adding `attachments=zone=hangzhou,tag=middleware`, all URL addresses from the registration center will automatically carry the two identifiers of `zone` and `tag`, which facilitates more flexible traffic management on the consumer side. + +## 3 Scenario example + +### 3.1 Scenario 1: Cross-region registration service + +For example: Some services of the Chinese website are too late to be deployed in Qingdao, and are only deployed in Hangzhou, while other applications in Qingdao need to reference this service, so the service can be registered to two registration centers at the same time. + +```xml + + + + +``` + +### 3.2 Scenario 2: Isolation based on business + +Some CRM services are specially designed for international websites, and some services are specially designed for Chinese websites. + +```xml + + + + + + + +``` + +### 3.3 Scenario 3: Invoking services based on business + +CRM needs to call the PC2 service of the Chinese station and the international station at the same time. PC2 is deployed in both the Chinese station and the international station. The interface and version number are the same, but the connected database is different. + +```xml + + + + + + + +``` + +If only the test environment temporarily needs to connect to two different registration centers, use vertical symbols to separate multiple different registration center addresses: + +```xml + + + + +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/registry/nacos/_index.md b/content/en/docs3-v2/java-sdk/reference-manual/registry/nacos/_index.md new file mode 100644 index 000000000000..4d131bbaadd4 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/registry/nacos/_index.md @@ -0,0 +1,190 @@ +--- +type: docs +title: "Nacos" +linkTitle: "Nacos" +weight: 3 +description: "The basic usage and working principle of the Nacos registry." +--- + +## 1 precondition +* Understand [Dubbo basic development steps](../../../quick-start/spring-boot/) +* Install and start [Nacos service](https://nacos.io/zh-cn/docs/quick-start.html) +>When Dubbo uses `3.0.0` and above, it needs to use Nacos `2.0.0` and above. + +## 2 Instructions for use +Check here [full sample code](https://github.com/apache/dubbo-samples/tree/master/3-extensions/registry/dubbo-samples-nacos/dubbo-samples-nacos-registry) + +### 2.1 Add dependencies +```xml + + + org.apache.dubbo + dubbo + 3.0.9 + + + com.alibaba.nacos + nacos-client + 2.1.0 + + + + +``` +Add Dubbo and Nacos dependencies + +> Dubbo `3.0.0` and above require nacos-client `2.0.0` and above + +### 2.2 Configure and enable Nacos + +```yaml +# application.yml (Spring Boot) +dubbo + registry + address: nacos://localhost:8848 +``` +or +```properties +# dubbo.properties +dubbo.registry.address=nacos://localhost:8848 +``` +or +```xml + +``` + +To enable the app, see what it looks like after registration or how it works, see [How it works](#4-How it works). + +## 3 Advanced configuration + +### 3.1 Authentication + +```yaml +# application.yml (Spring Boot) +dubbo + registry + address: nacos://localhost:8848?username=nacos&password=nacos +``` + +or + +```properties +# dubbo.properties +dubbo.registry.address: nacos://nacos:nacos@localhost:8848 +``` + +### 3.2 Custom namespace + +```yaml +# application.yml (Spring Boot) +dubbo: + registry: + address: nacos://localhost:8848?namespace=5cbb70a5-xxx-xxx-xxx-d43479ae0932 +``` + +or + +```yaml +# application.yml (Spring Boot) +dubbo: + registry: + address: nacos://localhost:8848 + parameters.namespace: 5cbb70a5-xxx-xxx-xxx-d43479ae0932 +``` + +### 3.3 Custom grouping + +```yaml +# application.yml +dubbo: + registry: + address: nacos://localhost:8848 + group: dubbo +``` + +> If not configured, the group is specified by Nacos by default. Group and namespace represent different isolation levels in Nacos. Generally speaking, namespace is used to isolate different users or environments, and group is used to further group data in the same environment. + +### 3.4 Register interface-level consumers +After Dubbo3.0.0, the parameter of whether to register consumers is added. If you need to register consumers to the nacos registration center, you need to set the parameter (register-consumer-url) to true, and the default is false. +```yaml +# application.yml +dubbo: + registry: + address: nacos://localhost:8848?register-consumer-url=true +``` +or +```yaml +# application.yml +dubbo: + registry: + address: nacos://localhost:8848 + parameters.register-consumer-url: true + +``` + +### 3.5 More configurations + +Parameter name | Chinese description | Default value +---|---|--- +username|username to connect to Nacos Server|nacos +paasword|password to connect to Nacos Server|nacos +backup|backup address|null +namespace|Namespace ID|public +group|group name|DEFAULT_GROUP +register-consumer-url|Whether to register the consumer side|false +com.alibaba.nacos.naming.log.filename|initialization log file name|naming.log +endpoint|Connect to the connection point specified by Nacos Server, please refer to [documentation](https://nacos.io/zh-cn/blog/address-server.html)|empty +endpointPort|Connect to the connection point port specified by Nacos Server, you can refer to [documentation](https://nacos.io/zh-cn/blog/address-server.html)|empty +endpointQueryParams|endpoint query parameter query|null +isUseCloudNamespaceParsing|whether to parse namespace parameters in the cloud environment|true +isUseEndpointParsingRule|whether to enable endpoint parameter rule parsing|true +namingLoadCacheAtStart|whether to read the local cache first at startup|true +namingCacheRegistryDir|Specify the cache subdirectory, the location is .../nacos/{SUB_DIR}/naming|empty +namingClientBeatThreadCount | client heartbeat thread pool size | half of the number of CPUs of the machine +namingPollingThreadCount|Client timing polling thread pool size for data update|half of the CPU number of the machine +namingRequestDomainMaxRetryCount|Number of retries requested by client to Nacos Server via HTTP|3 +namingPushEmptyProtection|When the service does not have a valid (healthy) instance, whether to enable the protection, after enabling it, the old service instance will be used|false +push.receiver.udp.port|port of client UDP|null + +After the nacos-server@`1.0.0` version, the client is supported to control some behaviors of the instance by reporting some instances containing specific metadata to the server. + +Parameter name | Chinese description | Default value +---|---|--- +preserved.heart.beat.timeout|The time (in milliseconds) from healthy to unhealthy after the instance does not send a heartbeat|15000 +preserved.ip.delete.timeout|The instance is deleted by the server after the instance does not send a heartbeat (milliseconds)|30000 +preserved.heart.beat.interval|Interval time for the instance to report the heartbeat on the client (milliseconds)|5000 +preserved.instance.id.generator|The id generation strategy of this instance, when the value is `snowflake`, it will increase from 0|simple +preserved.register.source|Registration instance registration service framework type (such as Dubbo, Spring Cloud, etc.)|empty + +These parameters can be configured to Nacos through parameter expansion in a manner similar to `namespace`, such as + + ```properties + dubbo.registry.parameters.preserved.heart.beat.timeout=5000 + ``` + +## 4 How it works + +The following is just to show the working principle of Nacos as the Dubbo registration center. It is recommended to use [Dubbo Admin](https://github.com/apache/dubbo-admin) for Dubbo service operation and maintenance + +### 4.1 Dubbo2 registration data + +Then, restart your Dubbo application, and Dubbo's service provision and consumption information can be displayed in the Nacos console: + +![dubbo-registry-nacos-1.png](/imgs/blog/dubbo-registry-nacos-1.png) + +As shown in the figure, the service name prefixed with `providers:` is the meta information of the service provider, and `consumers:` represents the meta information of the service consumer. Click "**Details**" to view the service status details: + +![image-dubbo-registry-nacos-2.png](/imgs/blog/dubbo-registry-nacos-2.png) + +### 4.2 Dubbo3 registration data +The "service name" for application-level service discovery is the application name + + + +> Dubbo3 adopts the dual registration mode of "application-level service discovery + interface-level service discovery" by default, so you will find that application-level services (application names) and interface-level services (interface names) appear in the Nacos console at the same time, you can configure `dubbo .registry.register-mode=instance/interface/all` to change the registration behavior. \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/registry/overview/_index.md b/content/en/docs3-v2/java-sdk/reference-manual/registry/overview/_index.md new file mode 100644 index 000000000000..c485a10a1d0a --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/registry/overview/_index.md @@ -0,0 +1,76 @@ +--- +type: docs +title: "Overview" +linkTitle: "Overview" +weight: 1 +description: "" +--- + +The registration center is the core component of Dubbo service governance. Dubbo relies on the coordination of the registration center to realize service (address) discovery. Automatic service discovery is the basis for microservices to achieve dynamic scaling, load balancing, and traffic management. Dubbo's service discovery mechanism has experienced interface-level service discovery in the Dubbo2 era and application-level service discovery in the Dubbo3 era. For details, see [Service Discovery Mechanism](/en/docs3-v2/java-sdk/concepts-and-architecture/service -discovery/) analysis to understand the specific evolution process. + +## Basic usage +The Dubbo registry component must be specified when developing an application. The configuration is very simple, just specify the cluster address of the registry: + +Taking Spring Boot development as an example, add a registry configuration item in application.yml + +```yaml +dubbo + registry + address: {protocol}://{cluster-address} +``` +Among them, protocol is the selected configuration center type, and cluster-address is the cluster address for accessing the registration center, such as + +`address: nacos://localshot:8848` + +If you need a cluster format address, you can use the backup parameter + +`address: nacos://localshot:8848?backup=localshot:8846,localshot:8847` + +> The application must specify the Dubbo registration center, even if the registration center is not enabled (you can set the address to be empty address='N/A' ). + +In addition to the rest, depending on each configuration center, you can refer to the [registry configuration reference manual](/en/docs3-v2/java-sdk/reference-manual/config/properties/#registry) or expand through the parameters parameter. + +## Configuration Center and Metadata Center +The configuration center and metadata center are the basic components to realize Dubbo's high-level service governance capabilities. Compared with the registration center, the configuration of these two components is usually optional. + +In order to be compatible with configurations of 2.6 and older versions, Dubbo will use it as both a metadata center and a configuration center for some registry types (such as Zookeeper, Nacos, etc.). + +```yaml +dubbo + registry + address: nacos://localhost:8848 +``` + +Default behavior after frame resolution + +```yaml +dubbo + registry + address: nacos://localhost:8848 + config-center + address: nacos://localhost:8848 + metadata-report + address: nacos://localhost:8848 +``` + +The default behavior can be adjusted or controlled by the following two parameters + +```yaml +dubbo + registry + address: nacos://localhost:8848 + use-as-config-center: false + use-as-metadata-report: false +``` + +## Registration Center Ecology +The mainstream registry implementations currently supported by the Dubbo backbone include +* Zookeeper +* Nacos +* Redis + +It also supports service discovery of Kubernetes and Mesh systems. + +In addition, [Dubbo extension ecology](https://github.com/apache/dubbo-spi-extensions) also provides registry extension implementations such as Consul, Eureka, and Etcd. Also welcome to contribute more registry implementations to the Dubbo ecosystem through [registry spi extension](../../spi/). + +Dubbo also supports [specifying multiple registries] (../multiple-registry/) in an application, and grouping services according to registries, which makes service group management or service migration easier. \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/registry/redis/_index.md b/content/en/docs3-v2/java-sdk/reference-manual/registry/redis/_index.md new file mode 100644 index 000000000000..054965a6b5f2 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/registry/redis/_index.md @@ -0,0 +1,74 @@ +--- +type: docs +title: "Redis" +linkTitle: "Redis" +weight: 5 +description: "The basic usage and working principle of the Redis registry." +--- + +## precondition +* Understand [Dubbo basic development steps](../../../quick-start/spring-boot/) +* Install and start the [Redis](http://redis.io) service + +## Instructions for use + +```xml + +``` + +or + +```xml + +``` + +or + +```xml + +``` + +or + +```xml + +``` + +## options + +* You can set the prefix of the key in redis through ``, the default is `dubbo`. +* The redis cluster strategy can be set via ``, the default is `failover`: + * `failover`: Only write and read any one, and retry another one when it fails, the server needs to configure data synchronization by itself + * `replicate`: Write to all servers at the same time on the client side, only read a single server, the server side does not need to be synchronized, the registration center cluster increases, and the performance pressure will also be greater + + +## working principle + +A registry implemented based on Redis [^1]. + +Redis expired data detects dirty data through heartbeat, the server time must be synchronized, and there is a certain pressure on the server, otherwise the expiration detection will be inaccurate + +![/user-guide/images/dubbo-redis-registry.jpg](/imgs/user/dubbo-redis-registry.jpg) + +Use Redis's Key/Map structure to store data structures: + +* The main key is the service name and type +* The Key in the Map is the URL address +* The Value in the Map is the expiration time, which is used to judge dirty data, and the dirty data will be deleted by the monitoring center [^3] + +Use Redis's Publish/Subscribe events to notify data changes: + +* Differentiate the event type by the value of the event: `register`, `unregister`, `subscribe`, `unsubscribe` +* Ordinary consumers directly subscribe to the Key of the specified service provider, and will only receive `register`, `unregister` events of the specified service +* The monitoring center subscribes to `/dubbo/*` through the `psubscribe` function, and will receive all change events of all services + +Call process: + +0. When the service provider starts, add the address of the current provider to `Key:/dubbo/com.foo.BarService/providers` +1. And send `register` event to `Channel:/dubbo/com.foo.BarService/providers` +2. When the service consumer starts, subscribe to `register` and `unregister` events from `Channel:/dubbo/com.foo.BarService/providers` +3. Add the address of the current consumer to `Key:/dubbo/com.foo.BarService/consumers` +4. After receiving the `register` and `unregister` events, the service consumer obtains the provider address list from `Key:/dubbo/com.foo.BarService/providers` +5. When the service monitoring center starts, subscribe to `register` and `unregister`, and `subscribe` and `unsubscribe` events from `Channel:/dubbo/*` +6. After receiving the `register` and `unregister` events, the service monitoring center obtains the provider address list from `Key:/dubbo/com.foo.BarService/providers` +7. After receiving the `subscribe` and `unsubscribe` events, the service monitoring center obtains the consumer address list from `Key:/dubbo/com.foo.BarService/consumers` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/registry/simple.md b/content/en/docs3-v2/java-sdk/reference-manual/registry/simple.md new file mode 100644 index 000000000000..568b6d5b3b2a --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/registry/simple.md @@ -0,0 +1,58 @@ +--- +type: docs +title: "Simple Registry" +linkTitle: "Simple" +weight: 7 +description: "Simple Registry Reference Manual" +--- + +{{% pageinfo %}} This function has been removed in Dubbo 2.7, please select [other registry](../) for migration. +{{% /pageinfo %}} + +The Simple registry itself is an ordinary Dubbo service, which can reduce third-party dependencies and make the overall communication method consistent. + +## configuration + +Expose the Simple registry as a Dubbo service: + +```xml + + + + + + + + + + + + + + +``` + +Quoting the Simple Registry service: + +```xml + +``` + +or: + +```xml + +``` + +or: + +```xml + +``` + +## Applicability Notes + +This `SimpleRegistryService` is just a simple implementation and does not support clustering. It can be used as a reference for a custom registry, but it is not suitable for direct use in a production environment. \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/registry/zookeeper/_index.md b/content/en/docs3-v2/java-sdk/reference-manual/registry/zookeeper/_index.md new file mode 100644 index 000000000000..2ccc1a8716d1 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/registry/zookeeper/_index.md @@ -0,0 +1,133 @@ +--- +type: docs +title: "Zookeeper" +linkTitle: "Zookeeper" +weight: 2 +description: "The basic usage and working principle of the Zookeeper registry." +--- + +## 1 precondition +* Understand [Dubbo basic development steps](../../../quick-start/spring-boot/) +* Install and start [Zookeeper](https://zookeeper.apache.org/) + +## 2 Instructions for use +Check out [full sample code](https://github.com/apache/dubbo-samples/tree/master/3-extensions/registry/dubbo-samples-zookeeper) here + +### 2.1 Add Maven dependency +```xml + + 3.0.8 + + + + + org.apache.dubbo + dubbo + ${dubbo.version} + + + + org.apache.dubbo + dubbo-dependencies-zookeeper + ${dubbo.version} + pom + + +``` + +`dubbo-dependencies-zookeeper` will automatically add Zookeeper-related client dependencies to the application, reducing the cost of using Zookeeper for users. If there is a version compatibility problem during use, users can also add it by themselves instead of using `dubbo-dependencies-zookeeper` Curator, Zookeeper Client and other dependencies. + +Since Dubbo uses Curator as a programming client interacting with Zookeeper Server, special attention should be paid to the compatibility between Zookeeper Server and Dubbo version dependencies + +|Zookeeper Server Version|Dubbo Version|Dubbo Zookeeper Dependency Package|Description| +|-----|-----|-----|-----| +|3.4.x and below|3.0.x and above|dubbo-dependencies-zookeeper|transitive dependencies Curator 4.x, Zookeeper 3.4.x| +|3.5.x and above|3.0.x and above|dubbo-dependencies-zookeeper-curator5|transitive dependencies Curator 5.x, Zookeeper 3.7.x| +|3.4.x and above|2.7.x and below|dubbo-dependencies-zookeeper|transitive dependencies Curator 4.x, Zookeeper 3.4.x| +|3.5.x and above|2.7.x and below|None|Need to add Curator, Zookeeper and other related client dependencies| + +### 2.2 Configure and enable Zookeeper +```yaml +# application.yml +dubbo + registry + address: zookeeper://localhost:2181 +``` +or +```properties +# dubbo.properties +dubbo.registry.address=zookeeper://localhost:2181 +``` +or +```xml + +``` + +`address` is the only attribute that must be specified to enable the zookeeper registration center, and in a production environment, `address` is usually specified as the cluster address, such as + +`address=zookeeper://10.20.153.10:2181?backup=10.20.153.11:2181,10.20.153.12:2181` + +It is also possible to configure protocol and address separately, such as + +`` + +## 3 Advanced configuration +### 3.1 Authentication and Authorization + +If Zookeeper enables authentication, Dubbo supports passing in the identity by specifying username and password. + +```yaml +# application.yml +dubbo + registry + address: zookeeper://localhost:2181 + username: hello + password: 1234 +``` + +You can also directly expand the parameters on the address `address=zookeeper://hello:1234@localhost:2181` + +### 3.2 Group isolation +By specifying the `group` attribute, the logical isolation of microservice addresses can be achieved within the same Zookeeper cluster. For example, multiple sets of development environments can be isolated in one cluster, and isolation can be achieved at the address discovery level. + +```yaml +# application.yml +dubbo + registry + address: zookeeper://localhost:2181 + group: daily1 +``` +### 3.3 Other extended configurations +Configure connection and session expiration time +```yaml +# application.yml +dubbo + registry + address: zookeeper://localhost:2181 + timeout: 30 * 1000* # Connection timeout, default 30s + session: 60 * 1000* # Session timeout, default 60s +``` + +The Zookeeper registry also supports some other control parameters, for details, see [Registry configuration item manual](../../config/properties#registry) + +## 4 How it works +### 4.1 Dubbo2 node structure + +![/user-guide/images/zookeeper.jpg](/imgs/user/zookeeper.jpg) + +process: +* When the service provider starts: write its own URL address to the `/dubbo/com.foo.BarService/providers` directory. +* When the service consumer starts: subscribe to the provider URL address under the `/dubbo/com.foo.BarService/providers` directory. And write your own URL address to `/dubbo/com.foo.BarService/consumers` directory +* When monitoring center starts: subscribe to all provider and consumer URL addresses under `/dubbo/com.foo.BarService` directory. + +The following functions are supported: + +* When the provider has abnormal downtime such as power failure, the registration center can automatically delete the provider information +* When the registration center restarts, the registration data and subscription requests can be automatically restored +* When the session expires, the registration data and subscription request can be automatically restored +* When `` is set, the failed registration and subscription requests will be recorded, and the background will retry periodically +* You can set zookeeper login information through `` +* The root node of zookeeper can be set through ``, if not configured, the default root node will be used. +* Support `*` wildcard ``, you can subscribe to all groups of services and providers of all versions + +### 4.2 Dubbo3 node structure \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/spi/_index.md b/content/en/docs3-v2/java-sdk/reference-manual/spi/_index.md new file mode 100755 index 000000000000..4dd88f9f8c06 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/spi/_index.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "SPI Extension Manual" +linkTitle: "SPI Extension Manual" +weight: 9 +--- \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/spi/description/_index.md b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/_index.md new file mode 100644 index 000000000000..7504e5b12640 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/_index.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "Dubbo SPI extension implementation description" +linkTitle: "Dubbo SPI extension implementation description" +weight: 2 +--- \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/spi/description/cache.md b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/cache.md new file mode 100644 index 000000000000..9f9997eb6144 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/cache.md @@ -0,0 +1,88 @@ +--- +type: docs +title: "Cache Extension" +linkTitle: "Cache Extension" +weight: 24 +--- + +## Expansion Description + +Use the request parameter as the key to cache the returned result. + +## Extension ports + +`org.apache.dubbo.cache.CacheFactory` + +## Extended configuration + +```xml + + + + + +``` + +## Known extensions + +* `org.apache.dubbo.cache.support.lru.LruCacheFactory` +* `org.apache.dubbo.cache.support.threadlocal.ThreadLocalCacheFactory` +* `org.apache.dubbo.cache.support.jcache.JCacheFactory` + + +## Extended example + +Maven project structure: + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxCacheFactory.java (implements the CacheFactory interface) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.cache.CacheFactory (plain text file, content: xxx=com.xxx.XxxCacheFactory) +``` + +XxxCacheFactory.java: + +```java +package com.xxx; + +import org.apache.dubbo.cache.CacheFactory; + +public class XxxCacheFactory implements CacheFactory { + public Cache getCache(URL url, String name) { + return new XxxCache(url, name); + } +} +``` + +XxxCache.java: + +```java +package com.xxx; + +import org.apache.dubbo.cache.Cache; + +public class XxxCache implements Cache { + public Cache(URL url, String name) { + //... + } + public void put(Object key, Object value) { + //... + } + public Object get(Object key) { + //... + } +} +``` + +META-INF/dubbo/org.apache.dubbo.cache.CacheFactory: + +```properties +xxx=com.xxx.XxxCacheFactory +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/spi/description/cluster.md b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/cluster.md new file mode 100644 index 000000000000..a55d31e0b36d --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/cluster.md @@ -0,0 +1,83 @@ +--- +type: docs +title: "Cluster Expansion" +linkTitle: "Cluster Expansion" +weight: 5 +--- + +## Expansion Description + +When there are multiple service providers, organize multiple service providers into a cluster and pretend to be one provider. + +## Extension ports + +`org.apache.dubbo.rpc.cluster.Cluster` + +## Extended configuration + +```xml + + + +``` + +## Known extensions + +* `org.apache.dubbo.rpc.cluster.support.wrapper.MockClusterWrapper` +* `org.apache.dubbo.rpc.cluster.support.FailoverCluster` +* `org.apache.dubbo.rpc.cluster.support.FailfastCluster` +* `org.apache.dubbo.rpc.cluster.support.FailsafeCluster` +* `org.apache.dubbo.rpc.cluster.support.FailbackCluster` +* `org.apache.dubbo.rpc.cluster.support.ForkingCluster` +* `org.apache.dubbo.rpc.cluster.support.AvailableCluster` +* `org.apache.dubbo.rpc.cluster.support.MergeableCluster` +* `org.apache.dubbo.rpc.cluster.support.BroadcastCluster` +* `org.apache.dubbo.rpc.cluster.support.registry.ZoneAwareCluster` + +## Extended example + +Maven project structure: + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxCluster.java (implements the Cluster interface) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.rpc.cluster.Cluster (plain text file, content: xxx=com.xxx.XxxCluster) +``` + +XxxCluster.java: + +```java +package com.xxx; + +import org.apache.dubbo.rpc.cluster.Cluster; +import org.apache.dubbo.rpc.cluster.support.AbstractClusterInvoker; +import org.apache.dubbo.rpc.cluster.Directory; +import org.apache.dubbo.rpc.cluster.LoadBalance; +import org.apache.dubbo.rpc.Invoker; +import org.apache.dubbo.rpc.Invocation; +import org.apache.dubbo.rpc.Result; +import org.apache.dubbo.rpc.RpcException; + +public class XxxCluster implements Cluster { + public Invoker merge(Directory directory) throws RpcException { + return new AbstractClusterInvoker(directory) { + public Result doInvoke(Invocation invocation, List> invokers, LoadBalance loadbalance) throws RpcException { + //... + } + }; + } +} +``` + +META-INF/dubbo/org.apache.dubbo.rpc.cluster.Cluster: + +```properties +xxx=com.xxx.XxxCluster +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/spi/description/compiler.md b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/compiler.md new file mode 100644 index 000000000000..193d8feaa54c --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/compiler.md @@ -0,0 +1,60 @@ +--- +type: docs +title: "Compiler Extensions" +linkTitle: "Compiler Extensions" +weight: 13 +--- + +## Expansion Description + +Java code compiler, used to dynamically generate bytecode to speed up calls. + +## Extension ports + +`org.apache.dubbo.common.compiler.Compiler` + +## Extended configuration + +autoload + +## Known extensions + +* `org.apache.dubbo.common.compiler.support.JdkCompiler` +* `org.apache.dubbo.common.compiler.support.JavassistCompiler` + +## Extended example + +Maven project structure: + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxCompiler.java (implement Compiler interface) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.common.compiler.Compiler (plain text file, content: xxx=com.xxx.XxxCompiler) +``` + +XxxCompiler.java: + +```java +package com.xxx; + +import org.apache.dubbo.common.compiler.Compiler; + +public class XxxCompiler implements Compiler { + public Object getExtension(Class type, String name) { + //... + } +} +``` + +META-INF/dubbo/org.apache.dubbo.common.compiler.Compiler: + +```properties +xxx=com.xxx.XxxCompiler +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/spi/description/config-center.md b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/config-center.md new file mode 100644 index 000000000000..57e7de7599c5 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/config-center.md @@ -0,0 +1,102 @@ +--- +type: docs +title: "Configuration Center Extension" +linkTitle: "Configuration Center Extension" +weight: 13 +--- + +## aim of design + +The core function of the configuration center is as Key-Value storage. The Dubbo framework informs the configuration center of the key it cares about, and the configuration center returns the value corresponding to the key. + +According to the application scenarios, the configuration center mainly undertakes the following responsibilities in the Dubbo framework: + +- As an external configuration center, it stores the dubbo.properties configuration file. At this time, the key value is usually the file name such as dubbo.properties, and the value is the content of the configuration file. +- Store individual configuration items, such as various switch items, constant values, etc. +- Store service governance rules. At this time, the key is usually organized in the format of "service name + rule type", and the value is the specific governance rule. + +In order to further realize the group management of key-value, Dubbo's configuration center also added the concepts of namespace and group. These concepts are reflected in many professional third-party configuration centers. Usually, namespace is used to isolate different tenants , group is used to group the key collection of the same tenant. + +Currently, the Dubbo configuration center has realized the docking of Zookeeper, Nacos, Etcd, Consul, and Apollo. Next, let’s take a look at how Dubbo’s abstract configuration center is mapped to a specific third-party implementation. + +## Extension ports + +* `org.apache.dubbo.configcenter.DynamicConfigurationFactory` +* `org.apache.dubbo.configcenter.DynamicConfiguration` + +## Known extensions + +* `org.apache.dubbo.configcenter.support.zookeeper.ZookeeperDynamicConfigurationFactory` +* `org.apache.dubbo.configcenter.support.nacos.NacosDynamicConfigurationFactory` +* `org.apache.dubbo.configcenter.support.etcd.EtcdDynamicConfigurationFactory` +* `org.apache.dubbo.configcenter.consul.ConsulDynamicConfigurationFactory` +* `org.apache.dubbo.configcenter.support.apollo.ApolloDynamicConfigurationFactory` +* `org.apache.dubbo.common.config.configcenter.file.FileSystemDynamicConfigurationFactory` + +## Implementation principle + +### Zookeeper + +zookeeper provides a tree-like storage model, the implementation principle is as follows: + +![image-20190127225608553](/imgs/dev/configcenter_zk_model.jpg) + +namespace, group, key, etc. correspond to different levels of ZNode nodes, and value is stored as the value of the root ZNode node. + +1. External configuration center dubbo.properties + + ![image-20190127225608553](/imgs/dev/configcenter_zk_properties.jpg) + + The figure above shows the storage structure of dubbo.properties files in two different scopes in zookeeper: + - Namespace namespace is: dubbo + - Grouping group: the global level is dubbo, shared by all applications; the application level is the application name demo-provider, which only takes effect for this application + - key: dubbo.properties + +2. Single configuration item + + ![image-20190127225608553](/imgs/dev/configcenter_zk_singleitem.jpg) + + Set the graceful shutdown event to 15000: + - Namespace namespace: dubbo + - Grouping group: dubbo + - key: dubbo.service.shutdown.wait + - value: 15000 + +3. Service Governance Rules + + ![image-20190127225608553](/imgs/dev/configcenter_zk_rule.jpg) + + The figure above shows an application-level conditional routing rule: + + - Namespace namespace: dubbo + - Grouping group: dubbo + - key: governance-conditionrouter-consumer.condition-router, where governance-conditionrouter-consumer is the application name, and condition-router represents conditional routing + + + > Note: + > + > Dubbo supports service governance rules at two granularities of application and service at the same time. For these two granularities, the key value rules are as follows: + > * Application granularity {application name + rule suffix}. Such as: `demo-application.configurators`, `demo-application.tag-router`, etc. + > * Service granularity {service interface name:[service version]:[service group] + rule suffix}, where service version and service group are optional, if they are configured, they will be reflected in the key, if they are not configured, use " :"Occupy place. Such as + > `org.apache.dubbo.demo.DemoService::.configurators`, `org.apache.dubbo.demo.DemoService:1.0.0:group1.configurators` + +### Etcd & Consul + +Etcd and Consul are essentially a tree-like storage structure similar to zookeeper. For implementation, please refer to zookeeper. + +### Nacos + +As a professional third-party configuration center, Nacos has a storage structure specially designed for configuration centers, including built-in concepts such as namespace, group, and dataid. And these concepts are basically in one-to-one correspondence with the abstract configuration center of the Dubbo framework. + +The corresponding relationship with Zookeeper implementation is as follows: + +![image-20190127225608553](/imgs/dev/configcenter_nacos_model.jpg) + +Referring to the example described above about the zookeeper implementation, the dataid here may be: +* External configuration center: dubbo.properties +* Single configuration item: dubbo.service.shutdown.wait +* Service governance rules: org.apache.dubbo.demo.DemoService:1.0.0:group1.configurators + +### Apollo + +Apollo is similar to Nacos, please refer to the description about Apollo in the Dynamic Configuration Center Documentation. \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/spi/description/container.md b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/container.md new file mode 100644 index 000000000000..6e287baf6fbd --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/container.md @@ -0,0 +1,67 @@ +--- +type: docs +title: "Container Extension" +linkTitle: "Container Extension" +weight: 22 +--- + +## Expansion Description + +Service container extension for custom loading content. + +## Extension ports + +`org.apache.dubbo.container.Container` + +## Extended configuration + +```sh +java org.apache.dubbo.container.Main spring jetty log4j +``` + +## Known extensions + +* `org.apache.dubbo.container.spring.SpringContainer` +* `org.apache.dubbo.container.spring.JettyContainer` +* `org.apache.dubbo.container.spring.Log4jContainer` + +## Extended example + +Maven project structure: + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxContainer.java (implements the Container interface) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.container.Container (plain text file, content: xxx=com.xxx.XxxContainer) +``` + +XxxContainer.java: + +```java +package com.xxx; + +org.apache.dubbo.container.Container; + + +public class XxxContainer implements Container { + public Status start() { + //... + } + public Status stop() { + //... + } +} +``` + +META-INF/dubbo/org.apache.dubbo.container.Container: + +```properties +xxx=com.xxx.XxxContainer +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/spi/description/dispatcher.md b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/dispatcher.md new file mode 100644 index 000000000000..5b99c65a893b --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/dispatcher.md @@ -0,0 +1,67 @@ +--- +type: docs +title: "Message Dispatch Extension" +linkTitle: "Message dispatch extension" +weight: 14 +--- + +## Expansion Description + +Channel information dispatcher, used to specify the thread pool model. + +## Extension ports + +`org.apache.dubbo.remoting.Dispatcher` + +## Extended configuration + +```xml + + + +``` + +## Known extensions + +* `org.apache.dubbo.remoting.transport.dispatcher.all.AllDispatcher` +* `org.apache.dubbo.remoting.transport.dispatcher.direct.DirectDispatcher` +* `org.apache.dubbo.remoting.transport.dispatcher.message.MessageOnlyDispatcher` +* `org.apache.dubbo.remoting.transport.dispatcher.execution.ExecutionDispatcher` +* `org.apache.dubbo.remoting.transport.dispatcher.connection.ConnectionOrderedDispatcher` + +## Extended example + +Maven project structure: + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxDispatcher.java (implements the Dispatcher interface) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.remoting.Dispatcher (plain text file, content: xxx=com.xxx.XxxDispatcher) +``` + +XxxDispatcher.java: + +```java +package com.xxx; + +import org.apache.dubbo.remoting.Dispatcher; + +public class XxxDispatcher implements Dispatcher { + public Group lookup(URL url) { + //... + } +} +``` + +META-INF/dubbo/org.apache.dubbo.remoting.Dispatcher: + +```properties +xxx=com.xxx.XxxDispatcher +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/spi/description/dubbo-spi.md b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/dubbo-spi.md new file mode 100644 index 000000000000..1f46d386c1f4 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/dubbo-spi.md @@ -0,0 +1,705 @@ +--- +type: docs +title: "Extension Point Development Guide" +linkTitle: "Extension Point Development Guide" +weight: 0 +description: "This article introduces the principle and implementation details of Dubbo SPI" +--- + +## 1 Introduction + +The full name of SPI is Service Provider Interface, which is a service discovery mechanism. The essence of SPI is to configure the fully qualified name of the interface implementation class in the file, and the service loader reads the configuration file and loads the implementation class. In this way, the implementation class can be dynamically replaced for the interface at runtime. Because of this feature, we can easily provide extended functions for our programs through the SPI mechanism. The SPI mechanism is also used in third-party frameworks. For example, Dubbo loads all components through the SPI mechanism. However, Dubbo does not use Java's native SPI mechanism, but enhances it to better meet the needs. In Dubbo, SPI is a very important module. Based on SPI, we can easily expand Dubbo. +In Dubbo, SPI has two main usages, one is to load fixed extension classes, and the other is to load adaptive extension classes. These two methods will be described in detail below. +Special attention should be paid to: In Dubbo, classes loaded based on SPI extensions are singletons. + +### 1.1 Load fixed extension classes + +If you were asked to design and load fixed extension classes, what would you do? +A common idea is to read the configuration file in a specific directory, then parse out the full class name, instantiate the class through the reflection mechanism, and then store the class in the collection. If necessary, directly from the collection Take. The implementation in Dubbo is also such an idea. +However, in Dubbo, the implementation is more complete, and it implements the functions of IOC and AOP. IOC means that if this extended class depends on other properties, Dubbo will automatically inject this property. How is this function implemented? A common idea is to get the setter of this extended class +method, call the setter method for property injection. What does AOP refer to? This means that Dubbo can inject its wrapper class into the extension class. For example, DubboProtocol is an extension class of Protocol, and ProtocolListenerWrapper is a wrapper class of DubboProtocol. + +### 1.2 Load adaptive extension class + +First explain the usage scenarios of adaptive extension classes. For example, we have a requirement that when calling a certain method, we can call different implementation classes based on parameter selection. Somewhat similar to the factory method, different instance objects are constructed based on different parameters. +The idea of implementation in Dubbo is similar to this, but the implementation of Dubbo is more flexible, and its implementation is somewhat similar to the strategy mode. Each extension class is equivalent to a strategy. Based on the URL message bus, the parameters are passed to the ExtensionLoader, and the corresponding extension class is loaded based on the parameters through the ExtensionLoader to realize the dynamic call to the target instance at runtime. + +## 2. Dubbo SPI source code analysis + +### 2.1 Load fixed extension class + +In Dubbo, the entry point for SPI to load fixed extension classes is the getExtension method of ExtensionLoader. Next, we will analyze the process of obtaining extension class objects in detail. + +```java +public T getExtension(String name) { + if (name == null || name. length() == 0) + throw new IllegalArgumentException("Extension name == null"); + if ("true".equals(name)) { + // Get the default extension implementation class + return getDefaultExtension(); + } + // Holder, as the name suggests, is used to hold the target object + Holder holder = cachedInstances. get(name); + // This logic ensures that only one thread can create a Holder object + if (holder == null) { + cachedInstances. putIfAbsent(name, new Holder()); + holder = cachedInstances. get(name); + } + Object instance = holder. get(); + // double check + if (instance == null) { + synchronized (holder) { + instance = holder. get(); + if (instance == null) { + // create extension instance + instance = createExtension(name); + // set the instance to the holder + holder.set(instance); + } + } + } + return (T) instance; +} +``` + +The logic of the above code is relatively simple. First, the cache is checked, and if the cache misses, an extended object is created. Let's take a look at the process of creating an extended object. + +```java +private T createExtension(String name, boolean wrap) { + // Load all extension classes from the configuration file to get the mapping relationship table from "configuration item name" to "configuration class" + Class clazz = getExtensionClasses().get(name); + // If there is no extension of the interface, or the implementation class of the interface does not allow repetition but actually repeats, an exception is thrown directly + if (clazz == null || unacceptableExceptions. contains(name)) { + throw findException(name); + } + try { + T instance = (T) EXTENSION_INSTANCES. get(clazz); + // This code ensures that the extended class will only be constructed once, which is a singleton. + if (instance == null) { + EXTENSION_INSTANCES.putIfAbsent(clazz, clazz.getDeclaredConstructor().newInstance()); + instance = (T) EXTENSION_INSTANCES. get(clazz); + } + // Inject dependencies into the instance + injectExtension(instance); + + // Automatically wrap if wrapping is enabled. + // For example, I defined the extension of DubboProtocol based on Protocol, but in fact, DubboProtocol is not directly used in Dubbo, but its wrapper class + // ProtocolListenerWrapper + if (wrap) { + + List> wrapperClassesList = new ArrayList<>(); + if (cachedWrapperClasses != null) { + wrapperClassesList.addAll(cachedWrapperClasses); + wrapperClassesList.sort(WrapperComparator. COMPARATOR); + Collections. reverse(wrapperClassesList); + } + + // Loop to create Wrapper instances + if (CollectionUtils. isNotEmpty(wrapperClassesList)) { + for (Class wrapperClass : wrapperClassesList) { + Wrapper wrapper = wrapperClass. getAnnotation(Wrapper. class); + if (wrapper == null + || (ArrayUtils.contains(wrapper.matches(), name) && !ArrayUtils.contains(wrapper.mismatches(), name))) { + // Pass the current instance as a parameter to the constructor of Wrapper, and create a Wrapper instance through reflection. + // Then inject dependencies into the Wrapper instance, and finally assign the Wrapper instance to the instance variable again + instance = injectExtension((T) wrapperClass. getConstructor(type). newInstance(instance)); + } + } + } + } + // initialization + initExtension(instance); + return instance; + } catch (Throwable t) { + throw new IllegalStateException("Extension instance (name: " + name + ", class: " + + type + ") couldn't be instantiated: " + t. getMessage(), t); + } +} +``` + +The logic of the createExtension method is a little more complicated, including the following steps: + +1. Get all extension classes through getExtensionClasses +2. Create an extended object through reflection +3. Inject dependencies into extended objects +4. Wrap the extension object in the corresponding Wrapper object +5. Initialize the extension object + +Among the above steps, the first step is the key to loading the extension class, and the third and fourth steps are the specific implementation of Dubbo IOC and AOP. In the following chapters, we will focus on analyzing the logic of the getExtensionClasses method and briefly introduce the specific implementation of Dubbo IOC. + +### 2.1.1 Get all extension classes + +Before we obtain the extension class by name, we first need to parse out the mapping relationship table from the extension item name to the extension class (Map\) according to the configuration file, and then extract it from the mapping relationship table according to the extension item name The corresponding extension class can be. The code analysis of the relevant process is as follows: + +```java +private Map> getExtensionClasses() { + // Get the loaded extension class from the cache + Map> classes = cachedClasses. get(); + // double check + if (classes == null) { + synchronized (cachedClasses) { + classes = cachedClasses. get(); + if (classes == null) { + // load extension class + classes = loadExtensionClasses(); + cachedClasses.set(classes); + } + } + } + return classes; +} +``` + +Here is also to check the cache first, and if the cache misses, lock it through synchronized. After locking, check the cache again and find it empty. At this time, if classes is still null, the extension class is loaded through loadExtensionClasses. Let's analyze the logic of the loadExtensionClasses method. + +```java +private Map> loadExtensionClasses() { + // Cache the default SPI extension + cacheDefaultExtensionName(); + + Map> extensionClasses = new HashMap<>(); + + // Load the files in the specified folder based on the policy + // Currently there are four strategies to read the configuration files in META-INF/services/ META-INF/dubbo/ META-INF/dubbo/internal/ META-INF/dubbo/external/ respectively + for (LoadingStrategy strategy : strategies) { + loadDirectory(extensionClasses, strategy.directory(), type.getName(), strategy.preferExtensionClassLoader(), strategy.overridden(), strategy.excludedPackages()); + loadDirectory(extensionClasses, strategy.directory(), type.getName().replace("org.apache", "com.alibaba"), strategy.preferExtensionClassLoader(), strategy.overridden(), strategy.excludedPackages()); + } + + return extensionClasses; +} +``` + +The loadExtensionClasses method does two things in total, one is to parse the SPI annotations, and the other is to call the loadDirectory method to load the specified folder configuration file. The process of parsing SPI annotations is relatively simple, so there is no need to say more. Let's take a look at what loadDirectory does. + +```java +private void loadDirectory(Map> extensionClasses, String dir, String type, + boolean extensionLoaderClassLoaderFirst, boolean overridden, String... excludedPackages) { + // fileName = folder path + type fully qualified name + String fileName = dir + type; + try { + Enumeration urls = null; + ClassLoader classLoader = findClassLoader(); + + // try to load from ExtensionLoader's ClassLoader first + if (extensionLoaderClassLoaderFirst) { + ClassLoader extensionLoaderClassLoader = ExtensionLoader. class. getClassLoader(); + if (ClassLoader. getSystemClassLoader() != extensionLoaderClassLoader) { + urls = extensionLoaderClassLoader. getResources(fileName); + } + } + // Load all files with the same name according to the file name + if (urls == null || !urls.hasMoreElements()) { + if (classLoader != null) { + urls = classLoader. getResources(fileName); + } else { + urls = ClassLoader. getSystemResources(fileName); + } + } + + if (urls != null) { + while (urls. hasMoreElements()) { + java.net.URL resourceURL = urls.nextElement(); + // load resources + loadResource(extensionClasses, classLoader, resourceURL, overridden, excludedPackages); + } + } + } catch (Throwable t) { + logger.error("Exception occurred when loading extension class (interface: " + + type + ", description file: " + fileName + ").", t); + } +} +``` + +The loadDirectory method first obtains all resource links through classLoader, and then loads resources through the loadResource method. Let's go ahead and take a look at the implementation of the loadResource method. + +```java +private void loadResource(Map> extensionClasses, ClassLoader classLoader, + java.net.URL resourceURL, boolean overridden, String... excludedPackages) { + try { + try (BufferedReader reader = new BufferedReader(new InputStreamReader(resourceURL. openStream(), StandardCharsets. UTF_8))) { + String line; + String clazz = null; + // Read configuration content line by line + while ((line = reader. readLine()) != null) { + // locate # characters + final int ci = line. indexOf('#'); + if (ci >= 0) { + // Intercept the string before #, the content after # is a comment, which needs to be ignored + line = line. substring(0, ci); + } + line = line. trim(); + if (line. length() > 0) { + try { + String name = null; + // Use the equal sign = as the boundary to intercept the key and value + int i = line. indexOf('='); + if (i > 0) { + name = line.substring(0, i).trim(); + clazz = line.substring(i + 1).trim(); + } else { + clazz = line; + } + // Load the class and cache the class through the loadClass method + if (StringUtils.isNotEmpty(clazz) && !isExcluded(clazz, excludedPackages)) { + loadClass(extensionClasses, resourceURL, Class. forName(clazz, true, classLoader), name, overridden); + } + } catch (Throwable t) { + IllegalStateException e = new IllegalStateException("Failed to load extension class (interface: " + type + ", class line: " + line + ") in " + resourceURL + ", cause: " + t.getMessage(), t); + exceptions. put(line, e); + } + } + } + } + } catch (Throwable t) { + logger.error("Exception occurred when loading extension class (interface: " + + type + ", class file: " + resourceURL + ") in " + resourceURL, t); + } +} +``` + +The loadResource method is used to read and parse configuration files, load classes through reflection, and finally call the loadClass method for other operations. The loadClass method is mainly used to operate the cache. The logic of this method is as follows: + +```java +private void loadClass(Map> extensionClasses, java.net.URL resourceURL, Class clazz, String name, + boolean overridden) throws NoSuchMethodException { + if (!type.isAssignableFrom(clazz)) { + throw new IllegalStateException("Error occurred when loading extension class (interface: " + + type + ", class line: " + clazz. getName() + "), class " + + clazz.getName() + " is not subtype of interface."); + } + // Check if there are Adaptive annotations on the target class + if (clazz. isAnnotationPresent(Adaptive. class)) { + cacheAdaptiveClass(clazz, overridden); + } else if (isWrapperClass(clazz)) { + // cache wrapper class + cacheWrapperClass(clazz); + } else { + // Enter here, indicating that this class is just an ordinary extension class + // Check if clazz has a default constructor, if not, throw an exception + clazz. getConstructor(); + if (StringUtils. isEmpty(name)) { + // If name is empty, try to get name from Extension annotation, or use lowercase class name as name + name = findAnnotationName(clazz); + if (name. length() == 0) { + throw new IllegalStateException("No such extension name for the class " + clazz. getName() + " in the config " + resourceURL); + } + } + + String[] names = NAME_SEPARATOR. split(name); + if (ArrayUtils. isNotEmpty(names)) { + // If the class has the Activate annotation, use the first element of the names array as the key, + // Store the mapping relationship between name and Activate annotation object + cacheActivateClass(clazz, names[0]); + for (String n : names) { + // Store the mapping relationship from Class to name + cacheName(clazz, n); + // Store the mapping relationship from name to Class. + // If there are multiple implementation classes corresponding to the same extension, whether overriding is allowed based on the override parameter, if not, an exception is thrown. + saveInExtensionClass(extensionClasses, clazz, n, overridden); + } + } + } +} +``` + +As above, the loadClass method operates different caches, such as cachedAdaptiveClass, cachedWrapperClasses and cachedNames, etc. Apart from that, there is no other logic in this method. + +At this point, the analysis of the process of caching class loading is over. There is nothing particularly complicated in the whole process. You can analyze it step by step, and you can debug it if you don’t understand it. Next, let's talk about Dubbo IOC. + +### 2.1.2 Dubbo IOC + +Dubbo IOC injects dependencies through the setter method. Dubbo first obtains all methods of the instance through reflection, and then traverses the method list to detect whether the method name has the characteristics of a setter method. If so, obtain the dependent object through ObjectFactory, and finally call the setter method through reflection to set the dependency to the target object. The code corresponding to the whole process is as follows: + +```java +private T injectExtension(T instance) { + + if (objectFactory == null) { + return instance; + } + + try { + // traverse all methods of the target class + for (Method method : instance. getClass(). getMethods()) { + // Check whether the method starts with set, and the method has only one parameter, and the method access level is public + if (!isSetter(method)) { + continue; + } + /** + * Detect whether there is DisableInject annotation modification. + */ + if (method. getAnnotation(DisableInject. class) != null) { + continue; + } + + /** + * Detect whether the ScopeModelAware and ExtensionAccessorAware classes are implemented, and if implemented, do not inject + */ + if (method. getDeclaringClass() == ScopeModelAware. class) { + continue; + } + if (instance instanceof ScopeModelAware || instance instanceof ExtensionAccessorAware) { + if (ignoredInjectMethodsDesc. contains(ReflectUtils. getDesc(method))) { + continue; + } + } + + // Primitive types are not injected + Class pt = method. getParameterTypes()[0]; + if (ReflectUtils. isPrimitives(pt)) { + continue; + } + + try { + // Get the attribute name, for example, the setName method corresponds to the attribute name name + String property = getSetterProperty(method); + // Get dependent objects from ObjectFactory + Object object = objectFactory. getExtension(pt, property); + if (object != null) { + // inject + method.invoke(instance, object); + } + } catch (Exception e) { + logger.error("Failed to inject via method " + method.getName() + + " of interface " + type. getName() + ": " + e. getMessage(), e); + } + + } + } catch (Exception e) { + logger. error(e. getMessage(), e); + } + return instance; +} +``` + +In the above code, the type of the objectFactory variable is AdaptiveExtensionFactory, and AdaptiveExtensionFactory internally maintains an ExtensionFactory list for storing other types of ExtensionFactory. Dubbo currently provides two types of ExtensionFactory, namely SpiExtensionFactory and SpringExtensionFactory. The former is used to create adaptive extensions, and the latter is used to obtain the required extensions from Spring's IOC container. The codes of these two classes are not very complicated, so I won't analyze them one by one here. + +Dubbo IOC currently only supports setter injection. Generally speaking, the logic is relatively simple and easy to understand. + +### 2.2 Load adaptive extension class + +The meaning of adaptive extension class is that, based on parameters, a specific target class is dynamically selected at runtime and then executed. +In Dubbo, many extensions are loaded through the SPI mechanism, such as Protocol, Cluster, LoadBalance, etc. Sometimes, some extensions do not want to be loaded during the framework startup phase, but want to be loaded according to runtime parameters when the extension method is called. This sounds contradictory. If the extension is not loaded, the extension methods cannot be called (except static methods). If the extension method is not called, the extension cannot be loaded. For this contradictory problem, Dubbo has solved it well through the adaptive expansion mechanism. The implementation logic of the self-adaptive expansion mechanism is relatively complicated. First, Dubbo will generate code with proxy functions for the expansion interface. Then compile this code through javassist or jdk to get the Class class. Finally, the proxy class is created through reflection, and the whole process is more complicated. + +The entry point for loading adaptive extension classes is the getAdaptiveExtension method of ExtensionLoader. + +```java +public T getAdaptiveExtension() { + // Get the adaptive extension from the cache + Object instance = cachedAdaptiveInstance. get(); + if (instance == null) { + // If there is an exception, throw it directly + if (createAdaptiveInstanceError != null) { + throw new IllegalStateException("Failed to create adaptive instance: " + + createAdaptiveInstanceError.toString(), + createAdaptiveInstanceError); + } + + synchronized (cachedAdaptiveInstance) { + instance = cachedAdaptiveInstance. get(); + // double check + if (instance == null) { + try { + // create adaptive extension + // There are two cases here: one is that there is an Adaptive class, and the other is that an Adaptive class needs to be generated + instance = createAdaptiveExtension(); + cachedAdaptiveInstance.set(instance); + } catch (Throwable t) { + createAdaptiveInstanceError = t; + throw new IllegalStateException("Failed to create adaptive instance: " + t.toString(), t); + } + } + } + } + + return (T) instance; +} +``` + +The getAdaptiveExtension method will first check the cache, and if the cache misses, call the createAdaptiveExtension method to create an adaptive extension. Next, let's look at the code of the createAdaptiveExtension method. + +```java +private T createAdaptiveExtension() { + try { + // Get the adaptive extension class and instantiate it through reflection + return injectExtension((T) getAdaptiveExtensionClass(). newInstance()); + } catch (Exception e) { + throw new IllegalStateException("Can not create adaptive extension ..."); + } +} +``` +The code of the createAdaptiveExtension method is relatively small, but it contains three logics, which are as follows: + +1. Call the getAdaptiveExtensionClass method to obtain the adaptive extension Class object +2. Instantiation via reflection +3. Call the injectExtension method to inject dependencies into the extension instance + +The first two logics are easy to understand, and the third logic is used to inject dependencies into adaptive extension objects. This logic may seem redundant, but it is necessary to exist. Here is a brief explanation. As mentioned earlier, there are two types of adaptive extensions in Dubbo, one is manually coded and the other is automatically generated. There may be some dependencies in the hand-coded Adaptive extension, while the automatically generated Adaptive extension will not depend on other classes. The purpose of calling the injectExtension method here is to inject dependencies for the hand-coded adaptive extension, which requires everyone to pay attention. Regarding the injectExtension method, it has been analyzed in the previous article, so I won’t go into details here. Next, analyze the logic of the getAdaptiveExtensionClass method. + +```java +private Class getAdaptiveExtensionClass() { + // Get all extension classes through SPI + getExtensionClasses(); + // Check the cache, if the cache is not empty, return the cache directly + if (cachedAdaptiveClass != null) { + return cachedAdaptiveClass; + } + // Create an adaptive extension class + return cachedAdaptiveClass = createAdaptiveExtensionClass(); +} +``` + +The getAdaptiveExtensionClass method also contains three logics, as follows: + +1. Call getExtensionClasses to get all extension classes +2. Check the cache, if the cache is not empty, return the cache +3. If the cache is empty, call createAdaptiveExtensionClass to create an adaptive extension class + +These three logics seem unremarkable, and there seems to be no need to talk about them. But there are some details hidden in this bland code that need to be explained. First, let’s start with the first logic. The getExtensionClasses method is used to get all the implementation classes of an interface. For example, this method can obtain DubboProtocol, HttpProtocol, InjvmProtocol and other implementation classes of the Protocol interface. In the process of obtaining the implementation class, if an implementation class is modified by the Adaptive annotation, then the class will be assigned to the cachedAdaptiveClass variable. At this point, the condition of the second step in the above steps is satisfied (the cache is not empty), just return the cachedAdaptiveClass directly. If all implementation classes are not modified by Adaptive annotations, then execute the logic of the third step to create adaptive extension classes. The relevant code is as follows: + +```java +private Class createAdaptiveExtensionClass() { + // Build adaptive extension code + String code = new AdaptiveClassCodeGenerator(type, cachedDefaultName).generate(); + ClassLoader classLoader = findClassLoader(); + // Get the compiler implementation class + org.apache.dubbo.common.compiler.Compiler compiler = ExtensionLoader.getExtensionLoader(org.apache.dubbo.common.compiler.Compiler.class).getAdaptiveExtension(); + // Compile the code and generate Class + return compiler.compile(code, classLoader); +} +``` + +The createAdaptiveExtensionClass method is used to generate an adaptive extension class. This method first generates the source code of the adaptive extension class, and then compiles the source code through a Compiler instance (Dubbo uses javassist as the compiler by default) to obtain a proxy class Class instance. Next, we will focus on the logic of proxy class code generation, and analyze other logic by yourself. + +### 2.2.1 Adaptive extension class code generation + +AdaptiveClassCodeGenerator#generate method generates extension class code +```java +public String generate() { + // If there is no method in the interface modified by the @Adaptive annotation, an exception is thrown directly + if (!hasAdaptiveMethod()) { + throw new IllegalStateException("No adaptive method exist on extension " + type.getName() + ", refuse to create the adaptive class!"); + } + + StringBuilder code = new StringBuilder(); + // Generate package name, import, method, etc. + code.append(generatePackageInfo()); + code.append(generateImports()); + code.append(generateClassDeclaration()); + + Method[] methods = type. getMethods(); + for (Method method : methods) { + code.append(generateMethod(method)); + } + code.append("}"); + + if (logger. isDebugEnabled()) { + logger. debug(code. toString()); + } + return code. toString(); +} + +``` + +#### 2.2.2 Generation method + +In the above code, the logic of the generation method is the most critical, let's analyze it in detail. +```java +private String generateMethod(Method method) { + String methodReturnType = method. getReturnType(). getCanonicalName(); + String methodName = method. getName(); + // generate method content + String methodContent = generateMethodContent(method); + String methodArgs = generateMethodArguments(method); + String methodThrows = generateMethodThrows(method); + return String. format(CODE_METHOD_DECLARATION, methodReturnType, methodName, methodArgs, methodThrows, methodContent); +} +``` + +generateMethodContent Analysis + +```java +private String generateMethodContent(Method method) { + // This method must be decorated with @Adaptive annotation + Adaptive adaptiveAnnotation = method. getAnnotation(Adaptive. class); + StringBuilder code = new StringBuilder(512); + if (adaptiveAnnotation == null) { + // Without @Adaptive annotation modification, exception information is generated + return generateUnsupported(method); + } else { + // Get the index of the URL on the parameter list + int urlTypeIndex = getUrlTypeIndex(method); + + if (urlTypeIndex != -1) { + // Generate a null check for the URL if it exists on the parameter list + code.append(generateUrlNullCheck(urlTypeIndex)); + } else { + // If there is no parameter of URL type in the parameter list, then it depends on whether the parameter object on the parameter list contains the getUrl method + // If there is, generate a URL null check + code.append(generateUrlAssignmentIndirectly(method)); + } + // parse the value attribute on the Adaptive annotation + String[] value = getMethodAdaptiveValue(adaptiveAnnotation); + // If there is a parameter of type Invocation on the parameter list, generate a null check and get the methodName. + boolean hasInvocation = hasInvocationArgument(method); + + code.append(generateInvocationArgumentNullCheck(method)); + // This logic is mainly to generate extName (that is, the extension) + // Divided into multiple situations: + // 1. Does defaultExtName exist? + // 2. Whether there is an invocation type parameter in the parameter + // 3. Whether to generate a proxy for the protocol + // Why should the protocol be considered separately? Because there is a method to get the protocol value in the URL + code.append(generateExtNameAssignment(value, hasInvocation)); + // check extName == null? + code.append(generateExtNameNullCheck(value)); + + // generate get extension (using ExtensionLoader.getExtension method) + code.append(generateExtensionAssignment()); + + // generate return statement + code.append(generateReturnAndInvocation(method)); + } + + return code. toString(); +} +``` + +The above logic mainly does the following things: +1. Check whether the Adaptive annotation is modified on the method +2. When generating code for a method, there must be a URL on the parameter list (or a URL in the parameter object) +3. Use ExtensionLoader.getExtension to get the extension +4. Execute the corresponding method + +### 2.2.3 Attach an example of dynamically generated code + +```java +package org.apache.dubbo.common.extension.adaptive; + +import org.apache.dubbo.common.extension.ExtensionLoader; + + +public class HasAdaptiveExt$Adaptive implements org.apache.dubbo.common.extension.adaptive.HasAdaptiveExt { + public java.lang.String echo(org.apache.dubbo.common.URL arg0, + java. lang. String arg1) { + // URL null check + if (arg0 == null) { + throw new IllegalArgumentException("url == null"); + } + + org.apache.dubbo.common.URL url = arg0; + // get the extension + String extName = url. getParameter("has. adaptive. ext", "adaptive"); + // extension null check + if (extName == null) { + throw new IllegalStateException( + "Failed to get extension (org.apache.dubbo.common.extension.adaptive.HasAdaptiveExt) name from url (" + + url.toString() + ") use keys([has.adaptive.ext])"); + } + // get extension + org.apache.dubbo.common.extension.adaptive.HasAdaptiveExt extension = (org.apache.dubbo.common.extension.adaptive.HasAdaptiveExt) ExtensionLoader.getExtensionLoader(org.apache.dubbo.common.extension.adaptive.HasAdaptiveExt.class) + .getExtension(extName); + // Execute the corresponding method + return extension.echo(arg0, arg1); + } +} + +``` + + +## 3. SPI extension example + +### 3.1 Load fixed extension class + +### 3.1.1 Write SPI interface and implementation class + +Whether it is Java SPI or SPI implemented in Dubbo, you need to write an interface. However, the interface in Dubbo needs to be decorated with @SPI annotation. + +```java +@SPI +public interface DemoSpi { + void say(); +} + +public class DemoSpiImpl implements DemoSpi { + public void say() { + } +} +``` + +#### 3.1.2 Put the implementation class in a specific directory + +From the above code, we can see that when dubbo loads the extension class, it will read from four directories. We create a new file named after the DemoSpi interface in the META-INF/dubbo directory, the content is as follows: + + +```text +demoSpiImpl = com.xxx.xxx.DemoSpiImpl (full class name for the implementation class of the DemoSpi interface) +``` + +#### 3.1.3 Use + +```java +public class DubboSPITest { + + @Test + public void sayHello() throws Exception { + ExtensionLoader extensionLoader = + ExtensionLoader. getExtensionLoader(DemoSpi. class); + DemoSpi dmeoSpi = extensionLoader. getExtension("demoSpiImpl"); + optimusPrime. sayHello(); + } +} +``` + +### 3.2 Load adaptive extension class + +This takes Protocol as an example to illustrate + +### 3.2.1 Protocol interface (extract some core methods) + +```java +@SPI("dubbo") +public interface Protocol { + @Adaptive + Exporter export(Invoker invoker) throws RpcException; + + @Adaptive + Invoker refer(Class type, URL url) throws RpcException; +} + +public class DubboProtocol extends AbstractProtocol { +  … + @Override + public Invoker refer(Class type, URL url) throws RpcException { + return protocolBindingRefer(type, url); + } + + @Override + public Exporter export(Invoker invoker) throws RpcException { +  … + return exporter; + } +} +``` + +### 3.2.2 Put the implementation class in a specific directory +In dubbo, the configuration path is META-INF/dubbo/internal/org.apache.dubbo.rpc.Protocol +```text +dubbo=org.apache.dubbo.rpc.protocol.dubbo.DubboProtocol +``` + +It should be noted that in dubbo, DubboProtocol is not used directly, but its wrapper class is used. + +### 3.2.3 Use + +```java +public class DubboAdaptiveTest { + + @Test + public void sayHello() throws Exception { + URL url = URL.valueOf("dubbo://localhost/test"); + Protocol adaptiveProtocol = ExtensionLoader.getExtensionLoader(Protocol.class).getAdaptiveExtension(); + adaptiveProtocol. refer(type, url); + } +} +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/spi/description/exchanger.md b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/exchanger.md new file mode 100644 index 000000000000..ab59dc011d58 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/exchanger.md @@ -0,0 +1,96 @@ +--- +type: docs +title: "Information Exchange Extension" +linkTitle: "Information exchange extension" +weight: 18 +--- + +## Expansion Description + +Based on the transport layer, implement the Request-Response information exchange semantics. + +## Extension ports + +* `org.apache.dubbo.remoting.exchange.Exchanger` +* `org.apache.dubbo.remoting.exchange.ExchangeServer` +* `org.apache.dubbo.remoting.exchange.ExchangeClient` + +## Extended configuration + +```xml + + + +``` + +## Known extensions + +`org.apache.dubbo.remoting.exchange.exchanger.HeaderExchanger` + +## Extended example + +Maven project structure: + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxExchanger.java (implements the Exchanger interface) + |-XxxExchangeServer.java (implements ExchangeServer interface) + |-XxxExchangeClient.java (implements ExchangeClient interface) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.remoting.exchange.Exchanger (plain text file, content: xxx=com.xxx.XxxExchanger) +``` + +XxxExchanger.java: + +```java +package com.xxx; + +import org.apache.dubbo.remoting.exchange.Exchanger; + + +public class XxxExchanger implements Exchanger { + public ExchangeServer bind(URL url, ExchangeHandler handler) throws RemotingException { + return new XxxExchangeServer(url, handler); + } + public ExchangeClient connect(URL url, ExchangeHandler handler) throws RemotingException { + return new XxxExchangeClient(url, handler); + } +} +``` + +XxxExchangeServer.java: + +```java + +package com.xxx; + +import org.apache.dubbo.remoting.exchange.ExchangeServer; + +public class XxxExchangeServer impelements ExchangeServer { + //... +} +``` + +XxxExchangeClient.java: + +```java +package com.xxx; + +import org.apache.dubbo.remoting.exchange.ExchangeClient; + +public class XxxExchangeClient impelments ExchangeClient { + //... +} +``` + +META-INF/dubbo/org.apache.dubbo.remoting.exchange.Exchanger: + +```properties +xxx=com.xxx.XxxExchanger +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/spi/description/exporter-listener.md b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/exporter-listener.md new file mode 100644 index 000000000000..80a0f2bb85c8 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/exporter-listener.md @@ -0,0 +1,70 @@ +--- +type: docs +title: "Expose Listener Extension" +linkTitle: "Expose listener extension" +weight: 4 +--- + +## Expansion Description + +This event is triggered when a service is exposed. + +## Extension ports + +`org.apache.dubbo.rpc.ExporterListener` + +## Extended configuration + +```xml + + + + +``` + +## Known extensions + +`org.apache.dubbo.registry.directory.RegistryExporterListener` + +## Extended example + +Maven project structure: + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxExporterListener.java (implements ExporterListener interface) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.rpc.ExporterListener (plain text file, content: xxx=com.xxx.XxxExporterListener) +``` + +XxxExporterListener.java: + +```java +package com.xxx; + +import org.apache.dubbo.rpc.ExporterListener; +import org.apache.dubbo.rpc.Exporter; +import org.apache.dubbo.rpc.RpcException; + + +public class XxxExporterListener implements ExporterListener { + public void exported(Exporter exporter) throws RpcException { + //... + } + public void unexported(Exporter exporter) throws RpcException { + //... + } +} +``` + +META-INF/dubbo/org.apache.dubbo.rpc.ExporterListener: + +```properties +xxx=com.xxx.XxxExporterListener +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/spi/description/extension-factory.md b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/extension-factory.md new file mode 100644 index 000000000000..fa38be8d45ff --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/extension-factory.md @@ -0,0 +1,62 @@ +--- +type: docs +title: "Extension Point Load Extension" +linkTitle: "Extension point load extension" +weight: 11 +--- + +## Expansion Description + +The loading container of the extension point itself, which can load the extension point from different containers. + +## Extension ports + +`org.apache.dubbo.common.extension.ExtensionFactory` + +## Extended configuration + +```xml + +``` + +## Known extensions + +* `org.apache.dubbo.common.extension.factory.SpiExtensionFactory` +* `org.apache.dubbo.config.spring.extension.SpringExtensionFactory` + +## Extended example + +Maven project structure: + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxExtensionFactory.java (implements ExtensionFactory interface) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.common.extension.ExtensionFactory (plain text file, content: xxx=com.xxx.XxxExtensionFactory) +``` + +XxxExtensionFactory.java: + +```java +package com.xxx; + +import org.apache.dubbo.common.extension.ExtensionFactory; + +public class XxxExtensionFactory implements ExtensionFactory { + public Object getExtension(Class type, String name) { + //... + } +} +``` + +META-INF/dubbo/org.apache.dubbo.common.extension.ExtensionFactory: + +```properties +xxx=com.xxx.XxxExtensionFactory +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/spi/description/filter.md b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/filter.md new file mode 100644 index 000000000000..a6481670a72a --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/filter.md @@ -0,0 +1,94 @@ +--- +type: docs +title: "Call Intercept Extension" +linkTitle: "Call Intercept Extension" +weight: 2 +--- + +## Expansion Description + +Service provider and service consumer call process interception. Most functions of Dubbo itself are implemented based on this extension point. Every time a remote method is executed, this interception will be executed. Please pay attention to the impact on performance. + +agreement: + +* User-defined filters are by default after built-in filters. +* The special value `default`, indicating where the default extension point is inserted. For example: `filter="xxx,default,yyy"`, means `xxx` is before the default filter, and `yyy` is after the default filter. +* The special symbol `-` means culling. For example: `filter="-foo1"`, exclude adding the default extension point `foo1`. For example: `filter="-default"`, remove all default extension points. +* When the provider and service configure filters at the same time, all filters are accumulated instead of overwritten. For example: `` and ``, then `xxx`,`yyy`,`aaa`,`bbb` will take effect. If you want to overwrite, you need to configure: `` + +## Extension ports + +`org.apache.dubbo.rpc.Filter` + +## Extended configuration + +```xml + + + + + + + + +``` + +## Known extensions + +* `org.apache.dubbo.rpc.filter.EchoFilter` +* `org.apache.dubbo.rpc.filter.GenericFilter` +* `org.apache.dubbo.rpc.filter.GenericImplFilter` +* `org.apache.dubbo.rpc.filter.TokenFilter` +* `org.apache.dubbo.rpc.filter.AccessLogFilter` +* `org.apache.dubbo.rpc.filter.CountFilter` +* `org.apache.dubbo.rpc.filter.ActiveLimitFilter` +* `org.apache.dubbo.rpc.filter.ClassLoaderFilter` +* `org.apache.dubbo.rpc.filter.ContextFilter` +* `org.apache.dubbo.rpc.filter.ConsumerContextFilter` +* `org.apache.dubbo.rpc.filter.ExceptionFilter` +* `org.apache.dubbo.rpc.filter.ExecuteLimitFilter` +* `org.apache.dubbo.rpc.filter.DeprecatedFilter` + +## Extended example + +Maven project structure: + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxFilter.java (implement the Filter interface) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.rpc.Filter (plain text file, content: xxx=com.xxx.XxxFilter) +``` + +XxxFilter.java: + +```java +package com.xxx; + +import org.apache.dubbo.rpc.Filter; +import org.apache.dubbo.rpc.Invoker; +import org.apache.dubbo.rpc.Invocation; +import org.apache.dubbo.rpc.Result; +import org.apache.dubbo.rpc.RpcException; + +public class XxxFilter implements Filter { + public Result invoke(Invoker invoker, Invocation invocation) throws RpcException { + // before filter... + Result result = invoker.invoke(invocation); + // after filter... + return result; + } +} +``` + +META-INF/dubbo/org.apache.dubbo.rpc.Filter: + +```properties +xxx=com.xxx.XxxFilter +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/spi/description/invoker-listener.md b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/invoker-listener.md new file mode 100644 index 000000000000..d1f600ec93b0 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/invoker-listener.md @@ -0,0 +1,69 @@ +--- +type: docs +title: "Reference Listener Extension" +linkTitle: "Reference listener extension" +weight: 3 +--- + +## Expansion Description + +This event is triggered when there is a service reference. + +## Extension ports + +`org.apache.dubbo.rpc.InvokerListener` + +## Extended configuration + +```xml + + + + +``` + +## Known extensions + +`org.apache.dubbo.rpc.listener.DeprecatedInvokerListener` + +## Extended example + +Maven project structure: + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxInvokerListener.java (implements the InvokerListener interface) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.rpc.InvokerListener (plain text file, content: xxx=com.xxx.XxxInvokerListener) +``` + +XxxInvokerListener.java: + +```java +package com.xxx; + +import org.apache.dubbo.rpc.InvokerListener; +import org.apache.dubbo.rpc.Invoker; +import org.apache.dubbo.rpc.RpcException; + +public class XxxInvokerListener implements InvokerListener { + public void referred(Invoker invoker) throws RpcException { + //... + } + public void destroyed(Invoker invoker) throws RpcException { + //... + } +} +``` + +META-INF/dubbo/org.apache.dubbo.rpc.InvokerListener: + +```properties +xxx=com.xxx.XxxInvokerListener +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/spi/description/liveness.md b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/liveness.md new file mode 100644 index 000000000000..b4ba1f71b600 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/liveness.md @@ -0,0 +1,72 @@ +--- +type: docs +title: "Liveness Survival Probe" +linkTitle: "Survival Probe" +weight: 12 +--- + +## Expansion Description + + +Expand the detection point of application survival. + + +## Extension ports + + +`org.apache.dubbo.qos.probe.LivenessProbe` + + +## Extended configuration + + +Dubbo QOS `live` command automatic discovery + + +## Known extensions + + +No default implementation yet + + +## Extended example + + +Maven project structure: + + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxLivenessProbe.java (implement LivenessProbe interface) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.qos.probe.LivenessProbe (plain text file, content: xxx=com.xxx.XxxLivenessProbe) +``` + + +XxxLivenessProbe.java: + + +```java +package com.xxx; + +public class XxxLivenessProbe implements LivenessProbe { + + public boolean check() { + //... + } +} +``` + + +META-INF/dubbo/org.apache.dubbo.qos.probe.LivenessProbe: + + +``` +xxx=com.xxx.XxxLivenessProbe +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/spi/description/load-balance.md b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/load-balance.md new file mode 100644 index 000000000000..c4c880b83bf9 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/load-balance.md @@ -0,0 +1,70 @@ +--- +type: docs +title: "Load Balancing Extension" +linkTitle: "Load Balancing Extension" +weight: 7 +--- + +## Expansion Description + +Select one of multiple service providers to call + +## Extension ports + +`org.apache.dubbo.rpc.cluster.LoadBalance` + +## Extended configuration + +```xml + + + +``` + +## Known extensions + +* `org.apache.dubbo.rpc.cluster.loadbalance.RandomLoadBalance` +* `org.apache.dubbo.rpc.cluster.loadbalance.RoundRobinLoadBalance` +* `org.apache.dubbo.rpc.cluster.loadbalance.LeastActiveLoadBalance` +* `org.apache.dubbo.rpc.cluster.loadbalance.ConsistentHashLoadBalance` +* `org.apache.dubbo.rpc.cluster.loadbalance.ShortestResponseLoadBalance` + +## Extended example + +Maven project structure: + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxLoadBalance.java (implements the LoadBalance interface) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.rpc.cluster.LoadBalance (plain text file, content: xxx=com.xxx.XxxLoadBalance) +``` + +XxxLoadBalance.java: + +```java +package com.xxx; + +import org.apache.dubbo.rpc.cluster.LoadBalance; +import org.apache.dubbo.rpc.Invoker; +import org.apache.dubbo.rpc.Invocation; +import org.apache.dubbo.rpc.RpcException; + +public class XxxLoadBalance implements LoadBalance { + public Invoker select(List> invokers, Invocation invocation) throws RpcException { + //... + } +} +``` + +META-INF/dubbo/org.apache.dubbo.rpc.cluster.LoadBalance: + +```properties +xxx=com.xxx.XxxLoadBalance +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/spi/description/logger-adapter.md b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/logger-adapter.md new file mode 100644 index 000000000000..34346c83149a --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/logger-adapter.md @@ -0,0 +1,89 @@ +--- +type: docs +title: "Log Adaptation Extension" +linkTitle: "Log adaptation extension" +weight: 26 +--- + +## Expansion Description + +Log output adaptation extension point. + +## Extension ports + +`org.apache.dubbo.common.logger.LoggerAdapter` + +## Extended configuration + +```xml + +``` + +or: + +```sh +-Ddubbo:application.logger=xxx +``` + +## Known extensions + +* `org.apache.dubbo.common.logger.slf4j.Slf4jLoggerAdapter` +* `org.apache.dubbo.common.logger.jcl.JclLoggerAdapter` +* `org.apache.dubbo.common.logger.log4j.Log4jLoggerAdapter` +* `org.apache.dubbo.common.logger.log4j2.Log4j2LoggerAdapter` +* `org.apache.dubbo.common.logger.jdk.JdkLoggerAdapter` + +## Extended example + +Maven project structure: + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxLoggerAdapter.java (implement LoggerAdapter interface) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.common.logger.LoggerAdapter (plain text file, content: xxx=com.xxx.XxxLoggerAdapter) +``` + +XxxLoggerAdapter.java: + +```java +package com.xxx; + +import org.apache.dubbo.common.logger.LoggerAdapter; + +public class XxxLoggerAdapter implements LoggerAdapter { + public Logger getLogger(URL url) { + //... + } +} +``` + +XxxLogger.java: + +```java +package com.xxx; + +import org.apache.dubbo.common.logger.Logger; + +public class XxxLogger implements Logger { + public XxxLogger(URL url) { + //... + } + public void info(String msg) { + //... + } + //... +} +``` + +META-INF/dubbo/org.apache.dubbo.common.logger.LoggerAdapter: + +```properties +xxx=com.xxx.XxxLoggerAdapter +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/spi/description/merger.md b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/merger.md new file mode 100644 index 000000000000..e6f489cac6e9 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/merger.md @@ -0,0 +1,72 @@ +--- +type: docs +title: "Merge result extension" +linkTitle: "Merge result extension" +weight: 8 +--- + +## Expansion Description + +Merge returns results for grouping and aggregation. + +## Extension ports + +`org.apache.dubbo.rpc.cluster.Merger` + +## Extended configuration + +```xml + +``` + +## Known extensions + +* `org.apache.dubbo.rpc.cluster.merger.ArrayMerger` +* `org.apache.dubbo.rpc.cluster.merger.ListMerger` +* `org.apache.dubbo.rpc.cluster.merger.SetMerger` +* `org.apache.dubbo.rpc.cluster.merger.MapMerger` +* `org.apache.dubbo.rpc.cluster.merger.ByteArrayMerger` +* `org.apache.dubbo.rpc.cluster.merger.CharArrayMerger` +* `org.apache.dubbo.rpc.cluster.merger.ShortArrayMerger` +* `org.apache.dubbo.rpc.cluster.merger.IntArrayMerger` +* `org.apache.dubbo.rpc.cluster.merger.LongArrayMerger` +* `org.apache.dubbo.rpc.cluster.merger.FloatArrayMerger` +* `org.apache.dubbo.rpc.cluster.merger.DoubleArrayMerger` +* `org.apache.dubbo.rpc.cluster.merger.BooleanArrayMerger` + +## Extended example + +Maven project structure: + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxMerger.java (implement Merger interface) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.rpc.cluster.Merger (plain text file, content: xxx=com.xxx.XxxMerger) +``` + +XxxMerger.java: + +```java +package com.xxx; + +import org.apache.dubbo.rpc.cluster.Merger; + +public class XxxMerger implements Merger { + public T merge(T... results) { + //... + } +} +``` + +META-INF/dubbo/org.apache.dubbo.rpc.cluster.Merger: + +```properties +xxx=com.xxx.XxxMerger +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/spi/description/metadata-report.md b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/metadata-report.md new file mode 100644 index 000000000000..a8ad57bc61b5 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/metadata-report.md @@ -0,0 +1,91 @@ +--- +type: docs +title: "Metadata Center Extension" +linkTitle: "Metadata Center Extension" +weight: 13 +--- + +## aim of design +See the [Metadata Center Manual](../../../metadata-center/overview/) + +## Extension ports + +* `org.apache.dubbo.metadata.store.MetadataReportFactory` +* `org.apache.dubbo.metadata.store.MetadataReport` + +## Known extensions + +## Implementation principle + +### SPI definition + +Reference: org.apache.dubbo.metadata.store.MetadataReportFactory, org.apache.dubbo.metadata.store.MetadataReport + +```java +@SPI("redis") +public interface MetadataReportFactory { + @Adaptive({"protocol"}) + MetadataReport getMetadataReport(URL url); +} +``` + + + +### Custom metadata storage + +The following uses Redis storage as an example for illustration. + +To create a new project, you need to support the following modifications: + +#### Extend AbstractMetadataReport + +```java +public class RedisMetadataReport extends AbstractMetadataReport { + private final static Logger logger = LoggerFactory. getLogger(RedisMetadataReport. class); + final JedisPool pool; + + public RedisMetadataReport(URL url) { + super(url); + pool = new JedisPool(new JedisPoolConfig(), url. getHost(), url. getPort()); + } + @Override + protected void doStoreProviderMetadata(ProviderMetadataIdentifier providerMetadataIdentifier, String serviceDefinitions) { + this.storeMetadata(providerMetadataIdentifier, serviceDefinitions); + } + @Override + protected void doStoreConsumerMetadata(ConsumerMetadataIdentifier consumerMetadataIdentifier, String value) { + this.storeMetadata(consumerMetadataIdentifier, value); + } + private void storeMetadata(MetadataIdentifier metadataIdentifier, String v) { + try (Jedis jedis = pool. getResource()) { + jedis.set(metadataIdentifier.getIdentifierKey() + META_DATA_SOTRE_TAG, v); + } catch (Throwable e) { + logger.error("Failed to put " + metadataIdentifier + " to redis " + v + ", cause: " + e.getMessage(), e); + throw new RpcException("Failed to put " + metadataIdentifier + " to redis " + v + ", cause: " + e.getMessage(), e); + } + } +} +``` + +#### Extends AbstractMetadataReportFactory + +```java +public class RedisMetadataReportFactory extends AbstractMetadataReportFactory { + @Override + public MetadataReport createMetadataReport(URL url) { + return new RedisMetadataReport(url); + } +} +``` + +#### Add MetadataReportFactory + +> META-INF/dubbo/internal/org.apache.dubbo.metadata.store.MetadataReportFactory + +```properties +redis=org.apache.dubbo.metadata.store.redis.RedisMetadataReportFactory +``` + +Just pack the above modification and project into a jar package, and then configure the url of the metadata center: redis://10.20.153.10:6379. + +At this point, a custom metadata store is ready to run. \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/spi/description/monitor.md b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/monitor.md new file mode 100644 index 000000000000..3aab26c04561 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/monitor.md @@ -0,0 +1,80 @@ +--- +type: docs +title: "Monitoring Center Extension" +linkTitle: "Monitoring Center Extension" +weight: 10 +--- + +## Expansion Description + +Responsible for the monitoring of service call times and call time. + +## Extension ports + +* `org.apache.dubbo.monitor.MonitorFactory` +* `org.apache.dubbo.monitor.Monitor` + +## Extended configuration + +```xml + + +``` + +## Known extensions + +org.apache.dubbo.monitor.support.dubbo.DubboMonitorFactory + +## Extended example + +Maven project structure: + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxMonitorFactoryjava (implement the MonitorFactory interface) + |-XxxMonitor.java (implement Monitor interface) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.monitor.MonitorFactory (plain text file, content: xxx=com.xxx.XxxMonitorFactory) +``` + +XxxMonitorFactory.java: + +```java +package com.xxx; + +import org.apache.dubbo.monitor.MonitorFactory; +import org.apache.dubbo.monitor.Monitor; +import org.apache.dubbo.common.URL; + +public class XxxMonitorFactory implements MonitorFactory { + public Monitor getMonitor(URL url) { + return new XxxMonitor(url); + } +} +``` + +XxxMonitor.java: + +```java +package com.xxx; + +import org.apache.dubbo.monitor.Monitor; + +public class XxxMonitor implements Monitor { + public void count(URL statistics) { + //... + } +} +``` + +META-INF/dubbo/org.apache.dubbo.monitor.MonitorFactory: + +```properties +xxx=com.xxx.XxxMonitorFactory +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/spi/description/networker.md b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/networker.md new file mode 100644 index 000000000000..24f4163f80df --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/networker.md @@ -0,0 +1,64 @@ +--- +type: docs +title: "Network Expansion" +linkTitle: "Network Expansion" +weight: 19 +--- + +## Expansion Description + +Peer-to-peer network node builder. + +## Extension ports + +`org.apache.dubbo.remoting.p2p.Networker` + +## Extended configuration + +```xml + + + +``` + +## Known extensions + +* `org.apache.dubbo.remoting.p2p.support.MulticastNetworker` +* `org.apache.dubbo.remoting.p2p.support.FileNetworker` + +## Extended example + +Maven project structure: + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxNetworker.java (implement Networker interface) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.remoting.p2p.Networker (plain text file, content: xxx=com.xxx.XxxNetworker) +``` + +XxxNetworker.java: + +```java +package com.xxx; + +import org.apache.dubbo.remoting.p2p.Networker; + +public class XxxNetworker implements Networker { + public Group lookup(URL url) { + //... + } +} +``` + +META-INF/dubbo/org.apache.dubbo.remoting.p2p.Networker: + +```properties +xxx=com.xxx.XxxNetworker +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/spi/description/page.md b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/page.md new file mode 100644 index 000000000000..c6db0234244a --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/page.md @@ -0,0 +1,68 @@ +--- +type: docs +title: "Peer-to-peer network node builder extension" +linkTitle: "Peer-to-peer network node builder extension" +weight: 19 +--- + +# page extension + +## Expansion Description + +Peer-to-peer network node builder. + +## Extension ports + +`org.apache.dubbo.container.page.PageHandler` + +## Extended configuration + +```xml + + + +``` + +## Known extensions + +* `org.apache.dubbo.container.page.pages.HomePageHandler` +* `org.apache.dubbo.container.page.pages.StatusPageHandler` +* `org.apache.dubbo.container.page.pages.LogPageHandler` +* `org.apache.dubbo.container.page.pages.SystemPageHandler` + +## Extended example + +Maven project structure: + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxPageHandler.java (implement PageHandler interface) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.container.page.PageHandler (plain text file, content: xxx=com.xxx.XxxPageHandler) +``` + +XxxPageHandler.java: + +```java +package com.xxx; + +import org.apache.dubbo.container.page.PageHandler; + +public class XxxPageHandler implements PageHandler { + public Group lookup(URL url) { + //... + } +} +``` + +META-INF/dubbo/org.apache.dubbo.container.page.PageHandler: + +```properties +xxx=com.xxx.XxxPageHandler +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/spi/description/protocol.md b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/protocol.md new file mode 100644 index 000000000000..e37114fe9d87 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/protocol.md @@ -0,0 +1,158 @@ +--- +type: docs +title: "Protocol Extension" +linkTitle: "Protocol Extension" +weight: 1 +--- + +## Expansion Description + +RPC protocol extension, encapsulates remote call details. + +contract: + +* When the user calls the `invoke()` method of the `Invoker` object returned by `refer()`, the protocol needs to execute the `invoke()` of the `Invoker` object passed in from the remote `export()` of the URL accordingly ` method. +* Among them, the `Invoker` returned by `refer()` is implemented by the protocol, and the protocol usually needs to send a remote request in this `Invoker`, and the `Invoker` passed in by `export()` is implemented and passed in by the framework, and the protocol does not need to care. + +Notice: + +* The protocol does not care about the transparent proxy of the business interface, with `Invoker` as the center, and the outer layer converts `Invoker` into a business interface. +* The protocol does not have to be TCP network communication, such as through shared files, IPC inter-process communication, etc. + +## Extension ports + +* `org.apache.dubbo.rpc.Protocol` +* `org.apache.dubbo.rpc.Exporter` +* `org.apache.dubbo.rpc.Invoker` + +```java +public interface Protocol { + /** + * Expose remote services:
+ * 1. When receiving a request, the protocol should record the request source address information: RpcContext.getContext().setRemoteAddress();
+ * 2. export() must be idempotent, that is, exposing the Invoker of the same URL twice is no different from exposing it once.
+ * 3. The Invoker passed in by export() is implemented and passed in by the framework, and the protocol does not need to care.
+ * + * @param type of service + * @param invoker service execution body + * @return exporter The reference of the exposed service, used to cancel the exposure + * @throws RpcException Throws when there is an error in the exposed service, such as the port is already occupied + */ + Exporter export(Invoker invoker) throws RpcException; + + /** + * Quoting remote services:
+ * 1. When the user calls the invoke() method of the Invoker object returned by refer(), the protocol needs to correspondingly execute the invoke() method of the Invoker object passed in from the URL remote export().
+ * 2. The Invoker returned by refer() is implemented by the protocol, and the protocol usually needs to send a remote request in this Invoker.
+ * 3. When check=false is set in the url, an exception cannot be thrown if the connection fails, and internal automatic recovery is required.
+ * + * @param type of service + * @param type service type + * @param url URL address of the remote service + * @return The local proxy for the invoker service + * @throws RpcException thrown when the connection to the service provider fails + */ + Invoker refer(Class type, URL url) throws RpcException; + +} +``` + +## Extended configuration + +```xml + + + + + + +``` + +## Known extensions + +* `org.apache.dubbo.rpc.protocol.injvm.InjvmProtocol` +* `org.apache.dubbo.rpc.protocol.dubbo.DubboProtocol` +* `org.apache.dubbo.rpc.protocol.rmi.RmiProtocol` +* `org.apache.dubbo.rpc.protocol.http.HttpProtocol` +* `org.apache.dubbo.rpc.protocol.http.hessian.HessianProtocol` +* `org.apache.dubbo.rpc.support.MockProtocol` + +## Extended example + +Maven project structure: + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxProtocol.java (implement the Protocol interface) + |-XxxExporter.java (implements the Exporter interface) + |-XxxInvoker.java (implements the Invoker interface) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.rpc.Protocol (plain text file, content: xxx=com.xxx.XxxProtocol) +``` + +XxxProtocol.java: + +```java +package com.xxx; + +import org.apache.dubbo.rpc.Protocol; + +public class XxxProtocol implements Protocol { + public Exporter export(Invoker invoker) throws RpcException { + return new XxxExporter(invoker); + } + public Invoker refer(Class type, URL url) throws RpcException { + return new XxxInvoker(type, url); + } +} +``` + +XxxExporter.java: + +```java +package com.xxx; + +import org.apache.dubbo.rpc.support.AbstractExporter; + +public class XxxExporter extends AbstractExporter { + public XxxExporter(Invoker invoker) throws RemotingException{ + super(invoker); + //... + } + public void unexport() { + super. unexport(); + //... + } +} +``` + +XxxInvoker.java: + +```java +package com.xxx; + +import org.apache.dubbo.rpc.support.AbstractInvoker; + +public class XxxInvoker extends AbstractInvoker { + public XxxInvoker(Class type, URL url) throws RemotingException{ + super(type, url); + } + + @Override + protected Result doInvoke(Invocation invocation) throws Throwable { + //... + } +} +``` + +META-INF/dubbo/org.apache.dubbo.rpc.Protocol: + +```properties +xxx=com.xxx.XxxProtocol +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/spi/description/proxy-factory.md b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/proxy-factory.md new file mode 100644 index 000000000000..7e9bd5d11af5 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/proxy-factory.md @@ -0,0 +1,70 @@ +--- +type: docs +title: "Dynamic Proxy Extension" +linkTitle: "Dynamic proxy extension" +weight: 12 +--- + +## Expansion Description + +Convert the `Invoker` interface into a business interface. + +## Extension ports + +`org.apache.dubbo.rpc.ProxyFactory` + +## Extended configuration + +```xml + + + +``` + +## Known extensions + +* `org.apache.dubbo.rpc.proxy.JdkProxyFactory` +* `org.apache.dubbo.rpc.proxy.JavassistProxyFactory` + +## Extended example + +Maven project structure: + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxProxyFactory.java (implement ProxyFactory interface) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.rpc.ProxyFactory (plain text file, content: xxx=com.xxx.XxxProxyFactory) +``` + +XxxProxyFactory.java: + +```java +package com.xxx; + +import org.apache.dubbo.rpc.ProxyFactory; +import org.apache.dubbo.rpc.Invoker; +import org.apache.dubbo.rpc.RpcException; + + +public class XxxProxyFactory implements ProxyFactory { + public T getProxy(Invoker invoker) throws RpcException { + //... + } + public Invoker getInvoker(T proxy, Class type, URL url) throws RpcException { + //... + } +} +``` + +META-INF/dubbo/org.apache.dubbo.rpc.ProxyFactory: + +```properties +xxx=com.xxx.XxxProxyFactory +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/spi/description/qos-permission.md b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/qos-permission.md new file mode 100644 index 000000000000..90e840c21cd8 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/qos-permission.md @@ -0,0 +1,62 @@ +--- +type: docs +title: "QoS Anonymous Access Verification Extension" +linkTitle: "QoS Anonymous Access Verification Extension" +weight: 27 +--- + +## Expansion Description + +QoS anonymous access authentication extension point. + +## Extension ports + +`org.apache.dubbo.qos.permission.PermissionChecker` + +## Extended configuration + + +Dubbo QoS `dubbo.application.qos-anonymous-access-permission-level` Anonymous access permission verification. + +## Default implementation + +`org.apache.dubbo.qos.permission.DefaultAnonymousAccessPermissionChecker` + +## Extended example + +Maven project structure: + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxPermissionChecker.java (implements PermissionChecker interface) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.qos.permission.PermissionChecker` (plain text file, content: qosPermissionChecker=com.xxx.XxxPermissionChecker) +``` + +XxxPermissionChecker.java: + +```java +package com.xxx.qos.permission; + +import org.apache.dubbo.qos.permission.PermissionChecker; + +public class XxxAnonymousAccessPermissionChecker implements PermissionChecker { + + @Override + public boolean access(CommandContext commandContext, PermissionLevel defaultCmdRequiredPermissionLevel) { + //... + } +} +``` + +META-INF/dubbo/org.apache.dubbo.qos.permission.PermissionChecker: + +```properties +qosPermissionChecker=com.xxx.XxxPermissionChecker +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/spi/description/readiness.md b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/readiness.md new file mode 100644 index 000000000000..f26c42fdf40a --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/readiness.md @@ -0,0 +1,74 @@ +--- +type: docs +title: "Readiness Probe" +linkTitle: "Readiness Probe" +weight: 12 +--- + +## Expansion Description + + +Extend the detection points of application readiness. + + +## Extension ports + + +`org.apache.dubbo.qos.probe.ReadinessProbe` + + +## Extended configuration + + +Dubbo QOS `ready` command auto-discovery + + +## Known extensions + + +- `org.apache.dubbo.qos.probe.impl.BootstrapReadinessProbe` +- `org.apache.dubbo.qos.probe.impl.ProviderReadinessProbe` + + + +## Extended example + + +Maven project structure: + + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxReadinessProbe.java (implements ReadinessProbe interface) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.qos.probe.ReadinessProbe (plain text file, content: xxx=com.xxx.XxxReadinessProbe) +``` + + +XxxReadinessProbe.java: + + +```java +package com.xxx; + +public class XxxReadinessProbe implements ReadinessProbe { + + public boolean check() { + //... + } +} +``` + + +META-INF/dubbo/org.apache.dubbo.qos.probe.ReadinessProbe: + + +``` +xxx=com.xxx.XxxReadinessProbe +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/spi/description/registry.md b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/registry.md new file mode 100644 index 000000000000..d4b26daac4c5 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/registry.md @@ -0,0 +1,210 @@ +--- +type: docs +title: "Registry Extension" +linkTitle: "Registry Extension" +weight: 9 +--- + +## Expansion Description + +Responsible for service registration and discovery. + +## Extension ports + +* `org.apache.dubbo.registry.RegistryFactory` +* `org.apache.dubbo.registry.Registry` + +## Extended configuration + +```xml + + + + + + +``` + +## Extension contract + +RegistryFactory.java: + +```java +public interface RegistryFactory { + /** + * Connect to the registration center. + * + * The connection to the registration center needs to deal with the contract:
+ * 1. When check=false is set, it means that the connection will not be checked, otherwise an exception will be thrown when the connection fails.
+ * 2. Support username:password authority authentication on the URL.
+ * 3. Support backup=10.20.153.10 alternative registration center cluster address.
+ * 4. Support file=registry.cache local disk file cache.
+ * 5. Support timeout=1000 request timeout setting.
+ * 6. Support session=60000 session timeout or expiration setting.
+ * + * @param url Registry address, not allowed to be empty + * @return Registry reference, never return empty + */ + Registry getRegistry(URL url); +} +``` + +RegistryService.java: + +```java +public interface RegistryService { // Registry extends RegistryService + /** + * Registration service. + * + * Registration requires processing contract:
+ * 1. When the URL is set to check=false, no error will be reported after the registration fails, and it will be retried regularly in the background, otherwise an exception will be thrown.
+ * 2. When the dynamic=false parameter is set in the URL, it needs to be stored persistently. Otherwise, when the registrant exits abnormally due to power failure, etc., it needs to be automatically deleted.
+ * 3. When category=overrides is set in the URL, it means classified storage, the default category is providers, and the data can be notified by category.
+ * 4. When the registration center restarts and the network fluctuates, data cannot be lost, including automatic deletion of data when disconnected.
+ * 5. URLs with the same URI but different parameters are allowed to coexist, and cannot be overwritten.
+ * + * @param url Registration information, not allowed to be empty, such as: dubbo://10.20.153.10/com.alibaba.foo.BarService?version=1.0.0&application=kylin + */ + void register(URL url); + + /** + * Unregister service. + * + * Cancellation of registration needs to deal with the contract:
+ * 1. If it is persistent storage data with dynamic=false and registration data cannot be found, throw IllegalStateException, otherwise ignore it.
+ * 2. Cancel registration by full URL matching.
+ * + * @param url Registration information, not allowed to be empty, such as: dubbo://10.20.153.10/com.alibaba.foo.BarService?version=1.0.0&application=kylin + */ + void unregister(URL url); + + /** + * Subscription service. + * + * Subscription requires processing contract:
+ * 1. When the URL is set to check=false, no error will be reported after the subscription fails, and it will be retried periodically in the background.
+ * 2. When category=overrides is set in the URL, only the data of the specified category will be notified. Multiple categories are separated by commas, and wildcards of asterisks are allowed, which means to subscribe to all category data.
+ * 3. It is allowed to use interface, group, version, classifier as conditional query, such as: interface=com.alibaba.foo.BarService&version=1.0.0
+ * 4. And the query condition allows asterisk wildcards, subscribe to all versions of all groups of all interfaces, or: interface=*&group=*&version=*&classifier=*
+ * 5. When the registration center restarts and the network fluctuates, the subscription request needs to be automatically resumed.
+ * 6. URLs with the same URI but different parameters are allowed to coexist, and cannot be overwritten.
+ * 7. The subscription process must be blocked, and return after the first notification.
+ * + * @param url subscription condition, not allowed to be empty, such as: consumer://10.20.153.10/com.alibaba.foo.BarService?version=1.0.0&application=kylin + * @param listener Change event listener, not allowed to be empty + */ + void subscribe(URL url, NotifyListener listener); + + /** + * Unsubscribe service. + * + * Unsubscribing requires processing contract:
+ * 1. If there is no subscription, just ignore it.
+ * 2. Unsubscribe by full URL match.
+ * + * @param url subscription condition, not allowed to be empty, such as: consumer://10.20.153.10/com.alibaba.foo.BarService?version=1.0.0&application=kylin + * @param listener Change event listener, not allowed to be empty + */ + void unsubscribe(URL url, NotifyListener listener); + + /** + * Query the registration list, corresponding to the push mode of subscription, here is the pull mode, and the result is returned only once. + * + * @see org.apache.dubbo.registry.NotifyListener#notify(List) + * @param url query condition, not allowed to be empty, such as: consumer://10.20.153.10/com.alibaba.foo.BarService?version=1.0.0&application=kylin + * @return The registered information list, which may be empty, has the same meaning as the parameter of {@link org.apache.dubbo.registry.NotifyListener#notify(List)}. + */ + List lookup(URL url); + +} +``` + +NotifyListener.java: + +```java +public interface NotifyListener { + /** + * Triggered when a service change notification is received. + * + * Notice to process contract:
+ * 1. The full notification is always based on the service interface and data type, that is, the partial data of the same type of a service will not be notified, and the user does not need to compare the results of the previous notification.
+ * 2. The first notification when subscribing must be a full notification of all types of data for a service.
+ * 3. When changing midway, different types of data are allowed to be notified separately, such as: providers, consumers, routes, overrides, and only one type is allowed to be notified, but the data of this type must be full, not incremental.
+ * 4. If one type of data is empty, it is necessary to notify an empty protocol and identification URL data with category parameter.
+ * 5. The notifier (that is, the registration center implementation) needs to ensure the order of notifications, such as: single-threaded push, queue serialization, and version comparison.
+ * + * @param urls Registered information list, always not empty, the meaning is the same as the return value of {@link org.apache.dubbo.registry.RegistryService#lookup(URL)}. + */ + void notify(List urls); + +} +``` + +## Known extensions + +`org.apache.dubbo.registry.support.dubbo.DubboRegistryFactory` + +## Extended example + +Maven project structure: + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxRegistryFactoryjava (implements RegistryFactory interface) + |-XxxRegistry.java (implement Registry interface) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.registry.RegistryFactory (plain text file, content: xxx=com.xxx.XxxRegistryFactory) +``` + +XxxRegistryFactory.java: + +```java +package com.xxx; + +import org.apache.dubbo.registry.RegistryFactory; +import org.apache.dubbo.registry.Registry; +import org.apache.dubbo.common.URL; + +public class XxxRegistryFactory implements RegistryFactory { + public Registry getRegistry(URL url) { + return new XxxRegistry(url); + } +} +``` + +XxxRegistry.java: + +```java +package com.xxx; + +import org.apache.dubbo.registry.Registry; +import org.apache.dubbo.registry.NotifyListener; +import org.apache.dubbo.common.URL; + +public class XxxRegistry implements Registry { + public void register(URL url) { + //... + } + public void unregister(URL url) { + //... + } + public void subscribe(URL url, NotifyListener listener) { + //... + } + public void unsubscribe(URL url, NotifyListener listener) { + //... + } +} +``` + +META-INF/dubbo/org.apache.dubbo.registry.RegistryFactory: + +```properties +xxx=com.xxx.XxxRegistryFactory +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/spi/description/remoting.md b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/remoting.md new file mode 100644 index 000000000000..1beb8b4a2092 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/remoting.md @@ -0,0 +1,127 @@ +--- +type: docs +title: "Network Transport Extension" +linkTitle: "Network Transport Extension" +weight: 17 +--- + +## Expansion Description + +Realization of remote communication server and client transmission. + +## Extension ports + +* `org.apache.dubbo.remoting.Transporter` +* `org.apache.dubbo.remoting.Server` +* `org.apache.dubbo.remoting.Client` + +## Extended configuration + +```xml + + + + + + +``` + +## Known extensions + +* `org.apache.dubbo.remoting.transport.transporter.netty.NettyTransporter` +* `org.apache.dubbo.remoting.transport.transporter.mina.MinaTransporter` +* `org.apache.dubbo.remoting.transport.transporter.grizzly.GrizzlyTransporter` + +## Extended example + +Maven project structure: + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxTransporter.java (implements the Transporter interface) + |-XxxServer.java (implement Server interface) + |-XxxClient.java (implement Client interface) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.remoting.Transporter (plain text file, content: xxx=com.xxx.XxxTransporter) +``` + +XxxTransporter.java: + +```java +package com.xxx; + +import org.apache.dubbo.remoting.Transporter; + +public class XxxTransporter implements Transporter { + public Server bind(URL url, ChannelHandler handler) throws RemotingException { + return new XxxServer(url, handler); + } + public Client connect(URL url, ChannelHandler handler) throws RemotingException { + return new XxxClient(url, handler); + } +} +``` + +XxxServer.java: + +```java +package com.xxx; + +import org.apache.dubbo.remoting.transport.transporter.AbstractServer; + +public class XxxServer extends AbstractServer { + public XxxServer(URL url, ChannelHandler handler) throws RemotingException{ + super(url, handler); + } + protected void doOpen() throws Throwable { + //... + } + protected void doClose() throws Throwable { + //... + } + public Collection getChannels() { + //... + } + public Channel getChannel(InetSocketAddress remoteAddress) { + //... + } +} +``` + +XxxClient.java: + +```java +package com.xxx; + +import org.apache.dubbo.remoting.transport.transporter.AbstractClient; + +public class XxxClient extends AbstractClient { + public XxxServer(URL url, ChannelHandler handler) throws RemotingException{ + super(url, handler); + } + protected void doOpen() throws Throwable { + //... + } + protected void doClose() throws Throwable { + //... + } + protected void doConnect() throws Throwable { + //... + } + public Channel getChannel() { + //... + } +} +``` + +META-INF/dubbo/org.apache.dubbo.remoting.Transporter: + +```properties +xxx=com.xxx.XxxTransporter +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/spi/description/router.md b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/router.md new file mode 100644 index 000000000000..73a71eb3b1a5 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/router.md @@ -0,0 +1,67 @@ +--- +type: docs +title: "Route Extension" +linkTitle: "Routing Extension" +weight: 6 +--- + +## Expansion Description + +Select one of multiple service providers to call. + +## Extension ports + +* `org.apache.dubbo.rpc.cluster.RouterFactory` +* `org.apache.dubbo.rpc.cluster.Router` + +## Known extensions + +* `org.apache.dubbo.rpc.cluster.router.ScriptRouterFactory` +* `org.apache.dubbo.rpc.cluster.router.FileRouterFactory` +* `org.apache.dubbo.rpc.cluster.router.condition.config.AppRouterFactory` +* `org.apache.dubbo.rpc.cluster.CacheableRouterFactory` +* `org.apache.dubbo.rpc.cluster.router.condition.ConditionRouterFactory` +* `org.apache.dubbo.rpc.cluster.router.mock.MockRouterFactory` +* `org.apache.dubbo.rpc.cluster.router.condition.config.ServiceRouterFactory` +* `org.apache.dubbo.rpc.cluster.router.tag.TagRouterFactory` + +## Extended example + +Maven project structure: + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxRouterFactory.java (implements RouterFactory interface) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.rpc.cluster.RouterFactory (plain text file, content: xxx=com.xxx.XxxRouterFactory) + +``` + +XxxRouterFactory.java: + +```java +package com.xxx; + +import org.apache.dubbo.rpc.cluster.RouterFactory; +import org.apache.dubbo.rpc.Invoker; +import org.apache.dubbo.rpc.Invocation; +import org.apache.dubbo.rpc.RpcException; + +public class XxxRouterFactory implements RouterFactory { + public Router getRouter(URL url) { + //... + } +} +``` + +META-INF/dubbo/org.apache.dubbo.rpc.cluster.RouterFactory: + +```properties +xxx=com.xxx.XxxRouterFactory +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/spi/description/serialize.md b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/serialize.md new file mode 100644 index 000000000000..1b2e955bf04e --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/serialize.md @@ -0,0 +1,77 @@ +--- +type: docs +title: "Serialization Extension" +linkTitle: "Serialization Extension" +weight: 16 +--- + +## Expansion Description + +Convert the object into a byte stream for network transmission, and convert the byte stream into an object for restoring the byte stream data into an object. + +## Extension ports + +* `org.apache.dubbo.common.serialize.Serialization` +* `org.apache.dubbo.common.serialize.ObjectInput` +* `org.apache.dubbo.common.serialize.ObjectOutput` + +## Extended configuration + +```xml + + + + +``` + +## Known extensions + +* `org.apache.dubbo.common.serialize.dubbo.DubboSerialization` +* `org.apache.dubbo.common.serialize.hessian.Hessian2Serialization` +* `org.apache.dubbo.common.serialize.java.JavaSerialization` +* `org.apache.dubbo.common.serialize.java.CompactedJavaSerialization` + +## Extended example + +Maven project structure: + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxSerialization.java (implements the Serialization interface) + |-XxxObjectInput.java (implement ObjectInput interface) + |-XxxObjectOutput.java (implement ObjectOutput interface) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.common.serialize.Serialization (plain text file, content: xxx=com.xxx.XxxSerialization) +``` + +XxxSerialization.java: + +```java +package com.xxx; + +import org.apache.dubbo.common.serialize.Serialization; +import org.apache.dubbo.common.serialize.ObjectInput; +import org.apache.dubbo.common.serialize.ObjectOutput; + + +public class XxxSerialization implements Serialization { + public ObjectOutput serialize(Parameters parameters, OutputStream output) throws IOException { + return new XxxObjectOutput(output); + } + public ObjectInput deserialize(Parameters parameters, InputStream input) throws IOException { + return new XxxObjectInput(input); + } +} +``` + +META-INF/dubbo/org.apache.dubbo.common.serialize.Serialization: + +```properties +xxx=com.xxx.XxxSerialization +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/spi/description/startup.md b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/startup.md new file mode 100644 index 000000000000..8a2dc0b61e33 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/startup.md @@ -0,0 +1,73 @@ +--- +type: docs +title: "Startup Startup Probe" +linkTitle: "Start Probe" +weight: 12 +--- + +## Expansion Description + + +Extend the detection point of application startup. + + +## Extension ports + + +`org.apache.dubbo.qos.probe.StartupProbe` + + +## Extended configuration + + +Dubbo QOS `startup` command auto-discovery + + +## Known extensions + + +- `org.apache.dubbo.qos.probe.impl.BootstrapLivenessProbe` + + + +## Extended example + + +Maven project structure: + + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxStartupProbe.java (implement the StartupProbe interface) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.qos.probe.StartupProbe (plain text file, content: xxx=com.xxx.XxxStartupProbe) +``` + + +XxxStartupProbee.java: + + +```java +package com.xxx; + +public class XxxStartupProbe implements StartupProbe { + + public boolean check() { + //... + } +} +``` + + +META-INF/dubbo/org.apache.dubbo.qos.probe.StartupProbe: + + +``` +xxx=com.xxx.XxxStartupProbe +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/spi/description/status-checker.md b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/status-checker.md new file mode 100644 index 000000000000..7d8c1ab63275 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/status-checker.md @@ -0,0 +1,69 @@ +--- +type: docs +title: "Status Check Extension" +linkTitle: "Status Check Extension" +weight: 21 +--- + +## Expansion Description + +Check the status of various resources that the service relies on. This status check can be used for both telnet's status command and hosting's status page. + +## Extension ports + +`org.apache.dubbo.common.status.StatusChecker` + +## Extended configuration + +```xml + + + +``` + +## Known extensions + +* `org.apache.dubbo.common.status.support.MemoryStatusChecker` +* `org.apache.dubbo.common.status.support.LoadStatusChecker` +* `org.apache.dubbo.rpc.dubbo.status.ServerStatusChecker` +* `org.apache.dubbo.rpc.dubbo.status.ThreadPoolStatusChecker` +* `org.apache.dubbo.registry.directory.RegistryStatusChecker` +* `org.apache.dubbo.rpc.config.spring.status.SpringStatusChecker` +* `org.apache.dubbo.rpc.config.spring.status.DataSourceStatusChecker` + +## Extended example + +Maven project structure: + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxStatusChecker.java (implement StatusChecker interface) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.common.status.StatusChecker (plain text file, content: xxx=com.xxx.XxxStatusChecker) +``` + +XxxStatusChecker.java: + +```java +package com.xxx; + +import org.apache.dubbo.common.status.StatusChecker; + +public class XxxStatusChecker implements StatusChecker { + public Status check() { + //... + } +} +``` + +META-INF/dubbo/org.apache.dubbo.common.status.StatusChecker: + +```properties +xxx=com.xxx.XxxStatusChecker +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/spi/description/telnet-handler.md b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/telnet-handler.md new file mode 100644 index 000000000000..d5750ac2411d --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/telnet-handler.md @@ -0,0 +1,82 @@ +--- +type: docs +title: "Telnet Command Extensions" +linkTitle: "Telnet command extension" +weight: 20 +--- + +## Expansion Description + +All servers support telnet access for manual intervention. + +## Extension ports + +`org.apache.dubbo.remoting.telnet.TelnetHandler` + +## Extended configuration + +```xml + + + +``` + +## Known extensions + +* `org.apache.dubbo.remoting.telnet.support.ClearTelnetHandler` +* `org.apache.dubbo.remoting.telnet.support.ExitTelnetHandler` +* `org.apache.dubbo.remoting.telnet.support.HelpTelnetHandler` +* `org.apache.dubbo.remoting.telnet.support.StatusTelnetHandler` +* `org.apache.dubbo.rpc.dubbo.telnet.ListTelnetHandler` +* `org.apache.dubbo.rpc.dubbo.telnet.ChangeTelnetHandler` +* `org.apache.dubbo.rpc.dubbo.telnet.CurrentTelnetHandler` +* `org.apache.dubbo.rpc.dubbo.telnet.InvokeTelnetHandler` +* `org.apache.dubbo.rpc.dubbo.telnet.TraceTelnetHandler` +* `org.apache.dubbo.rpc.dubbo.telnet.CountTelnetHandler` +* `org.apache.dubbo.rpc.dubbo.telnet.PortTelnetHandler` + +## Extended example + +Maven project structure: + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxTelnetHandler.java (implement TelnetHandler interface) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.remoting.telnet.TelnetHandler (plain text file, content: xxx=com.xxx.XxxTelnetHandler) +``` + +XxxTelnetHandler.java: + +```java +package com.xxx; + +import org.apache.dubbo.remoting.telnet.TelnetHandler; + +@Help(parameter="...", summary="...", detail="...") + +public class XxxTelnetHandler implements TelnetHandler { + public String telnet(Channel channel, String message) throws RemotingException { + //... + } +} +``` + +META-INF/dubbo/org.apache.dubbo.remoting.telnet.TelnetHandler: + +```properties +xxx=com.xxx.XxxTelnetHandler +``` + +## Usage + +```sh +telnet 127.0.0.1 20880 +dubbo> xxx args +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/spi/description/threadpool.md b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/threadpool.md new file mode 100644 index 000000000000..861e0a59414a --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/threadpool.md @@ -0,0 +1,65 @@ +--- +type: docs +title: "Thread Pool Extension" +linkTitle: "Thread pool extension" +weight: 15 +--- + +## Expansion Description + +The service provider's thread pool implements the strategy. When the server receives a request, it needs to create a thread in the thread pool to execute the service provider's business logic. + +## Extension ports + +`org.apache.dubbo.common.threadpool.ThreadPool` + +## Extended configuration + +```xml + + + +``` + +## Known extensions + +* `org.apache.dubbo.common.threadpool.FixedThreadPool` +* `org.apache.dubbo.common.threadpool.CachedThreadPool` + +## Extended example + +Maven project structure: + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxThreadPool.java (implement ThreadPool interface) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.common.threadpool.ThreadPool (plain text file, content: xxx=com.xxx.XxxThreadPool) +``` + +XxxThreadPool.java: + +```java +package com.xxx; + +import org.apache.dubbo.common.threadpool.ThreadPool; +import java.util.concurrent.Executor; + +public class XxxThreadPool implements ThreadPool { + public Executor getExecutor() { + //... + } +} +``` + +META-INF/dubbo/org.apache.dubbo.common.threadpool.ThreadPool: + +```properties +xxx=com.xxx.XxxThreadPool +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/spi/description/validation.md b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/validation.md new file mode 100644 index 000000000000..b3b43f061e87 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/spi/description/validation.md @@ -0,0 +1,80 @@ +--- +type: docs +title: "Authentication Extension" +linkTitle: "Authentication Extension" +weight: 25 +--- + +## Expansion Description + +Parameter validation extension point. + +## Extension ports + +`org.apache.dubbo.validation.Validation` + +## Extended configuration + +```xml + + + +``` + +## Known extensions + +`org.apache.dubbo.validation.support.jvalidation.JValidation` + +## Extended example + +Maven project structure: + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxValidation.java (implement Validation interface) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.validation.Validation (plain text file, content: xxx=com.xxx.XxxValidation) +``` + +XxxValidation.java: + +```java +package com.xxx; + +import org.apache.dubbo.validation.Validation; + +public class XxxValidation implements Validation { + public Object getValidator(URL url) { + //... + } +} +``` + +XxxValidator.java: + +```java +package com.xxx; + +import org.apache.dubbo.validation.Validator; + +public class XxxValidator implements Validator { + public XxxValidator(URL url) { + //... + } + public void validate(Invocation invocation) throws Exception { + //... + } +} +``` + +META-INF/dubbo/org.apache.dubbo.validation.Validation: + +```properties +xxx=com.xxx.XxxValidation +``` \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/reference-manual/spi/overview.md b/content/en/docs3-v2/java-sdk/reference-manual/spi/overview.md new file mode 100644 index 000000000000..cd063b93ab9f --- /dev/null +++ b/content/en/docs3-v2/java-sdk/reference-manual/spi/overview.md @@ -0,0 +1,101 @@ +--- +type: docs +title: "Dubbo SPI Overview" +linkTitle: "Dubbo SPI overview" +weight: 1 +description: "Dubbo provides very flexible scalability through the SPI mechanism" +--- + +## Extended Design Ideas + +Scalability is what any system pursues, and it is equally applicable to Dubbo. + +### What is scalability + +Scalability is a design concept that represents our vision for the future. We hope that based on the existing architecture or design, when some aspects change in the future, we can adapt to this with minimal changes. kind of change. + +### Advantages of Scalability + +The advantage of scalability is mainly manifested in the decoupling between modules, which conforms to the principle of opening and closing, which is open to expansion and closed to modification. When a new function is added to the system, there is no need to modify the structure and code of the existing system, just add an extension. + +### Extended implementation + +Generally speaking, the system will use Factory, IoC, OSGI, etc. to manage the extension (plug-in) life cycle. Considering the applicability of Dubbo, I don't want to strongly rely on IoC containers such as Spring. +And building a small IoC container by myself feels a bit over-designed, so choose the simplest Factory way to manage extensions (plug-ins). In Dubbo, all internal and third-party implementations are equal. + +### Scalability in Dubbo + +* Treat third-party implementations equally. In Dubbo, all internal implementations and third-party implementations are equal, and users can replace the native implementations provided by Dubbo based on their own business needs. +* Each extension point only encapsulates one change factor to maximize reuse. The implementers of each extension point often only care about one thing. If users need to expand, they only need to expand the extension points they care about, which greatly reduces the workload of users. + +## Features of Dubbo extension + +The extension capability in Dubbo is enhanced from the JDK standard SPI extension point discovery mechanism, which improves the following problems of the JDK standard SPI: + +* The JDK standard SPI will instantiate all the implementations of the extension point at one time. If there is an extension implementation, it will be time-consuming to initialize, but if it is not used, it will be loaded, which will be a waste of resources. +* If the extension point fails to load, even the name of the extension point cannot be obtained. For example: JDK standard ScriptEngine, get the name of the script type through getName(), but if RubyScriptEngine fails to load the RubyScriptEngine class because the jruby. When the user executes the ruby script, it will report that ruby is not supported, not the real reason for the failure. + +Based on the expansion capabilities provided by Dubbo, users can easily expand other protocols, filters, routes, etc. based on their own needs. The following introduces the characteristics of Dubbo's extension capabilities. + +* Load on demand. Dubbo's extension capability does not instantiate all implementations at once, but instantiates with extended classes to reduce resource waste. +* Increase the IOC capability of the extended class. Dubbo's extension ability is not just to discover the extension service implementation class, but to go further on this basis. If the attributes of the extension class depend on other objects, Dubbo will automatically complete the injection function of the dependent object. +* Increase the AOP capability of extended classes. Dubbo's extension capability will automatically discover the wrapper class of the extension class, complete the construction of the wrapper class, and enhance the function of the extension class. +* Possess the ability to dynamically select the extension implementation. The Dubbo extension will dynamically select the corresponding extension class at runtime based on parameters, which improves Dubbo's scalability. +* The extension implementation can be sorted. The execution order of the extension implementation can be specified based on user requirements. +* Provides the Adaptive capability of the extension point. This capability enables some extension classes to take effect on the consumer side, and some extension classes to take effect on the provider side. + +From the design goal of Dubbo extension, it can be seen that some features implemented by Dubbo, such as dynamic selection of extension implementation, IOC, AOP, etc., can provide users with very flexible expansion capabilities. + +## Dubbo extension loading process + +The whole process of Dubbo loading extension is as follows: + +![//imgs/v3/concepts/extension-load.png](/imgs/v3/concepts/extension-load.png) + +There are 4 main steps: +* Read and parse configuration files +* Cache all extension implementations +* Based on the extension name executed by the user, instantiate the corresponding extension implementation +* Perform IOC injection of extended instance attributes and instantiate extended wrapper classes to realize AOP features + +## How to use Dubbo's extension capability to expand + +The following takes the extension protocol as an example to illustrate how to use the extension capabilities provided by Dubbo to extend the Triple protocol. + +(1) Place a text file in the protocol implementation jar package: META-INF/dubbo/org.apache.dubbo.remoting.api.WireProtocol +```text +tri=org.apache.dubbo.rpc.protocol.tri.TripleHttp2Protocol +``` + +(2) Implementation class content +```java +@Activate +public class TripleHttp2Protocol extends Http2WireProtocol { + //... +} +``` + +Instructions: Http2WireProtocol implements the WireProtocol interface + +(3) In the Dubbo configuration module, each extension point has a corresponding configuration attribute or label, and the configuration specifies which extension to use. for example: +```text + +``` + +As can be seen from the above expansion steps, the user basically completes the expansion under the black box. + +## Dubbo extended application + +Dubbo's expansion capability is very flexible, and it is ubiquitous in the realization of its own functions. + +![//imgs/v3/concepts/extension-use.png](/imgs/v3/concepts/extension-use.png) + +Dubbo's extensibility makes it easy to divide the Dubbo project into sub-modules one by one to realize the hot-swappable feature. Users can completely replace Dubbo's native implementation based on their own needs to meet their own business needs. + +## scenes to be used + +* If you need to customize the load balancing strategy, you can use Dubbo's scalability. +* If you need to implement a custom registry, you can use Dubbo's extension capabilities. +* If you need to implement custom filters, you can use Dubbo's extension capabilities. + +Dubbo extensions treat internal implementations and third-party implementations equally. For more usage scenarios, see [SPI extension implementation](../description/) \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/upgrades-and-compatibility/2.x-to-3.x-compatibility-guide.md b/content/en/docs3-v2/java-sdk/upgrades-and-compatibility/2.x-to-3.x-compatibility-guide.md new file mode 100644 index 000000000000..866fba7f5270 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/upgrades-and-compatibility/2.x-to-3.x-compatibility-guide.md @@ -0,0 +1,96 @@ +--- +type: docs +title: "2.x to 3.x Operation Guide" +linkTitle: "2.x to 3.x Operation Guide" +weight: 1 +description: "Quickly understand the upgrade steps and compatibility of Dubbo 3" +--- +## Benefits of upgrading to Dubbo 3.X +Dubbo3 still maintains the classic architecture of 2.x. Its main responsibility is to solve the communication between microservice processes, and to better manage and control microservice clusters through rich service governance (such as address discovery, traffic management, etc.); The upgrade of the framework is comprehensive, reflected in almost every aspect of the core Dubbo features, through the upgrade to achieve a comprehensive improvement in stability, performance, scalability, and ease of use. + +![architecture-1](/imgs/v3/concepts/architecture-1.png) + +- **Universal communication protocol. ** The new RPC protocol should abandon the private protocol stack, use the more general HTTP/2 protocol as the transport layer carrier, and use the standardized features of the HTTP protocol to solve the problems of traffic versatility and penetration, so that the protocol can better respond Scenarios such as front-end and back-end docking, gateway proxy, etc.; supports the Stream communication mode, which meets the demands of different business communication models and brings greater throughput to the cluster. +- **For millions of cluster instances, the cluster is highly scalable. ** With the promotion of micro-service practices, the scale of micro-service cluster instances is also constantly expanding, which benefits from the characteristics of light-weight micro-services and easy horizontal expansion, but also brings a burden to the entire cluster capacity, especially It is some centralized service governance components; Dubbo3 needs to solve various resource bottlenecks caused by the expansion of instance scale, and realize truly unlimited horizontal expansion. +- **Comprehensively embrace cloud native. ** + + +## Dubbo 3.0 new features +The new features provided by Dubbo 3.0 include: + +* ** New address discovery model (application-level service discovery). ** + * See [Application-Level Service Discovery Migration Samples](/en/docs3-v2/java-sdk/upgrades-and-compatibility/service-discovery/service-discovery-samples/). + * See [Migration steps for application-level service discovery](/en/docs3-v2/java-sdk/upgrades-and-compatibility/service-discovery/migration-service-discovery/) + * See [Description of application-level service discovery address migration rules](/en/docs3-v2/java-sdk/upgrades-and-compatibility/service-discovery/service-discovery-rule/) +* **The next generation of the HTTP/2-based Triple protocol. ** + * See [Triple Protocol Migration Steps](/en/docs3-v2/java-sdk/upgrades-and-compatibility/migration-triple/) + * See [Triple protocol usage](/en/docs3-v2/java-sdk/reference-manual/protocol/triple/guide/) + * See [Triple Protocol Design and Implementation](/en/docs3-v2/java-sdk/reference-manual/protocol/triple/overview/). +* **Unified routing rules. ** + * See [Design and Implementation of Unified Routing Rules](/en/docs3-v2/java-sdk/advanced-features-and-usage/traffic/mesh-style/) + + +## Compatibility check before upgrade +In the process of cross-version upgrade, the existing risks are from big to small: directly modify Dubbo source code -> expand based on Dubbo SPI extension points -> use methods based on API or Spring. + +### 1. Directly modify Dubbo source code +For those who need to directly modify this part of Dubbo source code, the modifying party must judge whether it works normally in the higher version. For this non-standard behavior, Dubbo cannot guarantee its previous compatibility. In addition, the modification of Dubbo at runtime through javagent or asm is also within this scope. Most of these modifications can be detected by the scanning tools provided below. + +### 2. SPI extension +#### Incompatibilities +For SPI extensions, except that the two mechanisms of application-level service direction and EventDispatcher have been destructively modified in 3.x, most of the extensions provided in 2.7.x are also provided in 3.x. There are two areas to focus on in this section: + +- Event bus: Due to the complexity of event management, the support of EventDispatcher and EventListener in Dubbo 3.x has been removed. If there is a use of the corresponding extension mechanism, please consider refactoring to an extension corresponding to the Dubbo function. +- Application-level service discovery: The overall mechanism of application-level service discovery in Dubbo 2.7 has been completely refactored in Dubbo 3.x, and the performance and stability of functions have been greatly improved. Therefore, we recommend that you do not use the application-level service discovery mechanism in Dubbo 2.7. If there is a corresponding extension, you can re-verify the implementation based on the new code after upgrading to Dubbo 3.x (most APIs for application-level service discovery are forward Compatible). + +#### Optimization items (optional) +In addition, Dubbo 3.x has optimized the working mechanism of some extension points, which can greatly improve the performance of the application. + +- 1) Interceptor mechanism + +Dubbo can intercept requests based on Filter interceptors. In Dubbo 2.7, it is supported to intercept the request after the routing address is selected. In Dubbo 3.x, a new ClusterFilter mechanism is abstracted, which can greatly reduce the memory usage, and has great benefits for ultra-large-scale clusters. +If you have some interceptors on the consumer side that are implemented based on the Filter mechanism, and if there is no logic that is strongly bound to the remote IP address, we recommend that you add the corresponding `org.apache.dubbo.rpc.Filter` SPI extension point Migrated to the new SPI extension point `org.apache.dubbo.rpc.cluster.filter.ClusterFilter`. The method definitions of the two interfaces are exactly the same. + +- 2) Router -> StateRouter + +Dubbo provides Router, the ability to dynamically select and route, and most of the service governance capabilities are also implemented based on this Router extension point. In Dubbo 3.x, Dubbo abstracts a new StateRouter mechanism based on Router, which can greatly optimize address selection performance and memory usage. We will publish more about StateRouter in subsequent documents. + +### 3. API / Spring usage +For the use based on API or Spring, Dubbo 3.x and 2.7.x are used in the same way. In Dubbo 3.x, some invalid configurations are strongly checked, and this part of the exception will directly report an error during the startup process. , please follow the prompts to modify. + +## Upgrade process +### 1. Dependency upgrade +If you use Nacos as the registration center, due to the support of Nacos features, you need to upgrade Nacos Server to 2.x before upgrading to Dubbo 3.x (refer to the document [https://nacos.io/zh-cn/docs/v2 /upgrading/2.0.0-upgrading.html](https://nacos.io/zh-cn/docs/v2/upgrading/2.0.0-upgrading.html)), and then upgrade the Nacos Client of the application . No processing is required if using a Zookeeper registry. +If you are using Spring Cloud Alibaba Dubbo for access, please upgrade to xxx due to changes in some internal APIs of Dubbo. + +Please upgrade to the latest version 3.1.3 for Dubbo dependencies. Dubbo and the corresponding springboot starter GAV are as follows. +```xml + + org.apache.dubbo + dubbo + 3.1.3 + + + + org.apache.dubbo + dubbo-spring-boot-starter + 3.1.3 + +``` +### 2. Gray scale upgrade +The Dubbo 3 upgrade has no special restrictions on the release process, and it can be released according to normal business. +Since Dubbo is undergoing changes and upgrades across major versions, please release as many batches as possible during the release, and at the same time increase the time interval between the first batch and the second batch of releases, and make sufficient observations. +During the publishing process, we recommend that you first upgrade the downstream of the application (that is, the service provider), and then proceed with subsequent publishing after verifying that the service is processed normally. + +### 3. Upgrade observation indicators +During the release process, there are the following latitude indicators to judge whether there is a problem with the upgrade. + +- CPU, memory usage of the machine +- Interface request success rate +- Interface Request RT +- Log error message +- Does the custom extension behave as expected + +## Precautions +### 1. Application-level service discovery +Due to design problems in the application-level service discovery model of Dubbo 2.7, a large number of format changes have been made in Dubbo 3.x, so the application-level service discovery of 2.7.x and 3.x may not be able to subscribe to each other. sex. Although Dubbo will eliminate unrecognized instances, from the perspective of stability, if you enable the application-level service discovery feature in 2.7.x (not registered by default in 2.7.x), we recommend first Turn it off, and turn it on again after upgrading to 3.x. \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/upgrades-and-compatibility/3.0-to-3.1-compatibility-guide.md b/content/en/docs3-v2/java-sdk/upgrades-and-compatibility/3.0-to-3.1-compatibility-guide.md new file mode 100644 index 000000000000..2a19692de11c --- /dev/null +++ b/content/en/docs3-v2/java-sdk/upgrades-and-compatibility/3.0-to-3.1-compatibility-guide.md @@ -0,0 +1,22 @@ +--- +type: docs +title: "3.0 to 3.1 Operation Guide" +linkTitle: "3.0 to 3.1 Operation Guide" +weight: 1000 +description: "Quickly understand the upgrade steps and compatibility of Dubbo 3.1" +--- + +## Function modification points + +### 1. Nacos Group alignment (application-level service discovery) + +In Dubbo 2.7.x, the group value configured on the Nacos Registry URL is aligned with the group group in the Nacos Registry. (group can be regarded as a soft isolation similar to namespace) + +In Dubbo 3.0.x, the group configured on the Nacos Registry URL is not used by default, and all use DEFAULT_GROUP. (group no longer provides isolation) + +In Dubbo 3.1.x, the group value configured on the Nacos Registry URL will realign the group grouping in the Nacos Registry. + +Precautions: + +1. Please check whether the group attribute has been configured on the URL of the registration center. If so, check whether the group of the server and the consumer are consistent. If not, please modify it to be consistent. +2. If you do not want the group to be realigned to the group grouping in the Nacos registry, you can configure the `dubbo.nacos-service-discovery.use-default-group=false` global property value to ignore this function \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/upgrades-and-compatibility/3.1-to-3.2-compatibility-guide.md b/content/en/docs3-v2/java-sdk/upgrades-and-compatibility/3.1-to-3.2-compatibility-guide.md new file mode 100644 index 000000000000..bf00d3ba39aa --- /dev/null +++ b/content/en/docs3-v2/java-sdk/upgrades-and-compatibility/3.1-to-3.2-compatibility-guide.md @@ -0,0 +1,85 @@ +--- +type: docs +title: "3.1 Upgrade to 3.2 Operation Guide" +linkTitle: "3.1 Upgrade to 3.2 Operation Guide" +weight: 1001 +description: "Quickly understand the upgrade steps and compatibility of Dubbo 3.2" +--- + +# Function modification points + +## 1. Transitive dependency changes + +* Dubbo version 3.2.0 no longer shade `hessian-lite` code in `dubbo-all` by default, but use transitive dependency transfer instead. If you don't need to use `hessian-lite` in your application, you can remove `hessian-lite` from dependencies. +* From version 3.2.0 of Dubbo, `gson`, `fastjson` dependencies are no longer passed in `dubbo-all`, if you need to use `gson`, `fastjson` in your application, please manually install `gson`, `fastjson` ` Dependencies are added to the application. +* Dubbo 3.2.0 version passes `fastjson2` dependency in `dubbo-all`. + +## 2. Default serialization switch + +* Starting from version 3.2.0 of Dubbo, the default serialization method is switched from `hessian2` to `fastjson2`. For applications upgraded to 3.2.0, Dubbo will automatically try to use `fastjson2` for serialization. + +#### FAQ + +#### Q1: Will it affect the intercommunication with lower versions of Dubbo? + +Won't. Interoperability with lower versions still uses `hessian-lite`. For the principle, please refer to [Serialization Protocol Upgrade Guide](/en/docs3-v2/java-sdk/upgrades-and-compatibility/serialization-upgrade/). + +#### Q2: Why switch the default serialization method? + +`fastjson2` is a high-performance serialization framework with better performance than `hessian2`, natively supports JDK17, Native, etc., and is fully forward compatible with all functions of `hessian2`. +Since `hessian-lite` will become more and more difficult to maintain in the future, we decided to switch the default serialization method from `hessian2` to `fastjson2`. + +#### Q3: What is the relationship with native JSON? + +Dubbo uses the JSONB format of `fastjson2` instead of the native JSON format. The JSONB format corresponds to the JSON format, can fully represent JSON, and is a binary format. +For the specific protocol format, please refer to: [JSONB format](https://github.com/alibaba/fastjson2/wiki/jsonb_format_cn) + +#### Q4: What if I don't want to use `fastjson2`? + +If you don't want to use `fastjson2`, you can configure `prefer-serialization` to override the default configuration for `hessian2`. (such as `dubbo.provider.prefer-serialization=fastjson2,hessian2`) If there is no special requirement, we do not recommend continuing to use `hessian2`. + +## 3. Default internal serialization tool switch + +* Starting from version 3.2.0 of Dubbo, the **internal** serialization tool is switched from `fastjson` to `fastjson2` by default. + +#### FAQ + +#### Q1: Will it affect the RPC request traffic? + +Won't. The internal serialization tool is used when Dubbo internally parses parameters, not the RPC transmission serialization protocol. + +#### Q2: Why switch the default internal serialization tool? + +From version 3.2.0 of Dubbo, the default transitive dependencies no longer pass `fastjson` and `gson`. For compatibility reasons, the default internal serialization tool is switched to `fastjson2`. + +#### Q3: What if there is no `fastjson2` in my environment? + +Dubbo supports automatic switching of multiple serialization frameworks. If there is no `fastjson2` in your environment, Dubbo will automatically try to switch to `fastsjon` or `gson`. + +#### Q4: I want to specify the internal serialization tool of Dubbo, what should I do? + +You can configure `dubbo.json-framework.prefer` parameters, such as `-Ddubbo.json-framework.prefer=gson`. + +## 4. Triple protocol supports passing custom exceptions + +* Starting from Dubbo version 3.2.0, the Triple protocol supports returning custom exceptions instead of only returning `RpcException`. If the service interface throws an exception, after Dubbo 3.2.0, the custom exception object will be returned by default according to the Dubbo protocol. + +## 5. Push short protection is disabled by default + +* Dubbo version 3.2.0 starts to disable push protection by default, even if the registration center pushes empty addresses, Dubbo will not keep the last batch of provider information. + If you need to enable empty protection, you can configure `dubbo.application.enable-empty-protection` to `true`. + +#### FAQ + +#### Q1: How does disabling push short protection affect me? + +In most scenarios it has no effect. +The purpose of push empty protection is that when the registration center fails and actively pushes empty addresses, Dubbo keeps the last batch of provider information to ensure service availability. +However, when most registration centers fail, the registration center will not push empty addresses, only in some special cases. +However, if the push short protection is turned on, it will have a greater impact on Dubbo's Fallback logic, heartbeat logic, etc., and bring troubles to the development and use of Dubbo. + +#### Q2: I want to enable short push protection, what should I do? + +If you need to enable push empty protection for high availability in production, you can configure `dubbo.application.enable-empty-protection` to `true`. +At present, it is known that turning on the push-out protection will cause the server-side application to upgrade from `2.6. In this scenario, the service call will fail. +In addition, after the push-to-empty protection is turned on, when the server address is really empty, there will be more heartbeat exceptions and log exceptions. \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/upgrades-and-compatibility/_index.md b/content/en/docs3-v2/java-sdk/upgrades-and-compatibility/_index.md new file mode 100755 index 000000000000..97dd65a7ac0b --- /dev/null +++ b/content/en/docs3-v2/java-sdk/upgrades-and-compatibility/_index.md @@ -0,0 +1,8 @@ + +--- +type: docs +title: "Upgrade Compatibility" +linkTitle: "Upgrade Compatibility" +weight: 6 +--- + diff --git a/content/en/docs3-v2/java-sdk/upgrades-and-compatibility/migration-triple.md b/content/en/docs3-v2/java-sdk/upgrades-and-compatibility/migration-triple.md new file mode 100644 index 000000000000..fad6ac9aa66b --- /dev/null +++ b/content/en/docs3-v2/java-sdk/upgrades-and-compatibility/migration-triple.md @@ -0,0 +1,344 @@ +--- +type: docs +title: "Guide to Migrating Dubbo Protocol to Triple Protocol" +linkTitle: "Guide to migrating Dubbo protocol to Triple protocol" +weight: 2 +description: "Triple Protocol Migration Guide" +--- + +## Triple Introduction + +For the format and principle of the `Triple` protocol, please refer to [RPC Communication Protocol](/zh/docs/concepts/rpc-protocol/) + +According to the goals of Triple design, the `Triple` protocol has the following advantages: + +- Capable of cross-language interaction. Both the traditional multi-language and multi-SDK mode and the Mesh cross-language mode require a more general and scalable data transmission protocol. +- Provide a more complete request model. In addition to supporting the traditional Request/Response model (Unary one-way communication), it also supports Stream (streaming communication) and Bidirectional (two-way communication). +- Easy to expand, high penetration, including but not limited to Tracing / Monitoring and other support, should also be recognized by devices at all levels, gateway facilities, etc. can identify data packets, friendly to Service Mesh deployment, and reduce the difficulty of understanding for users. +- Fully compatible with grpc, the client/server can communicate with the native grpc client. +- Components in the existing grpc ecosystem can be reused to meet cross-language, cross-environment, and cross-platform intercommunication requirements in cloud-native scenarios. + +For Dubbo users currently using other protocols, the framework provides migration capabilities compatible with existing serialization methods. Without affecting existing online businesses, the cost of migrating protocols is almost zero. + +Dubbo users who need to add new connection to Grpc service can directly use the Triple protocol to achieve the connection, and do not need to introduce the grpc client separately to complete it. Not only can the existing Dubbo ease of use be retained, but also the complexity of the program and the development and maintenance can be reduced. Cost, it can be connected to the existing ecology without additional adaptation and development. + +For Dubbo users who need gateway access, the Triple protocol provides a more native way to make gateway development or use open source grpc gateway components easier. The gateway can choose not to parse the payload, which greatly improves the performance. When using the Dubbo protocol, the language-related serialization method is a big pain point for the gateway, and the traditional HTTP-to-Dubbo method is almost powerless for cross-language serialization. At the same time, since Triple's protocol metadata is stored in the request header, the gateway can easily implement customized requirements, such as routing and current limiting. + + +## Dubbo2 protocol migration process + +Dubbo2 users use dubbo protocol + custom serialization, such as hessian2 to complete remote calls. + +By default, Grpc only supports Protobuf serialization, and it cannot support multi-parameter and method overloading in the Java language. + +At the beginning of Dubbo3, one goal was to be perfectly compatible with Dubbo2. Therefore, in order to ensure the smooth upgrade of Dubbo2, the Dubbo framework has done a lot of work to ensure that the upgrade is seamless. Currently, the default serialization is consistent with Dubbo2 as `hessian2`. + +Therefore, if you decide to upgrade to the `Triple` protocol of Dubbo3, you only need to modify the protocol name in the configuration to `tri` (note: not triple). + +Next we use a [project] (https://github.com/apache/dubbo-samples/tree/master/3-extensions/protocol/dubbo-samples-triple/src/main/java/ org/apache/dubbo/sample/tri/migration) as an example, how to upgrade safely step by step. + +1. Only use the `dubbo` protocol to start `provider` and `consumer`, and complete the call. +2. Use `dubbo` and `tri` protocols to start `provider`, use `dubbo` protocol to start `consumer`, and complete the call. +3. Start `provider` and `consumer` using only `tri` protocol, and complete the call. + +### Define the service + +1. Define the interface +```java +public interface IWrapperGreeter { + + //... + + /** + * This is a normal interface, not serialized using pb + */ + String sayHello(String request); + +} +``` + +2. The implementation class is as follows +```java +public class IGreeter2Impl implements IWrapperGreeter { + + @Override + public String sayHello(String request) { + return "hello," + request; + } +} +``` + +### Only use dubbo protocol + +To ensure compatibility, we first upgrade some providers to the `dubbo3` version and use the `dubbo` protocol. + +Start a [`Provider`] using the `dubbo` protocol (https://github.com/apache/dubbo-samples/blob/master/3-extensions/protocol/dubbo-samples-triple/src/main/java/org /apache/dubbo/sample/tri/migration/ApiMigrationDubboProvider.java) and [`Consumer`](https://github.com/apache/dubbo-samples/blob/master/3-extensions/protocol/dubbo-samples-triple/src/main/java/org/apache/dubbo/sample/tri/migration/ApiMigrationDubboConsumer.java), complete the call, the output is as follows: +![result](/imgs/v3/migration/tri/dubbo3-tri-migration-dubbo-dubbo-result.png) + +### Use dubbo and triple protocol at the same time + +For the upgrade of online services, it is impossible to complete the provider and consumer upgrades at the same time. It needs to be operated step by step to ensure business stability. +In the second step, the provider provides a dual-protocol way to support dubbo + tri clients at the same time. + +The structure is shown in the figure: +![trust](/imgs/v3/migration/tri/migrate-dubbo-tri-strust.png) + +> According to the recommended upgrade steps, the provider already supports the tri protocol, so the consumer of dubbo3 can directly use the tri protocol + +Start [`Provider`] using `dubbo` protocol and `triple` protocol (https://github.com/apache/dubbo-samples/blob/master/3-extensions/protocol/dubbo-samples-triple/src/main /java/org/apache/dubbo/sample/tri/migration/ApiMigrationBothProvider.java) and [`Consumer`](https://github.com/apache/dubbo-samples/blob/master/3-extensions/protocol/ dubbo-samples-triple/src/main/java/org/apache/dubbo/sample/tri/migration/ApiMigrationBothConsumer.java), complete the call, the output is as follows: + +![result](/imgs/v3/migration/tri/dubbo3-tri-migration-both-dubbo-tri-result.png) + + +### Only use triple protocol + +When all consuemr are upgraded to a version that supports the `Triple` protocol, the provider can be switched to only use the `Triple` protocol to start + +The structure is shown in the figure: +![trust](/imgs/v3/migration/tri/migrate-only-tri-strust.png) + +[Provider](https://github.com/apache/dubbo-samples/blob/master/3-extensions/protocol/dubbo-samples-triple/src/main/java/org/apache/dubbo/sample/tri/ migration/ApiMigrationTriProvider.java) +and [Consumer](https://github.com/apache/dubbo-samples/blob/master/3-extensions/protocol/dubbo-samples-triple/src/main/java/org/apache/dubbo/sample/tri /migration/ApiMigrationTriConsumer.java) to complete the call, the output is as follows: + +![result](/imgs/v3/migration/tri/dubbo3-tri-migration-tri-tri-result.png) + + +### Implementation principle + +Through the upgrade process described above, we can easily complete the upgrade by modifying the protocol type. How does the framework help us do this? + +Through the introduction of the `Triple` protocol, we know that the data type of `Triple` in Dubbo3 is a `protobuf` object, so why non-`protobuf` java objects can also be transmitted normally. + +Here Dubbo3 uses an ingenious design, first judge whether the parameter type is a `protobuf` object, if not. Use a `protobuf` object to wrap `request` and `response`, which shields the complexity brought by other serialization. Declare the serialization type inside the `wrapper` object to support serialization extensions. + +The IDL of `protobuf` of wrapper is as follows: +```proto +syntax = "proto3"; + +package org.apache.dubbo.triple; + +message TripleRequestWrapper { + //hessian4 + // json + string serializeType = 1; + repeated bytes args = 2; + repeated string argTypes = 3; +} + +message TripleResponseWrapper { + string serializeType = 1; + bytes data = 2; + string type = 3; +} +``` + +For requests, use `TripleRequestWrapper` for wrapping, and for responses, use `TripleResponseWrapper` for wrapping. + +> For request parameters, you can see that args is modified by `repeated`, this is because multiple parameters of the java method need to be supported. Of course, serialization can only be one. The implementation of serialization follows the spi implemented by Dubbo2 + + +## Multilingual users (using Protobuf) +> It is recommended that all new services use this method + +For Dubbo3 and Triple, the main recommendation is to use `protobuf` serialization, and use `IDL` defined by `proto` to generate related interface definitions. Using `IDL` as a common interface convention in multiple languages, coupled with the natural interoperability of `Triple` and `Grpc`, can easily achieve cross-language interaction, such as Go language. + + +Use the `dubbo-compiler` plug-in to compile the prepared `.proto` file and write the implementation class to complete the method call: + +![result](/imgs/v3/migration/tri/dubbo3-tri-migration-tri-tri-result.png) + +From the upgrade example above, we can know that the `Triple` protocol uses `protbuf` objects to be serialized for transmission, so there is no other logic for methods that are themselves `protobuf` objects. + +The interface after compiling with the `protobuf` plugin is as follows: +```java +public interface PbGreeter { + + static final String JAVA_SERVICE_NAME = "org.apache.dubbo.sample.tri.PbGreeter"; + static final String SERVICE_NAME = "org.apache.dubbo.sample.tri.PbGreeter"; + + static final boolean inited = PbGreeterDubbo.init(); + + org.apache.dubbo.sample.tri.GreeterReply greet(org.apache.dubbo.sample.tri.GreeterRequest request); + + default CompletableFuture greetAsync(org.apache.dubbo.sample.tri.GreeterRequest request){ + return CompletableFuture. supplyAsync(() -> greet(request)); + } + + void greetServerStream(org.apache.dubbo.sample.tri.GreeterRequest request, org.apache.dubbo.common.stream.StreamObserver responseObserver); + + org.apache.dubbo.common.stream.StreamObserver greetStream(org.apache.dubbo.common.stream.StreamObserver responseObserver); +} +``` + +## Open the new feature of Triple - Stream (stream) +Stream is a new call type provided by Dubbo3. It is recommended to use stream in the following scenarios: + +- The interface needs to send a large amount of data. These data cannot be placed in an RPC request or response, and need to be sent in batches. However, if the application layer cannot solve the order and performance problems in the traditional multiple RPC method, if the order needs to be guaranteed , it can only be sent serially +- In streaming scenarios, data needs to be processed in the order they are sent, and the data itself has no definite boundary +- In push scenarios, multiple messages are sent and processed in the context of the same call + +Stream is divided into the following three types: +- SERVER_STREAM (server stream) + ![SERVER_STREAM](/imgs/v3/migration/tri/migrate-server-stream.png) +- CLIENT_STREAM (client stream) + ![CLIENT_STREAM](/imgs/v3/migration/tri/migrate-client-stream.png) +- BIDIRECTIONAL_STREAM (bidirectional stream) + ![BIDIRECTIONAL_STREAM](/imgs/v3/migration/tri/migrate-bi-stream.png) + +> Due to the limitations of the `java` language, the implementation of BIDIRECTIONAL_STREAM and CLIENT_STREAM is the same. + +In Dubbo3, the stream interface is declared and used as `SteamObserver`, and users can use and implement this interface to send and handle stream data, exceptions, and end. + +> For Dubbo2 users, they may be unfamiliar with StreamObserver, which is a stream type defined by Dubbo3. There is no Stream type in Dubbo2, so it has no impact on migration scenarios. + +Stream Semantic Guarantees +- Provide message boundaries, which can easily process messages separately +- Strictly ordered, the order of the sender is consistent with the order of the receiver +- Full duplex, no need to wait for sending +- Support cancellation and timeout + +### Non-PB serialized stream +1. api +```java +public interface IWrapperGreeter { + + StreamObserver sayHelloStream(StreamObserver response); + + void sayHelloServerStream(String request, StreamObserver response); +} +``` + +> The method input parameters and return values of the Stream method are strictly agreed. In order to prevent problems caused by writing errors, the Dubbo3 framework side checks the parameters, and throws an exception if there is an error. +> For `BIDIRECTIONAL_STREAM`, it should be noted that `StreamObserver` in the parameter is the response stream, and `StreamObserver` in the return parameter is the request stream. + +2. Implementation class +```java +public class WrapGreeterImpl implements WrapGreeter { + + //... + + @Override + public StreamObserver sayHelloStream(StreamObserver response) { + return new StreamObserver() { + @Override + public void onNext(String data) { + System.out.println(data); + response.onNext("hello,"+data); + } + + @Override + public void onError(Throwable throwable) { + throwable. printStackTrace(); + } + + @Override + public void onCompleted() { + System.out.println("onCompleted"); + response.onCompleted(); + } + }; + } + + @Override + public void sayHelloServerStream(String request, StreamObserver response) { + for (int i = 0; i < 10; i++) { + response.onNext("hello," + request); + } + response.onCompleted(); + } +} +``` + +3. Call method +```java +delegate.sayHelloServerStream("server stream", new StreamObserver() { + @Override + public void onNext(String data) { + System.out.println(data); + } + + @Override + public void onError(Throwable throwable) { + throwable. printStackTrace(); + } + + @Override + public void onCompleted() { + System.out.println("onCompleted"); + } +}); + + +StreamObserver request = delegate.sayHelloStream(new StreamObserver() { + @Override + public void onNext(String data) { + System.out.println(data); + } + + @Override + public void onError(Throwable throwable) { + throwable. printStackTrace(); + } + + @Override + public void onCompleted() { + System.out.println("onCompleted"); + } +}); +for (int i = 0; i < n; i++) { + request.onNext("stream request" + i); +} +request.onCompleted(); +``` + +## Serialized stream using Protobuf + +For the `Protobuf` serialization method, it is recommended to write `IDL` and use the `compiler` plugin to compile and generate. The generated code is roughly as follows: +```java +public interface PbGreeter { + + static final String JAVA_SERVICE_NAME = "org.apache.dubbo.sample.tri.PbGreeter"; + static final String SERVICE_NAME = "org.apache.dubbo.sample.tri.PbGreeter"; + + static final boolean inited = PbGreeterDubbo.init(); + + //... + + void greetServerStream(org.apache.dubbo.sample.tri.GreeterRequest request, org.apache.dubbo.common.stream.StreamObserver responseObserver); + + org.apache.dubbo.common.stream.StreamObserver greetStream(org.apache.dubbo.common.stream.StreamObserver responseObserver); +} +``` + +### Implementation principle of stream + +How does the streaming mode of the `Triple` protocol support it? + +- From the perspective of the protocol layer, `Triple` is built on the basis of `HTTP2`, so it directly has all the capabilities of `HTTP2`, so it has the ability to split `stream` and full-duplex. + +- In terms of the framework layer, `StreamObserver` is provided to users as a stream interface to provide stream processing for input and output parameters. The framework makes corresponding interface calls when sending and receiving stream data, so as to ensure the integrity of the life cycle of the stream. + +## Triple and application-level registration discovery + +The application-level service registration and discovery of the Triple protocol is consistent with other languages, and you can learn more about it through the following content. + +- [Service Discovery](/zh/docs/concepts/service-discovery/) +- [Application-level address discovery migration guide](/zh/docs/migration/migration-service-discovery/) + +## Intercommunicate with GRPC + +Through the introduction of the protocol, we know that the `Triple` protocol is based on `HTTP2` and compatible with `GRPC`. In order to ensure and verify the interoperability with `GRPC`, Dubbo3 has also written various tests in slave scenarios. For details, you can learn more through [here](https://github.com/apache/dubbo-samples/blob/master/3-extensions/protocol/dubbo-samples-triple/README.MD). + +## Future: Everything on Stub + +Students who have used `Grpc` should be familiar with `Stub`. +Grpc uses `compiler` to compile the written `proto` file into related protobuf objects and related rpc interfaces. By default several different `stubs` will be generated at the same time + +-blockingStub +- futureStub + -reactorStub + -... + +`stub` helps us shield the details of different calling methods in a unified way. However, currently `Dubbo3` only supports the traditional way of defining and calling interfaces. + +In the near future, `Triple` will also implement various commonly used `Stub`, allowing users to write a `proto` file, which can be conveniently used in any scene through `comipler`, please wait and see. \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/upgrades-and-compatibility/protobuf&interface.md b/content/en/docs3-v2/java-sdk/upgrades-and-compatibility/protobuf&interface.md new file mode 100644 index 000000000000..fe49cfc5182d --- /dev/null +++ b/content/en/docs3-v2/java-sdk/upgrades-and-compatibility/protobuf&interface.md @@ -0,0 +1,141 @@ +--- +type: docs +title: "Comparison of Protobuf and Interface" +linkTitle: "Protobuf vs Interface" +weight: 100 +description: >- + This article compares the differences between the two IDLs, Protobuf and Interface, to help Dubbo protocol developers understand Protobuf, and pave the way for the subsequent transfer to Triple protocol and Grpc protocol. +--- + +## 1. Data type + +### 1.1. Basic types + +| ptoto type | java type | +| ---- | ---- | +double | double +float | float +int32 | int +int64 | long +uint32 | int[Note] +uint64 | long[Note] +sint32 | int +sint64 | long +fixed32 | int[Note] +fixed64 | long[Note] +sfixed32 | int +sfixed64 | long +bool | boolean +string | String +bytes | ByteString + +> [Note] In Java, unsigned 32-bit and 64-bit integers are represented using their signed logarithms, with the top bit only stored in the sign bit. +## 2. Composite types + +### 2.1. Enumeration + +* Original pb code + +```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; +} +``` + +* Generated java code + +![image](/imgs/docs/advanced/protobufinterface/124234531-b96c2c80-db46-11eb-8155-a77dbe059f07.png) + +> Enumerations are constants, so use uppercase +### 2.2. Arrays + +* Original pb code + +```java +message VipIDToRidReq { + repeated uint32 vipID = 1; +} +``` + +* Generated java code + +![image](/imgs/docs/advanced/protobufinterface/124234564-c4bf5800-db46-11eb-94fc-a056af6089cb.png) + +> The bottom layer is actually an ArrayList +### 2.3. Collections + +PB does not support unordered and non-repeating collections, and can only ``borrow arrays to implement``, and needs to ``remove duplicates by itself``. + +### 2.4. Dictionaries + +* Original pb code + +```java +message BatchOnlineRes { + map onlineMap = 1;//online status +} +``` + +* Generated java code + +![image](/imgs/docs/advanced/protobufinterface/124234654-e4568080-db46-11eb-9700-b30022ebee21.png) + +### 2.5. Nesting + +* Original pb code + +```java +message BatchAnchorInfoRes { + map list = 1; //user information map list +} +/* +* The function of the corresponding interface: get user information in batches or individually +*/ +message AnchorInfo { + uint32 ownerUid = 1 [json_name="uid"]; //user id + string nickName = 2 [json_name="nn"]; //User nickname + string smallAvatar = 3 [json_name="savt"]; //full path of user avatar - small + string middleAvatar = 4 [json_name="mavt"]; //Full path of user avatar - middle + string bigAvatar = 5 [json_name="bavt"]; //Full path of user avatar - big + string avatar = 6 [json_name="avt"]; //User avatar +} +``` + +* Generated java code + +![image](/imgs/docs/advanced/protobufinterface/124234723-f89a7d80-db46-11eb-82d0-a8aee5322098.png) + +## 3. Field default value + +* For strings, the default is the empty string. +* For bytes, the default is the null byte. +* For bools, the default is false. +* For numeric types, the default value is zero. +* For enums, the default is the first defined enum value, which must be 0. +* For the message field, the field is not set. Its exact value is language dependent. See the generated code guide for details. + +## 4. Overall structure + +| Feature | Java Interface | Protobuf | Remarks | +| ---- | ---- | ---- | ---- | +| Method Overloading | √ | × | | +| Generic/templated | √ | × | | +| method inheritance | √ | × | | +| Nested definition | √ | Partial support | PB only supports message and enum nesting | +| import file | √ | √ | | +| field is null | √ | × | | +| Multiple input parameters | √ | × | PB only supports single input parameters | +| 0 input parameters | √ | × | PB must have input parameters | +| 0 output parameters | √ | × | PB must have output parameters | +| The input/output parameters are abstract classes | √ | × | The input/output parameters of PB must be concrete classes | +| The input/output parameters are interfaces | √ | × | The input/output parameters of PB must be concrete | +| The input parameter/output parameter is the basic type | √ | × | The input parameter/output parameter of PB must be a structure | + +## 5. Community profile +* Community homepage address: https://developers.google.cn/protocol-buffers/ +* Community open source address: https://github.com/google/protobuf +* Maven of related jars: https://search.maven.org/search?q=com.google.protobuf \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/upgrades-and-compatibility/serialization-upgrade.md b/content/en/docs3-v2/java-sdk/upgrades-and-compatibility/serialization-upgrade.md new file mode 100644 index 000000000000..2c5572300940 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/upgrades-and-compatibility/serialization-upgrade.md @@ -0,0 +1,26 @@ +--- +type: docs +title: "Serialization Protocol Upgrade Guide" +linkTitle: "Serialization Protocol Upgrade Guide" +weight: 6 +description: "Best practice for lossless upgrade serialization protocols" +--- +In version 3.1.0, the serialization protocol supported by Dubbo by default adds support for Fastjson2. Some users may consider upgrading the serialization protocol in the existing system, but the difference between the server and client versions may cause the client to not support the serialization protocol of the server. In version 3.2.0, Dubbo's server introduces a new configuration `prefer-serialization`, which can perfectly solve the possible risks in the server-side serialization upgrade process. + + +### Best Practices + +Serialization protocol upgrade needs to be done in two steps: + +* **First, it is necessary to promote the serialization protocol upgrade of the server, and at the same time, the `prefer-serialization` configuration needs to be added to the exposed configuration of the server. For example: the serialization protocol before the upgrade is hessian2, and the serialization protocol after the upgrade is Fastjson2, then the configuration shown below should be added to the exposed configuration of the server ** + +```yaml +dubbo.provider.prefer-serialization=fastjson2,hessian2 +dubbo.provider.serialization=hessian2 +``` +* **Secondly, the client needs to be upgraded to the same version as the server** + +### Implementation principle + +The dubbo client serialization protocol is selected according to the registration configuration of the server (that is, the `serialization` configuration of the server). In the request phase, dubbo will assemble the serialization protocol of the client into the request header, and the server will determine the deserialization protocol according to the request header when performing deserialization. +- **So, if the versions of the server and the client are inconsistent, the client may not be able to serialize. ** In order to solve this situation, 3.2.0 will use the protocol configured by `prefer-serialization` first when serializing the client. If the protocol related to `prefer-serialization` is not supported, the protocol configured by `serialization` will be used . (You can think of `serialization` as a bottom-up configuration) \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/upgrades-and-compatibility/service-discovery/_index.md b/content/en/docs3-v2/java-sdk/upgrades-and-compatibility/service-discovery/_index.md new file mode 100755 index 000000000000..1bcd924a8fa5 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/upgrades-and-compatibility/service-discovery/_index.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "Application Level Service Discovery" +linkTitle: "Application-Level Service Discovery" +weight: 6 +--- \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/upgrades-and-compatibility/service-discovery/migration-service-discovery.md b/content/en/docs3-v2/java-sdk/upgrades-and-compatibility/service-discovery/migration-service-discovery.md new file mode 100644 index 000000000000..ebc675d317c8 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/upgrades-and-compatibility/service-discovery/migration-service-discovery.md @@ -0,0 +1,159 @@ +--- +type: docs +title: "Guidelines for migrating interface-level service discovery to application-level service discovery" +linkTitle: "Guidelines for migrating interface-level service discovery to application-level service discovery" +weight: 10 +description: "This document is specifically aimed at old users of version 2.x. It explains in detail the default address registration and discovery behavior after upgrading to 3.x, and how to smoothly migrate to the address model of the new version." +--- + +**In general, 3.x is fully compatible with 2.x in address registration and discovery, which means that users can choose to upgrade any number of applications or machines in the cluster to 3.x, and at the same time Interoperability with 2.x versions is maintained in the process. ** +If you are concerned about the working principle behind migration, please refer to [Migration Rule Details and Working Principle](../service-discovery-rule) + +## 1 Quick upgrade steps + +Simply modify the pom.xml to the latest version to complete the upgrade. If you want to migrate to the application-level address, you only need to adjust the switch to control the default behavior of the 3.x version. + +1. Upgrade the Provider application to the latest 3.x version dependency, configure the dual registration switch `dubbo.application.register-mode=all` (it is recommended to set it through the global configuration center, it is automatically enabled by default), and complete the application release. +2. Upgrade the Consumer application to the latest 3.x version dependency, configure the dual subscription switch `dubbo.application.service-discovery.migration=APPLICATION_FIRST` (it is recommended to set it through the global configuration center, it is automatically enabled by default), and complete the application release. +3. After confirming that all consumers on the Provider have completed the application-level address migration, the Provider switches to the application-level address list registration. complete upgrade + + + +The following is a detailed description of the migration process. + +## 2 Provider-side upgrade process details + +Without changing any Dubbo configuration, an application or instance can be upgraded to version 3.x, and the upgraded Dubbo instance will tacitly guarantee compatibility with version 2.x, that is, the 2.x format will be registered normally address to the registry, so upgraded instances will still remain visible to the entire cluster. + + + +At the same time, the new address discovery model (registering application-level addresses) will also be automatically registered. + +![//imgs/v3/migration/provider-registration.png](/imgs/v3/migration/provider-registration.png) + +Through the -D parameter, you can specify the registration behavior when the provider starts + +```text +-Ddubbo.application.register-mode=all +# Optional values interface, instance, all, the default is all, that is, both interface-level addresses and application-level addresses are registered +``` + + + +In addition, the global default behavior can be modified in the configuration center to control the registration behavior of all 3.x instances. Among them, the priority of the global switch is lower than that of the -D parameter. + + + +In order to ensure smooth migration, that is, instances upgraded to 3.x can be discovered by 2.x and 3.x consumer instances at the same time, 3.x instances need to enable dual registration; when all upstream consumers are migrated to 3.x After the address model is specified, the provider can switch to the instance mode (only register application-level addresses). See the next section for how to upgrade the consumer to 3.x. + +### 2.1 Resource consumption caused by double registration + +Double registration will inevitably bring additional storage pressure on the registration center, but considering the great advantages of the data volume of the application-level address discovery model in terms of storage, even for some ultra-large-scale cluster users, the new data volume It doesn't cause storage problems either. Generally speaking, for an ordinary cluster, data growth can be controlled at 1/100 ~ 1/1000 of the previous total data + +Take a medium-sized cluster instance: 2000 instances, 50 applications (500 Dubbo interfaces, 10 interfaces per application on average). + +Assume that the average size of each interface-level URL address is 5kb, and the average size of each application-level URL is 0.5kb + +Old interface-level address volume: 2000 * 500 * 5kb ≈ 4.8G + +New application-level addresses: 2000 * 50 * 0.5kb ≈ 48M + +After double registration, only 48M data volume has been increased. + + + +## 3 Consumer side upgrade process + +For 2.x consumer instances, they will naturally see the 2.x version of the provider address list; + +For 3.x consumers, it has the ability to discover both 2.x and 3.x provider address lists. By default, if there is a 3.x address that can be consumed in the cluster, the 3.x address will be automatically consumed, and if there is no new address, the 2.x address will be automatically consumed. Dubbo3 provides a switch to control this behavior: + +```text +dubbo.application.service-discovery.migration=APPLICATION_FIRST +# optional value +# FORCE_INTERFACE, only consume interface-level addresses, if there is no address, an error will be reported, and only subscribe to 2.x addresses +# APPLICATION_FIRST, intelligent decision interface level/application level address, double subscription +# FORCE_APPLICATION, only consume application-level addresses, if there is no address, an error will be reported, and only subscribe to 3.x addresses +``` + +`dubbo.application.service-discovery.migration` supports configuration via `-D` and `Global Configuration Center`. + + + +![//imgs/v3/migration/consumer-subscription.png](/imgs/v3/migration/consumer-subscription.png) + + +Next, let's take a closer look at how to migrate consumers upgraded to 3.x to application-level addresses through the dual subscription mode (APPLICATION_FIRST). Before the specific development, first clarify the location selection behavior of the consumer: **For the dual subscription scenario, although the consumer can hold the 2.x address and the 3.x address at the same time, the two addresses are completely isolated during the location selection process Definitely: Either use 2.x address or 3.x address, there is no mixed calling of two addresses, this decision-making process is completed after receiving the first address notification. ** + + + +Next, let's look at the specific operation process of an `APPLICATION_FIRST` strategy. + +First, configure a configuration item in the global configuration center Nacos in advance (all consumers will implement this address selection strategy by default): + +![//imgs/v3/migration/nacos-migration-item.png](/imgs/v3/migration/nacos-migration-item.png) + + + +Next, upgrade the consumer to version 3.x and start it. At this time, the consumer reads the `APPLICATION_FIRST` configuration and executes the double subscription logic (subscribing to 2.x interface-level addresses and 3.x application-level addresses) + + + +At this point, the upgrade operation is completed, and the rest is the execution within the framework. Before the call occurs, the framework will have a "site selection process" on the consumer side. Note that the site selection here is different from the previous 2.x version. The site selection process includes two layers of screening: + +* Filter the address list (ClusterInvoker) first (interface-level address or application-level address) +* Then perform the actual provider address (Invoker) screening. + +![//imgs/v3/migration/migration-cluster-item.png](/imgs/v3/migration/migration-cluster-invoker.png) + +The basis for ClusterInvoker screening can be defined by the MigrationAddressComparator SPI. Currently, the official provides a simple address quantity comparison strategy, that is, migration will be performed when `application-level address quantity == interface-level address quantity` is satisfied. + +> In fact, FORCE_INTERFACE, APPLICATION_FIRST, and FORCE_APPLICATION control the filtering strategy of the ClusterInvoker type here + + + +### 3.1 Resource consumption caused by double subscription + +Double subscription will inevitably increase the memory consumption of the consumer, but due to the advantages of application-level address discovery in terms of the total number of addresses, this process is usually acceptable. We analyze it from two aspects: + +1. The amount of address push data increased due to double subscription. We introduced this point in the "Double Registration Resource Consumption" section, and the data volume growth of the registration center brought about by application-level service discovery is very limited. +2. The increase in memory on the consumer side brought about by double subscriptions. It should be noted that double subscription only exists in the startup transient state, and one of the addresses will be completely destroyed after the ClusterInvoker site selection decision; for a single service, the memory growth caused by the double subscription during the startup phase can be controlled at about 30% of the original memory % ~ 40%, and then it will drop to the single subscription level. If you switch to the application-level address, you can achieve a 50% drop in memory. + + + +### 3.2 Finer-grained control on the consumer side + +In addition to the global migration strategy, Dubbo provides more fine-grained migration strategy support on the consumer side. The control unit can be a certain consumer application, and the service A and service B it consumes can have their own independent migration strategies. The specific method is to configure the migration rules on the consumer side: + + +```yaml +key: demo-consumer +step: APPLICATION_FIRST +applications: + - name: demo-provider + step: FORCE_APPLICATION +services: + - serviceKey: org.apache.dubbo.config.api.DemoService:1.0.0 + step: FORCE_INTERFACE +``` + +Using this method can achieve more fine-grained migration control, but the current and subsequent transformation costs will be relatively high. Except for some special scenarios, we do not recommend enabling this configuration method. +([Migration Guide](../service-discovery-rule/)) **Officially recommended global switch-type migration strategy, allowing consumer instances to decide which available address list to use during the startup phase. ** + + + +## 4 Convergence of transition state + +In order to be compatible with the 2.x version at the same time, the application upgraded to the 3.x version is either in the double registration state or in the double subscription state for a period of time. + +To solve this problem, we still look at it from the Provider perspective. When all Providers are switched to application-level address registration, there will be no double subscription problem. + +### 4.1 Different upgrade strategies have a great impact + +There is no doubt that the sooner and more thoroughly the upgrade will be able to get rid of this situation as soon as possible. Imagine that if all applications in the organization can be upgraded to version 3.x, version convergence becomes very simple: Provider always maintains dual registration during the upgrade process. After all applications are upgraded to 3.x, you can Adjust the global default behavior to make Providers become application-level address list registrations. This process will not cause trouble for Consumer applications, because they are already version 3.x that can recognize application-level addresses. + +If there is no way to upgrade the entire application, or even only a part of the application can be upgraded within a long period of time, the inevitable migration state will last for a relatively long time. +In this case, what we can only pursue is to keep the upstream and downstream implementation versions and functions of the upgraded application converged as much as possible. The upstream consumers of certain Providers are promoted to upgrade to Dubbo3, so that the dual registration of these Providers can be lifted. To do this, the support of some auxiliary statistical tools may be required. + +1. To be able to analyze the dependencies between applications, such as which consumer applications a Provdier application is consumed by, this can be achieved through the service metadata reporting capability provided by Dubbo. +2. To know the dubbo version currently used by each application, you can scan or actively report. \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/upgrades-and-compatibility/service-discovery/service-discovery-rule.md b/content/en/docs3-v2/java-sdk/upgrades-and-compatibility/service-discovery/service-discovery-rule.md new file mode 100644 index 000000000000..7159df792d72 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/upgrades-and-compatibility/service-discovery/service-discovery-rule.md @@ -0,0 +1,203 @@ +--- +type: docs +title: "Application-level Service Discovery Address Migration Rules Description" +linkTitle: "Application-level service discovery address migration rules" +weight: 42 +description: "This article specifies the rule body information used in the address migration process. Users can customize their own migration rules according to their needs." +--- + +## State Model + + +Before Dubbo 3, the address registration model was registered to the registry at the interface-level granularity, while the new application-level registration model of Dubbo 3 is registered to the registry at the application-level granularity. The implementation of the registry is almost different, which leads to the inability to merge the invokers obtained from the interface-level registration model with the invokers obtained from the application-level registration model. In order to help users migrate from the interface level to the application level, Dubbo 3 has designed the Migration mechanism, which realizes the switching of the address model in the actual call based on the switching of the three states. + + +![//imgs/v3/migration/migration-1.png](/imgs/v3/migration/migration-1.png) + +Currently there are three states, FORCE_INTERFACE (mandatory interface level), APPLICATION_FIRST (application level priority), FORCE_APPLICATION (mandatory application level). + + +FORCE_INTERFACE: Only enable the registry logic for interface-level service discovery in compatibility mode, and 100% of the call traffic follows the original process +APPLICATION_FIRST: Enable interface-level and application-level dual subscriptions, and dynamically determine the calling traffic direction according to the threshold and grayscale traffic ratio at runtime +FORCE_APPLICATION: Only enable the registration center logic of application-level service discovery in the new mode, and 100% of the call traffic goes to the address of the application-level subscription + + +## Description of rule body + + +The rules are configured in yaml format, and the specific configuration is as follows: +```yaml +key: consumer application name (required) +step: state name (required) +threshold: decision threshold (default 1.0) +proportion: grayscale ratio (default 100) +delay: delay decision time (default 0) +force: force switching (default false) +interfaces: interface granularity configuration (optional) + - serviceKey: interface name (interface + : + version number) (required) + threshold: decision threshold + proportion: grayscale ratio + delay: delay decision time + force: force switch + step: state name (required) + - serviceKey: interface name (interface + : + version number) + step: state name +applications: application granular configuration (optional) + - serviceKey: application name (consumed upstream application name) (required) + threshold: decision threshold + proportion: grayscale ratio + delay: delay decision time + force: force switch + step: state name (required) +``` + + +- key: consumer application name +- step: state name (FORCE_INTERFACE, APPLICATION_FIRST, FORCE_APPLICATION) +- threshold: decision threshold (floating point number, refer to the following for specific meaning) +- proportion: grayscale ratio (0 to 100, determines the proportion of calling times) +- delay: Delay decision time (delay decision time, the actual waiting time is 1~2 times the delay time, depending on the time of the first notification from the registration center, for the current Dubbo registration center to achieve secondary configuration items keep 0) +- force: Forced switching (for FORCE_INTERFACE, FORCE_APPLICATION whether to switch directly without considering the decision, which may cause no address call failure) +- interfaces: interface granularity configuration + + + +The reference configuration example is as follows: +```yaml +key: demo-consumer +step: APPLICATION_FIRST +threshold: 1.0 +proportion: 60 +delay: 0 +force: false +interfaces: + - serviceKey: DemoService: 1.0.0 + threshold: 0.5 + proportion: 30 + delay: 0 + force: true + step: APPLICATION_FIRST + - serviceKey: GreetingService: 1.0.0 + step: FORCE_APPLICATION +``` + + +## Description of configuration method +### 1. Configuration center configuration file delivery (recommended) + + +- Key: consumer application name + ".migration" +- Group: DUBBO_SERVICEDISCOVERY_MIGRATION + + +Refer to the previous section for the content of configuration items + + +When the program starts, it will pull this configuration as the highest priority startup item. When the configuration item is a startup item, no checking operation will be performed, and the final state will be reached directly according to the status information. +When a new configuration item is received during the running of the program, the migration operation will be performed, and the configuration information will be checked during the process. If the check fails, it will be rolled back to the pre-migration state. Migration is performed at the interface granularity, that is, if an application has 10 interfaces, 8 of which migrate successfully and 2 fail, then in the final state, the 8 successfully migrated interfaces will execute the new behavior, and the 2 failed interfaces will still be old state. If it is necessary to re-trigger the migration, it can be achieved by re-delivering the rules. + + +Note: If the program is rolled back due to check failure during migration, since the program does not have the behavior of writing back configuration items, if the program is restarted at this time, the program will directly initialize according to the new behavior without checking. + + +### 2. Start parameter configuration + + +- Configuration item name: dubbo.application.service-discovery.migration +- Range of allowed values: FORCE_INTERFACE, APPLICATION_FIRST, FORCE_APPLICATION + + + +This configuration item can be passed in through environment variables or the configuration center, and has a lower priority than the configuration file at startup, that is, when the configuration file in the configuration center does not exist, this configuration item is read as the startup status. + + +### 3. Local file configuration + + + +| Configuration item name | Default value | Description | +| --- | --- | --- | +| dubbo.migration.file | dubbo-migration.yaml | Local configuration file path | +| dubbo.application.migration.delay | 60000 | Configuration file delay effective time (milliseconds) | + +The format in the configuration file is consistent with the rules mentioned above + + +The local file configuration method is essentially a delayed configuration notification method. The local file will not affect the default startup method. When the delay time is reached, a notification with the same content as the local file will be triggered. The delay time here is not related to the delay field in the rule body. +The local file configuration method can ensure that the startup is initialized with the default behavior. When the delay is reached, the migration operation is triggered and the corresponding check is performed to avoid starting in the final state at startup. + + +## Decision statement +### 1. Threshold detection + + +The threshold mechanism is designed to check the number of addresses before traffic switching. If the number of available addresses at the application level is compared with the number of available addresses at the interface level, the check fails if the threshold is not reached. + + +The core code is as follows: +```java +if (((float) newAddressSize / (float) oldAddressSize) >= threshold) { + return true; +} +return false; +``` + + +At the same time, MigrationAddressComparator is also an SPI extension point, users can expand it by themselves, and the results of all checks are intersected. + + +### 2. Gray scale + + +The gray scale function only takes effect in the application-level priority state. This feature allows users to determine the proportion of calls to the address of the new mode application-level registry. The prerequisite for the gray scale to take effect is to meet the threshold detection. In the application-level priority state, if the threshold detection passes, `currentAvailableInvoker` will be switched to the invoker corresponding to the application-level address; if the detection fails, `currentAvailableInvoker` will still be the original interface-level address The invoker. + + +The flow chart is as follows: +detection stage +![//imgs/v3/migration/migration-2.png](/imgs/v3/migration/migration-2.png) +call phase +![//imgs/v3/migration/migration-3.png](/imgs/v3/migration/migration-3.png) + + +The core code is as follows: +```java +// currentAvailableInvoker is based on MigrationAddressComparator's result +if (currentAvailableInvoker != null) { + if (step == APPLICATION_FIRST) { + // call ratio calculation based on random value + if (ThreadLocalRandom. current(). nextDouble(100) > promotion) { + return invoker.invoke(invocation); + } + } + return currentAvailableInvoker.invoke(invocation); +} + +``` + + +## Description of switching process + + +The process of address migration involves the switching of three states. In order to ensure smooth migration, there are 6 switching paths that need to be supported, which can be summarized as switching from mandatory interface level, mandatory application level to application level priority; application level priority to mandatory interface level, Mandatory application-level switching; there are also mandatory interface-level and mandatory application-level switching. +The switching process for the same interface is always synchronous. If a new rule is received before the previous rule has been processed, it will wait. + + +### 1. Switch to application-level priority + + +Switching from mandatory interface level, mandatory application level to application level priority is essentially a process of switching from a single subscription to a dual subscription, retaining the original subscription and creating another subscription. In this switching mode, the delay configuration configured in the rule body will not take effect, that is, the threshold detection will be performed immediately after the subscription is created, and a decision will be made to select a certain group of subscriptions for the actual priority call. Since the application-level priority mode supports dynamic threshold detection at runtime, the threshold will be recalculated and switched after all addresses are notified for the scenario where some registry centers fail to start and obtain all addresses. +Dynamic switching in the application-level priority mode is implemented based on the address listener of the service directory (Directory). +![//imgs/v3/migration/migration-4.png](/imgs/v3/migration/migration-4.png) + + +### 2. Application-level priority switch to mandatory + + +The process of switching from application-level priority to mandatory interface level and mandatory application level is to check the address of the double subscription. If it is satisfied, the other subscription will be destroyed. If it is not satisfied, the original application-level priority status will be rolled back. +If the user wants the switching process to switch directly without checking, it can be realized by configuring the force parameter. +![//imgs/v3/migration/migration-5.png](/imgs/v3/migration/migration-5.png) +### 3. Mandatory interface level and mandatory application level switch between each other + + +To switch between the mandatory interface level and the mandatory application level, a new subscription needs to be temporarily created to determine whether the new subscription (that is, the number of addresses of the new subscription is used to subtract the number of addresses of the old subscription when calculating the threshold) is up to the standard. Failure to meet the standard will destroy the new subscription and roll back to the previous state. +![//imgs/v3/migration/migration-6.png](/imgs/v3/migration/migration-6.png) \ No newline at end of file diff --git a/content/en/docs3-v2/java-sdk/upgrades-and-compatibility/service-discovery/service-discovery-samples.md b/content/en/docs3-v2/java-sdk/upgrades-and-compatibility/service-discovery/service-discovery-samples.md new file mode 100644 index 000000000000..640db50134b8 --- /dev/null +++ b/content/en/docs3-v2/java-sdk/upgrades-and-compatibility/service-discovery/service-discovery-samples.md @@ -0,0 +1,76 @@ +--- +type: docs +title: "Application-Level Service Discovery Migration Example" +linkTitle: "Application-level service discovery migration example" +weight: 5 +description: "This article specifically explains how users can quickly enable new features of application-level service discovery after upgrading to Dubbo 3.0." +--- + +Application-level service discovery is a protocol for service discovery between applications. Therefore, to use application-level service discovery, both the consumer and the server must be upgraded to Dubbo 3.0 and new features enabled (enabled by default) to use application-level service discovery in the link. Take advantage of application-level service discovery. +## Open method +### Server +After the application is upgraded to Dubbo 3.0, the server will automatically enable the interface-level + application-level dual registration function, and the developer does not need to modify any configuration by default + +### Consumer side +After the application is upgraded to Dubbo 3.0, the consumer side automatically starts the interface-level + application-level dual subscription function, and the developer does not need to modify any configuration by default. It is recommended that after the server is upgraded to Dubbo 3.0 and the application-level registration is enabled, configure the consumer end to close the interface-level subscription through rules to release the corresponding memory space. + +## Detailed description +### Server configuration + +1. Global switch + +Application configuration (can be specified by configuration file or -D) `dubbo.application.register-mode` enables the global registration switch for instance (only register application level) and all (both interface level and application level registration). After configuring this switch , by default, application-level addresses will be registered with all registries for service discovery on the consumer side. +> Example: [https://github.com/apache/dubbo-samples/blob/master/dubbo-samples-cloud-native/dubbo-servicediscovery-migration/dubbo-servicediscovery-migration-provider2/src/main/resources/ dubbo.properties](https://github.com/apache/dubbo-samples/blob/master/2-advanced/dubbo-samples-cloud-native/dubbo-servicediscovery-migration/dubbo-servicediscovery-migration-provider2/src /main/resources/dubbo.properties) + +``` +# double registration +dubbo.application.register-mode=all +``` +``` +# Application-level registration only +dubbo.application.register-mode=instance +``` + +2. Registration center address parameter configuration + +Registry-type=service can be configured on the address of the registry to display the registry that specifies the registry as application-level service discovery, and the registry with this configuration will only perform application-level service discovery. +> Example: [https://github.com/apache/dubbo-samples/blob/master/dubbo-samples-cloud-native/dubbo-demo-servicediscovery-xml/servicediscovery-provider/src/main/resources/spring/ dubbo-provider.xml](https://github.com/apache/dubbo-samples/blob/master/2-advanced/dubbo-samples-cloud-native/dubbo-demo-servicediscovery-xml/servicediscovery-provider/src /main/resources/spring/dubbo-provider.xml) + +```xml + +``` +### Consumer Subscription Mode +FORCE_INTERFACE: only interface-level subscription, the behavior is consistent with Dubbo 2.7 and previous versions. +APPLICATION_FIRST: interface level + application level multi-subscription, if the application level can subscribe to the address, use the application level subscription, if the address cannot be subscribed, use the interface level subscription, so as to ensure the greatest compatibility during the migration process. (Note: Due to the simultaneous subscription behavior, the memory usage in this mode will increase to a certain extent, so after all servers are upgraded to Dubbo 3.0, it is recommended to migrate to FORCE_APPLICATION mode to reduce memory usage) +FORCE_APPLICATION: Only application-level subscriptions will only use the new service discovery model. +### Consumer configuration + +1. Default configuration (no configuration required) + +After upgrading to Dubbo 3.0, the default behavior is interface-level + application-level multi-subscription. If the address can be subscribed at the application level, the application-level subscription will be used. If the address cannot be subscribed, the interface-level subscription will be used to ensure maximum compatibility. + +2. Subscription parameter configuration + +Application configuration (can be specified by configuration file or -D) `dubbo.application.service-discovery.migration` is `APPLICATION_FIRST` to enable multi-subscription mode, and configuration to `FORCE_APPLICATION` can force application-level subscription mode only. +The specific interface subscription can be configured in `parameters` in `ReferenceConfig`, and the Key is `migration.step`, and the Value is `APPLICATION_FIRST` or `FORCE_APPLICATION` key-value pair to configure a single subscription. +> Example: [https://github.com/apache/dubbo-samples/blob/master/dubbo-samples-cloud-native/dubbo-servicediscovery-migration/dubbo-servicediscovery-migration-consumer/src/test/java/ org/apache/dubbo/demo/consumer/DemoServiceConfigIT.java](https://github.com/apache/dubbo-samples/blob/master/2-advanced/dubbo-samples-cloud-native/dubbo-servicediscovery-migration /dubbo-servicediscovery-migration-consumer/src/test/java/org/apache/dubbo/demo/consumer/DemoServiceConfigIT.java) + +```java +System.setProperty("dubbo.application.service-discovery.migration", "APPLICATION_FIRST"); +``` +```java +ReferenceConfig referenceConfig = new ReferenceConfig<>(applicationModel. newModule()); +referenceConfig.setInterface(DemoService.class); +referenceConfig.setParameters(new HashMap<>()); +referenceConfig.getParameters().put("migration.step", mode); +return referenceConfig.get(); +``` + +3. Dynamic configuration (highest priority, configuration can be modified at runtime) + +This configuration needs to be pushed based on the configuration center, the Key is the application name + `.migration` (such as `demo-application.migraion`), and the Group is `DUBBO_SERVICEDISCOVERY_MIGRATION`. For details on rule body configuration, see [Guidelines for migrating from interface-level service discovery to application-level service discovery](../migration-service-discovery/). +> Example: [https://github.com/apache/dubbo-samples/blob/master/dubbo-samples-cloud-native/dubbo-servicediscovery-migration/dubbo-servicediscovery-migration-consumer/src/main/java/ org/apache/dubbo/demo/consumer/UpgradeUtil.java](https://github.com/apache/dubbo-samples/blob/master/2-advanced/dubbo-samples-cloud-native/dubbo-servicediscovery-migration /dubbo-servicediscovery-migration-consumer/src/main/java/org/apache/dubbo/demo/consumer/UpgradeUtil.java) + +```java +step: FORCE_INTERFACE +``` \ No newline at end of file diff --git a/content/en/latest/community/_index.md b/content/en/latest/community/_index.md index 95c7cbc6bf16..efe0dcd67205 100644 --- a/content/en/latest/community/_index.md +++ b/content/en/latest/community/_index.md @@ -1,8 +1,5 @@ --- title: Community -menu: - main: - weight: 40 --- diff --git a/content/en/latest/contribution-guidelines/_index.md b/content/en/latest/contribution-guidelines/_index.md index b4267abff489..1084f42c2c8e 100755 --- a/content/en/latest/contribution-guidelines/_index.md +++ b/content/en/latest/contribution-guidelines/_index.md @@ -4,9 +4,6 @@ type: docs title: "Dubbo Contribution Guidelines" linkTitle: "Contribution" description: "Dubbo Contribution Guidelines" -menu: - main: - weight: 50 --- diff --git a/content/en/latest/facade-docs/_index.md b/content/en/latest/facade-docs/_index.md index acd2f441ce6f..8a5af2ef1e60 100755 --- a/content/en/latest/facade-docs/_index.md +++ b/content/en/latest/facade-docs/_index.md @@ -4,11 +4,6 @@ type: docs title: "Documentation" linkTitle: "Documentation" weight: 20 -menu: - main: - weight: 10 - name: "Documentation" - --- diff --git a/content/en/latest/notices/_index.md b/content/en/latest/notices/_index.md index e3f4a4846bda..bdc4b97a5749 100755 --- a/content/en/latest/notices/_index.md +++ b/content/en/latest/notices/_index.md @@ -4,8 +4,5 @@ type: docs title: "Announcement" linkTitle: "Announcement" description: "Dubbo Announcement" -menu: - main: - weight: 60 --- diff --git a/content/en/overview/_index.md b/content/en/overview/_index.md new file mode 100755 index 000000000000..9ac8c9655c6c --- /dev/null +++ b/content/en/overview/_index.md @@ -0,0 +1,31 @@ +--- +type: docs +title: "Overview" +linkTitle: "Overview" +no_list: true +hide_summary: true +menu: + main: + weight: 1 +--- + +Dubbo is an RPC service framework that includes multiple language implementations (Java, Golang, etc.), where you can view the core concepts of Dubbo, as well as the demos and user manuals implemented in each language. + +* **If you are new to Dubbo**, you can quickly learn about Dubbo through the following links: + * [What is Dubbo](what/overview) + * [User Cases and Ecology](/en/users/) + * Experience Dubbo via [**Quick Start**](quickstart/) +* Want to know more about Dubbo features and usage details? + * Select the corresponding [**Multilanguage SDK Implementation**](mannual/), and refer to **Advanced Features** or **Reference Manual** +* Veteran users who want to learn about **Dubbo 3.0** quickly + * [3.0 Feature List](what/dubbo3/) + * Check the corresponding [Multilingual SDK Implementation](mannual/) for upgrades and compatibility + +#### Related Links +Dubbo's multilingual implementation and documentation: + +Language | OS | Compilers/SDK | Reference Documentation | +-- | -- | -- | -- | +Go | Windows, Linux, macOS | Go 1.13+ | [Go](../docs3-v2/golang-sdk) | +Java|Windows, Linux, macOS |Java 8+ | [Java](../docs3-v2/java-sdk/) | +Rust | Windwos, Linux, macOS | Rust 2021 edition | [Rust](../docs3-v2/rust-sdk) | \ No newline at end of file diff --git a/content/en/overview/mannual/Golang.md b/content/en/overview/mannual/Golang.md new file mode 100755 index 000000000000..b8024ee9d030 --- /dev/null +++ b/content/en/overview/mannual/Golang.md @@ -0,0 +1,14 @@ + +--- +type: docs +title: "Golang SDK" +linkTitle: "Golang" +description: "" +weight: 2 +manualLinkTarget: _blank +manualLinkRelref: ../../docs3-v2/golang-sdk/ +_build: { render: link } +--- + + + diff --git a/content/en/overview/mannual/Java.md b/content/en/overview/mannual/Java.md new file mode 100644 index 000000000000..d8afd3a153b2 --- /dev/null +++ b/content/en/overview/mannual/Java.md @@ -0,0 +1,13 @@ +--- +type: docs +title: "Java SDK" +linkTitle: "Java" +description: "" +weight: 1 +manualLinkRelref: ../../docs3-v2/java-sdk/ +manualLinkTarget: _blank +_build: { render: link } +--- + + + diff --git a/content/en/overview/mannual/Rust.md b/content/en/overview/mannual/Rust.md new file mode 100644 index 000000000000..b722e92f3180 --- /dev/null +++ b/content/en/overview/mannual/Rust.md @@ -0,0 +1,13 @@ +--- +type: docs +title: "Rust SDK" +linkTitle: "Rust" +description: "" +weight: 3 +manualLinkRelref: ../../docs3-v2/rust-sdk/ +manualLinkTarget: _blank +_build: { render: link } +--- + + + diff --git a/content/en/overview/mannual/_index.md b/content/en/overview/mannual/_index.md new file mode 100755 index 000000000000..0d037c883210 --- /dev/null +++ b/content/en/overview/mannual/_index.md @@ -0,0 +1,50 @@ + +--- +type: docs +title: "SDK Manual" +linkTitle: "SDK Manual" +weight: 5 +no_list: true +--- + + +{{< blocks/section color="white" height="auto">}} +
+
+
+
+
+
+
+

+ Java SDK +

+

Java SDK

+
+
+
+
+
+
+

+ Golang SDK +

+

Golang SDK

+
+
+
+
+
+
+

+ Rust SDK +

+

Rust SDK

+
+
+
+
+
+
+ +{{< /blocks/section >}} diff --git a/content/en/overview/quickstart/_index.md b/content/en/overview/quickstart/_index.md new file mode 100755 index 000000000000..f21fc3e7d81c --- /dev/null +++ b/content/en/overview/quickstart/_index.md @@ -0,0 +1,38 @@ + +--- +type: docs +title: "Quick Start" +linkTitle: "Quick Start" +weight: 2 +--- + +{{< blocks/section color="white" height="auto">}} +
+
+
+
+
+
+

+ Java SDK +

+

Dubbo Java SDK Quick start

+
+
+
+
+
+
+

+Golang SDK +

+

Dubbo Golang SDK Quick start

+
+
+
+ +
+
+
+ +{{< /blocks/section >}} \ No newline at end of file diff --git a/content/en/overview/tasks/_index.md b/content/en/overview/tasks/_index.md new file mode 100755 index 000000000000..796599cf1dbc --- /dev/null +++ b/content/en/overview/tasks/_index.md @@ -0,0 +1,11 @@ + +--- +type: docs +title: "Tasks" +linkTitle: "Tasks" +description: "" +weight: 4 +--- + + + diff --git a/content/en/overview/tasks/ecosystem/_index.md b/content/en/overview/tasks/ecosystem/_index.md new file mode 100755 index 000000000000..b85bb1111cfd --- /dev/null +++ b/content/en/overview/tasks/ecosystem/_index.md @@ -0,0 +1,58 @@ +--- +type: docs +title: "Microservice Governance" +linkTitle: "Microservice Governance" +description: "Demonstrate how to solve Dubbo microservice governance problems, such as transactions, full link tracking, current limiting and degradation, etc." +weight: 6 +no_list: true +--- + +{{< blocks/section color="white" height="auto">}} +
+
+
+
+
+
+

+ Transaction Management +

+

This example demonstrates how to implement transaction management of distributed Dubbo services through Seata to ensure data consistency.

+
+
+
+
+
+
+

+ rate limit downgrade +

+

Use Sentinel to protect your application from stability issues caused by sudden traffic overload of individual services.

+
+
+
+
+
+
+

+

http gateway access (document construction)

+

+

By converting the gateway http to dubbo protocol, the front-end traffic can be connected to the back-end dubbo service.

+
+
+
+
+
+
+

+

Spring Cloud system interoperability (document construction)

+

+

Demonstrates how to communicate with Spring Cloud's rest protocol through the Dubbo3 application-level service discovery mechanism.

+
+
+
+
+
+
+ +{{< /blocks/section >}} \ No newline at end of file diff --git a/content/en/overview/tasks/ecosystem/rate-limit.md b/content/en/overview/tasks/ecosystem/rate-limit.md new file mode 100644 index 000000000000..d0decdfa772f --- /dev/null +++ b/content/en/overview/tasks/ecosystem/rate-limit.md @@ -0,0 +1,95 @@ +--- +type: docs +title: "Current Limit Downgrade" +linkTitle: "Current limit downgrade" +weight: 2 +description: "Use Sentinel to protect your application from stability issues caused by sudden traffic overload of individual services." +--- + +## What is Sentinel + +With the popularity of microservices, the stability between services and services has become more and more important. Sentinel is a traffic management component for distributed, multilingual and heterogeneous service architectures. It mainly uses traffic as the entry point, from traffic routing, traffic control, traffic shaping, fuse downgrade, system adaptive overload protection, hotspot traffic protection, etc. dimensions to help developers ensure the stability of microservices. + +## 1. Example architecture description + +Interface definition: + +```java +public interface FooService { + + String sayHello(String name); +} +``` + +Interface implementation: + +```java +@DubboService(timeout = 3000) +public class FooServiceImpl implements FooService { + + @Override + public String sayHello(String name) { + return String. format("Hello, %s at %s", name, LocalDateTime. now()); + } +} +``` + +Current limiting configuration: + +```java +FlowRule flowRule = new FlowRule(FooService. class. getName()) + .setCount(10) + .setGrade(RuleConstant.FLOW_GRADE_QPS); +FlowRuleManager. loadRules(Collections. singletonList(flowRule)); +``` + +## 2. Quick start example + +### Step 1: Download the source code + +```shell script +git clone -b master https://github.com/apache/dubbo-samples.git +cd ./dubbo-samples-sentinel/ +``` + +### Step 2: Build use cases + +Execute the maven command to package the demo project + +```bash +mvn clean package +``` + +### Step 3: Start Provider + +```java +java -classpath ./target/dubbo-samples-sentinel-1.0-SNAPSHOT.jar org.apache.samples.sentinel.FooProviderBootstrap +``` + +### Step 4: Start OrderService + +```java +java -classpath ./target/dubbo-samples-sentinel-1.0-SNAPSHOT.jar org.apache.samples.sentinel.FooConsumerBootstrap +``` + +You can see that in the console output, `Blocked` means that blocking has started. + +``` +Success: Hello, dubbo at 2022-08-08T15:42:40.809 +Success: Hello, dubbo at 2022-08-08T15:42:40.812 +Success: Hello, dubbo at 2022-08-08T15:42:40.815 +Success: Hello, dubbo at 2022-08-08T15:42:40.818 +Success: Hello, dubbo at 2022-08-08T15:42:40.821 +Success: Hello, dubbo at 2022-08-08T15:42:40.823 +Success: Hello, dubbo at 2022-08-08T15:42:40.826 +Success: Hello, dubbo at 2022-08-08T15:42:40.828 +Success: Hello, dubbo at 2022-08-08T15:42:40.830 +Success: Hello, dubbo at 2022-08-08T15:42:40.834 +Blocked +Blocked +Blocked +Blocked +Blocked +``` + +> For more usage methods of Sentinel, please refer to: [Sentinel escorts Dubbo services](/zh/blog/2018/07/27/sentinel-为-dubbo-服务保驾护航/), [Sentinel official website](https://sentinelguard.io/zh-cn/index.html) \ No newline at end of file diff --git a/content/en/overview/tasks/ecosystem/transaction.md b/content/en/overview/tasks/ecosystem/transaction.md new file mode 100644 index 000000000000..103fae9eb246 --- /dev/null +++ b/content/en/overview/tasks/ecosystem/transaction.md @@ -0,0 +1,307 @@ +--- +type: docs +title: "Transaction Management" +linkTitle: "Transaction Management" +weight: 1 +description: "This example demonstrates how to implement transaction management of distributed Dubbo services through Seata to ensure data consistency." +--- + +## What is Seata +Seata is an open source distributed transaction solution dedicated to providing high-performance and easy-to-use distributed transaction services. Seata will provide users with AT, TCC, SAGA and XA transaction modes to create a one-stop distributed solution for users. + +## 1. Example architecture description +The user purchases commodity business, and the whole business includes 3 microservices: + +- Inventory service: deduction of the inventory quantity of a given item. +- Order service: Generate orders based on purchase requests. +- Account Services: deduction of the user account amount. + +![image.png](/imgs/docs3-v2/java-sdk/seata/transaction-1.png) + +### StorageService + +```java +public interface StorageService { + + /** + * Deducted storage quantity + */ + void deduct(String commodityCode, int count); +} +``` + +### OrderService + +```java +public interface OrderService { + + /** + * Create Order + */ + Order create(String userId, String commodityCode, int orderCount); +} +``` + +### AccountService + +```java +public interface AccountService { + + /** + * Borrow from user account + */ + void debit(String userId, int money); +} +``` + +## Two, the main business logic + +### BusinessService + +```java +public class BusinessServiceImpl implements BusinessService { + + private StorageService storageService; + + private OrderService orderService; + + /** + * Purchasing + */ + public void purchase(String userId, String commodityCode, int orderCount) { + // Deduct storage amount + storageService.deduct(commodityCode, orderCount); + // Create Order + orderService.create(userId, commodityCode, orderCount); + } +} +``` + +### StorageService + +```java +public class StorageServiceImpl implements StorageService { + + private JdbcTemplate jdbcTemplate; + + @Override + public void deduct(String commodityCode, int count) { + // Modify the database: deduct the amount of storage + jdbcTemplate.update("update storage_tbl set count = count - ? where commodity_code = ?", + new Object[]{count, commodityCode}); + } +} +``` + +### OrderService + +```java +public class OrderServiceImpl implements OrderService { + + private AccountService accountService; + + private JdbcTemplate jdbcTemplate; + + public Order create(String userId, String commodityCode, int orderCount) { + // calculate the amount + int orderMoney = calculate(commodityCode, orderCount); + + // The amount deducted from the user account + accountService.debit(userId, orderMoney); + + // Modify the database: create a new order + final Order order = new Order(); + order.userId = userId; + order.commodityCode = commodityCode; + order.count = orderCount; + order.money = orderMoney; + KeyHolder keyHolder = new GeneratedKeyHolder(); + jdbcTemplate. update(con -> { + PreparedStatement pst = con. prepareStatement( + "insert into order_tbl (user_id, commodity_code, count, money) values (?, ?, ?, ?)", + PreparedStatement. RETURN_GENERATED_KEYS); + pst.setObject(1, order.userId); + pst.setObject(2, order.commodityCode); + pst.setObject(3, order.count); + pst.setObject(4, order.money); + return pst; + }, keyHolder); + order.id = keyHolder.getKey().longValue(); + return order; + } +} +``` + +### AccountService + + +```java +public class AccountServiceImpl implements AccountService { + + private JdbcTemplate jdbcTemplate; + + @Override + public void debit(String userId, int money) { + // Modify the database: deduct the amount from the user account + jdbcTemplate.update("update account_tbl set money = money - ? where user_id = ?", new Object[]{money, userId}); + } +} +``` + +## 3. Quick start example + +### Step 1: Download the source code + +```shell script +git clone -b master https://github.com/apache/dubbo-samples.git +cd ./dubbo-samples-transaction/ +``` + +### Step 2: Start Seata-Server and MySQL through docker-compose + +In this example, we use docker-compose to quickly pull up services like seata-server and mysql. + +```bash +cd src/main/resources/docker +docker-compose up +``` + +### Step 3: Build use cases + +Execute the maven command to package the demo project + +```bash +mvn clean package +``` + +### Step 4: Start AccountService + +```java +java -classpath ./target/dubbo-samples-transaction-1.0-SNAPSHOT.jar org.apache.dubbo.samples.starter.DubboAccountServiceStarter +``` + +### Step 5: Start OrderService + +```java +java -classpath ./target/dubbo-samples-transaction-1.0-SNAPSHOT.jar org.apache.dubbo.samples.starter.DubboOrderServiceStarter +``` +### Step 6: Start StorageService + +```java +java -classpath ./target/dubbo-samples-transaction-1.0-SNAPSHOT.jar org.apache.dubbo.samples.starter.DubboStorageServiceStarter +``` + +### Step 7: Start BusinessService +```java +java -classpath ./target/dubbo-samples-transaction-1.0-SNAPSHOT.jar org.apache.dubbo.samples.starter.DubboBusinessTester +``` + +## 4. Example core process + +![image.png](/imgs/docs3-v2/java-sdk/seata/transaction-2.png) + +### Step 1: Modify the business code +Here only one line of annotation `@GlobalTransactional` is required to be written on the method of the business initiator: + +```java + @GlobalTransactional + public void purchase(String userId, String commodityCode, int orderCount) { +  … + } +``` + +### Step 2: Install the database + +- Requirements: MySQL (InnoDB storage engine). + +**Tips:** In fact, the 3 microservices in the example require 3 independent databases, but for convenience we use the same physical database and configure 3 logical connection strings. + +Change the database url, username and password in the following xml files + +dubbo-account-service.xml +dubbo-order-service.xml +dubbo-storage-service.xml + +```xml + + + +``` + +### Step 3: Create undo_log table for Seata + +`UNDO_LOG` This table is used in Seata's AT mode. + +```sql +-- Note that when the Seata version is upgraded to 0.3.0+, the normal index will be changed to a unique index. +CREATE TABLE `undo_log` ( + `id` bigint(20) NOT NULL AUTO_INCREMENT, + `branch_id` bigint(20) NOT NULL, + `xid` varchar(100) NOT NULL, + `context` varchar(128) NOT NULL, + `rollback_info` longblob NOT NULL, + `log_status` int(11) NOT NULL, + `log_created` datetime NOT NULL, + `log_modified` datetime NOT NULL, + `ext` varchar(100) DEFAULT NULL, + PRIMARY KEY (`id`), + UNIQUE KEY `ux_undo_log` (`xid`,`branch_id`) +) ENGINE=InnoDB AUTO_INCREMENT=1 DEFAULT CHARSET=utf8; +``` + +### Step 4: Create related business tables + +```sql + +DROP TABLE IF EXISTS `storage_tbl`; +CREATE TABLE `storage_tbl` ( + `id` int(11) NOT NULL AUTO_INCREMENT, + `commodity_code` varchar(255) DEFAULT NULL, + `count` int(11) DEFAULT 0, + PRIMARY KEY (`id`), + UNIQUE KEY (`commodity_code`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8; + + +DROP TABLE IF EXISTS `order_tbl`; +CREATE TABLE `order_tbl` ( + `id` int(11) NOT NULL AUTO_INCREMENT, + `user_id` varchar(255) DEFAULT NULL, + `commodity_code` varchar(255) DEFAULT NULL, + `count` int(11) DEFAULT 0, + `money` int(11) DEFAULT 0, + PRIMARY KEY (`id`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8; + + +DROP TABLE IF EXISTS `account_tbl`; +CREATE TABLE `account_tbl` ( + `id` int(11) NOT NULL AUTO_INCREMENT, + `user_id` varchar(255) DEFAULT NULL, + `money` int(11) DEFAULT 0, + PRIMARY KEY (`id`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8; +``` + +### Step 5: Start the Seata-Server service + +- Download the [server package](https://github.com/seata/seata/releases), unzip it. + +```shell +Usage: sh seata-server.sh(for linux and mac) or cmd seata-server.bat(for windows) [options] + Options: + --host, -h + The host to bind. + Default: 0.0.0.0 + --port, -p + The port to listen. + Default: 8091 + --storeMode, -m + log store mode: file, db + Default: file + --help + +e.g. + +sh seata-server.sh -p 8091 -h 127.0.0.1 -m file +``` \ No newline at end of file diff --git a/content/en/overview/tasks/kubernetes/_index.md b/content/en/overview/tasks/kubernetes/_index.md new file mode 100755 index 000000000000..ac88a582e0c9 --- /dev/null +++ b/content/en/overview/tasks/kubernetes/_index.md @@ -0,0 +1,38 @@ +--- +type: docs +title: "Kubernetes Deployment Solution" +linkTitle: "Kubernetes Deployment Solution" +description: "Demonstrate how to deploy Dubbo to Kubernetes and reuse Kubernetes Native Service." +weight: 2 +no_list: true +--- + +{{< blocks/section color="white" height="auto">}} +
+
+
+
+
+
+

+ API-SERVER +

+

Use API-SERVER as the registration center, deploy Dubbo application to Kubernetes and reuse Kubernetes Native Service example

+
+
+
+
+
+
+

+ Dubbo Mesh +

+

Through the Dubbo Control Plane, the details of service governance are shielded, while retaining the native ability to adapt to kubernetes, the decoupling of the data plane and kubernetes is realized from the architecture, and various problems caused by direct communication between the data plane and kubernetes are avoided.

For details, please refer to the Mesh solution section

+
+
+
+
+
+
+ +{{< /blocks/section >}} \ No newline at end of file diff --git a/content/en/overview/tasks/kubernetes/deploy-on-k8s.md b/content/en/overview/tasks/kubernetes/deploy-on-k8s.md new file mode 100644 index 000000000000..1e3340d1736b --- /dev/null +++ b/content/en/overview/tasks/kubernetes/deploy-on-k8s.md @@ -0,0 +1,321 @@ +--- +type: docs +title: "Deploying to Kubernetes" +linkTitle: "Native K8S Service based on API-SERVER" +weight: 2 +description: "This example demonstrates the usage example of deploying Dubbo application to Kubernetes and reusing Kubernetes Native Service directly using API-SERVER as the registration center. +The limitation of this example is that each Dubbo application needs to be granted permission to access specific resources of the API-SERVER. At the same time, direct access and monitoring of the API-SERVER is not a problem for small and medium clusters. +However, for larger-scale clusters, it may bring certain challenges to the stability of API-SERVER. In addition, you can consider deploying Dubbo applications to Kuberntes with the Dubbo control plane. +This solution does not need to grant the Dubbo application permission to access the API-SERVER, nor does it need to worry about the stability caused by the API-SERVER connecting too many data planes. " +--- + +You can follow the steps below to easily deploy the Dubbo service to the Kubernetes cluster. Check out the [full code sample address](https://github.com/apache/dubbo-samples/tree/master/3-extensions/registry /dubbo-samples-kubernetes) + +## 1 Overall Objective + +* Deploy Dubbo application to Kubernetes +* Realize service discovery based on Kubernetes built-in Service +* Connect Dubbo application to Kubernetes life cycle + +## 2 Basic process + +1. Create a Dubbo + Application ( [dubbo-samples-kubernetes](https://github.com/apache/dubbo-samples/tree/master/3-extensions/registry/dubbo-samples-kubernetes) ) +2. Build the container image and push it to the mirror warehouse ( [dubbo-demo example image](https://hub.docker.com/r/apache/dubbo-demo) ) +3. Deploy Dubbo Provider and Dubbo Consumer to Kubernetes respectively +4. Verify that service discovery and calling are normal + +## 3 detailed steps + +### 3.1 Environmental requirements + +Please ensure that the following environment is installed locally to provide container runtime, Kubernetes cluster and access tools + +* [Docker](https://www.docker.com/get-started/) +* [Minikube](https://minikube.sigs.k8s.io/docs/start/) +* [Kubectl](https://kubernetes.io/docs/tasks/tools/) +* [Kubens(optional)](https://github.com/ahmetb/kubectx) + +Start the local Kubernetes cluster with the following command + +```shell +minikube start +``` + +Check that the cluster is up and running with kubectl, and that kubectl is bound to the default local cluster + +```shell +kubectl cluster-info +``` + +### 3.2 Preconditions + +Since the sample Dubbo projects are all deployed in Pods and interact with API-SERVER, there are corresponding permission requirements. Here we create an independent ServiceAccount and bind the necessary Roles. All Dubbo Kubernetes later +All resources will use the newly created ServiceAccount here. + +Through the following commands, we have created an independent Namespace `dubbo-demo` and ServiceAccount `dubbo-sa`. + +```shell +# Initialize namespace and account +kubectl apply -f https://raw.githubusercontent.com/apache/dubbo-samples/master/dubbo-samples-kubernetes/dubbo-samples-apiserver-provider/src/main/resources/k8s/ServiceAccount.yml + +# switch namespace +kubens dubbo-demo +``` + +### 3.3 Deploy to Kubernetes + +#### 3.3.1 Deploy Provider + +```shell +# Deploy the Service +kubectl apply -f https://raw.githubusercontent.com/apache/dubbo-samples/master/dubbo-samples-kubernetes/dubbo-samples-apiserver-provider/src/main/resources/k8s/Service.yml + +# Deploy Deployment +kubectl apply -f https://raw.githubusercontent.com/apache/dubbo-samples/master/dubbo-samples-kubernetes/dubbo-samples-apiserver-provider/src/main/resources/k8s/Deployment.yml +``` + +The above command creates a Service named `dubbo-samples-apiserver-provider`, note that the service name here is the same as the dubbo application name in the project. + +Then Deployment deploys a 3-copy pod instance, and the Provider is started. +You can check the startup log with the following command. + +```shell +# View pod list +kubectl get pods -l app=dubbo-samples-apiserver-provider + +# View pod deployment logs +kubectl logs your-pod-id +``` + +#### 3.3.2 Deploy Consumer + +```shell +# Deploy the Service +kubectl apply -f https://raw.githubusercontent.com/apache/dubbo-samples/master/dubbo-samples-kubernetes/dubbo-samples-apiserver-consumer/src/main/resources/k8s/Service.yml + +# Deploy Deployment +kubectl apply -f https://raw.githubusercontent.com/apache/dubbo-samples/master/dubbo-samples-kubernetes/dubbo-samples-apiserver-consumer/src/main/resources/k8s/Deployment.yml +``` + +Deploying consumer and provider is the same, here also keep K8S Service and Dubbo consumer name consistent: dubbo-samples-apiserver-consumer. + +Check the startup log, the consumer completes the consumption of the provider service. + +```shell +# View pod list +kubectl get pods -l app=dubbo-samples-apiserver-consumer + +# View pod deployment logs +kubectl logs your-pod-id +``` + +You can see the log output as follows: + +```java +[22/04/22 01:10:24:024UTC]main INFO deploy.DefaultApplicationDeployer:[DUBBO]Dubbo Application[1.1](dubbo-samples-apiserver-consumer) is ready.,dubbo version:3.0.7,current host :172.17.0.6 + result: hello, Kubernetes Api Server +``` + +### 3.4 Modify the project and package it (can be skipped) + +The sample project and related images are ready, this section is only for users who need to modify the sample and see the deployment effect. Check here [full code sample address](https://github.com/apache/dubbo-samples/tree/master/3-extensions/registry/dubbo-samples-kubernetes) + +Set the Dubbo project to use Kubernetes as the registration center. Here, DEFAULT_MASTER_HOST specifies the default API-SERVER cluster address kubernetes.default.srv, and also specifies +namespace, trustCerts two parameters + +```properties +dubbo.application.name=dubbo-samples-apiserver-provider +dubbo.application.metadataServicePort=20885 +dubbo.registry.address=kubernetes://DEFAULT_MASTER_HOST?registry-type=service&duplicate=false&namespace=dubbo-demo&trustCerts=true +dubbo.protocol.name=dubbo +dubbo.protocol.port=20880 +dubbo.application.qosEnable=true +dubbo.application.qosAcceptForeignIp=true +dubbo.provider.token=true +``` + +If you want to package the image locally, you can use the jib-maven-plugin plugin to package the image + +```shell +# Package and push the image +mvn compile jib:build +``` + +> The Jib plugin will automatically package and publish the image. Note that for local development, you need to change the docker registry organization apache/dubbo-demo in the jib plug-in configuration to an organization with your own authority (including dubboteam in other kubernetes manifests to ensure that kubernetes deploys your own customized image) , if you encounter jib plug-in authentication problems, please refer to [corresponding link](https://github.com/GoogleContainerTools/jib/blob/master/docs/faq.md#what-should-i-do-when-the- registry-responds-with-unauthorized) to configure docker registry authentication information. +> You can specify `mvn compile jib:build -Djib.to.auth.username=x -Djib.to.auth.password=x -Djib.from.auth.username=x -Djib.from.auth directly on the command line .username=x`, or use docker-credential-helper. + +## 4 Best Practices + +TBD + +* rediness probe +* liveness probe +* ci/cd access to Skalfold + +## 5 Appendix k8s manifests + +ServiceAccount.yml + +```yaml +apiVersion: v1 +kind: Namespace +metadata: + name: dubbo-demo +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + namespace: dubbo-demo + name: dubbo-role +rules: + - apiGroups: [""] + resources: ["pods"] + verbs: ["get", "watch", "list", "update", "patch"] + - apiGroups: ["", "service.dubbo.apache.org"] + resources: ["services", "endpoints", "virtualservices", "destinationrules"] + verbs: ["get", "watch", "list"] +--- +apiVersion: v1 +kind: ServiceAccount +metadata: + name: dubbo-sa + namespace: dubbo-demo +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: RoleBinding +metadata: + name: dubbo-sa-bind + namespace: dubbo-demo +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: Role + name: dubbo-role +subjects: + - kind: ServiceAccount + name: dubbo-sa +``` + +Service.yml + +```yaml +apiVersion: v1 +kind: Service +metadata: + name: dubbo-samples-apiserver-provider + namespace: dubbo-demo +spec: + clusterIP: None + selector: + app: dubbo-samples-apiserver-provider + ports: + - protocol: TCP + port: 20880 + targetPort: 20880 +``` + +Deployment.yml + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: dubbo-samples-apiserver-provider + namespace: dubbo-demo +spec: + replicas: 3 + selector: + matchLabels: + app: dubbo-samples-apiserver-provider + template: + metadata: + labels: + app: dubbo-samples-apiserver-provider + spec: + serviceAccountName: dubbo-sa + containers: + - name: server + image: apache/dubbo-deemo:dubbo-samples-apiserver-provider_0.0.1 + ports: + - containerPort: 20880 + livenessProbe: + httpGet: + path: /live + port: 22222 + initialDelaySeconds: 5 + periodSeconds: 5 + readinessProbe: + httpGet: + path: /ready + port: 22222 + initialDelaySeconds: 5 + periodSeconds: 5 + startupProbe: + httpGet: + path: /startup + port: 22222 + failureThreshold: 30 + periodSeconds: 10 +``` + +Service.yml + +```yaml +apiVersion: v1 +kind: Service +metadata: + name: dubbo-samples-apiserver-consumer + namespace: dubbo-demo +spec: + clusterIP: None + selector: + app: dubbo-samples-apiserver-consumer + ports: + - protocol: TCP + port: 20880 + targetPort: 20880 +``` + +Deployment.yml + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: dubbo-samples-apiserver-consumer + namespace: dubbo-demo +spec: + replicas: 1 + selector: + matchLabels: + app: dubbo-samples-apiserver-consumer + template: + metadata: + labels: + app: dubbo-samples-apiserver-consumer + spec: + serviceAccountName: dubbo-sa + containers: + - name: server + image: apache/dubbo-demo:dubbo-samples-apiserver-consumer_0.0.1 + ports: + - containerPort: 20880 + livenessProbe: + httpGet: + path: /live + port: 22222 + initialDelaySeconds: 5 + periodSeconds: 5 + readinessProbe: + httpGet: + path: /ready + port: 22222 + initialDelaySeconds: 5 + periodSeconds: 5 + startupProbe: + httpGet: + path: /startup + port: 22222 + failureThreshold: 30 + periodSeconds: 10 +``` \ No newline at end of file diff --git a/content/en/overview/tasks/mesh/_index.md b/content/en/overview/tasks/mesh/_index.md new file mode 100755 index 000000000000..9f50664f02b3 --- /dev/null +++ b/content/en/overview/tasks/mesh/_index.md @@ -0,0 +1,61 @@ +--- +type: docs +title: "Mesh Deployment Solution" +linkTitle: "Mesh Deployment Solution" +description: "Demonstrates Dubbo Mesh solutions in various deployment forms, and how Dubbo Mesh helps users achieve smooth migration of architecture." +weight: 2 +no_list: true +--- + +{{< blocks/section color="white" height="auto">}} +
+
+
+
+
+
+

+ Istio + Sidecar + Thin SDK +

+

Demonstration of Dubbo3's Sidecar Mesh form, which can fully access Istio's service governance capabilities. This solution limits Dubbo3 application-level service discovery.

+
+
+
+
+
+
+

+ Istio + Proxyless +

+

The Dubbo3 Proxyless Mesh form without Sidecar can fully access the service management capability of Istio. This solution limits Dubbo3 application-level service discovery.

+
+
+
+
+
+
+

+ +

Dubbo Control Plane + Thin SDK (document construction)

+

+

+
+
+
+
+
+
+

+ +

Dubbo Control Plane + Proxyless (document construction)

+

+

+
+
+
+ +
+
+
+ +{{< /blocks/section >}} \ No newline at end of file diff --git a/content/en/overview/tasks/mesh/dubbo-mesh.md b/content/en/overview/tasks/mesh/dubbo-mesh.md new file mode 100644 index 000000000000..271ff4894d91 --- /dev/null +++ b/content/en/overview/tasks/mesh/dubbo-mesh.md @@ -0,0 +1,301 @@ +--- +type: docs +title: "Dubbo proxy mesh using Envoy & Istio" +linkTitle: "Sidecar mode" +weight: 1 +description: "This example demonstrates how to use Istio+Envoy's Service Mesh deployment mode to develop a Dubbo3 service. The Dubbo3 service uses Triple as the communication protocol. The communication process is intercepted by the Envoy data plane, and Dubbo is managed using the standard Istio traffic management capability." +--- + +By following the steps below, you can easily learn how to develop a Dubbo service that conforms to the Service Mesh architecture, deploy it to Kubernetes, and access Istio's traffic management system. Check here [Complete sample source code](https://github.com/apache/dubbo-samples/tree/master/3-extensions/registry/dubbo-samples-mesh-k8s) + +## 1 Overall Objective + +* Deploy Dubbo application to Kubernetes +* Istio automatically injects Envoy and implements traffic interception +* Traffic governance based on Istio rules + +## 2 Basic process and working principle + +This example demonstrates how to deploy an application developed by Dubbo under the Istio system to realize Envoy's automatic proxying of Dubbo services. The overall architecture of the example is shown in the figure below. + +![thinsdk](/imgs/v3/mesh/thinsdk-envoy.png) + +The steps you will need to complete the example are as follows: + +1. Create a Dubbo application ( [dubbo-samples-mesh-k8s](https://github.com/apache/dubbo-samples/tree/master/3-extensions/registry/dubbo-samples-mesh-k8s) ) +2. Build the container image and push it to the mirror warehouse ([the official image of this example](https://hub.docker.com/r/apache/dubbo-demo) ) +3. Deploy Dubbo Provider and Dubbo Consumer to Kubernetes respectively and verify that Envoy proxy injection is successful +4. Verify Envoy discovers the service address, normally intercepts RPC traffic and implements load balancing +5. Proportional traffic forwarding based on Istio VirtualService + +## 3 detailed steps + +### 3.1 Environmental requirements + +Please ensure that the following environment is installed locally to provide container runtime, Kubernetes cluster and access tools + +* [Docker](https://www.docker.com/get-started/) +* [Minikube](https://minikube.sigs.k8s.io/docs/start/) +* [Kubectl](https://kubernetes.io/docs/tasks/tools/) +* [Istio](https://istio.io/latest/docs/setup/getting-started/) +* [Kubens(optional)](https://github.com/ahmetb/kubectx) + +Start the local Kubernetes cluster with the following command + +```shell +minikube start +``` + +Check that the cluster is up and running with kubectl, and that kubectl is bound to the default local cluster + +```shell +kubectl cluster-info +``` + +### 3.2 Create an independent namespace and enable automatic injection + +Use the following command to create an independent Namespace `dubbo-demo` for the sample project, and enable sidecar automatic injection at the same time. + +```shell +# Initialize the namespace +kubectl apply -f https://raw.githubusercontent.com/apache/dubbo-samples/master/3-extensions/registry/dubbo-samples-mesh-k8s/deploy/Namespace.yml + +# switch namespace +kubens dubbo-demo + +# dubbo-demo enable automatic injection +kubectl label namespace dubbo-demo istio-injection=enabled + +``` + +### 3.3 Deploy to Kubernetes + +#### 3.3.1 Deploy Provider + +```shell +# Deploy the Service +kubectl apply -f https://raw.githubusercontent.com/apache/dubbo-samples/master/3-extensions/registry/dubbo-samples-mesh-k8s/deploy/provider/Service.yml + +# Deploy Deployment +kubectl apply -f https://raw.githubusercontent.com/apache/dubbo-samples/master/3-extensions/registry/dubbo-samples-mesh-k8s/deploy/provider/Deployment.yml +``` + +The above command creates a Service named `dubbo-samples-mesh-provider`, note that the service name here is the same as the dubbo application name in the project. + +Then the Deployment deploys a 2-copy pod instance, and the Provider is started. + +You can check the startup log with the following command. + +```shell +# View pod list +kubectl get pods -l app=dubbo-samples-mesh-provider + +# View pod deployment logs +kubectl logs your-pod-id +``` + +At this time, there should be a dubbo provider container instance and an Envoy Sidecar container instance in the pod. + +#### 3.3.2 Deploy Consumer + +```shell +# Deploy the Service +kubectl apply -f https://raw.githubusercontent.com/apache/dubbo-samples/master/3-extensions/registry/dubbo-samples-mesh-k8s/deploy/consumer/Service.yml + +# Deploy Deployment +kubectl apply -f https://raw.githubusercontent.com/apache/dubbo-samples/master/3-extensions/registry/dubbo-samples-mesh-k8s/deploy/consumer/Deployment.yml +``` + +Deploying consumer and provider is the same, here also keep K8S Service and Dubbo consumer application name (in [dubbo.properties](https://github.com/apache/dubbo-samples/blob/master/3-extensions/registry //dubbo-samples-mesh-k8s/dubbo-samples-mesh-consumer/src/main/resources/spring/dubbo-consumer.properties) consistent: `dubbo.application.name=dubbo-samples-mesh- consumer`. + +> The provider service (application) name of consumption is also specified in the Dubbo Consumer service statement `@DubboReference(version = "1.0.0", providedBy = "dubbo-samples-mesh-provider", lazy = true)` + +### 3.4 Check the normal communication between Provider and Consumer + +After performing step 3.3, check the startup log to see that the consumer has completed consumption of the provider service. + +```shell +# View pod list +kubectl get pods -l app=dubbo-samples-mesh-consumer + +# View pod deployment logs +kubectl logs your-pod-id + +# View pod isitio-proxy logs +kubectl logs your-pod-id -c istio-proxy +``` + +You can see that the consumer pod log output is as follows (the Triple protocol is load balanced by the Envoy proxy): + +```bash +===================== dubbo invoke 0 end ====================== +[10/08/22 07:07:36:036 UTC] main INFO action.GreetingServiceConsumer: consumer Unary reply <-message: "hello, service mesh, response from provider-v1: 172.18.96.22:50052, client: 172.18. 96.22, local: dubbo-samples-mesh-provider, remote: null, isProviderSide: true" + +===================== dubbo invoke 1 end ====================== +[10/08/22 07:07:42:042 UTC] main INFO action.GreetingServiceConsumer: consumer Unary reply <-message: "hello, service mesh, response from provider-v1: 172.18.96.18:50052, client: 172.18. 96.18, local: dubbo-samples-mesh-provider, remote: null, isProviderSide: true" + +``` + +The consumer istio-proxy log output is as follows: + +```shell +[2022-07-15T05:35:14.418Z] "POST /org.apache.dubbo.samples.Greeter/greet HTTP/2" 200 +- via_upstream - "-" 19 160 2 1 "-" "-" "6b8a5a03-5783-98bf-9bee-f93ea6e3d68e" +"dubbo-samples-mesh-provider:50052" "172.17.0.4:50052" +outbound|50052||dubbo-samples-mesh-provider.dubbo-demo.svc.cluster.local 172.17.0.7:52768 10.101.172.129:50052 172.17.0.7:38488 - default +``` + +You can see the provider pod log output as follows: + +```shell +[10/08/22 07:08:47:047 UTC] tri-protocol-50052-thread-8 INFO impl.GreeterImpl: Server test dubbo tri mesh received greet request name: "service mesh" + +[10/08/22 07:08:57:057 UTC] tri-protocol-50052-thread-9 INFO impl.GreeterImpl: Server test dubbo tri mesh received greet request name: "service mesh" +``` + +The log output of provider istio-proxy is as follows: + +```shell +[2022-07-15T05:25:34.061Z] "POST /org.apache.dubbo.samples.Greeter/greet HTTP/2" 200 +- via_upstream - "-" 19 162 1 1 "-" "-" "201e6976-da10-96e1-8da7-ad032e58db47" +"dubbo-samples-mesh-provider:50052" "172.17.0.10:50052" + inbound|50052|| 127.0.0.6:47013 172.17.0.10:50052 172.17.0.7:60244 + outbound_.50052_._.dubbo-samples-mesh-provider.dubbo-demo.svc.cluster.local default +``` + +### 3.5 Traffic Governance - VirtualService implements proportional traffic forwarding + +Deploy the v2 version of the demo provider +```shell +kubectl apply -f https://raw.githubusercontent.com/apache/dubbo-samples/master/3-extensions/registry/dubbo-samples-mesh-k8s/deploy/provider/Deployment-v2.yml +``` + +Set VirtualService and DestinationRule, and observe that traffic is directed to provider v1 and provider v2 respectively in a ratio of 4:1. +```shell +kubectl apply -f https://raw.githubusercontent.com/apache/dubbo-samples/master/3-extensions/registry/dubbo-samples-mesh-k8s/deploy/traffic/virtual-service.yml +``` + +From the log output of the consumer side, observe the traffic distribution effect as shown in the figure below: + +```java +===================== dubbo invoke 100 end ====================== +[10/08/22 07:15:58:058 UTC] main INFO action.GreetingServiceConsumer: consumer Unary reply <-message: "hello, service mesh, response from provider-v1: 172.18.96.18:50052, client: 172.18. 96.18, local: dubbo-samples-mesh-provider, remote: null, isProviderSide: true" + +===================== dubbo invoke 101 end ====================== +[10/08/22 07:16:03:003 UTC] main INFO action.GreetingServiceConsumer: consumer Unary reply <-message: "hello, service mesh, response from provider-v1: 172.18.96.22:50052, client: 172.18. 96.22, local: dubbo-samples-mesh-provider, remote: null, isProviderSide: true" + +===================== dubbo invoke 102 end ====================== +[10/08/22 07:16:08:008 UTC] main INFO action.GreetingServiceConsumer: consumer Unary reply <-message: "hello, service mesh, response from provider-v1: 172.18.96.18:50052, client: 172.18. 96.18, local: dubbo-samples-mesh-provider, remote: null, isProviderSide: true" + +===================== dubbo invoke 103 end ====================== +[10/08/22 07:16:13:013 UTC] main INFO action.GreetingServiceConsumer: consumer Unary reply <-message: "hello, service mesh, response from provider-v2: 172.18.96.6:50052, client: 172.18. 96.6, local: dubbo-samples-mesh-provider, remote: null, isProviderSide: true" + +===================== dubbo invoke 104 end ====================== +[10/08/22 07:16:18:018 UTC] main INFO action.GreetingServiceConsumer: consumer Unary reply <-message: "hello, service mesh, response from provider-v1: 172.18.96.22:50052, client: 172.18. 96.22, local: dubbo-samples-mesh-provider, remote: null, isProviderSide: true" + +===================== dubbo invoke 105 end ====================== +[10/08/22 07:16:24:024 UTC] main INFO action.GreetingServiceConsumer: consumer Unary reply <-message: "hello, service mesh, response from provider-v1: 172.18.96.18:50052, client: 172.18. 96.18, local: dubbo-samples-mesh-provider, remote: null, isProviderSide: true" + +===================== dubbo invoke 106 end ====================== +[10/08/22 07:16:29:029 UTC] main INFO action.GreetingServiceConsumer: consumer Unary reply <-message: "hello, service mesh, response from provider-v1: 172.18.96.22:50052, client: 172.18. 96.22, local: dubbo-samples-mesh-provider, remote: null, isProviderSide: true" + +===================== dubbo invoke 107 end ====================== +[10/08/22 07:16:34:034 UTC] main INFO action.GreetingServiceConsumer: consumer Unary reply <-message: "hello, service mesh, response from provider-v1: 172.18.96.18:50052, client: 172.18. 96.18, local: dubbo-samples-mesh-provider, remote: null, isProviderSide: true" + +===================== dubbo invoke 108 end ====================== +[10/08/22 07:16:39:039 UTC] main INFO action.GreetingServiceConsumer: consumer Unary reply <-message: "hello, service mesh, response from provider-v1: 172.18.96.22:50052, client: 172.18. 96.22, local: dubbo-samples-mesh-provider, remote: null, isProviderSide: true" + +===================== dubbo invoke 109 end ====================== +[10/08/22 07:16:44:044 UTC] main INFO action.GreetingServiceConsumer: consumer Unary reply <-message: "hello, service mesh, response from provider-v1: 172.18.96.18:50052, client: 172.18. 96.18, local: dubbo-samples-mesh-provider, remote: null, isProviderSide: true" + + +``` + +### 3.6 View dashboard + +See [How to start the dashboard](https://istio.io/latest/docs/setup/getting-started/#dashboard) on the Istio official website. + +## 4 Modified Example + +> 1. Modifying the example is not a necessary step, this section is for readers who want to adjust the code and see the deployment effect. +> 2. Note that the project source code storage path must be in English, otherwise protobuf compilation will fail. + +Modify Dubbo Provider configuration `dubbo-provider.properties` + +```properties +# provider +dubbo.application.name=dubbo-samples-mesh-provider +dubbo.application.metadataServicePort=20885 +dubbo.registry.address=N/A +dubbo.protocol.name=tri +dubbo.protocol.port=50052 +dubbo.application.qosEnable=true +# In order for the Kubernetes cluster to access the probe normally, it is necessary to enable QOS to allow remote access, which may bring security Risk, please carefully evaluate before opening +dubbo.application.qosAcceptForeignIp=true +``` + +Modify Dubbo Consumer configuration `dubbo-consumer.properties` + +```properties +# consumer +dubbo.application.name=dubbo-samples-mesh-consumer +dubbo.application.metadataServicePort=20885 +dubbo.registry.address=N/A +dubbo.protocol.name=tri +dubbo.protocol.port=20880 +dubbo.consumer.timeout=30000 +dubbo.application.qosEnable=true +# In order for the Kubernetes cluster to access the probe normally, it is necessary to enable QOS to allow remote access. This operation may bring security risks. Please evaluate it carefully before opening it +dubbo.application.qosAcceptForeignIp=true +# Flag to enable mesh sidecar proxy mode +dubbo.consumer.meshEnable=true +``` + +After completing the code modification, package the image through the Dockerfile provided by the project + +```shell +# Package and push the image +mvn compile jib:build +``` + +> The Jib plugin will automatically package and publish the image. Note that for local development, you need to change the docker registry organization apache/dubbo-demo in the jib plug-in configuration to an organization with your own authority (including dubboteam in other kubernetes manifests to ensure that kubernetes deploys your own customized image) , if you encounter jib plug-in authentication problems, please refer to [corresponding link](https://github.com/GoogleContainerTools/jib/blob/master/docs/faq.md#what-should-i-do-when-the- registry-responds-with-unauthorized) to configure docker registry authentication information. +> You can specify `mvn compile jib:build -Djib.to.auth.username=x -Djib.to.auth.password=x -Djib.from.auth.username=x -Djib.from.auth directly on the command line .username=x`, or use docker-credential-helper. + +## 5 Common commands + +```shell +# dump current Envoy configs +kubectl exec -it ${your pod id} -c istio-proxy curl http://127.0.0.1:15000/config_dump > config_dump + +# Enter the istio-proxy container +kubectl exec -it ${your pod id} -c istio-proxy -- /bin/bash + +# View container logs +kubectl logs ${your pod id} -n ${your namespace} + +kubectl logs ${your pod id} -n ${your namespace} -c istio-proxy + +# Enable automatic sidecar injection +kubectl label namespace ${your namespace} istio-injection=enabled --overwrite + +# Turn off automatic sidecar injection +kubectl label namespace ${your namespace} istio-injection=disabled --overwrite +``` + +## 6 Notes + +1. In the example, both the producer and the consumer belong to the same namespace; if you need to call a provider of a different namespace, you need to configure it as follows (**dubbo version>=3.1.2**): + +Annotation method: +```java + @DubboReference(providedBy = "istio-demo-dubbo-producer", providerPort = 20885, providerNamespace = "istio-demo") + +``` +xml way +```xml + +``` \ No newline at end of file diff --git a/content/en/overview/tasks/mesh/proxyless.md b/content/en/overview/tasks/mesh/proxyless.md new file mode 100644 index 000000000000..cc652c79853e --- /dev/null +++ b/content/en/overview/tasks/mesh/proxyless.md @@ -0,0 +1,270 @@ +--- +type: docs +title: "Istio + Proxyless" +linkTitle: "Proxyless mode" +weight: 2 +description: "" +--- + +Proxyless mode means that Dubbo communicates directly with Istiod, and implements service discovery and service governance capabilities through the xDS protocol. +In this example, a simple example will be used to demonstrate how to use the Proxyless mode. + +[Sample Address](https://github.com/apache/dubbo-samples/tree/master/3-extensions/registry/dubbo-samples-xds) + +## code structure + +This section mainly introduces the code structure of the example used in this article. By imitating the relevant configuration in this example and modifying the existing project code, the existing project can quickly run in Proxyless Mesh mode. + +### 1. Interface definition + +In order to make the example simple enough, a simple interface definition is used here, and only the parameters are spliced ​​to be returned. + +```java +public interface GreetingService { + String sayHello(String name); +} +``` + +### 2. Interface implementation + +```java +@DubboService(version = "1.0.0") +public class AnnotatedGreetingService implements GreetingService { + @Override + public String sayHello(String name) { + System.out.println("greeting service received: " + name); + return "hello, " + name + "! from host: " + NetUtils. getLocalHost(); + } +} +``` + +### 3. Client subscription method + +**Because the native xDS protocol cannot support the mapping from interface to application name, it is necessary to configure the `providedBy` parameter to mark which application this service comes from. ** + +In the future, we will realize automatic [service mapping](/en/docs3-v2/java-sdk/concepts-and-architecture/service-discovery/) relationship acquisition based on the control plane of Dubbo Mesh, and there will be no need for independent configuration parameters at that time. Dubbo can be run under the Mesh system, so stay tuned. + +```java +@Component("annotated Consumer") +public class GreetingServiceConsumer { + @DubboReference(version = "1.0.0", providedBy = "dubbo-samples-xds-provider") + private GreetingService greetingService; + public String doSayHello(String name) { + return greetingService.sayHello(name); + } +} +``` + +### 4. Server configuration + +The server configuration registration center is the address of istio, and the protocol is xds. + +We recommend configuring `protocol` to be the tri protocol (fully compatible with the grpc protocol) for a better experience in the istio system. + +In order to make Kubernetes aware of the state of the application, it is necessary to configure `qosAcceptForeignIp` parameter so that Kubernetes can obtain the correct application state, [alignment lifecycle](/en/docs3-v2/java-sdk/advanced-features-and-usage/ others/dubbo-kubernetes-probe/). + +```properties +dubbo.application.name=dubbo-samples-xds-provider +dubbo.application.metadataServicePort=20885 +dubbo.registry.address=xds://istiod.istio-system.svc:15012 +dubbo.protocol.name=tri +dubbo.protocol.port=50052 +dubbo.application.qosAcceptForeignIp=true +``` + +### 5. Client Configuration + +The client configuration registration center is the address of istio, and the protocol is xds. + +```properties +dubbo.application.name=dubbo-samples-xds-consumer +dubbo.application.metadataServicePort=20885 +dubbo.registry.address=xds://istiod.istio-system.svc:15012 +dubbo.application.qosAcceptForeignIp=true +``` + +## Quick start + +### Step 1: Build the Kubernetes environment + +Currently Dubbo only supports Mesh deployment in the Kubernetes environment, so you need to build the Kubernetes environment before running and starting this example. + +Build reference documents: + +> [minikube(https://kubernetes.io/zh-cn/docs/tutorials/hello-minikube/)](https://kubernetes.io/zh-cn/docs/tutorials/hello-minikube/) +> +> [kubeadm(https://kubernetes.io/zh-cn/docs/setup/production-environment/tools/)](https://kubernetes.io/zh-cn/docs/setup/production-environment/tools /) +> +> [k3s(https://k3s.io/)](https://k3s.io/) + +### Step 2: Build the Istio environment + +Build the Istio environment reference document: + +[Istio Installation Documentation (https://istio.io/latest/docs/setup/getting-started/)](https://istio.io/latest/docs/setup/getting-started/) + +Note: When installing Istio, you need to enable [first-party-jwt support](https://istio.io/latest/docs/ops/best-practices/security/#configure-third-party-service-account- tokens) (add the parameter `--set values.global.jwtPolicy=first-party-jwt` when using the `istioctl` tool to install)**, otherwise it will cause the problem of client authentication failure. + +Attached installation command reference: + +```bash +curl -L https://istio.io/downloadIstio | sh - +cd istio-1.xx.x +export PATH=$PWD/bin:$PATH +istioctl install --set profile=demo --set values.global.jwtPolicy=first-party-jwt -y +``` + +### Step 3: Pull the code and build + +```bash +git clone https://github.com/apache/dubbo-samples.git +cd dubbo-samples/dubbo-samples-xds +mvn clean package -DskipTests +``` + +### Step 4: Build the image + +Since Kubernetes adopts containerized deployment, the code needs to be packaged in a mirror before deployment. + +```bash +cd ./dubbo-samples-xds-provider/ +# dubbo-samples-xds/dubbo-samples-xds-provider/Dockerfile +docker build -t apache/dubbo-demo:dubbo-samples-xds-provider_0.0.1 . +cd ../dubbo-samples-xds-consumer/ +# dubbo-samples-xds/dubbo-samples-xds-consumer/Dockerfile +docker build -t apache/dubbo-demo:dubbo-samples-xds-consumer_0.0.1 . +cd ../ +``` + +### Step 5: Create namespace + +```bash +# Initialize the namespace +kubectl apply -f https://raw.githubusercontent.com/apache/dubbo-samples/master/dubbo-samples-xds/deploy/Namespace.yml + +# switch namespace +kubens dubbo-demo +``` + +### Step 6: Deploy the container + +```bash +cd ./dubbo-samples-xds-provider/src/main/resources/k8s +# dubbo-samples-xds/dubbo-samples-xds-provider/src/main/resources/k8s/Deployment.yml +# dubbo-samples-xds/dubbo-samples-xds-provider/src/main/resources/k8s/Service.yml +kubectl apply -f Deployment.yml +kubectl apply -f Service.yml +cd ../../../../../dubbo-samples-xds-consumer/src/main/resources/k8s +# dubbo-samples-xds/dubbo-samples-xds-consumer/src/main/resources/k8s/Deployment.yml +kubectl apply -f Deployment.yml +cd ../../../../../ +``` + +Looking at the log of the consumer, you can observe the following log: +``` +result: hello, xDS Consumer! from host: 172.17.0.5 +result: hello, xDS Consumer! from host: 172.17.0.5 +result: hello, xDS Consumer! from host: 172.17.0.6 +result: hello, xDS Consumer! from host: 172.17.0.6 +``` + +## common problem + +1. Configure a separate Istio cluster `clusterId` + +Usually the `clusterId` of Istio under the Kubernetes system is `Kubernetes`, if you are using a self-built istio production cluster or a cluster provided by a cloud vendor, you may need to configure `clusterId`. + +Configuration method: Specify the `ISTIO_META_CLUSTER_ID` environment variable as the desired `clusterId`. + +Reference configuration: +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: dubbo-samples-xds-consumer +spec: + selector: + matchLabels: + demo: consumer + replicas: 2 + template: + metadata: + labels: + demo: consumer + spec: + containers: + - env: + - name: ISTIO_META_CLUSTER_ID + value: Kubernetes + name: dubbo-samples-xds-provider + image: xxx +``` + +How to get `clusterId`: +> kubectl describe pod -n istio-system istiod-58b4f65df9-fq2ks +> Read the value of `CLUSTER_ID` in the environment variable + +2. Istio authentication failed + +Since the current Dubbo version does not support istio's `third-party-jwt` authentication, it is necessary to configure `jwtPolicy` to `first-party-jwt`. + +3. providedBy + +Since the current Dubbo version is limited by the communication model of istio and cannot obtain the application name corresponding to the interface, it is necessary to configure the `providedBy` parameter to mark which application the service comes from. +In the future, we will realize automatic [service mapping](/en/docs3-v2/java-sdk/concepts-and-architecture/service-discovery/) relationship acquisition based on the control plane of Dubbo Mesh, and there will be no need for independent configuration parameters at that time. Dubbo can be run under the Mesh system, so stay tuned. + +4. protocol name + +In Proxyless mode, application-level service discovery uses `Kubernetes Native Service` for application service discovery, but due to the limitation of istio, it currently only supports traffic interception and forwarding of `http` protocol and `grpc` protocol, so `Kubernetes Service` is configured in When you need to specify the `spec.ports.name` property to start with `http` or `grpc`. +Therefore we recommend using the triple protocol (fully compatible with the grpc protocol). Here, even if `name` is configured to start with `grpc`, it is actually a `dubbo` protocol that can also perform normal service discovery, but it affects the function of traffic routing. + +Reference configuration: +```yaml +apiVersion: v1 +kind: Service +metadata: + name: dubbo-samples-xds-provider +spec: + clusterIP: None + selector: + demo: provider + ports: + - name: grpc-tri + protocol: TCP + port: 50052 + targetPort: 50052 +``` + +5. metadataServicePort + +Since the metadata discovered by Dubbo 3 application-level services cannot be obtained from istio, it is necessary to use the service introspection mode. This requires that the port of `Dubbo MetadataService` is unified in the whole cluster. + +Reference configuration: +```properties +dubbo.application.metadataServicePort=20885 +``` + +In the future, we will realize automatic acquisition of [service metadata](/en/docs3-v2/java-sdk/concepts-and-architecture/service-discovery/) based on the control plane of Dubbo Mesh, and no independent configuration parameters will be required at that time. Dubbo can be run under the Mesh system, so stay tuned. + +6. qosAcceptForeignIp + +Due to the limitations of the working principle of the Kubernetes probe detection mechanism, the originator of the detection request is not `localhost`, so you need to configure the `qosAcceptForeignIp` parameter to enable global access. + +```properties +dubbo.application.qosAcceptForeignIp=true +``` + +Note: There are dangerous commands on the qos port, please evaluate the security of the network first. Even if the qos is not open, it only affects the inability of Kubernetes to obtain the life cycle status of Dubbo. + +7. Do not need to enable injection + +In Proxyless mode, the pod does not need to enable envoy injection. Please make sure that there is no `istio-injection=enabled` label in the namespace. + +8. Plain text connection istiod + +In Proxyless mode, connect to istiod through ssl by default, and also support connecting to istiod through clear text. + +Plain text connection reference configuration: +```properties +dubbo.registry.secure=plaintext +``` \ No newline at end of file diff --git a/content/en/overview/tasks/migration/2to3.md b/content/en/overview/tasks/migration/2to3.md new file mode 100644 index 000000000000..25d758212b5d --- /dev/null +++ b/content/en/overview/tasks/migration/2to3.md @@ -0,0 +1,44 @@ +--- +type: docs +title: "Upgrade to Dubbo3" +linkTitle: "Upgrade to Dubbo3" +weight: 1 +description: "Quickly understand the upgrade steps and compatibility of Dubbo 3" +--- + +** Upgrade directly to Dubbo 3.0 without changing any code. ** + +At the beginning of the design and development of version 3.0, we set the goal of being compatible with older versions of Dubbo users (2.5, 2.6, 2.7). Therefore, the upgrade process to version 3.0 will be completely transparent, users do not need to do any business transformation, and the behavior of the framework after upgrading to version 3.x will remain completely consistent with version 2.x. + +```xml + + org.apache.dubbo + dubbo + 3.0.10 + +``` + + +But also note that the transparent upgrade is only the first step towards 3.0, because "consistent framework behavior" means that users will not be able to experience the new features of 3.0. **If you want to enable the new features brought by 3.0, users need to make some modifications. We call this process migration, which is an on-demand process. ** + + + +Therefore, for legacy users, there are two different migration paths: + +* **In two steps, first promote business upgrade to version 3.0 in compatibility mode (no modification required), and then enable new features on demand at certain times (modification on demand);** +* **The upgrade and migration are completed synchronously. When the business is upgraded to version 3.0, the transformation is completed and new features are enabled;** + + + +The new features provided by Dubbo 3.0 include: + +* ** New address discovery model (application-level service discovery). ** + * See [Application-Level Service Discovery Migration Samples](/en/docs3-v2/java-sdk/upgrades-and-compatibility/service-discovery/service-discovery-samples/). + * See [Migration steps for application-level service discovery](/en/docs3-v2/java-sdk/upgrades-and-compatibility/service-discovery/migration-service-discovery/) + * See [Description of application-level service discovery address migration rules](/en/docs3-v2/java-sdk/upgrades-and-compatibility/service-discovery/service-discovery-rule/) +* **The next generation of the HTTP/2-based Triple protocol. ** + * See [Triple Protocol Migration Steps](/en/docs3-v2/java-sdk/upgrades-and-compatibility/migration-triple/) + * See [Triple protocol usage](/en/docs3-v2/java-sdk/reference-manual/protocol/triple/guide/) + * See [Triple Protocol Design and Implementation](/en/docs3-v2/java-sdk/reference-manual/protocol/triple/overview/). +* **Unified routing rules. ** + * See [Design and Implementation of Unified Routing Rules](/en/docs3-v2/java-sdk/advanced-features-and-usage/traffic/mesh-style/) \ No newline at end of file diff --git a/content/en/overview/tasks/migration/_index.md b/content/en/overview/tasks/migration/_index.md new file mode 100755 index 000000000000..e418c7082649 --- /dev/null +++ b/content/en/overview/tasks/migration/_index.md @@ -0,0 +1,48 @@ +--- +type: docs +title: "How to smoothly migrate to the new functions of Dubbo3" +linkTitle: "Migrate to Dubbo3" +description: "Demonstrate how to migrate to Dubbo3 with minimal cost and enable various new features." +weight: 5 +no_list: true +--- + +{{< blocks/section color="white" height="auto">}} +
+
+
+
+
+
+

+ Smooth upgrade to Dubbo3 +

+

Smoothly upgrade to Dubbo3 version.

+
+
+
+
+
+
+

+ Migrate to Dubbo3 application-level service discovery +

+

Migrate to Dubbo3 application-level service discovery.

+
+
+
+
+
+
+

+ Migrate to Triple Protocol +

+

Migrate to Dubbo3 Triple protocol

+
+
+
+
+
+
+ +{{< /blocks/section >}} \ No newline at end of file diff --git a/content/en/overview/tasks/migration/migration-triple.md b/content/en/overview/tasks/migration/migration-triple.md new file mode 100644 index 000000000000..d3474234d2e2 --- /dev/null +++ b/content/en/overview/tasks/migration/migration-triple.md @@ -0,0 +1,38 @@ +--- +type: docs +linkTitle: "Triple Protocol" +title: "Guide to Migrating Dubbo Protocol to Triple Protocol" +weight: 2 +description: "Triple Protocol Migration Guide" +--- + +## Triple Introduction + +For the format and principle of the `Triple` protocol, please refer to [RPC Communication Protocol](/en/docs3-v2/java-sdk/reference-manual/protocol/triple/overview/) + +According to the goals of Triple design, the `Triple` protocol has the following advantages: + +- Capable of cross-language interaction. Both the traditional multi-language and multi-SDK mode and the Mesh cross-language mode require a more general and scalable data transmission protocol. +- Provide a more complete request model. In addition to supporting the traditional Request/Response model (Unary one-way communication), it also supports Stream (streaming communication) and Bidirectional (two-way communication). +- Easy to expand, high penetration, including but not limited to Tracing / Monitoring and other support, should also be recognized by devices at all levels, gateway facilities, etc. can identify data packets, friendly to Service Mesh deployment, and reduce the difficulty of understanding for users. +- Fully compatible with grpc, the client/server can communicate with the native grpc client. +- Components in the existing grpc ecosystem can be reused to meet cross-language, cross-environment, and cross-platform intercommunication requirements in cloud-native scenarios. + +For Dubbo users currently using other protocols, the framework provides migration capabilities compatible with existing serialization methods. Without affecting existing online businesses, the cost of migrating protocols is almost zero. + +Dubbo users who need to add new connection to Grpc service can directly use the Triple protocol to achieve the connection, and do not need to introduce the grpc client separately to complete it. Not only can the existing Dubbo ease of use be retained, but also the complexity of the program and the development and maintenance can be reduced. Cost, it can be connected to the existing ecology without additional adaptation and development. + +For Dubbo users who need gateway access, the Triple protocol provides a more native way to make gateway development or use open source grpc gateway components easier. The gateway can choose not to parse the payload, which greatly improves the performance. When using the Dubbo protocol, the language-related serialization method is a big pain point for the gateway, and the traditional HTTP-to-Dubbo method is almost powerless for cross-language serialization. At the same time, since Triple's protocol metadata is stored in the request header, the gateway can easily implement customized requirements, such as routing and current limiting. + + +## Dubbo2 protocol migration process + +Dubbo2 users use dubbo protocol + custom serialization, such as hessian2 to complete remote calls. + +By default, Grpc only supports Protobuf serialization, and it cannot support multi-parameter and method overloading in the Java language. + +At the beginning of Dubbo3, one goal was to be perfectly compatible with Dubbo2. Therefore, in order to ensure the smooth upgrade of Dubbo2, the Dubbo framework has done a lot of work to ensure that the upgrade is seamless. Currently, the default serialization is consistent with Dubbo2 as `hessian2`. + +**So, if you decide to upgrade to Dubbo3's `Triple` protocol, you only need to modify the protocol name in the configuration to `tri` (note: not triple). ** + +For more instructions on using the `Triple` protocol, please refer to [Triple Protocol Migration Guide](/en/docs3-v2/java-sdk/upgrades-and-compatibility/migration-triple/). \ No newline at end of file diff --git a/content/en/overview/tasks/migration/service-discovery-samples.md b/content/en/overview/tasks/migration/service-discovery-samples.md new file mode 100644 index 000000000000..c93c33737fc7 --- /dev/null +++ b/content/en/overview/tasks/migration/service-discovery-samples.md @@ -0,0 +1,78 @@ +--- +type: docs +title: "Dubbo3 application-level service discovery" +linkTitle: "Application-Level Service Discovery" +weight: 5 +description: "This article specifically explains how users can quickly enable new features of application-level service discovery after upgrading to Dubbo 3.0." +--- + +Application-level service discovery is a protocol for service discovery between applications. Therefore, to use application-level service discovery, both the consumer and the server must be upgraded to Dubbo 3.0 and new features enabled (enabled by default) to use application-level service discovery in the link. Take advantage of application-level service discovery. +## Open method +## Server +After the application is upgraded to Dubbo 3.0, the server will automatically enable the interface-level + application-level dual registration function, and the developer does not need to modify any configuration by default + +### Consumer side +After the application is upgraded to Dubbo 3.0, the consumer side automatically starts the interface-level + application-level dual subscription function, and the developer does not need to modify any configuration by default. It is recommended that after the server is upgraded to Dubbo 3.0 and the application-level registration is enabled, configure the consumer end to close the interface-level subscription through rules to release the corresponding memory space. + +## Detailed description +### Server configuration + +1. Global switch + +Application configuration (can be specified by configuration file or -D) `dubbo.application.register-mode` enables the global registration switch for instance (only register application level) and all (both interface level and application level registration). After configuring this switch , by default, application-level addresses will be registered with all registries for service discovery on the consumer side. +> Example: [https://github.com/apache/dubbo-samples/blob/master/dubbo-samples-cloud-native/dubbo-servicediscovery-migration/dubbo-servicediscovery-migration-provider2/src/main/resources/ dubbo.properties](https://github.com/apache/dubbo-samples/blob/master/2-advanced/dubbo-samples-cloud-native/dubbo-servicediscovery-migration/dubbo-servicediscovery-migration-provider2/src /main/resources/dubbo.properties) + +``` +# double registration +dubbo.application.register-mode=all +``` +``` +# Application-level registration only +dubbo.application.register-mode=instance +``` + +2. Registration center address parameter configuration + +Registry-type=service can be configured on the address of the registry to display the registry that specifies the registry as application-level service discovery, and the registry with this configuration will only perform application-level service discovery. +> Example: [https://github.com/apache/dubbo-samples/blob/master/dubbo-samples-cloud-native/dubbo-demo-servicediscovery-xml/servicediscovery-provider/src/main/resources/spring/ dubbo-provider.xml](https://github.com/apache/dubbo-samples/blob/master/2-advanced/dubbo-samples-cloud-native/dubbo-demo-servicediscovery-xml/servicediscovery-provider/src /main/resources/spring/dubbo-provider.xml) + +```xml + +``` +### Consumer Subscription Mode + +FORCE_INTERFACE: only interface-level subscription, the behavior is consistent with Dubbo 2.7 and previous versions. +APPLICATION_FIRST: interface level + application level multi-subscription, if the application level can subscribe to the address, use the application level subscription, if the address cannot be subscribed, use the interface level subscription, so as to ensure the greatest compatibility during the migration process. (Note: Due to the simultaneous subscription behavior, the memory usage in this mode will increase to a certain extent, so after all servers are upgraded to Dubbo 3.0, it is recommended to migrate to FORCE_APPLICATION mode to reduce memory usage) +FORCE_APPLICATION: Only application-level subscriptions will only use the new service discovery model. + +### Consumer configuration + +1. Default configuration (no configuration required) + +After upgrading to Dubbo 3.0, the default behavior is interface-level + application-level multi-subscription. If the address can be subscribed at the application level, the application-level subscription will be used. If the address cannot be subscribed, the interface-level subscription will be used to ensure maximum compatibility. + +2. Subscription parameter configuration + +Application configuration (can be specified by configuration file or -D) `dubbo.application.service-discovery.migration` is `APPLICATION_FIRST` to enable multi-subscription mode, and configuration to `FORCE_APPLICATION` can force application-level subscription mode only. +The specific interface subscription can be configured in `parameters` in `ReferenceConfig`, and the Key is `migration.step`, and the Value is `APPLICATION_FIRST` or `FORCE_APPLICATION` key-value pair to configure a single subscription. +> Example: [https://github.com/apache/dubbo-samples/blob/master/dubbo-samples-cloud-native/dubbo-servicediscovery-migration/dubbo-servicediscovery-migration-consumer/src/test/java/ org/apache/dubbo/demo/consumer/DemoServiceConfigIT.java](https://github.com/apache/dubbo-samples/blob/master/2-advanced/dubbo-samples-cloud-native/dubbo-servicediscovery-migration /dubbo-servicediscovery-migration-consumer/src/test/java/org/apache/dubbo/demo/consumer/DemoServiceConfigIT.java) + +```java +System.setProperty("dubbo.application.service-discovery.migration", "APPLICATION_FIRST"); +``` +```java +ReferenceConfig referenceConfig = new ReferenceConfig<>(applicationModel. newModule()); +referenceConfig.setInterface(DemoService.class); +referenceConfig.setParameters(new HashMap<>()); +referenceConfig.getParameters().put("migration.step", mode); +return referenceConfig.get(); +``` + +3. Dynamic configuration (highest priority, configuration can be modified at runtime) + +This configuration needs to be pushed based on the configuration center, the Key is the application name + `.migration` (such as `demo-application.migraion`), and the Group is `DUBBO_SERVICEDISCOVERY_MIGRATION`. For details on rule body configuration, see [Guidelines for migrating from interface-level service discovery to application-level service discovery](/en/docs3-v2/java-sdk/upgrades-and-compatibility/service-discovery/service-discovery-rule/). +> Example: [https://github.com/apache/dubbo-samples/blob/master/dubbo-samples-cloud-native/dubbo-servicediscovery-migration/dubbo-servicediscovery-migration-consumer/src/main/java/ org/apache/dubbo/demo/consumer/UpgradeUtil.java](https://github.com/apache/dubbo-samples/blob/master/2-advanced/dubbo-samples-cloud-native/dubbo-servicediscovery-migration /dubbo-servicediscovery-migration-consumer/src/main/java/org/apache/dubbo/demo/consumer/UpgradeUtil.java) + +```java +step: FORCE_INTERFACE +``` \ No newline at end of file diff --git a/content/en/overview/tasks/traffic-management/_index.md b/content/en/overview/tasks/traffic-management/_index.md new file mode 100755 index 000000000000..fae717134ab3 --- /dev/null +++ b/content/en/overview/tasks/traffic-management/_index.md @@ -0,0 +1,88 @@ +--- +type: docs +title: "Traffic Management" +linkTitle: "Traffic Governance" +description: "Demonstrates how to use Dubbo's traffic management feature." +weight: 1 +no_list: true +--- + +{{< blocks/section color="white" height="auto">}} +
+
+
+
+
+
+

+ Dynamically adjust request timeout +

+

Setting a timeout period for Dubbo requests can effectively improve system stability and prevent individual services from being blocked and occupying too many resources.

By dynamically adjusting the service timeout period during the running period, it can effectively deal with problems such as frequent service timeouts and service blocking caused by unreasonable timeout settings and system emergencies, and improve system stability.

+
+
+
+
+
+
+

+ Adjust traffic distribution by weight +

+

Adjust traffic distribution by weight

+
+
+
+
+
+
+

+ Temporarily kick the service instance +

+

Temporarily kick the service instance

+
+
+
+
+
+
+

+ traffic grayscale +

+

According to the tags in the request context, the traffic is restricted and the grayscale release

+
+
+
+
+
+
+

+ Routing according to request conditions +

+

Routing according to the request initiator and method condition

+
+
+
+
+
+
+

+ Traffic isolation +

+

Isolate service traffic in different environments to ensure that services are not affected by each other

+
+
+
+
+
+
+

+ Same computer room/zone priority +

+

When an application invokes a service, it preferentially invokes the service provider in the same computer room/area.

+
+
+
+
+
+
+ +{{< /blocks/section >}} \ No newline at end of file diff --git a/content/en/overview/tasks/traffic-management/isolation.md b/content/en/overview/tasks/traffic-management/isolation.md new file mode 100644 index 000000000000..1680f1430db2 --- /dev/null +++ b/content/en/overview/tasks/traffic-management/isolation.md @@ -0,0 +1,78 @@ +--- +type: docs +title: "Temporarily kick out the problem service instance" +linkTitle: "Temporarily kick out the problem service instance" +weight: 5 +description: "Temporarily kick out problematic service instances in Dubbo-Admin" +--- + + +Dubbo provides the service management capability of temporarily removing problematic service instances, which can temporarily remove problematic service instances without restarting the application. + +Dubbo can temporarily remove problem service instances through XML configuration, annotation configuration, and dynamic configuration. Here we mainly introduce the dynamic configuration method. For other configuration methods, please refer to the old document [Configuration](https://dubbo.apache.org/zh/docsv2.7/user/configuration/) + + +## before the start + +Please make sure to run Dubbo-Admin successfully + +## Background Information + +When the service is running online, it is inevitable that some nodes have problems. In order not to affect the normal operation of the overall service, the service instance with the problem needs to be temporarily offline. Dubbo-Admin provides the ability to temporarily remove problematic service instances, which can help you temporarily offline problematic service instances without affecting the operation of the overall service. + + + +## Steps + +### Dynamic configuration + +1. Log in to the Dubbo-Admin console +2. In the left navigation pane, select Service Governance > Dynamic Configuration. +3. Click the Create button, fill in the rule content in the create dynamic configuration panel, and click Save. + + + +#### Detailed Rules + +##### Configuration template + +```yaml +--- +configVersion: v2.7 +scope: application/service +key: app-name/group+service+version +enabled: true +configs: +- addresses: ["0.0.0.0"] + providerAddresses: ["1.1.1.1:20880", "2.2.2.2:20881"] + side: consumer + applications/services: [] + parameters: + timeout: 1000 + loadbalance: random +- addresses: ["0.0.0.0:20880"] + side: provider + applications/services: [] + parameters: + threadpool: fixed + threads: 200 + iothreads: 4 + dispatcher: all + weight: 200 +... +``` + +**For the scenario of temporarily kicking out problematic service instances, you only need to clarify the following issues to know how to write the configuration:** + +1. Whether you want to modify the configuration of the entire application or a service. + - Application: `scope: application, key: app-name` (you can also use `services` to specify certain services). + - Service: `scope: service, key:group+service+version`. +2. The modification is applied to the provider side. + - Provider: `side: provider`. +3. Whether the configuration takes effect only for certain specific instances. + - All instances: `addresses: ["0.0.0.0"]` or `addresses: ["0.0.0.0:*"]` depends on the side value. + - Specified instances: `addersses[list of instance addresses]`. +4. The disabled parameter to be modified. + +## Result validation +Select the application related to the temporary removal of the problematic service instance configuration to trigger the call verification. \ No newline at end of file diff --git a/content/en/overview/tasks/traffic-management/timeout.md b/content/en/overview/tasks/traffic-management/timeout.md new file mode 100644 index 000000000000..9a5c0bc417fe --- /dev/null +++ b/content/en/overview/tasks/traffic-management/timeout.md @@ -0,0 +1,79 @@ +--- +type: docs +title: "Dynamic adjustment of service timeout" +linkTitle: "Dynamic adjustment of service timeout" +weight: 5 +description: "Dynamic adjustment of service timeout in Dubbo-Admin" +--- + + + +Dubbo provides the service governance capability of dynamically adjusting the timeout period, which can dynamically adjust the service timeout period without restarting the application. + +Dubbo can dynamically adjust the timeout time through XML configuration, annotation configuration, and dynamic configuration. Here we mainly introduce the dynamic configuration method. For other configuration methods, please refer to the old document [Configuration](https://dubbo.apache.org/zh/docsv2.7/user/configuration/) + +## before the start + +Please make sure to run Dubbo-Admin successfully + +## Background Information + +Various timeout configurations are encountered in daily work. After the business logic is changed, the existing call relationship may need to be adjusted continuously with the development of the business, and the change of the response time of the corresponding service interface may not be determined until it goes online. Dubbo-Admin provides a dynamic timeout configuration capability, which can help you quickly and dynamically adjust the interface timeout time to improve service availability. + + + +## Steps + +### Dynamic configuration + +1. Log in to the Dubbo-Admin console +2. In the left navigation pane, select Service Governance > Dynamic Configuration. +3. Click the Create button, fill in the rule content in the create dynamic configuration panel, and click Save. + + + +#### Detailed Rules + +##### Configuration template + +```yaml +--- +configVersion: v2.7 +scope: application/service +key: app-name/group+service+version +enabled: true +configs: +- addresses: ["0.0.0.0"] + providerAddresses: ["1.1.1.1:20880", "2.2.2.2:20881"] + side: consumer + applications/services: [] + parameters: + timeout: 1000 + loadbalance: random +- addresses: ["0.0.0.0:20880"] + side: provider + applications/services: [] + parameters: + threadpool: fixed + threads: 200 + iothreads: 4 + dispatcher: all + weight: 200 +... +``` + +**For the scenario of dynamically adjusting the timeout time, you only need to clarify the following issues to know how to write the configuration:** + +1. Whether you want to modify the configuration of the entire application or a service. + - Application: `scope: application, key: app-name` (you can also use `services` to specify certain services). + - Service: `scope: service, key:group+service+version`. +2. Whether the modification is applied to the consumer or the provider. + - Consumer: `side: consumer`, when acting on the consumer side, you can further use `providerAddress`, `applications` to select a specific provider example or application, if you configure the consumer and provider at the same time, the consumer will override provider. + - Provider: `side: provider`. +3. Whether the configuration takes effect only for certain specific instances. + - All instances: `addresses: ["0.0.0.0"]` or `addresses: ["0.0.0.0:*"]` depends on the side value. + - Specified instances: `addersses[list of instance addresses]`. +4. The timeout period to be modified. + +## Result validation +Select the application related to the timeout configuration to trigger the call verification. \ No newline at end of file diff --git a/content/en/overview/tasks/traffic-management/traffic-condition.md b/content/en/overview/tasks/traffic-management/traffic-condition.md new file mode 100644 index 000000000000..986e57a5971f --- /dev/null +++ b/content/en/overview/tasks/traffic-management/traffic-condition.md @@ -0,0 +1,63 @@ +--- +type: docs +title: "Traffic Isolation" +linkTitle: "Traffic Isolation" +weight: 5 +description: "Dynamic traffic isolation in Dubbo-Admin" +--- + +Dubbo provides the service management capability of dynamic traffic isolation, which can dynamically isolate traffic without restarting the application. + +Dubbo can implement traffic isolation through XML configuration, annotation configuration, and dynamic configuration. Here we mainly introduce the dynamic configuration method. For other configuration methods, please refer to the old document [Configuration](https://dubbo.apache.org/zh/docsv2.7/user/configuration/) + +## before the start + +Please make sure to run Dubbo-Admin successfully + +## Background Information + +If multiple versions of an application run simultaneously online and are deployed in different environments, such as daily environments and special environments, you can use label routing to isolate the traffic of different versions in different environments, and the order traffic of flash sales or orders from different channels Routing to special environments, routing normal traffic to everyday environments. Even if the special environment is abnormal, the traffic that should have entered the special environment will not enter the daily environment, and will not affect the use of the daily environment. + + +## Steps + +### Label Routing + +1. Log in to the Dubbo-Admin console +2. In the left navigation pane, select Service Governance > Label Routing. +3. Click the Create button, and in the Create New Tag Rule pane, fill in the rule content, and then click Save. + +#### Detailed Rules + +##### Configuration template + +```yaml +--- + force: false + runtime: true + enabled: true + key: governance-tagrouter-provider + tags: + - name: tag1 + addresses: ["127.0.0.1:20880"] + - name: tag2 + addresses: ["127.0.0.1:20881"] + ... +``` + +**For the traffic isolation scenario, you only need to clarify the following issues to know how to write the configuration:** + +1. To modify the configuration of the provider application to which the service belongs. + - Application: `scope: application, key: app-name` (you can also use `services` to specify certain services). +2. When the routing result is empty, whether to force return. + - force=false: When the routing result is empty, downgrade the provider whose tag is empty. + - force=true: When the routing result is empty, an exception will be returned directly. +3. Priority of routing rules + - priority=1: The priority of routing rules, used for sorting, the higher the priority, the higher the execution, it can be left blank, the default is 0. +4. Whether the configuration takes effect only for certain specific instances. + - All instances: `addresses: ["0.0.0.0"]` or `addresses: ["0.0.0.0:*"]` depends on the side value. + - Specified instances: `addersses[list of instance addresses]`. +5. The tag name to modify. + +## Result validation +Select the application related to the traffic isolation configuration to trigger the call verification. \ No newline at end of file diff --git a/content/en/overview/tasks/traffic-management/traffic-gray.md b/content/en/overview/tasks/traffic-management/traffic-gray.md new file mode 100644 index 000000000000..ccd0a8c26920 --- /dev/null +++ b/content/en/overview/tasks/traffic-management/traffic-gray.md @@ -0,0 +1,104 @@ +--- +type: docs +title: "Traffic Grayscale" +linkTitle: "Traffic Grayscale" +weight: 5 +description: "Configure label routing rules in Dubbo-Admin to achieve gray scale release" +--- + +Dubbo provides traffic grayscale service management capabilities, and can configure label routing rules and conditional routing to achieve grayscale publishing without restarting the application. + +Dubbo can achieve traffic grayscale through XML configuration, annotation configuration, and dynamic configuration. Here we mainly introduce the dynamic configuration method. For other configuration methods, please refer to the old document [Configuration](https://dubbo.apache.org/zh/docsv2.7/user/configuration/) + +## before the start + +Please make sure to run Dubbo-Admin successfully + +## Background Information + +Scenarios of demand changes and version iterations will be encountered during product development. In order to take into account both demand changes and system stability, the release should be as smooth as possible, and the number of affected people should be small to large, and roll back immediately if there is a problem. Dubbo-Admin provides dynamic traffic grayscale capabilities, which can help you bid for new services, release services smoothly, and improve service stability and availability. + +## Steps + +### Conditional Routing + +1. Log in to the Dubbo-Admin console +2. In the left navigation pane, select Service Governance > Conditional Routing. +3. Click the Create button, in the Create New Routing Rule panel, fill in the rule content, and then click Save. + + +#### Detailed Rules + +##### Configuration template + +```yaml +--- +scope: application/service +force: true +runtime: true +enabled: true +key: app-name/group+service+version +conditions: + - application=app1 => address=*:20880 + - method=sayHello => address=*:20880 +``` + +**For traffic grayscale scenarios, you only need to clarify the following issues to know how to write the configuration:** + +1. To modify the configuration of the consumer application or the configuration of a service. + - Application: `scope: application, key: app-name` (you can also use `services` to specify certain services). + - Service: `scope: service, key:group+service+version`. +2. When the routing result is empty, whether to force return. + - force=false: When the routing result is empty, downgrade the provider whose tag is empty. + - force=true: When the routing result is empty, an exception will be returned directly. +3. Priority of routing rules + - priority=1: The priority of routing rules, used for sorting, the higher the priority, the higher the execution, it can be left blank, the default is 0. +4. Whether the configuration takes effect only for certain specific instances. + - All instances: `addresses: ["0.0.0.0"]` or `addresses: ["0.0.0.0:*"]` depends on the side value. + - Specified instances: `addersses[list of instance addresses]`. +5. The condition rule to modify. + - => The previous one is the consumer matching condition. All parameters are compared with the consumer’s URL. When the consumer meets the matching condition, the subsequent filtering rules are executed for the consumer. + - => After that, it is the filter condition of the provider's address list. All parameters are compared with the provider's URL, and consumers only get the filtered address list in the end. + - If the matching condition is empty, it means to apply to all consumers, such as: => host != 10.20.153.11 + - If the filter condition is empty, access is prohibited, such as: host = 10.20.153.10 => + +### Label Routing + +1. Log in to the Dubbo-Admin console +2. In the left navigation pane, select Service Governance > Label Routing. +3. Click the Create button, and in the Create New Tag Rule pane, fill in the rule content, and then click Save. + +#### Detailed Rules + +##### Configuration template + +```yaml +--- + force: false + runtime: true + enabled: true + key: governance-tagrouter-provider + tags: + - name: tag1 + addresses: ["127.0.0.1:20880"] + - name: tag2 + addresses: ["127.0.0.1:20881"] + ... +``` + +**For traffic grayscale scenarios, you only need to clarify the following issues to know how to write the configuration:** + +1. To modify the configuration of the provider application to which the service belongs. + - Application: `scope: application, key: app-name` (you can also use `services` to specify certain services). +2. When the routing result is empty, whether to force return. + - force=false: When the routing result is empty, downgrade the provider whose tag is empty. + - force=true: When the routing result is empty, an exception will be returned directly. +3. Priority of routing rules + - priority=1: The priority of routing rules, used for sorting, the higher the priority, the higher the execution, it can be left blank, the default is 0. +4. Whether the configuration takes effect only for certain specific instances. + - All instances: `addresses: ["0.0.0.0"]` or `addresses: ["0.0.0.0:*"]` depends on the side value. + - Specified instances: `addersses[list of instance addresses]`. +5. The tag name to modify. + +## Result validation +Select the application related to traffic grayscale configuration to trigger the call verification. \ No newline at end of file diff --git a/content/en/overview/tasks/traffic-management/traffic-routing.md b/content/en/overview/tasks/traffic-management/traffic-routing.md new file mode 100644 index 000000000000..6de8e27f6adb --- /dev/null +++ b/content/en/overview/tasks/traffic-management/traffic-routing.md @@ -0,0 +1,66 @@ +--- +type: docs +title: "Request Routing" +linkTitle: "Request Routing" +weight: 5 +description: "Routing according to request conditions in Dubbo-Admin" +--- + +Dubbo provides the service governance capability of dynamically creating conditional routing, which can route according to the request initiator and method without restarting the application. + +Dubbo can implement dynamic routing according to request conditions through XML configuration, annotation configuration, and dynamic configuration. Here we mainly introduce the dynamic configuration method. For other configuration methods, please refer to the old document [Configuration](https://dubbo.apache.org/zh/docsv2.7/user/configuration/) + +## before the start + +Please make sure to run Dubbo-Admin successfully + +## Background Information + +In business scenarios such as black and white lists, excluding pre-release machines, exposing only some machines, and isolation by environment, routing rules are required to filter the target server address before initiating an RPC call, and the filtered address is used as the candidate address for the final RPC call. Dubbo-Admin provides conditional routing capabilities, which can help you configure routing rules to meet business scenarios. + +## Steps + +### Conditional Routing + +1. Log in to the Dubbo-Admin console +2. In the left navigation pane, select Service Governance > Conditional Routing. +3. Click the Create button, in the Create New Routing Rule panel, fill in the rule content, and then click Save. + + +#### Detailed Rules + +##### Configuration template + +```yaml +--- +scope: application/service +force: true +runtime: true +enabled: true +key: app-name/group+service+version +conditions: + - application=app1 => address=*:20880 + - method=sayHello => address=*:20880 +``` + +**For conditional routing scenarios, you only need to clarify the following questions to know how to write the configuration:** + +1. To modify the configuration of the consumer application or the configuration of a service. + - Application: `scope: application, key: app-name` (you can also use `services` to specify certain services). + - Service: `scope: service, key:group+service+version`. +2. When the routing result is empty, whether to force return. + - force=false: When the routing result is empty, downgrade the provider whose tag is empty. + - force=true: When the routing result is empty, an exception will be returned directly. +3. Priority of routing rules + - priority=1: The priority of routing rules, used for sorting, the higher the priority, the higher the execution, it can be left blank, the default is 0. +4. Whether the configuration takes effect only for certain specific instances. + - All instances: `addresses: ["0.0.0.0"]` or `addresses: ["0.0.0.0:*"]` depends on the side value. + - Specified instances: `addersses[list of instance addresses]`. +5. The condition rule to modify. + - => The previous one is the consumer matching condition. All parameters are compared with the consumer’s URL. When the consumer meets the matching condition, the subsequent filtering rules are executed for the consumer. + - => After that, it is the filter condition of the provider's address list. All parameters are compared with the provider's URL, and consumers only get the filtered address list in the end. + - If the matching condition is empty, it means to apply to all consumers, such as: => host != 10.20.153.11 + - If the filter condition is empty, access is prohibited, such as: host = 10.20.153.10 => + +## Result validation +Select the application related to the conditional routing configuration to trigger the call verification. \ No newline at end of file diff --git a/content/en/overview/tasks/traffic-management/weight.md b/content/en/overview/tasks/traffic-management/weight.md new file mode 100644 index 000000000000..8c9a6b2f5510 --- /dev/null +++ b/content/en/overview/tasks/traffic-management/weight.md @@ -0,0 +1,49 @@ +--- +type: docs +title: "Adjust traffic distribution by weight" +linkTitle: "Adjust traffic distribution by weight" +weight: 5 +description: "Adjust traffic distribution by weight in Dubbo-Admin" +--- + + + +Dubbo provides the service governance capability of adjusting traffic distribution by weight, and can dynamically adjust traffic distribution by weight without restarting the application. + +Dubbo can adjust traffic distribution by weight through XML configuration, annotation configuration, and dynamic configuration. Here we mainly introduce the dynamic configuration method. For other configuration methods, please refer to the old document [Configuration](https://dubbo.apache.org/zh/docsv2.7/user/configuration/) + +## before the start + +Please make sure to run Dubbo-Admin successfully + + +## Background Information + +In the case of different machine performance, the load of different machines needs to be evaluated systematically, and some machines need to be downgraded. By adjusting the traffic ratio of the machine by weight, the performance of the machine can be reasonably evaluated. +Certain services will face traffic shocks. In order to ensure the availability of core services, some services need to be downgraded. Adjust traffic distribution by weight to avoid faults caused by traffic impact. + + +## Steps + +### Weight Adjustment + +1. Log in to the Dubbo-Admin console +2. In the left navigation bar, select Service Governance > Weight Adjustment. +3. Click the Create button, and in the New Weight Rule panel, fill in the rule content, and then click Save. + + +#### Detailed Rules + + +**For the scenario of dynamically adjusting traffic distribution through weight, you only need to clarify the following issues to know how to write the configuration:** + +1. Whether you want to modify the configuration of the entire application or a service. + - Application: `scope: application, key: app-name` (you can also use `services` to specify certain services). + - Service: `scope: service, key:group+service+version`. +2. Whether the address list configuration takes effect only for some specific instances. + - All instances: `addresses: ["0.0.0.0"]` or `addresses: ["0.0.0.0:*"]` depends on the side value. + - Specified instances: `addersses[list of instance addresses]`. +3. The weight to modify. + +## Result validation +Select the application related to the weight configuration to trigger the call verification. \ No newline at end of file diff --git a/content/en/overview/tasks/traffic-management/zone.md b/content/en/overview/tasks/traffic-management/zone.md new file mode 100644 index 000000000000..2d4d430dca4e --- /dev/null +++ b/content/en/overview/tasks/traffic-management/zone.md @@ -0,0 +1,63 @@ +--- +type: docs +title: "Same computer room/area priority" +linkTitle: "Same computer room/area priority" +weight: 5 +description: "Dynamic configuration in Dubbo-Admin The priority of the same computer room/area" +--- + +Dubbo provides the service management capability of dynamically configuring the priority of the same computer room/region, and can dynamically configure the priority of the same computer room/region without restarting the application. + +Dubbo can be configured through XML, annotation configuration, and dynamic configuration in the same computer room/area first. Here we mainly introduce the dynamic configuration method. For other configuration methods, please refer to the old document [Configuration](https://dubbo.apache.org/zh/docsv2.7/user/configuration/) + +## before the start + +Please make sure to run Dubbo-Admin successfully + +## Background Information + +When applications are deployed in multiple different computer rooms/regions, cross-region calls will occur between applications, and cross-region calls will increase the response time. Priority in the same computer room/area means that when an application invokes a service, the service provider in the same computer room/area is called first. Dubbo-Admin provides a dynamic same-computer room/region priority capability, which can help you quickly and dynamically configure the same-computer room/region priority, avoiding network delays caused by cross-regions, thereby reducing call response time. + + +## Steps + +### Label Routing + +1. Log in to the Dubbo-Admin console +2. In the left navigation pane, select Service Governance > Label Routing. +3. Click the Create button, and in the Create New Tag Rule pane, fill in the rule content, and then click Save. + +#### Detailed Rules + +##### Configuration template + +```yaml +--- + force: false + runtime: true + enabled: true + key: governance-tagrouter-provider + tags: + - name: tag1 + addresses: ["127.0.0.1:20880"] + - name: tag2 + addresses: ["127.0.0.1:20881"] + ... +``` + +**For the same computer room/area priority scenario, you only need to clarify the following questions to know how to write the configuration:** + +1. To modify the configuration of the provider application to which the service belongs. + - Application: `scope: application, key: app-name` (you can also use `services` to specify certain services). +2. When the routing result is empty, whether to force return. + - force=false: When the routing result is empty, downgrade the provider whose tag is empty. + - force=true: When the routing result is empty, an exception will be returned directly. +3. Priority of routing rules + - priority=1: The priority of routing rules, used for sorting, the higher the priority, the higher the execution, it can be left blank, the default is 0. +4. Whether the configuration takes effect only for certain specific instances. + - All instances: `addresses: ["0.0.0.0"]` or `addresses: ["0.0.0.0:*"]` depends on the side value. + - Specified instances: `addersses[list of instance addresses]`. +5. The tag name to modify. + +## Result validation +Select the application related to the priority configuration of the same computer room/area to trigger the call verification. \ No newline at end of file diff --git a/content/en/overview/tasks/triple/_index.md b/content/en/overview/tasks/triple/_index.md new file mode 100755 index 000000000000..9ce330875dac --- /dev/null +++ b/content/en/overview/tasks/triple/_index.md @@ -0,0 +1,48 @@ +--- +type: docs +title: "Triple Usage Example" +linkTitle: "Triple Usage Example" +description: "Demonstrates Triple's cross-language communication, Streaming and other capabilities" +weight: 2 +no_list: true +--- + +{{< blocks/section color="white" height="auto">}} +
+
+
+
+
+
+

+ Define a service using IDL +

+

Using IDL to define cross-language services

+
+
+
+
+
+
+

+ Pojo serialization compatibility mode +

+

Pojo serialization compatibility mode

+
+
+
+
+
+
+

+ Streaming communication +

+

Stream communication mode

+
+
+
+
+
+
+ +{{< /blocks/section >}} \ No newline at end of file diff --git a/content/en/overview/tasks/triple/idl.md b/content/en/overview/tasks/triple/idl.md new file mode 100644 index 000000000000..1a9ec1734b9c --- /dev/null +++ b/content/en/overview/tasks/triple/idl.md @@ -0,0 +1,237 @@ +--- +type: docs +title: "Using IDL + Protobuf to define services across languages" +linkTitle: "Using IDL + Protobuf to define services across languages" +weight: 1 +description: "" +--- + +Service is the core concept in Dubbo. A service represents a set of RPC methods. Service is the basic unit of user-oriented programming and service discovery mechanism. The basic process of Dubbo development is: user-defined RPC service, through agreed configuration +Declare RPC as a Dubbo service, and then program based on the service API. For the service provider, it provides a specific implementation of the RPC service, while for the service consumer, it uses specific data to initiate a service call. + +The following describes how to quickly develop Dubbo services from three aspects: defining services, compiling services, configuring and loading services. + +For specific use cases, please refer to: [dubbo-samples-triple/stub](https://github.com/apache/dubbo-samples/tree/master/3-extensions/protocol/dubbo-samples-triple/src/main/java /org/apache/dubbo/sample/tri/stub); + +## Define the service +Dubbo3 recommends using IDL to define cross-language services. If you are more accustomed to using language-specific service definition methods, please move to [Multi-language SDK](/en/docs3-v2/) to view. + +```text +syntax = "proto3"; + +option java_multiple_files = true; +option java_package = "org.apache.dubbo.demo"; +option java_outer_classname = "DemoServiceProto"; +option objc_class_prefix = "DEMOSRV"; + +package demoservice; + +// The demo service definition. +service DemoService { + rpc SayHello (HelloRequest) returns (HelloReply) {} +} + +// The request message containing the user's name. +message HelloRequest { + string name = 1; +} + +// The response message containing the greetings +message HelloReply { + string message = 1; +} + +``` + +The above is a simple example of using IDL to define a service. We can name it `DemoService.proto`. The RPC service name `DemoService` and method signature are defined in the proto file +`SayHello (HelloRequest) returns (HelloReply) {}`, and also defines the method input parameter structure, output parameter structure `HelloRequest` and `HelloReply`. +The service in IDL format relies on the Protobuf compiler to generate client and server programming APIs that can be called by users. Dubbo provides unique plug-ins for multiple languages based on the native Protobuf Compiler to adapt to the Dubbo framework Proprietary API and programming model. + +> The service defined using Dubbo3 IDL only allows one input and output parameter. This form of service signature has two advantages. One is that it is more friendly to multi-language implementation, and the other is that it can guarantee the backward compatibility of the service, relying on the Protobuf sequence With optimized compatibility, we can easily adjust the transmitted data structure, such as adding and deleting fields, without worrying about interface compatibility at all. + +## Compile service +According to the language currently used, configure the corresponding Protobuf plug-in, and after compilation, the language-related service definition stub will be produced. + +### Java + +Java compiler configuration reference: +```xml + + org.xolstice.maven.plugins + protobuf-maven-plugin + 0.6.1 + + com.google.protobuf:protoc:${protoc.version}:exe:${os.detected.classifier} + + grpc-java + io.grpc:protoc-gen-grpc-java:${grpc.version}:exe:${os.detected.classifier} + + + + dubbo + org.apache.dubbo + dubbo-compiler + 3.0.10 + org.apache.dubbo.gen.tri.Dubbo3TripleGenerator + + + + + + + compile + test-compile + compile-custom + test-compile-custom + + + + +``` + +The stub generated by the Java language is as follows, the core is an interface definition +```java +@javax.annotation.Generated( +value = "by Dubbo generator", +comments = "Source: DemoService.proto") +public interface DemoService { + static final String JAVA_SERVICE_NAME = "org.apache.dubbo.demo.DemoService"; + static final String SERVICE_NAME = "demoservice. DemoService"; + + org.apache.dubbo.demo.HelloReply sayHello(org.apache.dubbo.demo.HelloRequest request); + + CompletableFuture sayHelloAsync(org.apache.dubbo.demo.HelloRequest request); +} +``` + +### Golang + +The stub generated by the Go language is as follows. This stub stores user-defined interfaces and data types. + +```go +func _DUBBO_Greeter_SayHello_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) { +in := new(HelloRequest) +if err := dec(in); err != nil { +return nil, err +} +base := srv.(dgrpc.Dubbo3GrpcService) +args := []interface{}{} +args = append(args, in) +invo := invocation. NewRPCInvocation("SayHello", args, nil) +if interceptor == nil { +result := base.GetProxyImpl().Invoke(ctx, invo) +return result.Result(), result.Error() +} +info := &grpc. UnaryServerInfo{ +Server: srv, +FullMethod: "/main. Greeter/SayHello", +} +handler := func(ctx context.Context, req interface{}) (interface{}, error) { +result := base.GetProxyImpl().Invoke(context.Background(), invo) +return result.Result(), result.Error() +} +return interceptor(ctx, in, info, handler) +} +``` + + +## Configure and load the service +The provider is responsible for providing specific Dubbo service implementations, that is, following the format constrained by the RPC signature to implement specific business logic codes. After implementing the service, register the service implementation as a standard Dubbo service, +Afterwards, the Dubbo framework can forward the received request to the service implementation, execute the method, and return the result. + +The configuration on the consumer side will be simpler. You only need to declare that the service defined by IDL is a standard Dubbo service, and the framework can help developers generate corresponding proxies. Developers will be completely oriented to proxy programming. +Basically, the implementation of all languages in Dubbo ensures that the proxy exposes standardized interfaces according to the IDL service definition. + +### Java +Provider, implement service +```java +public class DemoServiceImpl implements DemoService { + private static final Logger logger = LoggerFactory. getLogger(DemoServiceImpl. class); + + @Override + public HelloReply sayHello(HelloRequest request) { + logger.info("Hello " + request.getName() + ", request from consumer: " + RpcContext.getContext().getRemoteAddress()); + return HelloReply. newBuilder() + .setMessage("Hello " + request.getName() + ", response from provider: " + + RpcContext.getContext().getLocalAddress()) + .build(); + } + + @Override + public CompletableFuture sayHelloAsync(HelloRequest request) { + return CompletableFuture.completedFuture(sayHello(request)); + } +} +``` +Provider, registration service (take Spring XML as an example) +```xml + + +``` + +Consumer side, reference service +```xml + +``` + +On the consumer side, use the service proxy +```java +public void callService() throws Exception { + ... + DemoService demoService = context. getBean("demoService", DemoService. class); + HelloRequest request = HelloRequest.newBuilder().setName("Hello").build(); + HelloReply reply = demoService.sayHello(request); + System.out.println("result: " + reply.getMessage()); +} +``` + +### Golang + +Provider, implement service + +```go +type User struct { +ID string +name string +Age int32 +Time time. Time +} + +type UserProvider struct { +} + +func (u *UserProvider) GetUser(ctx context.Context, req []interface{}) (*User, error) { +gxlog.CInfo("req:%#v", req) +rsp := User{"A001", "Alex Stocks", 18, time. Now()} +gxlog.CInfo("rsp:%#v", rsp) +return &rsp, nil +} + +func (u *UserProvider) Reference() string { +return "UserProvider" +} + +func (u User) JavaClassName() string { +return "org.apache.dubbo.User" +} + +func main() { + hessian.RegisterPOJO(&User{}) +config. SetProviderService(new(UserProvider)) +} +``` + +On the consumer side, use the service proxy + +```go +func main() { +config. Load() +user := &pkg. User{} +err := userProvider.GetUser(context.TODO(), []interface{}{"A001"}, user) +if err != nil { +os. Exit(1) +return +} +gxlog.CInfo("response result: %v\n", user) +} +``` \ No newline at end of file diff --git a/content/en/overview/tasks/triple/streaming.md b/content/en/overview/tasks/triple/streaming.md new file mode 100644 index 000000000000..bb3abc752455 --- /dev/null +++ b/content/en/overview/tasks/triple/streaming.md @@ -0,0 +1,296 @@ +--- +type: docs +title: "Streaming communication mode" +linkTitle: "Streaming communication mode" +weight: 3 +description: "" +--- + +For specific use cases, please refer to: [dubbo-samples-triple/pojo](https://github.com/apache/dubbo-samples/tree/master/3-extensions/protocol/dubbo-samples-triple/src/main/java /org/apache/dubbo/sample/tri/pojo); + +## Open the new feature of Triple - Stream (stream) +Stream is a new call type provided by Dubbo3. It is recommended to use stream in the following scenarios: + +- The interface needs to send a large amount of data. These data cannot be placed in an RPC request or response, and need to be sent in batches. However, if the application layer cannot solve the order and performance problems in the traditional multiple RPC method, if the order needs to be guaranteed , it can only be sent serially +- In streaming scenarios, data needs to be processed in the order they are sent, and the data itself has no definite boundary +- In push scenarios, multiple messages are sent and processed in the context of the same call + +Stream is divided into the following three types: +- SERVER_STREAM (server stream) + ![SERVER_STREAM](/imgs/v3/migration/tri/migrate-server-stream.png) +- CLIENT_STREAM (client stream) + ![CLIENT_STREAM](/imgs/v3/migration/tri/migrate-client-stream.png) +- BIDIRECTIONAL_STREAM (bidirectional stream) + ![BIDIRECTIONAL_STREAM](/imgs/v3/migration/tri/migrate-bi-stream.png) + +> Due to the limitations of the `java` language, the implementation of BIDIRECTIONAL_STREAM and CLIENT_STREAM is the same. + +In Dubbo3, the stream interface is declared and used as `SteamObserver`, and users can use and implement this interface to send and handle stream data, exceptions, and end. + +> For Dubbo2 users, they may be unfamiliar with StreamObserver, which is a stream type defined by Dubbo3. There is no Stream type in Dubbo2, so it has no impact on migration scenarios. + +Stream Semantic Guarantees +- Provide message boundaries, which can easily process messages separately +- Strictly ordered, the order of the sender is consistent with the order of the receiver +- Full duplex, no need to wait for sending +- Support cancellation and timeout + +### Non-PB serialized stream +1. api +```java +public interface IWrapperGreeter { + + StreamObserver sayHelloStream(StreamObserver response); + + void sayHelloServerStream(String request, StreamObserver response); +} +``` + +> The method input parameters and return values of the Stream method are strictly agreed. In order to prevent problems caused by writing errors, the Dubbo3 framework side checks the parameters, and throws an exception if there is an error. +> For `BIDIRECTIONAL_STREAM`, it should be noted that `StreamObserver` in the parameter is the response stream, and `StreamObserver` in the return parameter is the request stream. + +2. Implementation class +```java +public class WrapGreeterImpl implements WrapGreeter { + + //... + + @Override + public StreamObserver sayHelloStream(StreamObserver response) { + return new StreamObserver() { + @Override + public void onNext(String data) { + System.out.println(data); + response.onNext("hello,"+data); + } + + @Override + public void onError(Throwable throwable) { + throwable. printStackTrace(); + } + + @Override + public void onCompleted() { + System.out.println("onCompleted"); + response.onCompleted(); + } + }; + } + + @Override + public void sayHelloServerStream(String request, StreamObserver response) { + for (int i = 0; i < 10; i++) { + response.onNext("hello," + request); + } + response.onCompleted(); + } +} +``` + +3. Call method +```java +delegate.sayHelloServerStream("server stream", new StreamObserver() { + @Override + public void onNext(String data) { + System.out.println(data); + } + + @Override + public void onError(Throwable throwable) { + throwable. printStackTrace(); + } + + @Override + public void onCompleted() { + System.out.println("onCompleted"); + } +}); + + +StreamObserver request = delegate.sayHelloStream(new StreamObserver() { + @Override + public void onNext(String data) { + System.out.println(data); + } + + @Override + public void onError(Throwable throwable) { + throwable. printStackTrace(); + } + + @Override + public void onCompleted() { + System.out.println("onCompleted"); + } +}); +for (int i = 0; i < n; i++) { + request.onNext("stream request" + i); +} +request.onCompleted(); +``` + +## Serialized stream using Protobuf + +For the `Protobuf` serialization method, it is recommended to write `IDL` and use the `compiler` plugin to compile and generate. The generated code is roughly as follows: +```java +public interface PbGreeter { + + static final String JAVA_SERVICE_NAME = "org.apache.dubbo.sample.tri.PbGreeter"; + static final String SERVICE_NAME = "org.apache.dubbo.sample.tri.PbGreeter"; + + static final boolean inited = PbGreeterDubbo.init(); + + //... + + void greetServerStream(org.apache.dubbo.sample.tri.GreeterRequest request, org.apache.dubbo.common.stream.StreamObserver responseObserver); + + org.apache.dubbo.common.stream.StreamObserver greetStream(org.apache.dubbo.common.stream.StreamObserver responseObserver); +} +``` + +### Complete use case + +1. Writing the Java interface + ```java + import org.apache.dubbo.common.stream.StreamObserver; + import org.apache.dubbo.hello.HelloReply; + import org.apache.dubbo.hello.HelloRequest; + + public interface IGreeter { + /** + * 
+          * Sends greeting by stream
+          *
+ */ + StreamObserver sayHello(StreamObserver replyObserver); + + } + ``` + +2. Write the implementation class + ```java + public class IStreamGreeterImpl implements IStreamGreeter { + + @Override + public StreamObserver sayHello(StreamObserver replyObserver) { + + return new StreamObserver() { + private List replyList = new ArrayList<>(); + + @Override + public void onNext(HelloRequest helloRequest) { + System.out.println("onNext receive request name:" + helloRequest.getName()); + replyList.add(HelloReply.newBuilder() + .setMessage("receive name:" + helloRequest.getName()) + .build()); + } + + @Override + public void onError(Throwable cause) { + System.out.println("onError"); + replyObserver.onError(cause); + } + + @Override + public void onCompleted() { + System.out.println("onComplete receive request size:" + replyList.size()); + for (HelloReply reply : replyList) { + replyObserver.onNext(reply); + } + replyObserver.onCompleted(); + } + }; + } + } + ``` +3. Create a Provider + + ```java + public class StreamProvider { + public static void main(String[] args) throws InterruptedException { + ServiceConfig service = new ServiceConfig<>(); + service.setInterface(IStreamGreeter.class); + service.setRef(new IStreamGreeterImpl()); + service.setProtocol(new ProtocolConfig(CommonConstants.TRIPLE, 50051)); + service.setApplication(new ApplicationConfig("stream-provider")); + service.setRegistry(new RegistryConfig("zookeeper://127.0.0.1:2181")); + service. export(); + System.out.println("dubbo service started"); + new CountDownLatch(1). await(); + } + } + ``` + +4. Create Consumer + + ```java + public class StreamConsumer { + public static void main(String[] args) throws InterruptedException, IOException { + ReferenceConfig ref = new ReferenceConfig<>(); + ref. setInterface(IStreamGreeter. class); + ref. setCheck(false); + ref.setProtocol(CommonConstants.TRIPLE); + ref. setLazy(true); + ref. setTimeout(100000); + ref. setApplication(new ApplicationConfig("stream-consumer")); + ref.setRegistry(new RegistryConfig("zookeeper://mse-6e9fda00-p.zk.mse.aliyuncs.com:2181")); + final IStreamGreeter iStreamGreeter = ref. get(); + + System.out.println("dubbo ref started"); + try { + + StreamObserver streamObserver = iStreamGreeter.sayHello(new StreamObserver() { + @Override + public void onNext(HelloReply reply) { + System.out.println("onNext"); + System.out.println(reply.getMessage()); + } + + @Override + public void onError(Throwable throwable) { + System.out.println("onError:" + throwable.getMessage()); + } + + @Override + public void onCompleted() { + System.out.println("onCompleted"); + } + }); + + streamObserver.onNext(HelloRequest.newBuilder() + .setName("tony") + .build()); + + streamObserver.onNext(HelloRequest.newBuilder() + .setName("nick") + .build()); + + streamObserver.onCompleted(); + } catch (Throwable t) { + t. printStackTrace(); + } + System.in.read(); + } + } + ``` + +5. Run Provider and Consumer, you can see that the request returns normally + > onNext\ + > receive name:tony\ + > onNext\ + > receive name:nick\ + > onCompleted + +### common problem + +1. protobuf class not found + +Since the bottom layer of the Triple protocol needs to rely on the protobuf protocol for transmission, even if the defined service interface does not use protobuf, it is necessary to introduce protobuf dependencies into the environment. + +```xml + + com.google.protobuf + protobuf-java + 3.19.4 + +``` \ No newline at end of file diff --git a/content/en/overview/tasks/triple/wrap.md b/content/en/overview/tasks/triple/wrap.md new file mode 100644 index 000000000000..6ff2eb21c58b --- /dev/null +++ b/content/en/overview/tasks/triple/wrap.md @@ -0,0 +1,171 @@ +--- +type: docs +title: "Pojo Serialization Compatibility Mode" +linkTitle: "Pojo serialization compatibility mode" +weight: 2 +description: "" +--- + +This tutorial will build a simple project from scratch to demonstrate how to use Dubbo Triple based on POJO, and upgrade to the Triple protocol while the application does not change the existing interface definition. **In this mode, Triple is used in the same way as Dubbo protocol. ** + +For specific use cases, please refer to: [dubbo-samples-triple/pojo](https://github.com/apache/dubbo-samples/tree/master/3-extensions/protocol/dubbo-samples-triple/src/main/java /org/apache/dubbo/sample/tri/pojo); + +### precondition +- [JDK](https://jdk.java.net/) version >= 8 +- Installed [Maven](https://maven.apache.org/) +- Installed and started [Zookeeper](https://zookeeper.apache.org/) + +### Create project +1. First create an empty maven project + ``` + $ mvn archetype:generate \ + -DgroupId=org.apache.dubbo \ + -DartifactId=tri-pojo-demo\ + -DarchetypeArtifactId=maven-archetype-quickstart\ + -DarchetypeVersion=1.4 \ + -DarchetypeGroupId=org.apache.maven.archetypes \ + -Dversion=1.0-SNAPSHOT + ``` +2. Switch to the project directory + ``` + $ cd tri-pojo-demo + ``` +3. Set JDK version in `pom.xml`, add Dubbo dependencies and plugins + ```xml + + UTF-8 + 1.8 + 1.8 + + + + + junit + junit + 4.13 + test + + + org.apache.dubbo + dubbo + 3.0.8 + + + org.apache.dubbo + dubbo-dependencies-zookeeper-curator5 + pom + 3.0.8 + + + com.google.protobuf + protobuf-java + 3.19.4 + + + ``` +4. Add interface definition `src/main/java/org/apache/dubbo/Greeter.java` + ```java + package org.apache.dubbo; + + public interface Greeter { + String sayHello(String name); + } + ``` +5. Add server-side interface implementation `src/main/java/org/apache/dubbo/GreeterImpl.java` + ```java + package org.apache.dubbo; + + public class GreeterImpl implements Greeter { + @Override + public String sayHello(String name) { + return "Hello," + name + "!"; + } + } + ``` +6. Add server startup class `src/main/java/org/apache/dubbo/MyDubboServer.java` + ```java + package org.apache.dubbo; + + import org.apache.dubbo.common.constants.CommonConstants; + import org.apache.dubbo.config.ApplicationConfig; + import org.apache.dubbo.config.ProtocolConfig; + import org.apache.dubbo.config.RegistryConfig; + import org.apache.dubbo.config.ServiceConfig; + import org.apache.dubbo.config.bootstrap.DubboBootstrap; + + import java.io.IOException; + + public class MyDubboServer { + + public static void main(String[] args) throws IOException { + ServiceConfig service = new ServiceConfig<>(); + service.setInterface(Greeter.class); + service.setRef(new GreeterImpl()); + + DubboBootstrap bootstrap = DubboBootstrap. getInstance(); + bootstrap. application(new ApplicationConfig("tri-pojo-server")) + .registry(new RegistryConfig("zookeeper://127.0.0.1:2181")) + .protocol(new ProtocolConfig(CommonConstants.TRIPLE, 50051)) + .service(service) + .start(); + System.out.println("Dubbo triple pojo server started"); + System.in.read(); + } + } + ``` + +7. Add the client startup class `src/main/java/org/apache/dubbo/MyDubboClient.java` + ```java + package org.apache.dubbo; + + import org.apache.dubbo.common.constants.CommonConstants; + import org.apache.dubbo.config.ApplicationConfig; + import org.apache.dubbo.config.ReferenceConfig; + import org.apache.dubbo.config.RegistryConfig; + import org.apache.dubbo.config.bootstrap.DubboBootstrap; + + public class MyDubboClient { + public static void main(String[] args) { + DubboBootstrap bootstrap = DubboBootstrap. getInstance(); + ReferenceConfig ref = new ReferenceConfig<>(); + ref. setInterface(Greeter. class); + ref.setProtocol(CommonConstants.TRIPLE); + ref. setTimeout(3000); + bootstrap. application(new ApplicationConfig("tri-pojo-client")) + .registry(new RegistryConfig("zookeeper://127.0.0.1:2181")) + .reference(ref) + .start(); + + Greeter greeter = ref. get(); + String reply = greeter. sayHello("pojo"); + System.out.println("Received reply:" + reply); + } + } + ``` +8. Compile the code + ``` + $ mvn clean install + ``` +9. Start the server + ``` + $ mvn org.codehaus.mojo:exec-maven-plugin:3.0.0:java -Dexec.mainClass="org.apache.dubbo.MyDubboServer" + Dubbo triple pojo server started + ``` +10. Open a new terminal and start the client + ``` + $ mvn org.codehaus.mojo:exec-maven-plugin:3.0.0:java -Dexec.mainClass="org.apache.dubbo.MyDubboClient" + Received reply: message: "Hello, Demo!" + ``` +### common problem + +1. protobuf class not found + +Since the bottom layer of the Triple protocol needs to rely on the protobuf protocol for transmission, even if the defined service interface does not use protobuf, it is necessary to introduce protobuf dependencies into the environment. + +```xml + + com.google.protobuf + protobuf-java + 3.19.4 + +``` \ No newline at end of file diff --git a/content/en/overview/what/_index.md b/content/en/overview/what/_index.md new file mode 100644 index 000000000000..b78706610080 --- /dev/null +++ b/content/en/overview/what/_index.md @@ -0,0 +1,16 @@ +--- +type: docs +title: "What is Dubbo" +linkTitle: "What is Dubbo" +weight: 1 +description: "" +--- + +Apache Dubbo is an RPC microservice framework that provides SDK implementations in multiple languages including Java and Golang. + +* It is the first time to contact Dubbo, please continue to read this chapter to understand the rich functions and core concepts provided by Dubbo; +* If you want to experience Dubbo quickly, please refer to [Quick Start](../quickstart) +* Dubbo3 Advanced Usage Reference [Multilanguage SDK Documentation](../mannual) +* Dubbo3 design and migration + * [3.0 Design Concept and Core Functions](./dubbo3/) + * [How to migrate to Dubbo3](/en/docs3-v2/java-sdk/upgrades-and-compatibility) \ No newline at end of file diff --git a/content/en/overview/what/architecture.md b/content/en/overview/what/architecture.md new file mode 100644 index 000000000000..97ad586e05b6 --- /dev/null +++ b/content/en/overview/what/architecture.md @@ -0,0 +1,124 @@ +--- +type: docs +title: "Architecture" +linkTitle: "Architecture" +weight: 3 +--- + +## RPC communication +Dubbo3's Triple protocol is built on the HTTP/2 protocol, so it has better penetration and versatility. The Triple protocol is compatible with gRPC and provides communication models such as Request Response, Request Streaming, Response Streaming, and Bi-directional Streaming; from Triple Starting from the agreement, Dubbo also supports IDL-based service definition. + +In addition, Dubbo also integrates most of the industry's mainstream protocols, allowing users to use these communication protocols within the Dubbo framework, providing users with a unified programming model and service governance model, these protocols include rest, hessian2, jsonrpc, thrift, etc. , note that there will be some differences in the range supported by different language SDK implementations. + +Details can be viewed +* [Triple Quick Facts](/en/docs3-v2/java-sdk/concepts-and-architecture/triple/) +* [Specification](https://github.com/apache/dubbo-awesome/blob/master/proposals/D0-triple.md) + +## Service Discovery +Service discovery, that is, the ability of the consumer to automatically discover the list of service addresses, is a key capability that the microservice framework needs to have. With the help of automated service discovery, microservices can be implemented without knowing the deployment location and IP address of the peer. communication. + +There are many ways to realize service discovery. Dubbo provides a Client-Based service discovery mechanism. Usually, additional third-party registry components need to be deployed to coordinate the service discovery process, such as the commonly used [Nacos](https:/ /nacos.io/), Consul, Zookeeper, etc. Dubbo itself also provides the connection to various registry components, and users can choose flexibly. + +Dubbo is based on the automatic service discovery capability of the consumer, and its basic working principle is as follows: + +![architecture](/imgs/architecture.png) + +Under the traditional deployment architecture, service discovery involves three participating roles: provider, consumer, and registration center. Among them, the provider registers the URL address to the registration center, the registration center is responsible for aggregating data, and the consumer subscribes to the URL address from the registration center. renew. +In the context of cloud native, for example, when the application is deployed on a platform such as Kubernetes, since the platform itself maintains the mapping relationship between the application/service and the instance, the registration center and the registration action are sinked to the infrastructure layer to a certain extent, so the framework Own registration action is sometimes not necessary. + +Dubbo3 provides a new application-level service discovery model, which is different from Dubbo2's interface-level service discovery model in terms of design and implementation. It can be viewed here: +* [Application-level service discovery](/en/docs3-v2/java-sdk/concepts-and-architecture/service-discovery/#Introduction to application-level service discovery) + +## Traffic management +Since Dubbo2, Dubbo has provided rich service governance rules, including routing rules, dynamic configuration, etc. + +On the one hand, Dubbo3 is connecting to the governance rules represented by VirtualService and DestinationRule used in popular Mesh products such as Istio by docking xDS; on the other hand, Dubbo is seeking to design a set of its own rules to achieve Traffic governance, and flexible governance capabilities. + +* [Dubbo2 Service Governance Rules](../../tasks/traffic-management) +* Dubbo3 service governance rules + +## Dubbo Mesh +The goal of Dubbo Mesh is to provide a complete Mesh solution adapted to the Dubbo system, including customized control plane (Control Plane) and customized data plane solutions. The Dubbo control plane is based on the industry's mainstream Istio extension, and supports richer traffic governance rules, Dubbo application-level service discovery models, etc. The Dubbo data plane can use Envoy Sidecar, which implements the deployment solution of Dubbo SDK + Envoy, or Dubbo Proxyless mode. Directly realize the communication between Dubbo and the control plane. Dubbo Mesh is undergoing rapid evolution, we will try our best to keep the content of the document updated. + +![mix-mesh](/imgs/v3/mesh/mix-mesh.png) + +View Dubbo Mesh design details here +* [Dubbo Proxy Mesh](https://github.com/apache/dubbo-awesome/blob/master/proposals/D3.1-thinsdk-sidecar-mesh.md) +* [Dubbo Proxyless Mesh](https://github.com/apache/dubbo-awesome/blob/master/proposals/D3.2-proxyless-mesh.md) +* [Dubbo Control Plane](https://github.com/apache/dubbo-awesome/blob/master/proposals/D3.2-proxyless-mesh.md) + +## Deployment Architecture +> This section focuses on describing the Dubbo deployment architecture in the traditional mode. The deployment architecture in the cloud-native background will change, mainly reflected in the fact that the infrastructure (Kubernetes, Service Mesh, etc.) will take on more responsibilities. +> The responsibilities of centralized components such as registration center, metadata center, configuration center, etc. are integrated, and operation and maintenance become simpler, but by emphasizing these centralized components, it is easier for us to understand the working principle of Dubbo. + +As a micro-service framework, Dubbo sdk is deployed in each location of the distributed cluster along with the micro-service components. In order to realize the cooperation between various micro-service components in a distributed environment, +Dubbo defines some centralized components, including: +* Registry. Coordinate address registration and discovery between Consumer and Provider +* Configuration center. + * Store the global configuration of the Dubbo startup phase to ensure cross-environment sharing and global consistency of the configuration + * Responsible for the storage and push of service governance rules (routing rules, dynamic configuration, etc.). +* Metadata Center. + * Receive the service interface metadata reported by the Provider, and provide operation and maintenance capabilities for Admin and other consoles (such as service testing, interface documents, etc.) + * As a supplement to the service discovery mechanism, it provides the synchronization capability of additional interface/method level configuration information, which is equivalent to the additional extension of the registration center + +![threecenters](/imgs/v3/concepts/threecenters.png) + +The above figure completely describes the interaction process between Dubbo microservice components and each center. + +The above three centers are not a necessary condition for running Dubbo. Users can decide to enable only one or more of them according to their own business conditions to simplify deployment. Typically, all users will be registered with an independent +Start Dubbo service development, and the configuration center and metadata center will be gradually introduced on demand during the evolution of microservices. + +### Registry + +The registration center plays a very important role, and it carries the responsibilities of service registration and service discovery. Currently Dubbo supports service discovery and service registration at the following two granularities, namely interface level and application level, and the registration center can be deployed on demand: + +- In the traditional Dubbo SDK usage posture, if you only provide RPC services in direct connection mode, you do not need to deploy a registration center. +- Regardless of the interface level or the application level, if Dubbo SDK itself is required for service registration and service discovery, you can choose to deploy a registration center and integrate the corresponding registration center in Dubbo. + +- In the Dubbo + Mesh scenario, with the weakening of Dubbo service registration capabilities, the registration center in Dubbo is no longer a must, and its responsibilities are beginning to be replaced by the control plane. If the Dubbo + Mesh deployment method is adopted, whether it is The mesh method of ThinSDK or the mesh method of Proxyless no longer requires independent deployment of the registration center. + +The registration center does not depend on the configuration center and metadata center, as shown in the following figure: + +![centers-registry](/imgs/v3/concepts/centers-registry.png) + +The configuration center and metadata center are not deployed in the figure. In Dubbo, the instance of the registration center will be used as the configuration center and metadata center at the same time by default. This is the default behavior of Dubbo. If you really do not need the capabilities of the configuration center or metadata center , which can be turned off in the configuration. There are two configurations in the configuration of the registration center, namely use-as-config-center and use-as-metadata-center. Just set the configuration to false. + +### Metadata Center + +The metadata center is supported in version 2.7.x. As application-level service registration and service discovery are implemented in Dubbo, the metadata center becomes more and more important. The metadata center will need to be deployed in the following situations: + +1. For an application service originally built with the old version of Dubbo, when migrating to Dubbo 3, Dubbo 3 will need a metadata center to maintain the mapping relationship between RPC services and applications (that is, the mapping relationship between interfaces and applications), because if Application-level service discovery and service registration are adopted, and the data organization form of the "application-instance list" structure will be adopted in the registration center, which is no longer the data organization form of the previous "interface-instance list" structure. When the application services that use interface-level service registration and service discovery are migrated to the application level, the corresponding relationship between the interface and the application cannot be obtained, so that the instance list information cannot be obtained from the registration center. Therefore, in order to be compatible with this scenario, Dubbo is in When the Provider side starts, it will store the mapping relationship between the interface and the application in the metadata center. +2. In order to allow the registration center to focus more on address discovery and push capabilities and reduce the burden on the registration center, the metadata center carries all service metadata, a large number of interface/method level configuration information, etc., regardless of interface granularity or application granularity Service discovery and registration, and the metadata center all play an important role. + +If you have the above two requirements, you can choose to deploy the metadata center and integrate the metadata center through Dubbo configuration. + +The metadata center does not depend on the registration center and configuration center, and users can freely choose whether to integrate and deploy the metadata center, as shown in the following figure: + +![centers-metadata](/imgs/v3/concepts/centers-metadata.png) + +There is no configuration center in this figure, which means that the ability to manage configuration globally may not be required. There is no registration center in the figure, which means that the Dubbo mesh solution may be adopted, or service registration may not be required, and only receive service calls in direct connection mode. + +### Configuration Center + +The configuration center is different from the other two centers. It has nothing to do with the interface level or the application level. It has no corresponding relationship with the interface. It is only related to the configuration data. Even if the registration center and metadata center are not deployed, the configuration center can be directly accessed. into the Dubbo application service. In the entire deployment architecture, instances in the entire cluster (whether they are Providers or Consumers) will share the configuration in the configuration center cluster, as shown in the following figure: + +![centers-config](/imgs/v3/concepts/centers-config.png) + +There is no registration center in the figure, which means that the Dubbo mesh solution may be adopted, or service registration may not be required, and only receive service calls in direct connection mode. + +There is no metadata center in this figure, which means that Consumer can obtain service metadata from the MetadataService exposed by Provider, so as to realize RPC call + +### Guarantee the high-availability deployment architecture of the three centers + +Although the three major centers are no longer necessary for Dubbo application services, in a real production environment, once the three major centers have been integrated and deployed, the three major centers will still face availability issues. Dubbo needs to support the three major centers High availability solution. Dubbo supports multiple registration centers, multiple data centers, and multiple configuration centers to meet the needs of deployment architecture models such as multi-active in the same city, three centers in two places, and multi-active in different places. + +Dubbo SDK supports Multiple mode for all three centers. + +- Multiple registries: Dubbo supports multiple registries, that is, an interface or an application can be registered in multiple registries, such as ZK clusters and Nacos clusters, and consumers can also subscribe from multiple registries Service address information for service discovery. By supporting multiple registration centers, it is ensured that one of the registration center clusters can be switched to another registration center cluster when it is unavailable, so that services can be provided normally and service calls can be initiated. This can also satisfy the registration center to adapt to various high-availability deployment architecture modes in deployment. +- Multiple configuration centers: Dubbo supports multiple configuration centers to ensure that when a configuration center cluster becomes unavailable, it can switch to another configuration center cluster to ensure that the global configuration, routing rules, and other information can be obtained from the configuration center normally. This can also satisfy the configuration center to adapt to various high-availability deployment architecture modes in deployment. + +- Multiple data centers: Dubbo supports multiple data centers: it is used to deal with disaster recovery and other situations where a metadata center cluster is unavailable. At this time, you can switch to another metadata center cluster to ensure that the metadata center can normally provide relevant service elements. Data management capabilities. + +Taking the registration center as an example, the following is a schematic diagram of the deployment architecture of a multi-active scenario: + +![multiple-registry-deployment-architecture](/imgs/v3/concepts/multiple-registry-deployment-architecture.png) \ No newline at end of file diff --git a/content/en/overview/what/dubbo3.md b/content/en/overview/what/dubbo3.md new file mode 100644 index 000000000000..d0516810e0dd --- /dev/null +++ b/content/en/overview/what/dubbo3.md @@ -0,0 +1,94 @@ + +--- +type: docs +title: "Dubbo 3 Quick Facts" +linkTitle: "Dubbo 3 Quick Facts" +weight: 2 +--- + +This article will take you to quickly understand the design background, overall architecture and core features of Dubbo3, and its relationship with typical users such as Alibaba HSF2, etc. You can also learn more in the following sections: +* **New users, take a quick look at the core features of Dubbo3:** + * [Next Generation Communication Protocol - Triple](/en/docs3-v2/java-sdk/concepts-and-architecture/triple/) + * [Secrets of a million-instance cluster - application-level service discovery](/en/docs3-v2/java-sdk/concepts-and-architecture/service-discovery/) + * [Dubbo Mesh](/en/docs3-v2/java-sdk/concepts-and-architecture/mesh/) +* **Dubbo3 compatibility and migration cost?** + * [Java - Migration Guide](/en/docs3-v2/java-sdk/upgrades-and-compatibility) + * [Golang - Migration Guide](/en/docs3-v2/golang-sdk/) +* **Dubbo3 related resources:** + * For more information, such as performance indicators, advanced feature descriptions, etc., please refer to [Multilingual SDK Implementation](/en/overview/mannual/) + * Speeches and offline activities + +### background + +The design and development of Dubbo3 has two major backgrounds. + +**First, how to better meet the demands of corporate practice. ** Since Dubbo was donated by Alibaba in 2011, it has been the preferred open source service framework for many large-scale enterprise microservice practices. During this period, the enterprise architecture has undergone changes from the SOA architecture to the microservice architecture, and the Dubbo community itself is constantly updating and iterating to better meet the demands of the enterprise. However, the limitations of Dubbo2 architecture are gradually highlighted in practice: +- **Protocol**, the Dubbo2 protocol is famous for its performance and simplicity, but it encounters more and more problems of versatility and penetration in the cloud-native era; +- **Scalability**, Dubbo2 is still far superior to many other frameworks in terms of scalability, but as microservices bring more applications and instances, we have to think about how to deal with the actual combat of larger-scale clusters; +- **Service Governance Ease of Use**, such as richer traffic governance, observability, intelligent load balancing, etc. + +**Secondly, adapt to the development of cloud native technology stack. ** While microservices make the evolution of business development more flexible and fast, it also brings some unique features and requirements: such as the number of components after microservices is increasing, how to solve the stability of each component, how to quickly Horizontal expansion, etc., cloud-native infrastructure represented by Docker, Kubernetes, and Service Mesh has brought some new options to solve these problems. As more microservice components and capabilities are sinking to the infrastructure layer represented by Kubernetes, the traditional microservice development framework should eliminate some redundant mechanisms and actively adapt to the infrastructure layer to achieve capability reuse. Capabilities such as the life cycle and service governance of the microservice framework should be better integrated with the Kubernetes service orchestration mechanism; the microservice architecture represented by Service Mesh brings new options to microservice development, and Sidecar brings multilingual, transparent upgrades, and traffic control However, it also brings disadvantages such as operation and maintenance complexity and performance loss. Therefore, the traditional microservice system based on the service framework will still be the mainstream, and will still occupy half of the country in the long run, and will maintain mixed deployment for a long time state. + +### Overall objective + +Dubbo3 still maintains the classic architecture of 2.x. Its main responsibility is to solve the communication between microservice processes, and to better manage and control microservice clusters through rich service governance (such as address discovery, traffic management, etc.); The upgrade of the framework is comprehensive, reflected in almost every aspect of the core Dubbo features, through the upgrade to achieve a comprehensive improvement in stability, performance, scalability, and ease of use. + +![architecture-1](/imgs/v3/concepts/architecture-1.png) + +- **Common communication protocol.** The new RPC protocol should abandon the private protocol stack, use the more general HTTP/2 protocol as the transport layer carrier, and use the standardized features of the HTTP protocol to solve the problems of traffic versatility and penetration, so that the protocol can better respond Scenarios such as front-end and back-end docking, gateway proxy, etc.; supports the Stream communication mode, which meets the demands of different business communication models and brings greater throughput to the cluster. +- **For millions of cluster instances, the cluster is highly scalable.** With the promotion of micro-service practices, the scale of micro-service cluster instances is also constantly expanding, which benefits from the characteristics of light-weight micro-services and easy horizontal expansion, but also brings a burden to the entire cluster capacity, especially It is some centralized service governance components; Dubbo3 needs to solve various resource bottlenecks caused by the expansion of instance scale, and realize truly unlimited horizontal expansion. +- **Richer programming model, less business intrusion.** In the development state, the business application is programmed for Dubbo SDK. In the running state, the SDK and the business application run in the same process. The ease of use, stability and resource consumption of the SDK will greatly affect the business application; therefore, 3.0 should have More abstract API, more friendly configuration mode, less encroachment on business application resources, and higher availability. +- **Easier to use and richer service governance capabilities.** The dynamic nature of microservices has brought high complexity to the governance work, and Dubbo has been doing a good job in this regard. It is the earliest batch of governance capability definers and practitioners; 3.0 needs to be oriented to richer scenarios. Provides capabilities such as observability, security, grayscale release, error injection, external configuration, and unified governance rules. +- **Fully embrace cloud native.** + +### Facing the pain points of enterprise production practice + +Dubbo2 is still the preferred open source service framework in China. It is widely used in almost all digital transformation enterprises such as the Internet, financial insurance, software companies, and traditional enterprises, and has been tested in a large-scale production environment. Take Alibaba, a contributor and typical user of Dubbo2, as an example. The HSF2 framework maintained internally by Alibaba based on Dubbo2 has experienced previous double-eleven peak tests. Billions of RPC calls are made every day, and more than ten million service instances are managed. In the long-term optimization and practical accumulation, Alibaba has a vision and plan for the next-generation service framework, and began to evolve rapidly internally, and was quickly contributed to the Apache community. Just like Alibaba, the practical demands of other users are related to Pain points are also rapidly accumulating in the open source community, forming a consistent direction and technical solutions. It can be said that the birth of Dubbo3 comes from the accumulation of a large base of enterprise users, in order to better meet their practical demands. + +![dubbo3-hsf](/imgs/v3/concepts/dubbo-hsf.png) + +Dubbo3 integrates a large amount of service management experience of Alibaba HSF2 and other community enterprises. Currently, Dubbo3 has been fully applied to the production practice environment. Banks, Fenghuodi, Ping An Health, etc. The virtuous circle formed by the cooperation between the community and users has greatly promoted the development of Dubbo3. Alibaba has completely replaced the internally maintained HSF2 framework with the community version of Dubbo3. Their practical experience has promoted the stability of Dubbo3 on the one hand, and is positively It is enough to continuously export the practical experience of service governance to the open source community. + +### For millions of cluster instances, horizontal scalability + +With the accumulation of practical experience in microservices, microservices are split into finer grains and deployed to more and more machine instances to support the growing business scale. Among many Dubbo2 enterprise users, especially large-scale enterprises represented by finance, insurance and the Internet, they began to encounter cluster capacity bottlenecks (for typical cases, please refer to [Industrial and Commercial Bank of China Practice Cases](/zh/users/icbc/)): +* **Service discovery process** + * The data storage scale of the registration center reaches the capacity bottleneck + * Data registration & push efficiency is seriously reduced +* **Dubbo Process** + * Occupy more machine resources, resulting in lower utilization of business resources + * Frequent GC affects business stability + +Dubbo3 solves these problems very well in design. The service governance (service discovery) model implemented through the new design can realize the data transmission and data storage on the service discovery link to reduce by about 90% on average; at the same time, Dubbo3 itself is in the business In the process, it becomes lighter and more stable, achieving a 50% increase in resource utilization. + +A greater advantage of Dubbo3 lies in its improvement of the stability of the overall architecture. The new service discovery architecture makes it easier and more accurate to evaluate the capacity and scalability of the entire cluster. + +![capacity](/imgs/v3/concepts/capacity.png) + +If application development is roughly divided into two levels: business development and operation and maintenance deployment, factors that change frequently include services (interfaces), applications, and machine instances. In the 2.x era, the growth of all these three factors will affect the overall capacity of the microservice cluster, especially the fluctuation caused by the increase or decrease of interfaces, which is very opaque to the overall capacity assessment. In 3.0, the change of cluster capacity is only related to the two factors of application name and machine instance, and the objects of capacity evaluation are often applications and instances, so the entire cluster becomes more stable and transparent. + +### Cloud Native + +In the cloud-native era, changes in the underlying infrastructure are profoundly affecting application deployment, operation and maintenance, and even the development process. It also affects the selection and deployment mode of Dubbo3 microservice technology solutions. + +#### Next Generation RPC Protocol + +The new-generation Triple protocol is based on HTTP/2 as the transport layer, has better gateway and proxy penetration, natively supports Stream communication semantics, and is compatible with the gRPC protocol. + +#### Multilingual Friendly + +Dubbo3 has taken multilingual friendliness as a key consideration in terms of service definition, RPC protocol, serialization, and service governance. Currently, it provides stable multilingual versions of Java and Golang, and 3.0 implementations of more language versions such as Rust , Javascript, C/C++, C#, etc. are under development and construction. + +#### Kubernetes + +Applications developed by Dubbo3 can be natively deployed on the Kubernetes platform. Dubbo3 has been designed to be aligned with container scheduling platforms such as Kubernetes in terms of address and life cycle; for users who want to further reuse the underlying infrastructure capabilities of Kubernetes, Dubbo3 has also been connected to the native The Kubernetes Service system. + +#### Service Mesh + +Service Mesh emphasizes the role of the control plane in microservice governance, which to a certain extent promotes the expansion and standardization of the control plane communication protocol and scope of responsibility; the Sidecar model under the traditional Mesh architecture emphasizes the unified control of traffic by bypass agents to achieve Features such as transparent upgrade, multilingual non-sense, and no business intrusion. + +Dubbo3 provides a Dubbo Mesh solution based on its own thinking, emphasizing the unified management and control of microservice clusters. In terms of deployment architecture, it supports both sicecar and proxyless deployment architecture without sidecar. Users who use Dubbo Mesh are based on their own business Features will have more options for deployment architectures. + +#### Heterogeneous System Interoperability + +We are seeing more and more requests for interoperability of heterogeneous microservice systems, such as Dubbo, Spring Cloud, gRPC, etc. Some are due to the migration of the technology stack, and some are due to the need to achieve business intermodulation after the merger of the organization. With the help of the new service discovery model and the flexible and scalable RPC protocol, Dubbo3 can become the future development goal of Dubbo3. \ No newline at end of file diff --git a/content/en/overview/what/ecosystem.md b/content/en/overview/what/ecosystem.md new file mode 100644 index 000000000000..0fb7d3629efa --- /dev/null +++ b/content/en/overview/what/ecosystem.md @@ -0,0 +1,60 @@ +--- +type: docs +title: "Ecosystem" +linkTitle: "Ecosystem" +weight: 5 +--- +### Dashboard + +* [Dubbo-admin](https://github.com/apache/dubbo-admin) + +### Supported Components and Deployment Architectures + +Dubbo implementations generally support the following products or deployment architectures, and specific multilingual SDK implementations may vary. + +* Registry + * Zookeeper + * [Nacos](https://nacos.io/zh-cn/docs/use-nacos-with-dubbo.html) + * Kubernetes +* Metadata center + * Zookeeper + * [Nacos](https://nacos.io/zh-cn/docs/use-nacos-with-dubbo.html) + * Redis +* Configuration center + * Zookeeper + * [Nacos](https://nacos.io/zh-cn/docs/use-nacos-with-dubbo.html) + * Redis + * Apollo +* Mesh + * Data plane Envoy + * Control plane Istio + +### Protocols and Interoperability +* Interoperability with the gRPC system can be realized based on the Triple protocol +* Based on the REST protocol and application-level service discovery, the interoperability of the Spring Cloud system at the protocol and address discovery levels can be realized + +### SPI Integration +There are many Dubbo extension implementations here, including protocols, serialization, registration centers, etc. +* [dubbo-spi-extensions] + +### Gateway component +* [Apache Shenyu] +* [Apache APISIX] +* [Apache Dubbo-pixiu] +* [Tengine] + +### Link Tracking +* [Zipkin] +* [Apache Skywalking] + +### Other microservice components +* Current Limiting [Sentinel] +* Affairs [Seata] + +### Multilingual implementation +* Golang +* Java +* Rust +* Node +* Python +* PHP \ No newline at end of file diff --git a/content/en/overview/what/extensibility.md b/content/en/overview/what/extensibility.md new file mode 100644 index 000000000000..a66dcfdd7500 --- /dev/null +++ b/content/en/overview/what/extensibility.md @@ -0,0 +1,100 @@ +--- +type: docs +title: "Extensibility" +linkTitle: "Extensibility" +weight: 4 +--- + +## Extended Design Ideas + +Scalability is what any system pursues, and it is equally applicable to Dubbo. + +### What is scalability + +Scalability is a design concept that represents our vision for the future. We hope that based on the existing architecture or design, when some aspects change in the future, we can adapt to this with minimal changes. kind of change. + +### Advantages of Scalability + +The advantage of scalability is mainly manifested in the decoupling between modules, which conforms to the principle of opening and closing, which is open to expansion and closed to modification. When a new function is added to the system, there is no need to modify the structure and code of the existing system, just add an extension. + +### Extended implementation + +Generally speaking, the system will use Factory, IoC, OSGI, etc. to manage the extension (plug-in) life cycle. Considering the applicability of Dubbo, I don't want to strongly rely on IoC containers such as Spring. +And building a small IoC container by myself feels a bit over-designed, so choose the simplest Factory way to manage extensions (plug-ins). In Dubbo, all internal and third-party implementations are equal. + +### Scalability in Dubbo + +* Treat third-party implementations equally. In Dubbo, all internal implementations and third-party implementations are equal, and users can replace the native implementations provided by Dubbo based on their own business needs. +* Each extension point only encapsulates one change factor to maximize reuse. The implementers of each extension point often only care about one thing. If users need to expand, they only need to expand the extension points they care about, which greatly reduces the workload of users. + +## Features of Dubbo extension + +The extension capability in Dubbo is enhanced from the JDK standard SPI extension point discovery mechanism, which improves the following problems of the JDK standard SPI: + +* The JDK standard SPI will instantiate all the implementations of the extension point at one time. If there is an extension implementation, it will take time to initialize, but if it is not used, it will be loaded, which will waste resources. +* If the extension point fails to load, even the name of the extension point cannot be obtained. For example: JDK standard ScriptEngine, get the name of the script type through getName(), but if RubyScriptEngine fails to load the RubyScriptEngine class because the jruby. When the user executes the ruby script, it will report that ruby is not supported, not the real reason for the failure. + +Based on the expansion capabilities provided by Dubbo, users can easily expand other protocols, filters, routes, etc. based on their own needs. The following introduces the characteristics of Dubbo's extension capabilities. + +* Load on demand. Dubbo's extension capability does not instantiate all implementations at once, but instantiates which extension class is used to reduce resource waste. +* Increase the IOC capability of the extended class. Dubbo's extension capability is not just to discover the extension service implementation class, but to go further on this basis. If the attributes of the extension class depend on other objects, Dubbo will automatically complete the injection function of the dependent object. +* Increase the AOP capability of extended classes. Dubbo's extension capability will automatically discover the wrapper class of the extension class, complete the construction of the wrapper class, and enhance the function of the extension class. +* Possess the ability to dynamically select the extension implementation. The Dubbo extension will dynamically select the corresponding extension class at runtime based on parameters, which improves Dubbo's scalability. +* The extension implementation can be sorted. The execution order of the extension implementation can be specified based on user requirements. +* Provides the Adaptive capability of the extension point. This capability enables some extension classes to take effect on the consumer side, and some extension classes to take effect on the provider side. + +From the design goal of Dubbo extension, it can be seen that some features implemented by Dubbo, such as dynamic selection of extension implementation, IOC, AOP, etc., can provide users with very flexible expansion capabilities. + +## Dubbo extension loading process + +The whole process of Dubbo loading extension is as follows: + +![//imgs/v3/concepts/extension-load.png](/imgs/v3/concepts/extension-load.png) + +There are 4 main steps: +* Read and parse configuration files +* Cache all extension implementations +* Based on the extension name executed by the user, instantiate the corresponding extension implementation +* Perform IOC injection of extended instance attributes and instantiate extended wrapper classes to realize AOP features + +## How to use Dubbo's extension capability to expand + +The following takes the extension protocol as an example to illustrate how to use the extension capabilities provided by Dubbo to extend the Triple protocol. + +(1) Place a text file in the protocol implementation jar package: META-INF/dubbo/org.apache.dubbo.remoting.api.WireProtocol +```text +tri=org.apache.dubbo.rpc.protocol.tri.TripleHttp2Protocol +``` + +(2) Implementation class content +```java +@Activate +public class TripleHttp2Protocol extends Http2WireProtocol { + //... +} +``` + +Instructions: Http2WireProtocol implements the WireProtocol interface + +(3) In the Dubbo configuration module, each extension point has a corresponding configuration attribute or label, and the configuration specifies which extension to use. for example: +```text + +``` + +As can be seen from the above expansion steps, the user basically completes the expansion under the black box. + +## Dubbo extended application + +Dubbo's expansion capability is very flexible, and it is ubiquitous in the realization of its own functions. + +![//imgs/v3/concepts/extension-use.png](/imgs/v3/concepts/extension-use.png) + +Dubbo's extensibility makes it easy to divide the Dubbo project into sub-modules one by one to realize the hot-swappable feature. Users can completely replace Dubbo's native implementation based on their own needs to meet their own business needs. + +## scenes to be used + +* If you need to customize the load balancing strategy, you can use Dubbo's scalability. +* If you need to implement a custom registry, you can use Dubbo's extension capabilities. +* If you need to implement custom filters, you can use Dubbo's extension capabilities. + +Dubbo extensions treat internal implementations and third-party implementations equally. For more usage scenarios, see [SPI extension implementation](/en/docs3-v2/java-sdk/reference-manual/spi/description/) \ No newline at end of file diff --git a/content/en/overview/what/overview.md b/content/en/overview/what/overview.md new file mode 100644 index 000000000000..ffb830574e9c --- /dev/null +++ b/content/en/overview/what/overview.md @@ -0,0 +1,105 @@ +--- +type: docs +title: "Introduction to Dubbo" +linkTitle: "Introduction" +weight: 1 +description: "" +--- + +Apache Dubbo is an RPC service development framework, which is used to solve service governance and communication problems under the microservice architecture. It officially provides multi-language SDK implementations such as Java and Golang. Microservices developed using Dubbo are natively capable of remote address discovery and communication with each other. +Using the rich service governance features provided by Dubbo, service governance demands such as service discovery, load balancing, and traffic scheduling can be realized. Dubbo is designed to be highly scalable, and users can easily implement various custom logics for traffic interception and location selection. + +Dubbo3 is defined as a cloud-native-oriented next-generation RPC service framework. 3.0 has evolved based on Dubbo 2.x. While maintaining the original core features, Dubbo3 has improved in ease of use, ultra-large-scale microservice practice, cloud-native infrastructure adaptation, and security. A comprehensive upgrade has been carried out in several major directions such as sex. + +### What is Dubbo + +Apache Dubbo was originally donated by Alibaba as an open source in 2008, and soon became the de facto standard framework for the selection of open source service frameworks in China, and has been widely used in various industries. In 2017, Dubbo officially donated to the Apache Software Foundation and became a top-level project of Apache. Currently, Dubbo3 is already a one-stop microservice solution providing: +* HTTP/2-based [Triple protocol](/en/docs3-v2/java-sdk/concepts-and-architecture/triple/) and programming experience for proxy API. +* Powerful [traffic management capability] (../../tasks/traffic-management), such as address discovery, load balancing, routing address selection, dynamic configuration, etc. +* [Multi-language SDK implementation](../../mannual/), covering Java, Golang, Javascript, etc. More language implementations will be released in succession. +* Flexible adaptation and expansion capabilities, which can be easily adapted to other components of the microservice system such as Tracing and Transaction. +* [Dubbo Mesh Solution](/en/docs3-v2/java-sdk/concepts-and-architecture/mesh/), while supporting flexible Mesh deployment solutions such as Sidecar and Proxyless. + +The overall architecture of Apache Dubbo can well meet the large-scale microservice practice of enterprises, because it is designed to solve the practical problems of ultra-large-scale microservice clusters from the beginning, whether it is Alibaba, ICBC, China Ping An, Ctrip and other community users, They have fully verified the stability and performance of Dubbo through years of large-scale production environment traffic. Therefore, Dubbo has unparalleled advantages in solving business landing and large-scale practice: +* out of the box + * High ease of use, such as the interface-oriented proxy feature of the Java version can realize local transparent calls + * Rich in functions, most of the microservice governance capabilities can be realized based on native libraries or lightweight extensions +* Designed for ultra-large-scale microservice clusters + * Extreme performance, high-performance RPC communication protocol design and implementation + * Horizontally scalable, easily supporting address discovery and traffic management of millions of cluster instances +* [highly extensible](../extensibility) + * Interception and extension of traffic and protocols during calling, such as Filter, Router, LB, etc. + * Extension of microservice governance components, such as Registry, Config Center, Metadata Center, etc. +* Enterprise-level microservice governance capabilities + * The de facto standard service framework supported by domestic public cloud vendors + * Years of enterprise practical experience test, refer to [user practice case](../../../users) + +### Dubbo basic workflow + +![dubbo-rpc](/imgs/v3/concepts/rpc.png) + +First of all, Dubbo is an RPC framework, which defines its own RPC communication protocol and programming method. As shown in the figure above, when using Dubbo, users first need to define the Dubbo service; secondly, after deploying the Dubbo service online, rely on Dubbo's application layer communication protocol to realize data exchange, and the data transmitted by Dubbo must be serialized. And here the serialization protocol is fully extensible. +The first step in using Dubbo is to define Dubbo services. The definition of services in Dubbo is a set of methods to complete business functions. You can choose to define them in a way that is bound to a certain language. For example, in Java, Dubbo services have a set of The Interface interface of the method can also use the language-neutral Protobuf Buffers [IDL definition service](../../tasks/triple/idl/). After the service is defined, the server (Provider) needs to provide a specific implementation of the service and declare it as a Dubbo service. From the perspective of the service consumer (Consumer), a service proxy can be obtained by calling the API provided by the Dubbo framework ( stub) object, and then you can call the service method like a local service. +After the consumer initiates a call to the service method, the Dubbo framework is responsible for sending the request to the service provider deployed on the remote machine. After receiving the request, the provider will call the implementation class of the service, and then return the processing result to the consumer. This completes a complete service call. The data flow of Request and Response in the figure is shown. +> It should be noted that in Dubbo, when we refer to services, we usually refer to RPC-grained interfaces or methods that provide the function of adding, deleting, and modifying a specific business, which is not the same as the services generally referred to in some microservice concept books concept. + +In a distributed system, especially with the development of the microservice architecture, the deployment, release, and scaling of applications become extremely frequent. As an RPC consumer, how to dynamically discover the address of the service provider becomes a precondition for RPC communication . Dubbo provides an automatic address discovery mechanism to deal with the dynamic migration of machine instances in distributed scenarios. As shown in the figure below, the address of the provider and the consumer is coordinated by introducing the registration center. After the provider starts, it registers its own address with the registration center, and the consumer dynamically perceives the address list of the provider by pulling or subscribing to a specific node in the registration center. Variety. + +![arch-service-discovery](/imgs/architecture.png) + +### Dubbo core features + +#### High performance RPC communication protocol +Service communication across processes or hosts is a basic capability of Dubbo. Dubbo RPC sends the request data (Request) to the backend service in a predefined protocol encoding method, and receives the calculation result (Response) returned by the server. RPC communication is completely transparent to the user, and the user does not need to care about how and where the request is sent, and only needs to get the correct call result for each call. In addition to the Request-Response communication model in synchronous mode, Dubbo3 also provides a richer selection of communication models: +* Consumer side asynchronous request (Client Side Asynchronous Request-Response) +* Provider side asynchronous execution (Server Side Asynchronous Request-Response) +* Consumer request stream (Request Streaming) +* Provider response stream (Response Streaming) +* Bidirectional Streaming + +For details, please refer to the list of optional protocols implemented by each language SDK or [Triple Protocol](/en/docs3-v2/java-sdk/concepts-and-architecture/triple/) + +#### Automatic service (address) discovery +Dubbo's service discovery mechanism allows microservice components to evolve independently and be deployed arbitrarily, and the consumer can complete communication without knowing the deployment location and IP address of the peer. Dubbo provides a Client-Based service discovery mechanism, and users can enable service discovery in various ways: +* Use independent registry components, such as [Nacos](https://nacos.io/), Zookeeper, Consul, Etcd, etc. +* Leave the organization and registration of services to the underlying container platform, such as Kubernetes, which is understood to be a more cloud-native usage + +#### Run state traffic control +Transparent address discovery allows Dubbo requests to be sent to any IP instance, and traffic is randomly allocated during this process. When richer and finer-grained control of traffic is required, Dubbo's traffic control strategy can be used. Dubbo provides strategies including load balancing, traffic routing, request timeout, traffic degradation, retry, etc., based on these basic capabilities You can easily implement more scenario-based routing solutions, including canary release, A/B testing, weight routing, same-region priority, etc. What's even cooler is that Dubbo supports traffic control policies to take effect dynamically in the running state without redeployment . For details, please refer to: +* [Traffic management example](../../tasks/traffic-management) + +#### Rich extension components and ecology +Dubbo's powerful service governance capabilities are not only reflected in the core framework, but also include its excellent expansion capabilities and the support of surrounding supporting facilities. Through the definition of extension points that exist in almost every key process, such as Filter, Router, and Protocol, we can enrich Dubbo's functions or realize the connection with other microservice supporting systems, including Transaction and Tracing. Currently, there are implementations that extend through SPI For details, please refer to the details of Dubbo extensibility, and you can also find more extension implementations in the [apache/dubbo-spi-extensions](https://github.com/apache/dubbo-spi-extensions) project. For details, please refer to: +* [Dubbo Ecosystem](../../what/ecosystem) +* [Dubbo Extensibility Design](../../what/extensibility) + +#### Cloud Native Design + +Dubbo is designed to fully follow the development concept of cloud-native microservices, which is reflected in many aspects. First, it supports cloud-native infrastructure and deployment architecture, including containers, Kubernetes, etc. The overall solution of Dubbo Mesh is also in version 3.1 Official release; on the other hand, many core components of Dubbo have been upgraded for cloud native, including Triple protocol, unified routing rules, and support for multiple languages. + +It is worth mentioning that how to use Dubbo to support elastic scaling services such as Serverless is also planned in the future, including using Native Image to improve Dubbo's startup speed and resource consumption. + +Combined with the current version, this section mainly expands Dubbo's cloud-native features from the following two points +* [Container Scheduling Platform (Kubernetes)](../../tasks/kubernetes/deploy-on-k8s) +* [Dubbo Mesh](/en/docs3-v2/java-sdk/concepts-and-architecture/mesh/) + +##### Kubernetes +For Dubbo microservices to support Kubernetes platform scheduling, the most basic thing is to realize the alignment of the dubbo service life cycle and the container life cycle, which includes life cycle events such as Dubbo startup, destruction, and service registration. Compared with the past where Dubbo defined life cycle events by itself and required developers to abide by the agreement during operation and maintenance practice, the underlying infrastructure of Kubernetes defines strict component life cycle events (probes), and instead requires Dubbo to adapt according to the agreement. + +Kubernetes Service is another level of adaptation, which reflects the trend of service definition and registration sinking to the cloud-native underlying infrastructure. In this mode, users no longer need to build additional registry components, Dubbo consumer end nodes can automatically connect to Kubernetes (API-Server or DNS), and query the instance list (Kubernetes endpoints) according to the service name (Kubernetes Service Name) . At this point, the service is defined through the standard Kubernetes Service API and dispatched to each node. + +##### Dubbo Mesh + +Service Mesh has been widely disseminated and recognized in the industry, and is considered to be the next-generation microservice architecture, mainly because it solves many difficult problems, including transparent upgrades, multilingualism, dependency conflicts, and traffic management. The typical architecture of Service Mesh is to intercept all egress and ingress traffic by deploying independent Sidecar components, and integrate rich traffic management strategies such as load balancing and routing in Sidecar. In addition, Service Mesh also requires a control plane (Control Panel) to realize the control of Sidecar traffic, that is, to issue various policies. We call this architecture here Classic Mesh. + +However, no technical architecture is perfect, and classic Mesh also faces the problem of high cost at the implementation level +1. Operation and maintenance control panel (Control Panel) is required +2. Need to operate and maintain Sidecar +3. Need to consider how to migrate from the original SDK to Sidecar +4. It is necessary to consider the performance loss of the entire link after introducing Sidecar + +In order to solve the related cost problems introduced by Sidecar, Dubbo introduced and implemented a new Proxyless Mesh architecture. As the name suggests, Proxyless Mesh refers to the deployment without Sidecar, and the Dubbo SDK directly interacts with the control plane. The architecture diagram is as follows + +![dubbo-proxyless](/imgs/v3/mesh/dubbo-proxyless.png) + +It can be imagined that in different organizations and different development stages, microservices built with Dubbo will allow three deployment architectures in the future: traditional SDK, Sidecar-based Service Mesh, and Proxyless Mesh without Sidecar. Based on Sidecar's Service Mesh, that is, the classic Mesh architecture, the independent sidecar runtime takes over all the traffic, separate from the Sidecar's Proxyless Mesh, and the secondary SDK directly communicates with the control plane through xDS. Dubbo microservices allow deployment on physical machines, containers, and Kubernetes platforms, and can use Admin as the control plane and manage them with unified traffic governance rules. \ No newline at end of file diff --git a/content/en/overview/what/usecases.md b/content/en/overview/what/usecases.md new file mode 100644 index 000000000000..2c1090b5cb00 --- /dev/null +++ b/content/en/overview/what/usecases.md @@ -0,0 +1,9 @@ +--- +type: docs +title: "Users" +linkTitle: "Users" +weight: 6 +manualLinkRelref: ../../../users/ +manualLinkTarget: _blank +_build: { render: link } +--- \ No newline at end of file diff --git a/content/en/release/_index.md b/content/en/release/_index.md new file mode 100644 index 000000000000..7636a87c7f11 --- /dev/null +++ b/content/en/release/_index.md @@ -0,0 +1,13 @@ + +--- +type: docs +title: "Releases" +linkTitle: "Releases" +menu: + main: + weight: 30 +--- + + + + diff --git a/content/en/release/dubbo-admin.md b/content/en/release/dubbo-admin.md new file mode 100644 index 000000000000..de99185dd136 --- /dev/null +++ b/content/en/release/dubbo-admin.md @@ -0,0 +1,26 @@ +--- +type: docs +title: "Dubbo Admin" +linkTitle: "Dubbo Admin" +weight: 3 +--- + +## Verify + +You can follow the [steps](https://www.apache.org/info/verification) here, and use the [KEYS](https://downloads.apache.org/dubbo/KEYS) file to verify the download. + +> GitHub: https://github.com/apache/dubbo-admin \ +> Release notes: https://github.com/apache/dubbo-admin/releases +> + +### 0.4.0 (2021-11-21) + +#### Source Release + +* [source](https://www.apache.org/dyn/closer.lua/dubbo/dubbo-admin/0.4.0/apache-dubbo-admin-0.4.0-source-release.zip) | + [asc](https://www.apache.org/dyn/closer.lua/dubbo/dubbo-admin/0.4.0/apache-dubbo-admin-0.4.0-source-release.zip.asc) | + [sha512](https://www.apache.org/dyn/closer.lua/dubbo/dubbo-admin/0.4.0/apache-dubbo-admin-0.4.0-source-release.zip.sha512) + +#### Docker image Release + +* [apache/dubbo-admin:0.4.0](https://hub.docker.com/layers/dubbo-admin/apache/dubbo-admin/0.4.0/images/sha256-17e3a246848c7331a18542b73006fb7c0ec0fda767ee788fc164ad8fa52c0600?context=explore) diff --git a/content/en/release/dubbo-go-pixiu.md b/content/en/release/dubbo-go-pixiu.md new file mode 100644 index 000000000000..5e57f4996c55 --- /dev/null +++ b/content/en/release/dubbo-go-pixiu.md @@ -0,0 +1,14 @@ +--- +type: docs +title: "Dubbo Go Pixiu" +linkTitle: "Dubbo Go Pixiu" +weight: 4 +--- + +## Verify + +You can follow the [steps](https://www.apache.org/info/verification) here, and use the [KEYS](https://downloads.apache.org/dubbo/KEYS) file to verify the download. + +> GitHub: https://github.com/apache/dubbo-go-pixiu \ +> Release notes: https://github.com/apache/dubbo-go-pixiu/releases +> \ No newline at end of file diff --git a/content/en/release/dubbo-spi-extensions.md b/content/en/release/dubbo-spi-extensions.md new file mode 100644 index 000000000000..39421f4d8786 --- /dev/null +++ b/content/en/release/dubbo-spi-extensions.md @@ -0,0 +1,169 @@ +--- +type: docs +title: "Dubbo SPI Extensions" +linkTitle: "Dubbo SPI Extensions" +weight: 5 +--- + +## Verify + +You can follow the [steps](https://www.apache.org/info/verification) here, and use the [KEYS](https://downloads.apache.org/dubbo/KEYS) file to verify the download. + +> GitHub: https://github.com/apache/dubbo-spi-extensions\ +> Release notes: https://github.com/apache/dubbo-spi-extensions/releases +> + +## Dubbo SPI Extensions 1.0.3 (2022-11-28) + +#### Source Release + +* [source](https://www.apache.org/dyn/closer.lua/dubbo/dubbo-spi-extensions/1.0.2/apache-dubbo-extensions-1.0.2-src.zip) | + [asc](https://www.apache.org/dyn/closer.lua/dubbo/dubbo-spi-extensions/1.0.2/apache-dubbo-extensions-1.0.2-src.zip.asc) | + [sha512](https://www.apache.org/dyn/closer.lua/dubbo/dubbo-spi-extensions/1.0.2/apache-dubbo-extensions-1.0.2-src.zip.sha512) + +#### Maven Release + +```xml + + org.apache.dubbo.extensions + ${component_name} + ${component_version} + +``` + +#### Included Components + +- dubbo-cluster-extensions + - dubbo-cluster-broadcast-1:1.0.1 + - dubbo-cluster-loadbalance-peakewma:1.0.1 + - dubbo-cluster-specify-address-dubbo3:1.0.1 + - dubbo-cluster-specify-address-dubbo2:1.0.1 +- dubbo-filter-extensions + - dubbo-filter-seata:1.0.1 +- dubbo-configcenter-extensions + - dubbo-configcenter-consul:1.0.1 + - dubbo-configcenter-etcd:1.0.1 +- dubbo-metadata-report-extensions + - dubbo-metadata-report-consul:1.0.1 +- dubbo-remoting-extensions + - dubbo-remoting-etcd3:1.0.1 + - dubbo-metadata-report-etcd:1.0.1 + - dubbo-remoting-quic:1.0.1 + - dubbo-remoting-grizzly:1.0.1 + - dubbo-remoting-mina:1.0.1 + - dubbo-remoting-p2p:1.0.1 +- dubbo-registry-extensions + - dubbo-registry-dns:1.0.1 + - dubbo-registry-consul:1.0.1 + - dubbo-registry-etcd3:1.0.1 + - dubbo-remoting-redis:1.0.1 + - dubbo-registry-redis:1.0.1 + - dubbo-registry-sofa:1.0.1 + - dubbo-registry-nameservice:1.0.0 +- dubbo-rpc-extensions + - dubbo-rpc-native-thrift:1.0.1 + - dubbo-rpc-http:1.0.1 + - dubbo-rpc-webservice:1.0.1 + - dubbo-rpc-rmi:1.0.1 + - dubbo-rpc-hessian:1.0.1 + - dubbo-rpc-memcached:1.0.1 + - dubbo-rpc-redis:1.0.1 + - dubbo-rpc-rocketmq:1.0.0 +- dubbo-serialization-extensions + - dubbo-serialization-native-hessian:1.0.1 + - dubbo-serialization-protostuff + - dubbo-serialization-protobuf:1.0.1 + - dubbo-serialization-kryo:1.0.1 + - dubbo-serialization-gson:1.0.1 + - dubbo-serialization-fst:1.0.1 + - dubbo-serialization-fastjson:1.0.1 + - dubbo-serialization-avro:1.0.1 + - dubbo-serialization-msgpack:1.0.1 + +## All Dubbo SPI Extensions status + +### dubbo-cluster + +| Module | Version Number | Adapted to Dubbo Version | +| --- |-------|---------------| +| dubbo-cluster-broadcast-1 | 1.0.1 | 2.7.x ~ 3.x.x | +| dubbo-cluster-loadbalance-peakewma | 1.0.1 | 2.7.x ~ 3.x.x | +| dubbo-cluster-specify-address-dubbo2 | 1.0.1 | 2.7.x | +| dubbo-cluster-specify-address-dubbo3 | 1.0.1 | 3.x.x | + +### dubbo-configcenter + +| Module | Version Number | Adapted to Dubbo Version | +| --- |-------|---------------| +| dubbo-configcenter-consul | 1.0.1 | 2.7.x ~ 3.x.x | +| dubbo-configcenter-etcd | 1.0.1 | 2.7.x ~ 3.x.x | + +### dubbo-filter + +| Module | Version Number | Adapted to Dubbo Version | +| --- |-------|---------------| +| dubbo-filter-seata | 1.0.1 | 2.7.x ~ 3.x.x | + +### dubbo-metadata-report + +| Module | Version Number | Adapted to Dubbo Version | +| --- |-------|---------------| +| dubbo-metadata-report-consul | 1.0.1 | 2.7.x ~ 3.x.x | +| dubbo-metadata-report-etcd | 1.0.1 | 2.7.x ~ 3.x.x | + +### dubbo-registry + +| Module | Version Number | Adapted to Dubbo Version | +| --- |-------|---------------| +| dubbo-registry-dns | 1.0.1 | 3.0.1 ~ 3.0.5 | +| dubbo-registry-kubernetes | 1.0.1 | 3.0.1 ~ 3.0.5 | +| dubbo-registry-xds | 1.0.1 | 3.0.1 ~ 3.0.5 | +| dubbo-registry-consul | 1.0.1 | 2.7.x ~ 3.x.x | +| dubbo-registry-etcd3 | 1.0.1 | 2.7.x ~ 3.x.x | +| dubbo-registry-redis | 1.0.1 | 2.7.x ~ 3.x.x | +| dubbo-registry-sofa | 1.0.1 | 2.7.x ~ 3.x.x | +| dubbo-registry-nameservice | 1.0.0 | 2.7.x ~ 3.x.x | + +### dubbo-remoting + +| Module | Version Number | Adapted to Dubbo Version | +| --- |-------|---------------| +| dubbo-remoting-quic | 1.0.1 | 2.7.x ~ 3.x.x | +| dubbo-remoting-etcd3 | 1.0.1 | 2.7.x ~ 3.x.x | +| dubbo-remoting-grizzly | 1.0.1 | 2.7.x ~ 3.x.x | +| dubbo-remoting-mina | 1.0.1 | 2.7.x ~ 3.x.x | +| dubbo-remoting-p2p | 1.0.1 | 2.7.x ~ 3.x.x | +| dubbo-remoting-redis | 1.0.1 | 2.7.x ~ 3.x.x | + +### dubbo-rpc + +| Module | Version Number | Adapted to Dubbo Version | +| --- |-------|---------------| +| dubbo-rpc-native-thrift | 1.0.1 | 2.7.x ~ 3.x.x | +| dubbo-rpc-http | 1.0.1 | 2.7.x ~ 3.x.x | +| dubbo-rpc-webservice | 1.0.1 | 2.7.x ~ 3.x.x | +| dubbo-rpc-rmi | 1.0.1 | 2.7.x ~ 3.x.x | +| dubbo-rpc-hessian | 1.0.1 | 2.7.x ~ 3.x.x | +| dubbo-rpc-memcached | 1.0.1 | 2.7.x ~ 3.x.x | +| dubbo-rpc-redis | 1.0.1 | 2.7.x ~ 3.x.x | +| dubbo-rpc-rocketmq | 1.0.0 | 2.7.x ~ 3.x.x | + +### dubbo-serialization + +| Module | Version Number | Adapted to Dubbo Version | +| --- |-------|---------------| +| dubbo-serialization-protostuff | 1.0.1 | 2.7.x ~ 3.x.x | +| dubbo-serialization-protobuf | 1.0.1 | 2.7.x ~ 3.x.x | +| dubbo-serialization-kryo | 1.0.1 | 2.7.x ~ 3.x.x | +| dubbo-serialization-gson | 1.0.1 | 2.7.x ~ 3.x.x | +| dubbo-serialization-fst | 1.0.1 | 2.7.x ~ 3.x.x | +| dubbo-serialization-fastjson | 1.0.1 | 2.7.x ~ 3.x.x | +| dubbo-serialization-avro | 1.0.1 | 2.7.x ~ 3.x.x | +| dubbo-serialization-hession | 1.0.1 | 2.7.x ~ 3.x.x | +| dubbo-serialization-msgpack | 1.0.1 | 2.7.x ~ 3.x.x | + +### dubbo-plugin + +| Module | Version Number | Adapted to Dubbo Version | +|----------------|-------|--------------| +| dubbo-api-docs | 1.0.0 | 2.7.x | \ No newline at end of file diff --git a/content/en/release/go.md b/content/en/release/go.md new file mode 100644 index 000000000000..fd906370ebb6 --- /dev/null +++ b/content/en/release/go.md @@ -0,0 +1,14 @@ +--- +type: docs +title: "Go SDK" +linkTitle: "Go SDK" +weight: 2 +--- + +## Verify + +You can follow the [steps](https://www.apache.org/info/verification) here, and use the [KEYS](https://downloads.apache.org/dubbo/KEYS) file to verify the download. + +> GitHub: https://github.com/apache/dubbo-go \ +> Release notes: https://github.com/apache/dubbo-go/releases +> \ No newline at end of file diff --git a/content/en/release/java.md b/content/en/release/java.md new file mode 100644 index 000000000000..d86fe771e5f8 --- /dev/null +++ b/content/en/release/java.md @@ -0,0 +1,99 @@ +--- +type: docs +title: "Java SDK" +linkTitle: "Java SDK" +weight: 1 +--- + +## Verify + +You can follow the [steps](https://www.apache.org/info/verification) here, and use the [KEYS](https://downloads.apache.org/dubbo/KEYS) file to verify the download. + +## Apache Dubbo + +Please click to learn about each [version details and upgrade notes](/zh/docsv2.7/user/versions/) + +> GitHub: https://github.com/apache/dubbo \ +> Release notes: https://github.com/apache/dubbo/releases +> + +### 3.2.0-beta.3 (2022-12-22) + +#### Source Release + +* [source](https://www.apache.org/dyn/closer.lua/dubbo/3.2.0-beta.3/apache-dubbo-3.2.0-beta.3-src.zip) | + [asc](https://www.apache.org/dyn/closer.lua/dubbo/3.2.0-beta.3/apache-dubbo-3.2.0-beta.3-src.zip.asc) | + [sha512](https://www.apache.org/dyn/closer.lua/dubbo/3.2.0-beta.3/apache-dubbo-3.2.0-beta.3-src.zip.sha512) + +#### Maven Release + +* [org.apache.dubbo:dubbo:3.2.0-beta.3](https://search.maven.org/artifact/org.apache.dubbo/dubbo/3.2.0-beta.3/jar) + +```xml + + org.apache.dubbo + dubbo + 3.2.0-beta. + +``` + +### 3.1.4 (2022-12-22) + +#### Source Release + +* [source](https://www.apache.org/dyn/closer.lua/dubbo/3.1.4/apache-dubbo-3.1.4-src.zip) | + [asc](https://www.apache.org/dyn/closer.lua/dubbo/3.1.4/apache-dubbo-3.1.4-src.zip.asc) | + [sha512](https://www.apache.org/dyn/closer.lua/dubbo/3.1.4/apache-dubbo-3.1.4-src.zip.sha512) + +#### Maven Release + +* [org.apache.dubbo:dubbo:3.1.4](https://search.maven.org/artifact/org.apache.dubbo/dubbo/3.1.4/jar) + +```xml + + org.apache.dubbo + dubbo + 3.1.4 + +``` + +### 3.0.12 (2022-09-29) + +#### Source Release + +* [source](https://www.apache.org/dyn/closer.lua/dubbo/3.0.12/apache-dubbo-3.0.12-src.zip) | + [asc](https://www.apache.org/dyn/closer.lua/dubbo/3.0.12/apache-dubbo-3.0.12-src.zip.asc) | + [sha512](https://www.apache.org/dyn/closer.lua/dubbo/3.0.12/apache-dubbo-3.0.12-src.zip.sha512) + +#### Maven Release + +* [org.apache.dubbo:dubbo:3.0.12](https://search.maven.org/artifact/org.apache.dubbo/dubbo/3.0.12/jar) + +```xml + + org.apache.dubbo + dubbo + 3.0.12 + +``` + +### 2.7.19 (2022-12-13) + +#### Source Release + +* [source](https://www.apache.org/dyn/closer.lua/dubbo/2.7.19/apache-dubbo-2.7.19-src.zip) | + [asc](https://www.apache.org/dyn/closer.lua/dubbo/2.7.19/apache-dubbo-2.7.19-src.zip.asc) | + [sha512](https://www.apache.org/dyn/closer.lua/dubbo/2.7.19/apache-dubbo-2.7.19-src.zip.sha512) + + +#### Maven Release + +* [org.apache.dubbo:dubbo:2.7.19](https://search.maven.org/artifact/org.apache.dubbo/dubbo/2.7.19/jar) + +```xml + + org.apache.dubbo + dubbo + 2.7.19 + +``` diff --git a/content/en/release/past-releases/_index.md b/content/en/release/past-releases/_index.md new file mode 100644 index 000000000000..e9e690038bfc --- /dev/null +++ b/content/en/release/past-releases/_index.md @@ -0,0 +1,7 @@ +--- +type: docs +title: "Past Releases" +linkTitle: "Past Releases" +weight: 100 +--- + diff --git a/content/en/release/past-releases/dubbo-admin.md b/content/en/release/past-releases/dubbo-admin.md new file mode 100644 index 000000000000..49c03778c118 --- /dev/null +++ b/content/en/release/past-releases/dubbo-admin.md @@ -0,0 +1,19 @@ +--- +type: docs +title: "Dubbo Admin" +linkTitle: "Dubbo Admin" +weight: 3 +--- + +## Verify + +You can follow the [steps](https://www.apache.org/info/verification) here, and use the [KEYS](https://downloads.apache.org/dubbo/KEYS) file to verify the download. + +> GitHub: https://github.com/apache/dubbo-admin \ +> Release notes: https://github.com/apache/dubbo-admin/releases + +### 0.1 (2019-02-15) + +* [source](https://archive.apache.org/dist/incubator/dubbo/dubbo-ops/0.1/apache-dubbo-ops-incubating-0.1-source-release.zip) | + [asc](https://archive.apache.org/dist/incubator/dubbo/dubbo-ops/0.1/apache-dubbo-ops-incubating-0.1-source-release.zip.asc) | + [sha512](https://archive.apache.org/dist/incubator/dubbo/dubbo-ops/0.1/apache-dubbo-ops-incubating-0.1-source-release.zip.sha512) \ No newline at end of file diff --git a/content/en/release/past-releases/dubbo-go-pixiu.md b/content/en/release/past-releases/dubbo-go-pixiu.md new file mode 100644 index 000000000000..5e57f4996c55 --- /dev/null +++ b/content/en/release/past-releases/dubbo-go-pixiu.md @@ -0,0 +1,14 @@ +--- +type: docs +title: "Dubbo Go Pixiu" +linkTitle: "Dubbo Go Pixiu" +weight: 4 +--- + +## Verify + +You can follow the [steps](https://www.apache.org/info/verification) here, and use the [KEYS](https://downloads.apache.org/dubbo/KEYS) file to verify the download. + +> GitHub: https://github.com/apache/dubbo-go-pixiu \ +> Release notes: https://github.com/apache/dubbo-go-pixiu/releases +> \ No newline at end of file diff --git a/content/en/release/past-releases/dubbo-spi-extensions.md b/content/en/release/past-releases/dubbo-spi-extensions.md new file mode 100644 index 000000000000..dacc3b0e1e76 --- /dev/null +++ b/content/en/release/past-releases/dubbo-spi-extensions.md @@ -0,0 +1,107 @@ +--- +type: docs +title: "Dubbo SPI Extensions" +linkTitle: "Dubbo SPI Extensions" +weight: 5 +--- + +## Verify + +You can follow the [steps](https://www.apache.org/info/verification) here, and use the [KEYS](https://downloads.apache.org/dubbo/KEYS) file to verify the download. + +> GitHub: https://github.com/apache/dubbo-spi-extensions\ +> Release notes: https://github.com/apache/dubbo-spi-extensions/releases +> + +## Dubbo SPI Extensions 1.0.2 (2022-08-02) + +#### Source Release + +* [source](https://archive.apache.org/dist/dubbo/dubbo-spi-extensions/1.0.2/apache-dubbo-extensions-1.0.2-src.zip) | + [asc](https://archive.apache.org/dist/dubbo/dubbo-spi-extensions/1.0.2/apache-dubbo-extensions-1.0.2-src.zip.asc) | + [sha512](https://archive.apache.org/dist/dubbo/dubbo-spi-extensions/1.0.2/apache-dubbo-extensions-1.0.2-src.zip.sha512) + +#### Maven Release + +```xml + + org.apache.dubbo.extensions + ${component_name} + ${component_version} + +``` + +#### Included Components + +- dubbo-configcenter-extensions + - dubbo-configcenter-consul:1.0.0 + - dubbo-configcenter-etcd:1.0.0 +- dubbo-filter-extensions + - dubbo-filter-seata:1.0.0 +- dubbo-metadata-report-extensions + - dubbo-metadata-report-consul:1.0.0 + - dubbo-metadata-report-etcd:1.0.0 +- dubbo-registry-extensions + - dubbo-registry-consul:1.0.0 + - dubbo-registry-etcd3:1.0.0 + - dubbo-registry-redis:1.0.0 + - dubbo-registry-sofa:1.0.0 +- dubbo-remoting-extensions + - dubbo-remoting-etcd3:1.0.0 + - dubbo-remoting-grizzly:1.0.0 + - dubbo-remoting-mina:1.0.0 + - dubbo-remoting-p2p:1.0.0 + - dubbo-remoting-redis:1.0.0 +- dubbo-rpc-extensions + - dubbo-rpc-hessian:1.0.0 + - dubbo-rpc-memcached:1.0.0 + - dubbo-rpc-redis:1.0.0 +- dubbo-serialization-extensions + - dubbo-serialization-msgpack:1.0.0 + - dubbo-serialization-native-hession:1.0.0 + +## Dubbo SPI Extensions 1.0.1 (2022-03-14) + +#### Source Release + +* [source](https://archive.apache.org/dist/dubbo/dubbo-spi-extensions/1.0.1/apache-dubbo-extensions-1.0.1-src.zip) | + [asc](https://archive.apache.org/dist/dubbo/dubbo-spi-extensions/1.0.1/apache-dubbo-extensions-1.0.1-src.zip.asc) | + [sha512](https://archive.apache.org/dist/dubbo/dubbo-spi-extensions/1.0.1/apache-dubbo-extensions-1.0.1-src.zip.sha512) + +#### Maven Release + +```xml + + org.apache.dubbo.extensions + ${component_name} + ${component_version} + +``` + +#### Included Components + +- dubbo-api-docs:1.0.0 +- dubbo-cluster-extensions + - dubbo-cluster-broadcast-1:1.0.0 + - dubbo-cluster-loadbalance-peakewma:.1.0.0 + - dubbo-cluster-specify-address-dubbo2:1.0.0 + - dubbo-cluster-specify-address-dubbo3:1.0.0 +- dubbo-registry-extensions + - dubbo-registry-dns:1.0.0 + - dubbo-registry-kubernetes:1.0.0 + - dubbo-registry-xds:1.0.0 +- dubbo-remoting-extensions + - dubbo-remoting-quic:1.0.0 +- dubbo-rpc-extensions + - dubbo-rpc-native-thrift:1.0.0 + - dubbo-rpc-http:1.0.0 + - dubbo-rpc-webservice:1.0.0 + - dubbo-rpc-rmi:1.0.0 +- dubbo-serialization-extensions + - dubbo-serialization-protostuff:1.0.0 + - dubbo-serialization-protobuf:1.0.0 + - dubbo-serialization-kryo:1.0.0 + - dubbo-serialization-gson:1.0.0 + - dubbo-serialization-fst:1.0.0 + - dubbo-serialization-fastjson:1.0.0 + - dubbo-serialization-avro:1.0.0 \ No newline at end of file diff --git a/content/en/release/past-releases/go.md b/content/en/release/past-releases/go.md new file mode 100644 index 000000000000..fd906370ebb6 --- /dev/null +++ b/content/en/release/past-releases/go.md @@ -0,0 +1,14 @@ +--- +type: docs +title: "Go SDK" +linkTitle: "Go SDK" +weight: 2 +--- + +## Verify + +You can follow the [steps](https://www.apache.org/info/verification) here, and use the [KEYS](https://downloads.apache.org/dubbo/KEYS) file to verify the download. + +> GitHub: https://github.com/apache/dubbo-go \ +> Release notes: https://github.com/apache/dubbo-go/releases +> \ No newline at end of file diff --git a/content/en/release/past-releases/java.md b/content/en/release/past-releases/java.md new file mode 100644 index 000000000000..df3b2337f6c9 --- /dev/null +++ b/content/en/release/past-releases/java.md @@ -0,0 +1,565 @@ +--- +type: docs +title: "Java SDK" +linkTitle: "Java SDK" +weight: 1 +--- + +## Verify + +You can follow the [steps](https://www.apache.org/info/verification) here, and use the [KEYS](https://downloads.apache.org/dubbo/KEYS) file to verify the download. + +Please click to learn about each [version details and upgrade notes](/zh/docsv2.7/user/versions/) + +> GitHub: https://github.com/apache/dubbo \ +> Release notes: https://github.com/apache/dubbo/releases +> + +### 3.2.0-beta.3 (2022-12-22) + +#### Source Release + +* [source](https://www.apache.org/dyn/closer.lua/dubbo/3.2.0-beta.3/apache-dubbo-3.2.0-beta.3-src.zip) | + [asc](https://www.apache.org/dyn/closer.lua/dubbo/3.2.0-beta.3/apache-dubbo-3.2.0-beta.3-src.zip.asc) | + [sha512](https://www.apache.org/dyn/closer.lua/dubbo/3.2.0-beta.3/apache-dubbo-3.2.0-beta.3-src.zip.sha512) + +#### Maven Release + +* [org.apache.dubbo:dubbo:3.2.0-beta.3](https://search.maven.org/artifact/org.apache.dubbo/dubbo/3.2.0-beta.3/jar) + +```xml + + org.apache.dubbo + dubbo + 3.2.0-beta. + +``` + +### 3.1.4 (2022-12-22) + +#### Source Release + +* [source](https://www.apache.org/dyn/closer.lua/dubbo/3.1.4/apache-dubbo-3.1.4-src.zip) | + [asc](https://www.apache.org/dyn/closer.lua/dubbo/3.1.4/apache-dubbo-3.1.4-src.zip.asc) | + [sha512](https://www.apache.org/dyn/closer.lua/dubbo/3.1.4/apache-dubbo-3.1.4-src.zip.sha512) + +#### Maven Release + +* [org.apache.dubbo:dubbo:3.1.4](https://search.maven.org/artifact/org.apache.dubbo/dubbo/3.1.4/jar) + +```xml + + org.apache.dubbo + dubbo + 3.1.4 + +``` + +### 3.2.0-beta.2 (2022-11-28) + +#### Source Release + +* [source](https://archive.apache.org/dist/dubbo/3.2.0-beta.2/apache-dubbo-3.2.0-beta.2-src.zip) | + [asc](https://archive.apache.org/dist/dubbo/3.2.0-beta.2/apache-dubbo-3.2.0-beta.2-src.zip.asc) | + [sha512](https://archive.apache.org/dist/dubbo/3.2.0-beta.2/apache-dubbo-3.2.0-beta.2-src.zip.sha512) + +#### Maven Release + +* [org.apache.dubbo:dubbo:3.2.0-beta.2](https://search.maven.org/artifact/org.apache.dubbo/dubbo/3.2.0-beta.2/jar) + +```xml + + org.apache.dubbo + dubbo + 3.2.0-beta.2 + +``` + +### 3.1.3 (2022-11-28) + +#### Source Release + +* [source](https://archive.apache.org/dist/dubbo/3.1.3/apache-dubbo-3.1.3-src.zip) | + [asc](https://archive.apache.org/dist/dubbo/3.1.3/apache-dubbo-3.1.3-src.zip.asc) | + [sha512](https://archive.apache.org/dist/dubbo/3.1.3/apache-dubbo-3.1.3-src.zip.sha512) + +#### Maven Release + +* [org.apache.dubbo:dubbo:3.1.3](https://search.maven.org/artifact/org.apache.dubbo/dubbo/3.1.3/jar) + +```xml + + org.apache.dubbo + dubbo + 3.1.3 + +``` + +### 2.7.18 (2022-09-29) + +#### Source Release + +* [source](https://archive.apache.org/dist/dubbo/2.7.18/apache-dubbo-2.7.18-src.zip) | + [asc](https://archive.apache.org/dist/dubbo/2.7.18/apache-dubbo-2.7.18-src.zip.asc) | + [sha512](https://archive.apache.org/dist/dubbo/2.7.18/apache-dubbo-2.7.18-src.zip.sha512) + + +#### Maven Release + +* [org.apache.dubbo:dubbo:2.7.18](https://search.maven.org/artifact/org.apache.dubbo/dubbo/2.7.18/jar) + +```xml + + org.apache.dubbo + dubbo + 2.7.18 + +``` + +### 3.2.0-beta.1 (2022-11-08) + +#### Source Release + +* [source](https://archive.apache.org/dist/dubbo/3.2.0-beta.1/apache-dubbo-3.2.0-beta.1-src.zip) | + [asc](https://archive.apache.org/dist/dubbo/3.2.0-beta.1/apache-dubbo-3.2.0-beta.1-src.zip.asc) | + [sha512](https://archive.apache.org/dist/dubbo/3.2.0-beta.1/apache-dubbo-3.2.0-beta.1-src.zip.sha512) + +#### Maven Release + +* [org.apache.dubbo:dubbo:3.2.0-beta.1](https://search.maven.org/artifact/org.apache.dubbo/dubbo/3.2.0-beta.1/jar) + +```xml + + org.apache.dubbo + dubbo + 3.2.0-beta.1 + +``` + +### 3.1.2 (2022-11-08) + +#### Source Release + +* [source](https://archive.apache.org/dist/dubbo/3.1.2/apache-dubbo-3.1.2-src.zip) | + [asc](https://archive.apache.org/dist/dubbo/3.1.2/apache-dubbo-3.1.2-src.zip.asc) | + [sha512](https://archive.apache.org/dist/dubbo/3.1.2/apache-dubbo-3.1.2-src.zip.sha512) + +#### Maven Release + +* [org.apache.dubbo:dubbo:3.1.2](https://search.maven.org/artifact/org.apache.dubbo/dubbo/3.1.2/jar) + +```xml + + org.apache.dubbo + dubbo + 3.1.2 + +``` + +### 3.1.1 (2022-09-29) + +#### Source Release + +* [source](https://archive.apache.org/dist/dubbo/3.1.1/apache-dubbo-3.1.1-src.zip) | + [asc](https://archive.apache.org/dist/dubbo/3.1.1/apache-dubbo-3.1.1-src.zip.asc) | + [sha512](https://archive.apache.org/dist/dubbo/3.1.1/apache-dubbo-3.1.1-src.zip.sha512) + +#### Maven Release + +* [org.apache.dubbo:dubbo:3.1.1](https://search.maven.org/artifact/org.apache.dubbo/dubbo/3.1.1/jar) + +```xml + + org.apache.dubbo + dubbo + 3.1.1 + +``` + +### 3.1.0 (2022-08-22) + +#### Source Release + +* [source](https://archive.apache.org/dist/dubbo/3.1.0/apache-dubbo-3.1.0-src.zip) | + [asc](https://archive.apache.org/dist/dubbo/3.1.0/apache-dubbo-3.1.0-src.zip.asc) | + [sha512](https://archive.apache.org/dist/dubbo/3.1.0/apache-dubbo-3.1.0-src.zip.sha512) + +#### Maven Release + +* [org.apache.dubbo:dubbo:3.1.0](https://search.maven.org/artifact/org.apache.dubbo/dubbo/3.1.0/jar) + +```xml + + org.apache.dubbo + dubbo + 3.1.0 + +``` + +### 3.0.11 (2022-08-23) + +#### Source Release + +* [source](https://archive.apache.org/dist/dubbo/3.0.11/apache-dubbo-3.0.11-src.zip) | + [asc](https://archive.apache.org/dist/dubbo/3.0.11/apache-dubbo-3.0.11-src.zip.asc) | + [sha512](https://archive.apache.org/dist/dubbo/3.0.11/apache-dubbo-3.0.11-src.zip.sha512) + +#### Maven Release + +* [org.apache.dubbo:dubbo:3.0.11](https://search.maven.org/artifact/org.apache.dubbo/dubbo/3.0.11/jar) + +```xml + + org.apache.dubbo + dubbo + 3.0.11 + +``` + +### 2.7.17 (2022-08-23) + +#### Source Release + +* [source](https://archive.apache.org/dist/dubbo/2.7.17/apache-dubbo-2.7.17-src.zip) | + [asc](https://archive.apache.org/dist/dubbo/2.7.17/apache-dubbo-2.7.17-src.zip.asc) | + [sha512](https://archive.apache.org/dist/dubbo/2.7.17/apache-dubbo-2.7.17-src.zip.sha512) + + +#### Maven Release + +* [org.apache.dubbo:dubbo:2.7.17](https://search.maven.org/artifact/org.apache.dubbo/dubbo/2.7.17/jar) + +```xml + + org.apache.dubbo + dubbo + 2.7.17 + +``` + +### 2.7.16 (2022-07-06) + +#### Source Release + +* [source](https://archive.apache.org/dist/dubbo/2.7.16/apache-dubbo-2.7.16-src.zip) | + [asc](https://archive.apache.org/dist/dubbo/2.7.16/apache-dubbo-2.7.16-src.zip.asc) | + [sha512](https://archive.apache.org/dist/dubbo/2.7.16/apache-dubbo-2.7.16-src.zip.sha512) + + +#### Maven Release + +* [org.apache.dubbo:dubbo:2.7.16](https://search.maven.org/artifact/org.apache.dubbo/dubbo/2.7.16/jar) + +```xml + + org.apache.dubbo + dubbo + 2.7.16 + +``` + +### 3.0.10 (2022-07-21) + +#### Source Release + +* [source](https://archive.apache.org/dist/dubbo/3.0.10/apache-dubbo-3.0.10-src.zip) | + [asc](https://archive.apache.org/dist/dubbo/3.0.10/apache-dubbo-3.0.10-src.zip.asc) | + [sha512](https://archive.apache.org/dist/dubbo/3.0.10/apache-dubbo-3.0.10-src.zip.sha512) + +#### Maven Release + +* [org.apache.dubbo:dubbo:3.0.10](https://search.maven.org/artifact/org.apache.dubbo/dubbo/3.0.10/jar) + +```xml + + org.apache.dubbo + dubbo + 3.0.10 + +``` + +### 3.0.9 (2022-06-23) + +#### Source Release + +* [source](https://archive.apache.org/dist/dubbo/3.0.9/apache-dubbo-3.0.9-src.zip) | + [asc](https://archive.apache.org/dist/dubbo/3.0.9/apache-dubbo-3.0.9-src.zip.asc) | + [sha512](https://archive.apache.org/dist/dubbo/3.0.9/apache-dubbo-3.0.9-src.zip.sha512) + +#### Maven Release + +* [org.apache.dubbo:dubbo:3.0.9](https://search.maven.org/artifact/org.apache.dubbo/dubbo/3.0.9/jar) + +```xml + + org.apache.dubbo + dubbo + 3.0.9 + +``` + +### 3.0.8 (2022-05-11) + +* [source](https://archive.apache.org/dist/dubbo/3.0.8/apache-dubbo-3.0.8-src.zip) | + [asc](https://archive.apache.org/dist/dubbo/3.0.8/apache-dubbo-3.0.8-src.zip.asc) | + [sha512](https://archive.apache.org/dist/dubbo/3.0.8/apache-dubbo-3.0.8-src.zip.sha512) + +### 3.0.7 (2022-04-01) + +* [source](https://archive.apache.org/dist/dubbo/3.0.7/apache-dubbo-3.0.7-src.zip) | + [asc](https://archive.apache.org/dist/dubbo/3.0.7/apache-dubbo-3.0.7-src.zip.asc) | + [sha512](https://archive.apache.org/dist/dubbo/3.0.7/apache-dubbo-3.0.7-src.zip.sha512) + +### 3.0.6 (2022-02-28) + +* [source](https://archive.apache.org/dist/dubbo/3.0.6/apache-dubbo-3.0.6-src.zip) | + [asc](https://archive.apache.org/dist/dubbo/3.0.6/apache-dubbo-3.0.6-src.zip.asc) | + [sha512](https://archive.apache.org/dist/dubbo/3.0.6/apache-dubbo-3.0.6-src.zip.sha512) + +### 3.0.5 (2021-12-30) + +* [source](https://archive.apache.org/dist/dubbo/3.0.5/apache-dubbo-3.0.5-src.zip) | + [asc](https://archive.apache.org/dist/dubbo/3.0.5/apache-dubbo-3.0.5-src.zip.asc) | + [sha512](https://archive.apache.org/dist/dubbo/3.0.5/apache-dubbo-3.0.5-src.zip.sha512) + +### 2.7.15 (2021-12-29) + +* [source](https://archive.apache.org/dist/dubbo/2.7.15/apache-dubbo-2.7.15-src.zip) | + [asc](https://archive.apache.org/dist/dubbo/2.7.15/apache-dubbo-2.7.15-src.zip.asc) | + [sha512](https://archive.apache.org/dist/dubbo/2.7.15/apache-dubbo-2.7.15-src.zip.sha512) + +### 3.0.4 (2021-10-24) + +* [source](https://archive.apache.org/dist/dubbo/3.0.4/apache-dubbo-3.0.4-src.zip) | + [asc](https://archive.apache.org/dist/dubbo/3.0.4/apache-dubbo-3.0.4-src.zip.asc) | + [sha512](https://archive.apache.org/dist/dubbo/3.0.4/apache-dubbo-3.0.4-src.zip.sha512) + +### 3.0.3 (2021-09-27) + +* [source](https://archive.apache.org/dist/dubbo/3.0.3/apache-dubbo-3.0.3-src.zip) | + [asc](https://archive.apache.org/dist/dubbo/3.0.3/apache-dubbo-3.0.3-src.zip.asc) | + [sha512](https://archive.apache.org/dist/dubbo/3.0.3/apache-dubbo-3.0.3-src.zip.sha512) + +### 2.7.14 (2021-09-20) + +* [source](https://archive.apache.org/dist/dubbo/2.7.14/apache-dubbo-2.7.14-src.zip) | + [asc](https://archive.apache.org/dist/dubbo/2.7.14/apache-dubbo-2.7.14-src.zip.asc) | + [sha512](https://archive.apache.org/dist/dubbo/2.7.14/apache-dubbo-2.7.14-src.zip.sha512) + +### 2.6.11 (2021-09-18) + +* [source](https://archive.apache.org/dist/dubbo/2.6.11/apache-dubbo-2.6.11-source-release.zip) | + [asc](https://archive.apache.org/dist/dubbo/2.6.11/apache-dubbo-2.6.11-source-release.zip.asc) | + [sha512](https://archive.apache.org/dist/dubbo/2.6.11/apache-dubbo-2.6.11-source-release.zip.sha512) + +### 3.0.2.1 (2021-08-23) + +* [source](https://archive.apache.org/dist/dubbo/3.0.2.1/apache-dubbo-3.0.2.1-src.zip) | + [asc](https://archive.apache.org/dist/dubbo/3.0.2.1/apache-dubbo-3.0.2.1-src.zip.asc) | + [sha512](https://archive.apache.org/dist/dubbo/3.0.2.1/apache-dubbo-3.0.2.1-src.zip.sha512) + +### 3.0.2 (2021-08-16) + +* [source](https://archive.apache.org/dist/dubbo/3.0.2/apache-dubbo-3.0.2-src.zip) | + [asc](https://archive.apache.org/dist/dubbo/3.0.2/apache-dubbo-3.0.2-src.zip.asc) | + [sha512](https://archive.apache.org/dist/dubbo/3.0.2/apache-dubbo-3.0.2-src.zip.sha512) + +### 2.7.13 (2021-08-05) + +* [source](https://archive.apache.org/dist/dubbo/2.7.13/apache-dubbo-2.7.13-src.zip) | + [asc](https://archive.apache.org/dist/dubbo/2.7.13/apache-dubbo-2.7.13-src.zip.asc) | + [sha512](https://archive.apache.org/dist/dubbo/2.7.13/apache-dubbo-2.7.13-src.zip.sha512) + +### 3.0.1 (2021-07-02) + +* [source](https://archive.apache.org/dist/dubbo/3.0.1/apache-dubbo-3.0.1-src.zip) | + [asc](https://archive.apache.org/dist/dubbo/3.0.1/apache-dubbo-3.0.1-src.zip.asc) | + [sha512](https://archive.apache.org/dist/dubbo/3.0.1/apache-dubbo-3.0.1-src.zip.sha512) + +### 3.0.0 (2021-06-16) + +* [source](https://archive.apache.org/dist/dubbo/3.0.0/apache-dubbo-3.0.0-src.zip) | + [asc](https://archive.apache.org/dist/dubbo/3.0.0/apache-dubbo-3.0.0-src.zip.asc) | + [sha512](https://archive.apache.org/dist/dubbo/3.0.0/apache-dubbo-3.0.0-src.zip.sha512) + +### 2.7.12 (2021-06-11) + +* [source](https://archive.apache.org/dist/dubbo/2.7.12/apache-dubbo-2.7.12-src.zip) | + [asc](https://archive.apache.org/dist/dubbo/2.7.12/apache-dubbo-2.7.12-src.zip.asc) | + [sha512](https://archive.apache.org/dist/dubbo/2.7.12/apache-dubbo-2.7.12-src.zip.sha512) + + +### 2.7.11 (2021-05-12) + +* [source](https://archive.apache.org/dist/dubbo/2.7.11/apache-dubbo-2.7.11-src.zip) | + [asc](https://archive.apache.org/dist/dubbo/2.7.11/apache-dubbo-2.7.11-src.zip.asc) | + [sha512](https://archive.apache.org/dist/dubbo/2.7.11/apache-dubbo-2.7.11-src.zip.sha512) + +### 2.7.10 (2021-04-08) + +* [source](https://archive.apache.org/dist/dubbo/2.7.10/apache-dubbo-2.7.10-src.zip) | + [asc](https://archive.apache.org/dist/dubbo/2.7.10/apache-dubbo-2.7.10-src.zip.asc) | + [sha512](https://archive.apache.org/dist/dubbo/2.7.10/apache-dubbo-2.7.10-src.zip.sha512) + + +### 2.7.9 (2020-02-23) + +* [source](https://archive.apache.org/dist/dubbo/2.7.9/apache-dubbo-2.7.9-src.zip) | + [asc](https://archive.apache.org/dist/dubbo/2.7.9/apache-dubbo-2.7.9-src.zip.asc) | + [sha512](https://archive.apache.org/dist/dubbo/2.7.9/apache-dubbo-2.7.9-src.zip.sha512) + + +### 2.7.8 (2020-07-28) + +* [source](https://archive.apache.org/dist/dubbo/2.7.8/apache-dubbo-2.7.8-source-release.zip) | + [asc](https://archive.apache.org/dist/dubbo/2.7.8/apache-dubbo-2.7.8-source-release.zip.asc) | + [sha512](https://archive.apache.org/dist/dubbo/2.7.8/apache-dubbo-2.7.8-source-release.zip.sha512) + +### 2.7.7 (2020-05-18) + +* [source](https://archive.apache.org/dist/dubbo/2.7.7/apache-dubbo-2.7.7-src.zip) | + [asc](https://archive.apache.org/dist/dubbo/2.7.7/apache-dubbo-2.7.7-src.zip.asc) | + [sha512](https://archive.apache.org/dist/dubbo/2.7.7/apache-dubbo-2.7.7-src.zip.sha512) + +### 2.7.5 (2019-12-29) + +* [source](https://archive.apache.org/dist/dubbo/2.7.5/apache-dubbo-2.7.5-src.zip) | + [asc](https://archive.apache.org/dist/dubbo/2.7.5/apache-dubbo-2.7.5-src.zip.asc) | + [sha512](https://archive.apache.org/dist/dubbo/2.7.5/apache-dubbo-2.7.5-src.zip.sha512) + +### 2.7.4.1 (2019-10-27) + +* [source](https://archive.apache.org/dist/dubbo/2.7.4.1/apache-dubbo-2.7.4.1-src.zip) | + [asc](https://archive.apache.org/dist/dubbo/2.7.4.1/apache-dubbo-2.7.4.1-src.zip.asc) | + [sha512](https://archive.apache.org/dist/dubbo/2.7.4.1/apache-dubbo-2.7.4.1-src.zip.sha512) + +### 2.7.4 (2019-10-19) + +* [source](https://archive.apache.org/dist/dubbo/2.7.4/apache-dubbo-2.7.4-src.zip) | + [asc](https://archive.apache.org/dist/dubbo/2.7.4/apache-dubbo-2.7.4-src.zip.asc) | + [sha512](https://archive.apache.org/dist/dubbo/2.7.4/apache-dubbo-2.7.4-src.zip.sha512) + +### 2.7.3 (2019-07-19) + +* [source](https://archive.apache.org/dist/dubbo/2.7.3/apache-dubbo-2.7.3-src.zip) | + [asc](https://archive.apache.org/dist/dubbo/2.7.3/apache-dubbo-2.7.3-src.zip.asc) | + [sha512](https://archive.apache.org/dist/dubbo/2.7.3/apache-dubbo-2.7.3-src.zip.sha512) + +### 2.7.2 (2019-06-06) + +* [source](https://archive.apache.org/dist/dubbo/2.7.2/apache-dubbo-2.7.2-src.zip) | + [asc](https://archive.apache.org/dist/dubbo/2.7.2/apache-dubbo-2.7.2-src.zip.asc) | + [sha512](https://archive.apache.org/dist/dubbo/2.7.2/apache-dubbo-2.7.2-src.zip.sha512) + +### 2.7.1 (2019-03-26) + +* [source](https://archive.apache.org/dist/incubator/dubbo/2.7.1/apache-dubbo-incubating-2.7.1-src.zip) | + [asc](https://archive.apache.org/dist/incubator/dubbo/2.7.1/apache-dubbo-incubating-2.7.1-src.zip.asc) | + [sha512](https://archive.apache.org/dist/incubator/dubbo/2.7.1/apache-dubbo-incubating-2.7.1-src.zip.sha512) +* [binary](https://archive.apache.org/dist/incubator/dubbo/2.7.1/apache-dubbo-incubating-2.7.1-bin.zip) | + [asc](https://archive.apache.org/dist/incubator/dubbo/2.7.1/apache-dubbo-incubating-2.7.1-bin.zip.asc) | + [sha512](https://archive.apache.org/dist/incubator/dubbo/2.7.1/apache-dubbo-incubating-2.7.1-bin.zip.sha512) + +### 2.7.0 (2019-01-29) + +* [source](https://archive.apache.org/dist/incubator/dubbo/2.7.0/apache-dubbo-incubating-2.7.0-source-release.zip) | + [asc](https://archive.apache.org/dist/incubator/dubbo/2.7.0/apache-dubbo-incubating-2.7.0-source-release.zip.asc) | + [sha512](https://archive.apache.org/dist/incubator/dubbo/2.7.0/apache-dubbo-incubating-2.7.0-source-release.zip.sha512) +* [binary](https://archive.apache.org/dist/incubator/dubbo/2.7.0/apache-dubbo-incubating-2.7.0-bin-release.zip) | + [asc](https://archive.apache.org/dist/incubator/dubbo/2.7.0/apache-dubbo-incubating-2.7.0-bin-release.zip.asc) | + [sha512](https://archive.apache.org/dist/incubator/dubbo/2.7.0/apache-dubbo-incubating-2.7.0-bin-release.zip.sha512) + +### 2.6.7 (2019-07-15) + +* [source](https://www.apache.org/dyn/closer.lua/dubbo/2.6.7/apache-dubbo-2.6.7-source-release.zip) | + [asc](https://www.apache.org/dyn/closer.lua/dubbo/2.6.7/apache-dubbo-2.6.7-source-release.zip.asc) | + [sha512](https://www.apache.org/dyn/closer.lua/dubbo/2.6.7/apache-dubbo-2.6.7-source-release.zip.sha512) +* [binary](https://www.apache.org/dyn/closer.lua/dubbo/2.6.7/apache-dubbo-2.6.7-bin-release.zip) | + [asc](https://www.apache.org/dyn/closer.lua/dubbo/2.6.7/apache-dubbo-2.6.7-bin-release.zip.asc) | + [sha512](https://www.apache.org/dyn/closer.lua/dubbo/2.6.7/apache-dubbo-2.6.7-bin-release.zip.sha512) + +### 2.6.6 (2019-03-07) + +* [source](https://www.apache.org/dyn/closer.lua/incubator/dubbo/2.6.6/apache-dubbo-incubating-2.6.6-source-release.zip) | + [asc](https://www.apache.org/dyn/closer.lua/incubator/dubbo/2.6.6/apache-dubbo-incubating-2.6.6-source-release.zip.asc) | + [sha512](https://www.apache.org/dyn/closer.lua/incubator/dubbo/2.6.6/apache-dubbo-incubating-2.6.6-source-release.zip.sha512) +* [binary](https://www.apache.org/dyn/closer.lua/incubator/dubbo/2.6.6/apache-dubbo-incubating-2.6.6-bin-release.zip) | + [asc](https://www.apache.org/dyn/closer.lua/incubator/dubbo/2.6.6/apache-dubbo-incubating-2.6.6-bin-release.zip.asc) | + [sha512](https://www.apache.org/dyn/closer.lua/incubator/dubbo/2.6.6/apache-dubbo-incubating-2.6.6-bin-release.zip.sha512) + +### 2.6.5 (2018-11-23) + +* [source](https://archive.apache.org/dist/incubator/dubbo/2.6.5/apache-dubbo-incubating-2.6.5-source-release.zip) | + [asc](https://archive.apache.org/dist/incubator/dubbo/2.6.5/apache-dubbo-incubating-2.6.5-source-release.zip.asc) | + [sha512](https://archive.apache.org/dist/incubator/dubbo/2.6.5/apache-dubbo-incubating-2.6.5-source-release.zip.sha512) +* [binary](https://archive.apache.org/dist/incubator/dubbo/2.6.5/apache-dubbo-incubating-2.6.5-bin-release.zip) | + [asc](https://archive.apache.org/dist/incubator/dubbo/2.6.5/apache-dubbo-incubating-2.6.5-bin-release.zip.asc) | + [sha512](https://archive.apache.org/dist/incubator/dubbo/2.6.5/apache-dubbo-incubating-2.6.5-bin-release.zip.sha512) + +### 2.6.4 (2018-10-08) + +* [source](https://archive.apache.org/dist/incubator/dubbo/2.6.4/apache-dubbo-incubating-2.6.4-source-release.zip) | + [asc](https://archive.apache.org/dist/incubator/dubbo/2.6.4/apache-dubbo-incubating-2.6.4-source-release.zip.asc) | + [sha512](https://archive.apache.org/dist/incubator/dubbo/2.6.4/apache-dubbo-incubating-2.6.4-source-release.zip.sha512) +* [binary](https://archive.apache.org/dist/incubator/dubbo/2.6.4/apache-dubbo-incubating-2.6.4-bin-release.zip) | + [asc](https://archive.apache.org/dist/incubator/dubbo/2.6.4/apache-dubbo-incubating-2.6.4-bin-release.zip.asc) | + [sha512](https://archive.apache.org/dist/incubator/dubbo/2.6.4/apache-dubbo-incubating-2.6.4-bin-release.zip.sha512) + +### 2.6.3 (2018-09-11) + +* [source](https://archive.apache.org/dist/incubator/dubbo/2.6.3/apache-dubbo-incubating-2.6.3-source-release.zip) | + [asc](https://archive.apache.org/dist/incubator/dubbo/2.6.3/apache-dubbo-incubating-2.6.3-source-release.zip.asc) | + [sha512](https://archive.apache.org/dist/incubator/dubbo/2.6.3/apache-dubbo-incubating-2.6.3-source-release.zip.sha512) +* [binary](https://archive.apache.org/dist/incubator/dubbo/2.6.3/apache-dubbo-incubating-2.6.3-bin-release.zip) | + [asc](https://archive.apache.org/dist/incubator/dubbo/2.6.3/apache-dubbo-incubating-2.6.3-bin-release.zip.asc) | + [sha512](https://archive.apache.org/dist/incubator/dubbo/2.6.3/apache-dubbo-incubating-2.6.3-bin-release.zip.sha512) + +### 2.6.2 (2018-06-07) + +* [source](https://archive.apache.org/dist/incubator/dubbo/2.6.2/dubbo-incubating-2.6.2-source-release.zip) | + [asc](https://archive.apache.org/dist/incubator/dubbo/2.6.2/dubbo-incubating-2.6.2-source-release.zip.asc) | + [sha512](https://archive.apache.org/dist/incubator/dubbo/2.6.2/dubbo-incubating-2.6.2-source-release.zip.sha512) +* [binary](https://archive.apache.org/dist/incubator/dubbo/2.6.2/dubbo-incubating-2.6.2-bin-release.zip) | + [asc](https://archive.apache.org/dist/incubator/dubbo/2.6.2/dubbo-incubating-2.6.2-bin-release.zip.asc) | + [sha512](https://archive.apache.org/dist/incubator/dubbo/2.6.2/dubbo-incubating-2.6.2-bin-release.zip.sha512) + +## Dubbo Spring Boot Starter + +> GitHub: https://github.com/apache/incubator-dubbo-spring-boot-project \ +> 发布说明：https://github.com/apache/incubator-dubbo-spring-boot-project/releases + +### 2.7.1 (2019-04-09) + +* [source](https://www.apache.org/dyn/closer.lua/incubator/dubbo/spring-boot-project/2.7.1/apache-dubbo-spring-boot-project-incubating-2.7.1-source-release.zip) | + [asc](https://www.apache.org/dyn/closer.lua/incubator/dubbo/spring-boot-project/2.7.1/apache-dubbo-spring-boot-project-incubating-2.7.1-source-release.zip.asc) | + [sha512](https://www.apache.org/dyn/closer.lua/incubator/dubbo/spring-boot-project/2.7.1/apache-dubbo-spring-boot-project-incubating-2.7.1-source-release.zip.sha512) +* [binary](https://www.apache.org/dyn/closer.lua/incubator/dubbo/spring-boot-project/2.7.1/apache-dubbo-spring-boot-project-incubating-2.7.1-bin-release.zip) | + [asc](https://www.apache.org/dyn/closer.lua/incubator/dubbo/spring-boot-project/2.7.1/apache-dubbo-spring-boot-project-incubating-2.7.1-bin-release.zip.asc) | + [sha512](https://www.apache.org/dyn/closer.lua/incubator/dubbo/spring-boot-project/2.7.1/apache-dubbo-spring-boot-project-incubating-2.7.1-bin-release.zip.sha512) + +### 2.7.0 (2019-02-14) + +* [source](https://archive.apache.org/dist/incubator/dubbo/spring-boot-project/2.7.0/apache-dubbo-spring-boot-project-incubating-2.7.0-source-release.zip) | + [asc](https://archive.apache.org/dist/incubator/dubbo/spring-boot-project/2.7.0/apache-dubbo-spring-boot-project-incubating-2.7.0-source-release.zip.asc) | + [sha512](https://archive.apache.org/dist/incubator/dubbo/spring-boot-project/2.7.0/apache-dubbo-spring-boot-project-incubating-2.7.0-source-release.zip.sha512) +* [binary](https://archive.apache.org/dist/incubator/dubbo/spring-boot-project/2.7.0/apache-dubbo-spring-boot-project-incubating-2.7.0-bin-release.zip) | + [asc](https://archive.apache.org/dist/incubator/dubbo/spring-boot-project/2.7.0/apache-dubbo-spring-boot-project-incubating-2.7.0-bin-release.zip.asc) | + [sha512](https://archive.apache.org/dist/incubator/dubbo/spring-boot-project/2.7.0/apache-dubbo-spring-boot-project-incubating-2.7.0-bin-release.zip.sha512) + +### 0.2.1 (2019-01-27) + +* [source](https://archive.apache.org/dist/incubator/dubbo/spring-boot-project/0.2.1/apache-dubbo-spring-boot-project-incubating-0.2.1-source-release.zip) | + [asc](https://archive.apache.org/dist/incubator/dubbo/spring-boot-project/0.2.1/apache-dubbo-spring-boot-project-incubating-0.2.1-source-release.zip.asc) | + [sha512](https://archive.apache.org/dist/incubator/dubbo/spring-boot-project/0.2.1/apache-dubbo-spring-boot-project-incubating-0.2.1-source-release.zip.sha512) +* [binary](https://archive.apache.org/dist/incubator/dubbo/spring-boot-project/0.2.1/apache-dubbo-spring-boot-project-incubating-0.2.1-bin-release.zip) | + [asc](https://archive.apache.org/dist/incubator/dubbo/spring-boot-project/0.2.1/apache-dubbo-spring-boot-project-incubating-0.2.1-bin-release.zip.asc) | + [sha512](https://archive.apache.org/dist/incubator/dubbo/spring-boot-project/0.2.1/apache-dubbo-spring-boot-project-incubating-0.2.1-bin-release.zip.sha512) + +### 0.1.2 (2019-01-27) + +* [source](https://archive.apache.org/dist/incubator/dubbo/spring-boot-project/0.1.2/apache-dubbo-spring-boot-project-incubating-0.1.2-source-release.zip) | + [asc](https://archive.apache.org/dist/incubator/dubbo/spring-boot-project/0.1.2/apache-dubbo-spring-boot-project-incubating-0.1.2-source-release.zip.asc) | + [sha512](https://archive.apache.org/dist/incubator/dubbo/spring-boot-project/0.1.2/apache-dubbo-spring-boot-project-incubating-0.1.2-source-release.zip.sha512) +* [binary](https://archive.apache.org/dist/incubator/dubbo/spring-boot-project/0.1.2/apache-dubbo-spring-boot-project-incubating-0.1.2-bin-release.zip) | + [asc](https://archive.apache.org/dist/incubator/dubbo/spring-boot-project/0.1.2/apache-dubbo-spring-boot-project-incubating-0.1.2-bin-release.zip.asc) | + [sha512](https://archive.apache.org/dist/incubator/dubbo/spring-boot-project/0.1.2/apache-dubbo-spring-boot-project-incubating-0.1.2-bin-release.zip.sha512) diff --git a/content/zh/docs/advanced/protobuf&interface.md b/content/zh/docs/advanced/protobuf&interface.md index 79fc90bafec5..4e35b34d5738 100644 --- a/content/zh/docs/advanced/protobuf&interface.md +++ b/content/zh/docs/advanced/protobuf&interface.md @@ -143,4 +143,4 @@ message AnchorInfo { ## 5. 社区资料 * 社区主页地址：https://developers.google.cn/protocol-buffers/ * 社区开源地址：https://github.com/google/protobuf -* 相关jar的maven：http://mvnrepository.com/artifact/com.google.protobuf +* 相关jar的maven：https://search.maven.org/search?q=com.google.protobuf diff --git a/content/zh/docs3-v2/java-sdk/upgrades-and-compatibility/protobuf&interface.md b/content/zh/docs3-v2/java-sdk/upgrades-and-compatibility/protobuf&interface.md index 098695027b19..a0b8cc16eab5 100644 --- a/content/zh/docs3-v2/java-sdk/upgrades-and-compatibility/protobuf&interface.md +++ b/content/zh/docs3-v2/java-sdk/upgrades-and-compatibility/protobuf&interface.md @@ -138,4 +138,4 @@ message AnchorInfo { ## 5. 社区资料 * 社区主页地址：https://developers.google.cn/protocol-buffers/ * 社区开源地址：https://github.com/google/protobuf -* 相关jar的maven：http://mvnrepository.com/artifact/com.google.protobuf +* 相关jar的maven：https://search.maven.org/search?q=com.google.protobuf