diff --git a/.github/workflows/build_and_deploy.yml b/.github/workflows/build_and_deploy.yml index 62eb7334d047..b601693aa87a 100644 --- a/.github/workflows/build_and_deploy.yml +++ b/.github/workflows/build_and_deploy.yml @@ -4,11 +4,6 @@ on: push: branches: - master - pull_request: - types: [ opened, synchronize, reopened, closed ] - branches: - - master - jobs: build_and_deploy_job: diff --git a/assets/scss/_styles_project.scss b/assets/scss/_styles_project.scss index a6fb42e0f422..d4d505426bdd 100644 --- a/assets/scss/_styles_project.scss +++ b/assets/scss/_styles_project.scss @@ -42,3 +42,7 @@ assets/scss/_styles_project.scss } } } + +.card-bottom { + margin-bottom: 20px; +} diff --git a/assets/scss/main.scss b/assets/scss/main.scss index 804a78cc887b..7dc275e0bf37 100644 --- a/assets/scss/main.scss +++ b/assets/scss/main.scss @@ -57,4 +57,20 @@ footer { } } +.o-lang-home__list { + & h4 { + margin-bottom: 0.75rem; + } + + & ul { + padding-left: 0.25rem; + padding-bottom: 0.5rem; + list-style: none; + } + + & li { + padding-bottom: 0.25rem; + } +} + @import "styles_project"; \ No newline at end of file diff --git a/config.toml b/config.toml index 0551c9a542aa..e7a91c31357a 100644 --- a/config.toml +++ b/config.toml @@ -105,6 +105,35 @@ url_latest_version = "https://dubbo.apache.org/zh/docs/" version = "v2.x" url = "https://dubbo.apache.org/zh/docsv2.7/" +[[params.versions]] + version = "v3.0(building)" + url = "https://dubbo.apache.org/zh/docs3-building/" + + +# Add Ecosystems +# en_ecosystem_docs_menu = "Advanced Docs" +# cn_ecosystem_docs_menu = "高级文档" +# +# [[params.ecosystems.docs]] +# ecosystem = "Dubbo Java SDK" +# en.docs.url = "https://chickenlj.github.io/incubator-dubbo-website/en/java-sdk/" +# cn.docs.url = "https://chickenlj.github.io/incubator-dubbo-website/cn/java-sdk/" +# +# [[params.ecosystems.docs]] +# ecosystem = "Dubbo Golang SDK" +# en.docs.url = "https://chickenlj.github.io/incubator-dubbo-website/en/golang-sdk/" +# cn.docs.url = "https://chickenlj.github.io/incubator-dubbo-website/cn/golang-sdk/" +# +# [[params.ecosystems.docs]] +# ecosystem = "Dubbo Pixiu" +# en.docs.url = "https://chickenlj.github.io/incubator-dubbo-website/en/pixiu/" +# cn.docs.url = "https://chickenlj.github.io/incubator-dubbo-website/cn/pixiu/" +# +# [[params.ecosystems.docs]] +# ecosystem = "Dubbo Admin" +# en.docs.url = "https://chickenlj.github.io/incubator-dubbo-website/en/admin/" +# cn.docs.url = "https://chickenlj.github.io/incubator-dubbo-website/cn/admin/" + # Repository configuration (URLs for in-page links to opening issues and suggesting changes) github_repo = "https://github.com/apache/dubbo-website" # An optional link to a related project repo. For example, the sibling repository where your product code lives. @@ -128,6 +157,7 @@ sidebar_search_disable = true navbar_logo = true # Set to true to disable the About link in the site footer footer_about_disable = true +navbar_translucent_over_cover_disable = true # Adds a H2 section titled "Feedback" to the bottom of each doc. The responses are sent to Google Analytics as events. # This feature depends on [services.googleAnalytics] and will be disabled if "services.googleAnalytics.id" is not set. diff --git a/content/en/docs/v2.7/user/configuration/xml.md b/content/en/docs/v2.7/user/configuration/xml.md index 25657fa47382..1d6485a5053e 100644 --- a/content/en/docs/v2.7/user/configuration/xml.md +++ b/content/en/docs/v2.7/user/configuration/xml.md @@ -7,7 +7,7 @@ description: "Configure Dubbo with XML" --- -> About the XML configuration items, see：[XML References](../references/xml). If you prefer use API directly instead of using Spring, see [API Configuration](../api). Want an example of how to use configuration, see [Quick Start](../../quick-start). +> About the XML configuration items, see：[XML References](content/old/en/docs/v2.7/user/references/xml). If you prefer use API directly instead of using Spring, see [API Configuration](../api). Want an example of how to use configuration, see [Quick Start](../../quick-start). ## provider.xml demo diff --git a/content/en/docs/v2.7/user/examples/context.md b/content/en/docs/v2.7/user/examples/context.md index 74d0aab94c59..d9a73b89e6d8 100644 --- a/content/en/docs/v2.7/user/examples/context.md +++ b/content/en/docs/v2.7/user/examples/context.md @@ -6,7 +6,7 @@ weight: 19 description: "Dubbo context" --- -All environment information of during the current call will put into the context,and all configuration information will convert the parameters of `URL` instance,Ref to the column of **URL parameters** at the [schema configuration reference book](../references/xml) +All environment information of during the current call will put into the context,and all configuration information will convert the parameters of `URL` instance,Ref to the column of **URL parameters** at the [schema configuration reference book](content/old/en/docs/v2.7/user/references/xml) `RpcContext` is a temporary status recorder of `ThreadLocal`,when accept `RPC` request or send `RPC` request,The `RpcContext` will be changed.Such as: `A` call `B` and `B` call `C`. On `B` machine,before `B` call `C`,the `RpcContext` will record the information of `A` call `B`.After `B` call `C`,the `RpcContext` record the information of `B` call `C`. diff --git a/content/en/docs/v2.7/user/recommend.md b/content/en/docs/v2.7/user/recommend.md index 1d8ae8d2af79..2e0724a65fa0 100644 --- a/content/en/docs/v2.7/user/recommend.md +++ b/content/en/docs/v2.7/user/recommend.md @@ -168,7 +168,7 @@ The Dubbo default value is used if completely not set up , please see the instru ``` -[^1]: Overlay rules for configuration: 1) The method level configuration has a higher priority than the interface level, that is to say,small scope have a high priority 2) Consumer side configuration has a higher priority than provider side, better than global configuration, the last one is the Dubbo hard coded configuration value（[Dubbo configuration introduction](./configuration/properties.md)） +[^1]: Overlay rules for configuration: 1) The method level configuration has a higher priority than the interface level, that is to say,small scope have a high priority 2) Consumer side configuration has a higher priority than provider side, better than global configuration, the last one is the Dubbo hard coded configuration value（[Dubbo configuration introduction](content/old/en/docs/v2.7/user/configuration/properties.md)） [^2]: With the first call, the call will be called 3 times [^3]: How to select a service to call when there are multiple Provider services [^4]: It means that consumer service can call the best provider service, and reduce to call the the slow provider service. diff --git a/content/en/docs/v2.7/user/references/registry/redis.md b/content/en/docs/v2.7/user/references/registry/redis.md index 7a0fab03e2a4..b09ca5f26608 100644 --- a/content/en/docs/v2.7/user/references/registry/redis.md +++ b/content/en/docs/v2.7/user/references/registry/redis.md @@ -73,7 +73,7 @@ A home-brewed service registry server is used in Alibaba instead of redis server ## Installation -Pls. refer to [redis install manual](http://dubbo.apache.org/en-us/docs/admin/install/redis.html) for how to install a redis based registry server. To set it up, specify `dubbo.registry.address` to `redis://127.0.0.1:6379` in `conf/dubbo.properties` for both provider and consumer (you can refer to [quick start](../../quick-start.md)) after install a redis server. +Pls. refer to [redis install manual](http://dubbo.apache.org/en-us/docs/admin/install/redis.html) for how to install a redis based registry server. To set it up, specify `dubbo.registry.address` to `redis://127.0.0.1:6379` in `conf/dubbo.properties` for both provider and consumer (you can refer to [quick start](content/old/en/docs/v2.7/user/quick-start.md)) after install a redis server. [^1]: [Redis](http://redis.io) is a high performance KV cache server diff --git a/content/en/docs/v2.7/user/references/registry/zookeeper.md b/content/en/docs/v2.7/user/references/registry/zookeeper.md index 1f7777e13589..b1ed1ff37ce2 100644 --- a/content/en/docs/v2.7/user/references/registry/zookeeper.md +++ b/content/en/docs/v2.7/user/references/registry/zookeeper.md @@ -142,7 +142,7 @@ Configure single zookeeper to serve as multiple registry servers: ## Zookeeper Installation -Pls. refer to [zookeeper install manual](../../../admin/install/zookeeper.md) for how to install zookeeper based registry server. To set it up, specify `dubbo.registry.address` to `zookeeper://127.0.0.1:2181` in `conf/dubbo.properties` for both provider and consumer (you can refer to [quick start](../../quick-start.md)) after install a zookeeper server. +Pls. refer to [zookeeper install manual](content/old/en/docs/v2.7/admin/install/zookeeper.md) for how to install zookeeper based registry server. To set it up, specify `dubbo.registry.address` to `zookeeper://127.0.0.1:2181` in `conf/dubbo.properties` for both provider and consumer (you can refer to [quick start](content/old/en/docs/v2.7/user/quick-start.md)) after install a zookeeper server. ## Declaration of Reliability diff --git a/content/en/docs/v3.0/languages/erlang/quick-start.md b/content/en/docs/v3.0/languages/erlang/quick-start.md index ce5001af09de..7ac5008c392a 100644 --- a/content/en/docs/v3.0/languages/erlang/quick-start.md +++ b/content/en/docs/v3.0/languages/erlang/quick-start.md @@ -38,7 +38,7 @@ into the project's `apps` directory. ``` ## Consumer configuration -Please reference [Reference Config](./reference.md) +Please reference [Reference Config](content/old/en/docs/v3.0/languages/erlang/reference.md) ## Init dubbolib in your project It is need you diff --git a/content/en/latest/admin/_index.md b/content/en/latest/admin/_index.md new file mode 100755 index 000000000000..58b4141f2fd4 --- /dev/null +++ b/content/en/latest/admin/_index.md @@ -0,0 +1,8 @@ + +--- +type: advanced-docs +title: "admin" +linkTitle: "admin" +weight: 3 +--- + diff --git a/content/en/latest/community/_index.md b/content/en/latest/community/_index.md new file mode 100644 index 000000000000..95c7cbc6bf16 --- /dev/null +++ b/content/en/latest/community/_index.md @@ -0,0 +1,186 @@ +--- +title: Community +menu: + main: + weight: 40 +--- + + +{{% blocks/lead %}} +You may consider contributing more to the following side projects of Apache Dubbo: +{{% /blocks/lead %}} + +{{< blocks/section color="white" height="auto">}} +
+
+
+
+
dubbo-go
+
languages
+

golang implementation

+ GitHub > +
+
+
+
+
+
+
dubbo-js
+
language
+

js implementation

+ GitHub > +
+
+
+
+
+
+
dubbo-php
+
languages
+

php implementation

+ GitHub > +
+
+
+
+
+
+
dubbo-python
+
languages
+

python implementation

+ GitHub > +
+
+
+
+ +
+
+
+
+
dubbo-erlang
+
languages
+

erlang implementation

+ GitHub > +
+
+
+
+
+
+
dubbo-website
+
documentation
+

Dubbo Official Website

+ GitHub > +
+
+
+
+
+
+
dubbo-samples
+
samples
+

Dubbo java samples

+ GitHub > +
+
+
+
+
+
+
dubbo-go-samples
+
samples
+

Dubbo golang samples

+ GitHub > +
+
+
+
+ +
+
+
+
+
dubbo-admin
+
eco-system
+

Dubbo admin console

+ GitHub > +
+
+
+
+
+
+
dubbo-spring-boot
+
eco-system
+

Spring Boot Starter

+ GitHub > +
+
+
+
+
+
+
dubbo-go-hessian2
+
eco-system
+

Hessian2 golang library

+ GitHub > +
+
+
+
+
+
+
dubbo-proxy
+
eco-system
+

Dubbo proxy server

+ GitHub > +
+
+
+
+ +
+
+
+
+
dubbo-hessian-lite
+
eco-system
+

Hessian java library

+ GitHub > +
+
+
+
+
+
+
dubbo-getty
+
eco-system
+

Dubbo-go networking library

+ GitHub > +
+
+
+
+
+
+
dubbo-spi-extensions
+
SPI extensions
+

Dubbo extension collections

+ GitHub > +
+
+
+
+
+
+
dubbo-awesome
+
eco-system
+

Dubbo resource collections

+ GitHub > +
+
+
+
+{{< /blocks/section >}} + diff --git a/content/en/latest/contribution-guidelines/_index.md b/content/en/latest/contribution-guidelines/_index.md new file mode 100755 index 000000000000..b4267abff489 --- /dev/null +++ b/content/en/latest/contribution-guidelines/_index.md @@ -0,0 +1,94 @@ + +--- +type: docs +title: "Dubbo Contribution Guidelines" +linkTitle: "Contribution" +description: "Dubbo Contribution Guidelines" +menu: + main: + weight: 50 +--- + + +## 为 Dubbo 做贡献 + +Dubbo 是在非限制性的 Apache 2.0 许可下发布的，遵循标准的 Github 开发流程，使用Github追踪处理问题，并将 pull request 合并到 master 中。如果您想为 Dubbo 做贡献（即便是一些微小的），请不要犹豫，遵循下面的指导方针。 + +### 联系我们 + +#### 邮件列表 + + +邮件列表是讨论几乎所有与 Dubbo 有关事情的推荐方式。有关如何订阅的详细文档，请参阅[指南](https://github.com/apache/dubbo/wiki/Mailing-list-subscription-guide)。 + +- [dev@dubbo.apache.org](mailto:dev-subscribe@dubbo.apache.org): 开发邮件列表，如果您在使用或开发Dubbo时遇到任何问题，您可以在此提出问题。 +- [commits@dubbo.apache.org](mailto:commits-subscribe@dubbo.apache.org): 所有提交将被发送到这个邮件列表。如果您对Dubbo的发展感兴趣，您可以订阅它。 +- [notification@dubbo.apache.org](mailto:notification-subscribe@dubbo.apache.org): 所有Github [issue](https://github.com/apache/dubbo/issues)和[pull request](https://github.com/apache/dubbo/pulls)的更新都会被发送到这个邮件列表。 + +### 报告问题 + +在报告任何问题时请遵循[模版](https://github.com/apache/dubbo/issues/new?template=dubbo-issue-report-template.md)。 + +### 代码约定 +我们的代码风格几乎和标准 Java 约定一致（流行IDE的默认设置满足这一点），主要有以下附加限制： + +* 如果当前行中有超过 120 个字符，则起一个新的行。 + +* 确保所有新的 .java 文件都有一个简单的 JavaDoc 类注释，其中至少有一个标识创建日期的标签，最好至少有一个关于该类的解释说明。 + +* 将ASF许可注释添加到所有新的 .java 文件（从项目中的现有文件复制） + +* 请确保没有将 @author 标记添加到您所贡献的文件中，因为 Apache 不使用 @author 标记，其他方式（如cvs）将公平地记录所有您的贡献。 + +* 为代码添加一些 JavaDoc，如果您更改命名空间，则需要一些 XSD DOC 元素。 + +* 对于新的特征或重要的修复程序，应该添加单元测试。 + +* 如果没有其他人使用您的分支，请将它与 master（或主项目中的其他目标分支）同步。 + +* 当编写提交消息时，请遵循这些约定，如果您正在修复一个现有问题，请在提交消息的末尾添加 Fixes XXX（其中XXX是问题编号）。 + +### 贡献流程 + +这是一个贡献者工作流程的大致说明： + +* 克隆当前项目 +* 从希望贡献的分支上创新新的分支，通常是 master 分支。 +* 提交您的更改。 +* 确保提交消息的格式正确。 +* 将新分支推送到您克隆的代码库中。 +* 执行检查表 [pull request模版](https://github.com/apache/dubbo/blob/master/PULL_REQUEST_TEMPLATE.md)。 +* 在提交 pull request 请求前, 请将您克隆的代码和远程代码库同步，这样您的 pull request 会简单清晰。具体操作如下： +``` +git remote add upstream git@github.com:apache/dubbo.git +git fetch upstream +git rebase upstream/master +git checkout -b your_awesome_patch +... add some work +git push origin your_awesome_patch +``` +* 提交 pull request 请求到 apache/dubbo 并等待回复。 + +谢谢您的贡献！ + +### 代码风格 + + +我们提供了 IntelliJ idea 的模版文件[dubbo_codestyle_for_idea.xml](https://github.com/apache/dubbo/tree/master/codestyle/dubbo_codestyle_for_idea.xml)，您可以将它导入到IDE。 + +如果使用 Eclipse，可以通过参考该文件手动配置。 + +**注意事项** + +使用 dubbo_codestyle_for_idea.xml 为你的 IDEA 设置代码格式是贡献代码前至关重要的一个步骤，否则你将会无法通过 Travis CI 的代码风格校验，下面几个步骤给你演示了如何配置代码格式： + +1. 进入菜单页 `Editor > Code Style` +2. 在 Code Style 页面的 scheme 菜单中点击 manage profiles 选项 +在下拉列表中选择 `Import Scheme`, 接着选择 `IntelliJ IDEA code style XML` 导入 xml 文件 +3. 输入你的格式名称，方便在不同工程之间进行识别，最后别忘了 ⏎ 来保存更改. + +设置完成后，IDEA 会帮助你自动 reformat 代码 + + + + diff --git a/content/en/latest/contribution-guidelines/committer/_index.md b/content/en/latest/contribution-guidelines/committer/_index.md new file mode 100755 index 000000000000..e68c97ab2eb5 --- /dev/null +++ b/content/en/latest/contribution-guidelines/committer/_index.md @@ -0,0 +1,11 @@ + +--- +type: docs +title: "Committer Guidelines" +linkTitle: "Committer Guidelines" +description: "Dubbo Committer Guidelines" +weight: 2 +--- + + + diff --git a/content/en/latest/contribution-guidelines/committer/apache-dubbo-page_dev.md b/content/en/latest/contribution-guidelines/committer/apache-dubbo-page_dev.md new file mode 100644 index 000000000000..b7cf70f36c4a --- /dev/null +++ b/content/en/latest/contribution-guidelines/committer/apache-dubbo-page_dev.md @@ -0,0 +1,34 @@ +--- +type: docs +title: "官方 Dubbo 主页的维护" +linkTitle: "官方主页" +weight: 5 +--- + + +Apache 有一个官方的网站，用来维护所有的孵化项目的信息。每一个孵化项目在这个网站下都有一个信息页。 +Dubbo 的信息页地址是 [https://incubator.apache.org/projects/dubbo.html](https://incubator.apache.org/projects/dubbo.html)。 + +当项目发生比较大的变化，比如新的 committer 的加入，新的 PMC 的当选，或是新版本的 Release 等，都需要将这些更新信息维护到这个页面。 + +这个官方网站的项目地址是[https://svn.apache.org/repos/asf/incubator/public/trunk](https://svn.apache.org/repos/asf/incubator/public/trunk)。 + +维护这个页面的方法如下： + +1.安装 SVN。若是 Mac OS X 系统或是 Linux 系统，则自带了 SVN。若是 Windows 系统，则请首先自行安装 SVN。 + +2.用 SVN 将这个[项目](https://svn.apache.org/repos/asf/incubator/public/trunk) checkout 下来 。 + +3.修改 content/projects/dubbo.xml 文件，并保存。 + +4.安装 ANT。执行 trunk 目录下的 build.sh 或者 build.bat 脚本构建项目。 + +5.构建完成后，可以用浏览器打开 target/site/projects/dubbo.html 文件，预览修改是否生效。 + +6.用 SVN 的 commit 命令将 dubbo.xml 文件提交到服务器，并且不要提交 dubbo.html 文件（因为服务器端会定时自动构建）。 +此过程会要求输入Apache id和密码。 + +参考: + +1. http://incubator.apache.org/guides/website.html +2. https://svn.apache.org/repos/asf/incubator/public/trunk/README.txt diff --git a/content/en/latest/contribution-guidelines/committer/label-an-issue-guide_dev.md b/content/en/latest/contribution-guidelines/committer/label-an-issue-guide_dev.md new file mode 100644 index 000000000000..fba6232e3d35 --- /dev/null +++ b/content/en/latest/contribution-guidelines/committer/label-an-issue-guide_dev.md @@ -0,0 +1,32 @@ +--- +type: docs +title: "给问题打标签" +linkTitle: "问题标签" +weight: 3 +--- + +如果您正在处理一个问题，请记得**给这个问题标记一个或者多个您认为有意义的标签**。有了标签，其他开发人员就会很轻松地识别出问题，以便对其进行分类并跟踪进度。 + +对于需要编码和发版修复的 issues 和 pull requests，需要您**将其标记为 [milestone](https://github.com/apache/incubator*dubbo/milestones)**。 + +一些常用的标签： + +* 请求帮助 + * help wanted + * good first issue +* 优先级 + * priority/blocker + * priority/high + * priority/low + * priority/normal +* 状态 + * status/need-triage + * status/DO-NOT-MERGE + * status/READY-TO-MERGE + * status/invalid + * status/wontfix +* 类型 + * type/bug + * type/documentation + * type/enhancement + * type/feature diff --git a/content/en/latest/contribution-guidelines/committer/new-committer-guide_dev.md b/content/en/latest/contribution-guidelines/committer/new-committer-guide_dev.md new file mode 100644 index 000000000000..806a5c3f2693 --- /dev/null +++ b/content/en/latest/contribution-guidelines/committer/new-committer-guide_dev.md @@ -0,0 +1,87 @@ +--- +type: docs +title: "Apache 提交者注册流程" +linkTitle: "注册流程" +weight: 1 +--- + + +## 一、Apache 提交者的产生 + +### 项目孵化初始化提交者 + +项目孵化阶段，在孵化项目提案中，会有初始化提交者列表这一选项。确认你是初始化提交者的一员。项目在 apache 孵化器社区投票通过后，提交者可以开始准备注册账户了。可以参看[孵化器 wiki](https://wiki.apache.org/incubator/) + +### 活跃的贡献者被选举为提交者 + +在后期的开发过程中，活跃的贡献者可以被选举为提交者。见[如何成为 committer](https://www.apache.org/dev/new-committers-guide.html#becoming-a-committer) + +## 二、个人开发者提交 ICLA + +### 1、选择 apache id +在[ apache 提交者列表页](http://people.apache.org/committer-index.html)查看已经注册过的 apache id， + +### 2、个人提交者授权协议（ICLA）： +下载[ ICLA 模板](https://www.apache.org/licenses/icla.pdf)，查找可用的 id。将 icla.pdf 个人信息填写正确后打印,签名、扫描、并当做附件发送邮件给秘书 secretary@apache.org，秘书会帮忙创建 apache 用户 id。同时会创建一个 your_id@apache.org 的邮箱，可以在[ apache 提交者列表页](http://people.apache.org/committer-index.html)查看查找用户是否已经创建。 + +### 3、导师帮助提交用户id创建请求 +导师将帮助提交 apache 账户创建请求给 root 邮件组，会有人帮助建立 id。一般需要2天时间账户会建立，请等待并在[ apache 提交者列表页](http://people.apache.org/committer-index.html)查看查找用户是否已经创建。 + +## 三、加入apache开发者组 +1. 登陆 [Apache 账户工具](https://id.apache.org/)，在登陆页面点击"忘记密码"设置始化密码，会有一封密码重置邮件发送到 forward 邮箱(在孵化项目提案中提交的开发者邮件) +2. 关于 apache 邮箱：apache.org 邮箱并没有自己的邮件内容存储服务器。它需要借用其他邮件提供商的邮件内容存储、分发功能。在很多投票环节是建议使用 apache 邮箱的。 + 这里就有一个问题，怎么在其它邮箱里面配置 apache.org 邮箱转发功能： + * 收件箱：收取发送到 apache.org 的邮件。这个在第一步配置好 Apache 账户工具的 forward 邮箱就可以用 forward 邮箱收取邮件了 + * 发件箱：将发出的邮件显示发件邮箱为 apache.org 邮箱。请参考：[设置 apache 邮箱指南](https://reference.apache.org/committer/email)和[ gmail 邮箱设置方式](http://gmailblog.blogspot.com/2009/07/send-mail-from-another-address-without.html)。 其他邮箱服务的设置方式不方便找到，gmail 的最方便，建议换成 gmail 邮箱(不是广告)。 +3. 修改编辑页面的 homepage url，[apache 提交者列表页](http://people.apache.org/committer-index.html)中你的账户能加主页链接。 +4. 修改编辑页面的 github 账户(username)，提交确认后两个小时内会有邮件邀请你加入 github.com/apache-committers 组。这期间可以阅读[ ASF 工作方式](http://www.apache.org/foundation/how-it-works.html#developers)以对 ASF 开发做一些基本了解。 +## 四、提交者获得对项目的写权限 + +[GitBox 账户链接工具](https://gitbox.apache.org/setup/)的操作 + +### Apache账户授权 +按照提示授权对 Apache 账户的 OAuth 协议登入 + +### Github账户授权 +按照提示授权对 github 账户的 OAuth 协议登入 + +### 在 github.com 设置 github 账户两因素授权（2FA） +按照[授权 GitHub 2FA wiki](https://help.github.com/articles/configuring-two-factor-authentication-via-a-totp-mobile-app/) 操作如下： +* 在手机安装 “google 身份验证器” app +* 按照[授权 GitHub 2FA wiki](https://help.github.com/articles/configuring-two-factor-authentication-via-a-totp-mobile-app/) 一步一步操作。 + + 在[两因素授权验证](https://github.com/settings/two_factor_authentication/verify)界面，不建议选择用手机扫描二维码，因为有些手机会扫描不出来。 + 请打开手机 “google 身份验证器” app，点“+”选择“输入提供的秘钥”： 在“账户名” input 框写入 github 账户。在“您的秘钥” input 框写入:打开的网页中 "enter this text code" 链接里面的文本。在 app 中点击"添加" 后，将为此账户生成6位数字动态。将此6位数字写入网页中的文本框，然后点 “Enable”。这样 2FA 就设置成功了。 + +* 退出并重新登陆 github，输入用户名、密码后会多一步动态密码的填写，该动态密码就是 google 身份验证器上面的动态密码 + +* 大概需要半个小时,会有邮件通知你已经加入了 xx project-committers 开发者组。你也可以进入 [apache teams](https://github.com/orgs/apache/teams) 页面查看。 + +* 2FA 提交后，你已经 clone 的项目会有权限校验问题，解决方法为下面二选一： + * 申请 Access Token： + 在 github 上生成 access token 后，指令行需要密码的地方就粘贴token。 + 参考官网[帮助链接一](https://help.github.com/articles/https-cloning-errors/#provide-access-token-if-2fa-enabled)和[帮助链接二](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/) + * 改用 ssh： + 在命令行执行 ssh-keygen 命令， 然后把pub文件中的内容粘贴到 github 上 + +* 注意：一定要保证 github 的 2FA 为 "enable" 状态。当你将 2FA 设置为 "off" 时候，将会被对应的 apache committer 写权限组除名，直到你再次设置成功为止。 + +## 五、其他 + +### The Apache Way +详情请参考 [wiki](http://apache.org/foundation/governance/) + +社区重于代码，如果某问题或者方案没有在社区(邮件列表)讨论过，就当没有发生过 + +### 添加你的名字 + +请访问孵化器[主页](https://incubator.apache.org/projects/dubbo.html)将你的名字添加到上面. 具体可以参考这个[文档](http://dubbo.apache.org/docs/3.0/zh-cn/docs/developers/committer-guide/apache-dubbo-page_dev.html). + +请访问 Dubbo[官方网站](http://dubbo.apache.org/docs/3.0/zh-cn/docs/developers/developers/developers_dev.html) 将你的名字添加到上面. + +### 小福利 + +Jetbrains 给 apache 提交者一个小福利，就是可以免费使用 idea 的全产品系列。具体注册地址为：https://www.jetbrains.com/shop/eform/apache?product=ALL + +### 相关 wiki +https://www.apache.org/dev/new-committers-guide.html diff --git a/content/en/latest/contribution-guidelines/committer/release-guide_dev.md b/content/en/latest/contribution-guidelines/committer/release-guide_dev.md new file mode 100644 index 000000000000..4cf48266147a --- /dev/null +++ b/content/en/latest/contribution-guidelines/committer/release-guide_dev.md @@ -0,0 +1,483 @@ +--- +type: docs +title: "如何准备 Apache Release" +linkTitle: "发版准备" +weight: 2 +--- + + +## 理解 Apache 发布的内容和流程 + +总的来说，Source Release 是 Apache 关注的重点，也是发布的必须内容；而 Binary Release 是可选项，Dubbo 可以选择是否发布二进制包到 Apache 仓库或者发布到 Maven 中央仓库。 + +请参考以下链接，找到更多关于 ASF 的发布指南: + +- [Apache Release Guide](http://www.apache.org/dev/release-publishing) +- [Apache Release Policy](http://www.apache.org/dev/release.html) +- [Maven Release Info](http://www.apache.org/dev/publishing-maven-artifacts.html) + +## 本地构建环境准备 + +主要包括签名工具、Maven 仓库认证相关准备 + +### 安装GPG + +详细文档请参见[这里](https://www.gnupg.org/download/index.html), Mac OS 下配置如下 + +```sh +$ brew install gpg +$ gpg --version #检查版本，应该为2.x +``` + +### 用gpg生成key + +根据提示，生成 key + + ```shell + $ gpg --full-gen-key + gpg (GnuPG) 2.0.12; Copyright (C) 2009 Free Software Foundation, Inc. + This is free software: you are free to change and redistribute it. + There is NO WARRANTY, to the extent permitted by law. + + Please select what kind of key you want: + (1) RSA and RSA (default) + (2) DSA and Elgamal + (3) DSA (sign only) + (4) RSA (sign only) + Your selection? 1 + RSA keys may be between 1024 and 4096 bits long. + What keysize do you want? (2048) 4096 + Requested keysize is 4096 bits + Please specify how long the key should be valid. + 0 = key does not expire + = key expires in n days + w = key expires in n weeks + m = key expires in n months + y = key expires in n years + Key is valid for? (0) + Key does not expire at all + Is this correct? (y/N) y + + GnuPG needs to construct a user ID to identify your key. + + Real name: Robert Burrell Donkin + Email address: rdonkin@apache.org + Comment: CODE SIGNING KEY + You selected this USER-ID: + "Robert Burrell Donkin (CODE SIGNING KEY) " + + Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O + You need a Passphrase to protect your secret key. # 填入密码，以后打包过程中会经常用到 + ``` + +### 查看 key id + +```sh +$ gpg --list-keys +pub rsa4096/28681CB1 2018-04-26 # 28681CB1就是key id +uid [ultimate] liujun (apache-dubbo) +sub rsa4096/D3D6984B 2018-04-26 + +# 通过key id发送public key到keyserver +$ gpg --keyserver pgpkeys.mit.edu --send-key 28681CB1 +# 其中，pgpkeys.mit.edu为随意挑选的keyserver，keyserver列表为：https://sks-keyservers.net/status/，为相互之间是自动同步的，选任意一个都可以。 +``` +如果有多个 public key，设置默认 key。修改`~/.gnupg/gpg.conf` + +```sh +# If you have more than 1 secret key in your keyring, you may want to +# uncomment the following option and set your preferred keyid. +default-key 28681CB1 +``` +如果有多个 public key, 也可以删除无用的 key： + +```sh +### 先删除私钥，再删除公钥 +$ gpg --yes --delete-secret-keys shenglicao2@gmail.com ###老的私钥，指明邮箱即可 +$ gpg --delete-keys 1808C6444C781C0AEA0AAD4C4D6A8007D20DB8A4 +``` + +> PS: 最新版本经过实测，本地没有gpg.conf这个文件，因此如果在执行过程中遇到签名失败，可以参考这个文章：https://blog.csdn.net/wenbo20182/article/details/72850810 或 https://d.sb/2016/11/gpg-inappropriate-ioctl-for-device-errors + +由于公钥服务器没有检查机制，任何人都可以用你的名义上传公钥，所以没有办法保证服务器上的公钥的可靠性。 +通常，你可以在网站上公布一个公钥指纹，让其他人核对下载到的公钥是否为真。 +```sh +# fingerprint参数生成公钥指纹： +$ gpg --fingerprint liujun +pub rsa4096 2019-10-17 [SC] + 1376 A2FF 67E4 C477 5739 09BD 7DB6 8550 D366 E4C0 +uid [ultimate] liujun (CODE SIGNING KEY) +sub rsa4096 2019-10-17 [E] +``` +登录 https://id.apache.org, 将上面的 fingerprint （即 1376 A2FF 67E4 C477 5739 09BD 7DB6 8550 D366 E4C0） +粘贴到自己的用户信息中 OpenPGP Public Key Primary Fingerprint + +### 设置 Apache 中央仓库 + +Dubbo 项目的父 pom 为 Apache pom(2.7.0 以上版本需要，2.6.x 发布版本不需要此操作) + +```xml + +org.apache +apache +19 + +``` + + 添加以下内容到 .m2/settings.xml + 所有密码请使用 [maven-encryption-plugin](http://maven.apache.org/guides/mini/guide-encryption.html)加密后再填入 + +```xml + +... + + + + apache.snapshots.https + + + + + + apache.releases.https + + + + ... + + + gpg.passphrase + + + + +``` + +## 打包&上传 + +### 准备分支 + +从主干分支拉取新分支作为发布分支，如现在要发布$`{release_version}`版本，则从2.6.x拉出新分支`${release_version}-release`，此后`${release_version}` Release Candidates涉及的修改及打标签等都在`${release_version}-release`分支进行，最终发布完成后合入主干分支。 + +### 编译打包 + +首先，在`${release_version}-release`分支验证maven组件打包、source源码打包、签名等是否都正常工作。**2.6.x记得要使用1.6进行编译打包** + +```shell +$ mvn clean install -Prelease +$ mvn deploy +``` + +上述命令将snapshot包推送到maven中央仓库 + +### ~~用maven-release-plugin发布~~ (`废弃`，参考后一步) + +~~先用dryRun验证是否ok~~ + +```shell +$ mvn release:prepare -Prelease -Darguments="-DskipTests" -DautoVersionSubmodules=true -Dusername=YOUR GITHUB ID-DdryRun=true +``` + +~~验证通过后，执行release:prepare~~ + +```shell +$ mvn release:clean +$ mvn release:prepare -Prelease -Darguments="-DskipTests" -DautoVersionSubmodules=true -Dusername=YOUR GITHUB ID -DpushChanges=false +``` + +> 执行release插件时，如果指定了`-DpushChanges=true`, 插件会自动提交到远端的GitHub仓库中，此时就需要输入GitHub的密码，注意不是输入web页面的登录密码，而是一个`Personal access tokens`，获取方式详见[这里](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line) + +> 这里有一点要注意的是tag， 在执行过程中，需要选择发布的artifactId, 下一个版本artifactId以及发布版本的tag, tag默认的是dubbo-parent-xxxx，需要改成dubbo-xxxx + +执行完上述步骤后，你会发现： +1. `source-release.zip` 和 `bin-release.zip`包已经生成在`dubbo-distribution`目录下，请解压并检查文件是否完整 +2. 本地已经打出相应的tag，同时新增一个commit，名叫`[maven-release-plugin] prepare release dubbo-x.x.x` +3. 分支版本自动升级为`${release_version+1}-SNAPSHOT`，同时新增一个commit，名叫`[[maven-release-plugin] prepare for next development iteration` + +> 如果指定了`-DpushChanges=true`, 则本地提交会自动推送到远端的GitHub仓库。根据经验，建议不要指定为true，请设置为false，待本地检查通过之后再手动提交 + +~~执行release:perform，做staging发布~~ + +```shell +$ mvn -Prelease release:perform -Darguments="-DskipTests" -DautoVersionSubmodules=true -Dusername=YOUR GITHUB ID +``` + +此时插件会自动下载远端的tag对应的源码，编译后，将所有Artifacts发布到配置的远程[maven仓库](http://repository.apache.org)，处于staging状态。 + +### 使用mvn deploy进行deploy + +> 要求：maven 3.5+ + +修改pom文件中的版本号，从2.7.x-SNAPSHOT改为2.7.x， 目前有3个地方需要修改。建议全文搜索。 + +```shell +$ mvn clean install -Prelease +$ mvn deploy -Prelease -DskipTests +``` + +所有被deploy到远程[maven仓库](http://repository.apache.org)的Artifacts都会处于staging状态 + +#### 注意点 + +- 在deploy执行过程中，有可能因为网络等原因被中断，如果是这样，可以重新开始执行。 +- deploy执行到maven仓库的时候，请确认下包的总量是否正确。多次出现了包丢失的情况，特别是dubbo-parent包。 + + +## 准备Apache发布 + +1. 准备svn本机环境（Apache使用svn托管项目的发布内容） + +2. 将dubbo checkout到本地目录 + + ```shell + $ svn checkout https://dist.apache.org/repos/dist/dev/dubbo + # 假定本地目录为 ~/apache/dubbo + ``` + +3. 当前发布版本为${release_version}，新建目录 + + ```shell + $ cd ~/apache/dubbo # dubbo svn根目录 + $ mkdir ${release_version} + ``` + +4. 添加public key到[KEYS](https://dist.apache.org/repos/dist/dev/dubbo/KEYS)文件并提交到SVN仓库（第一次做发布的人需要做这个操作，具体操作参考KEYS文件里的说明）。KEYS主要是让参与投票的人在本地导入，用来校验sign的正确性 + + ```sh + $ (gpg --list-sigs && gpg --armor --export ) >> KEYS + ``` + +5. 拷贝`dubbo-distribution/dubbo-apache-release/target`下的source相关的包到svn本地仓库`dubbo/${release_version}` + +6. 生成sha512签名 + + 针对`src.zip` + + ```shell + $ shasum -a 512 apache-dubbo-${release_version}-src.zip >> apache-dubbo-${release_version}-src.zip.sha512 + ``` + + 针对`bin-release.zip`，需要增加`-b`参数，表明是一个二进制文件 + + ```shell + $ shasum -b -a 512 apache-dubbo-${release_version}-bin.zip >> apache-dubbo-${release_version}-bin.zip.sha512 + ``` + + +7. 如果有binary release要同时发布 + + 在`dubbo-distribution/dubbo-apache-release/target`目录下，拷贝`bin.zip`以及`bin.zip.asc`到svn本地仓库`dubbo/${release_version}`，参考第6步，生成sha512签名。 + +8. 提交到Apache svn + + ```shell + $ svn status + $ svn commit -m 'prepare for ${release_version} RC1' + ``` + +9. 关闭Maven的staging仓库 + + 此步骤为发布2.7.0及以上版本必须要的步骤。在此之前请先确保所有的artifact都是ok的。登录http://repository.apache.org，点击左侧的`Staging repositories`，然后搜索Dubbo关键字，会出现一系列的仓库，选择你最近上传的仓库，然后点击上方的Close按钮，这个过程会进行一系列检查，检查通过以后，在下方的Summary标签页上出现一个连接，请保存好这个链接，需要放在接下来的投票邮件当中。链接应该是类似这样的: https://repository.apache.org/content/repositories/orgapachedubbo-1015 + + > 请注意点击Close可能会出现失败，通常是网络原因，只要重试几次就可以了。可以点击Summary旁边的Activity标签来确认。 + +## 验证Release Candidates + +详细的检查列表请参考官方的[check list](https://wiki.apache.org/incubator/IncubatorReleaseChecklist) + +首先，从一下地址下载要发布的Release Candidate到本地环境： + +
+https://dist.apache.org/repos/dist/dev/dubbo/${release_version}/
+
+ +然后，开始验证环节，验证包含但不限于以下内容和形式 + +### 检查签名和hash等信息 + +#### 检查sha512哈希 + +```sh +$ shasum -c apache-dubbo-${release_version}-src.zip.sha512 +$ shasum -c apache-dubbo-${release_version}-bin.zip.sha512 +``` + +#### 检查gpg签名 + +如果是第一次检查，需要首先导入公钥。 + +```sh + $ curl https://dist.apache.org/repos/dist/dev/dubbo/KEYS >> KEYS # download public keys to local directory + $ gpg --import KEYS # import keys + $ gpg —-edit-key liujun + > trust # type trust command +``` +然后使用如下命令检查签名 + + ```sh +gpg --verify apache-dubbo-3.0.4-src.zip.asc apache-dubbo-3.0.4-src.zip +gpg --verify apache-dubbo-3.0.4-bin.zip.asc apache-dubbo-3.0.4-bin.zip + ``` + + +### 检查源码包的文件内容 + +解压缩`apache-dubbo-${release_version}-src.zip`，进行如下检查: + +- DISCLAIMER exists +- LICENSE and NOTICE exists and contents are good +- All files and no binary files exist +- All files has standard ASF License header +- Can compile from source +- All unit tests can pass + ```sh + mvn clean test # This will run all unit tests + # you can also open rat and style plugin to check if every file meets requirements. + mvn clean test -Drat.skip=false -Dcheckstyle.skip=false + ``` +- Release candidates match with corresponding tags, you can find tag link and hash in vote email. + - check the version number in pom.xml are the same + - check there are no extra files or directories in the source package, for example, no empty directories or useless log files，这里需要注意换行符是否一致 + `diff -r a rc_dir tag_dir` + - check the top n tag commits, dive into the related files and check if the source package has the same changes + +### 检查三方依赖的合规性 + +按照Apache基金会合规性规定，源码或者是二进制分发包中均不能包含Category X的依赖，其中就常见的是包含了GPL/LGPL的依赖，即使是传递依赖也不行。因此在发版的时候需要通过以下的命令进行检查： + +```sh +mvn license:add-third-party -Dlicense.useMissingFile +find . -name THIRD-PARTY.txt | xargs grep -E 'GPL|General Public License' | grep -v Apache | grep -v MIT | grep -v CDDL +``` + +如果一个依赖提供了双协议或多重协议，可以选择与Apache最兼容的一个协议。 + +你可以参考此文章：[ASF第三方许可证策](https://apache.org/legal/resolved.html) + + +### 检查二进制包的文件内容 + +解压缩`apache-dubbo-${release_version}-bin.zip`，进行如下检查: + +* Check signatures are good +* LICENSE and NOTICE exists and contents are good + +注意，如果二进制包里面引入了第三方依赖，则需要更新LICENSE，加入第三方依赖的LICENSE，如果第三方依赖的LICENSE是Apache 2.0，并且对应的项目中包含了NOTICE，还需要更新NOTICE文件 + +## 进入投票 + +dubbo毕业之后，投票分只需要一次： + +1. Dubbo社区投票，发起投票邮件到dev@dubbo.apache.org。在社区开发者Review，经过至少72小时并统计到3个同意发版的binding票后（只有PMC的票才是binding），即可进入下一阶段的投票。 + +Dubbo社区投票邮件模板： + +```text +Hello Dubbo Community, + +This is a call for vote to release Apache Dubbo version 2.7.2. + +The release candidates: +https://dist.apache.org/repos/dist/dev/dubbo/2.7.2/ + +The staging repo: +https://repository.apache.org/content/repositories/orgapachedubbo-1005 + +Git tag for the release: +https://github.com/apache/dubbo/tree/dubbo-2.7.2 + +Hash for the release tag: +afab04c53edab38d52275d2a198ea1aff7a4f41e + +Release Notes: +https://github.com/apache/dubbo/releases/tag/untagged-4775c0a22c60fca55118 + +The artifacts have been signed with Key : 28681CB1, which can be found in the keys file: +https://dist.apache.org/repos/dist/dev/dubbo/KEYS + +The vote will be open for at least 72 hours or until necessary number of votes are reached. + +Please vote accordingly: + +[ ] +1 approve +[ ] +0 no opinion +[ ] -1 disapprove with the reason + +Thanks, +The Apache Dubbo Team +``` + + +宣布投票结果模板： +```text +We’ve received 3 +1 binding votes and one +1 non-binding vote: + ++1 binding, Ian Luo ++1 binding, Huxing Zhang ++1 binding, Jun Liu + ++1 non-binding, Jerrick + +I will start to release today. + +Best regards, +The Apache Dubbo Team +``` + +## 正式发布 + +1. 将[dev](https://dist.apache.org/repos/dist/dev/dubbo)目录下的发布包添加到[release](https://dist.apache.org/repos/dist/release/dubbo)目录下，KEYS有更新的，也需要同步更新。 +2. 删除[dev](https://dist.apache.org/repos/dist/dev/dubbo)目录下的发布包 +3. 删除[release](https://dist.apache.org/repos/dist/release/dubbo)目录下上一个版本的发布包，这些包会被自动保存在[这里](https://archive.apache.org/dist/dubbo) +4. 此步骤为发布2.7.0及以上版本必须要的步骤。在此之前请先确保所有的artifact都是ok的。登录http://repository.apache.org，点击左侧的`Staging repositories`，然后搜索Dubbo关键字，会出现一系列的仓库，选择你最近上传的仓库，然后点击上方的Release按钮. +5. 发布GitHub上的[release notes](https://github.com/apache/dubbo/releases) +6. 修改GitHub的Readme文件，将版本号更新到最新发布的版本 +7. 在官网下载[页面](http://dubbo.apache.org/en-us/blog/download.html)上添加最新版本的下载链接。最新的下载链接应该类似[这样](https://www.apache.org/dyn/closer.cgi?path=dubbo/$VERSION/apache-dubbo-$VERSION-source-release.zip). 同时更新以前版本的下载链接，改为类似[这样](https://archive.apache.org/dist/dubbo/$VERSION/apache-dubbo-$VERSION-bin-release.zip). 具体可以参考过往的[下载链接](https://github.com/apache/dubbo-website/blob/asf-site/blog/en-us/download.md) [可以参考] (https://github.com/apache/dubbo-website/pull/887) +8. 合并`${release-version}-release`分支到对应的主干分支， 然后删除相应的release分支，例如: `git push origin --delete 2.7.0-release` +9. 发邮件到 `dev@dubbo.apache.org` + 宣布release邮件模板： + +```text +Hello Community, + +The Apache Dubbo team is pleased to announce that the +2.6.6 has just been released. + +Apache Dubbo™ is a high-performance, java based, open source +RPC framework. Dubbo offers three key functionalities, which include +interface based remote call, fault tolerance & load balancing, and +automatic service registration & discovery. + +Both the source release[1] and the maven binary release[2] are available +now, you can also find the detailed release notes here[3]. + + +If you have any usage questions, or have problems when upgrading or find +any problems about enhancements included in this release, please don’t +hesitate to let us know by sending feedback to this mailing list or filing +an issue on GitHub[4]. + + +[1] http://dubbo.apache.org/en-us/blog/download.html +[2] https://repo1.maven.org/maven2/org/apache/dubbo/dubbo +[3] https://github.com/apache/dubbo/releases +[4] https://github.com/apache/dubbo/issues + +``` + + +## 完成Maven Convenient Binary发布（可选） + +**repository.apache.org** nexus仓库的权限已经申请，参见[jira](https://issues.apache.org/jira/browse/INFRA-16451) + +发布jar包到maven仓库，首先访问[repository.apache.org](https://repository.apache.org), 选择`staging repository`, 点击`release`按钮。等待一段时间之后，在[这里](https://repository.apache.org/content/repositories/releases/org/apache/dubbo/)确认完整性和正确性. 发布到Maven中央仓库则还需要等待一段时间。可以在[这里](https://repo.maven.apache.org/maven2/org/apache/dubbo)进行确认。 + +## FAQ + +#### gpg: signing failed: Inappropriate ioctl for device + +If you've encountered this error, try the following commands: + +``` +export GPG_TTY=$(tty) +``` diff --git a/content/en/latest/contribution-guidelines/committer/website-guide_dev.md b/content/en/latest/contribution-guidelines/committer/website-guide_dev.md new file mode 100644 index 000000000000..99a787f2bd84 --- /dev/null +++ b/content/en/latest/contribution-guidelines/committer/website-guide_dev.md @@ -0,0 +1,11 @@ +--- +type: docs +title: "网站向导" +linkTitle: "网站向导" +weight: 3 +--- + + +1. Apache Dubbo 的网站仓库是 https://github.com/apache/dubbo-website +2. 网站构建完毕后，它会被自动发布到 dubbo.apache.org，您也可以通过 https://selfserve.apache.org 手动触发（需要使用 Apache 账号登陆） + diff --git a/content/en/latest/contribution-guidelines/contributor/_index.md b/content/en/latest/contribution-guidelines/contributor/_index.md new file mode 100755 index 000000000000..720899649032 --- /dev/null +++ b/content/en/latest/contribution-guidelines/contributor/_index.md @@ -0,0 +1,11 @@ + +--- +type: docs +title: "Contributor Guidelines" +linkTitle: "Contributor Guidelines" +description: "Dubbo Contributor Guidelines" +weight: 1 +--- + + + diff --git a/content/en/latest/contribution-guidelines/contributor/become-a-committer_dev.md b/content/en/latest/contribution-guidelines/contributor/become-a-committer_dev.md new file mode 100644 index 000000000000..976f8d8f4edd --- /dev/null +++ b/content/en/latest/contribution-guidelines/contributor/become-a-committer_dev.md @@ -0,0 +1,20 @@ +--- +type: docs +title: "如何成为 Dubbo Committer" +linkTitle: "成为 Committer" +weight: 1 +--- + +每个人都可以成为 Apache 项目的贡献者。作为一个贡献者只是意味着你对项目感兴趣并以某种方式做出贡献，从提出合理的问题（这些问题记录了项目并向开发人员提供反馈）到提供新的特性作为补丁。 + +如果你成为对一个项目有价值的贡献者，你有可能被邀请成为一个 committer。committer 是 ASF（Apache软件基金会）中用来表示提交特定项目的人的术语。它给你带来对项目仓库和资源写的权限。 + +在 Dubbo 社区，如果一个 committer 获得大量的优秀成绩，就可以被邀请加入项目管理委员会（PMC）。 + +当您不熟悉ASF使用的开源的开发过程时，有时难以理解的一点，就是我们更重视社区而不是代码。一个强大而健康的社区将受到尊重，成为一个有趣和有益的地方。更重要的是，一个多元化和健康的社区可以长时间的持续支持代码，即使个别公司在这个领域来来往往，也是如此。 + +更多详细信息可以在[这里](https://community.apache.org/contributors/)找到。 + +### 我可以贡献什么？ + +请参阅[新的贡献者指南](/zh/docs/contribution-guidelines/contributor/new-contributor-guide_dev)。 diff --git a/content/en/latest/contribution-guidelines/contributor/cla-signing-guide_dev.md b/content/en/latest/contribution-guidelines/contributor/cla-signing-guide_dev.md new file mode 100644 index 000000000000..ad5df4088461 --- /dev/null +++ b/content/en/latest/contribution-guidelines/contributor/cla-signing-guide_dev.md @@ -0,0 +1,30 @@ +--- +type: docs +title: "CLA 签署向导" +linkTitle: "CLA 签署向导" +weight: 2 +--- + + +以下情况，需要您签署 Apache ICLA： + +* 在 Dubbo 被捐赠给 Apache 之前，您已经为 Dubbo 作出了很多贡献，并且您以前没有签署过 Alibaba-CLA。 +* 您已经为 Dubbo 作出了很多贡献，并且您被邀请成为 Dubbo 提交者，且之前没有签署过 Alibaba-CLA 或者 Apache ICLA。 + +### 步骤 + +* 下载这篇 [pdf 文档](https://www.apache.org/licenses/icla.pdf) +* 编辑该文档，在必要的空格处填上适当的内容 +* 打印 +* 在打印好的文件上签字 +* 扫描 +* 发送一封邮件到secretary@apache.org，并抄送给private@dubbo.apache.org： + * 邮件标题为“ICLA submission” + * 请在邮件正文附上您的github账号链接 + * 请记得将您的ICLA文档放入邮件的附件里 + +### 空格填写必要说明 + +* Mailing address：首选英文格式的公司地址 +* preferred apache id(s)：如果您被邀请成为一名提交者，那么需要您填写一个apache账号，否则，可以不填 +* notify project：Dubbo（意思就是Dubbo就是通知您签署ICLA的项目） \ No newline at end of file diff --git a/content/en/latest/contribution-guidelines/contributor/dubbo-extension-guide_dev.md b/content/en/latest/contribution-guidelines/contributor/dubbo-extension-guide_dev.md new file mode 100644 index 000000000000..d8c7443c5ddc --- /dev/null +++ b/content/en/latest/contribution-guidelines/contributor/dubbo-extension-guide_dev.md @@ -0,0 +1,53 @@ +--- +type: docs +title: "扩展 Dubbo 向导" +linkTitle: "扩展 Dubbo" +weight: 5 +--- + + +Dubbo 使用微内核+插件的设计模式。内核只负责组装插件，Dubbo 的功能都是由扩展点（插件）实现，这就意味着 Dubbo 的所有功能都可以被用户定制的扩展所替代。 + +### Dubbo 生态系统 + +我们建议您将扩展加入到 Dubbo 生态系统。使用这种模式，可以使 Dubbo 的核心仓库更干净，并且可以减少维护工作。更少的代码也可以提高核心仓库的构建速度。 + +### 依赖 + +要实现您自己的 Dubbo 扩展，通常只需依赖 API jar 就可以满足您的需求。例如： + +```xml + + org.apache.dubbo + dubbo-serialization-api + ${dubbo.version} + +``` + +### Src指导 + +通常，要实现特殊的扩展，只需要参考[开发者指南](http://dubbo.apache.org/#/docs/dev/build.md?lang=en-us)，实现Dubbo必要的接口和合适的扩展即可。除此之外，还有一些其它的事项需要注意： + +1. 良好的测试，您需要编写单元测试和冒烟测试以消除潜在的 bug。 +2. 没有警告，如有不可避免的警告，请使用 @SuppressWarnings 阻止它，但是请不要乱用。 +3. README。添加必要的自述以说明如何使用扩展，以及需要注意的事项。 +4. 许可证：请确保使用Apache License 2.0。 + +### 通知社区 + +1. 提交您的代码到 [github](https://github.com)。 +2. 加入邮件列表（建议）。点击[这里](https://github.com/apache/dubbo/wiki/Mailing-list-subscription-guide)查看如何加入邮件列表。 +3. 发送一封邮件到 dev@incubator.dubbo.apache.org 通知社区。 +4. 通常，发送邮件之后，社区会对您的扩展进行讨论，dubbo 组的管理员会联系您转移您的项目到 dubbo 生态系统。 + +### 转移项目到dubbo生态系统 + +1. dubbo 组的管理员会请您将您的项目的所有者转让给 dubbo。 +2. dubbo 组的管理员会在 dubbo 组下新建一个项目并邀请您加入到这个项目。 +3. 一旦您接受邀请，您可以将您的项目转移到 dubbo 组下的新项目里。 +4. dubbo 组的成员会对您的项目进行代码审查。随后，您可以对这些代码进行改进。 + + + + + diff --git a/content/en/latest/contribution-guidelines/contributor/mailing-list-subscription-guide_dev.md b/content/en/latest/contribution-guidelines/contributor/mailing-list-subscription-guide_dev.md new file mode 100644 index 000000000000..55300068bdd1 --- /dev/null +++ b/content/en/latest/contribution-guidelines/contributor/mailing-list-subscription-guide_dev.md @@ -0,0 +1,87 @@ +--- +type: docs +title: "邮件列表订阅向导" +linkTitle: "邮件组向导" +weight: 3 +--- + + +Apache incubator 的 Dubbo 开发者邮件列表（dev@dubbo.apache.org）已经建立，请随时订阅并参考[^1]获取更多细节。 + +你也可以直接查看[历史邮件](https://lists.apache.org/list.html?dev@dubbo.apache.org) + +下面是一个关于 Dubbo 邮件列表订阅的简短指南： + +1. 发一封邮件到 dev-subscribe@dubbo.apache.org，其内容和标题均可为空。随后，您会收到一封邮件，其内容如下： + +``` +from: dev-help@dubbo.apache.org +reply-to: dev-sc.xxxxxxx.xxxxxxxx-hello=example.com@dubbo.apache.org +to: hello@example.com +date: Sat, Feb 24, 2018 at 3:12 PM +subject: confirm subscribe to dev@dubbo.apache.org +mailed-by: apache.org + +Hi! This is the ezmlm program. I'm managing the +dev@dubbo.apache.org mailing list. + +I'm working for my owner, who can be reached +at dev-owner@dubbo.apache.org. + +To confirm that you would like + + hello@example.com + +added to the dev mailing list, please send +a short reply to this address: + + dev-sc.xxxxxxx.xxxxxxxx-hello=example.com@dubbo.apache.org + +Usually, this happens when you just hit the "reply" button. +If this does not work, simply copy the address and paste it into +the "To:" field of a new message. + +or click here: + mailto:dev-sc.xxxxxxx.xxxxxxxx-hello=example.com@dubbo.apache.org + +... +``` + +2. 直接回复邮件，其内容和标题仍然可以为空，随后，您将再次收到一封邮件，其内容如下： + +``` +from: dev-help@dubbo.apache.org +to: hello@example.com +date: Sat, Feb 24, 2018 at 3:14 PM +subject: WELCOME to dev@dubbo.apache.org +mailed-by: apache.org + +Hi! This is the ezmlm program. I'm managing the +dev@dubbo.apache.org mailing list. + +I'm working for my owner, who can be reached +at dev-owner@dubbo.apache.org. + +Acknowledgment: I have added the address + + hello@example.com + +to the dev mailing list. + +Welcome to dev@dubbo.apache.org! + +Please save this message so that you know the address you are +subscribed under, in case you later want to unsubscribe or change your +subscription address. + +... +``` + +3. 到此，邮件列表订阅完毕，从现在开始，您将收到很多发送到该邮件列表的邮件，如果您有更多的问题，只需发送邮件到dev@dubbo.apache.org，就会有人回答您的问题。 + +4. 如果您想取消订阅，只需发送一封邮件到dev-unsubscribe@dubbo.apache.org，收到回复后，请按其指定步骤执行。 + +> 请注意：dev@dubbo.apache.org是有效的。dev@dubbo.incubator.apache.org已经不再使用。 + +[^1] https://apache.org/foundation/mailinglists.html#subscribing + diff --git a/content/en/latest/contribution-guidelines/contributor/new-contributor-guide_dev.md b/content/en/latest/contribution-guidelines/contributor/new-contributor-guide_dev.md new file mode 100644 index 000000000000..40a96d0fb8a6 --- /dev/null +++ b/content/en/latest/contribution-guidelines/contributor/new-contributor-guide_dev.md @@ -0,0 +1,133 @@ +--- +type: docs +title: "新贡献者向导" +linkTitle: "新手向导" +weight: 2 +--- + + +这篇向导旨在给正在准备向 Dubbo 提交贡献的新手提供指导。 + +### 邮件列表描述 + +邮件列表是 Dubbo 官方推荐的讨论方式，所有与 Dubbo 相关的内容都可以在这里讨论，请点击 [issue](https://github.com/apache/dubbo/issues/1393) 了解更多关于邮件列表订阅的内容 + +如需订阅如下邮件列表，请参考 [邮件列表订阅向导](/zh/docs/contribution-guidelines/contributor/mailing-list-subscription-guide_dev) + +* dev@dubbo.apache.org：开发邮件列表，您在使用或者开发 Dubbo 的过程中遇到的任何问题，都可以在这里进行提问。 +* commits@dubbo.apache.org：所有的提交内容都会推送到这个邮件列表，如果您对 Dubbo 的进展感兴趣，可以订阅这个邮件列表。 +* issues@dubbo.apache.org：所有的 JIRA [issues](https://issues.apache.org/jira/projects/DUBBO/issues) 和修改信息都会推送到这个邮件列表。Dubbo 社区已经决定使用 github issues 代替 JIRA issues，因此大部分 issues 将由 github issues 进行跟踪。JIRA issues 用于跟踪 ASF 相关问题。 + +### 报告问题 + +### 贡献代码 +#### 贡献流程 +此贡献流程适用于所有的Apache Dubbo社区内容，包括但不限于dubbo(主干仓库)、dubbo admin、dubbo website。 + +以下以贡献dubbo(主干仓库)为例，详细说明贡献流程。 + +##### 1. **fork Apache/Dubbo 项目到您的github帐号下** + +##### 2. **克隆您fork的Dubbo代码仓库到您本地** +```shell +git clone ${your fork dubbo repo address，for example：https://github.com/${your github id}/dubbo.git} +cd dubbo +``` + +##### 3. **添加Apache/Dubbo仓库为upstream仓库** +```shell +git remote add upstream https://github.com/apache/dubbo.git + +git remote -v + + origin ${your fork dubbo repo address} (fetch) + origin ${your fork dubbo repo address} (push) + upstream https://github.com/apache/dubbo.git (fetch) + upstream https://github.com/apache/dubbo.git (push) + +git fetch origin +git fetch upstream +``` +##### 4. **我们的工作以issue为驱动，认领一个issue，或者创建一个issue并描述清楚要做什么。** +新人推荐标记为： `good first issue` 的 issue + +##### 5. **选择一个开发的基础分支，通常是 upstream/master， 并基于此创建一个新的本地分支** +upstream/master 分支是目前 2.7.x 版本的开发分支 + +```shell +# 从远程仓库创建分支到本地 +git checkout -b up-dev-issue#${issue-number} upstream/master +``` +为了避免一些不必要的麻烦，我们推荐以 "upstream" 中的分支为基础创建新的本地分支。 +可以以要做的事情的简单描述作为分支名(只要你能看懂就行)，通常情况下我们会把issue号包含到分支名中，例如上面的 checkout 命令中的。 + +##### 6. **在本地新建的开发分支上进行各种修改** +首先请保证您阅读并正确设置Dubbo code style， 相关内容请阅读 [编码规范](#编码规范) 。 + +修改时请保证该本地分支上的修改仅和issue相关，并尽量细化，做到一个分支只修改一件事，一个PR只修改一件事。 + +可以在提交注释中添加"#issue号"，将该提交与issue关联。 + +##### 7. **将您开发完成后的分支，上传到您fork的仓库** +```shell +git push origin up-dev-issue#${issue-number} +``` + +##### 8. **创建 pull request** + +* 参考[pull request template](https://github.com/apache/dubbo/blob/master/PULL_REQUEST_TEMPLATE.md)中的检查列表 + +Dubbo社区将会Review您的Pull Request，并可能提出修改意见，您可以根据修改意见回到步骤6进行修改，并使用步骤7进行重新提交。 + +##### 9. **如果没有问题，Dubbo社区将会把您的修改合并，恭喜您成为Dubbo的贡献者。** + +#### 特别说明: +* 开源项目一般都是以分支的方式工作，每件事情都创建一个分支。 +* 创建分支时，不要从本地仓库里的分支里创建，而是从指向主仓库的远程仓库创建。 +* 不要一直在同一个分支工作， 一个分支只做一件事情，不要在同一个分支做多件事情。 +* 一直在同一分支中修改，提交都会一直在该分支中。这样就会造成每次PR都会带着之前的所有被merge、未被merge的提交。 +* 一件事情可以是一个issue，也可以是一个issue中的部分(issue太大可以拆解)。 +* 一个分支(一件事情)只提一个PR。 +* 提了PR后，如果PR有问题需要修改，可以继续在这个PR关联的分支修改提交。在PR被merge前，向这个分支继提交都会进入这个PR。 +* 如果只是想纯更新代码，可以从主仓库提PR到你fork的仓库， 源选择主仓库里的分支，目标选你fork的仓库的分支。 +* 这种方式更新代码，你fork的仓库中会多一个提交。如果以你fork的仓库中的分支为源创建分支， 这个提交纪录会被带过去并会在PR中， 所以要以主仓库的分支为源创建分支。 +* issue 认领: 在要认领的issue中回复，明确表式你将处理这个issue。这样社区的PMC和Committer会把该issue assign给你。当然认领前先看下这个issue有没有被别人认领了。 + 为了方便，我们可以把认领的回复统一为: **@i will solve it@**， 当然这不是必须的。 + +#### 编码规范 +请按照[CONTRIBUTING.md](https://github.com/apache/dubbo/blob/master/CONTRIBUTING.md)中的编码规范对自己的代码进行检查。 +##### **代码约定** +我们的代码风格几乎和标准 Java 约定一致（流行IDE的默认设置满足这一点），主要有以下附加限制： +* 如果当前行中有超过 120 个字符，则起一个新的行。 +* 确保所有新的 .java 文件都有一个简单的 JavaDoc 类注释，最好至少有一个关于该类的解释说明。 +* 将ASF许可注释添加到所有新的 .java 文件（从项目中的现有文件复制） +* 请确保没有将 @author 标记添加到您所贡献的文件中，因为 Apache 不使用 @author 标记，其他方式（如cvs）将公平地记录所有您的贡献。 +* 为代码添加一些 JavaDoc，如果您更改命名空间，则需要一些 XSD DOC 元素。 +* 对于新的特征或重要的修复程序，应该添加单元测试。 +* 如果没有其他人使用您的分支，请将它与 master（或主项目中的其他目标分支）同步。 +* 当编写提交消息时，请遵循这些约定，如果您正在修复一个现有问题，请在提交消息的末尾添加 Fixes XXX（其中XXX是问题编号）。 + +##### **代码风格** +我们提供了 IntelliJ idea 的模版文件 dubbo根目录/codestyle/dubbo_codestyle_for_idea.xml，您可以将它导入到IDE。 +如果使用 Eclipse，可以通过参考该文件手动配置。 + +**代码风格检查:** + +1. 安装 checkstyle 插件(IDEA可以在插件市场搜索) +2. 插件安装好后，在IDEA的settings==>tool==>checkstyle中设置: +![checkstyle1](/imgs/dev/checkstyle1.png) +![checkstyle2](/imgs/dev/checkstyle2.png) +![checkstyle3](/imgs/dev/checkstyle3.png) +![checkstyle4](/imgs/dev/checkstyle4.png) + +**注意事项** + +使用 dubbo_codestyle_for_idea.xml 为你的 IDEA 设置代码格式是贡献代码前至关重要的一个步骤，否则你将会无法通过 CI 的代码风格校验，下面几个步骤给你演示了如何配置代码格式： +1. 进入菜单页 Editor > Code Style +2. 在 Code Style 页面的 scheme 菜单中点击 manage profiles 选项 在下拉列表中选择 Import Scheme， 接着选择 IntelliJ IDEA code style XML 导入 xml 文件 +3. 输入你的格式名称，方便在不同工程之间进行识别，最后别忘了 ⏎ 来保存更改. + 设置完成后，IDEA 会帮助你自动 reformat 代码 + +### 参与发布投票 + +参与发布投票是一种重要的贡献社区的方式，Dubbo 社区非常欢迎和鼓励任何人参与投票，每当一个版本需要正式发布的时候，会在开发者邮件列表上进行发布投票，只有当投票取得通过之后，才会正式发布，可以参考这个[检查列表](https://wiki.apache.org/incubator/IncubatorReleaseChecklist)对源码进行合规性检查。如果有任何问题，可以在开发者邮件列表上提问。 diff --git a/content/en/latest/contribution-guidelines/contributor/reporting-security-issues_dev.md b/content/en/latest/contribution-guidelines/contributor/reporting-security-issues_dev.md new file mode 100644 index 000000000000..4b0194156073 --- /dev/null +++ b/content/en/latest/contribution-guidelines/contributor/reporting-security-issues_dev.md @@ -0,0 +1,26 @@ +--- +type: docs +title: "报告安全问题" +linkTitle: "反馈漏洞" +weight: 4 +--- + +Apache Software Foundation 在消除其软件项目中的安全性问题方面采取严格的立场。Apache Dubbo 对与其功能和特性有关的问题非常敏感并很快提出。 + +## 报告漏洞 + +如果您对 Dubbo 的安全性有担心，或者发现漏洞或潜在威胁，请发送电子邮件至 security@dubbo.apache.org 与 Apache Dubbo 安全团队联系。在邮件中，指定问题或潜在威胁的描述。还敦促您推荐重现和复制问题的方法。Dubbo 社区会在评估和分析调查结果之后与您联系。 + +请先注意在安全电子邮件中报告安全问题，然后再在公共领域公开该问题。 + + +## 漏洞处理 + +漏洞处理过程的概述是： + +* 报告者将漏洞秘密报告给 Apache。 +* 相应项目的安全团队与报告者私下合作来解决漏洞。 +* 制作了包含该修复程序的有关 Apache 产品的新版本。 +* 该漏洞已公开宣布。 + +有关此过程的详细说明，请参见[此处](https://www.apache.org/security/committers.html) diff --git a/content/en/latest/contribution-guidelines/contributor/software-donation-guide_dev.md b/content/en/latest/contribution-guidelines/contributor/software-donation-guide_dev.md new file mode 100644 index 000000000000..f4425f0104da --- /dev/null +++ b/content/en/latest/contribution-guidelines/contributor/software-donation-guide_dev.md @@ -0,0 +1,112 @@ +--- +type: docs +title: "软件捐献向导" +linkTitle: "捐献向导" +weight: 4 +--- + +在您阅读这篇指南之前，请确保您已经向PMC确认了实际需要的 SGA。 + +如果您向 Apache Dubbo 捐赠了大量的代码或文档，则需要在合并代码或者文档之前签署[软件授权书](https://www.apache.org/licenses/#grants)。 + +### 操作步骤 + +1. 下载这篇[pdf文档](https://www.apache.org/licenses/software-grant-template.pdf) +2. 打印下载好的文档 +3. 按要求填充表格（请看下边示例） +4. 请您的领导在上边签字 +5. 扫描 +6. 将扫描好的文档以邮件的方式发送给secretary@apache.org，并抄送给private@dubbo.apache.org + +### 示例 + +下边是一个文本示例，原始文本可以在[这里](https://www.apache.org/licenses/software-grant.txt)找到 + +``` +License Agreement + + + This License Agreement is entered into as of the _12th_ day of +___April____, __2018__ by ___ABC Software Co., Ltd.____ ("Licensor"), +in favor of The Apache Software Foundation, a Delaware nonstock +membership corporation (the "Foundation"). + + WHEREAS, Licensor owns or has sufficient rights to contribute the +software source code and other related intellectual property as +itemized on Exhibit A ("Software") under the terms of this agreement +to the Foundation for use within Foundation software development +projects ("Projects"). + + NOW, THEREFORE, FOR GOOD AND VALUABLE CONSIDERATION, the receipt +and legal sufficiency of which are hereby acknowledged, the parties +hereto, intending to be legally bound, agree as follows: + +1. Subject to the terms and conditions of this License, Licensor +hereby grants to the Foundation: + + a) a non-exclusive, worldwide, royalty-free, irrevocable + copyright license to reproduce, prepare derivative works of, + publicly display, publicly perform, distribute and sublicense, + internally and externally, the Software and such derivative + works, in source code and object code form; and, + + b) a non-exclusive, worldwide, royalty-free, irrevocable + patent license under Licensed Patents to make, use, sell, + offer to sell, import and otherwise transfer the Software + in source code and object code form. "Licensed Patents" mean + patent claims owned by Licensor which are necessarily + infringed by the use or sale of the Software alone. + +2. Licensor represents that, to Licensor's knowledge, Licensor is +legally entitled to grant the above license. Licensor agrees to notify +the Foundation of any facts or circumstances of which Licensor becomes +aware and which makes or would make Licensor's representations in this +License Agreement inaccurate in any respect. + +3. This Software is provided AS-IS, WITHOUT WARRANTIES OR CONDITIONS +OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, WITHOUT LIMITATION, +ANY WARRANTIES OR CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY +OR FITNESS FOR A PARTICULAR PURPOSE. NEITHER THE LICENSOR NOR ITS +SUPPLIERS WILL BE LIABLE TO THE FOUNDATION OR ITS LICENSEES FOR ANY +DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +DAMAGES (INCLUDING WITHOUT LIMITATION LOST PROFITS), HOWEVER CAUSED +AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF +THE USE OR DISTRIBUTION OF THE WORK OR THE EXERCISE OF ANY RIGHTS +GRANTED HEREUNDER, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. + +This License Agreement is the entire agreement of the parties +with respect to its subject matter, and may only be amended by a +writing signed by each party. This License Agreement may be +executed in one or more counterparts, each of which shall be +considered an original. + + IN WITNESS WHEREOF, Licensor has executed this License Agreement +as of the date first written above. + + + LICENSOR: + + + Signed By: _____________________________________ <--- Your boss's sign here + + Print Name: _____Lei Li_________________________ <--- Your boss's name here + + Title: ____Director_____________________________ <--- Your boss's title here + + Representing: ____ABC Software Co., Ltd. _______ + + ________________________________________________ + + Contact Name: ____Lei Li________________________ <--- Your boss's name here + + Contact Email: ____lilei@abc.com________________ <--- Your boss's email here + +Exhibit A + +List of software and other intellectual property covered by this agreement: + +* Github address where your code is hosted +* Pull request link +``` + diff --git a/content/en/latest/contribution-guidelines/contributor/test-coverage-guide_dev.md b/content/en/latest/contribution-guidelines/contributor/test-coverage-guide_dev.md new file mode 100644 index 000000000000..b8574daabf88 --- /dev/null +++ b/content/en/latest/contribution-guidelines/contributor/test-coverage-guide_dev.md @@ -0,0 +1,21 @@ +--- +type: docs +title: "测试覆盖率向导" +linkTitle: "测试覆盖率向导" +weight: 7 +--- + +### 写单元测试的收益 +* 单元测试能帮助每个人深入代码细节，了解代码的功能。 +* 通过测试用例我们能发现bug，并提交代码的健壮性。 +* 测试用例同时也是代码的demo用法。 +### 单元测试用例的一些设计原则 +* 应该精心设计好步骤，颗粒度和组合条件。 +* 注意边界条件。 +* 单元测试也应该好好设计，不要写无用的代码。 +* 当你发现一个`方法`很难写单元测试时，如果可以确认这个`方法`是`臭代码`，那么就和开发者一起重构它。 +* Dubbo中用的mock框架是: [mockito](http://site.mockito.org/). 下面是一些开发向导:[mockito tutorial](http://www.baeldung.com/bdd-mockito),[mockito refcard](https://dzone.com/refcardz/mockito) +* TDD（可选）：当你开始写一个新的功能时，你可以试着先写测试用例。 +### 测试覆盖率设定值 +* 在现阶段，Delta更改代码的测试覆盖设定值为：>＝60%，越高越好。 +* 我们可以在这个页面中看到测试报告: https://codecov.io/gh/apache/dubbo diff --git a/content/en/latest/download/_index.md b/content/en/latest/download/_index.md new file mode 100755 index 000000000000..a63be278f0fb --- /dev/null +++ b/content/en/latest/download/_index.md @@ -0,0 +1,13 @@ + +--- +type: docs +title: "Download" +linkTitle: "Download" +weight: 20 +menu: + main: + weight: 30 +--- + + + diff --git a/content/en/latest/facade-docs/_index.md b/content/en/latest/facade-docs/_index.md new file mode 100755 index 000000000000..acd2f441ce6f --- /dev/null +++ b/content/en/latest/facade-docs/_index.md @@ -0,0 +1,15 @@ + +--- +type: docs +title: "Documentation" +linkTitle: "Documentation" +weight: 20 +menu: + main: + weight: 10 + name: "Documentation" + +--- + + + diff --git a/content/en/latest/facade-docs/contact /_index.md b/content/en/latest/facade-docs/contact /_index.md new file mode 100755 index 000000000000..2fededdd0854 --- /dev/null +++ b/content/en/latest/facade-docs/contact /_index.md @@ -0,0 +1,11 @@ + +--- +type: docs +title: "How to Contact the Dubbo Community?" +linkTitle: "How to Contact the Dubbo Community?" +description: "" +weight: 4 +--- + + + diff --git a/content/en/latest/facade-docs/how/_index.md b/content/en/latest/facade-docs/how/_index.md new file mode 100755 index 000000000000..b46d4e3fa982 --- /dev/null +++ b/content/en/latest/facade-docs/how/_index.md @@ -0,0 +1,8 @@ + +--- +type: docs +title: "How to use Dubbo?" +linkTitle: "How to use Dubbo?" +weight: 3 +--- + diff --git a/content/en/latest/facade-docs/how/quick-start.md b/content/en/latest/facade-docs/how/quick-start.md new file mode 100644 index 000000000000..ea2dfbf4a959 --- /dev/null +++ b/content/en/latest/facade-docs/how/quick-start.md @@ -0,0 +1,38 @@ +--- +type: docs +title: "Quick Start" +linkTitle: "Quick Start" +weight: 3 +--- + +{{< blocks/section color="white" height="auto">}} +
+
+
+
+
+
+

+ Quick start +

+

Dubbo Java SDK

+
+
+
+
+
+
+

+ Quick start +

+

Dubbo Golang SDK

+
+
+
+ +
+
+
+ +{{< /blocks/section >}} + diff --git a/content/en/latest/facade-docs/what/_index.md b/content/en/latest/facade-docs/what/_index.md new file mode 100644 index 000000000000..dca523204b5d --- /dev/null +++ b/content/en/latest/facade-docs/what/_index.md @@ -0,0 +1,7 @@ +--- +type: docs +title: "What is Dubbo?" +linkTitle: "What is Dubbo?" +weight: 1 +description: "" +--- \ No newline at end of file diff --git a/content/en/latest/facade-docs/what/core-concepts.md b/content/en/latest/facade-docs/what/core-concepts.md new file mode 100644 index 000000000000..df31c8282e37 --- /dev/null +++ b/content/en/latest/facade-docs/what/core-concepts.md @@ -0,0 +1,7 @@ +--- +type: docs +title: "Core Concepts" +linkTitle: "Core Concepts" +weight: 2 +description: "" +--- \ No newline at end of file diff --git a/content/en/latest/facade-docs/what/ecosystem.md b/content/en/latest/facade-docs/what/ecosystem.md new file mode 100644 index 000000000000..a42cd4b905d5 --- /dev/null +++ b/content/en/latest/facade-docs/what/ecosystem.md @@ -0,0 +1,7 @@ +--- +type: docs +title: "Dubbo Ecosystem" +linkTitle: "Dubbo Ecosystem" +weight: 3 +description: "" +--- \ No newline at end of file diff --git a/content/en/latest/facade-docs/what/overview.md b/content/en/latest/facade-docs/what/overview.md new file mode 100644 index 000000000000..7cafaa0f09f7 --- /dev/null +++ b/content/en/latest/facade-docs/what/overview.md @@ -0,0 +1,7 @@ +--- +type: docs +title: "Introduction" +linkTitle: "Introduction" +weight: 1 +description: "" +--- \ No newline at end of file diff --git a/content/en/latest/facade-docs/why/_index.md b/content/en/latest/facade-docs/why/_index.md new file mode 100755 index 000000000000..9e4836a117b7 --- /dev/null +++ b/content/en/latest/facade-docs/why/_index.md @@ -0,0 +1,11 @@ + +--- +type: docs +title: "Why use Dubbo?" +linkTitle: "Why use Dubbo?" +description: "" +weight: 2 +--- + + + diff --git a/content/en/latest/facade-docs/why/advantage.md b/content/en/latest/facade-docs/why/advantage.md new file mode 100755 index 000000000000..0a0740bbd1bc --- /dev/null +++ b/content/en/latest/facade-docs/why/advantage.md @@ -0,0 +1,11 @@ + +--- +type: docs +title: "Advantage" +linkTitle: "Advantage" +description: "" +weight: 1 +--- + + + diff --git a/content/en/latest/golang-sdk/_index.md b/content/en/latest/golang-sdk/_index.md new file mode 100755 index 000000000000..1b3de410d1b1 --- /dev/null +++ b/content/en/latest/golang-sdk/_index.md @@ -0,0 +1,8 @@ + +--- +type: advanced-docs +title: "golang" +linkTitle: "golang" +weight: 3 +--- + diff --git a/content/en/latest/java-sdk/_index.md b/content/en/latest/java-sdk/_index.md new file mode 100755 index 000000000000..9d5fefd9e445 --- /dev/null +++ b/content/en/latest/java-sdk/_index.md @@ -0,0 +1,8 @@ + +--- +type: advanced-docs +title: "Dubbo Java SDK" +linkTitle: "Dubbo Java SDK" +weight: 3 +--- + diff --git a/content/en/latest/java-sdk/v2.x/_index.md b/content/en/latest/java-sdk/v2.x/_index.md new file mode 100755 index 000000000000..1935db7ac148 --- /dev/null +++ b/content/en/latest/java-sdk/v2.x/_index.md @@ -0,0 +1,8 @@ + +--- +type: advanced-docs +title: "v2.x" +linkTitle: "v2.x" +weight: 1 +--- + diff --git a/content/en/latest/java-sdk/v2.x/advanced-features-and-usage/_index.md b/content/en/latest/java-sdk/v2.x/advanced-features-and-usage/_index.md new file mode 100755 index 000000000000..e384131bc8a5 --- /dev/null +++ b/content/en/latest/java-sdk/v2.x/advanced-features-and-usage/_index.md @@ -0,0 +1,8 @@ + +--- +type: advanced-docs +title: "Advanced Features & Usage" +linkTitle: "Advanced Features & Usage" +weight: 4 +--- + diff --git a/content/en/latest/java-sdk/v2.x/concepts-and-architecture/_index.md b/content/en/latest/java-sdk/v2.x/concepts-and-architecture/_index.md new file mode 100755 index 000000000000..f911f7417735 --- /dev/null +++ b/content/en/latest/java-sdk/v2.x/concepts-and-architecture/_index.md @@ -0,0 +1,8 @@ + +--- +type: advanced-docs +title: "Concepts & Architecture" +linkTitle: "Concepts & Architecture" +weight: 3 +--- + diff --git a/content/en/latest/java-sdk/v2.x/concepts-and-architecture/users.md b/content/en/latest/java-sdk/v2.x/concepts-and-architecture/users.md new file mode 100644 index 000000000000..c9af84c04d7b --- /dev/null +++ b/content/en/latest/java-sdk/v2.x/concepts-and-architecture/users.md @@ -0,0 +1,6 @@ +--- +type: advanced-docs +title: "用户列表" +linkTitle: "用户列表" +weight: 3 +--- diff --git a/content/en/latest/java-sdk/v2.x/contributing/_index.md b/content/en/latest/java-sdk/v2.x/contributing/_index.md new file mode 100755 index 000000000000..bdef0ad150c2 --- /dev/null +++ b/content/en/latest/java-sdk/v2.x/contributing/_index.md @@ -0,0 +1,8 @@ + +--- +type: advanced-docs +title: "Contributing" +linkTitle: "Contributing" +weight: 7 +--- + diff --git a/content/en/latest/java-sdk/v2.x/introduction/_index.md b/content/en/latest/java-sdk/v2.x/introduction/_index.md new file mode 100755 index 000000000000..85c937b2965b --- /dev/null +++ b/content/en/latest/java-sdk/v2.x/introduction/_index.md @@ -0,0 +1,8 @@ + +--- +type: advanced-docs +title: "Introduction" +linkTitle: "Introduction" +weight: 1 +--- + diff --git a/content/en/latest/java-sdk/v2.x/introduction/users.md b/content/en/latest/java-sdk/v2.x/introduction/users.md new file mode 100644 index 000000000000..2e10662e47cc --- /dev/null +++ b/content/en/latest/java-sdk/v2.x/introduction/users.md @@ -0,0 +1,6 @@ +--- +type: advanced-docs +title: "Users" +linkTitle: "Users" +weight: 3 +--- diff --git a/content/en/latest/java-sdk/v2.x/quick-start/_index.md b/content/en/latest/java-sdk/v2.x/quick-start/_index.md new file mode 100755 index 000000000000..762f84891d60 --- /dev/null +++ b/content/en/latest/java-sdk/v2.x/quick-start/_index.md @@ -0,0 +1,8 @@ + +--- +type: advanced-docs +title: "Quick start" +linkTitle: "Quick start" +weight: 2 +--- + diff --git a/content/en/latest/java-sdk/v2.x/quick-start/quick-start.md b/content/en/latest/java-sdk/v2.x/quick-start/quick-start.md new file mode 100644 index 000000000000..05d66531bf11 --- /dev/null +++ b/content/en/latest/java-sdk/v2.x/quick-start/quick-start.md @@ -0,0 +1,8 @@ +--- +type: advanced-docs +title: "快速开始" +linkTitle: "快速开始" +weight: 3 +--- + +链接到各个生态的quick-start \ No newline at end of file diff --git a/content/en/latest/java-sdk/v2.x/reference-manual/_index.md b/content/en/latest/java-sdk/v2.x/reference-manual/_index.md new file mode 100755 index 000000000000..8b31e2586018 --- /dev/null +++ b/content/en/latest/java-sdk/v2.x/reference-manual/_index.md @@ -0,0 +1,8 @@ + +--- +type: advanced-docs +title: "Reference Manual" +linkTitle: "Reference Manual" +weight: 5 +--- + diff --git a/content/en/latest/java-sdk/v2.x/upgrades-and-compatibility/_index.md b/content/en/latest/java-sdk/v2.x/upgrades-and-compatibility/_index.md new file mode 100755 index 000000000000..9160ff74b96c --- /dev/null +++ b/content/en/latest/java-sdk/v2.x/upgrades-and-compatibility/_index.md @@ -0,0 +1,8 @@ + +--- +type: advanced-docs +title: "Upgrades & Compatibility" +linkTitle: "Upgrades & Compatibility" +weight: 6 +--- + diff --git a/content/en/latest/java-sdk/v3.x/_index.md b/content/en/latest/java-sdk/v3.x/_index.md new file mode 100755 index 000000000000..fcb85345b107 --- /dev/null +++ b/content/en/latest/java-sdk/v3.x/_index.md @@ -0,0 +1,8 @@ + +--- +type: advanced-docs +title: "v3.x" +linkTitle: "v3.x" +weight: 2 +--- + diff --git a/content/en/latest/java-sdk/v3.x/advanced-features-and-usage/_index.md b/content/en/latest/java-sdk/v3.x/advanced-features-and-usage/_index.md new file mode 100755 index 000000000000..e384131bc8a5 --- /dev/null +++ b/content/en/latest/java-sdk/v3.x/advanced-features-and-usage/_index.md @@ -0,0 +1,8 @@ + +--- +type: advanced-docs +title: "Advanced Features & Usage" +linkTitle: "Advanced Features & Usage" +weight: 4 +--- + diff --git a/content/en/latest/java-sdk/v3.x/concepts-and-architecture/_index.md b/content/en/latest/java-sdk/v3.x/concepts-and-architecture/_index.md new file mode 100755 index 000000000000..f911f7417735 --- /dev/null +++ b/content/en/latest/java-sdk/v3.x/concepts-and-architecture/_index.md @@ -0,0 +1,8 @@ + +--- +type: advanced-docs +title: "Concepts & Architecture" +linkTitle: "Concepts & Architecture" +weight: 3 +--- + diff --git a/content/en/latest/java-sdk/v3.x/concepts-and-architecture/users.md b/content/en/latest/java-sdk/v3.x/concepts-and-architecture/users.md new file mode 100644 index 000000000000..c9af84c04d7b --- /dev/null +++ b/content/en/latest/java-sdk/v3.x/concepts-and-architecture/users.md @@ -0,0 +1,6 @@ +--- +type: advanced-docs +title: "用户列表" +linkTitle: "用户列表" +weight: 3 +--- diff --git a/content/en/latest/java-sdk/v3.x/contributing/_index.md b/content/en/latest/java-sdk/v3.x/contributing/_index.md new file mode 100755 index 000000000000..bdef0ad150c2 --- /dev/null +++ b/content/en/latest/java-sdk/v3.x/contributing/_index.md @@ -0,0 +1,8 @@ + +--- +type: advanced-docs +title: "Contributing" +linkTitle: "Contributing" +weight: 7 +--- + diff --git a/content/en/latest/java-sdk/v3.x/introduction/_index.md b/content/en/latest/java-sdk/v3.x/introduction/_index.md new file mode 100755 index 000000000000..85c937b2965b --- /dev/null +++ b/content/en/latest/java-sdk/v3.x/introduction/_index.md @@ -0,0 +1,8 @@ + +--- +type: advanced-docs +title: "Introduction" +linkTitle: "Introduction" +weight: 1 +--- + diff --git a/content/en/latest/java-sdk/v3.x/introduction/users.md b/content/en/latest/java-sdk/v3.x/introduction/users.md new file mode 100644 index 000000000000..2e10662e47cc --- /dev/null +++ b/content/en/latest/java-sdk/v3.x/introduction/users.md @@ -0,0 +1,6 @@ +--- +type: advanced-docs +title: "Users" +linkTitle: "Users" +weight: 3 +--- diff --git a/content/en/latest/java-sdk/v3.x/quick-start/_index.md b/content/en/latest/java-sdk/v3.x/quick-start/_index.md new file mode 100755 index 000000000000..762f84891d60 --- /dev/null +++ b/content/en/latest/java-sdk/v3.x/quick-start/_index.md @@ -0,0 +1,8 @@ + +--- +type: advanced-docs +title: "Quick start" +linkTitle: "Quick start" +weight: 2 +--- + diff --git a/content/en/latest/java-sdk/v3.x/reference-manual/_index.md b/content/en/latest/java-sdk/v3.x/reference-manual/_index.md new file mode 100755 index 000000000000..8b31e2586018 --- /dev/null +++ b/content/en/latest/java-sdk/v3.x/reference-manual/_index.md @@ -0,0 +1,8 @@ + +--- +type: advanced-docs +title: "Reference Manual" +linkTitle: "Reference Manual" +weight: 5 +--- + diff --git a/content/en/latest/java-sdk/v3.x/upgrades-and-compatibility/_index.md b/content/en/latest/java-sdk/v3.x/upgrades-and-compatibility/_index.md new file mode 100755 index 000000000000..9160ff74b96c --- /dev/null +++ b/content/en/latest/java-sdk/v3.x/upgrades-and-compatibility/_index.md @@ -0,0 +1,8 @@ + +--- +type: advanced-docs +title: "Upgrades & Compatibility" +linkTitle: "Upgrades & Compatibility" +weight: 6 +--- + diff --git a/content/en/latest/notices/_index.md b/content/en/latest/notices/_index.md new file mode 100755 index 000000000000..e3f4a4846bda --- /dev/null +++ b/content/en/latest/notices/_index.md @@ -0,0 +1,11 @@ + +--- +type: docs +title: "Announcement" +linkTitle: "Announcement" +description: "Dubbo Announcement" +menu: + main: + weight: 60 +--- + diff --git a/content/en/latest/notices/security.md b/content/en/latest/notices/security.md new file mode 100755 index 000000000000..e665d769dfa7 --- /dev/null +++ b/content/en/latest/notices/security.md @@ -0,0 +1,73 @@ + +--- +type: docs +title: "安全漏洞" +linkTitle: "安全漏洞" +description: "安全漏洞说明" +weight: 90 +--- + +## 1. Log4j CVE-2021-44228 漏洞 + +最近，主流日志组件 [log4j2](https://logging.apache.org/log4j/2.x/) 爆出[安全漏洞 CVE-2021-44228](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-44228)。 + +以下是漏洞 CVE-2021-44228 对 Apache Dubbo 框架的影响总结及用户应对指南。 + +## Dubbo 影响范围 +**该漏洞对 Dubbo 框架使用安全并无影响。** + +Dubbo 本身不强依赖 log4j2 框架，也不会通过依赖传递将 log4j2 带到业务工程中去，因此，正在使用 Dubbo 2.7.x、3.0.x 等版本的用户均无需强制升级 Dubbo 版本。 + +以下是 Dubbo 各组件对 log4j2 的依赖分析，涉及 `dubbo-common`、`dubbo-spring-boot-starter`、`dubbo-spring-boot-actuator`： + +* dubbo-common 包含对 `log4j-core` 的可选依赖，请检查项目自身是否启用了 log4j 依赖，如启用则对应升级即可。 +```xml +[INFO] --- maven-dependency-plugin:3.1.2:tree (default-cli) @ dubbo-common --- +[INFO] org.apache.dubbo:dubbo-common:jar:2.7.14-SNAPSHOT +[INFO] +- org.apache.logging.log4j:log4j-api:jar:2.11.1:provided +[INFO] \- org.apache.logging.log4j:log4j-core:jar:2.11.1:provided + +``` + +* dubbo-spring-boot-starter 通过 spring-boot 组件传递了 log4j-api 依赖，log4j-api 本身并无安全问题，升级 log4j-core 组件时注意与 log4j-api 的兼容性 + +```xml +[INFO] --- maven-dependency-plugin:3.1.2:tree (default-cli) @ dubbo-spring-boot-starter --- +[INFO] org.apache.dubbo:dubbo-spring-boot-starter:jar:2.7.14-SNAPSHOT +[INFO] \- org.springframework.boot:spring-boot-starter:jar:2.3.1.RELEASE:compile (optional) +[INFO] \- org.springframework.boot:spring-boot-starter-logging:jar:2.3.1.RELEASE:compile (optional) +[INFO] \- org.apache.logging.log4j:log4j-to-slf4j:jar:2.13.3:compile (optional) +[INFO] \- org.apache.logging.log4j:log4j-api:jar:2.13.3:compile (optional) + +``` + +* dubbo-spring-boot-actuator 通过 spring-boot 组件传递了 log4j-api 依赖，log4j-api 本身并无安全问题，升级 log4j-core 组件时应注意与 log4j-api 的兼容性 + +```xml +[INFO] org.apache.dubbo:dubbo-spring-boot-actuator:jar:2.7.14-SNAPSHOT +[INFO] \- org.springframework.boot:spring-boot-starter-web:jar:2.3.1.RELEASE:compile (optional) +[INFO] \- org.springframework.boot:spring-boot-starter:jar:2.3.1.RELEASE:compile +[INFO] \- org.springframework.boot:spring-boot-starter-logging:jar:2.3.1.RELEASE:compile +[INFO] \- org.apache.logging.log4j:log4j-to-slf4j:jar:2.13.3:compile +[INFO] \- org.apache.logging.log4j:log4j-api:jar:2.13.3:compile +``` + + +## 2. 序列化 +Dubbo 支持序列化协议的扩展，理论上用户可以基于该扩展机制启用任意的序列化协议，这带来了极大的灵活的，但同时也要意识到其中潜藏的安全性风险。 +数据反序列化是最容易被被攻击者利用的一个环节，攻击者利用它执行 RCE 攻击等窃取或破坏服务端数据，用户在切换序列化协议或实现前， +应充分调研目标序列化协议及其框架实现的安全性保障，并提前设置相应的安全措施（如设置黑/白名单）。Dubbo 框架自身并不能保证目标序列化机制的安全性。 + +Dubbo 2.7 官方版本提供的序列化协议有如下几种： +* Hessian2 +* Fastjson +* Kryo +* FST +* JDK +* Protostuff/Protobuf +* Avro +* Gson + +针对以上序列化扩展，在发现或收到相关的漏洞报告之后，Dubbo 官方会跟进并升级依赖到最新的安全版本，但最终的漏洞修复方案取决于序列化的框架实现。 + +> 针对使用 [dubbo hessian2](https://github.com/apache/dubbo-hessian-lite/releases) 版本的用户，Dubbo 官方会保证hessian2序列化机制的安全性并尽可能的修复上报的安全漏洞 diff --git a/content/en/latest/pixiu/_index.md b/content/en/latest/pixiu/_index.md new file mode 100755 index 000000000000..3e7201da0198 --- /dev/null +++ b/content/en/latest/pixiu/_index.md @@ -0,0 +1,8 @@ + +--- +type: advanced-docs +title: "pixiu" +linkTitle: "pixiu" +weight: 3 +--- + diff --git a/content/zh/_index.html b/content/zh/_index.html index edf2df656eaf..387ad5dc3141 100644 --- a/content/zh/_index.html +++ b/content/zh/_index.html @@ -4,53 +4,53 @@ +++ -{{< blocks/cover title="Apache Dubbo" image_anchor="top" height="auto" color="primary" >}} +{{< blocks/cover title="Apache Dubbo" image_anchor="top" height="full" color="secondary" >}}
- }}"> - 快速开始 + + 快速开始 - - DOWNLOAD + + Dubbo3 速览 - - GITHUB - -

Apache Dubbo 是一款高性能、轻量级的开源服务框架

- {{< blocks/link-down color="info" >}} +

Apache Dubbo 是一款微服务框架，为大规模微服务实践提供高性能 RPC 通信、流量治理、可观测性等解决方案，
+ 涵盖 Java、Golang 等多种语言 SDK 实现。

+
+ {{< blocks/link-down color="white" >}} +
{{< /blocks/cover >}} -{{% blocks/lead color="primary" %}} -Apache Dubbo |ˈdʌbəʊ| 提供了六大核心能力：面向接口代理的高性能RPC调用，智能容错和负载均衡，服务自动注册和发现，高度可扩展能力，运行期流量调度，可视化的服务治理与运维。 -{{% /blocks/lead %}} - -{{< blocks/section color="dark" >}} -{{% blocks/feature icon="fas fa-exchange-alt" title="面向接口代理的高性能RPC调用" %}} -提供高性能的基于代理的远程调用能力，服务以接口为粒度，为开发者屏蔽远程调用底层细节。 -{{% /blocks/feature %}} - -{{% blocks/feature icon="fas fa-random" title="智能负载均衡" %}} -内置多种负载均衡策略，智能感知下游节点健康状况，显著减少调用延迟，提高系统吞吐量。 -{{% /blocks/feature %}} - -{{% blocks/feature icon="fa fa-share-alt" title="服务自动注册与发现" %}} -支持多种注册中心服务，服务实例上下线实时感知。 -{{% /blocks/feature %}} +{{% blocks/lead color="white" %}} +

下一代云原生微服务框架 - Dubbo3

+
+

+ 3.0 版本的正式发布，标志着 Apache Dubbo 正式进入云原生时代。3.0 在通信协议、服务发现、部署架构、服务治理上都对云原生基础设施进行了全面适配， + 提供了Triple、应用级服务发现、Dubbo Mesh等核心特性。 +

+

+ Dubbo3 已被阿里巴巴、饿了么、钉钉、工商银行、小米等在生产环境广泛采用，学习更多用户案例 + {{% /blocks/lead %}} +

-{{% blocks/feature icon="fad fa-expand" title="高度可扩展能力" %}} -遵循微内核+插件的设计原则，所有核心能力如Protocol、Transport、Serialization被设计为扩展点，平等对待内置实现和第三方实现。 +{{< blocks/section color="100" >}} +{{% blocks/feature icon="fas fa-exchange-alt" title="下一代RPC协议 - Triple" url="./docs/concepts/rpc-protocol/" %}} +Triple 协议是基于 HTTP/2 之上定义的下一代 RPC 通信协议，相比于上一代 Dubbo2 协议，它具有更好的穿透性、通用性、以及面向网关代理场景的高性能表现， +提供了 Reactive Stream 数据交换模型。Triple 实现了对 gRPC 的完全兼容。 {{% /blocks/feature %}} -{{% blocks/feature icon="fas fa-traffic-light" title="运行期流量调度" %}} -内置条件、脚本等路由策略，通过配置不同的路由规则，轻松实现灰度发布，同机房优先等功能。 +{{% blocks/feature icon="fas fa-share-alt" title="应用级服务发现" url="./docs/concepts/service-discovery/" %}} +从服务/接口粒度到应用粒度的升级，使得 Dubbo 在集群可伸缩性、连接异构微服务体系上更具优势。应用粒度能以更低的资源消耗支持超百万实例规模集群程； +实现与 Spring Cloud、Kubernetes Service 等异构微服务体系的互联互通。 {{% /blocks/feature %}} -{{% blocks/feature icon="fas fa-sliders-h" title="可视化的服务治理与运维" %}} -提供丰富服务治理、运维工具：随时查询服务元数据、服务健康状态及调用统计，实时下发路由策略、调整配置参数。 +{{% blocks/feature icon="fa fa-share-alt" title="Mesh 解决方案" %}} +依赖 Dubbo Mesh 将 Dubbo 纳入 Istio 等开源 Mesh 治理体系， +3.0 同时支持 ThinSDK + Sidecar 与 FatSDK（Proxyless）的部署模式，为 Mesh 架构提供了更多选择，尤其对于面临迁移或混合部署的场景， +Dubbo 提供了统一控制面的能力。 {{% /blocks/feature %}} {{< /blocks/section >}} -{{< blocks/section color="white" >}} +{{< blocks/section color="primary" >}} {{% blocks/feature icon="far fa-envelope" title="订阅邮件组" %}} dev@dubbo.apache.org 参与社区的讨论 {{% /blocks/feature %}} diff --git a/content/zh/docs3-building/docs/_index.md b/content/zh/docs3-building/docs/_index.md new file mode 100755 index 000000000000..d029bfea07e2 --- /dev/null +++ b/content/zh/docs3-building/docs/_index.md @@ -0,0 +1,38 @@ + +--- +type: docs +title: "文档" +linkTitle: "文档" +no_list: true +hide_summary: true +menu: + main: + weight: 10 +--- +> 本文档最新版本基于 Dubbo3 编写，由于 Dubbo3 完全兼容 2.7 版本用法，因此本文档中的通用功能（指除 3.x 版本特有功能外）同样适用于 2.7 版本用户。 +> +> 如有需要，请点此查看[老版本文档]() +> + + +Dubbo 是一款包含多种语言实现（Java、Golang等）的 RPC 服务框架，在这里可以查看 Dubbo 核心概念以及每种语言实现的 Demo、用户手册等。 + +* **如果你是第一次接触 Dubbo**，可以通过以下链接快速了解 Dubbo: + * [什么是 Dubbo](what/overview.md) + * [用户案例与生态](what/usecases.md) + * 通过 [**快速开始**](quickstart/) 体验 Dubbo +* 想了解更多 Dubbo 特性与使用细节? + * 选择相应 [**多语言 SDK 实现**](mannual/)，并参考**高级特性**或**参考手册** + * [**FAQ**](faq) +* 老用户，想快速了解 **Dubbo 3.0** 相关知识 + * [3.0 特性一览](whatsnew/) + * 查看相应[多语言 SDK 实现](mannual/)，了解升级与兼容性 + +#### 相关链接 +Dubbo 的多语言实现及文档: + +Language | OS | Compilers/SDK +-- | -- | -- +Go|Windows, Linux, Mac|Go 1.13+ +Java|Windows, Linux, Mac|Java 8+ + diff --git a/content/zh/docs3-building/docs/contact /_index.md b/content/zh/docs3-building/docs/contact /_index.md new file mode 100755 index 000000000000..5a921e1334ea --- /dev/null +++ b/content/zh/docs3-building/docs/contact /_index.md @@ -0,0 +1,11 @@ + +--- +type: docs +title: "联系社区" +linkTitle: "联系社区" +description: "" +weight: 6 +--- + + + diff --git a/content/zh/docs3-building/docs/mannual/Golang.md b/content/zh/docs3-building/docs/mannual/Golang.md new file mode 100755 index 000000000000..0808bdd0b507 --- /dev/null +++ b/content/zh/docs3-building/docs/mannual/Golang.md @@ -0,0 +1,13 @@ + +--- +type: docs +title: "Golang SDK" +linkTitle: "Golang" +description: "" +weight: 2 +manualLinkTarget: _blank +_build: { render: link } +--- + + + diff --git a/content/zh/docs3-building/docs/mannual/Java.md b/content/zh/docs3-building/docs/mannual/Java.md new file mode 100644 index 000000000000..5302ce31516a --- /dev/null +++ b/content/zh/docs3-building/docs/mannual/Java.md @@ -0,0 +1,13 @@ +--- +type: docs +title: "Java SDK" +linkTitle: "Java" +description: "" +weight: 1 +manualLinkRelref: ../../java-sdk/ +manualLinkTarget: _blank +_build: { render: link } +--- + + + diff --git a/content/zh/docs3-building/docs/mannual/_index.md b/content/zh/docs3-building/docs/mannual/_index.md new file mode 100755 index 000000000000..8197f914cc11 --- /dev/null +++ b/content/zh/docs3-building/docs/mannual/_index.md @@ -0,0 +1,40 @@ + +--- +type: docs +title: "用户手册" +linkTitle: "用户手册" +weight: 5 +no_list: true +--- + + +{{< blocks/section color="white" height="auto" >}} +
+
+
+
+
+
+

+ Java SDK +

+

Java SDK

+
+
+
+
+
+
+

+ Golang SDK +

+

Golang SDK

+
+
+
+ +
+
+
+ +{{< /blocks/section >}} diff --git a/content/zh/docs3-building/docs/quickstart/_index.md b/content/zh/docs3-building/docs/quickstart/_index.md new file mode 100755 index 000000000000..f152a6e73774 --- /dev/null +++ b/content/zh/docs3-building/docs/quickstart/_index.md @@ -0,0 +1,38 @@ + +--- +type: docs +title: "快速开始" +linkTitle: "快速开始" +weight: 2 +--- + +{{< blocks/section color="white" height="auto">}} +
+
+
+
+
+
+

+ Quick start +

+

Dubbo Java SDK

+
+
+
+
+
+
+

+ Quick start +

+

Dubbo Golang SDK

+
+
+
+ +
+
+
+ +{{< /blocks/section >}} \ No newline at end of file diff --git a/content/zh/docs3-building/docs/tasks/_index.md b/content/zh/docs3-building/docs/tasks/_index.md new file mode 100755 index 000000000000..302f98ae523d --- /dev/null +++ b/content/zh/docs3-building/docs/tasks/_index.md @@ -0,0 +1,11 @@ + +--- +type: docs +title: "示例实践" +linkTitle: "示例实践" +description: "" +weight: 4 +--- + + + diff --git a/content/zh/docs3-building/docs/tasks/deploy-on-k8s.md b/content/zh/docs3-building/docs/tasks/deploy-on-k8s.md new file mode 100644 index 000000000000..7d35b9c80a12 --- /dev/null +++ b/content/zh/docs3-building/docs/tasks/deploy-on-k8s.md @@ -0,0 +1,11 @@ +--- +type: docs +title: "部署到 Kubernetes" +linkTitle: "如何部署 Dubbo 到 Kubernetes" +weight: 3 +description: "" +--- + + + + diff --git a/content/zh/docs3-building/docs/tasks/dubbo-mesh-proxyless.md b/content/zh/docs3-building/docs/tasks/dubbo-mesh-proxyless.md new file mode 100644 index 000000000000..66e55b8029ad --- /dev/null +++ b/content/zh/docs3-building/docs/tasks/dubbo-mesh-proxyless.md @@ -0,0 +1,9 @@ +--- +type: docs +title: "Dubbo Mesh（Proxyless）部署" +linkTitle: "基于 Proxyless 的 Dubbo Mesh 部署方案" +weight: 3 +description: "" +--- + + diff --git a/content/zh/docs3-building/docs/tasks/dubbo-mesh-sidecar.md b/content/zh/docs3-building/docs/tasks/dubbo-mesh-sidecar.md new file mode 100644 index 000000000000..d334d44f317e --- /dev/null +++ b/content/zh/docs3-building/docs/tasks/dubbo-mesh-sidecar.md @@ -0,0 +1,9 @@ +--- +type: docs +title: "Dubbo Mesh（Sidecar）部署" +linkTitle: "基于 Sidecar 的 Dubbo Mesh 部署方案" +weight: 3 +description: "" +--- + + diff --git a/content/zh/docs3-building/docs/tasks/idl.md b/content/zh/docs3-building/docs/tasks/idl.md new file mode 100644 index 000000000000..c38d0ae19526 --- /dev/null +++ b/content/zh/docs3-building/docs/tasks/idl.md @@ -0,0 +1,204 @@ +--- +type: docs +title: "使用 IDL + Protobuf 跨语言定义服务" +linkTitle: "使用 IDL + Protobuf 跨语言定义服务" +weight: 3 +description: "" +--- + +服务是 Dubbo 中的核心概念，一个服务代表一组 RPC 方法的集合，服务是面向用户编程、服务发现机制等的基本单位。Dubbo 开发的基本流程是：用户定义 RPC 服务，通过约定的配置 +方式将 RPC 声明为 Dubbo 服务，然后就可以基于服务 API 进行编程了。对服务提供者来说是提供 RPC 服务的具体实现，而对服务消费者来说则是使用特定数据发起服务调用。 + +下面从定义服务、编译服务、配置并加载服务三个方面说明如何快速的开发 Dubbo 服务。 + +## 定义服务 +Dubbo3 推荐使用 IDL 定义跨语言服务，如您更习惯使用特定语言的服务定义方式，请移步[多语言 SDK](../mannual)查看。 + +```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; +} + +``` + +以上是使用 IDL 定义服务的一个简单示例，我们可以把它命名为 `DemoService.proto`，proto 文件中定义了 RPC 服务名称 `DemoService` 与方法签名 +`SayHello (HelloRequest) returns (HelloReply) {}`，同时还定义了方法的入参结构体、出参结构体 `HelloRequest` 与 `HelloReply`。 +IDL 格式的服务依赖 Protobuf 编译器，用来生成可以被用户调用的客户端与服务端编程 API，Dubbo 在原生 Protobuf Compiler 的基础上提供了适配多种语言的特有插件，用于适配 Dubbo 框架特有的 API 与编程模型。 + +> 使用 Dubbo3 IDL 定义的服务只允许一个入参与出参，这种形式的服务签名有两个优势，一是对多语言实现更友好，二是可以保证服务的向后兼容性，依赖于 Protobuf 序列化的兼容性，我们可以很容易的调整传输的数据结构如增、删字段等，完全不用担心接口的兼容性。 + +## 编译服务 +根据当前采用的语言，配置相应的 Protobuf 插件，编译后将生产语言相关的服务定义 stub。 + +### Java +Java 语言生成的 stub 如下，核心是一个接口定义 +```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 + +Go 语言生成的 stub 如下，这个 stub 里存了用户定义的接口和数据的类型。 + +```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) +} +``` + + +## 配置并加载服务 +提供端负责提供具体的 Dubbo 服务实现，也就是遵循 RPC 签名所约束的格式，去实现具体的业务逻辑代码。在实现服务之后，要将服务实现注册为标准的 Dubbo 服务， +之后 Dubbo 框架就能根据接收到的请求转发给服务实现，执行方法，并将结果返回。 + +消费端的配置会更简单一些，只需要声明 IDL 定义的服务为标准的 Dubbo 服务，框架就可以帮助开发者生成相应的 proxy，开发者将完全面向 proxy 编程， +基本上 Dubbo 所有语言的实现都保证了 proxy 依据 IDL 服务定义暴露标准化的接口。 + +### Java +提供端，实现服务 +```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)); + } +} +``` + +提供端，注册服务(以 Spring XML 为例) +```xml + + +``` + +消费端，引用服务 +```xml + +``` + +消费端，使用服务 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 + +提供端，实现服务 + +```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)) +} +``` + +消费端，使用服务 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) +} +``` + +## 查看完整示例 +* [Java IDL Quick Start]() +* [Golang IDL Quick Start]() diff --git a/content/zh/docs3-building/docs/tasks/traffic-management.md b/content/zh/docs3-building/docs/tasks/traffic-management.md new file mode 100644 index 000000000000..d4beaf1d966e --- /dev/null +++ b/content/zh/docs3-building/docs/tasks/traffic-management.md @@ -0,0 +1,15 @@ +--- +type: docs +title: "流量管理" +linkTitle: "如何使用 Dubbo 的流量治理能力" +weight: 3 +description: "" +--- + +* 超时 +* 路由规则 +* 动态配置 +* 多注册中心 + + + diff --git a/content/zh/docs3-building/docs/what/_index.md b/content/zh/docs3-building/docs/what/_index.md new file mode 100644 index 000000000000..0b96c4f68266 --- /dev/null +++ b/content/zh/docs3-building/docs/what/_index.md @@ -0,0 +1,17 @@ +--- +type: docs +title: "什么是 Dubbo" +linkTitle: "什么是 Dubbo" +weight: 1 +description: "" +--- + +Apache Dubbo 是一款 RPC 微服务框架，提供了包括 Java、Golang 等在内的多种语言 SDK 实现，如果你是， +* 第一次接触 Dubbo，请继续阅读本章了解 Dubbo 提供的丰富功能及核心概念； +* 想快速体验 Dubbo，请参考 [快速开始](../quickstart) +* 高级用法请参考 [多语言 SDK 文档](../mannual) +* 关注 Dubbo3 + * [3.0 设计理念与核心功能](../whatsnew) + * [如何迁移到 Dubbo3](../../java-sdk/upgrades-and-compatibility) + + diff --git a/content/zh/docs3-building/docs/what/architecture.md b/content/zh/docs3-building/docs/what/architecture.md new file mode 100644 index 000000000000..a1cbf95880de --- /dev/null +++ b/content/zh/docs3-building/docs/what/architecture.md @@ -0,0 +1,77 @@ +--- +type: docs +title: "总体架构" +linkTitle: "总体架构" +weight: 2 +--- + +作为一个微服务框架，Dubbo sdk 跟随着微服务组件被部署在分布式集群各个位置，为了在分布式环境下实现各个微服务组件间的协作， +Dubbo 定义了一些中心化组件，这包括： +* 注册中心。协调 Consumer 与 Provider 之间的地址注册与发现 +* 配置中心。 + * 存储 Dubbo 启动阶段的全局配置，保证配置的跨环境共享与全局一致性 + * 负责服务治理规则（路由规则、动态配置等）的存储与推送。 +* 元数据中心。 + * 接收 Provider 上报的服务接口元数据，为 Admin 等控制台提供运维能力（如服务测试、接口文档等） + * 作为服务发现机制的补充，提供额外的接口/方法级别配置信息的同步能力，相当于注册中心的额外扩展 + +![threecenters](/imgs/v3/concepts/threecenters.png) + +上图完整的描述了 Dubbo 微服务组件与各个中心的交互过程。 + +以上三个中心并不是运行 Dubbo 的必要条件，用户完全可以根据自身业务情况决定只启用其中一个或多个，以达到简化部署的目的。通常情况下，所有用户都会以独立的注册中心 +以开始 Dubbo 服务开发，而配置中心、元数据中心则会在微服务演进的过程中逐步的按需被引入进来。 + +## 注册中心 + +注册中心扮演着非常重要的角色，它承载着服务注册和服务发现的职责。目前Dubbo支持以下两种粒度的服务发现和服务注册，分别是接口级别和应用级别，注册中心可以按需进行部署： + +- 在传统的Dubbo SDK使用姿势中，如果仅仅提供直连模式的RPC服务，不需要部署注册中心。 +- 无论是接口级别还是应用级别，如果需要Dubbo SDK自身来做服务注册和服务发现，则可以选择部署注册中心，在Dubbo中集成对应的注册中心。 + +- 在Dubbo + Mesh 的场景下，随着 Dubbo 服务注册能力的弱化，Dubbo内的注册中心也不再是必选项，其职责开始被控制面取代，如果采用了Dubbo + Mesh的部署方式，无论是ThinSDK的mesh方式还是Proxyless的mesh方式，都不再需要独立部署注册中心。 + +而注册中心并不依赖于配置中心和元数据中心，如下图所示： + +![centers-registry](/imgs/v3/concepts/centers-registry.png) + +该图中没有部署配置中心和元数据中心，在Dubbo中会默认将注册中心的实例同时作为配置中心和元数据中心，这是Dubbo的默认行为，如果确实不需要配置中心或者元数据中心的能力，可在配置中关闭，在注册中心的配置中有两个配置分别为use-as-config-center和use-as-metadata-center，将配置置为false即可。 + +## 元数据中心 + +元数据中心在2.7.x版本开始支持，随着应用级别的服务注册和服务发现在Dubbo中落地，元数据中心也变的越来越重要。在以下几种情况下会需要部署元数据中心： + +1. 对于一个原先采用老版本Dubbo搭建的应用服务，在迁移到Dubbo 3时，Dubbo 3 会需要一个元数据中心来维护RPC服务与应用的映射关系（即接口与应用的映射关系），因为如果采用了应用级别的服务发现和服务注册，在注册中心中将采用“应用 —— 实例列表”结构的数据组织形式，不再是以往的“接口 —— 实例列表”结构的数据组织形式，而以往用接口级别的服务注册和服务发现的应用服务在迁移到应用级别时，得不到接口与应用之间的对应关系，从而无法从注册中心得到实例列表信息，所以Dubbo为了兼容这种场景，在Provider端启动时，会往元数据中心存储接口与应用的映射关系。 +2. 为了让注册中心更加聚焦与地址的发现和推送能力，减轻注册中心的负担，元数据中心承载了所有的服务元数据、大量接口/方法级别配置信息等，无论是接口粒度还是应用粒度的服务发现和注册，元数据中心都起到了重要的作用。 + +如果有以上两种需求，都可以选择部署元数据中心，并通过Dubbo的配置来集成该元数据中心。 + +元数据中心并不依赖于注册中心和配置中心，用户可以自由选择是否集成和部署元数据中心，如下图所示： + +![centers-metadata](/imgs/v3/concepts/centers-metadata.png) + +该图中不配备配置中心，意味着可以不需要全局管理配置的能力。该图中不配备注册中心，意味着可能采用了Dubbo mesh的方案，也可能不需要进行服务注册，仅仅接收直连模式的服务调用。 + +## 配置中心 + +配置中心与其他两大中心不同，它无关于接口级还是应用级，它与接口并没有对应关系，它仅仅与配置数据有关，即使没有部署注册中心和元数据中心，配置中心也能直接被接入到Dubbo应用服务中。在整个部署架构中，整个集群内的实例（无论是Provider还是Consumer）都将会共享该配置中心集群中的配置，如下图所示： +![centers-config](/imgs/v3/concepts/centers-config.png) + +该图中不配备注册中心，意味着可能采用了Dubbo mesh的方案，也可能不需要进行服务注册，仅仅接收直连模式的服务调用。 + +该图中不配备元数据中心，意味着Consumer可以从Provider暴露的MetadataService获取服务元数据，从而实现RPC调用 + +## 保证三大中心高可用的部署架构 + +虽然三大中心已不再是Dubbo应用服务所必须的，但是在真实的生产环境中，一旦已经集成并且部署了该三大中心，三大中心还是会面临可用性问题，Dubbo需要支持三大中心的高可用方案。在Dubbo中就支持多注册中心、多元数据中心、多配置中心，来满足同城多活、两地三中心、异地多活等部署架构模式的需求。 + +Dubbo SDK对三大中心都支持了Multiple模式。 + +- 多注册中心：Dubbo 支持多注册中心，即一个接口或者一个应用可以被注册到多个注册中心中，比如可以注册到ZK集群和Nacos集群中，Consumer也能够从多个注册中心中进行订阅相关服务的地址信息，从而进行服务发现。通过支持多注册中心的方式来保证其中一个注册中心集群出现不可用时能够切换到另一个注册中心集群，保证能够正常提供服务以及发起服务调用。这也能够满足注册中心在部署上适应各类高可用的部署架构模式。 +- 多配置中心：Dubbo支持多配置中心，来保证其中一个配置中心集群出现不可用时能够切换到另一个配置中心集群，保证能够正常从配置中心获取全局的配置、路由规则等信息。这也能够满足配置中心在部署上适应各类高可用的部署架构模式。 + +- 多元数据中心：Dubbo 支持多元数据中心：用于应对容灾等情况导致某个元数据中心集群不可用，此时可以切换到另一个元数据中心集群，保证元数据中心能够正常提供有关服务元数据的管理能力。 + +拿注册中心举例，下面是一个多活场景的部署架构示意图： + +![multiple-registry-deployment-architecture](/imgs/v3/concepts/multiple-registry-deployment-architecture.png) diff --git a/content/zh/docs3-building/docs/what/ecosystem.md b/content/zh/docs3-building/docs/what/ecosystem.md new file mode 100644 index 000000000000..6cd59c98d378 --- /dev/null +++ b/content/zh/docs3-building/docs/what/ecosystem.md @@ -0,0 +1,57 @@ +--- +type: docs +title: "Dubbo 生态" +linkTitle: "生态系统" +weight: 3 +description: "" +--- + +### 多语言实现 +* Golang +* Java +* Rust +* Javascript +* Python +* PHP + +### Dashboard +* Dubbo-admin + +### 中心化组件 +* 注册中心 + * Zookeeper + * Nacos + * Kubernetes +* 元数据中心 + * Zookeeper + * Nacos + * Redis +* 配置中心 + * Zookeeper + * Nacos + * Redis + * Apollo + +### 协议与互通性 +* 如何实现与 gRPC 体系互通 +* 如何实现与 Spring Cloud 体系互通 + +### SPI 集成 +* dubbo-spi-extensions +* 参见 SPI 扩展说明 + +### 网关组件 +* Apache Shenyu(Incubating) +* Apache APISIX +* Apache Dubbo-pixiu +* Tengine + +### 链路追踪 +* Zipkin +* Apache Skywalking + +### 其他微服务组件 +* Sentinel +* Seata + + diff --git a/content/zh/docs3-building/docs/what/overview.md b/content/zh/docs3-building/docs/what/overview.md new file mode 100644 index 000000000000..9021b8c2fdbb --- /dev/null +++ b/content/zh/docs3-building/docs/what/overview.md @@ -0,0 +1,113 @@ +--- +type: docs +title: "Dubbo 简介" +linkTitle: "了解 Dubbo" +weight: 1 +description: "" +--- + +Apache Dubbo 是一款 RPC 服务开发框架，用于解决微服务架构下的服务治理与通信问题，并提供了 Java、Golang 等多种语言的 SDK 实现。使用 Dubbo 开发的微服务，将原生具备相互之间的远程地址发现与通信能力， +同时利用 Dubbo 提供的丰富服务治理特性，可以实现诸如服务发现、负载均衡、流量调度等服务治理诉求。Dubbo 被设计为高度可扩展，用户几乎可以在任意功能点去定制自己的实现以满足自身业务需求。 + +3.0 版本（Dubbo3）开始，我们将 Dubbo 定义为面向云原生的下一代 RPC 服务框架。3.0 基于 [Dubbo 2.x]() 演进而来，在保持原有核心功能特性的同时， Dubbo3 在易用性、超大规模微服务实践、云原生基础设施适配、安全性等几大方向上进行了全面升级。 + +### Dubbo 是什么 + +Apache Dubbo 是一款开源 RPC 服务框架，它最初在 2008 年由 Alibaba 捐献开源，并且很快成为了国内开源服务框架选型的事实标准框架，得到了各行各业的广泛应用。在 2017 年，Dubbo 正式捐献到 Apache 软件基金会并成为 Apache 顶级项目，目前 Dubbo3 已经是一站式的微服务解决方案提供： +* 基于 HTTP/2 的 [Triple 协议]()以及面向代理 API 的编程体验。 +* 强大的[流量治理能力]()，如地址发现、负载均衡、路由选址、动态配置等。 +* [多语言 SDK 实现]()，涵盖 Java、Golang、Javascript 等，更多语言实现将会陆续发布。 +* 灵活的适配与扩展能力，可轻松与微服务体系其他组件如 Tracing、Transaction 等适配。 +* [Service Mesh 解决方案]()，同时支持 Sidecar、Proxyless 等灵活的 Mesh 部署方案。 + +Apache Dubbo 总体架构能很好的满足企业的大规模微服务实践，因为它从设计之初就是为了解决超大规模微服务集群实践问题，不论是阿里巴巴还是工商银行、中国平安、携程等社区用户，它们都通过多年的大规模生产环境流量对 Dubbo 的稳定性与性能进行了充分验证，因此，Dubbo 在解决业务落地与规模化实践方面有着无可比拟的优势： +* 开箱即用 + * 易用性高，如 Java 版本的面向接口代理特性能实现本地透明调用 + * 功能丰富，基于原生库或轻量扩展即可实现绝大多数的微服务治理能力 +* 面向超大规模微服务集群设计 + * 极致性能，高性能的 RPC 通信协议设计与实现 + * 横向可扩展，轻松支持百万规模集群实例的地址发现与流量治理 +* [高度可扩展]() + * 调用过程中对流量及协议的拦截扩展，如 Filter、Router、LB 等 + * 微服务治理组件扩展，如 Registry、Config Center、Metadata Center 等 +* 企业级微服务治理能力 + * 国内共有云厂商支持的事实标准服务框架 + * 多年企业实践经验考验，参考[用户实践案例](../../users) + +### Dubbo 基本工作流程 + +![dubbo-rpc](/imgs/v3/concepts/rpc.png) + +Dubbo 首先是一款 RPC 框架，它定义了自己的 RPC 通信协议与编程方式。如上图所示，用户在使用 Dubbo 时首先需要定义好 Dubbo 服务；其次，是在将 Dubbo 服务部署上线之后，依赖 Dubbo 的应用层通信协议实现数据交换，Dubbo 所传输的数据都要经过序列化，而这里的[序列化协议]()是完全可扩展的。 +使用 Dubbo 的第一步就是定义 Dubbo 服务，服务在 Dubbo 中的定义就是完成业务功能的一组方法的集合，可以选择使用与某种语言绑定的方式定义，如在 Java 中 Dubbo 服务就是有一组方法的 Interface 接口，也可以使用语言中立的 Protobuf Buffers [IDL 定义服务]()。定义好服务之后，服务端（Provider）需要提供服务的具体实现，并将其声明为 Dubbo 服务，而站在服务消费方（Consumer）的视角，通过调用 Dubbo 框架提供的 API 可以获得一个服务代理（stub）对象，然后就可以像使用本地服务一样对服务方法发起调用了。 +在消费端对服务方法发起调用后，Dubbo 框架负责将请求发送到部署在远端机器上的服务提供方，提供方收到请求后会调用服务的实现类，之后将处理结果返回给消费端，这样就完成了一次完整的服务调用。如图中的 Request、Response 数据流程所示。 +>需要注意的是，在 Dubbo 中，我们提到服务时，通常是指 RPC 粒度的、提供某个具体业务增删改功能的接口或方法，与一些微服务概念书籍中泛指的服务并不是一个概念。 + +在分布式系统中，尤其是随着微服务架构的发展，应用的部署、发布、扩缩容变得极为频繁，作为 RPC 消费方，如何定动态的发现服务提供方地址成为 RPC 通信的前置条件。Dubbo 提供了自动的地址发现机制，用于应对分布式场景下机器实例动态迁移的问题。如下图所示，通过引入注册中心来协调提供方与消费方的地址，提供者启动之后向注册中心注册自身地址，消费方通过拉取或订阅注册中心特定节点，动态的感知提供方地址列表的变化。 + +![arch-service-discovery](/imgs/v3/architecture.png) + +地址发现解决了实例变更的问题，但微服务环境下的服务治理诉求同样变得非常复杂，用户需要考虑 Dubbo 服务治理的问题如服务测试、服务元数据管理、流量管控、动态行为调整等，为此， Dubbo 架构引入了配置中心、元数据中心进一步拓展了其服务治理边界。 + +![how-dubbo-works](/imgs/v3/concepts/threecenters.png) + +随着云原生架构的发展，更多的微服务组件及能力正下沉到以 Kubernetes 为代表的基础设施层。一方面传统微服务开发框架应剔除一些冗余机制，积极的适配到基础设施层以做到能力复用；另一方面微服务框架生命周期、服务治理等能力应更好地与 Kubernetes 服务编排机制融合。更近一步的，以 Service Mesh 为代表的微服务架构给微服务开发带来了新的选择，Dubbo3 也完成了对 Kubernetes、Mesh 的适配。 + +![mix-mesh](/imgs/v3/mesh/mix-mesh.png) + +### Dubbo 核心特性 + +#### 高性能 RPC 通信协议 +跨进程或主机的服务通信是 Dubbo 的一项基本能力，Dubbo RPC 以预先定义好的协议编码方式将请求数据（Request）发送给后端服务，并接收服务端返回的计算结果（Response）。RPC 通信对用户来说是完全透明的，使用者无需关心请求是如何发出去的、发到了哪里，每次调用只需要拿到正确的调用结果就行。除了同步模式的 Request-Response 通信模型外，Dubbo3 还提供更丰富的通信模型选择： +* 消费端异步请求(Client Side Asynchronous Request-Response) +* 提供端异步执行（Server Side Asynchronous Request-Response） +* 消费端请求流（Request Streaming） +* 提供端响应流（Response Streaming） +* 双向流式通信（Bidirectional Streaming） + +具体可参见[可选协议列表]()、[Triple协议]() + +#### 自动服务（地址）发现 +Dubbo 的服务发现机制，让微服务组件之间可以独立演进并任意部署，消费端可以在无需感知对端部署位置与 IP 地址的情况下完成通信。Dubbo 提供的是 Client-Based 的服务发现机制，使用者可以有多种方式启用服务发现： +* 使用独立的注册中心组件，如 Nacos、Zookeeper、Consul、Etcd 等。 +* 将服务的组织与注册交给底层容器平台，如 Kubernetes，这被理解是一种更云原生的使用方式 + +#### 运行态流量管控 +透明地址发现让 Dubbo 请求可以被发送到任意 IP 实例上，这个过程中流量被随机分配。当需要对流量进行更丰富、更细粒度的管控时，就可以用到 Dubbo 的流量管控策略，Dubbo 提供了包括负载均衡、流量路由、请求超时、流量降级、重试等策略，基于这些基础能力可以轻松的实现更多场景化的路由方案，包括金丝雀发布、A/B测试、权重路由、同区域优先等，更酷的是，Dubbo 支持流控策略在运行态动态生效，无需重新部署。具体可参见： +* [路由说明]() +* [负载均衡]() +* [服务治理示例]() + +#### 丰富的扩展组件及生态 +Dubbo 强大的服务治理能力不仅体现在核心框架上，还包括其优秀的扩展能力以及周边配套设施的支持。通过 Filter、Router、Protocol 等几乎存在于每一个关键流程上的扩展点定义，我们可以丰富 Dubbo 的功能或实现与其他微服务配套系统的对接，包括 Transaction、Tracing 目前都有通过 SPI 扩展的实现方案，具体可以参见 Dubbo 扩展性的详情，也可以在 [apache/dubbo-spi-extensions](https://github.com/apache/dubbo-spi-extensions) 项目中发现与更多的扩展实现。具体可参见： +* [Dubbo 生态]() +* [官方扩展组件]() +* [Dubbo 可扩展性设计]() + +#### 面向云原生设计 + +Dubbo 从设计上是完全遵循云原生微服务开发理念的，这体现在多个方面，首先是对云原生基础设施与部署架构的支持，包括 Kubernetes、Service Mesh 等，另一方面，Dubbo 众多核心组件都已面向云原生升级，包括 Triple 协议、统一路由规则、对多语言支持。值得一提的是，如何使用 Dubbo 支持弹性伸缩的服务如 Serverless 也在未来计划之中，这包括利用 Native Image 提高 Dubbo 的启动速度与资源消耗等。 + +结合当前版本，本节主要从以下两点展开 Dubbo 的云原生特性 +* 容器调度平台（Kubernetes） +* Service Mesh + +##### Kubernetes +Dubbo 微服务要支持 Kubernetes 平台调度，最基础的就是实现 dubbo 服务生命周期与容器生命周期的对齐，这包括 Dubbo 的启动、销毁、服务注册等生命周期事件。相比于以往 Dubbo 自行定义生命周期事件，并要求开发人员在运维实践过程中遵守约定，Kubernetes 底层基础设施定义了严格的组件生命周期事件(probe)，转而要求 Dubbo 去按约定适配。 + +Kubernetes Service 是另一个层面的适配，这体现了服务定义与注册向云原生底层基础设施下沉的趋势。在这种模式下，用户不再需要搭建额外的注册中心组件，Dubbo 消费端节点能自动对接到 Kubernetes（API-Server 或 DNS），根据服务名（Kubernetes Service Name） 查询到实例列表（Kubernetes endpoints）。 此时服务是通过标准的 Kubernetes Service API 定义，并被调度到各个节点。 + +##### Service Mesh + +Service Mesh 在业界得到了广泛的传播与认可，并被认为是下一代的微服务架构，这主要是因为它解决了很多棘手的问题，包括透明升级、多语言、依赖冲突、流量治理等。Service Mesh 的典型架构是通过部署独立的 Sidecar 组件来拦截所有的出口与入口流量，并在 Sidecar 中集成丰富的流量治理策略如负载均衡、路由等，除此之外，Service Mesh 还需要一个控制面（Control Panel）来实现对 Sidecar 流量的管控，即各种策略下发。我们在这里称这种架构为经典 Mesh。 + +然而任何技术架构都不是完美的，经典 Mesh 在实施层面也面临成本过高的问题 +1. 需要运维控制面（Control Panel） +2. 需要运维 Sidecar +3. 需要考虑如何从原有 SDK 迁移到 Sidecar +4. 需要考虑引入 Sidecar 后整个链路的性能损耗 + +为了解决 Sidecar 引入的相关成本问题，Dubbo 引入了另一种变相的 Mesh 架构 - Proxyless Mesh，顾名思义，Proxyless Mesh 就是指没有 Sidecar 的部署，转而由 Dubbo SDK 直接与控制面交互，其架构图如下 + + +可以设想，在不同的组织、不同的发展阶段，未来以 Dubbo 构建的微服务将会允许有三种部署架构：传统 SDK、基于 Sidecar 的 Service Mesh、脱离 Sidecar 的 Proxyless Mesh。基于 Sidecar 的 Service Mesh，即经典的 Mesh 架构，独立的 sidecar 运行时接管所有的流量，脱离 Sidecar 的 Proxyless Mesh，富 SDK 直接通过 xDS 与控制面通信。Dubbo 微服务允许部署在物理机、容器、Kubernetes 平台之上，能做到以 Admin 为控制面，以统一的流量治理规则进行治理。 diff --git a/content/zh/docs3-building/docs/what/usecases.md b/content/zh/docs3-building/docs/what/usecases.md new file mode 100644 index 000000000000..723ca4e20d8c --- /dev/null +++ b/content/zh/docs3-building/docs/what/usecases.md @@ -0,0 +1,9 @@ +--- +type: docs +title: "用户案例" +linkTitle: "用户案例" +weight: 4 +manualLinkRelref: ../../users/ +manualLinkTarget: _blank +_build: { render: link } +--- \ No newline at end of file diff --git a/content/zh/docs3-building/docs/whatsnew/_index.md b/content/zh/docs3-building/docs/whatsnew/_index.md new file mode 100755 index 000000000000..a1271d1a58d9 --- /dev/null +++ b/content/zh/docs3-building/docs/whatsnew/_index.md @@ -0,0 +1,31 @@ + +--- +type: docs +title: "3.0 速览" +linkTitle: "3.0 速览" +weight: 3 +content: + - 核心特性: + - "[Triple]()" + - "[Examples]()" + - 关注迁移: + - "[Java](../java-sdk/)" + - "[Golang](../golang-sdk/upgrades-and-compatibility/)" + - 其他问题: + - "[性能指标](../java-sdk/)" + - "[相关资源](../golang-sdk/upgrades-and-compatibility/)" +cascade: + - show_banner: true +--- + +[背景](background.md) 部分带你快速了解 Dubbo3 的设计背景、总体架构与核心特性、与典型用户如阿里巴巴 HSF2 的关系等。也可以通过如下部分了解更多： +* 小白用户，**快速浏览 Dubbo3 核心特性：** + * [下一代通信协议 - Triple](triple.md) + * [百万实例集群的秘密 - 应用级服务发现](servicediscovery3.md) + * [Dubbo Mesh](mesh.md) +* Dubbo3 的兼容性与迁移成本? + * [Java - 迁移指南](../../java-sdk/) + * [Golang - 迁移指南](../../golang-sdk/) +* 其他 **Dubbo3 相关资源：** + * 更多资料，如性能指标、高级特性说明等请参考 [多语言 SDK 实现](../mannual/) + * [演讲与线下活动](../../activities/) diff --git a/content/zh/docs3-building/docs/whatsnew/background.md b/content/zh/docs3-building/docs/whatsnew/background.md new file mode 100644 index 000000000000..ded8a5751913 --- /dev/null +++ b/content/zh/docs3-building/docs/whatsnew/background.md @@ -0,0 +1,66 @@ +--- +type: docs +title: "背景" +linkTitle: "背景" +weight: 1 +--- +Dubbo3 的设计与开发有两个大的背景。 + +**首先，如何更好的满足企业实践诉求。** Dubbo 自 2011 由阿里巴巴捐献开源以来，一直是众多大型企业微服务实践的首选开源服务框架。在此期间，企业架构经历了从 SOA 架构到微服务架构变迁，Dubbo 社区自身也在不断的更新迭代以更好的满足企业诉求。然而 Dubbo2 架构上的局限逐渐在实践中凸显：1.协议，Dubbo2 协议以性能、简洁著称，但却在云原生时代遇到越来越多的通用性、穿透性问题；2.可伸缩性，Dubbo2 在可伸缩性上依旧远超很多其他框架，但随着微服务带来更多应用与实例我们不得不思考如何应对更大规模集群的实战；3.服务治理易用性，如更丰富的流量治理、可观测性、智能负载均衡等。 + +**其次，适配云原生技术栈的发展。** 微服务让业务开发演进更灵活、快捷的同时，也带来了一些它独有的特征和需求：如微服务之后组件数量越来越多，如何解决各个组件的稳定性，如何快速的水平扩容等，以 Docker、Kubernetes、Service Mesh 为代表的云原生基础设施为解决这些问题带来了一些新的选择。随着更多的微服务组件及能力正下沉到以 Kubernetes 为代表的基础设施层，传统微服务开发框架应剔除一些冗余机制，积极的适配到基础设施层以做到能力复用，微服务框架生命周期、服务治理等能力应更好地与 Kubernetes 服务编排机制融合； 以 Service Mesh 为代表微服务架构给微服务开发带来的新的选择，Sidecar 给多语言、透明升级、流量管控等带来的优势，但同时也带来运维复杂性、性能损耗等弊端，因此基于服务框架的传统微服务体系还将是主流，长期仍将占据半壁江山，在长时间内将会维持混合部署将会维持混合部署状态。 + +### 总体目标 +Dubbo3 依旧保持了 2.x 的经典架构，以解决微服务进程间通信为主要职责，通过丰富的服务治理（如地址发现、流量管理等）能力来更好的管控微服务集群；Dubbo3 对原有框架的升级是全面的，体现在核心 Dubbo 特性的几乎每个环节，通过升级实现了稳定性、性能、伸缩性、易用性的全面提升。 + +![architecture-1](../../../imgs/v3/concepts/architecture-1.png) + +* **通用的通信协议。** 全新的 RPC 协议应摒弃私有协议栈，以更通用的 HTTP/2 协议为传输层载体，借助 HTTP 协议的标准化特性，解决流量通用性、穿透性等问题，让协议能更好的应对前后端对接、网关代理等场景；支持 Stream 通信模式，满足不同业务通信模型诉求的同时给集群带来更大的吞吐量。 +* **面向百万集群实例，集群高度可伸缩。** 随着微服务实践的推广，微服务集群实例的规模也在不停的扩展，这得益于微服务轻量化、易于水平扩容的特性，同时也给整个集群容量带来了负担，尤其是一些中心化的服务治理组件；Dubbo3 需要解决实例规模扩展带来的种种资源瓶颈问题，实现真正的无限水平扩容。 +* **更丰富的编程模型，更小的业务侵入。** 在开发态业务应用面向 Dubbo SDK 编程，在运行态 SDK 与业务应用运行在同一个进程，SDK 的易用性、稳定性与资源消耗将在很大程度上影响业务应用；因此 3.0 应该具备更抽象的 API、更友好的配置模式、更少的侵占业务应用资源、具备更高的可用性。 +* **更易用、更丰富的服务治理能力。** 微服务的动态特性给治理工作带来了很高的复杂性，而 Dubbo 这方面一直做的不错，是最早的一批治理能力定义者与实践者；3.0 需面向更丰富的场景化，提供诸如可观测性、安全性、灰度发布、错误注入、外部化配置、统一的治理规则等能力。 +* **全面拥抱云原生。** + +### 面向企业生产实践痛点 +Dubbo2 仍旧是国内首选开源服务框架，被广泛应用在互联网、金融保险、软件企业、传统企业等几乎所有数字化转型企业中，久经规模化生产环境检验。以 Dubbo2 的贡献者和典型用户阿里巴巴为例，阿里巴巴基于 Dubbo2 在内部维护的 HSF2 框架经历了历次双十一峰值考验，每天数十亿次的 RPC 调用，治理着超过千万的服务实例。在长期的优化和实践积累中，阿里巴巴有了对下一代服务框架的设想与方案，在内部开始了快速演进，并快速的被贡献到 Apache 社区，如同阿里巴巴一样，其他用户的实践诉求与痛点也在开源社区快速的积累，形成了一致的方向和技术方案，可以说 Dubbo3 的诞生就来自于超大基数的企业用户积累，为了更好的满足他们的实践诉求。 + +![dubbo3-hsf](../../../imgs/v3/concepts/dubbo-hsf.png) + +Dubbo3 融合了阿里巴巴 HSF2 及其他社区企业的大量服务治理经验，当前 Dubbo3 已经被全面应用到生产实践环境，用户包括阿里巴巴电商、饿了么、钉钉、考拉、阿里云、小米、工商银行、风火递、平安健康等。社区与用户的合作形成的良性循环极大的促进了 Dubbo3 的发展，阿里巴巴已经以社区版 Dubbo3 完全取代了内部维护的 HSF2 框架，他们的实践经验一方面推动 Dubbo3 的稳定性，另一方面正够源源不断的将服务治理实践经验输出到开源社区。 + +### 面向百万集群实例，横向可扩容 +随着微服务实践经验的积累，微服务被拆分成更细粒度，部署到越来越多的机器实例，以支撑不断增长的业务规模。在众多的 Dubbo2 企业用户中，尤其是以金融保险、互联网为代表的规模化企业开始遇到集群容量瓶颈问题（典型的请参照[工商银行实践案例]()）： +* 服务发现过程 + * 注册中心数据存储规模达到容量瓶颈 + * 数据注册&推送效率严重下降 +* Dubbo 进程 + * 侵占更多机器资源，导致业务资源利用率降低 + * 频繁 GC 影响业务稳定性 + +Dubbo3 在设计上很好的解决了这些问题，通过全新设计实现的服务治理（服务发现）模型，可以实现服务发现链路上的数据传输、数据存储量平均下降 90% 左右；同时 Dubbo3 自身在业务进程中变得更轻量、更稳定，实现提升资源利用率 50%。 + +Dubbo3 一个更大的优势在于其对整体架构稳定性的提升，新的服务发现架构使得对于整个集群容量、可伸缩性评估变得更容易、更准确。 + +![capacity](../../../imgs/v3/concepts/capacity.png) + +如果将应用开发粗略划分为业务开发、运维部署两个层次，其中变化比较频繁的因素包括服务（接口）、应用、机器实例。在 2.x 时代，所有这三个因素的增长都会影响微服务集群的总体容量，尤其是接口增减带来的波动，对整体容量评估是非常不透明的。而在 3.0 中集群容量变化仅与应用名、机器实例两个因素相关，而我们容量评估的对象往往都是应用与实例，因此整个集群集群变的更稳定透明。 + +### 云原生 +在云原生时代，底层基础设施的变革正深刻影响应用的部署、运维甚至开发过程，往上也影响了 Dubbo3 微服务技术方案的选型与部署模式。 + +#### 下一待 RPC 协议 +新一代的 Triple 协议基于 HTTP/2 作为传输层，具备更好的网关、代理穿透性，原生支持 Stream 通信语义，兼容 gRPC 协议。 + +#### 多语言友好 +Dubbo3 从服务定义、RPC 协议、序列化、服务治理等多个方面都已经将多语言友好性作为重点考量因素，目前提供了 Java、Golang 稳定的多语言版本，更多语言版本的 3.0 实现如 Rust、Javascript、C/C++、C# 等在开发建设中。 + +#### Kubernetes +Dubbo3 开发的应用可以原生部署到 Kubernetes 平台，Dubbo3 在地址、生命周期等已设计可与 Kubernetes 等容器调度平台对齐；对于要进一步复用 Kubernetes 底层基础设施能力的用户来说，Dubbo3 也已对接到了原生的 Kubernetes Service 体系。 + +#### Serivice Mesh +Service Mesh 强调控制面在微服务治理中的作用，在一定程度上推动了控制面通信协议、职责范围的扩展与标准化；传统 Mesh 架构下的 Sidecar 模型强调旁路代理对于流量的统一管控，以实现透明升级、多语言无感、无业务侵入等特性。 + +Dubbo3 提供了基于自身思考的 Dubbo Mesh 解决方案，强调了控制面对微服务集群的统一管控，而在部署架构上，同时支持 sicecar 与无 sidecar 的 proxyless 部署架构，使用 Dubbo Mesh 的用户基于自身的业务特点将有更多的部署架构选择。 + +#### 异构体系互通 +我们正看到越来越多的异构微服务体系互通的诉求，典型如 Dubbo、Spring Cloud、gRPC 等。有些是因为技术栈迁移，有些是组织合并后需要实现业务互调，Dubbo3 借助于新的服务发现模型以及可灵活扩展的 RPC 协议，可以成为 \ No newline at end of file diff --git a/content/zh/docs3-building/docs/whatsnew/mesh.md b/content/zh/docs3-building/docs/whatsnew/mesh.md new file mode 100644 index 000000000000..3a88a01ae13b --- /dev/null +++ b/content/zh/docs3-building/docs/whatsnew/mesh.md @@ -0,0 +1,61 @@ +--- +type: docs +title: "Dubbo Mesh" +linkTitle: "Dubbo Mesh" +weight: 4 +--- +通过以下示例快速查看使用&部署示例 +* [Dubbo Sidecar Mesh]() +* [Dubbo Proxyless Mesh]() + +## Service Mesh +在云原生背景下，如果我们将 Service Mesh 理解为底层基础设施，则在 Mesh 架构中，以往耦合在业务进程中的微服务治理部分能力正被 Mesh 接管，传统微服务框架更注重 RPC 协议与编程模型。以下是时下流行的 Mesh 产品 Istio 的架构图： + +![istio](/imgs/istio.png) + +在 Mesh 架构下 +* 统一的控制面提供证书管理、可观测性、流量治理等能力 +* Sidecar 让 SDK 更轻量、侵入性更小，更好的实现透明升级、流量拦截等 + +## Dubbo Mesh +Dubbo Mesh 从设计理念上更强调控制面的统一管控、标准化与治理能力，而在数据面给出了更多的选择，包括 Sidecar Mesh 与 Proxyless Mesh 等部署模式。 +多种部署模型给企业提供了更多选择，通过混合部署的模型，在实现服务治理控制面的共享的同时，可以更好的应对不同场景的部署要求，适应复杂的基础设施环境并从总体上提升架构的可用性。 + +![dubbo-sidecar](/imgs/dubbo-sidecar.png) + +### Sidecar Mesh + +![dubbo-sidecar](/imgs/dubbo-sidecar.png) + +如上图所示，Dubbo 可以与 Sidecar 部署在同一个 Pod 或容器中，通过在外围部署一个独立的控制平面，实现对流量和治理的统一管控。控制面与 SIcecar 之间通过图中虚线所示的 xDS 协议进行配置分发，而 Dubbo 进程间的通信不再是直连模式，转而通过 Sidecar 代理，Sidecar 拦截所有进出流量，并完成路由寻址等服务治理任务。 + +Sidecar 模式的 Mesh 架构有很多优势，如平滑升级、多语言、业务侵入小等，但也带来了一些额外的问题，比如： +* Sidecar 通信带来了额外的性能损耗，这在复杂拓扑的网络调用中将变得尤其明显。 +* Sidecar 的存在让应用的声明周期管理变得更加复杂。 +* 部署环境受限，并不是所有的环境都能满足 Sidecar 部署与请求拦截要求。 + +### Proxyless Mesh +![dubbo-proxyless](/imgs/dubbo-proxyless.png) + +针对上述问题，Dubbo 社区自很早之前就做了 Dubbo 直接对接到控制面的设想与思考，并在国内开源社区率先提出了 Proxyless Mesh 的概念，Proxyless 概念最开始是谷歌提出来的。 +Proxyless 模式使得微服务又回到了 2.x 时代的部署架构，如上图所示，和我们上面看的 Dubbo 经典服务治理模式非常相似，所以说这个模式并不新鲜， Dubbo 从最开始就是这么样的设计模式。但相比于 Mesh 架构，Dubbo2 并没有强调控制面的统一管控，而这点恰好是 Service Mesh 所强调的，强调对流量、可观测性、证书等的标准化管控与治理，也是 Mesh 理念先进的地方。 + +通过不同语言版本的 Dubbo3 SDK 直接实现 xDS 协议解析，实现 Dubbo 与 Control Plane 的直接通信，进而实现控制面对流量管控、服务治理、可观测性、安全等的统一管控，规避 Sidecar 模式带来的性能损耗与部署架构复杂性。 + +在 Dubbo3 Proxyless 架构模式下，Dubbo 进程将直接与控制面通信，Dubbo 进程之间也继续保持直连通信模式，我们可以看出 Proxyless 架构的优势： +* 没有额外的 Proxy 中转损耗，因此更适用于性能敏感应用 +* 更有利于遗留系统的平滑迁移 +* 架构简单，容易运维部署 +* 适用于几乎所有的部署环境 + +### 高级用法 +Dubbo SDK 提供了非常灵活的配置来控制服务治理行为，如接口粒度的服务地址发现能力、接口粒度的配置同步等，这些能力让应用的开发和部署更加灵活。而在通用的 Mesh 部署方案或产品下一些高级功能可能受限，从总体上影响了易用性与灵活性，为此 Dubbo 计划提供了一些变种的部署方案或控制面定制产品，以满足深度用户的一些高级需求。 + + + + + + + + + diff --git a/content/zh/docs3-building/docs/whatsnew/servicediscovery3.md b/content/zh/docs3-building/docs/whatsnew/servicediscovery3.md new file mode 100644 index 000000000000..ed73940a7370 --- /dev/null +++ b/content/zh/docs3-building/docs/whatsnew/servicediscovery3.md @@ -0,0 +1,11 @@ +--- +type: docs +title: "应用级服务发现" +linkTitle: "应用级服务发现" +weight: 3 +--- + + + + + diff --git a/content/zh/docs3-building/docs/whatsnew/triple.md b/content/zh/docs3-building/docs/whatsnew/triple.md new file mode 100644 index 000000000000..51a68a9c06a9 --- /dev/null +++ b/content/zh/docs3-building/docs/whatsnew/triple.md @@ -0,0 +1,9 @@ +--- +type: docs +title: "Triple 协议" +linkTitle: "Triple 协议" +weight: 2 +--- + + + diff --git a/content/zh/docs3-building/golang-sdk/_index.md b/content/zh/docs3-building/golang-sdk/_index.md new file mode 100755 index 000000000000..937577306c5c --- /dev/null +++ b/content/zh/docs3-building/golang-sdk/_index.md @@ -0,0 +1,8 @@ + +--- +type: docs +title: "Golang" +linkTitle: "Golang" +weight: 3 +--- + diff --git a/content/zh/docs3-building/java-sdk/_index.md b/content/zh/docs3-building/java-sdk/_index.md new file mode 100755 index 000000000000..eaaa2dacd989 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/_index.md @@ -0,0 +1,23 @@ + +--- +type: docs +title: "Java" +weight: 3 +#no_list: true +#hide_summary: true +content: + - 快速开始: + - "[Spring Boot 快速开始](quick-start/)" + - 概念与架构: + - "[性能与基准测试](concepts-and-architecture/)" + - 高级特性: + - "[常用高级配置方式](advanced-features-and-usage/)" + - 参考手册: + - "[可扩展性：Filter、Router 等](reference-manual/)" + - "[元数据中心与服务测试](reference-manual/)" + - 升级与兼容性: + - "[3.0 迁移指南](upgrades-and-compatibility/)" + - "[Triple 协议与Stream 流式接口](upgrades-and-compatibility/)" +--- + +{{% docs/content_box %}} diff --git a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/_index.md b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/_index.md new file mode 100755 index 000000000000..1a8ace15f09b --- /dev/null +++ b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/_index.md @@ -0,0 +1,8 @@ + +--- +type: docs +title: "高级特性和用法" +linkTitle: "高级特性和用法" +weight: 4 +--- + diff --git a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/observability/_index.md b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/observability/_index.md new file mode 100755 index 000000000000..7370904db766 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/observability/_index.md @@ -0,0 +1,8 @@ + +--- +type: docs +title: "可观测性类特性" +linkTitle: "可观测性类特性" +weight: 2 +--- + diff --git a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/others/_index.md b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/others/_index.md new file mode 100755 index 000000000000..62104f7e5080 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/others/_index.md @@ -0,0 +1,8 @@ + +--- +type: docs +title: "其他" +linkTitle: "其他" +weight: 6 +--- + diff --git a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/others/graceful-shutdown.md b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/others/graceful-shutdown.md new file mode 100644 index 000000000000..afdae3810d15 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/others/graceful-shutdown.md @@ -0,0 +1,41 @@ +--- +type: docs +title: "优雅停机" +linkTitle: "优雅停机" +weight: 2 +description: "让 Dubbo 服务完成优雅停机" +--- + +Dubbo 是通过 JDK 的 ShutdownHook 来完成优雅停机的，所以如果用户使用 `kill -9 PID` 等强制关闭指令，是不会执行优雅停机的，只有通过 `kill PID` 时，才会执行。 + +## 原理 + +服务提供方 + +* 停止时，先标记为不接收新请求，新请求过来时直接报错，让客户端重试其它机器。 +* 然后，检测线程池中的线程是否正在运行，如果有，等待所有线程执行完成，除非超时，则强制关闭。 + +服务消费方 + +* 停止时，不再发起新的调用请求，所有新的调用在客户端即报错。 +* 然后，检测有没有请求的响应还没有返回，等待响应返回，除非超时，则强制关闭。 + +## 设置方式 + +设置优雅停机超时时间，缺省超时时间是 10 秒，如果超时则强制关闭。 + +```properties +# dubbo.properties +dubbo.service.shutdown.wait=15000 +``` + +如果 ShutdownHook 不能生效，可以自行调用： + +```java +DubboShutdownHook.destroyAll(); +``` + +{{% alert title="建议" color="primary" %}} +使用 tomcat 等容器部署的场景，建议通过扩展 ContextListener 等自行调用以下代码实现优雅停机 +{{% /alert %}} + diff --git a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/others/lifecycle.md b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/others/lifecycle.md new file mode 100644 index 000000000000..71ef8cc89d08 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/others/lifecycle.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "Kubernetes 生命周期探针" +linkTitle: "Kubernetes 生命周期探针" +weight: 6 +--- \ No newline at end of file diff --git a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/others/logger-strategy.md b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/others/logger-strategy.md new file mode 100644 index 000000000000..59c60744fa04 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/others/logger-strategy.md @@ -0,0 +1,29 @@ +--- +type: docs +title: "日志框架适配" +linkTitle: "日志框架适配" +weight: 5 +description: "在 Dubbo 中适配日志框架" +--- + +自 `2.2.1` 开始，dubbo 开始内置 log4j、slf4j、jcl、jdk 这些日志框架的适配[1]，也可以通过以下方式显式配置日志输出策略： + +0. 命令行 + + ```sh + java -Ddubbo.application.logger=log4j + ``` + +0. 在 `dubbo.properties` 中指定 + + ``` + dubbo.application.logger=log4j + ``` + +0. 在 `dubbo.xml` 中配置 + + ```xml + + ``` + +[1]: 自定义扩展可以参考 [日志适配扩展](../../../dev/impls/logger-adapter) diff --git a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/others/service-container.md b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/others/service-container.md new file mode 100644 index 000000000000..50f704b2f268 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/others/service-container.md @@ -0,0 +1,67 @@ +--- +type: docs +title: "自定义服务容器" +linkTitle: "自定义服务容器" +weight: 1 +description: "使用 Dubbo 中的服务容器" +--- + +服务容器是一个 standalone 的启动程序，因为后台服务不需要 Tomcat 或 JBoss 等 Web 容器的功能，如果硬要用 Web 容器去加载服务提供方，增加复杂性，也浪费资源。 + +服务容器只是一个简单的 Main 方法，并加载一个简单的 Spring 容器，用于暴露服务。 + +服务容器的加载内容可以扩展，内置了 spring, jetty, log4j 等加载，可通过[容器扩展点](../../references/spis/container)进行扩展。配置配在 java 命令的 -D 参数或者 `dubbo.properties` 中。 + +## 容器类型 + +### Spring Container + +* 自动加载 `META-INF/spring` 目录下的所有 Spring 配置。 +* 配置 spring 配置加载位置： + + ```properties + dubbo.spring.config=classpath*:META-INF/spring/*.xml + ``` + +### Jetty Container + +* 启动一个内嵌 Jetty，用于汇报状态。 +* 配置： + * `dubbo.jetty.port=8080`：配置 jetty 启动端口 + * `dubbo.jetty.directory=/foo/bar`：配置可通过 jetty 直接访问的目录，用于存放静态文件 + * `dubbo.jetty.page=log,status,system`：配置显示的页面，缺省加载所有页面 + + +### Log4j Container + +* 自动配置 log4j 的配置，在多进程启动时，自动给日志文件按进程分目录。 +* 配置： + * `dubbo.log4j.file=/foo/bar.log`：配置日志文件路径 + * `dubbo.log4j.level=WARN`：配置日志级别 + * `dubbo.log4j.subdirectory=20880`：配置日志子目录，用于多进程启动，避免冲突 + +## 容器启动 + +缺省只加载 spring + +```sh +java org.apache.dubbo.container.Main +``` + +通过 main 函数参数传入要加载的容器 + +```sh +java org.apache.dubbo.container.Main spring jetty log4j +``` + +通过 JVM 启动参数传入要加载的容器 + +```sh +java org.apache.dubbo.container.Main -Ddubbo.container=spring,jetty,log4j +``` + +通过 classpath 下的 `dubbo.properties` 配置传入要加载的容器 + +``` +dubbo.container=spring,jetty,log4j +``` diff --git a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/others/set-host.md b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/others/set-host.md new file mode 100644 index 000000000000..93f5e4d926a5 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/others/set-host.md @@ -0,0 +1,75 @@ +--- +type: docs +title: "主机地址自定义暴露" +linkTitle: "主机地址自定义暴露" +weight: 3 +description: "自定义 Dubbo 服务对外暴露的主机地址" +--- + +## 背景 + +在 Dubbo 中， Provider 启动时主要做两个事情，一是启动 server，二是向注册中心注册服务。启动 server 时需要绑定 socket，向注册中心注册服务时也需要发送 socket 唯一标识服务地址。 + +1. `dubbo`中不设置`host`时默认`host`是什么? +2. 那在`dubbo`中如何指定服务的`host`,我们是否可以用hostname或domain代替IP地址作为`host`? +3. 在使用docker时,有时需要设置端口映射,此时,启动server时绑定的socket和向注册中心注册的socket使用不同的端口号,此时又该如何设置? + +#### dubbo 中不设置 host 时默认 host 是什么 + +一般的 dubbo 协议配置如下: +``` xml + ... + + ... +``` + +可以看到,只配置了端口号,没有配置 host，此时设置的 host 又是什么呢? + +查看代码发现,在 `org.apache.dubbo.config.ServiceConfig#findConfigedHosts()` 中,通过 `InetAddress.getLocalHost().getHostAddress()` 获取默认 host。其返回值如下： + +1. 未联网时，返回 127.0.0.1 +2. 在阿里云服务器中，返回私有地址,如: 172.18.46.234 +3. 在本机测试时，返回公有地址，如: 30.5.10.11 + +#### 那在 dubbo 中如何指定服务的 socket? + +除此之外,可以通过 `dubbo.protocol` 或 `dubbo.provider `的 `host` 属性对 `host` 进行配置,支持IP地址和域名,如下: + +``` xml + ... + + ... +``` + +#### 在使用 docker 时，有时需要设置端口映射，此时，启动 server 时绑定的 socket 和向注册中心注册的 socket 使用不同的端口号，此时又该如何设置？ + +见 [dubbo 通过环境变量设置 host](https://github.com/dubbo/dubbo-samples/tree/master/dubbo-samples-docker) + +有些部署场景需要动态指定服务注册的地址，如 docker bridge 网络模式下要指定注册宿主机 ip 以实现外网通信。dubbo 提供了两对启动阶段的系统属性，用于设置对外通信的ip、port地址。 + +* DUBBO_IP_TO_REGISTRY --- 注册到注册中心的ip地址 +* DUBBO_PORT_TO_REGISTRY --- 注册到注册中心的port端口 +* DUBBO_IP_TO_BIND --- 监听ip地址 +* DUBBO_PORT_TO_BIND --- 监听port端口 + +以上四个配置项均为可选项，如不配置 dubbo 会自动获取 ip 与端口，请根据具体的部署场景灵活选择配置。 +dubbo 支持多协议，如果一个应用同时暴露多个不同协议服务，且需要为每个服务单独指定 ip 或 port，请分别在以上属性前加协议前缀。 如： + +* HESSIAN_DUBBO_PORT_TO_BIND hessian协议绑定的port +* DUBBO_DUBBO_PORT_TO_BIND dubbo协议绑定的port +* HESSIAN_DUBBO_IP_TO_REGISTRY hessian协议注册的ip +* DUBBO_DUBBO_PORT_TO_BIND dubbo协议注册的ip + +PORT_TO_REGISTRY 或 IP_TO_REGISTRY 不会用作默认 PORT_TO_BIND 或 IP_TO_BIND，但是反过来是成立的 +如设置 PORT_TO_REGISTRY=20881 IP_TO_REGISTRY=30.5.97.6，则 PORT_TO_BIND IP_TO_BIND 不受影响 +如果设置 PORT_TO_BIND=20881 IP_TO_BIND=30.5.97.6，则默认 PORT_TO_REGISTRY=20881 IP_TO_REGISTRY=30.5.97.6 + +## 总结 + + 1. 可以通过`dubbo.protocol`或`dubbo.provider`的`host`属性对`host`进行配置,支持IP地址和域名.但此时注册到注册中心的IP地址和监听IP地址是同一个值 + 2. 为了解决在虚拟环境或局域网内consumer无法与provider通信的问题,可以通过环境变量分别设置注册到注册中心的IP地址和监听IP地址,其优先级高于`dubbo.protocol`或`dubbo.provider`的`host`配置 + +## 参考 + + 1. [Proposal: support hostname or domain in service discovery.](https://github.com/apache/dubbo/issues/2043) + 2. [dubbo通过环境变量设置host](https://github.com/dubbo/dubbo-samples/tree/master/dubbo-samples-docker) diff --git a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/performance/_index.md b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/performance/_index.md new file mode 100755 index 000000000000..205a163149fb --- /dev/null +++ b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/performance/_index.md @@ -0,0 +1,8 @@ + +--- +type: docs +title: "性能优化类特性" +linkTitle: "性能优化类特性" +weight: 5 +--- + diff --git a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/performance/reference-config-cache.md b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/performance/reference-config-cache.md new file mode 100644 index 000000000000..f5467cd3a984 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/performance/reference-config-cache.md @@ -0,0 +1,43 @@ +--- +type: docs +title: "服务引用配置对象缓存" +linkTitle: "服务引用配置对象缓存" +weight: 2 +description: "在 Dubbo 中缓存 ReferenceConfig" +--- + +`ReferenceConfig` 实例很重，封装了与注册中心的连接以及与提供者的连接，需要缓存。否则重复生成 `ReferenceConfig` 可能造成性能问题并且会有内存和连接泄漏。在 API 方式编程时，容易忽略此问题。 + +因此，自 `2.4.0` 版本开始， dubbo 提供了简单的工具类 `ReferenceConfigCache`用于缓存 `ReferenceConfig` 实例。 + +使用方式如下： + +```java +ReferenceConfig reference = new ReferenceConfig(); +reference.setInterface(XxxService.class); +reference.setVersion("1.0.0"); +...... +ReferenceConfigCache cache = ReferenceConfigCache.getCache(); +// cache.get方法中会缓存 Reference对象，并且调用ReferenceConfig.get方法启动ReferenceConfig +XxxService xxxService = cache.get(reference); +// 注意！ Cache会持有ReferenceConfig，不要在外部再调用ReferenceConfig的destroy方法，导致Cache内的ReferenceConfig失效！ +// 使用xxxService对象 +xxxService.sayHello(); +``` + +消除 Cache 中的 `ReferenceConfig`，将销毁 `ReferenceConfig` 并释放对应的资源。 + +```java +ReferenceConfigCache cache = ReferenceConfigCache.getCache(); +cache.destroy(reference); +``` + +缺省 `ReferenceConfigCache` 把相同服务 Group、接口、版本的 `ReferenceConfig` 认为是相同，缓存一份。即以服务 Group、接口、版本为缓存的 Key。 + +可以修改这个策略，在 `ReferenceConfigCache.getCache` 时，传一个 `KeyGenerator`。详见 `ReferenceConfigCache` 类的方法。 + +```java +KeyGenerator keyGenerator = new ... +ReferenceConfigCache cache = ReferenceConfigCache.getCache(keyGenerator ); +``` + diff --git a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/performance/simplify-registry-data.md b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/performance/simplify-registry-data.md new file mode 100644 index 000000000000..dfd466fa0efb --- /dev/null +++ b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/performance/simplify-registry-data.md @@ -0,0 +1,262 @@ +--- +type: docs +title: "注册信息简化" +linkTitle: "注册信息简化" +weight: 3 +description: "减少注册中心上服务的注册数据" +--- + +## 背景 + +Dubbo provider 中的服务配置项有接近 [30 个配置项](http://dubbo.apache.org/en-us/docs/user/references/xml/dubbo-service.html)。 排除注册中心服务治理需要之外，很大一部分配置项是 provider 自己使用，不需要透传给消费者。这部分数据不需要进入注册中心，而只需要以 key-value 形式持久化存储。 + +Dubbo consumer 中的配置项也有 [20+个配置项](http://dubbo.apache.org/en-us/docs/user/references/xml/dubbo-reference.html)。在注册中心之中，服务消费者列表中只需要关注 application，version，group，ip，dubbo 版本等少量配置，其他配置也可以以 key-value 形式持久化存储。 + +这些数据是以服务为维度注册进入注册中心，导致了数据量的膨胀，进而引发注册中心(如 zookeeper)的网络开销增大，性能降低。 + +## 现有功能 sample + +当前现状一个简单展示。通过这个展示，分析下为什么需要做简化配置。 + +参考 sample 子工程： dubbo-samples-simplified-registry/dubbo-samples-simplified-registry-nosimple （跑 sample 前，先跑下 ZKClean 进行配置项清理） + +dubbo-provider.xml配置 + +``` + + + + +``` + +启动 provider 的 main 方法之后，查看 zookeeper 的叶子节点（路径为：/dubbo/org.apache.dubbo.samples.simplified.registry.nosimple.api.DemoService/providers 目录下）的内容如下： + +``` +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%26**executes**%3D4500%26generic%3Dfalse%26group%3Ddubbo-simple%26interface%3D +org.apache.dubbo.samples.simplified.registry.nosimple.api.DemoService%26methods%3D +sayHello%26**owner**%3Dvict%26pid%3D2767%26**retries**%3D7%26revision%3D1.2.3%26side%3D +provider%26**timeout**%3D5300%26timestamp%3D1542361152795%26valid%3Dtrue%26version%3D1.2.3 +``` + +从加粗字体中能看到有：executes, retries, owner, timeout。但是这些字段不是每个都需要传递给 dubbo ops 或者 dubbo consumer。 同样的，consumer 也有这个问题，可以在例子中启动 Consumer 的 main 方法进行查看。 + +## 设计目标和宗旨 + +期望简化进入注册中心的 provider 和 consumer 配置数量。 +期望将部分配置项以其他形式存储。这些配置项需要满足：不在服务调用链路上，同时这些配置项不在注册中心的核心链路上(服务查询，服务列表)。 + +## 配置 + +简化注册中心的配置，只在 2.7 之后的版本中进行支持。 +开启 provider 或者 consumer 简化配置之后，默认保留的配置项如下： + +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 | | +| TIMESTAMP_KEY | timestamp | | +| DUBBO_VERSION_KEY | dubbo | | +| SPECIFICATION_VERSION_KEY | **specVersion** | 新增，用于表述dubbo版本，如2.7.0 | + + +consumer： + +| Constant Key | Key | remark | +| ------ | ------ | ------ | +| APPLICATION_KEY | application | | +| VERSION_KEY | version | | +| GROUP_KEY | group | | +| DUBBO_VERSION_KEY | dubbo | | +| SPECIFICATION_VERSION_KEY | **specVersion** | 新增，用于表述dubbo版本，如2.7.0 | + +Constant Key 表示来自于类 org.apache.dubbo.common.Constants 的字段。 + +下面介绍几种常用的使用方式。所有的 sample，都可以查看[sample-2.7](https://github.com/dubbo/dubbo-samples/tree/master) + +### 方式1. 配置dubbo.properties + +sample 在 dubbo-samples-simplified-registry/dubbo-samples-simplified-registry-xml 工程下 （跑 sample 前，先跑下ZKClean 进行配置项清理） + +dubbo.properties + +```properties + +dubbo.registry.simplified=true +dubbo.registry.extra-keys=retries,owner +``` + +怎么去验证呢？ + +##### provider端验证 + +provider端配置 + +```xml + + + + + + + + +``` + +得到的 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%26**owner**%3D +vict%26**retries**%3D7%26**timeout**%3D5300%26timestamp%3D1542594503305%26version%3D1.2.3 +``` + +和上面的**现有功能 sample**进行对比，上面的 sample 中，executes, retries, owner, timeout 四个配置项都进入了注册中心。但是本实例不是： +* 配置了：dubbo.registry.simplified=true， 默认情况下，timeout 在默认的配置项列表，所以还是会进入注册中心； +* 配置了：dubbo.registry.extra-keys=retries,owner ， 所以 retries，owner 也会进入注册中心。 + +总结：timeout，retries,owner 进入了注册中心，而 executes 没有进入。 + +consumer 端配置 + +```xml + + + + + + + + + + + +``` + +得到的 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 +``` + +* 配置了：dubbo.registry.simplified=true ， 默认情况下，application,version,group,dubbo 在默认的配置项列表，所以还是会进入注册中心； + + +### 方式2. 声明spring bean + +sample在dubbo-samples-simplified-registry/dubbo-samples-simplified-registry-annotation 工程下 （跑 sample 前，先跑下ZKClean 进行配置项清理） + +##### Provider配置 + +privide 端 bean 配置： + +```java +// 等同于dubbo.properties配置，用@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 +// 暴露服务 +@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; + } +} +``` + +和上面 sample 中的 dubbo.properties 的效果是一致的。结果如下： +* 默认情况下，timeout 在默认的配置项列表，所以还是会进入注册中心； +* 配置了 retries,owner 作为额外的 key 进入注册中心 ， 所以 retries，owner 也会进入注册中心。 + +总结：timeout，retries,owner 进入了注册中心，而 executes 没有进入。 + +##### Consumer配置 + +consumer 端 bean 配置： + +```java +@Bean +public RegistryConfig registryConfig() { + RegistryConfig registryConfig = new RegistryConfig(); + registryConfig.setAddress("zookeeper://127.0.0.1:2181"); + registryConfig.setSimplified(true); + return registryConfig; + } +``` + +消费服务： + +```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); + } +} +``` + +和上面 sample 中 consumer 端的配置是一样的。结果如下： +* 默认情况下，application,version,group,dubbo 在默认的配置项列表，所以还是会进入注册中心。 + +###### 注意： +如果一个应用中既有provider又有consumer，那么配置需要合并成： + +```java +@Bean +public RegistryConfig registryConfig() { + RegistryConfig registryConfig = new RegistryConfig(); + registryConfig.setAddress("zookeeper://127.0.0.1:2181"); + registryConfig.setSimplified(true); + //只对provider生效 + registryConfig.setExtraKeys("retries,owner"); + return registryConfig; +} +``` + +## 后续规划 + +本版本还保留了大量的配置项，接下来的版本中，会逐渐删除所有的配置项。 diff --git a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/performance/threading-model/_index.md b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/performance/threading-model/_index.md new file mode 100755 index 000000000000..9fad36f07ddc --- /dev/null +++ b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/performance/threading-model/_index.md @@ -0,0 +1,8 @@ + +--- +type: docs +title: "线程模型" +linkTitle: "线程模型" +weight: 1 +--- + diff --git a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/performance/threading-model/consumer.md b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/performance/threading-model/consumer.md new file mode 100644 index 000000000000..88f2a0460691 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/performance/threading-model/consumer.md @@ -0,0 +1,45 @@ +--- +type: docs +title: "消费端线程模型" +linkTitle: "消费端线程模型" +weight: 2 +description: "Dubbo 消费端线程池模型用法" +--- + +2.7.5 版本对整个调用链路做了全面的优化，根据压测结果显示，总体 QPS 性能提升将近 30%，同时也减少了调用过程中的内存分配开销。其中一个值得提及的设计点是 2.7.5 引入了 Servicerepository 的概念，在服务注册阶段提前生成 ServiceDescriptor 和 MethodDescriptor，以减少 RPC 调用阶段计算 Service 原信息带来的资源消耗。 + +## 消费端线程池模型优化 + +对 2.7.5 版本之前的 Dubbo 应用，尤其是一些消费端应用，当面临需要消费大量服务且并发数比较大的大流量场景时（典型如网关类场景），经常会出现消费端线程数分配过多的问题，具体问题讨论可参见 [Need a limited Threadpool in consumer side #2013](https://github.com/apache/dubbo/issues/2013) + +改进后的消费端线程池模型，通过复用业务端被阻塞的线程，很好的解决了这个问题。 + +#### 老的线程池模型 + +![消费端线程池.png](/imgs/user/consumer-threadpool0.png) + +我们重点关注 Consumer 部分： + +1. 业务线程发出请求，拿到一个 Future 实例。 +2. 业务线程紧接着调用 future.get 阻塞等待业务结果返回。 +3. 当业务数据返回后，交由独立的 Consumer 端线程池进行反序列化等处理，并调用 future.set 将反序列化后的业务结果置回。 +4. 业务线程拿到结果直接返回 + + + +**2.7.5 版本引入的线程池模型** + +![消费端线程池新.png](/imgs/user/consumer-threadpool1.png) + +1. 业务线程发出请求，拿到一个 Future 实例。 +2. 在调用 future.get() 之前，先调用 ThreadlessExecutor.wait()，wait 会使业务线程在一个阻塞队列上等待，直到队列中被加入元素。 +3. 当业务数据返回后，生成一个 Runnable Task 并放入 ThreadlessExecutor 队列 +4. 业务线程将 Task 取出并在本线程中执行：反序列化业务数据并 set 到 Future。 +5. 业务线程拿到结果直接返回 + +这样，相比于老的线程池模型，由业务线程自己负责监测并解析返回结果，免去了额外的消费端线程池开销。 + +关于性能优化，在接下来的版本中将会持续推进，主要从以下两个方面入手： + +1. RPC 调用链路。目前能看到的点包括：进一步减少执行链路的内存分配、在保证协议兼容性的前提下提高协议传输效率、提高 Filter、Router 等计算效率。 +2. 服务治理链路。进一步减少地址推送、服务治理规则推送等造成的内存、cpu 资源消耗。 diff --git a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/performance/threading-model/provider.md b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/performance/threading-model/provider.md new file mode 100644 index 000000000000..f0398b854925 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/performance/threading-model/provider.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "服务端线程模型" +linkTitle: "服务端线程模型" +weight: 1 +--- diff --git a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/_index.md b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/_index.md new file mode 100755 index 000000000000..c63ca0354bba --- /dev/null +++ b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/_index.md @@ -0,0 +1,8 @@ + +--- +type: docs +title: "RPC请求类特性" +linkTitle: "RPC请求类特性" +weight: 3 +--- + diff --git a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/accesslog.md b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/accesslog.md new file mode 100644 index 000000000000..459506362507 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/accesslog.md @@ -0,0 +1,21 @@ +--- +type: docs +title: "调用信息记录" +linkTitle: "调用信息记录" +weight: 13 +description: "配置 Dubbo 的访问日志" +--- + +如果你想记录每一次请求信息，可开启访问日志，类似于apache的访问日志。**注意**：此日志量比较大，请注意磁盘容量。 + +将访问日志输出到当前应用的log4j日志： + +```xml + +``` + +将访问日志输出到指定文件： + +```xml + +``` diff --git a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/async-call.md b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/async-call.md new file mode 100644 index 000000000000..7304ad3b15ce --- /dev/null +++ b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/async-call.md @@ -0,0 +1,222 @@ +--- +type: docs +title: "异步调用" +linkTitle: "异步调用" +weight: 3 +description: "在 Dubbo 中发起异步调用" +--- + + +从 2.7.0 开始，Dubbo 的所有异步编程接口开始以 [CompletableFuture](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletableFuture.html) 为基础 + +基于 NIO 的非阻塞实现并行调用，客户端不需要启动多线程即可完成并行调用多个远程服务，相对多线程开销较小。 + +![/user-guide/images/future.jpg](/imgs/user/future.jpg) + + +## 使用 CompletableFuture 签名的接口 + +需要服务提供者事先定义 CompletableFuture 签名的服务，接口定义指南如下： + +Provider端异步执行将阻塞的业务从Dubbo内部线程池切换到业务自定义线程，避免Dubbo线程池的过度占用，有助于避免不同服务间的互相影响。异步执行无异于节省资源或提升RPC响应性能，因为如果业务执行需要阻塞，则始终还是要有线程来负责执行。 + +{{% alert title="注意" color="warning" %}} +Provider 端异步执行和 Consumer 端异步调用是相互独立的，你可以任意正交组合两端配置 +- Consumer同步 - Provider同步 +- Consumer异步 - Provider同步 +- Consumer同步 - Provider异步 +- Consumer异步 - Provider异步 + {{% /alert %}} + + +## 定义 CompletableFuture 签名的接口 + +服务接口定义： + +```java +public interface AsyncService { + CompletableFuture sayHello(String name); +} +``` + +服务实现： + +```java +public class AsyncServiceImpl implements AsyncService { + @Override + public CompletableFuture sayHello(String name) { + RpcContext savedContext = RpcContext.getContext(); + // 建议为supplyAsync提供自定义线程池，避免使用JDK公用线程池 + return CompletableFuture.supplyAsync(() -> { + System.out.println(savedContext.getAttachment("consumer-key1")); + try { + Thread.sleep(5000); + } catch (InterruptedException e) { + e.printStackTrace(); + } + return "async response from provider."; + }); + } +} +``` + +通过 `return CompletableFuture.supplyAsync() `，业务执行已从 Dubbo 线程切换到业务线程，避免了对 Dubbo 线程池的阻塞。 + + + +## 使用AsyncContext + +Dubbo 提供了一个类似 Servlet 3.0 的异步接口`AsyncContext`，在没有 CompletableFuture 签名接口的情况下，也可以实现 Provider 端的异步执行。 + +服务接口定义： + +```java +public interface AsyncService { + String sayHello(String name); +} +``` + +服务暴露，和普通服务完全一致： + +```xml + + +``` + +服务实现： + +```java +public class AsyncServiceImpl implements AsyncService { + public String sayHello(String name) { + final AsyncContext asyncContext = RpcContext.startAsync(); + new Thread(() -> { + // 如果要使用上下文，则必须要放在第一句执行 + asyncContext.signalContextSwitch(); + try { + Thread.sleep(500); + } catch (InterruptedException e) { + e.printStackTrace(); + } + // 写回响应 + asyncContext.write("Hello " + name + ", response from provider."); + }).start(); + return null; + } +} +``` + +注意接口的返回类型是 `CompletableFuture`。 + +XML引用服务： + +```xml + +``` + +调用远程服务： + +```java +// 调用直接返回CompletableFuture +CompletableFuture future = asyncService.sayHello("async call request"); +// 增加回调 +future.whenComplete((v, t) -> { + if (t != null) { + t.printStackTrace(); + } else { + System.out.println("Response: " + v); + } +}); +// 早于结果输出 +System.out.println("Executed before response return."); +``` + +## 使用 RpcContext + +在 consumer.xml 中配置： + +```xml + + + +``` + +调用代码: + +```java +// 此调用会立即返回null +asyncService.sayHello("world"); +// 拿到调用的Future引用，当结果返回后，会被通知和设置到此Future +CompletableFuture helloFuture = RpcContext.getContext().getCompletableFuture(); +// 为Future添加回调 +helloFuture.whenComplete((retValue, exception) -> { + if (exception == null) { + System.out.println(retValue); + } else { + exception.printStackTrace(); + } +}); +``` + +或者，你也可以这样做异步调用: + +```java +CompletableFuture future = RpcContext.getContext().asyncCall( + () -> { + asyncService.sayHello("oneway call request1"); + } +); + +future.get(); +``` + + + +## 重载服务接口 + +如果你只有这样的同步服务定义，而又不喜欢 RpcContext 的异步使用方式。 + +```java +public interface GreetingsService { + String sayHi(String name); +} +``` + +那还有一种方式，就是利用 Java 8 提供的 default 接口实现，重载一个带有 CompletableFuture 签名的方法。 + +> CompletableFuture 签名的方法目前只支持 Dubbo 协议，其他协议由于第三方实现问题，需要视具体情况而定。 + +有两种方式来实现： + +1. 提供方或消费方自己修改接口签名 + +```java +public interface GreetingsService { + String sayHi(String name); + + // AsyncSignal is totally optional, you can use any parameter type as long as java allows your to do that. + default CompletableFuture sayHi(String name, AsyncSignal signal) { + return CompletableFuture.completedFuture(sayHi(name)); + } +} +``` + +1. Dubbo 官方提供 compiler hacker，编译期自动重写同步方法，请[在此](https://github.com/dubbo/dubbo-async-processor#compiler-hacker-processer)讨论和跟进具体进展。 + + + +你也可以设置是否等待消息发出： [^1] + +- `sent="true"` 等待消息发出，消息发送失败将抛出异常。 +- `sent="false"` 不等待消息发出，将消息放入 IO 队列，即刻返回。 + +```xml + +``` + +如果你只是想异步，完全忽略返回值，可以配置 `return="false"`，以减少 Future 对象的创建和管理成本： + +```xml + +``` + +[^1]: 异步总是不等待返回 \ No newline at end of file diff --git a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/attachment.md b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/attachment.md new file mode 100644 index 000000000000..7d337114169a --- /dev/null +++ b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/attachment.md @@ -0,0 +1,38 @@ +--- +type: docs +title: "调用链路传递隐式参数" +linkTitle: "调用链路传递隐式参数" +weight: 5 +description: "通过 Dubbo 中的 Attachment 在服务消费方和提供方之间隐式传递参数" +--- + +可以通过 `RpcContext` 上的 `setAttachment` 和 `getAttachment` 在服务消费方和提供方之间进行参数的隐式传递。 + +{{% alert title="注意" color="primary" %}} +path, group, version, dubbo, token, timeout 几个 key 是保留字段，请使用其它值。 +{{% /alert %}} + +![/user-guide/images/context.png](/imgs/user/context.png) + +#### 在服务消费方端设置隐式参数 + +`setAttachment` 设置的 KV 对，在完成下面一次远程调用会被清空，即多次远程调用要多次设置。 + +```xml +RpcContext.getContext().setAttachment("index", "1"); // 隐式传参，后面的远程调用都会隐式将这些参数发送到服务器端，类似cookie，用于框架集成，不建议常规业务使用 +xxxService.xxx(); // 远程调用 +// ... +``` + +#### 在服务提供方端获取隐式参数 + +```java +public class XxxServiceImpl implements XxxService { + + public void xxx() { + // 获取客户端隐式传入的参数，用于框架集成，不建议常规业务使用 + String index = RpcContext.getContext().getAttachment("index"); + } +} +``` + diff --git a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/callback-parameter.md b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/callback-parameter.md new file mode 100644 index 000000000000..893aecb0cec4 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/callback-parameter.md @@ -0,0 +1,120 @@ +--- +type: docs +title: "服务端对客户端进行回调" +linkTitle: "服务端对客户端进行回调" +weight: 9 +description: "通过参数回调从服务器端调用客户端逻辑" +--- + +参数回调方式与调用本地 callback 或 listener 相同，只需要在 Spring 的配置文件中声明哪个参数是 callback 类型即可。Dubbo 将基于长连接生成反向代理，这样就可以从服务器端调用客户端逻辑。可以参考 [dubbo 项目中的示例代码](https://github.com/dubbo/dubbo-samples/tree/master/dubbo-samples-callback)。 + +#### 服务接口示例 + +###### 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); +} +``` + +#### 服务提供者接口实现示例 + +```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); // 定时触发变更通知 + } catch (Throwable t) { // 防御容错 + t.printStackTrace(); + } + } + } + }); + t.setDaemon(true); + t.start(); + } + + public void addListener(String key, CallbackListener listener) { + listeners.put(key, listener); + listener.changed(getChanged(key)); // 发送变更通知 + } + + private String getChanged(String key) { + return "Changed: " + new SimpleDateFormat("yyyy-MM-dd HH:mm:ss").format(new Date()); + } +} +``` + +#### 服务提供者配置示例 + +```xml + + + + + + + + +``` + +#### 服务消费者配置示例 + +```xml + +``` + +#### 服务消费者调用示例 + +```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); + } +}); +``` + +{{% alert title="提示" color="primary" %}} +`2.0.6` 及其以上版本支持 +{{% /alert %}} diff --git a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/context.md b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/context.md new file mode 100644 index 000000000000..fff2509bbd63 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/context.md @@ -0,0 +1,46 @@ +--- +type: docs +title: "RPC调用上下文" +linkTitle: "RPC调用上下文" +weight: 6 +description: "通过上下文存放当前调用过程中所需的环境信息" +--- + +上下文中存放的是当前调用过程中所需的环境信息。所有配置信息都将转换为 URL 的参数，参见 [schema 配置参考手册](../../references/xml) 中的**对应URL参数**一列。 + +RpcContext 是一个 ThreadLocal 的临时状态记录器，当接收到 RPC 请求，或发起 RPC 请求时，RpcContext 的状态都会变化。比如：A 调 B，B 再调 C，则 B 机器上，在 B 调 C 之前，RpcContext 记录的是 A 调 B 的信息，在 B 调 C 之后，RpcContext 记录的是 B 调 C 的信息。 + +## 服务消费方 + +```java +// 远程调用 +xxxService.xxx(); +// 本端是否为消费端，这里会返回true +boolean isConsumerSide = RpcContext.getContext().isConsumerSide(); +// 获取最后一次调用的提供方IP地址 +String serverIP = RpcContext.getContext().getRemoteHost(); +// 获取当前服务配置信息，所有配置信息都将转换为URL的参数 +String application = RpcContext.getContext().getUrl().getParameter("application"); +// 注意：每发起RPC调用，上下文状态会变化 +yyyService.yyy(); +``` + +## 服务提供方 + +```java +public class XxxServiceImpl implements XxxService { + + public void xxx() { + // 本端是否为提供端，这里会返回true + boolean isProviderSide = RpcContext.getContext().isProviderSide(); + // 获取调用方IP地址 + String clientIP = RpcContext.getContext().getRemoteHost(); + // 获取当前服务配置信息，所有配置信息都将转换为URL的参数 + String application = RpcContext.getContext().getUrl().getParameter("application"); + // 注意：每发起RPC调用，上下文状态会变化 + yyyService.yyy(); + // 此时本端变成消费端，这里会返回false + boolean isProviderSide = RpcContext.getContext().isProviderSide(); + } +} +``` diff --git a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/echo-service.md b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/echo-service.md new file mode 100644 index 000000000000..f9fef53179f2 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/echo-service.md @@ -0,0 +1,29 @@ +--- +type: docs +title: "回声测试" +linkTitle: "回声测试" +weight: 12 +description: "通过回声测试检测 Dubbo 服务是否可用" +--- + +回声测试用于检测服务是否可用，回声测试按照正常请求流程执行，能够测试整个调用是否通畅，可用于监控。 + +所有服务自动实现 `EchoService` 接口，只需将任意服务引用强制转型为 `EchoService`，即可使用。 + +Spring 配置： +```xml + +``` + +代码： +```java +// 远程服务引用 +MemberService memberService = ctx.getBean("memberService"); + +EchoService echoService = (EchoService) memberService; // 强制转型为EchoService + +// 回声测试可用性 +String status = echoService.$echo("OK"); + +assert(status.equals("OK")); +``` diff --git a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/events-notify.md b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/events-notify.md new file mode 100644 index 000000000000..45f3b0b2b402 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/events-notify.md @@ -0,0 +1,108 @@ +--- +type: docs +title: "调用触发事件通知" +linkTitle: "调用触发事件通知" +weight: 8 +description: "在调用之前、调用之后、出现异常时的事件通知" +--- + +在调用之前、调用之后、出现异常时，会触发 `oninvoke`、`onreturn`、`onthrow` 三个事件，可以配置当事件发生时，通知哪个类的哪个方法。 + +{{% alert title="提示" color="primary" %}} +支持版本：`2.0.7` 之后 +{{% /alert %}} + +#### 服务提供者与消费者共享服务接口 + +```java +interface IDemoService { + public Person get(int id); +} +``` + +#### 服务提供者实现 + +```java +class NormalDemoService implements IDemoService { + public Person get(int id) { + return new Person(id, "charles`son", 4); + } +} +``` + +#### 服务提供者配置 + +```xml + + + + +``` + +#### 服务消费者 Callback 接口 + +```java +interface Notify { + public void onreturn(Person msg, Integer id); + public void onthrow(Throwable ex, Integer id); +} +``` + +#### 服务消费者 Callback 实现 + +```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); + } +} +``` + +#### 服务消费者 Callback 配置 + +```xml + + + + +``` + +`callback` 与 `async` 功能正交分解，`async=true` 表示结果是否马上返回，`onreturn` 表示是否需要回调。 + +两者叠加存在以下几种组合情况： + +* 异步回调模式：`async=true onreturn="xxx"` +* 同步回调模式：`async=false onreturn="xxx"` +* 异步无回调 ：`async=true` +* 同步无回调 ：`async=false` + +{{% alert title="提示" color="primary" %}} +`async=false` 默认 +{{% /alert %}} + +#### 测试代码 + +```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：只是用来说明callback正常被调用，业务具体实现自行决定. +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()); +``` diff --git a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/generic-service.md b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/generic-service.md new file mode 100644 index 000000000000..5276c4429ec6 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/generic-service.md @@ -0,0 +1,151 @@ +--- +type: docs +title: "泛化调用" +linkTitle: "泛化调用" +weight: 4 +description: "实现一个通用的远程服务 Mock 框架，可通过实现 GenericService 接口处理所有服务请求" +--- + +# 实现泛化服务暴露 + +泛接口实现方式主要用于服务器端没有 API 接口及模型类元的情况，参数及返回值中的所有 POJO 均用 Map 表示，通常用于框架集成，比如：实现一个通用的远程服务 Mock 框架，可通过实现 GenericService 接口处理所有服务请求。 + +在 Java 代码中实现 `GenericService` 接口： + +```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]; + } + } +} +``` + +## 通过 Spring 暴露泛化实现 + +在 Spring 配置申明服务的实现： + +```xml + + +``` + +## 通过 API 方式暴露泛化实现 + +```java +... +// 用org.apache.dubbo.rpc.service.GenericService可以替代所有接口实现 +GenericService xxxService = new XxxGenericService(); + +// 该实例很重量，里面封装了所有与注册中心及服务提供方连接，请缓存 +ServiceConfig service = new ServiceConfig(); +// 弱类型接口名 +service.setInterface("com.xxx.XxxService"); +service.setVersion("1.0.0"); +// 指向一个通用服务实现 +service.setRef(xxxService); + +// 暴露及注册服务 +service.export(); +``` + +# 实现泛化服务调用 + +泛化接口调用方式主要用于客户端没有 API 接口及模型类元的情况，参数及返回值中的所有 POJO 均用 `Map` 表示，通常用于框架集成，比如：实现一个通用的服务测试框架，可通过 `GenericService` 调用所有服务实现。 + +## 通过 Spring 使用泛化调用 + +在 Spring 配置申明 `generic="true"`： + +```xml + +``` + +在 Java 代码获取 barService 并开始泛化调用： + +```java +GenericService barService = (GenericService) applicationContext.getBean("barService"); +Object result = barService.$invoke("sayHello", new String[] { "java.lang.String" }, new Object[] { "World" }); +``` + +## 通过 API 方式使用泛化调用 + +```java +import org.apache.dubbo.rpc.service.GenericService; +... + +// 引用远程服务 +// 该实例很重量，里面封装了所有与注册中心及服务提供方连接，请缓存 +ReferenceConfig reference = new ReferenceConfig(); +// 弱类型接口名 +reference.setInterface("com.xxx.XxxService"); +reference.setVersion("1.0.0"); +// 声明为泛化接口 +reference.setGeneric(true); + +// 用org.apache.dubbo.rpc.service.GenericService可以替代所有接口引用 +GenericService genericService = reference.get(); + +// 基本类型以及Date,List,Map等不需要转换，直接调用 +Object result = genericService.$invoke("sayHello", new String[] {"java.lang.String"}, new Object[] {"world"}); + +// 用Map表示POJO参数，如果返回值为POJO也将自动转成Map +Map person = new HashMap(); +person.put("name", "xxx"); +person.put("password", "yyy"); +// 如果返回POJO将自动转成Map +Object result = genericService.$invoke("findPerson", new String[] +{"com.xxx.Person"}, new Object[]{person}); + +... +``` + +## 有关泛化类型的进一步解释 + +假设存在 POJO 如： + +```java +package com.xxx; + +public class PersonImpl implements Person { + private String name; + private String password; + + public String getName() { + return name; + } + + public void setName(String name) { + this.name = name; + } + + public String getPassword() { + return password; + } + + public void setPassword(String password) { + this.password = password; + } +} +``` + +则 POJO 数据： + +```java +Person person = new PersonImpl(); +person.setName("xxx"); +person.setPassword("yyy"); +``` + +可用下面 Map 表示： + +```java +Map map = new HashMap(); +// 注意：如果参数类型是接口，或者List等丢失泛型，可通过class属性指定类型。 +map.put("class", "com.xxx.PersonImpl"); +map.put("name", "xxx"); +map.put("password", "yyy"); +``` diff --git a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/group-merger.md b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/group-merger.md new file mode 100644 index 000000000000..22bba6d35488 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/group-merger.md @@ -0,0 +1,67 @@ +--- +type: docs +title: "分组聚合" +linkTitle: "分组聚合" +weight: 1 +description: "通过分组对结果进行聚合并返回聚合后的结果" +--- + +通过分组对结果进行聚合并返回聚合后的结果，比如菜单服务，用group区分同一接口的多种实现，现在消费方需从每种group中调用一次并返回结果，对结果进行合并之后返回，这样就可以实现聚合菜单项。 + +相关代码可以参考 [dubbo 项目中的示例](https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-merge) + +## 配置 + +搜索所有分组 + +```xml + +``` + +合并指定分组 + +```xml + +``` + +指定方法合并结果，其它未指定的方法，将只调用一个 Group + +```xml + + + +``` + +某个方法不合并结果，其它都合并结果 + +```xml + + + +``` + +指定合并策略，缺省根据返回值类型自动匹配，如果同一类型有两个合并器时，需指定合并器的名称 + +{{% alert title="提示" color="primary" %}} +参见：[合并结果扩展](../../../dev/impls/merger) +{{% /alert %}} + +```xml + + + +``` + +指定合并方法，将调用返回结果的指定方法进行合并，合并方法的参数类型必须是返回结果类型本身 + +```xml + + + +``` + + +{{% alert title="提示" color="primary" %}} +从 `2.1.0` 版本开始支持 +{{% /alert %}} + diff --git a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/local-mock.md b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/local-mock.md new file mode 100644 index 000000000000..d14a446f51bc --- /dev/null +++ b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/local-mock.md @@ -0,0 +1,106 @@ +--- +type: docs +title: "本地伪装" +linkTitle: "本地伪装" +weight: 10 +description: "如何在 Dubbo 中利用本地伪装实现服务降级" +--- + +本地伪装 [^1] 通常用于服务降级，比如某验权服务，当服务提供方全部挂掉后，客户端不抛出异常，而是通过 Mock 数据返回授权失败。 + +在 spring 配置文件中按以下方式配置： + +```xml + +``` + +或 + +```xml + +``` + +在工程中提供 Mock 实现 [^2]： + +```java +package com.foo; +public class BarServiceMock implements BarService { + public String sayHello(String name) { + // 你可以伪造容错数据，此方法只在出现RpcException时被执行 + return "容错数据"; + } +} +``` + +如果服务的消费方经常需要 try-catch 捕获异常，如： + +```java +Offer offer = null; +try { + offer = offerService.findOffer(offerId); +} catch (RpcException e) { + logger.error(e); +} +``` + +请考虑改为 Mock 实现，并在 Mock 实现中 return null。如果只是想简单的忽略异常，在 `2.0.11` 以上版本可用： + +```xml + +``` + +## 进阶用法 + +### return + +使用 `return` 来返回一个字符串表示的对象，作为 Mock 的返回值。合法的字符串可以是： +* *empty*: 代表空，基本类型的默认值，或者集合类的空值 +* *null*: `null` +* *true*: `true` +* *false*: `false` +* *JSON 格式*: 反序列化 JSON 所得到的对象 + +### throw + +使用 `throw` 来返回一个 Exception 对象，作为 Mock 的返回值。 + +当调用出错时，抛出一个默认的 RPCException: + +```xml + +``` + +当调用出错时，抛出指定的 Exception： + +```xml + +``` + +### force 和 fail + +在 `2.6.6` 以上的版本，可以开始在 Spring XML 配置文件中使用 `fail:` 和 `force:`。`force:` 代表强制使用 Mock 行为，在这种情况下不会走远程调用。`fail:` 与默认行为一致，只有当远程调用发生错误时才使用 Mock 行为。`force:` 和 `fail:` 都支持与 `throw` 或者 `return` 组合使用。 + +强制返回指定值： + +```xml + +``` + +强制抛出指定异常： + +```xml + +``` + +### 在方法级别配置 Mock + +Mock 可以在方法级别上指定，假定 `com.foo.BarService` 上有好几个方法，我们可以单独为 `sayHello()` 方法指定 Mock 行为。具体配置如下所示，在本例中，只要 `sayHello()` 被调用到时，强制返回 "fake": + +```xml + + + +``` + +[^1]: Mock 是 Stub 的一个子集，便于服务提供方在客户端执行容错逻辑，因经常需要在出现 RpcException (比如网络失败，超时等)时进行容错，而在出现业务异常(比如登录用户名密码错误)时不需要容错，如果用 Stub，可能就需要捕获并依赖 RpcException 类，而用 Mock 就可以不依赖 RpcException，因为它的约定就是只有出现 RpcException 时才执行。 +[^2]: 在 interface 旁放一个 Mock 实现，它实现 BarService 接口，并有一个无参构造函数 diff --git a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/local-stub.md b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/local-stub.md new file mode 100644 index 000000000000..71989d6593e0 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/local-stub.md @@ -0,0 +1,50 @@ +--- +type: docs +title: "本地存根" +linkTitle: "本地存根" +weight: 11 +description: "在 Dubbo 中利用本地存根在客户端执行部分逻辑" +--- + +远程服务后，客户端通常只剩下接口，而实现全在服务器端，但提供方有些时候想在客户端也执行部分逻辑，比如：做 ThreadLocal 缓存，提前验证参数，调用失败后伪造容错数据等等，此时就需要在 API 中带上 Stub，客户端生成 Proxy 实例，会把 Proxy 通过构造函数传给 Stub [^1]，然后把 Stub 暴露给用户，Stub 可以决定要不要去调 Proxy。 + +![/user-guide/images/stub.jpg](/imgs/user/stub.jpg) + +在 spring 配置文件中按以下方式配置： + +```xml + +``` + +或 + +```xml + +``` + +提供 Stub 的实现 [^2]： + +```java +package com.foo; +public class BarServiceStub implements BarService { + private final BarService barService; + + // 构造函数传入真正的远程代理对象 + public BarServiceStub(BarService barService){ + this.barService = barService; + } + + public String sayHello(String name) { + // 此代码在客户端执行, 你可以在客户端做ThreadLocal本地缓存，或预先验证参数是否合法，等等 + try { + return barService.sayHello(name); + } catch (Exception e) { + // 你可以容错，可以做任何AOP拦截事项 + return "容错数据"; + } + } +} +``` + +[^1]: Stub 必须有可传入 Proxy 的构造函数。 +[^2]: 在 interface 旁边放一个 Stub 实现，它实现 BarService 接口，并有一个传入远程 BarService 实例的构造函数 diff --git a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/parameter-validation.md b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/parameter-validation.md new file mode 100644 index 000000000000..bdd45fae00f8 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/parameter-validation.md @@ -0,0 +1,197 @@ +--- +type: docs +title: "参数校验" +linkTitle: "参数校验" +weight: 2 +description: "在 Dubbo 中进行参数校验" +--- + +参数验证功能是基于 [JSR303](https://jcp.org/en/jsr/detail?id=303) 实现的，用户只需标识 JSR303 标准的验证 annotation，并通过声明 filter 来实现验证。 + +## Maven 依赖 + +```xml + + javax.validation + validation-api + 1.0.0.GA + + + org.hibernate + hibernate-validator + 4.2.0.Final + +``` + +## 示例 + +### 参数标注示例 + +```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 // 不允许为空 + @Size(min = 1, max = 20) // 长度或大小范围 + private String name; + + @NotNull(groups = ValidationService.Save.class) // 保存时不允许为空，更新时允许为空 ，表示不更新该字段 + @Pattern(regexp = "^\\s*\\w+(?:\\.{0,1}[\\w-]+)*@[a-zA-Z0-9]+(?:[-.][a-zA-Z0-9]+)*\\.[a-zA-Z]+\\s*$") + private String email; + + @Min(18) // 最小值 + @Max(100) // 最大值 + private int age; + + @Past // 必须为一个过去的时间 + private Date loginDate; + + @Future // 必须为一个未来的时间 + 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; + } +} +``` + +### 分组验证示例 + +```java +public interface ValidationService { // 缺省可按服务接口区分验证场景，如：@NotNull(groups = ValidationService.class) + @interface Save{} // 与方法同名接口，首字母大写，用于区分验证场景，如：@NotNull(groups = ValidationService.Save.class)，可选 + void save(ValidationParameter parameter); + void update(ValidationParameter parameter); +} +``` + +### 关联验证示例 + +```java +import javax.validation.GroupSequence; + +public interface ValidationService { + @GroupSequence(Update.class) // 同时验证Update组规则 + @interface Save{} + void save(ValidationParameter parameter); + + @interface Update{} + void update(ValidationParameter parameter); +} +``` + +### 参数验证示例 + +```java +import javax.validation.constraints.Min; +import javax.validation.constraints.NotNull; + +public interface ValidationService { + void save(@NotNull ValidationParameter parameter); // 验证参数不为空 + void delete(@Min(1) int id); // 直接对基本类型参数验证 +} +``` + +## 配置 + +### 在客户端验证参数 + +```xml + +``` + +### 在服务器端验证参数 + +```xml + +``` + +{{% alert title="提示" color="primary" %}} +Dubbo 默认支持 hibernate-validator 版本 <=6.x，若使用 hibernate-validator 7.x 版本，请将 validation 参数声明为 jvalidatorNew +{{% /alert %}} + +## 验证异常信息 + +```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) { // 抛出的是RpcException + ConstraintViolationException ve = (ConstraintViolationException) e.getCause(); // 里面嵌了一个ConstraintViolationException + Set> violations = ve.getConstraintViolations(); // 可以拿到一个验证错误详细信息的集合 + System.out.println(violations); + } + } +} +``` + +{{% alert title="提示" color="primary" %}} +自 `2.1.0` 版本开始支持, 如何使用可以参考 [dubbo 项目中的示例代码](https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-validation) + +验证方式可扩展，扩展方式参见开发者手册中的[验证扩展](../../references/spis/validation) +{{% /alert %}} + diff --git a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/result-cache.md b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/result-cache.md new file mode 100644 index 000000000000..4a89565f2fc0 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/rpc/result-cache.md @@ -0,0 +1,38 @@ +--- +type: docs +title: "调用结果缓存" +linkTitle: "调用结果缓存" +weight: 7 +description: "通过缓存结果加速访问速度" +--- + +结果缓存，用于加速热门数据的访问速度，Dubbo 提供声明式缓存，以减少用户加缓存的工作量。 + +## 缓存类型 + +* `lru` 基于最近最少使用原则删除多余缓存，保持最热的数据被缓存。 +* `threadlocal` 当前线程缓存，比如一个页面渲染，用到很多 portal，每个 portal 都要去查用户信息，通过线程缓存，可以减少这种多余访问。 +* `jcache` 与 [JSR107](http://jcp.org/en/jsr/detail?id=107%27) 集成，可以桥接各种缓存实现。 + +缓存类型可扩展，参见：[缓存扩展](../../references/spis/cache) + +## 配置 + +```xml + +``` + +或： + +```xml + + + +``` + +{{% alert title="提示" color="primary" %}} +`2.1.0` 以上版本支持。 + +[示例代码](https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-cache) +{{% /alert %}} + diff --git a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/security/_index.md b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/security/_index.md new file mode 100755 index 000000000000..1dda223a30b1 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/security/_index.md @@ -0,0 +1,8 @@ + +--- +type: docs +title: "安全类特性" +linkTitle: "安全类特性" +weight: 4 +--- + diff --git a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/security/tls.md b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/security/tls.md new file mode 100644 index 000000000000..77f6c2471ce0 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/security/tls.md @@ -0,0 +1,51 @@ +--- +type: docs +title: "TLS支持" +linkTitle: "TLS支持" +weight: 1 +description: "通过 TLS 保证传输安全" +--- + +2.7.5 版本在传输链路的安全性上做了很多工作，对于内置的 Dubbo Netty Server 和新引入的 gRPC 协议都提供了基于 TLS 的安全链路传输机制。 + +TLS 的配置都有统一的入口，如下所示： + +##### Provider 端 + +```java +SslConfig sslConfig = new SslConfig(); +sslConfig.setServerKeyCertChainPath("path to cert"); +sslConfig.setServerPrivateKeyPath(args[1]); +// 如果开启双向 cert 认证 +if (mutualTls) { + sslConfig.setServerTrustCertCollectionPath(args[2]); +} + +ProtocolConfig protocolConfig = new ProtocolConfig("dubbo/grpc"); +protocolConfig.setSslEnabled(true); +``` + + + +##### Consumer 端 + +```java +if (!mutualTls) {} + sslConfig.setClientTrustCertCollectionPath(args[0]); +} else { + sslConfig.setClientTrustCertCollectionPath(args[0]); + sslConfig.setClientKeyCertChainPath(args[1]); + sslConfig.setClientPrivateKeyPath(args[2]); +} +``` + +为尽可能保证应用启动的灵活性，TLS Cert 的指定还能通过 -D 参数或环境变量等方式来在启动阶段根据部署环境动态指定，具体请参见 Dubbo 配置读取规则与 TLS 示例 + +{{% alert title="提示" color="primary" %}} +参考 Dubbo [配置读取规则](../../configuration/configuration-load-process)，TLS [示例](https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-ssl) + +如果要使用的是 gRPC 协议，在开启 TLS 时会使用到协议协商机制，因此必须使用支持 ALPN 机制的 Provider，推荐使用的是 netty-tcnative，具体可参见 gRPC Java 社区的[总结]( https://github.com/grpc/grpc-java/blob/master/SECURITY.md) +{{% /alert %}} + + +在服务调用的安全性上，Dubbo 在后续的版本中会持续投入，其中服务发现/调用的鉴权机制预计在接下来的版本中就会和大家见面。 diff --git a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/security/token-authorization.md b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/security/token-authorization.md new file mode 100644 index 000000000000..6e28da88aa17 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/security/token-authorization.md @@ -0,0 +1,37 @@ +--- +type: docs +title: "权限控制" +linkTitle: "权限控制" +weight: 2 +description: "通过令牌验证在注册中心控制权限" +--- + +通过令牌验证在注册中心控制权限，以决定要不要下发令牌给消费者，可以防止消费者绕过注册中心访问提供者，另外通过注册中心可灵活改变授权方式，而不需修改或升级提供者 + +![/user-guide/images/dubbo-token.jpg](/imgs/user/dubbo-token.jpg) + +可以全局设置开启令牌验证： + +```xml + + +``` +或 + +```xml + + +``` + +也可在服务级别设置： + +```xml + + +``` +或 + +```xml + + +``` diff --git a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/service/_index.md b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/service/_index.md new file mode 100755 index 000000000000..753a77186cd1 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/service/_index.md @@ -0,0 +1,8 @@ + +--- +type: docs +title: "服务类特性" +linkTitle: "服务类特性" +weight: 1 +--- + diff --git a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/service/multi-versions.md b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/service/multi-versions.md new file mode 100644 index 000000000000..551a7be541c1 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/service/multi-versions.md @@ -0,0 +1,49 @@ +--- +type: docs +title: "服务分版本" +linkTitle: "服务分版本" +weight: 1 +description: "在 Dubbo 中为同一个服务配置多个版本" +--- + +当一个接口实现，出现不兼容升级时，可以用版本号过渡，版本号不同的服务相互间不引用。 + +可以按照以下的步骤进行版本迁移： + +1. 在低压力时间段，先升级一半提供者为新版本 +2. 再将所有消费者升级为新版本 +3. 然后将剩下的一半提供者升级为新版本 + +老版本服务提供者配置： + +```xml + +``` + +新版本服务提供者配置： + +```xml + +``` + +老版本服务消费者配置： + +```xml + +``` + +新版本服务消费者配置： + +```xml + +``` + +如果不需要区分版本，可以按照以下的方式配置 [^1]： + +{{% alert title="提示" color="primary" %}} +`2.2.0` 以上版本支持 +{{% /alert %}} + +```xml + +``` diff --git a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/service/service-downgrade.md b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/service/service-downgrade.md new file mode 100644 index 000000000000..07790c44c425 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/service/service-downgrade.md @@ -0,0 +1,27 @@ +--- +type: docs +title: "服务降级" +linkTitle: "服务降级" +weight: 3 +description: "降级 Dubbo 服务" +--- + +可以通过服务降级功能临时屏蔽某个出错的非关键服务，并定义降级后的返回策略。 + +向注册中心写入动态配置覆盖规则： + +```java +RegistryFactory registryFactory = ExtensionLoader.getExtensionLoader(RegistryFactory.class).getAdaptiveExtension(); +Registry registry = registryFactory.getRegistry(URL.valueOf("zookeeper://10.20.153.10:2181")); +registry.register(URL.valueOf("override://0.0.0.0/com.foo.BarService?category=configurators&dynamic=false&application=foo&mock=force:return+null")); +``` + +其中： + +* `mock=force:return+null` 表示消费方对该服务的方法调用都直接返回 null 值，不发起远程调用。用来屏蔽不重要服务不可用时对调用方的影响。 +* 还可以改为 `mock=fail:return+null` 表示消费方对该服务的方法调用在失败后，再返回 null 值，不抛异常。用来容忍不重要服务不稳定时对调用方的影响。 + +{{% alert title="提示" color="primary" %}} +`2.2.0` 以上版本支持 +{{% /alert %}} + diff --git a/content/zh/docs3-building/java-sdk/advanced-features-and-usage/service/service-group.md b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/service/service-group.md new file mode 100644 index 000000000000..18a60fd89785 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/advanced-features-and-usage/service/service-group.md @@ -0,0 +1,33 @@ +--- +type: docs +title: "服务分组" +linkTitle: "服务分组" +weight: 2 +description: "使用服务分组区分服务接口的不同实现" +--- + +当一个接口有多种实现时，可以用 group 区分。 + +## 服务 + +```xml + + +``` + +## 引用 + +```xml + + +``` + +任意组： + +```xml + +``` + +{{% alert title="提示" color="primary" %}} +`2.2.0` 以上版本支持，总是只调一个可用组的实现 +{{% /alert %}} diff --git a/content/zh/docs3-building/java-sdk/concepts-and-architecture/_index.md b/content/zh/docs3-building/java-sdk/concepts-and-architecture/_index.md new file mode 100755 index 000000000000..25376686d78f --- /dev/null +++ b/content/zh/docs3-building/java-sdk/concepts-and-architecture/_index.md @@ -0,0 +1,8 @@ + +--- +type: docs +title: "概念和架构" +linkTitle: "概念和架构" +weight: 3 +--- + diff --git a/content/zh/docs3-building/java-sdk/concepts-and-architecture/overall-architecture.md b/content/zh/docs3-building/java-sdk/concepts-and-architecture/overall-architecture.md new file mode 100644 index 000000000000..540ed7d024ac --- /dev/null +++ b/content/zh/docs3-building/java-sdk/concepts-and-architecture/overall-architecture.md @@ -0,0 +1,11 @@ +--- +type: docs +title: "总体架构" +linkTitle: "总体架构" +weight: 1 +--- + +### 总体架构图 + + +### 消费端调用原理（选址等） diff --git a/content/zh/docs3-building/java-sdk/concepts-and-architecture/service-discovery.md b/content/zh/docs3-building/java-sdk/concepts-and-architecture/service-discovery.md new file mode 100644 index 000000000000..4af2a11e3944 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/concepts-and-architecture/service-discovery.md @@ -0,0 +1,71 @@ +--- +type: docs +title: "服务发现" +linkTitle: "服务发现" +weight: 2 +--- +服务发现，即消费端自动发现服务地址列表的能力，是微服务框架需要具备的关键能力，借助于自动化的服务发现，微服务之间可以在无需感知对端部署位置与 IP 地址的情况下实现通信。 + +实现服务发现的方式有很多种，Dubbo 提供的是一种 Client-Based 的服务发现机制，通常还需要部署额外的第三方注册中心组件来协调服务发现过程，如常用的 Nacos、Consul、Zookeeper 等，Dubbo 自身也提供了对多种注册中心组件的对接，用户可以灵活选择。 + +Dubbo 基于消费端的自动服务发现能力，其基本工作原理如下图： + +![//imgs/architecture.png](/imgs/architecture.png) + +服务发现的一个核心组件是注册中心，Provider 注册地址到注册中心，Consumer 从注册中心读取和订阅 Provider 地址列表。 +因此，要启用服务发现，需要为 Dubbo 增加注册中心配置： + +以 dubbo-spring-boot-starter 使用方式为例，增加 registry 配置 + +```properties +# application.properties +dubbo + registry + address: zookeeper://127.0.0.1:2181 +``` + +## What's New in Dubbo3 +就使用方式上而言，Dubbo3 与 Dubbo2 的服务发现配置是完全一致的，不需要改动什么内容。但就实现原理上而言，Dubbo3 引入了全新的服务发现模型 - 应用级服务发现， +在工作原理、数据格式上已完全不能兼容老版本服务发现。 + +* Dubbo3 应用级服务发现，以应用粒度组织地址数据 +* Dubbo2 接口级服务发现，以接口粒度组织地址数据 + +Dubbo3 格式的 Provider 地址不能被 Dubbo2 的 Consumer 识别到，反之 Dubbo2 的消费者也不能订阅到 Dubbo3 Provider。 +* 对于新用户，我们提倡直接启用 Dubbo3 的默认行为，即启用应用级服务发现，参见《[应用级服务发现](../../examples/service-discovery)》； +* 对于老用户，要面临如何平滑迁移到应用级服务发现的问题，考虑到老用户的规模如此之大，Dubbo3 默认保持了接口级地址发现的行为，这保证了老用户可以直接无感升级到 Dubbo3。 +而如果要开启应用级服务发现，则需要通过配置显示开启（双注册、双订阅），具体开启与平滑迁移过程，可参见《[地址发现迁移指南](../../migration/migration-service-discovery)》。 + +## 应用级服务发现简介 +概括来说，Dubbo3 引入的应用级服务发现主要有以下优势 +* 适配云原生微服务变革。云原生时代的基础设施能力不断向上释放，像 Kubernetes 等平台都集成了微服务概念抽象，Dubbo3 的应用级服务发现是适配各种微服务体系的通用模型。 +* 提升性能与可伸缩性。支持超大规模集群的服务治理一直以来都是 Dubbo 的优势，通过引入应用级服务发现模型，从本质上解决了注册中心地址数据的存储与推送压力，相应的 Consumer 侧的地址计算压力也成数量级下降；集群规模也开始变得可预测、可评估（与 RPC 接口数量无关，只与实例部署规模相关）。 + +下图是 Dubbo2 的服务发现模型：Provider 注册服务地址，Consumer 经过注册中心协调并发现服务地址，进而对地址发起通信，这是被绝大多数微服务框架的经典服务发现流程。而 Dubbo2 的特殊之处在于，它把 “RPC 接口”的信息也融合在了地址发现过程中，而这部分信息往往是和具体的业务定义密切相关的。 + +![//imgs/v3/concepts/servicediscovery_old.png](/imgs/v3/concepts/servicediscovery_old.png) + +而在接入云原生基础设施后，基础设施融入了微服务概念的抽象，容器化微服务被编排、调度的过程即完成了在基础设施层面的注册。如下图所示，基础设施既承担了注册中心的职责，又完成了服务注册的动作，而 “RPC 接口”这部分信息，由于与具体的业务相关，不可能也不适合被基础设施托管。 + +![//imgs/v3/concepts/servicediscovery_k8s.png](/imgs/v3/concepts/servicediscovery_k8s.png) + +在这样的场景下，对 Dubbo3 的服务注册发现机制提出了两个要求： +Dubbo3 需要在原有服务发现流程中抽象出通用的、与业务逻辑无关的地址映射模型，并确保这部分模型足够合理，以支持将地址的注册行为和存储委托给下层基础设施 +Dubbo3 特有的业务接口同步机制，是 Dubbo3 需要保留的优势，需要在 Dubbo3 中定义的新地址模型之上，通过框架内的自有机制予以解决。 + +这样设计的全新的服务发现模型，在架构兼容性、可伸缩性上都给 Dubbo3 带来了更大的优势。 + +![//imgs/v3/concepts/servicediscovery_mem.png](/imgs/v3/concepts/servicediscovery_mem.png) + +在架构兼容性上，如上文所述，Dubbo3 复用下层基础设施的服务抽象能力成为了可能；另一方面，如 Spring Cloud 等业界其它微服务解决方案也沿用这种模型， +在打通了地址发现之后，使得用户探索用 Dubbo 连接异构的微服务体系成为了一种可能。 + +Dubbo3 服务发现模型更适合构建可伸缩的服务体系，这点要如何理解？ +这里先举个简单的例子，来直观的对比 Dubbo2 与 Dubbo3 在地址发现流程上的数据流量变化：假设一个微服务应用定义了 100 个接口（Dubbo 中的服务）， +则需要往注册中心中注册 100 个服务，如果这个应用被部署在了 100 台机器上，那这 100 个服务总共会产生 100 * 100 = 10000 个虚拟节点；而同样的应用， +对于 Dubbo3 来说，新的注册发现模型只需要 1 个服务（只和应用有关和接口无关）， 只注册和机器实例数相等的 1 * 100 = 100 个虚拟节点到注册中心。 +在这个简单的示例中，Dubbo 所注册的地址数量下降到了原来的 1 / 100，对于注册中心、订阅方的存储压力都是一个极大的释放。更重要的是， +地址发现容量彻底与业务 RPC 定义解耦开来，整个集群的容量评估对运维来说将变得更加透明：部署多少台机器就会有多大负载，不会像 Dubbo2 一样， +因为业务 RPC 重构就会影响到整个集群服务发现的稳定性。 + +请通过以下 blog 了解更多应用级服务发现设计原则细节。 diff --git a/content/zh/docs3-building/java-sdk/concepts-and-architecture/service-invocation.md b/content/zh/docs3-building/java-sdk/concepts-and-architecture/service-invocation.md new file mode 100644 index 000000000000..9426206f6b76 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/concepts-and-architecture/service-invocation.md @@ -0,0 +1,13 @@ +--- +type: docs +title: "服务调用" +linkTitle: "服务调用" +weight: 3 +--- + + +Filter + +Router + +LoadBalance \ No newline at end of file diff --git a/content/zh/docs3-building/java-sdk/contributing/_index.md b/content/zh/docs3-building/java-sdk/contributing/_index.md new file mode 100755 index 000000000000..24ba35940904 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/contributing/_index.md @@ -0,0 +1,8 @@ + +--- +type: docs +title: "参与贡献" +linkTitle: "参与贡献" +weight: 7 +--- + diff --git a/content/zh/docs3-building/java-sdk/contributing/guide.md b/content/zh/docs3-building/java-sdk/contributing/guide.md new file mode 100644 index 000000000000..16c6cd0db6d7 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/contributing/guide.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "贡献指南" +linkTitle: "贡献指南" +weight: 2 +--- diff --git a/content/zh/docs3-building/java-sdk/contributing/overview.md b/content/zh/docs3-building/java-sdk/contributing/overview.md new file mode 100644 index 000000000000..c087fc3b6f43 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/contributing/overview.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "概述" +linkTitle: "概述" +weight: 1 +--- diff --git a/content/zh/docs3-building/java-sdk/quick-start/_index.md b/content/zh/docs3-building/java-sdk/quick-start/_index.md new file mode 100755 index 000000000000..d4895cc73e55 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/quick-start/_index.md @@ -0,0 +1,8 @@ + +--- +type: docs +title: "快速入门" +linkTitle: "快速入门" +weight: 2 +--- + diff --git a/content/zh/docs3-building/java-sdk/reference-manual/_index.md b/content/zh/docs3-building/java-sdk/reference-manual/_index.md new file mode 100755 index 000000000000..aabb12962423 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/_index.md @@ -0,0 +1,8 @@ + +--- +type: docs +title: "参考手册" +linkTitle: "参考手册" +weight: 5 +--- + diff --git a/content/zh/docs3-building/java-sdk/reference-manual/config-center/_index.md b/content/zh/docs3-building/java-sdk/reference-manual/config-center/_index.md new file mode 100644 index 000000000000..3d139af023ab --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/config-center/_index.md @@ -0,0 +1,7 @@ +--- +type: docs +title: "配置中心参考手册" +linkTitle: "配置中心参考手册" +weight: 7 +description: "" +--- diff --git a/content/zh/docs3-building/java-sdk/reference-manual/config-center/apollo/_index.md b/content/zh/docs3-building/java-sdk/reference-manual/config-center/apollo/_index.md new file mode 100644 index 000000000000..fa239c2de7ec --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/config-center/apollo/_index.md @@ -0,0 +1,7 @@ +--- +type: docs +title: "Apollo" +linkTitle: "Apollo" +weight: 4 +description: "" +--- diff --git a/content/zh/docs3-building/java-sdk/reference-manual/config-center/apollo/guide.md b/content/zh/docs3-building/java-sdk/reference-manual/config-center/apollo/guide.md new file mode 100644 index 000000000000..13dc994973dd --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/config-center/apollo/guide.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "使用说明" +linkTitle: "使用说明" +weight: 2 +--- diff --git a/content/zh/docs3-building/java-sdk/reference-manual/config-center/apollo/overview.md b/content/zh/docs3-building/java-sdk/reference-manual/config-center/apollo/overview.md new file mode 100644 index 000000000000..c087fc3b6f43 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/config-center/apollo/overview.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "概述" +linkTitle: "概述" +weight: 1 +--- diff --git a/content/zh/docs3-building/java-sdk/reference-manual/config-center/nacos/_index.md b/content/zh/docs3-building/java-sdk/reference-manual/config-center/nacos/_index.md new file mode 100644 index 000000000000..7fed8cf789af --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/config-center/nacos/_index.md @@ -0,0 +1,7 @@ +--- +type: docs +title: "Nacos" +linkTitle: "Nacos" +weight: 3 +description: "" +--- diff --git a/content/zh/docs3-building/java-sdk/reference-manual/config-center/nacos/guide.md b/content/zh/docs3-building/java-sdk/reference-manual/config-center/nacos/guide.md new file mode 100644 index 000000000000..13dc994973dd --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/config-center/nacos/guide.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "使用说明" +linkTitle: "使用说明" +weight: 2 +--- diff --git a/content/zh/docs3-building/java-sdk/reference-manual/config-center/nacos/overview.md b/content/zh/docs3-building/java-sdk/reference-manual/config-center/nacos/overview.md new file mode 100644 index 000000000000..c087fc3b6f43 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/config-center/nacos/overview.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "概述" +linkTitle: "概述" +weight: 1 +--- diff --git a/content/zh/docs3-building/java-sdk/reference-manual/config-center/overview/_index.md b/content/zh/docs3-building/java-sdk/reference-manual/config-center/overview/_index.md new file mode 100644 index 000000000000..40ea6666d928 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/config-center/overview/_index.md @@ -0,0 +1,79 @@ +--- +type: docs +title: "配置中心概述" +linkTitle: "配置中心概述" +weight: 1 +--- + +配置中心在 Dubbo 中承担3个职责： + +1. 外部化配置：启动配置的集中式存储 （简单理解为 dubbo.properties 的外部化存储）。 +2. 服务治理：服务治理规则的存储与通知。 +3. 动态配置：控制动态开关或者动态变更属性值 + +启用动态配置，以 Zookeeper 为例，可查看 [配置中心属性详解](../../references/xml/dubbo-config-center) + +```xml + +``` + +或者 + +```properties +dubbo.config-center.address=zookeeper://127.0.0.1:2181 +``` + +或者 + +```java +ConfigCenterConfig configCenter = new ConfigCenterConfig(); +configCenter.setAddress("zookeeper://127.0.0.1:2181"); +``` + +> 为了兼容 2.6.x 版本配置，在使用 Zookeeper 作为注册中心，且没有显示配置配置中心的情况下，Dubbo 框架会默认将此 Zookeeper 用作配置中心，但将只作服务治理用途。 + +## 外部化配置 +请参考文档 [外部化配置](../configuration/external-config) + +## 动态配置 +[TODO 待完善] + +## 服务治理 + +#### Zookeeper + +默认节点结构： + +![zk-configcenter-governance](/imgs/user/zk-configcenter-governance.jpg) + +- namespace，用于不同配置的环境隔离。 +- config，Dubbo 约定的固定节点，不可更改，所有配置和服务治理规则都存储在此节点下。 +- dubbo，所有服务治理规则都是全局性的，dubbo 为默认节点 +- configurators/tag-router/condition-router/migration，不同的服务治理规则类型，node value 存储具体规则内容 + +#### Apollo + +所有的服务治理规则都是全局性的，默认从公共命名空间 `dubbo` 读取和订阅： + +![apollo-configcenter-governance.jpg](/imgs/user/apollo-configcenter-governance.jpg) + +不同的规则以不同的 key 后缀区分： + +- configurators，[覆盖规则](../../examples/config-rule) +- tag-router，[标签路由](../../examples/routing-rule) +- condition-router，[条件路由](../../examples/condition-router) +- migration, [迁移规则](../../examples/todo) + +#### Nacos + +所有的服务治理规则都是全局的，默认从 namespace: `public` 下进行读取， 通过 dataId: `interface name` 以及 group: `dubbo` 去读取和订阅： + +![nacos-configcenter-governance.jpg](/imgs/user/nacos-configcenter-governance.png) + +不同的规则以 dataId 的后缀区分： + +- configurators，[覆盖规则](../../examples/config-rule) +- tag-router，[标签路由](../../examples/routing-rule) +- condition-router，[条件路由](../../examples/condition-router) +- migration, [迁移规则](../../examples/todo) + diff --git a/content/zh/docs3-building/java-sdk/reference-manual/config-center/zookeeper/_index.md b/content/zh/docs3-building/java-sdk/reference-manual/config-center/zookeeper/_index.md new file mode 100644 index 000000000000..2864a6f0b145 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/config-center/zookeeper/_index.md @@ -0,0 +1,7 @@ +--- +type: docs +title: "Zookeeper" +linkTitle: "Zookeeper" +weight: 2 +description: "" +--- diff --git a/content/zh/docs3-building/java-sdk/reference-manual/config-center/zookeeper/guide.md b/content/zh/docs3-building/java-sdk/reference-manual/config-center/zookeeper/guide.md new file mode 100644 index 000000000000..37430b92141b --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/config-center/zookeeper/guide.md @@ -0,0 +1,7 @@ +--- +type: docs +title: "使用说明" +linkTitle: "使用说明" +weight: 2 +--- + diff --git a/content/zh/docs3-building/java-sdk/reference-manual/config-center/zookeeper/overview.md b/content/zh/docs3-building/java-sdk/reference-manual/config-center/zookeeper/overview.md new file mode 100644 index 000000000000..c087fc3b6f43 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/config-center/zookeeper/overview.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "概述" +linkTitle: "概述" +weight: 1 +--- diff --git a/content/zh/docs3-building/java-sdk/reference-manual/config/_index.md b/content/zh/docs3-building/java-sdk/reference-manual/config/_index.md new file mode 100644 index 000000000000..2cb876ce3003 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/config/_index.md @@ -0,0 +1,7 @@ +--- +type: docs +title: "配置说明手册" +linkTitle: "配置说明手册" +weight: 1 +description: "以不同的方式来配置你的 Dubbo 应用" +--- \ No newline at end of file diff --git a/content/zh/docs3-building/java-sdk/reference-manual/config/annotation/_index.md b/content/zh/docs3-building/java-sdk/reference-manual/config/annotation/_index.md new file mode 100644 index 000000000000..f9674a104a40 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/config/annotation/_index.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "Annotation 配置手册" +linkTitle: "Annotation 配置手册" +weight: 5 +--- \ No newline at end of file diff --git a/content/zh/docs3-building/java-sdk/reference-manual/config/annotation/description.md b/content/zh/docs3-building/java-sdk/reference-manual/config/annotation/description.md new file mode 100644 index 000000000000..b82b3289ac85 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/config/annotation/description.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "配置项描述" +linkTitle: "配置项描述" +weight: 2 +--- \ No newline at end of file diff --git a/content/zh/docs3-building/java-sdk/reference-manual/config/annotation/guide.md b/content/zh/docs3-building/java-sdk/reference-manual/config/annotation/guide.md new file mode 100644 index 000000000000..4ca6dd6a08fc --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/config/annotation/guide.md @@ -0,0 +1,97 @@ +--- +type: docs +title: "配置指南" +linkTitle: "配置指南" +weight: 1 +description: "以注解配置的方式来配置你的 Dubbo 应用" +--- + +{{% alert title="提示" color="primary" %}} +需要 `2.6.3` 及以上版本支持。 点此查看 [完整示例](https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-annotation) +{{% /alert %}} + + +## 服务提供方 + +### `Service`注解暴露服务 + +```java +@Service +public class AnnotationServiceImpl implements AnnotationService { + @Override + public String sayHello(String name) { + return "annotation: hello, " + name; + } +} +``` + +### 增加应用共享配置 + +```properties +# dubbo-provider.properties +dubbo.application.name=annotation-provider +dubbo.registry.address=zookeeper://127.0.0.1:2181 +dubbo.protocol.name=dubbo +dubbo.protocol.port=20880 +``` + +### 指定Spring扫描路径 + +```java +@Configuration +@EnableDubbo(scanBasePackages = "org.apache.dubbo.samples.simple.annotation.impl") +@PropertySource("classpath:/spring/dubbo-provider.properties") +static public class ProviderConfiguration { + +} +``` + +## 服务消费方 + +### `Reference`注解引用服务 + +```java +@Component("annotationAction") +public class AnnotationAction { + + @Reference + private AnnotationService annotationService; + + public String doSayHello(String name) { + return annotationService.sayHello(name); + } +} + +``` + +### 增加应用共享配置 + +```properties +# dubbo-consumer.properties +dubbo.application.name=annotation-consumer +dubbo.registry.address=zookeeper://127.0.0.1:2181 +dubbo.consumer.timeout=3000 +``` + +### 指定Spring扫描路径 + +```java +@Configuration +@EnableDubbo(scanBasePackages = "org.apache.dubbo.samples.simple.annotation.action") +@PropertySource("classpath:/spring/dubbo-consumer.properties") +@ComponentScan(value = {"org.apache.dubbo.samples.simple.annotation.action"}) +static public class ConsumerConfiguration { + +} +``` + +### 调用服务 + +```java +public static void main(String[] args) throws Exception { + AnnotationConfigApplicationContext context = new AnnotationConfigApplicationContext(ConsumerConfiguration.class); + context.start(); + final AnnotationAction annotationAction = (AnnotationAction) context.getBean("annotationAction"); + String hello = annotationAction.doSayHello("world"); +} +``` diff --git a/content/zh/docs3-building/java-sdk/reference-manual/config/api/_index.md b/content/zh/docs3-building/java-sdk/reference-manual/config/api/_index.md new file mode 100644 index 000000000000..80e4fec97b21 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/config/api/_index.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "API 配置手册" +linkTitle: "API 配置手册" +weight: 2 +--- \ No newline at end of file diff --git a/content/zh/docs3-building/java-sdk/reference-manual/config/api/description.md b/content/zh/docs3-building/java-sdk/reference-manual/config/api/description.md new file mode 100644 index 000000000000..b82b3289ac85 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/config/api/description.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "配置项描述" +linkTitle: "配置项描述" +weight: 2 +--- \ No newline at end of file diff --git a/content/zh/docs3-building/java-sdk/reference-manual/config/api/guide.md b/content/zh/docs3-building/java-sdk/reference-manual/config/api/guide.md new file mode 100644 index 000000000000..fa1b50263033 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/config/api/guide.md @@ -0,0 +1,315 @@ +--- +type: docs +title: "配置指南" +linkTitle: "配置指南" +weight: 1 +description: "以API 配置的方式来配置你的 Dubbo 应用" +--- + +通过API编码方式组装配置，启动Dubbo，发布及订阅服务。此方式可以支持动态创建ReferenceConfig/ServiceConfig，结合泛化调用可以满足API Gateway或测试平台的需要。 + +> API 属性与XML配置项一一对应，各属性含义请参见：[XML配置参考手册](../../../references/xml/)，比如：`ApplicationConfig.setName("xxx")` 对应 `` + +> API使用范围说明：API 仅用于 OpenAPI, ESB, Test, Mock, Gateway 等系统集成，普通服务提供方或消费方，请采用[XML 配置](../xml) 或 +> [注解配置](../annotation) 或 [属性配置](../properties) 方式使用 Dubbo + +> 参考[API示例](https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-api) + +## 服务提供者 + +通过ServiceConfig暴露服务接口，发布服务接口到注册中心。 + +> 注意：为了更好支持Dubbo3的应用级服务发现，推荐使用新的DubboBootstrap 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) { + // 服务实现 + DemoService demoService = new DemoServiceImpl(); + + // 当前应用配置 + ApplicationConfig application = new ApplicationConfig(); + application.setName("demo-provider"); + + // 连接注册中心配置 + RegistryConfig registry = new RegistryConfig(); + registry.setAddress("zookeeper://10.20.130.230:2181"); + + // 服务提供者协议配置 + ProtocolConfig protocol = new ProtocolConfig(); + protocol.setName("dubbo"); + protocol.setPort(12345); + protocol.setThreads(200); + + // 注意：ServiceConfig为重对象，内部封装了与注册中心的连接，以及开启服务端口 + // 服务提供者暴露服务配置 + ServiceConfig service = new ServiceConfig(); // 此实例很重，封装了与注册中心的连接，请自行缓存，否则可能造成内存和连接泄漏 + service.setApplication(application); + service.setRegistry(registry); // 多个注册中心可以用setRegistries() + service.setProtocol(protocol); // 多个协议可以用setProtocols() + service.setInterface(DemoService.class); + service.setRef(demoService); + service.setVersion("1.0.0"); + + // 暴露及注册服务 + service.export(); + + // 挂起等待(防止进程退出） + System.in.read(); + } +} +``` + +## 服务消费者 + +通过ReferenceConfig引用远程服务，从注册中心订阅服务接口。 + +> 注意：为了更好支持Dubbo3的应用级服务发现，推荐使用新的DubboBootstrap 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) { + // 当前应用配置 + ApplicationConfig application = new ApplicationConfig(); + application.setName("demo-consumer"); + + // 连接注册中心配置 + RegistryConfig registry = new RegistryConfig(); + registry.setAddress("zookeeper://10.20.130.230:2181"); + + // 注意：ReferenceConfig为重对象，内部封装了与注册中心的连接，以及与服务提供方的连接 + // 引用远程服务 + ReferenceConfig reference = new ReferenceConfig(); // 此实例很重，封装了与注册中心的连接以及与提供者的连接，请自行缓存，否则可能造成内存和连接泄漏 + reference.setApplication(application); + reference.setRegistry(registry); // 多个注册中心可以用setRegistries() + reference.setInterface(DemoService.class); + reference.setVersion("1.0.0"); + + // 和本地bean一样使用demoService + // 注意：此代理对象内部封装了所有通讯细节，对象较重，请缓存复用 + DemoService demoService = reference.get(); + demoService.sayHello("Dubbo"); + } +} +``` + +## Bootstrap API + +通过DubboBootstrap API可以减少重复配置，更好控制启动过程，支持批量发布/订阅服务接口，还可以更好支持Dubbo3的应用级服务发现。 + +```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"); + + // 服务提供者协议配置 + ProtocolConfig protocol = new ProtocolConfig(); + protocol.setName("dubbo"); + protocol.setPort(12345); + protocol.setThreads(200); + + // 注意：ServiceConfig为重对象，内部封装了与注册中心的连接，以及开启服务端口 + // 服务提供者暴露服务配置 + ServiceConfig demoServiceConfig = new ServiceConfig<>(); + demoServiceConfig.setInterface(DemoService.class); + demoServiceConfig.setRef(new DemoServiceImpl()); + demoServiceConfig.setVersion("1.0.0"); + + // 第二个服务配置 + ServiceConfig fooServiceConfig = new ServiceConfig<>(); + fooServiceConfig.setInterface(FooService.class); + fooServiceConfig.setRef(new FooServiceImpl()); + fooServiceConfig.setVersion("1.0.0"); + + ... + + // 通过DubboBootstrap简化配置组装，控制启动过程 + DubboBootstrap.getInstance() + .application("demo-provider") // 应用配置 + .registry(new RegistryConfig("zookeeper://127.0.0.1:2181")) // 注册中心配置 + .protocol(protocol) // 全局默认协议配置 + .service(demoServiceConfig) // 添加ServiceConfig + .service(fooServiceConfig) + .start() // 启动Dubbo + .await(); // 挂起等待(防止进程退出） + } +} +``` + +```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) { + + // 引用远程服务 + 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"); + + // 通过DubboBootstrap简化配置组装，控制启动过程 + DubboBootstrap bootstrap = DubboBootstrap.getInstance(); + bootstrap.application("demo-consumer") // 应用配置 + .registry(new RegistryConfig("zookeeper://127.0.0.1:2181")) // 注册中心配置 + .reference(demoServiceReference) // 添加ReferenceConfig + .service(fooServiceReference) + .start(); // 启动Dubbo + + ... + + // 和本地bean一样使用demoService + // 通过Interface获取远程服务接口代理，不需要依赖ReferenceConfig对象 + DemoService demoService = DubboBootstrap.getInstance().getCache().get(DemoService.class); + demoService.sayHello("Dubbo"); + + FooService fooService = DubboBootstrap.getInstance().getCache().get(FooService.class); + fooService.greeting("Dubbo"); + } + +} + +``` + +## 其它配置 + +API配置能力与XML配置是等价的，其它的各种配置都可以用API设置。 + +下面只列出不同的地方，其它参见上面的写法。 + +### 基本配置 + +可以在DubboBootstrap中设置全局基本配置，包括应用配置、协议配置、注册中心、配置中心、元数据中心、模块、监控、SSL、provider配置、consumer配置等。 + +```java +// 注册中心 +RegistryConfig registry = new RegistryConfig(); +registry.setAddress("zookeeper://192.168.10.1:2181"); +... + +// 服务提供者协议配置 +ProtocolConfig protocol = new ProtocolConfig(); +protocol.setName("dubbo"); +protocol.setPort(12345); +protocol.setThreads(200); +... + +// 配置中心 +ConfigCenterConfig configCenter = new ConfigCenterConfig(); +configCenter.setAddress("zookeeper://192.168.10.2:2181"); +... + +// 元数据中心 +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配置（ServiceConfig默认配置） +ProviderConfig provider = new ProviderConfig(); +provider.setGroup("demo"); +provider.setVersion("1.0.0"); +... + +// Consumer配置（ReferenceConfig默认配置） +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(); + +``` + +### 方法级设置 + +```java +... + +// 方法级配置 +List methods = new ArrayList(); +MethodConfig method = new MethodConfig(); +method.setName("sayHello"); +method.setTimeout(10000); +method.setRetries(0); +methods.add(method); + +// 引用远程服务 +ReferenceConfig reference = new ReferenceConfig(); // 此实例很重，封装了与注册中心的连接以及与提供者的连接，请自行缓存，否则可能造成内存和连接泄漏 +... +reference.setMethods(methods); // 设置方法级配置 + +... +``` + +### 点对点直连 + +```java + +... + +// 此实例很重，封装了与注册中心的连接以及与提供者的连接，请自行缓存，否则可能造成内存和连接泄漏 +ReferenceConfig reference = new ReferenceConfig(); +// 如果点对点直连，可以用reference.setUrl()指定目标地址，设置url后将绕过注册中心， +// 其中，协议对应provider.setProtocol()的值，端口对应provider.setPort()的值， +// 路径对应service.setPath()的值，如果未设置path，缺省path为接口名 +reference.setUrl("dubbo://10.20.130.230:20880/com.xxx.DemoService"); + +... +``` + diff --git a/content/zh/docs3-building/java-sdk/reference-manual/config/env/_index.md b/content/zh/docs3-building/java-sdk/reference-manual/config/env/_index.md new file mode 100644 index 000000000000..d52ae588f593 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/config/env/_index.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "环境变量配置手册" +linkTitle: "环境变量配置手册" +weight: 7 +--- \ No newline at end of file diff --git a/content/zh/docs3-building/java-sdk/reference-manual/config/env/description.md b/content/zh/docs3-building/java-sdk/reference-manual/config/env/description.md new file mode 100644 index 000000000000..b82b3289ac85 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/config/env/description.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "配置项描述" +linkTitle: "配置项描述" +weight: 2 +--- \ No newline at end of file diff --git a/content/zh/docs3-building/java-sdk/reference-manual/config/env/guide.md b/content/zh/docs3-building/java-sdk/reference-manual/config/env/guide.md new file mode 100644 index 000000000000..7b9af1b902c9 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/config/env/guide.md @@ -0,0 +1,35 @@ +--- +type: docs +title: "配置指南" +linkTitle: "配置指南" +weight: 1 +description: "在 Dubbo 中自动加载环境变量" +--- + +从 2.7.3 版本开始，Dubbo 会自动从约定 key 中读取配置，并将配置以 Key-Value 的形式写入到URL中。 + +支持的 key 有以下两个： + +1. `dubbo.labels`，指定一些列配置到 URL 中的键值对，通常通过 JVM -D 或系统环境变量指定。 + + 增加以下配置： + + ```properties + # JVM + -Ddubbo.labels = "tag1=value1; tag2=value2" + # 环境变量 + DUBBO_LABELS = "tag1=value1; tag2=value2" + ``` + + 最终生成的 URL 会包含 tag1、tag2 两个 key: `dubbo://xxx?tag1=value1&tag2=value2` + +2. `dubbo.env.keys`，指定环境变量 key 值，Dubbo 会尝试从环境变量加载每个 key + + ```properties + # JVM + -Ddubbo.env.keys = "DUBBO_TAG1, DUBBO_TAG2" + # 环境变量 + DUBBO_ENV_KEYS = "DUBBO_TAG1, DUBBO_TAG2" + ``` + + 最终生成的 URL 会包含 DUBBO_TAG1、DUBBO_TAG2 两个 key: `dubbo://xxx?DUBBO_TAG1=value1&DUBBO_TAG2=value2` \ No newline at end of file diff --git a/content/zh/docs3-building/java-sdk/reference-manual/config/overview/_index.md b/content/zh/docs3-building/java-sdk/reference-manual/config/overview/_index.md new file mode 100644 index 000000000000..c7b42882599b --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/config/overview/_index.md @@ -0,0 +1,196 @@ +--- +type: docs +title: "配置概述" +linkTitle: "配置概述" +weight: 1 +description: "Dubbo配置介绍" +--- + +本文主要介绍Dubbo配置概况，包括配置组件、配置来源、配置方式及配置加载流程。 + +## 配置组件 + +Dubbo框架的配置项比较繁多，为了更好地管理各种配置，将其按照用途划分为不同的组件，最终所有配置项都会汇聚到URL中，传递给后续处理模块。 + +常用配置组件如下： +- application: Dubbo应用配置 +- registry: 注册中心 +- protocol: 服务提供者RPC协议 +- config-center: 配置中心 +- metadata-report: 元数据中心 +- service: 服务提供者配置 +- reference: 远程服务引用配置 +- provider: service的默认配置或分组配置 +- consumer: reference的默认配置或分组配置 +- module: 模块配置 +- monitor: 监控配置 +- metrics: 指标配置 +- ssl: SSL/TLS配置 + +### consumer 与 reference的关系 + +reference可以指定具体的consumer，如果没有指定consumer则会自动使用全局默认的consumer配置。 + +consumer的属性是reference属性的默认值，可以体现在两个地方： + +1. 在刷新属性(属性覆盖)时，先提取其consumer的属性，然后提取reference自身的属性覆盖上去，叠加后的属性集合作为配置来源之一。 +2. 在组装reference的URL参数时，先附加其consumer的属性，然后附加reference自身的属性。 + +> 可以将consumer组件理解为reference组件的虚拟分组，根据需要可以定义多个不同的consumer，不同的consumer设置特定的默认值， +然后在reference中指定consumer或者将 标签嵌套在标签之中。 + +### provider 与 service的关系 + +service可以指定具体的provider，如果没有指定则会自动使用全局默认的provider配置。 +provider的属性是service属性的默认值，覆盖规则类似上面的consumer与reference，也可以将provider理解为service的虚拟分组。 + + +## 配置来源 + +从Dubbo支持的配置来源说起，默认有6种配置来源： + +- JVM System Properties，JVM -D 参数 +- System environment，JVM进程的环境变量 +- Externalized Configuration，外部化配置，从配置中心读取 +- Application Configuration，应用的属性配置，从Spring应用的Environment中提取"dubbo"打头的属性集 +- API / XML /注解等编程接口采集的配置可以被理解成配置来源的一种，是直接面向用户编程的配置采集方式 +- 从classpath读取配置文件 dubbo.properties + +### 覆盖关系 + +下图展示了配置覆盖关系的优先级，从上到下优先级依次降低： + +![覆盖关系](/imgs/blog/configuration.jpg) + +请参考相关内容：[属性覆盖](../properties#属性覆盖)。 + + +## 配置方式 + +按照驱动方式可以分为以下四种方式： + +### API配置 +以Java编码的方式组织配置，包括Raw API和Bootstrap API，具体请参考[API配置](../api)。 + +### XML配置 +以XML方式配置各种组件，支持与Spring无缝集成，具体请参考[XML配置](../xml)。 + +### Annotation配置 +以注解方式暴露服务和引用服务接口，支持与Spring无缝集成，具体请参考[Annotation配置](../annotation)。 + +### 属性配置 +根据属性Key-value生成配置组件，类似SpringBoot的ConfigurationProperties，具体请参考[属性配置](../properties)。 + +属性配置的另外一个重要的功能特性是[属性覆盖](../properties#属性覆盖)，使用外部属性的值覆盖已创建的配置组件属性。 + +如果要将属性配置放到外部的配置中心，请参考[外部化配置](../external-config)。 + +除了外围驱动方式上的差异，Dubbo的配置读取总体上遵循了以下几个原则： + +1. Dubbo 支持了多层级的配置，并按预定优先级自动实现配置间的覆盖，最终所有配置汇总到数据总线URL后驱动后续的服务暴露、引用等流程。 +2. 配置格式以 Properties 为主，在配置内容上遵循约定的 `path-based` 的[命名规范](../properties#配置格式) + + +## 配置加载流程 + +![配置加载流程](/imgs/v3/config/config-load.svg) + +从上图可以看出，配置加载大概分为两个阶段： + +* 第一阶段为DubboBootstrap初始化之前，在Spring context启动时解析处理XML配置/注解配置/Java-config 或者是执行API配置代码，创建config bean并且加入到ConfigManager中。 +* 第二阶段为DubboBootstrap初始化过程，从配置中心读取外部配置，依次处理实例级属性配置和应用级属性配置，最后刷新所有配置实例的属性，也就是[属性覆盖](../properties#属性覆盖)。 + + +## 几种编程配置方式 + +接下来，我们看一下选择不同的开发方式时，对应到 ServiceConfig、ReferenceConfig 等编程接口采集的配置的变化。 + +#### Spring XML + +> 参见[示例](https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-basic) + +```xml + + + + + + + + + + + +``` + +#### Spring Annotation + +> 参见[示例](https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-annotation) + +```java + // AnnotationService服务实现 + + @Service + 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 + +> 参见[示例](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 + +## DemoService version +demo.service.version=1.0.0 +``` + +#### API + +> 参考[示例](https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-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(); + } +``` + diff --git a/content/zh/docs3-building/java-sdk/reference-manual/config/properties/_index.md b/content/zh/docs3-building/java-sdk/reference-manual/config/properties/_index.md new file mode 100644 index 000000000000..eba4eec50bda --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/config/properties/_index.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "Properties 配置手册" +linkTitle: "Properties 配置手册" +weight: 5 +--- \ No newline at end of file diff --git a/content/zh/docs3-building/java-sdk/reference-manual/config/properties/description.md b/content/zh/docs3-building/java-sdk/reference-manual/config/properties/description.md new file mode 100644 index 000000000000..b82b3289ac85 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/config/properties/description.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "配置项描述" +linkTitle: "配置项描述" +weight: 2 +--- \ No newline at end of file diff --git a/content/zh/docs3-building/java-sdk/reference-manual/config/properties/guide.md b/content/zh/docs3-building/java-sdk/reference-manual/config/properties/guide.md new file mode 100644 index 000000000000..409d5b4899fc --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/config/properties/guide.md @@ -0,0 +1,301 @@ +--- +type: docs +title: "配置指南" +linkTitle: "配置指南" +weight: 1 +description: "以属性配置的方式来配置你的 Dubbo 应用" +--- + +Dubbo属性配置有两个职责： + +1. 定义配置：根据属性创建配置组件实例，类似SpringBoot的`@ConfigurationProperties`的作用。 +2. 属性覆盖：覆盖已存在的配置组件实例的属性值，类似Spring `PropertyOverrideConfigurer` 的作用。 + + +> 一个属性配置的例子 [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 +``` + +## 配置来源 + +从Dubbo支持的配置来源说起，默认有6种配置来源： + +- JVM System Properties，JVM -D 参数 +- System environment，JVM进程的环境变量 +- Externalized Configuration，外部化配置，从配置中心读取 +- Application Configuration，应用的属性配置，从Spring应用的Environment中提取"dubbo"打头的属性集 +- API / XML /注解等编程接口采集的配置可以被理解成配置来源的一种，是直接面向用户编程的配置采集方式 +- 从classpath读取配置文件 dubbo.properties + +关于dubbo.properties属性： + +1. 如果在 classpath 下有超过一个 dubbo.properties 文件，比如，两个 jar 包都各自包含了 dubbo.properties，dubbo 将随机选择一个加载，并且打印错误日志。 +2. Dubbo 可以自动加载 classpath 根目录下的 dubbo.properties，但是你同样可以使用 JVM 参数来指定路径：`-Ddubbo.properties.file=xxx.properties`。 + +### 覆盖关系 + +下图展示了配置覆盖关系的优先级，从上到下优先级依次降低： + +![覆盖关系](/imgs/blog/configuration.jpg) + +请参考相关内容：[属性覆盖](../properties#属性覆盖)。 + +## 处理流程 + +属性配置处理流程请查看 [配置加载流程](../overview#配置加载流程)。 + + +## 配置格式 + +目前Dubbo支持的所有配置都是`.properties`格式的，包括`-D`、`Externalized Configuration`等，`.properties`中的所有配置项遵循一种`path-based`的配置格式。 + +在Spring应用中也可以将属性配置放到`application.yml`中，其树层次结构的方式可读性更好一些。 + +```properties +# 应用级配置（无id） +dubbo.{config-type}.{config-item}={config-item-value} + +# 实例级配置（指定id或name） +dubbo.{config-type}s.{config-id}.{config-item}={config-item-value} +dubbo.{config-type}s.{config-name}.{config-item}={config-item-value} + +# 服务接口配置 +dubbo.service.{interface-name}.{config-item}={config-item-value} +dubbo.reference.{interface-name}.{config-item}={config-item-value} + +# 方法配置 +dubbo.service.{interface-name}.{method-name}.{config-item}={config-item-value} +dubbo.reference.{interface-name}.{method-name}.{config-item}={config-item-value} + +# 方法argument配置 +dubbo.reference.{interface-name}.{method-name}.{argument-index}.{config-item}={config-item-value} + +``` + +### 应用级配置（无id） + +应用级配置的格式为：配置类型单数前缀，无id/name。 +```properties +# 应用级配置（无id） +dubbo.{config-type}.{config-item}={config-item-value} +``` + +* 如果该类型的配置不存在任何实例时，则将使用应用级配置的属性创建默认实例。 +* 如果该类型的配置存在一个或多个实例，且没有找到配置实例对应的配置时，则将应用级配置的属性用于属性覆盖。详细请参考[属性覆盖](../properties#属性覆盖)。 + +```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 +``` + +### 实例级配置（指定id或name） + +针对某个实例的属性配置需要指定id或者name，其前缀格式为：配置类型复数前缀 + id/name。 + +```properties +# 实例级配置（指定id或name） +dubbo.{config-type}s.{config-id}.{config-item}={config-item-value} +dubbo.{config-type}s.{config-name}.{config-item}={config-item-value} + +``` + +* 如果不存在该id或者name的实例，则根据属性创建配置组件实例。 +* 如果已存在相同id或name的实例，则提取该前缀的属性集合用于属性覆盖。详细请参考[属性覆盖](../properties#属性覆盖)。 +* 具体的配置复数形式请参考[单复数配置对照表](../properties#单复数配置对照表) + +```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 +``` + +### 服务接口配置 + +```properties +dubbo.service.org.apache.dubbo.samples.api.DemoService.timeout=5000 +dubbo.reference.org.apache.dubbo.samples.api.DemoService.timeout=6000 +``` + +### 方法配置 + +方法配置格式: + +```properties +# 方法配置 +dubbo.service.{interface-name}.{method-name}.{config-item}={config-item-value} +dubbo.reference.{interface-name}.{method-name}.{config-item}={config-item-value} + +# 方法argument配置 +dubbo.reference.{interface-name}.{method-name}.{argument-index}.{config-item}={config-item-value} +``` + +方法配置示例： +```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 +``` + +等价于XML配置： + +```xml + + + + + +``` + +### 参数配置 + +parameters参数为map对象，支持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}] +``` + +### 传输层配置 + +triple协议采用Http2做底层通信协议，允许使用者自定义Http2的[6个settings参数](https://datatracker.ietf.org/doc/html/rfc7540#section-6.5.2) + +配置格式如下： + +```properties +# 通知对端header压缩索引表的上限个数 +dubbo.rpc.tri.header-table-size=4096 + +# 启用服务端推送功能 +dubbo.rpc.tri.enable-push=false + +# 通知对端允许的最大并发流数 +dubbo.rpc.tri.max-concurrent-streams=2147483647 + +# 声明发送端的窗口大小 +dubbo.rpc.tri.initial-window-size=1048576 + +# 设置帧的最大字节数 +dubbo.rpc.tri.max-frame-size=32768 + +# 通知对端header未压缩的最大字节数 +dubbo.rpc.tri.max-header-list-size=8192 +``` + +等价于yml配置： + +```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 +``` + + + +### 属性与XML配置映射规则 + +可以将 xml 的 tag 名和属性名组合起来，用 ‘.’ 分隔。每行一个属性。 + +* `dubbo.application.name=foo` 相当于 `` +* `dubbo.registry.address=10.20.153.10:9090` 相当于 ` ` + +如果在 xml 配置中有超过一个的 tag，那么你可以使用 ‘id’ 进行区分。如果你不指定id，它将作用于所有 tag。 + +* `dubbo.protocols.rmi.port=1099` 相当于 ` ` +* `dubbo.registries.china.address=10.20.153.10:9090` 相当于 `` + + +## 属性覆盖 + +属性覆盖是指用配置的属性值覆盖config bean实例的属性，类似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 + +但与`PropertyOverrideConfigurer`的不同之处是，Dubbo的属性覆盖有多个匹配格式，优先级从高到低依次是： + +```properties +#1. 指定id的实例级配置 +dubbo.{config-type}s.{config-id}.{config-item}={config-item-value} + +#2. 指定name的实例级配置 +dubbo.{config-type}s.{config-name}.{config-item}={config-item-value} + +#3. 应用级配置（单数配置） +dubbo.{config-type}.{config-item}={config-item-value} +``` + +属性覆盖处理流程： + +按照优先级从高到低依次查找，如果找到此前缀开头的属性，则选定使用这个前缀提取属性，忽略后面的配置。 + +![属性覆盖流程](/imgs/v3/config/properties-override.svg) + + +## 单复数配置对照表 + +复数配置的命名与普通单词变复数的规则相同： + +1. 字母y结尾时，去掉y，改为ies +2. 字母s结尾时，加es +3. 其它加s + +| Config Type | 单数配置 | 复数配置 | +| --------------------------------- | ------------------------------------------------------------ | ----------------------------------- | +| 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 | 无 | +| reference | dubbo.reference.{interfaceName}.xxx=xxx | 无 | +| method | dubbo.service.{interfaceName}.{methodName}.xxx=xxx
dubbo.reference.{interfaceName}.{methodName}.xxx=xxx | 无 | +| argument | dubbo.service.{interfaceName}.{methodName}.{arg-index}.xxx=xxx | 无 | + diff --git a/content/zh/docs3-building/java-sdk/reference-manual/config/xml/_index.md b/content/zh/docs3-building/java-sdk/reference-manual/config/xml/_index.md new file mode 100644 index 000000000000..80f68ebbe012 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/config/xml/_index.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "XML 配置手册" +linkTitle: "XML 配置手册" +weight: 2 +--- \ No newline at end of file diff --git a/content/zh/docs3-building/java-sdk/reference-manual/config/xml/description.md b/content/zh/docs3-building/java-sdk/reference-manual/config/xml/description.md new file mode 100644 index 000000000000..071c24975dce --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/config/xml/description.md @@ -0,0 +1,349 @@ +--- +type: docs +title: "配置项描述" +linkTitle: "配置项描述" +weight: 2 +--- + + +# dubbo:application + +应用信息配置。对应的配置类：`org.apache.dubbo.config.ApplicationConfig` + +| 属性 | 对应URL参数 | 类型 | 是否必填 | 缺省值 | 作用 | 描述 | 兼容性 | +| --- | --- | ---- | --- | --- | --- | --- | --- | +| name | application | string | 必填 | | 服务治理 | 当前应用名称，用于注册中心计算应用间依赖关系，注意：消费者和提供者应用名不要一样，此参数不是匹配条件，你当前项目叫什么名字就填什么，和提供者消费者角色无关，比如：kylin应用调用了morgan应用的服务，则kylin项目配成kylin，morgan项目配成morgan，可能kylin也提供其它服务给别人使用，但kylin项目永远配成kylin，这样注册中心将显示kylin依赖于morgan | 1.0.16以上版本 | +| version | application.version | string | 可选 | | 服务治理 | 当前应用的版本 | 2.2.0以上版本 | +| owner | owner | string | 可选 | | 服务治理 | 应用负责人，用于服务治理，请填写负责人公司邮箱前缀 | 2.0.5以上版本 | +| organization | organization | string | 可选 | | 服务治理 | 组织名称(BU或部门)，用于注册中心区分服务来源，此配置项建议不要使用autoconfig，直接写死在配置中，比如china,intl,itu,crm,asc,dw,aliexpress等 | 2.0.0以上版本 | +| architecture
| architecture
| string | 可选 | | 服务治理 | 用于服务分层对应的架构。如，intl、china。不同的架构使用不同的分层。 | 2.0.7以上版本 | +| environment | environment | string | 可选 | | 服务治理 | 应用环境，如：develop/test/product，不同环境使用不同的缺省值，以及作为只用于开发测试功能的限制条件 | 2.0.0以上版本 | +| compiler | compiler | string | 可选 | javassist | 性能优化 | Java字节码编译器，用于动态类的生成，可选：jdk或javassist | 2.1.0以上版本 | +| logger | logger | string | 可选 | slf4j | 性能优化 | 日志输出方式，可选：slf4j,jcl,log4j,log4j2,jdk | 2.2.0以上版本 | +| metadata-type | metadata-type |String| 可选 | local | 服务治理 | metadata 传递方式，是以 Provider 视角而言的，Consumer 侧配置无效，可选值有：
remote - Provider 把 metadata 放到远端注册中心，Consumer 从注册中心获取
local - Provider 把 metadata 放在本地，Consumer 从 Provider 处直接获取| 2.7.6以上版本 | + + +# dubbo:argument + +方法参数配置。对应的配置类： `org.apache.dubbo.config.ArgumentConfig`。该标签为 `` 的子标签，用于方法参数的特征描述，比如： + +```xml + + + +``` +| 属性 | 对应URL参数 | 类型 | 是否必填 | 缺省值 | 作用 | 描述 | 兼容性 | +| --- | --- | ---- | --- | --- | --- | --- | --- | +| index | | int | 必填 | | 标识 | 参数索引 | 2.0.6以上版本 | +| type | | String | 与index二选一 | | 标识 | 通过参数类型查找参数的index | 2.0.6以上版本 | +| callback | <metodName><index>.retries | boolean | 可选 | | 服务治理 | 参数是否为callback接口，如果为callback，服务提供方将生成反向代理，可以从服务提供方反向调用消费方，通常用于事件推送. | 2.0.6以上版本 | + + +# dubbo:config-center + +配置中心。对应的配置类：`org.apache.dubbo.config.ConfigCenterConfig` + +| 属性 | 对应URL参数 | 类型 | 是否必填 | 缺省值 | 描述 | 兼容性 | +| ---------------- | ---------------------- | ------------------- | -------- | ---------------- | ------------------------------------------------------------ | ------ | +| protocol | config.protocol | string | 可选 | zookeeper | 使用哪个配置中心：apollo、zookeeper、nacos等。
以zookeeper为例
1. 指定protocol，则address可以简化为`127.0.0.1:2181`；
2. 不指定protocol，则address取值为`zookeeper://127.0.0.1:2181` | 2.7.0+ | +| address | config.address | string | 必填 | | 配置中心地址。
取值参见protocol说明 | 2.7.0+ | +| highest-priority | config.highestPriority | boolean | 可选 | true | 来自配置中心的配置项具有最高优先级，即会覆盖本地配置项。 | 2.7.0+ | +| namespace | config.namespace | string | 可选 | dubbo | 通常用于多租户隔离，实际含义视具体配置中心而不同。
如：
zookeeper - 环境隔离，默认值`dubbo`；
apollo - 区分不同领域的配置集合，默认使用`dubbo`和`application` | 2.7.0+ | +| cluster | config.cluster | string | 可选 | | 含义视所选定的配置中心而不同。
如Apollo中用来区分不同的配置集群 | 2.7.0+ | +| group | config.group | string | 可选 | dubbo | 含义视所选定的配置中心而不同。
nacos - 隔离不同配置集
zookeeper - 隔离不同配置集 | 2.7.0+ | +| check | config.check | boolean | 可选 | true | 当配置中心连接失败时，是否终止应用启动。 | 2.7.0+ | +| config-file | config.configFile | string | 可选 | dubbo.properties | 全局级配置文件所映射到的key
zookeeper - 默认路径/dubbo/config/dubbo/dubbo.properties
apollo - dubbo namespace中的dubbo.properties键 | 2.7.0+ | +| timeout | config.timeout | integer | | 3000ms | 获取配置的超时时间 | 2.7.0+ | +| username | | string | | | 如果配置中心需要做校验，用户名
Apollo暂未启用 | 2.7.0+ | +| password | | string | | | 如果配置中心需要做校验，密码
Apollo暂未启用 | 2.7.0+ | +| parameters | | Map | | | 扩展参数，用来支持不同配置中心的定制化配置参数 | 2.7.0+ | +| include-spring-env | | boolean | 可选 | false | 使用Spring框架时支持，为true时，会自动从Spring Environment中读取配置。
默认依次读取
key为dubbo.properties的配置
key为dubbo.properties的PropertySource | 2.7.0+ | + + +# dubbo:consumer + +服务消费者缺省值配置。配置类： `org.apache.dubbo.config.ConsumerConfig` 。同时该标签为 `` 标签的缺省值设置。 + +| 属性 | 对应URL参数 | 类型 | 是否必填 | 缺省值 | 作用 | 描述 | 兼容性 | +| --- | --- | ---- | --- | --- | --- | --- | --- | +| timeout | default.timeout | int | 可选 | 1000 | 性能调优 | 远程服务调用超时时间(毫秒) | 1.0.16以上版本 | +| retries | default.retries | int | 可选 | 2 | 性能调优 | 远程服务调用重试次数，不包括第一次调用，不需要重试请设为0,仅在cluster为failback/failover时有效 | 1.0.16以上版本 | +| loadbalance | default.loadbalance | string | 可选 | random | 性能调优 | 负载均衡策略，可选值：random,roundrobin,leastactive，分别表示：随机，轮询，最少活跃调用 | 1.0.16以上版本 | +| async | default.async | boolean | 可选 | false | 性能调优 | 是否缺省异步执行，不可靠异步，只是忽略返回值，不阻塞执行线程 | 2.0.0以上版本 | +| connections | default.connections | int | 可选 | 100 | 性能调优 | 每个服务对每个提供者的最大连接数，rmi、http、hessian等短连接协议支持此配置，dubbo协议长连接不支持此配置 | 1.0.16以上版本 | +| generic | generic | boolean | 可选 | false | 服务治理 | 是否缺省泛化接口，如果为泛化接口，将返回GenericService | 2.0.0以上版本 | +| check | check | boolean | 可选 | true | 服务治理 | 启动时检查提供者是否存在，true报错，false忽略 | 1.0.16以上版本 | +| proxy | proxy | string | 可选 | javassist | 性能调优 | 生成动态代理方式，可选：jdk/javassist | 2.0.5以上版本 | +| owner | owner | string | 可选 | | 服务治理 | 调用服务负责人，用于服务治理，请填写负责人公司邮箱前缀 | 2.0.5以上版本 | +| actives | default.actives | int | 可选 | 0 | 性能调优 | 每服务消费者每服务每方法最大并发调用数 | 2.0.5以上版本 | +| cluster | default.cluster | string | 可选 | failover | 性能调优 | 集群方式，可选：failover/failfast/failsafe/failback/forking | 2.0.5以上版本 | +| filter | reference.filter | string | 可选 | | 性能调优 | 服务消费方远程调用过程拦截器名称，多个名称用逗号分隔 | 2.0.5以上版本 | +| listener | invoker.listener | string | 可选 | | 性能调优 | 服务消费方引用服务监听器名称，多个名称用逗号分隔 | 2.0.5以上版本 | +| registry | | string | 可选 | 缺省向所有registry注册 | 配置关联 | 向指定注册中心注册，在多个注册中心时使用，值为<dubbo:registry>的id属性，多个注册中心ID用逗号分隔，如果不想将该服务注册到任何registry，可将值设为N/A | 2.0.5以上版本 | +| layer | layer | string | 可选 | | 服务治理 | 服务调用者所在的分层。如：biz、dao、intl:web、china:acton。 | 2.0.7以上版本 | +| init | init | boolean | 可选 | false | 性能调优 | 是否在afterPropertiesSet()时饥饿初始化引用，否则等到有人注入或引用该实例时再初始化。 | 2.0.10以上版本 | +| cache | cache | string/boolean | 可选 | | 服务治理 | 以调用参数为key，缓存返回结果，可选：lru, threadlocal, jcache等 | Dubbo2.1.0及其以上版本支持 | +| validation | validation | boolean | 可选 | | 服务治理 | 是否启用JSR303标准注解验证，如果启用，将对方法参数上的注解进行校验 | Dubbo2.1.0及其以上版本支持 | +| version | version | string | 可选 | | 服务治理 | 在 Dubbo 中为同一个服务配置多个版本 | Dubbo2.2.0及其以上版本支持 | + +# dubbo:method + +方法级配置。对应的配置类： `org.apache.dubbo.config.MethodConfig`。同时该标签为 `` 或 `` 的子标签，用于控制到方法级。 + +| 属性 | 对应URL参数 | 类型 | 是否必填 | 缺省值 | 作用 | 描述 | 兼容性 | +| --- | --- | ---- | --- | --- | --- | --- | --- | +| name | | string | 必填 | | 标识 | 方法名 | 1.0.8以上版本 | +| timeout | <methodName>.timeout | int | 可选 | 缺省为的timeout | 性能调优 | 方法调用超时时间(毫秒) | 1.0.8以上版本 | +| retries | <methodName>.retries | int | 可选 | 缺省为<dubbo:reference>的retries | 性能调优 | 远程服务调用重试次数，不包括第一次调用，不需要重试请设为0 | 2.0.0以上版本 | +| loadbalance | <methodName>.loadbalance | string | 可选 | 缺省为的loadbalance | 性能调优 | 负载均衡策略，可选值：random,roundrobin,leastactive，分别表示：随机，轮询，最少活跃调用 | 2.0.0以上版本 | +| async | <methodName>.async | boolean | 可选 | 缺省为<dubbo:reference>的async | 性能调优 | 是否异步执行，不可靠异步，只是忽略返回值，不阻塞执行线程 | 1.0.9以上版本 | +| sent | <methodName>.sent | boolean | 可选 | true | 性能调优 | 异步调用时，标记sent=true时，表示网络已发出数据 | 2.0.6以上版本 | +| actives | <methodName>.actives | int | 可选 | 0 | 性能调优 | 每服务消费者最大并发调用限制 | 2.0.5以上版本 | +| executes | <methodName>.executes | int | 可选 | 0 | 性能调优 | 每服务每方法最大使用线程数限制- -，此属性只在<dubbo:method>作为<dubbo:service>子标签时有效 | 2.0.5以上版本 | +| deprecated | <methodName>.deprecated | boolean | 可选 | false | 服务治理 | 服务方法是否过时，此属性只在<dubbo:method>作为<dubbo:service>子标签时有效 | 2.0.5以上版本 | +| sticky | <methodName>.sticky | boolean | 可选 | false | 服务治理 | 设置true 该接口上的所有方法使用同一个provider.如果需要更复杂的规则，请使用路由 | 2.0.6以上版本 | +| return | <methodName>.return | boolean | 可选 | true | 性能调优 | 方法调用是否需要返回值,async设置为true时才生效，如果设置为true，则返回future，或回调onreturn等方法，如果设置为false，则请求发送成功后直接返回Null | 2.0.6以上版本 | +| oninvoke | attribute属性，不在URL中体现 | String | 可选 | | 性能调优 | 方法执行前拦截 | 2.0.6以上版本 | +| onreturn | attribute属性，不在URL中体现 | String | 可选 | | 性能调优 | 方法执行返回后拦截 | 2.0.6以上版本 | +| onthrow | attribute属性，不在URL中体现 | String | 可选 | | 性能调优 | 方法执行有异常拦截 | 2.0.6以上版本 | +| cache | <methodName>.cache | string/boolean | 可选 | | 服务治理 | 以调用参数为key，缓存返回结果，可选：lru, threadlocal, jcache等 | Dubbo2.1.0及其以上版本支持 | +| validation | <methodName>.validation | boolean | 可选 | | 服务治理 | 是否启用JSR303标准注解验证，如果启用，将对方法参数上的注解进行校验 | Dubbo2.1.0及其以上版本支持 | + +比如: + +```xml + + + +``` + +# dubbo:module + +模块信息配置。对应的配置类 `org.apache.dubbo.config.ModuleConfig` + +| 属性 | 对应URL参数 | 类型 | 是否必填 | 缺省值 | 作用 | 描述 | 兼容性 | +| --- | --- | ---- | --- | --- | --- | --- | --- | +| name | module | string | 必填 | | 服务治理 | 当前模块名称，用于注册中心计算模块间依赖关系 | 2.2.0以上版本 | +| version | module.version | string | 可选 | | 服务治理 | 当前模块的版本 | 2.2.0以上版本 | +| owner | owner | string | 可选 | | 服务治理 | 模块负责人，用于服务治理，请填写负责人公司邮箱前缀 | 2.2.0以上版本 | +| organization | organization | string | 可选 | | 服务治理 | 组织名称(BU或部门)，用于注册中心区分服务来源，此配置项建议不要使用autoconfig，直接写死在配置中，比如china,intl,itu,crm,asc,dw,aliexpress等 | 2.2.0以上版本 | + + +# dubbo:monitor + +监控中心配置。对应的配置类： `org.apache.dubbo.config.MonitorConfig` + +| 属性 | 对应URL参数 | 类型 | 是否必填 | 缺省值 | 作用 | 描述 | 兼容性 | +| --- | --- | ---- | --- | --- | --- | --- | --- | +| protocol | protocol | string | 可选 | dubbo | 服务治理 | 监控中心协议，如果为protocol="registry"，表示从注册中心发现监控中心地址，否则直连监控中心。 | 2.0.9以上版本 | +| address | <url> | string | 可选 | N/A | 服务治理 | 直连监控中心服务器地址，address="10.20.130.230:12080" | 1.0.16以上版本 | + + +# dubbo:parameter + +选项参数配置。对应的配置类：`java.util.Map`。同时该标签为``或``或``或``或``的子标签，用于配置自定义参数，该配置项将作为扩展点设置自定义参数使用。 + +| 属性 | 对应URL参数 | 类型 | 是否必填 | 缺省值 | 作用 | 描述 | 兼容性 | +| --- | --- | ---- | --- | --- | --- | --- | --- | +| key | key | string | 必填 | | 服务治理 | 路由参数键 | 2.0.0以上版本 | +| value | value | string | 必填 | | 服务治理 | 路由参数值 | 2.0.0以上版本 | + +比如： + +```xml + + + +``` + +也可以： + +```xml + +``` + +# dubbo:protocol + + +服务提供者协议配置。对应的配置类： `org.apache.dubbo.config.ProtocolConfig`。同时，如果需要支持多协议，可以声明多个 `` 标签，并在 `` 中通过 `protocol` 属性指定使用的协议。 + +| 属性 | 对应URL参数 | 类型 | 是否必填 | 缺省值 | 作用 | 描述 | 兼容性 | +| --- | --- | ---- | --- | --- | --- | --- | --- | +| id | | string | 可选 | dubbo | 配置关联 | 协议BeanId，可以在<dubbo:service protocol="">中引用此ID，如果ID不填，缺省和name属性值一样，重复则在name后加序号。 | 2.0.5以上版本 | +| name | <protocol> | string | 必填 | dubbo | 性能调优 | 协议名称 | 2.0.5以上版本 | +| port | <port> | int | 可选 | dubbo协议缺省端口为20880，rmi协议缺省端口为1099，http和hessian协议缺省端口为80；如果没有配置port，则自动采用默认端口，如果配置为-1，则会分配一个没有被占用的端口。Dubbo 2.4.0+，分配的端口在协议缺省端口的基础上增长，确保端口段可控。 | 服务发现 | 服务端口 | 2.0.5以上版本 | +| host | <host> | string | 可选 | 自动查找本机IP | 服务发现 | -服务主机名，多网卡选择或指定VIP及域名时使用，为空则自动查找本机IP，-建议不要配置，让Dubbo自动获取本机IP | 2.0.5以上版本 | +| threadpool | threadpool | string | 可选 | fixed | 性能调优 | 线程池类型，可选：fixed/cached | 2.0.5以上版本 | +| threads | threads | int | 可选 | 200 | 性能调优 | 服务线程池大小(固定大小) | 2.0.5以上版本 | +| iothreads | threads | int | 可选 | cpu个数+1 | 性能调优 | io线程池大小(固定大小) | 2.0.5以上版本 | +| accepts | accepts | int | 可选 | 0 | 性能调优 | 服务提供方最大可接受连接数 | 2.0.5以上版本 | +| payload | payload | int | 可选 | 8388608(=8M) | 性能调优 | 请求及响应数据包大小限制，单位：字节 | 2.0.5以上版本 | +| codec | codec | string | 可选 | dubbo | 性能调优 | 协议编码方式 | 2.0.5以上版本 | +| serialization | serialization | string | 可选 | dubbo协议缺省为hessian2，rmi协议缺省为java，http协议缺省为json | 性能调优 | 协议序列化方式，当协议支持多种序列化方式时使用，比如：dubbo协议的dubbo,hessian2,java,compactedjava，以及http协议的json等 | 2.0.5以上版本 | +| accesslog | accesslog | string/boolean | 可选 | | 服务治理 | 设为true，将向logger中输出访问日志，也可填写访问日志文件路径，直接把访问日志输出到指定文件 | 2.0.5以上版本 | +| path | <path> | string | 可选 | | 服务发现 | 提供者上下文路径，为服务path的前缀 | 2.0.5以上版本 | +| transporter | transporter | string | 可选 | dubbo协议缺省为netty | 性能调优 | 协议的服务端和客户端实现类型，比如：dubbo协议的mina,netty等，可以分拆为server和client配置 | 2.0.5以上版本 | +| server | server | string | 可选 | dubbo协议缺省为netty，http协议缺省为servlet | 性能调优 | 协议的服务器端实现类型，比如：dubbo协议的mina,netty等，http协议的jetty,servlet等 | 2.0.5以上版本 | +| client | client | string | 可选 | dubbo协议缺省为netty | 性能调优 | 协议的客户端实现类型，比如：dubbo协议的mina,netty等 | 2.0.5以上版本 | +| dispatcher | dispatcher | string | 可选 | dubbo协议缺省为all | 性能调优 | 协议的消息派发方式，用于指定线程模型，比如：dubbo协议的all, direct, message, execution, connection等 | 2.1.0以上版本 | +| queues | queues | int | 可选 | 0 | 性能调优 | 线程池队列大小，当线程池满时，排队等待执行的队列大小，建议不要设置，当线程池满时应立即失败，重试其它服务提供机器，而不是排队，除非有特殊需求。 | 2.0.5以上版本 | +| charset | charset | string | 可选 | UTF-8 | 性能调优 | 序列化编码 | 2.0.5以上版本 | +| buffer | buffer | int | 可选 | 8192 | 性能调优 | 网络读写缓冲区大小 | 2.0.5以上版本 | +| heartbeat | heartbeat | int | 可选 | 0 | 性能调优 | 心跳间隔，对于长连接，当物理层断开时，比如拔网线，TCP的FIN消息来不及发送，对方收不到断开事件，此时需要心跳来帮助检查连接是否已断开 | 2.0.10以上版本 | +| telnet | telnet | string | 可选 | | 服务治理 | 所支持的telnet命令，多个命令用逗号分隔 | 2.0.5以上版本 | +| register | register | boolean | 可选 | true | 服务治理 | 该协议的服务是否注册到注册中心 | 2.0.8以上版本 | +| contextpath | contextpath | String | 可选 | 缺省为空串 | 服务治理 | | 2.0.6以上版本 | + + +# dubbo:provider + + +服务提供者缺省值配置。对应的配置类： `org.apache.dubbo.config.ProviderConfig`。同时该标签为 `` 和 `` 标签的缺省值设置。 + +| 属性 | 对应URL参数 | 类型 | 是否必填 | 缺省值 | 作用 | 描述 | 兼容性 | +| --- | --- | ---- | --- | --- | --- | --- | --- | +| id | | string | 可选 | dubbo | 配置关联 | 协议BeanId，可以在<dubbo:service proivder="">中引用此ID | 1.0.16以上版本 | +| protocol | <protocol> | string | 可选 | dubbo | 性能调优 | 协议名称 | 1.0.16以上版本 | +| host | <host> | string | 可选 | 自动查找本机IP | 服务发现 | 服务主机名，多网卡选择或指定VIP及域名时使用，为空则自动查找本机IP，建议不要配置，让Dubbo自动获取本机IP | 1.0.16以上版本 | +| threads | threads | int | 可选 | 200 | 性能调优 | 服务线程池大小(固定大小) | 1.0.16以上版本 | +| payload | payload | int | 可选 | 8388608(=8M) | 性能调优 | 请求及响应数据包大小限制，单位：字节 | 2.0.0以上版本 | +| path | <path> | string | 可选 | | 服务发现 | 提供者上下文路径，为服务path的前缀 | 2.0.0以上版本 | +| server | server | string | 可选 | dubbo协议缺省为netty，http协议缺省为servlet | 性能调优 | 协议的服务器端实现类型，比如：dubbo协议的mina,netty等，http协议的jetty,servlet等 | 2.0.0以上版本 | +| client | client | string | 可选 | dubbo协议缺省为netty | 性能调优 | 协议的客户端实现类型，比如：dubbo协议的mina,netty等 | 2.0.0以上版本 | +| codec | codec | string | 可选 | dubbo | 性能调优 | 协议编码方式 | 2.0.0以上版本 | +| serialization | serialization | string | 可选 | dubbo协议缺省为hessian2，rmi协议缺省为java，http协议缺省为json | 性能调优 | 协议序列化方式，当协议支持多种序列化方式时使用，比如：dubbo协议的dubbo,hessian2,java,compactedjava，以及http协议的json,xml等 | 2.0.5以上版本 | +| default | | boolean | 可选 | false | 配置关联 | 是否为缺省协议，用于多协议 | 1.0.16以上版本 | +| filter | service.filter | string | 可选 | | 性能调优 | 服务提供方远程调用过程拦截器名称，多个名称用逗号分隔 | 2.0.5以上版本 | +| listener | exporter.listener | string | 可选 | | 性能调优 | 服务提供方导出服务监听器名称，多个名称用逗号分隔 | 2.0.5以上版本 | +| threadpool | threadpool | string | 可选 | fixed | 性能调优 | 线程池类型，可选：fixed/cached/limit(2.5.3以上)/eager(2.6.x以上) | 2.0.5以上版本 | +| accepts | accepts | int | 可选 | 0 | 性能调优 | 服务提供者最大可接受连接数 | 2.0.5以上版本 | +| version | version | string | 可选 | 0.0.0 | 服务发现 | 服务版本，建议使用两位数字版本，如：1.0，通常在接口不兼容时版本号才需要升级 | 2.0.5以上版本 | +| group | group | string | 可选 | | 服务发现 | 服务分组，当一个接口有多个实现，可以用分组区分 | 2.0.5以上版本 | +| delay | delay | int | 可选 | 0 | 性能调优 | 延迟注册服务时间(毫秒)- ，设为-1时，表示延迟到Spring容器初始化完成时暴露服务 | 2.0.5以上版本 | +| timeout | default.timeout | int | 可选 | 1000 | 性能调优 | 远程服务调用超时时间(毫秒) | 2.0.5以上版本 | +| retries | default.retries | int | 可选 | 2 | 性能调优 | 远程服务调用重试次数，不包括第一次调用，不需要重试请设为0 | 2.0.5以上版本 | +| connections | default.connections | int | 可选 | 0 | 性能调优 | 对每个提供者的最大连接数，rmi、http、hessian等短连接协议表示限制连接数，dubbo等长连接协表示建立的长连接个数 | 2.0.5以上版本 | +| loadbalance | default.loadbalance | string | 可选 | random | 性能调优 | 负载均衡策略，可选值：random,roundrobin,leastactive，分别表示：随机，轮询，最少活跃调用 | 2.0.5以上版本 | +| async | default.async | boolean | 可选 | false | 性能调优 | 是否缺省异步执行，不可靠异步，只是忽略返回值，不阻塞执行线程 | 2.0.5以上版本 | +| stub | stub | boolean | 可选 | false | 服务治理 | 设为true，表示使用缺省代理类名，即：接口名 + Local后缀。 | 2.0.5以上版本 | +| mock | mock | boolean | 可选 | false | 服务治理 | 设为true，表示使用缺省Mock类名，即：接口名 + Mock后缀。 | 2.0.5以上版本 | +| token | token | boolean | 可选 | false | 服务治理 | 令牌验证，为空表示不开启，如果为true，表示随机生成动态令牌 | 2.0.5以上版本 | +| registry | registry | string | 可选 | 缺省向所有registry注册 | 配置关联 | 向指定注册中心注册，在多个注册中心时使用，值为<dubbo:registry>的id属性，多个注册中心ID用逗号分隔，如果不想将该服务注册到任何registry，可将值设为N/A | 2.0.5以上版本 | +| dynamic | dynamic | boolean | 可选 | true | 服务治理 | 服务是否动态注册，如果设为false，注册后将显示后disable状态，需人工启用，并且服务提供者停止时，也不会自动取消册，需人工禁用。 | 2.0.5以上版本 | +| accesslog | accesslog | string/boolean | 可选 | false | 服务治理 | 设为true，将向logger中输出访问日志，也可填写访问日志文件路径，直接把访问日志输出到指定文件 | 2.0.5以上版本 | +| owner | owner | string | 可选 | | 服务治理 | 服务负责人，用于服务治理，请填写负责人公司邮箱前缀 | 2.0.5以上版本 | +| document | document | string | 可选 | | 服务治理 | 服务文档URL | 2.0.5以上版本 | +| weight | weight | int | 可选 | | 性能调优 | 服务权重 | 2.0.5以上版本 | +| executes | executes | int | 可选 | 0 | 性能调优 | 服务提供者每服务每方法最大可并行执行请求数 | 2.0.5以上版本 | +| actives | default.actives | int | 可选 | 0 | 性能调优 | 每服务消费者每服务每方法最大并发调用数 | 2.0.5以上版本 | +| proxy | proxy | string | 可选 | javassist | 性能调优 | 生成动态代理方式，可选：jdk/javassist | 2.0.5以上版本 | +| cluster | default.cluster | string | 可选 | failover | 性能调优 | 集群方式，可选：failover/failfast/failsafe/failback/forking | 2.0.5以上版本 | +| deprecated | deprecated | boolean | 可选 | false | 服务治理 | 服务是否过时，如果设为true，消费方引用时将打印服务过时警告error日志 | 2.0.5以上版本 | +| queues | queues | int | 可选 | 0 | 性能调优 | 线程池队列大小，当线程池满时，排队等待执行的队列大小，建议不要设置，当线程池满时应立即失败，重试其它服务提供机器，而不是排队，除非有特殊需求。 | 2.0.5以上版本 | +| charset | charset | string | 可选 | UTF-8 | 性能调优 | 序列化编码 | 2.0.5以上版本 | +| buffer | buffer | int | 可选 | 8192 | 性能调优 | 网络读写缓冲区大小 | 2.0.5以上版本 | +| iothreads | iothreads | int | 可选 | CPU + 1 | 性能调优 | IO线程池，接收网络读写中断，以及序列化和反序列化，不处理业务，业务线程池参见threads配置，此线程池和CPU相关，不建议配置。 | 2.0.5以上版本 | +| telnet | telnet | string | 可选 | | 服务治理 | 所支持的telnet命令，多个命令用逗号分隔 | 2.0.5以上版本 | +| <dubbo:service> | contextpath | contextpath | String | 可选 | 缺省为空串 | 服务治理 | | 2.0.6以上版本 | +| layer | layer | string | 可选 | | 服务治理 | 服务提供者所在的分层。如：biz、dao、intl:web、china:acton。 | 2.0.7以上版本 | + + +# dubbo:reference + + +服务消费者引用服务配置。对应的配置类： `org.apache.dubbo.config.ReferenceConfig` + +| 属性 | 对应URL参数 | 类型 | 是否必填 | 缺省值 | 作用 | 描述 | 兼容性 | +| --- | --- | ---- | --- | --- | --- | --- | --- | +| id | | string | 必填 | | 配置关联 | 服务引用BeanId | 1.0.0以上版本 | +| interface | | class | 必填 | | 服务发现 | 服务接口名 | 1.0.0以上版本 | +| version | version | string | 可选 | | 服务发现 | 服务版本，与服务提供者的版本一致 | 1.0.0以上版本 | +| group | group | string | 可选 | | 服务发现 | 服务分组，当一个接口有多个实现，可以用分组区分，必需和服务提供方一致 | 1.0.7以上版本 | +| timeout | timeout | long | 可选 | 缺省使用<dubbo:consumer>的timeout | 性能调优 | 服务方法调用超时时间(毫秒) | 1.0.5以上版本 | +| retries | retries | int | 可选 | 缺省使用<dubbo:consumer>的retries | 性能调优 | 远程服务调用重试次数，不包括第一次调用，不需要重试请设为0 | 2.0.0以上版本 | +| connections | connections | int | 可选 | 缺省使用<dubbo:consumer>的connections | 性能调优 | 对每个提供者的最大连接数，rmi、http、hessian等短连接协议表示限制连接数，dubbo等长连接协表示建立的长连接个数 | 2.0.0以上版本 | +| loadbalance | loadbalance | string | 可选 | 缺省使用<dubbo:consumer>的loadbalance | 性能调优 | 负载均衡策略，可选值：random,roundrobin,leastactive，分别表示：随机，轮询，最少活跃调用 | 2.0.0以上版本 | +| async | async | boolean | 可选 | 缺省使用<dubbo:consumer>的async | 性能调优 | 是否异步执行，不可靠异步，只是忽略返回值，不阻塞执行线程 | 2.0.0以上版本 | +| generic | generic | boolean | 可选 | 缺省使用<dubbo:consumer>的generic | 服务治理 | 是否缺省泛化接口，如果为泛化接口，将返回GenericService | 2.0.0以上版本 | +| check | check | boolean | 可选 | 缺省使用<dubbo:consumer>的check | 服务治理 | 启动时检查提供者是否存在，true报错，false忽略 | 2.0.0以上版本 | +| url | url | string | 可选 | | 服务治理 | 点对点直连服务提供者地址，将绕过注册中心 | 1.0.6以上版本 | +| stub | stub | class/boolean | 可选 | | 服务治理 | 服务接口客户端本地代理类名，用于在客户端执行本地逻辑，如本地缓存等，该本地代理类的构造函数必须允许传入远程代理对象，构造函数如：public XxxServiceLocal(XxxService xxxService) | 2.0.0以上版本 | +| mock | mock | class/boolean | 可选 | | 服务治理 | 服务接口调用失败Mock实现类名，该Mock类必须有一个无参构造函数，与Local的区别在于，Local总是被执行，而Mock只在出现非业务异常(比如超时，网络异常等)时执行，Local在远程调用之前执行，Mock在远程调用后执行。 | Dubbo1.0.13及其以上版本支持 | +| cache | cache | string/boolean | 可选 | | 服务治理 | 以调用参数为key，缓存返回结果，可选：lru, threadlocal, jcache等 | Dubbo2.1.0及其以上版本支持 | +| validation | validation | boolean | 可选 | | 服务治理 | 是否启用JSR303标准注解验证，如果启用，将对方法参数上的注解进行校验 | Dubbo2.1.0及其以上版本支持 | +| proxy | proxy | boolean | 可选 | javassist | 性能调优 | 选择动态代理实现策略，可选：javassist, jdk | 2.0.2以上版本 | +| client | client | string | 可选 | | 性能调优 | 客户端传输类型设置，如Dubbo协议的netty或mina。 | Dubbo2.0.0以上版本支持 | +| registry | | string | 可选 | 缺省将从所有注册中心获服务列表后合并结果 | 配置关联 | 从指定注册中心注册获取服务列表，在多个注册中心时使用，值为<dubbo:registry>的id属性，多个注册中心ID用逗号分隔 | 2.0.0以上版本 | +| owner | owner | string | 可选 | | 服务治理 | 调用服务负责人，用于服务治理，请填写负责人公司邮箱前缀 | 2.0.5以上版本 | +| actives | actives | int | 可选 | 0 | 性能调优 | 每服务消费者每服务每方法最大并发调用数 | 2.0.5以上版本 | +| cluster | cluster | string | 可选 | failover | 性能调优 | 集群方式，可选：failover/failfast/failsafe/failback/forking | 2.0.5以上版本 | +| filter | reference.filter | string | 可选 | default | 性能调优 | 服务消费方远程调用过程拦截器名称，多个名称用逗号分隔 | 2.0.5以上版本 | +| listener | invoker.listener | string | 可选 | default | 性能调优 | 服务消费方引用服务监听器名称，多个名称用逗号分隔 | 2.0.5以上版本 | +| layer | layer | string | 可选 | | 服务治理 | 服务调用者所在的分层。如：biz、dao、intl:web、china:acton。 | 2.0.7以上版本 | +| init | init | boolean | 可选 | false | 性能调优 | 是否在afterPropertiesSet()时饥饿初始化引用，否则等到有人注入或引用该实例时再初始化。 | 2.0.10以上版本 | +| protocol | protocol | string | 可选 | | 服务治理 | 只调用指定协议的服务提供方，其它协议忽略。 | 2.2.0以上版本 | + + +# dubbo:registry + + +注册中心配置。对应的配置类： `org.apache.dubbo.config.RegistryConfig`。同时如果有多个不同的注册中心，可以声明多个 `` 标签，并在 `` 或 `` 的 `registry` 属性指定使用的注册中心。 + +| 属性 | 对应URL参数 | 类型 | 是否必填 | 缺省值 | 作用 | 描述 | 兼容性 | +| --- | --- | ---- | --- | --- | --- | --- | --- | +| id | | string | 可选 | | 配置关联 | 注册中心引用BeanId，可以在<dubbo:service registry="">或<dubbo:reference registry="">中引用此ID | 1.0.16以上版本 | +| address | <host:port> | string | 必填 | | 服务发现 | 注册中心服务器地址，如果地址没有端口缺省为9090，同一集群内的多个地址用逗号分隔，如：ip:port,ip:port，不同集群的注册中心，请配置多个<dubbo:registry>标签 | 1.0.16以上版本 | +| protocol | <protocol> | string | 可选 | dubbo | 服务发现 | 注册中心地址协议，支持`dubbo`, `multicast`, `zookeeper`, `redis`, `consul(2.7.1)`, `sofa(2.7.2)`, `etcd(2.7.2)`, `nacos(2.7.2)`等协议 | 2.0.0以上版本 | +| port | <port> | int | 可选 | 9090 | 服务发现 | 注册中心缺省端口，当address没有带端口时使用此端口做为缺省值 | 2.0.0以上版本 | +| username | <username> | string | 可选 | | 服务治理 | 登录注册中心用户名，如果注册中心不需要验证可不填 | 2.0.0以上版本 | +| password | <password> | string | 可选 | | 服务治理 | 登录注册中心密码，如果注册中心不需要验证可不填 | 2.0.0以上版本 | +| transport | registry.transporter | string | 可选 | netty | 性能调优 | 网络传输方式，可选mina,netty | 2.0.0以上版本 | +| timeout | registry.timeout | int | 可选 | 5000 | 性能调优 | 注册中心请求超时时间(毫秒) | 2.0.0以上版本 | +| session | registry.session | int | 可选 | 60000 | 性能调优 | 注册中心会话超时时间(毫秒)，用于检测提供者非正常断线后的脏数据，比如用心跳检测的实现，此时间就是心跳间隔，不同注册中心实现不一样。 | 2.1.0以上版本 | +| file | registry.file | string | 可选 | | 服务治理 | 使用文件缓存注册中心地址列表及服务提供者列表，应用重启时将基于此文件恢复，注意：两个注册中心不能使用同一文件存储 | 2.0.0以上版本 | +| wait | registry.wait | int | 可选 | 0 | 性能调优 | 停止时等待通知完成时间(毫秒) | 2.0.0以上版本 | +| check | check | boolean | 可选 | true | 服务治理 | 注册中心不存在时，是否报错 | 2.0.0以上版本 | +| register | register | boolean | 可选 | true | 服务治理 | 是否向此注册中心注册服务，如果设为false，将只订阅，不注册 | 2.0.5以上版本 | +| subscribe | subscribe | boolean | 可选 | true | 服务治理 | 是否向此注册中心订阅服务，如果设为false，将只注册，不订阅 | 2.0.5以上版本 | +| dynamic | dynamic | boolean | 可选 | true | 服务治理 | 服务是否动态注册，如果设为false，注册后将显示为disable状态，需人工启用，并且服务提供者停止时，也不会自动取消注册，需人工禁用。 | 2.0.5以上版本 | +| group | group | string | 可选 | dubbo | 服务治理 | 服务注册分组，跨组的服务不会相互影响，也无法相互调用，适用于环境隔离。 | 2.0.5以上版本 | +| simplified | simplified | boolean | 可选 | false | 服务治理 | 注册到注册中心的URL是否采用精简模式的（与低版本兼容） | 2.7.0以上版本 | +| extra-keys | extraKeys | string | 可选 | | 服务治理 | 在simplified=true时，extraKeys允许你在默认参数外将额外的key放到URL中，格式："interface,key1,key2"。 | 2.7.0以上版本 | + +# dubbo:service + +服务提供者暴露服务配置。对应的配置类：`org.apache.dubbo.config.ServiceConfig` + +| 属性 | 对应URL参数 | 类型 | 是否必填 | 缺省值 | 作用 | 描述 | 兼容性 | +| --- | --- | ---- | --- | --- | --- | --- | --- | +| interface | | class | 必填 | | 服务发现 | 服务接口名 | 1.0.0以上版本 | +| ref | | object | 必填 | | 服务发现 | 服务对象实现引用 | 1.0.0以上版本 | +| version | version | string | 可选 | 0.0.0 | 服务发现 | 服务版本，建议使用两位数字版本，如：1.0，通常在接口不兼容时版本号才需要升级 | 1.0.0以上版本 | +| group | group | string | 可选 | | 服务发现 | 服务分组，当一个接口有多个实现，可以用分组区分 | 1.0.7以上版本 | +| path | <path> | string | 可选 | 缺省为接口名 | 服务发现 | 服务路径 (注意：1.0不支持自定义路径，总是使用接口名，如果有1.0调2.0，配置服务路径可能不兼容) | 1.0.12以上版本 | +| delay | delay | int | 可选 | 0 | 性能调优 | 延迟注册服务时间(毫秒) ，设为-1时，表示延迟到Spring容器初始化完成时暴露服务 | 1.0.14以上版本 | +| timeout | timeout | int | 可选 | 1000 | 性能调优 | 远程服务调用超时时间(毫秒) | 2.0.0以上版本 | +| retries | retries | int | 可选 | 2 | 性能调优 | 远程服务调用重试次数，不包括第一次调用，不需要重试请设为0 | 2.0.0以上版本 | +| connections | connections | int | 可选 | 100 | 性能调优 | 对每个提供者的最大连接数，rmi、http、hessian等短连接协议表示限制连接数，dubbo等长连接协表示建立的长连接个数 | 2.0.0以上版本 | +| loadbalance | loadbalance | string | 可选 | random | 性能调优 | 负载均衡策略，可选值：random,roundrobin,leastactive，分别表示：随机，轮询，最少活跃调用 | 2.0.0以上版本 | +| async | async | boolean | 可选 | false | 性能调优 | 是否缺省异步执行，不可靠异步，只是忽略返回值，不阻塞执行线程 | 2.0.0以上版本 | +| local | local | class/boolean | 可选 | false | 服务治理 | 设为true，表示使用缺省代理类名，即：接口名 + Local后缀，已废弃，请使用stub| 2.0.0以上版本 | +| stub | stub | class/boolean | 可选 | false | 服务治理 | 设为true，表示使用缺省代理类名，即：接口名 + Stub后缀，服务接口客户端本地代理类名，用于在客户端执行本地逻辑，如本地缓存等，该本地代理类的构造函数必须允许传入远程代理对象，构造函数如：public XxxServiceStub(XxxService xxxService) | 2.0.0以上版本 | +| mock | mock | class/boolean | 可选 | false | 服务治理 | 设为true，表示使用缺省Mock类名，即：接口名 + Mock后缀，服务接口调用失败Mock实现类，该Mock类必须有一个无参构造函数，与Local的区别在于，Local总是被执行，而Mock只在出现非业务异常(比如超时，网络异常等)时执行，Local在远程调用之前执行，Mock在远程调用后执行。 | 2.0.0以上版本 | +| token | token | string/boolean | 可选 | false | 服务治理 | 令牌验证，为空表示不开启，如果为true，表示随机生成动态令牌，否则使用静态令牌，令牌的作用是防止消费者绕过注册中心直接访问，保证注册中心的授权功能有效，如果使用点对点调用，需关闭令牌功能 | 2.0.0以上版本 | +| registry | | string | 可选 | 缺省向所有registry注册 | 配置关联 | 向指定注册中心注册，在多个注册中心时使用，值为<dubbo:registry>的id属性，多个注册中心ID用逗号分隔，如果不想将该服务注册到任何registry，可将值设为N/A | 2.0.0以上版本 | +| provider | | string | 可选 | 缺省使用第一个provider配置 | 配置关联 | 指定provider，值为<dubbo:provider>的id属性 | 2.0.0以上版本 | +| deprecated | deprecated | boolean | 可选 | false | 服务治理 | 服务是否过时，如果设为true，消费方引用时将打印服务过时警告error日志 | 2.0.5以上版本 | +| dynamic | dynamic | boolean | 可选 | true | 服务治理 | 服务是否动态注册，如果设为false，注册后将显示后disable状态，需人工启用，并且服务提供者停止时，也不会自动取消册，需人工禁用。 | 2.0.5以上版本 | +| accesslog | accesslog | string/boolean | 可选 | false | 服务治理 | 设为true，将向logger中输出访问日志，也可填写访问日志文件路径，直接把访问日志输出到指定文件 | 2.0.5以上版本 | +| owner | owner | string | 可选 | | 服务治理 | 服务负责人，用于服务治理，请填写负责人公司邮箱前缀 | 2.0.5以上版本 | +| document | document | string | 可选 | | 服务治理 | 服务文档URL | 2.0.5以上版本 | +| weight | weight | int | 可选 | | 性能调优 | 服务权重 | 2.0.5以上版本 | +| executes | executes | int | 可选 | 0 | 性能调优 | 服务提供者每服务每方法最大可并行执行请求数 | 2.0.5以上版本 | | actives | actives | int | 可选 | 0 | 性能调优 | 每服务消费者每服务每方法最大并发调用数 | 2.0.5以上版本 | +| proxy | proxy | string | 可选 | javassist | 性能调优 | 生成动态代理方式，可选：jdk/javassist | 2.0.5以上版本 | +| cluster | cluster | string | 可选 | failover | 性能调优 | 集群方式，可选：failover/failfast/failsafe/failback/forking | 2.0.5以上版本 | +| filter | service.filter | string | 可选 | default | 性能调优 | 服务提供方远程调用过程拦截器名称，多个名称用逗号分隔 | 2.0.5以上版本 | +| listener | exporter.listener | string | 可选 | default | 性能调优 | 服务提供方导出服务监听器名称，多个名称用逗号分隔 | | +| protocol | | string | 可选 | | 配置关联 | 使用指定的协议暴露服务，在多协议时使用，值为<dubbo:protocol>的id属性，多个协议ID用逗号分隔 | 2.0.5以上版本 | +| layer | layer | string | 可选 | | 服务治理 | 服务提供者所在的分层。如：biz、dao、intl:web、china:acton。 | 2.0.7以上版本 | +| register | register | boolean | 可选 | true | 服务治理 | 该协议的服务是否注册到注册中心 | 2.0.8以上版本 | diff --git a/content/zh/docs3-building/java-sdk/reference-manual/config/xml/guide.md b/content/zh/docs3-building/java-sdk/reference-manual/config/xml/guide.md new file mode 100644 index 000000000000..ad60f98fbbeb --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/config/xml/guide.md @@ -0,0 +1,98 @@ +--- +type: docs +title: "配置指南" +linkTitle: "配置指南" +weight: 1 +description: "以 XML 配置的方式来配置你的 Dubbo 应用" +--- + +有关 XML 的详细配置项，请参见：[XML配置参考手册](../../../references/xml)。如果不想使用 Spring 配置，而希望通过 API 的方式进行调用，请参见：[API配置](../api)。想知道如何使用配置，请参见：[快速启动](../../../quick-start)。 + +请在此查看文档描述的[完整示例](https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-basic) + +## provider.xml 示例 + +```xml + + + + + + + +``` + +## consumer.xml示例 + +```xml + + + + + +``` + +所有标签都支持自定义参数，用于不同扩展点实现的特殊配置，如： + +```xml + + + +``` + +或： [^1] + +```xml + + + +``` + +## 配置之间的关系 + +![dubbo-config](/imgs/user/dubbo-config.jpg) + +标签 | 用途 | 解释 +------------- | ------------- | ------------- +`` | 服务配置 | 用于暴露一个服务，定义服务的元信息，一个服务可以用多个协议暴露，一个服务也可以注册到多个注册中心 +`` [^2] | 引用配置 | 用于创建一个远程服务代理，一个引用可以指向多个注册中心 +`` | 协议配置 | 用于配置提供服务的协议信息，协议由提供方指定，消费方被动接受 +`` | 应用配置 | 用于配置当前应用信息，不管该应用是提供者还是消费者 +`` | 模块配置 | 用于配置当前模块信息，可选 +`` | 注册中心配置 | 用于配置连接注册中心相关信息 +`` | 监控中心配置 | 用于配置连接监控中心相关信息，可选 +`` | 提供方配置 | 当 ProtocolConfig 和 ServiceConfig 某属性没有配置时，采用此缺省值，可选 +`` | 消费方配置 | 当 ReferenceConfig 某属性没有配置时，采用此缺省值，可选 +`` | 方法配置 | 用于 ServiceConfig 和 ReferenceConfig 指定方法级的配置信息 +`` | 参数配置 | 用于指定方法参数配置 + + +## 不同粒度配置的覆盖关系 + +以 timeout 为例，下图显示了配置的查找顺序，其它 retries, loadbalance, actives 等类似： + +* 方法级优先，接口级次之，全局配置再次之。 +* 如果级别一样，则消费方优先，提供方次之。 + +其中，服务提供方配置，通过 URL 经由注册中心传递给消费方。 + +![dubbo-config-override](/imgs/user/dubbo-config-override.jpg) + +（建议由服务提供方设置超时，因为一个方法需要执行多长时间，服务提供方更清楚，如果一个消费方同时引用多个服务，就不需要关心每个服务的超时设置）。 + +理论上 ReferenceConfig 中除了`interface`这一项，其他所有配置项都可以缺省不配置，框架会自动使用ConsumerConfig，ServiceConfig, ProviderConfig等提供的缺省配置。 + +[^1]: `2.1.0` 开始支持，注意声明：`xmlns:p="http://www.springframework.org/schema/p"` +[^2]: 引用缺省是延迟初始化的，只有引用被注入到其它 Bean，或被 `getBean()` 获取，才会初始化。如果需要饥饿加载，即没有人引用也立即生成动态代理，可以配置：`` diff --git a/content/zh/docs3-building/java-sdk/reference-manual/config/yaml/_index.md b/content/zh/docs3-building/java-sdk/reference-manual/config/yaml/_index.md new file mode 100644 index 000000000000..7a20d81c2f95 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/config/yaml/_index.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "YAML 配置手册" +linkTitle: "YAML 配置手册" +weight: 4 +--- \ No newline at end of file diff --git a/content/zh/docs3-building/java-sdk/reference-manual/config/yaml/description.md b/content/zh/docs3-building/java-sdk/reference-manual/config/yaml/description.md new file mode 100644 index 000000000000..b82b3289ac85 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/config/yaml/description.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "配置项描述" +linkTitle: "配置项描述" +weight: 2 +--- \ No newline at end of file diff --git a/content/zh/docs3-building/java-sdk/reference-manual/config/yaml/guide.md b/content/zh/docs3-building/java-sdk/reference-manual/config/yaml/guide.md new file mode 100644 index 000000000000..60114cfb88b1 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/config/yaml/guide.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "配置指南" +linkTitle: "配置指南" +weight: 1 +--- diff --git a/content/zh/docs3-building/java-sdk/reference-manual/graalvm/_index.md b/content/zh/docs3-building/java-sdk/reference-manual/graalvm/_index.md new file mode 100644 index 000000000000..1412a54a3200 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/graalvm/_index.md @@ -0,0 +1,214 @@ +--- +type: docs +title: "Dubbo 集成 Graalvm参考手册" +linkTitle: "Dubbo 集成 Graalvm参考手册" +weight: 9 +description: "" +--- + +dubbo3.0支持native-image文档 + +## 概述 + +本文档将介绍将dubbo3.0项目接入GraalVM，进行native-image编译为二进制的流程。 + +关于GraalVm的更多信息可以阅读 https://www.graalvm.org/docs/getting-started/container-images/ 此文档。 + +## 使用样例 + +在编译我们的dubbo项目之前，需要确保我们正基于graalVm的环境。 + +1. 安装GraalVM + +进入https://www.graalvm.org/ 官网根据自己的系统选取最新版本安装： + +![](/imgs/blog/dubbo3.0-graalvm-support/graalvmgw.jpg) + +安装完成后，修改配置JAVA_HOME的路径，生效后查看本地jdk可以看到如下： + +![](/imgs/blog/dubbo3.0-graalvm-support/graalvm_env.jpg) +这里我们使用的基于jdk1.8版本的GraalVM。 + +- 安装native-image，只需执行gu install native-image即可。 + +1. 拉取dubbo代码，切换到[apache:3.0](https://github.com/apache/dubbo)分支。 +2. 手动执行生成SPI代码。 + +由于目前编译native-image不支持代码动态生成编译，所以有关代码动态生成的部分需要我们手动先生成，这里提供了工具函数： + +![](/imgs/blog/dubbo3.0-graalvm-support/code_generator.jpg) +执行CodeGenerator即可在dubbo-native模块下生成SPI代码。 + +1. 在根目录下执行install + +``` +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. 编译demo项目 + +这里我们提供了可直接进行编译的示例项目，dubbo-demo/dubbo-demo-native。上面步骤install完成后，先到dubbo-demo-native的provider下，执行native-image编译： + +``` + mvn clean package -P native -Dmaven.test.skip=true +``` + +这里由于我们在maven中引入了native-image插件，所以直接-P native即可执行该插件。 + +![](/imgs/blog/dubbo3.0-graalvm-support/native_image_build.jpg) +编译成功后可以在target下看到已经生成的二进制文件，本地启动一个zookeeper，直接执行该二进制，可见启动成功如下： + +![](/imgs/blog/dubbo3.0-graalvm-support/run_provider.jpg) +consumer端同样执行编译，在consumer的target下也会生成二进制文件：demo-native-consumer,执行该二进制可以看到调用结果如下： + +![](/imgs/blog/dubbo3.0-graalvm-support/run_consumer.jpg) +### 具体步骤 + +实际上在这个demo下我们做了一些工作来确保项目可以编译执行，主要有以下几个步骤 + +- 引入dubbo-native依赖 + +``` + + + org.apache.dubbo + + dubbo-native + + ${project.version} + + +``` + +该模块下有我们生成的SPI代码。 + +- 引入native-image插件 + +``` + + + 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 + + + + + + +``` + +其中定义了生成的镜像名以及一些构建镜像的参数。 + +- 挂载native-image-agent + +由于我们需要将一些反射、JNI等类先指定出来，我们需要先使用该agent以正常方式运行一遍生成这些类的json形式的信息。 + +在启动参数中添加： + +``` +-agentlib:native-image-agent=config-output-dir=/tmp/config/,config-write-period-secs=300,config-write-initial-delay-secs=5 +``` + +以正常方式启动，在项目的resources下建立文件夹META-INF.native-image，把在本地目录中生成的文件粘进去： + +![](/imgs/blog/dubbo3.0-graalvm-support/resources.jpg) +（可能会有缺漏没有生成的类信息，需要根据编译或运行时的报错信息手动添加。） + + + +**完成以上几步后就可以进行项目的编译了。** diff --git a/content/zh/docs3-building/java-sdk/reference-manual/metadata-center/_index.md b/content/zh/docs3-building/java-sdk/reference-manual/metadata-center/_index.md new file mode 100644 index 000000000000..f3fad3427b04 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/metadata-center/_index.md @@ -0,0 +1,7 @@ +--- +type: docs +title: "元数据中心参考手册" +linkTitle: "元数据中心参考手册" +weight: 6 +description: "" +--- diff --git a/content/zh/docs3-building/java-sdk/reference-manual/metadata-center/nacos/_index.md b/content/zh/docs3-building/java-sdk/reference-manual/metadata-center/nacos/_index.md new file mode 100644 index 000000000000..7fed8cf789af --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/metadata-center/nacos/_index.md @@ -0,0 +1,7 @@ +--- +type: docs +title: "Nacos" +linkTitle: "Nacos" +weight: 3 +description: "" +--- diff --git a/content/zh/docs3-building/java-sdk/reference-manual/metadata-center/nacos/guide.md b/content/zh/docs3-building/java-sdk/reference-manual/metadata-center/nacos/guide.md new file mode 100644 index 000000000000..13dc994973dd --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/metadata-center/nacos/guide.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "使用说明" +linkTitle: "使用说明" +weight: 2 +--- diff --git a/content/zh/docs3-building/java-sdk/reference-manual/metadata-center/nacos/overview.md b/content/zh/docs3-building/java-sdk/reference-manual/metadata-center/nacos/overview.md new file mode 100644 index 000000000000..c087fc3b6f43 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/metadata-center/nacos/overview.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "概述" +linkTitle: "概述" +weight: 1 +--- diff --git a/content/zh/docs3-building/java-sdk/reference-manual/metadata-center/overview/_index.md b/content/zh/docs3-building/java-sdk/reference-manual/metadata-center/overview/_index.md new file mode 100644 index 000000000000..3dece31ac6e3 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/metadata-center/overview/_index.md @@ -0,0 +1,619 @@ +--- +type: docs +title: "元数据中心概述" +linkTitle: "元数据中心概述" +weight: 1 +--- + + +## 背景 + +dubbo provider中的服务配置项有接近[30个配置项](https://dubbo.apache.org/zh/docs/v2.7/user/references/xml/dubbo-provider/)。 排除注册中心服务治理需要之外，很大一部分配置项是provider自己使用，不需要透传给消费者。这部分数据不需要进入注册中心，而只需要以key-value形式持久化存储。 +dubbo consumer中的配置项也有[20+个配置项](https://dubbo.apache.org/zh/docs/v2.7/user/references/xml/dubbo-consumer/)。在注册中心之中，服务消费者列表中只需要关注application，version，group，ip，dubbo版本等少量配置，其他配置也可以以key-value形式持久化存储。 +这些数据是以服务为维度注册进入注册中心，导致了数据量的膨胀，进而引发注册中心(如zookeeper)的网络开销增大，性能降低。 +除了上述配置项的存储之外，dubbo服务元数据信息也需要被存储下来。元数据信息包括服务接口，及接口的方法信息。这些信息将被用于服务mock，服务测试。 + +以上的元数据都是基于接口级别。在3.0版本中，引入了应用元数据的概念，应用元数据描述的是整个应用的信息概览。并且引入了服务自省映射，用于应用级别的服务发现。 + + +## 目标 + +需要将注册中心原来的数据信息和元数据信息保存到独立的key-value的存储中，这个key-value可以是DB，redis或者其他持久化存储。核心代码中支持了zookeeper，redis, nacos(推荐)的默认支持。 +>因为是基于key-value存储，key不会改变，最新的value会将原来的value进行覆盖 + +Provider存储内容的格式，参见：org.apache.dubbo.metadata.definition.model.FullServiceDefinition。是该类型gson化之后的存储。 +Consumer存储内容，为Map格式。从Consumer端注册到注册中心的URL中的获取参数信息。即通过URL.getParameterMap()获取到的Map，进行gson化之后进行存储。 + +详细的内容，可以参考下面的sample输出。 + + + +## 配置 + +默认的元数据存储，额外支持以下几个特性： +* 失败重试 +* 每天定时重刷 + +#### 失败重试 +失败重试可以通过retrytimes （重试次数,默认100），retryperiod（重试周期，默认3000ms）进行设置。 + +#### 定时刷新 +默认开启，可以通过设置cycleReport=false进行关闭。 + +#### 完整的配置项： + +```properties +dubbo.metadata-report.address=zookeeper://127.0.0.1:2181 +dubbo.metadata-report.username=xxx ##非必须 +dubbo.metadata-report.password=xxx ##非必须 +dubbo.metadata-report.retry-times=30 ##非必须,default值100 +dubbo.metadata-report.retry-period=5000 ##非必须,default值3000 +dubbo.metadata-report.cycle-report=false ##非必须,default值true +dubbo.metadata-report.sync.report=false ##非必须,default值为false +``` +> 如果元数据地址(dubbo.metadata-report.address)也不进行配置，会判断注册中心的协议是否支持元数据中心，如果支持，会使用注册中心的地址来用作元数据中心。 + + +接下来看几个sample的配置。无论哪种配置方式，都需要引入maven依赖： + +zookeeper: +```xml + + org.apache.dubbo + dubbo-metadata-report-zookeeper + +``` + +redis: +```xml + + org.apache.dubbo + dubbo-metadata-report-redis + +``` + +nacos: +```xml + + org.apache.dubbo + dubbo-metadata-report-nacos + +``` + + +> **完整的sample，查看[sample-2.7](https://github.com/dubbo/dubbo-samples/tree/master)** + +### 方式一：在配置中心配置 + +参考sample：dubbo-samples-metadata-report/dubbo-samples-metadata-report-configcenter 工程。 + +##### 配置中心配置 + +配置中心的配置，可以参考configcenter的文档。配置的内容如下： + +```properties +dubbo.registry.address=zookeeper://127.0.0.1:2181 +### 注意驼峰式风格 +dubbo.metadata-report.address=zookeeper://127.0.0.1:2181 ###元数据存储的地址 +``` + +在sample中，使用了Zookeeper作为配置中心。启动本地zookeeper服务之后，直接运行：org.apache.dubbo.samples.metadatareport.configcenter.ZKTools 就可以完成写入。 +如果配置中心使用了nacos，apollo，这些产品本身支持ops配置。 + +##### 应用配置 + +```properties +###dubbo.properties +dubbo.config-center.address=zookeeper://127.0.0.1:2181 +... +``` + +完成上述两步之后，注册中心地址、元数据地址将从配置中心进行获取。现在可以依次运行Provider类和Consumer类，会在console中得到对应的输出或者直接通过zookeeper的cli查看。 + +##### Provider配置 + +provider端存储的元数据内容如下： + +```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" + }] +} + +``` + +provider存储的内容包括了provider服务往注册中心填写的全部参数，以及服务的方法信息（方法名，入参出参的格式）。 + +##### 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" +} +``` + +consumer端存储了consumer往注册中心填写的全部参数。 + + + +上面的例子，主要是将元数据地址放在配置中心，在元数据区存储下来的provider端服务信息和consumer端服务信息的展示。 +接下来的两个例子，主要讲解在工程中配置：xml方式，annotation方式。 + +### 方式二：配置在项目中-properties方式引入配置 + +参考sample：dubbo-samples-metadata-report/dubbo-samples-metadata-report-local-properties工程。 + +##### dubbo.properties + +```properties +dubbo.metadata-report.address=zookeeper://127.0.0.1:2181 +``` + +配置完成这个之后，其余的不用特别关注。也可以直接查看对应的provider和consumer端的服务信息。 + +##### provider存储的某个服务的内容： + +```json +{ + "parameters": { + "valid": "true", + "async": "true", + "side": "provider", + "application": "metadatareport-local-xml-provider", + "methods": "sayHello", + "dubbo": "2.0.2", + "interface": "org.apache.dubbo.samples.metadatareport.local.xml.api.DemoService", + "generic": "false", + "anyhost": "true" + }, + "canonicalName": "org.apache.dubbo.samples.metadatareport.local.xml.api.DemoService", + "codeSource": "file:/Users/cvictory/workspace/work-mw/dubbo-samples/dubbo-samples-metadata-report/dubbo-samples-metadata-report-local-xml/target/classes/", + "methods": [{ + "name": "sayHello", + "parameterTypes": ["java.lang.String"], + "returnType": "java.lang.String" + }], + "types": [{ + "type": "int" + }, { + "type": "char" + }, { + "type": "java.lang.String", + "properties": { + "value": { + "type": "char[]" + }, + "hash": { + "type": "int" + } + } + }] +} + +``` + +##### consumer端存储的内容： + +```json +{ + "valid": "true", + "side": "consumer", + "application": "metadatareport-local-xml-consumer", + "methods": "sayHello", + "dubbo": "2.0.2", + "interface": "org.apache.dubbo.samples.metadatareport.local.xml.api.DemoService" +} + +``` + + + +### 方式三：配置在项目中-annotation方式引入配置 + +参考sample：dubbo-samples-metadata-report/dubbo-samples-metadata-report-local-annotaion工程。 + +##### @Bean 引入bean + +```java +@Bean +public MetadataReportConfig metadataReportConfig() { + MetadataReportConfig metadataReportConfig = new MetadataReportConfig(); + metadataReportConfig.setAddress("zookeeper://127.0.0.1:2181"); + return metadataReportConfig; +} + +``` +引入Bean之后，其余的地方也不需要特别配置。直接查看对应的服务信息： + +##### provider存储的某个服务的内容： + +```json +{ + "parameters": { + "side": "provider", + "methods": "sayHello", + "dubbo": "2.0.2", + "interface": "org.apache.dubbo.samples.metadatareport.local.annotation.api.AnnotationService", + "version": "1.1.8", + "generic": "false", + "revision": "1.1.8", + "valid": "true", + "application": "metadatareport-local-annotaion-provider", + "default.timeout": "1000", + "group": "d-test", + "anyhost": "true" + }, + "canonicalName": "org.apache.dubbo.samples.metadatareport.local.annotation.api.AnnotationService", + "codeSource": "file:/Users/cvictory/workspace/work-mw/dubbo-samples/dubbo-samples-metadata-report/dubbo-samples-metadata-report-local-annotaion/target/classes/", + "methods": [{ + "name": "sayHello", + "parameterTypes": ["java.lang.String"], + "returnType": "java.lang.String" + }], + "types": [{ + "type": "int" + }, { + "type": "java.lang.String", + "properties": { + "value": { + "type": "char[]" + }, + "hash": { + "type": "int" + } + } + }, { + "type": "char" + }] +} +``` + +##### consumer端存储的内容： + +```json +{ + "valid": "true", + "side": "consumer", + "application": "metadatareport-local-annotaion-consumer", + "methods": "sayHello", + "dubbo": "2.0.2", + "interface": "org.apache.dubbo.samples.metadatareport.local.annotation.api.AnnotationService", + "version": "1.1.8", + "revision": "1.1.8", + "group": "d-test" +} +``` + +## 扩展 +### SPI定义 + +参考：org.apache.dubbo.metadata.store.MetadataReportFactory ， org.apache.dubbo.metadata.store.MetadataReport + +```java +@SPI("redis") +public interface MetadataReportFactory { + @Adaptive({"protocol"}) + MetadataReport getMetadataReport(URL url); +} +``` + + + +### 自定义元数据的存储 + +下面以Redis存储为例进行说明。 + +新建一个project，需要支持以下修改： + +#### 扩展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); + } + } +} +``` + +#### 扩展 AbstractMetadataReportFactory + +```java +public class RedisMetadataReportFactory extends AbstractMetadataReportFactory { + @Override + public MetadataReport createMetadataReport(URL url) { + return new RedisMetadataReport(url); + } +} +``` + +#### 增加 MetadataReportFactory + +> META-INF/dubbo/internal/org.apache.dubbo.metadata.store.MetadataReportFactory + +```properties +redis=org.apache.dubbo.metadata.store.redis.RedisMetadataReportFactory +``` + +只要将上面的修改和project打包成jar包，然后配置元数据中心的url：redis://10.20.153.10:6379。 + +至此，一个自定义的元数据存储就可以运行了。 + + +### 数据存储 + +#### 接口级别元数据 + +##### Zookeeper + +```xml + +``` + +Zookeeper 基于树形结构进行数据存储，它的元数据信息位于以下节点: +```text +Provider: /dubbo/metadata/{interface name}/{version}/{group}/provider/{application name} +Consumer: /dubbo/metadata/{interface name}/{version}/{group}/consumer/{application name} +``` + +当 version 或者 group 不存在时，version 路径和 group 路径会取消，路径如下: +```text +Provider: /dubbo/metadata/{interface name}/provider/{application name} +Consumer: /dubbo/metadata/{interface name}/consumer/{application name} +``` + +通过 zkCli get 操作查看数据. + +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.CompletableFuture.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 +``` + + +##### Redis + +```xml + +``` + +在Redis中，使用string数据结构来进行存储元数据信息: +```text +Provider: {service name}:{version}:{group}:provider:{application name} +Consumer: {service name}:{version}:{group}:consumer:{application name} +``` + +当 version 或者 group 不存在时，`:` 依然保留: + +```text +Provider: {service name}:::provider:{application name} +Consumer: {service name}:::consumer:{application name} +``` + +通过 Redis client get key 查看数据. + +Provider key: +```shell script +127.0.0.1:6379> get 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\":\"sayHello\",\"parameterTypes\":[\"java.lang.String\"],\"returnType\":\"java.lang.String\"},{\"name\":\"sayHelloAsync\",\"parameterTypes\":[\"java.lang.String\"],\"returnType\":\"java.util.concurrent.CompletableFuture\"}],\"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.CompletableFuture.Completion\",\"status\":\"int\"}},{\"type\":\"int\"}]}" +``` + +Consumer key: +```shell script +127.0.0.1:6379> get 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\"}" +``` + +##### Nacos +```xml + +``` + +在 Nacos 中，本身就存在配置中心这个概念，正好用于元数据存储。在配置中心的场景下，存在命名空间- namespace 的概念，在 namespace 之下，还存在 group 概念。即通过 namespace 和 group 以及 dataId 去定位一个配置项，在不指定 namespace 的情况下，默认使用 `public` 作为默认的命名空间。 + +```text +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' +``` + +当 version 或者 group 不存在时，`:` 依然保留: + +```text +Provider: namespace: 'public', dataId: '{service name}:::provider:{application name}', group: 'dubbo' +Consumer: namespace: 'public', dataId: '{service name}:::consumer:{application name}', group: 'dubbo' +``` + +可以通过 Nacos 自带的 web console 界面进行查看. + +Provider data: +![nacos-metadata-report-provider-metadata.png](/imgs/user/nacos-metadata-report-provider-metadata.png) + +Consumer data: +![nacos-metadata-report-consumer-metadata.png](/imgs/user/nacos-metadata-report-consumer-metadata.png) + + +#### 应用级别元数据 +应用级别元数据只有当一个应用定义服务之后，才会进行暴露。会根据当前应用的自身信息，以及接口信息，去计算出该应用的 revision 修订值，用于保存应用级别元数据， + +##### Zookeeper +Zookeeper 的应用级别元数据位于 /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 +``` + +#### Redis +Redis 元数据中心目前还不支持应用级别元数据，但已提上日程，会在近期进行实现。 + +##### Nacos +Nacos 应用级别的元数据位于 namespace: 'public', dataId: '{application name}', group: '{revision}' + +![nacos-metadata-report-application-metadata.png](/imgs/user/nacos-metadata-report-application-metadata.png) + + +#### 服务自省映射 - Service Name Mapping +在Dubbo 3.0 中，默认使用了服务自省机制去实现服务发现，关于服务自省可以查看[服务自省](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/) + +简而言之，服务自省机制需要能够通过 interface name 去找到对应的 application name，这个关系可以是一对多的，即一个 service name 可能会对应多个不同的 application name。在 3.0 中，元数据中心提供此项映射的能力。 + + +##### Zookeeper +在上面提到，service name 和 application name 可能是一对多的，在 zookeeper 中，使用单个 key-value 进行保存，多个 application name 通过英文逗号`,`隔开。由于是单个 key-value 去保存数据，在多客户端的情况下可能会存在并发覆盖的问题。因此，我们使用 zookeeper 中的版本机制 version 去解决该问题。在 zookeeper 中，每一次对数据进行修改，dataVersion 都会进行增加，我们可以利用 version 这个机制去解决多个客户端同时更新映射的并发问题。不同客户端在更新之前，先去查一次 version，当作本地凭证。在更新时，把凭证 version 传到服务端比对 version, 如果不一致说明在次期间被其他客户端修改过，重新获取凭证再进行重试(CAS)。目前如果重试6次都失败的话，放弃本次更新映射行为。 + +Curator api. +```java +CuratorFramework client = ... +client.setData().withVersion(ticket).forPath(path, dataBytes); +``` + +映射信息位于: +```text +/dubbo/mapping/{service name} +``` + +通过 zkCli get 操作查看数据. + +```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 +``` + + +##### Redis +Redis 元数据中心目前还不支持服务自省映射，但已提上日程，会在近期进行实现。 + + +##### Nacos +在上面提到，service name 和 application name 可能是一对多的，在 nacos 中，使用单个 key-value 进行保存，多个 application name 通过英文逗号`,`隔开。由于是单个 key-value 去保存数据，在多客户端的情况下可能会存在并发覆盖的问题。因此，我们使用 nacos 中 publishConfigCas 的能力去解决该问题。在 nacos 中，使用 publishConfigCas 会让用户传递一个参数 casMd5，该值的含义是之前配置内容的 md5 值。不同客户端在更新之前，先去查一次 nacos 的 content 的值，计算出 md5 值，当作本地凭证。在更新时，把凭证 md5 传到服务端比对 md5 值, 如果不一致说明在次期间被其他客户端修改过，重新获取凭证再进行重试(CAS)。目前如果重试6次都失败的话，放弃本次更新映射行为。 + +Nacos api: +```java +ConfigService configService = ... +configService.publishConfigCas(key, group, content, ticket); +``` + +映射信息位于 namespace: 'public', dataId: '{service name}', group: 'mapping'. + +![nacos-metadata-report-service-name-mapping.png](/imgs/user/nacos-metadata-report-service-name-mapping.png) + + + + + + + diff --git a/content/zh/docs3-building/java-sdk/reference-manual/metadata-center/redis/_index.md b/content/zh/docs3-building/java-sdk/reference-manual/metadata-center/redis/_index.md new file mode 100644 index 000000000000..34200f813988 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/metadata-center/redis/_index.md @@ -0,0 +1,7 @@ +--- +type: docs +title: "Redis" +linkTitle: "Redis" +weight: 4 +description: "" +--- diff --git a/content/zh/docs3-building/java-sdk/reference-manual/metadata-center/redis/guide.md b/content/zh/docs3-building/java-sdk/reference-manual/metadata-center/redis/guide.md new file mode 100644 index 000000000000..37430b92141b --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/metadata-center/redis/guide.md @@ -0,0 +1,7 @@ +--- +type: docs +title: "使用说明" +linkTitle: "使用说明" +weight: 2 +--- + diff --git a/content/zh/docs3-building/java-sdk/reference-manual/metadata-center/redis/overview.md b/content/zh/docs3-building/java-sdk/reference-manual/metadata-center/redis/overview.md new file mode 100644 index 000000000000..c087fc3b6f43 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/metadata-center/redis/overview.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "概述" +linkTitle: "概述" +weight: 1 +--- diff --git a/content/zh/docs3-building/java-sdk/reference-manual/metadata-center/zookeeper/_index.md b/content/zh/docs3-building/java-sdk/reference-manual/metadata-center/zookeeper/_index.md new file mode 100644 index 000000000000..2864a6f0b145 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/metadata-center/zookeeper/_index.md @@ -0,0 +1,7 @@ +--- +type: docs +title: "Zookeeper" +linkTitle: "Zookeeper" +weight: 2 +description: "" +--- diff --git a/content/zh/docs3-building/java-sdk/reference-manual/metadata-center/zookeeper/guide.md b/content/zh/docs3-building/java-sdk/reference-manual/metadata-center/zookeeper/guide.md new file mode 100644 index 000000000000..13dc994973dd --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/metadata-center/zookeeper/guide.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "使用说明" +linkTitle: "使用说明" +weight: 2 +--- diff --git a/content/zh/docs3-building/java-sdk/reference-manual/metadata-center/zookeeper/overview.md b/content/zh/docs3-building/java-sdk/reference-manual/metadata-center/zookeeper/overview.md new file mode 100644 index 000000000000..c087fc3b6f43 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/metadata-center/zookeeper/overview.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "概述" +linkTitle: "概述" +weight: 1 +--- diff --git a/content/zh/docs3-building/java-sdk/reference-manual/performance/_index.md b/content/zh/docs3-building/java-sdk/reference-manual/performance/_index.md new file mode 100755 index 000000000000..e3536c13c3e3 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/performance/_index.md @@ -0,0 +1,8 @@ + +--- +type: docs +title: "性能参考手册" +linkTitle: "性能参考手册" +weight: 8 +--- + diff --git a/content/zh/docs3-building/java-sdk/reference-manual/performance/benchmarking.md b/content/zh/docs3-building/java-sdk/reference-manual/performance/benchmarking.md new file mode 100644 index 000000000000..f5e36dd6a4f3 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/performance/benchmarking.md @@ -0,0 +1,106 @@ +--- +type: docs +title: "基准测试" +linkTitle: "基准测试" +weight: 1 +description: "" +--- + + +## 1 Benchmark 结论 + +对比 2.x 版本，Dubbo3 版本 + +- 服务发现资源利用率显著提升。 + - 对比接口级服务发现，单机常驻内存下降 50%，地址变更期 GC 消耗下降一个数量级 (百次 -> 十次) + - 对比应用级服务发现，单机常驻内存下降 75%，GC 次数趋零 +- Dubbo 协议性能持平，Triple 协议在网关、Stream吞吐量方面更具优势。 + - Dubbo协议 （3.0 vs 2.x），3.0 实现较 2.x 总体 qps rt 持平，略有提升 + - Triple协议 vs Dubbo协议，直连调用场景 Triple 性能并无优势，其优势在网关、Stream调用场景。 + + + +以下是详细压测过程与数据 + +## 2 应用级服务发现（地址推送链路） + +此部分压测数据是由工商银行 Dubbo 团队基于内部生产数据给出，压测过程模拟了“生产环境地址+zookeeper”的服务发现架构。 + +### 2.1 环境 + +| | 描述 | +| ------------ | ------------------------------------------------------------ | +| **压测数据** | 提供者
500运行实例✖️8interface✖️5protocol，即每个提供者向注册中心注册40个URL，总计20000个URL，每个URL字符长度约1k。

注册中心
2个独立zookeeper注册中心，服务提供者消费者采用并行配置。

消费者
配置1c2g，xmx=768，开启GC，从2个注册中心订阅，每5秒调用一次服务。运行20小时。 | +| **压测环境** | Java version "1.8.0"
Java(TM) SE Runtime Enviroment (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 数据分析 + +![//imgs/v3/performance/registry-mem.svg](/imgs/v3/performance/registry-mem.svg) + +
图一 服务发现模型内存占用变化

+ +- Dubbo3 接口级服务发现模型，常驻内存较 2.x 版本下降约 50% +- Dubbo3 应用级服务发现模型，常驻内存较 2.x 版本下降约 75% + + +![//imgs/v3/performance/registry-gc.svg](/imgs/v3/performance/registry-gc.svg) + +
图二 服务发现模型 GC 变化

+ +- Dubbo3 接口级服务发现模型，YGC 次数 2.x 版本大幅下降，从数百次下降到十几次 +- Dubbo3 应用级服务发现模型，FGC 次数 2.x 版本大幅下降，从数百次下降到零次 + + + +## 3 RPC 协议（远程调用链路） + +- Dubbo3 的 _Dubbo协议 _实现与 Dubbo2 版本在性能上基本持平。 +- 由于 Triple协议 本身是基于 HTTP/2 构建，因此在单条链路上的 RPC 调用并未比基于 TCP 的 Dubbo2 有提升，反而在某些调用场景出现一定下降。但 _Triple协议 _更大的优势在于网关穿透性、通用性，以及 Stream 通信模型带来的总体吞吐量提升。 +- Triple 预期在网关代理场景下一定会有更好的性能表现，鉴于当前压测环境，本轮 benchmark 暂未提供。 + + + +### 3.1 环境 + + +| | 描述 | +| ------------ | ------------------------------------------------------------ | +| **机器** | 4C8G Linux JDK 1.8（Provider）4C8G Linux JDK 1.8 （Consumer） | +| **压测用例** | RPC 方法类型包括：无参无返回值、普通pojo返回值、pojo列表返回值

2.7 版本 Dubbo 协议（Hessian2 序列化）
3.0 版本 Dubbo 协议（Hessian2 序列化）
3.0 版本 Dubbo 协议（Protobuf 序列化）
3.0 版本 Triple 协议（Protobuf 序列化）
3.0 版本 Triple 协议（Protobuf 套 Hessian2 序列化） | +| **压测方法** | 单链接场景下，消费端起 32 并发线程（当前机器配置 qps rt 较均衡的并发数），持续压后采集压测数据
压测数据通过 https://github.com/apache/dubbo-benchmark 得出 | + +
+ +### 3.2 数据分析 + +| | **Dubbo + Hessian2
2.7** | **Dubbo + Hessian2
3.0** | **Dubbo + Protobuf
3.0** | **Triple + Protobuf
3.0** | **Triple + Protobuf(Hessian)
3.0** | +| ------------------ | ----------------------------- | ----------------------------- | ----------------------------- | ------------------------------ | --------------------------------------- | +| **无参方法** | 30333 ops/s
2.5ms P99 | 30414 ops/s
2.4ms P99 | 24123 ops/s
3.2ms P99 | 7016 ops/s
8.7ms P99 | 6635 ops/s
9.1ms P99 | +| **pojo返回值** | 8984 ops/s
6.1 ms P99 | 12279 ops/s
5.7 ms P99 | 21479 ops/s
3.0 ms P99 | 6255 ops/s
8.9 ms P99 | 6491 ops/s
10 ms P99 | +| **pojo列表返回值** | 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 | + +#### 3.2.1 Dubbo 协议不同版本实现对比 + +![//imgs/v3/performance/rpc-dubbo.svg](/imgs/v3/performance/rpc-dubbo.svg) + +
图三 Dubbo协议在不同版本的实现对比
+ +- 就 Dubbo RPC + Hessian 的默认组合来说，Dubbo3 与 Dubbo2 在性能上在不同调用场景下基本持平 + +#### 3.2.2 Dubbo协议 vs Triple协议 + +![//imgs/v3/performance/rpc-triple.svg](/imgs/v3/performance/rpc-triple.svg) + +
图四 Triple vs Dubbo
+ +- 单纯看 Consumer <-> Provider 的点对点调用，可以看出 Triple 协议本身并不占优势，同样使用 Protobuf 序列化方式，Dubbo RPC 协议总体性能还是要优于 Triple。

+- Triple 实现在 3.0 版本中将会得到持续优化，但不能完全改变在某些场景下“基于 HTTP/2 的 RPC 协议”对比“基于 TCP 的 RPC 协议”处于劣势的局面 + +#### 3.2.3 补充网关场景 + +TBD

+ +#### 3.3.4 模拟 Stream 通信场景的吞吐量提升 + +TBD diff --git a/content/zh/docs3-building/java-sdk/reference-manual/protocol/_index.md b/content/zh/docs3-building/java-sdk/reference-manual/protocol/_index.md new file mode 100755 index 000000000000..259d37856d28 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/protocol/_index.md @@ -0,0 +1,8 @@ + +--- +type: docs +title: "RPC 协议参考手册" +linkTitle: "RPC 协议参考手册" +weight: 4 +--- + diff --git a/content/zh/docs3-building/java-sdk/reference-manual/protocol/dubbo/_index.md b/content/zh/docs3-building/java-sdk/reference-manual/protocol/dubbo/_index.md new file mode 100755 index 000000000000..81d56f7be3d9 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/protocol/dubbo/_index.md @@ -0,0 +1,8 @@ + +--- +type: docs +title: "Dubbo协议" +linkTitle: "Dubbo协议" +weight: 2 +--- + diff --git a/content/zh/docs3-building/java-sdk/reference-manual/protocol/dubbo/guide.md b/content/zh/docs3-building/java-sdk/reference-manual/protocol/dubbo/guide.md new file mode 100644 index 000000000000..9139650626c4 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/protocol/dubbo/guide.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "使用说明" +linkTitle: "使用说明" +weight: 2 +--- \ No newline at end of file diff --git a/content/zh/docs3-building/java-sdk/reference-manual/protocol/dubbo/overview.md b/content/zh/docs3-building/java-sdk/reference-manual/protocol/dubbo/overview.md new file mode 100644 index 000000000000..d44d924d06f6 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/protocol/dubbo/overview.md @@ -0,0 +1,121 @@ +--- +type: docs +title: "协议概述" +linkTitle: "协议概述" +weight: 1 +--- + + +Dubbo 缺省协议采用单一长连接和 NIO 异步通讯，适合于小数据量大并发的服务调用，以及服务消费者机器数远大于服务提供者机器数的情况。 + +反之，Dubbo 缺省协议不适合传送大数据量的服务，比如传文件，传视频等，除非请求量很低。 + +![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 + +## 特性 + +缺省协议，使用基于 netty `3.2.5.Final` 和 hessian2 `3.2.1-fixed-2(Alibaba embed version)` 的 tbremoting 交互。 + +* 连接个数：单连接 +* 连接方式：长连接 +* 传输协议：TCP +* 传输方式：NIO 异步传输 +* 序列化：Hessian 二进制序列化 +* 适用范围：传入传出参数数据包较小（建议小于100K），消费者比提供者个数多，单一消费者无法压满提供者，尽量不要用 dubbo 协议传输大文件或超大字符串。 +* 适用场景：常规远程服务方法调用 + +## 约束 + +* 参数及返回值需实现 `Serializable` 接口 +* 参数及返回值不能自定义实现 `List`, `Map`, `Number`, `Date`, `Calendar` 等接口，只能用 JDK 自带的实现，因为 hessian 会做特殊处理，自定义实现类中的属性值都会丢失。 +* Hessian 序列化，只传成员属性值和值的类型，不传方法或静态变量，兼容情况 [^1][^2]： + +| 数据通讯 | 情况 | 结果 | +| ------------- | ------------- | ------------- | +| A->B | 类A多一种 属性（或者说类B少一种 属性）| 不抛异常，A多的那 个属性的值，B没有， 其他正常 | +| A->B | 枚举A多一种 枚举（或者说B少一种 枚举），A使用多 出来的枚举进行传输 | 抛异常 | +| A->B | 枚举A多一种 枚举（或者说B少一种 枚举），A不使用 多出来的枚举进行传输 | 不抛异常，B正常接 收数据 | +| A->B | A和B的属性 名相同，但类型不相同 | 抛异常 | +| A->B | serialId 不相同 | 正常传输 | + +接口增加方法，对客户端无影响，如果该方法不是客户端需要的，客户端不需要重新部署。输入参数和结果集中增加属性，对客户端无影响，如果客户端并不需要新属性，不用重新部署。 + +输入参数和结果集属性名变化，对客户端序列化无影响，但是如果客户端不重新部署，不管输入还是输出，属性名变化的属性值是获取不到的。 + +总结：服务器端和客户端对领域对象并不需要完全一致，而是按照最大匹配原则。 + +## 配置 + +配置协议： + +```xml + +``` + +设置默认协议： + +```xml + +``` + +设置某个服务的协议： + +```xml + +``` + +多端口： + +```xml + + +``` + +配置协议选项： + +```xml + +``` + +多连接配置： + +Dubbo 协议缺省每服务每提供者每消费者使用单一长连接，如果数据量较大，可以使用多个连接。 + +```xml + + +``` + +* `` 或 `` 表示该服务使用 JVM 共享长连接。**缺省** +* `` 或 `` 表示该服务使用独立长连接。 +* `` 或`` 表示该服务使用独立两条长连接。 + +为防止被大量连接撑挂，可在服务提供方限制大接收连接数，以实现服务提供方自我保护。 + +```xml + +``` + +## 常见问题 + +#### 为什么要消费者比提供者个数多? + +因 dubbo 协议采用单一长连接，假设网络为千兆网卡 [^3]，根据测试经验数据每条连接最多只能压满 7MByte(不同的环境可能不一样，供参考)，理论上 1 个服务提供者需要 20 个服务消费者才能压满网卡。 + +#### 为什么不能传大包? + +因 dubbo 协议采用单一长连接，如果每次请求的数据包大小为 500KByte，假设网络为千兆网卡 [^3]，每条连接最大 7MByte(不同的环境可能不一样，供参考)，单个服务提供者的 TPS(每秒处理事务数)最大为：128MByte / 500KByte = 262。单个消费者调用单个服务提供者的 TPS(每秒处理事务数)最大为：7MByte / 500KByte = 14。如果能接受，可以考虑使用，否则网络将成为瓶颈。 + +#### 为什么采用异步单一长连接? + +因为服务的现状大都是服务提供者少，通常只有几台机器，而服务的消费者多，可能整个网站都在访问该服务，比如 Morgan 的提供者只有 6 台提供者，却有上百台消费者，每天有 1.5 亿次调用，如果采用常规的 hessian 服务，服务提供者很容易就被压跨，通过单一连接，保证单一消费者不会压死提供者，长连接，减少连接握手验证等，并使用异步 IO，复用线程池，防止 C10K 问题。 + +[^1]: 由吴亚军提供 +[^2]: 总结：会抛异常的情况：枚举值一边多一种，一边少一种，正好使用了差别的那种，或者属性名相同，类型不同 +[^3]: 1024Mbit=128MByte + diff --git a/content/zh/docs3-building/java-sdk/reference-manual/protocol/grpc/_index.md b/content/zh/docs3-building/java-sdk/reference-manual/protocol/grpc/_index.md new file mode 100755 index 000000000000..e4d6450bba8d --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/protocol/grpc/_index.md @@ -0,0 +1,8 @@ + +--- +type: docs +title: "gRPC协议" +linkTitle: "gRPC协议" +weight: 5 +--- + diff --git a/content/zh/docs3-building/java-sdk/reference-manual/protocol/grpc/guide.md b/content/zh/docs3-building/java-sdk/reference-manual/protocol/grpc/guide.md new file mode 100644 index 000000000000..9139650626c4 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/protocol/grpc/guide.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "使用说明" +linkTitle: "使用说明" +weight: 2 +--- \ No newline at end of file diff --git a/content/zh/docs3-building/java-sdk/reference-manual/protocol/grpc/overview.md b/content/zh/docs3-building/java-sdk/reference-manual/protocol/grpc/overview.md new file mode 100644 index 000000000000..d0513b1ffee4 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/protocol/grpc/overview.md @@ -0,0 +1,23 @@ +--- +type: docs +title: "协议概述" +linkTitle: "协议概述" +weight: 1 +--- +Dubbo 自 2.7.5 版本开始支持 gRPC 协议，对于计划使用 HTTP/2 通信，或者想利用 gRPC 带来的 Stream、反压、Reactive 编程等能力的开发者来说， +都可以考虑启用 gRPC 协议。 + +## 支持 gRPC 的好处 +* 为期望使用 gRPC 协议的用户带来服务治理能力，方便接入 Dubbo 体系 +* 用户可以使用 Dubbo 风格的，基于接口的编程风格来定义和使用远程服务 + +## 如何在 Dubbo 中使用 gRPC +大概需要以下步骤： +1. 使用 IDL 定义服务 +2. 配置 compiler 插件，本地预编译 +3. 配置暴露/引用 Dubbo 服务 + +具体可参见以下[示例](https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-grpc) + +除了原生 StreamObserver 接口类型之外，Dubbo 还支持 [RxJava](https://github.com/apache/dubbo-samples/tree/master/java/dubbo-samples-grpc/dubbo-samples-rxjava)、[Reactor](https://github.com/apache/dubbo-samples/tree/master/java/dubbo-samples-grpc/dubbo-samples-reactor) 编程风格的 API + diff --git a/content/zh/docs3-building/java-sdk/reference-manual/protocol/hessian/_index.md b/content/zh/docs3-building/java-sdk/reference-manual/protocol/hessian/_index.md new file mode 100755 index 000000000000..18343fa8acaf --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/protocol/hessian/_index.md @@ -0,0 +1,8 @@ + +--- +type: docs +title: "Hessian协议" +linkTitle: "Hessian协议" +weight: 10 +--- + diff --git a/content/zh/docs3-building/java-sdk/reference-manual/protocol/hessian/guide.md b/content/zh/docs3-building/java-sdk/reference-manual/protocol/hessian/guide.md new file mode 100644 index 000000000000..298e971e394b --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/protocol/hessian/guide.md @@ -0,0 +1,74 @@ +--- +type: docs +title: "使用说明" +linkTitle: "使用说明" +weight: 2 +--- + + +Hessian [^1] 协议用于集成 Hessian 的服务，Hessian 底层采用 Http 通讯，采用 Servlet 暴露服务，Dubbo 缺省内嵌 Jetty 作为服务器实现。 + +Dubbo 的 Hessian 协议可以和原生 Hessian 服务互操作，即： + +* 提供者用 Dubbo 的 Hessian 协议暴露服务，消费者直接用标准 Hessian 接口调用 +* 或者提供方用标准 Hessian 暴露服务，消费方用 Dubbo 的 Hessian 协议调用。 + +## 特性 + +* 连接个数：多连接 +* 连接方式：短连接 +* 传输协议：HTTP +* 传输方式：同步传输 +* 序列化：Hessian二进制序列化 +* 适用范围：传入传出参数数据包较大，提供者比消费者个数多，提供者压力较大，可传文件。 +* 适用场景：页面传输，文件传输，或与原生hessian服务互操作 + +## 依赖 + +```xml + + com.caucho + hessian + 4.0.7 + +``` + +## 约束 + +* 参数及返回值需实现 `Serializable` 接口 +* 参数及返回值不能自定义实现 `List`, `Map`, `Number`, `Date`, `Calendar` 等接口，只能用 JDK 自带的实现，因为 hessian 会做特殊处理，自定义实现类中的属性值都会丢失。 + +## 配置 + +定义 hessian 协议： + +```xml + +``` + +设置默认协议： + +```xml + +``` + +设置 service 协议： + +```xml + +``` + +多端口： + +```xml + + +``` + +直连： + +```xml + +``` + +[^1]: [Hessian](http://hessian.caucho.com) 是 Caucho 开源的一个 RPC 框架，其通讯效率高于 WebService 和 Java 自带的序列化。 diff --git a/content/zh/docs3-building/java-sdk/reference-manual/protocol/hessian/overview.md b/content/zh/docs3-building/java-sdk/reference-manual/protocol/hessian/overview.md new file mode 100644 index 000000000000..ed5e7234ba58 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/protocol/hessian/overview.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "协议概述" +linkTitle: "协议概述" +weight: 1 +--- diff --git a/content/zh/docs3-building/java-sdk/reference-manual/protocol/http/_index.md b/content/zh/docs3-building/java-sdk/reference-manual/protocol/http/_index.md new file mode 100755 index 000000000000..8eb15efafa13 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/protocol/http/_index.md @@ -0,0 +1,8 @@ + +--- +type: docs +title: "HTTP协议" +linkTitle: "HTTP协议" +weight: 6 +--- + diff --git a/content/zh/docs3-building/java-sdk/reference-manual/protocol/http/guide.md b/content/zh/docs3-building/java-sdk/reference-manual/protocol/http/guide.md new file mode 100644 index 000000000000..9e7bdec34198 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/protocol/http/guide.md @@ -0,0 +1,65 @@ +--- +type: docs +title: "使用说明" +linkTitle: "使用说明" +weight: 2 +--- + + +基于 HTTP 表单的远程调用协议，采用 Spring 的 HttpInvoker 实现 + +{{% alert title="提示" color="primary" %}} +`2.3.0` 以上版本支持 +{{% /alert %}} + +## 特性 + +* 连接个数：多连接 +* 连接方式：短连接 +* 传输协议：HTTP +* 传输方式：同步传输 +* 序列化：表单序列化 +* 适用范围：传入传出参数数据包大小混合，提供者比消费者个数多，可用浏览器查看，可用表单或URL传入参数，暂不支持传文件。 +* 适用场景：需同时给应用程序和浏览器 JS 使用的服务。 + +## 约束 +* 参数及返回值需符合 Bean 规范 + +## 配置 + +配置协议： + +```xml + +``` + +配置 Jetty Server (默认)： + +```xml + +``` + +配置 Servlet Bridge Server (推荐使用)： + +```xml + +``` + +配置 DispatcherServlet： + +```xml + + dubbo + org.apache.dubbo.remoting.http.servlet.DispatcherServlet + 1 + + + dubbo + /* + +``` + +注意，如果使用 servlet 派发请求： + +* 协议的端口 `` 必须与 servlet 容器的端口相同， +* 协议的上下文路径 `` 必须与 servlet 应用的上下文路径相同。 diff --git a/content/zh/docs3-building/java-sdk/reference-manual/protocol/http/overview.md b/content/zh/docs3-building/java-sdk/reference-manual/protocol/http/overview.md new file mode 100644 index 000000000000..ed5e7234ba58 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/protocol/http/overview.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "协议概述" +linkTitle: "协议概述" +weight: 1 +--- diff --git a/content/zh/docs3-building/java-sdk/reference-manual/protocol/memcached/_index.md b/content/zh/docs3-building/java-sdk/reference-manual/protocol/memcached/_index.md new file mode 100755 index 000000000000..b248e53ad669 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/protocol/memcached/_index.md @@ -0,0 +1,8 @@ + +--- +type: docs +title: "Memcached协议" +linkTitle: "Memcached协议" +weight: 12 +--- + diff --git a/content/zh/docs3-building/java-sdk/reference-manual/protocol/memcached/guide.md b/content/zh/docs3-building/java-sdk/reference-manual/protocol/memcached/guide.md new file mode 100644 index 000000000000..9139650626c4 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/protocol/memcached/guide.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "使用说明" +linkTitle: "使用说明" +weight: 2 +--- \ No newline at end of file diff --git a/content/zh/docs3-building/java-sdk/reference-manual/protocol/memcached/overview.md b/content/zh/docs3-building/java-sdk/reference-manual/protocol/memcached/overview.md new file mode 100644 index 000000000000..ed5e7234ba58 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/protocol/memcached/overview.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "协议概述" +linkTitle: "协议概述" +weight: 1 +--- diff --git a/content/zh/docs3-building/java-sdk/reference-manual/protocol/overview/_index.md b/content/zh/docs3-building/java-sdk/reference-manual/protocol/overview/_index.md new file mode 100644 index 000000000000..94ca217e236c --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/protocol/overview/_index.md @@ -0,0 +1,200 @@ +--- +type: docs +title: "协议概述" +linkTitle: "协议概述" +weight: 1 +--- + +Dubbo3 提供了 Triple(Dubbo3)、Dubbo2 协议，这是 Dubbo 框架的原生协议。除此之外，Dubbo3 也对众多第三方协议进行了集成，并将它们纳入 Dubbo 的编程与服务治理体系， +包括 gRPC、Thrift、JsonRPC、Hessian2、REST 等。以下重点介绍 Triple 与 Dubbo2 协议。 + +## Triple 协议 + +Triple 协议是 Dubbo3 推出的主力协议。Triple 意为第三代，通过 Dubbo1.0/ Dubbo2.0 两代协议的演进，以及云原生带来的技术标准化浪潮，Dubbo3 新协议 Triple 应运而生。 + +### RPC 协议的选择 + +协议是 RPC 的核心，它规范了数据在网络中的传输内容和格式。除必须的请求、响应数据外，通常还会包含额外控制数据，如单次请求的序列化方式、超时时间、压缩方式和鉴权信息等。 + +协议的内容包含三部分 +- 数据交换格式： 定义 RPC 的请求和响应对象在网络传输中的字节流内容，也叫作序列化方式 +- 协议结构： 定义包含字段列表和各字段语义以及不同字段的排列方式 +- 协议通过定义规则、格式和语义来约定数据如何在网络间传输。一次成功的 RPC 需要通信的两端都能够按照协议约定进行网络字节流的读写和对象转换。如果两端对使用的协议不能达成一致，就会出现鸡同鸭讲，无法满足远程通信的需求。 + +![协议选择](/imgs/v3/concepts/triple-protocol.png) + +RPC 协议的设计需要考虑以下内容： +- 通用性： 统一的二进制格式，跨语言、跨平台、多传输层协议支持 +- 扩展性： 协议增加字段、升级、支持用户扩展和附加业务元数据 +- 性能：As fast as it can be +- 穿透性：能够被各种终端设备识别和转发：网关、代理服务器等 + 通用性和高性能通常无法同时达到，需要协议设计者进行一定的取舍。 + +#### HTTP/1.1 + +比于直接构建于 TCP 传输层的私有 RPC 协议，构建于 HTTP 之上的远程调用解决方案会有更好的通用性，如WebServices 或 REST 架构，使用 HTTP + JSON 可以说是一个事实标准的解决方案。 + +选择构建在 HTTP 之上，有两个最大的优势： + +- HTTP 的语义和可扩展性能很好的满足 RPC 调用需求。 +- 通用性，HTTP 协议几乎被网络上的所有设备所支持，具有很好的协议穿透性。 + +但也存在比较明显的问题： + +- 典型的 Request – Response 模型，一个链路上一次只能有一个等待的 Request 请求。会产生 HOL。 +- Human Readable Headers，使用更通用、更易于人类阅读的头部传输格式，但性能相当差 +- 无直接 Server Push 支持，需要使用 Polling Long-Polling 等变通模式 + +#### gRPC +上面提到了在 HTTP 及 TCP 协议之上构建 RPC 协议各自的优缺点，相比于 Dubbo 构建于 TCP 传输层之上，Google 选择将 gRPC 直接定义在 HTTP/2 协议之上。 +gRPC 的优势由HTTP2 和 Protobuf 继承而来。 + +- 基于 HTTP2 的协议足够简单，用户学习成本低，天然有 server push/ 多路复用 / 流量控制能力 +- 基于 Protobuf 的多语言跨平台二进制兼容能力，提供强大的统一跨语言能力 +- 基于协议本身的生态比较丰富，k8s/etcd 等组件的天然支持协议，云原生的事实协议标准 + +但是也存在部分问题 + +- 对服务治理的支持比较基础，更偏向于基础的 RPC 功能，协议层缺少必要的统一定义，对于用户而言直接用起来并不容易。 +- 强绑定 protobuf 的序列化方式，需要较高的学习成本和改造成本，对于现有的偏单语言的用户而言，迁移成本不可忽视 + +#### 最终的选择 Triple +最终我们选择了兼容 gRPC ，以 HTTP2 作为传输层构建新的协议，也就是 Triple。 + +容器化应用程序和微服务的兴起促进了针对负载内容优化技术的发展。 客户端中使用的传统通信协议（ RESTFUL或其他基于 HTTP 的自定义协议）难以满足应用在性能、可维护性、扩展性、安全性等方便的需求。一个跨语言、模块化的协议会逐渐成为新的应用开发协议标准。自从 2017 年 gRPC 协议成为 CNCF 的项目后，包括 k8s、etcd 等越来越多的基础设施和业务都开始使用 gRPC 的生态，作为云原生的微服务化框架， Dubbo 的新协议也完美兼容了 gRPC。并且，对于 gRPC 协议中一些不完善的部分， Triple 也将进行增强和补充。 + +那么，Triple 协议是否解决了上面我们提到的一系列问题呢？ + +- 性能上: Triple 协议采取了 metadata 和 payload 分离的策略，这样就可以避免中间设备，如网关进行 payload 的解析和反序列化，从而降低响应时间。 +- 路由支持上，由于 metadata 支持用户添加自定义 header ，用户可以根据 header 更方便的划分集群或者进行路由，这样发布的时候切流灰度或容灾都有了更高的灵活性。 +- 安全性上，支持双向TLS认证（mTLS）等加密传输能力。 +- 易用性上，Triple 除了支持原生 gRPC 所推荐的 Protobuf 序列化外，使用通用的方式支持了 Hessian / JSON 等其他序列化，能让用户更方便的升级到 Triple 协议。对原有的 Dubbo 服务而言，修改或增加 Triple 协议 只需要在声明服务的代码块添加一行协议配置即可，改造成本几乎为 0。 + +### Triple 协议 + +![Triple 协议通信方式](/imgs/v3/concepts/triple.png) + +- 现状 + +1、完整兼容grpc、客户端/服务端可以与原生grpc客户端打通 + +2、目前已经经过大规模生产实践验证，达到生产级别 + +- 特点与优势 + +1、具备跨语言互通的能力，传统的多语言多 SDK 模式和 Mesh 化跨语言模式都需要一种更通用易扩展的数据传输格式。 + +2、提供更完善的请求模型，除了 Request/Response 模型，还应该支持 Streaming 和 Bidirectional。 + +3、易扩展、穿透性高，包括但不限于 Tracing / Monitoring 等支持，也应该能被各层设备识别，网关设施等可以识别数据报文，对 Service Mesh 部署友好，降低用户理解难度。 + +4、多种序列化方式支持、平滑升级 + +5、支持 Java 用户无感知升级，不需要定义繁琐的 IDL 文件，仅需要简单的修改协议名便可以轻松升级到 Triple 协议 + +#### Triple 协议内容介绍 + +基于 grpc 协议进行进一步扩展 + +- 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} + +其中 Service-Version 跟 Service-Group 分别标识了 Dubbo 服务的 version 跟 group 信息，因为grpc的 path 申明了 service name 跟 method name，相比于 Dubbo 协议，缺少了version 跟 group 信息；Tracing-ID、Tracing-RPC-ID 用于全链路追踪能力，分别表示 tracing id 跟 span id 信息；Cluster-Info 表示集群信息，可以使用其构建一些如集群划分等路由相关的灵活的服务治理能力。 + +#### Triple Streaming + +Triple协议相比传统的unary方式，多了目前提供的Streaming RPC的能力 + +- Streaming 用于什么场景呢？ + +在一些大文件传输、直播等应用场景中， consumer或provider需要跟对端进行大量数据的传输，由于这些情况下的数据量是非常大的，因此是没有办法可以在一个RPC的数据包中进行传输，因此对于这些数据包我们需要对数据包进行分片之后，通过多次RPC调用进行传输，如果我们对这些已经拆分了的RPC数据包进行并行传输，那么到对端后相关的数据包是无序的，需要对接收到的数据进行排序拼接，相关的逻辑会非常复杂。但如果我们对拆分了的RPC数据包进行串行传输，那么对应的网络传输RTT与数据处理的时延会是非常大的。 + +为了解决以上的问题，并且为了大量数据的传输以流水线方式在consumer与provider之间传输，因此Streaming RPC的模型应运而生。 + +通过Triple协议的Streaming RPC方式，会在consumer跟provider之间建立多条用户态的长连接，Stream。同一个TCP连接之上能同时存在多个Stream，其中每条Stream都有StreamId进行标识，对于一条Stream上的数据包会以顺序方式读写。 + +### 总结 + +在API领域，最重要的趋势是标准化技术的崛起。Triple 协议是 Dubbo3 推出的主力协议。它采用分层设计，其数据交换格式基于Protobuf (Protocol Buffers) 协议开发，具备优秀的序列化/反序列化效率，当然还支持多种序列化方式，也支持众多开发语言。在传输层协议，Triple 选择了 HTTP/2，相较于 HTTP/1.1，其传输效率有了很大提升。此外HTTP/2作为一个成熟的开放标准，具备丰富的安全、流控等能力，同时拥有良好的互操作性。Triple 不仅可以用于Server端服务调用，也可以支持浏览器、移动App和IoT设备与后端服务的交互，同时 Triple协议无缝支持 Dubbo3 的全部服务治理能力。 + +在Cloud Native的潮流下，跨平台、跨厂商、跨环境的系统间互操作性的需求必然会催生基于开放标准的RPC技术，而gRPC顺应了历史趋势，得到了越来越广泛地应用。在微服务领域，Triple协议的提出与落地，是 Dubbo3 迈向云原生微服务的一大步。 + +## 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 bit) + + 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. + + +**注意：** 对于(Variable Part)变长部分，当前版本的dubbo框架使用json序列化时，在每部分内容间额外增加了换行符作为分隔，请选手在Variable Part的每个part后额外增加换行符， 如： +``` +Dubbo version bytes (换行符) +Service name bytes (换行符) +... +``` diff --git a/content/zh/docs3-building/java-sdk/reference-manual/protocol/redis/_index.md b/content/zh/docs3-building/java-sdk/reference-manual/protocol/redis/_index.md new file mode 100755 index 000000000000..78fd3ab2cc26 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/protocol/redis/_index.md @@ -0,0 +1,8 @@ + +--- +type: docs +title: "Redis协议" +linkTitle: "Redis协议" +weight: 9 +--- + diff --git a/content/zh/docs3-building/java-sdk/reference-manual/protocol/redis/guide.md b/content/zh/docs3-building/java-sdk/reference-manual/protocol/redis/guide.md new file mode 100644 index 000000000000..4430aea86cfd --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/protocol/redis/guide.md @@ -0,0 +1,53 @@ +--- +type: docs +title: "使用说明" +linkTitle: "使用说明" +weight: 2 +--- + + +基于 Redis [^1] 实现的 RPC 协议。 + +{{% alert title="提示" color="primary" %}} +`2.3.0` 以上版本支持 +{{% /alert %}} + +## 注册 redis 服务的地址 + +```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")); +``` + +## 在客户端引用 + +在客户端使用 [^2]： + +```xml + +``` + +或者，点对点直连： + +```xml + +``` + +也可以使用自定义接口： + +```xml + +``` + +方法名建议和 redis 的标准方法名相同，即：get(key), set(key, value), delete(key)。 + +如果方法名和 redis 的标准方法名不相同，则需要配置映射关系 [^3]： + +```xml + +``` + +[^1]: [Redis](http://redis.io) 是一个高效的 KV 存储服务器 +[^2]: 不需要感知 Redis 的地址 +[^3]: 其中 "p:xxx" 为 spring 的标准 p 标签 diff --git a/content/zh/docs3-building/java-sdk/reference-manual/protocol/redis/overview.md b/content/zh/docs3-building/java-sdk/reference-manual/protocol/redis/overview.md new file mode 100644 index 000000000000..ed5e7234ba58 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/protocol/redis/overview.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "协议概述" +linkTitle: "协议概述" +weight: 1 +--- diff --git a/content/zh/docs3-building/java-sdk/reference-manual/protocol/rest/_index.md b/content/zh/docs3-building/java-sdk/reference-manual/protocol/rest/_index.md new file mode 100755 index 000000000000..d48e3e9fbf50 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/protocol/rest/_index.md @@ -0,0 +1,8 @@ + +--- +type: docs +title: "Rest协议" +linkTitle: "Rest协议" +weight: 4 +--- + diff --git a/content/zh/docs3-building/java-sdk/reference-manual/protocol/rest/guide.md b/content/zh/docs3-building/java-sdk/reference-manual/protocol/rest/guide.md new file mode 100644 index 000000000000..9139650626c4 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/protocol/rest/guide.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "使用说明" +linkTitle: "使用说明" +weight: 2 +--- \ No newline at end of file diff --git a/content/zh/docs3-building/java-sdk/reference-manual/protocol/rest/overview.md b/content/zh/docs3-building/java-sdk/reference-manual/protocol/rest/overview.md new file mode 100644 index 000000000000..35a818058cfe --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/protocol/rest/overview.md @@ -0,0 +1,1243 @@ +--- +type: docs +title: "协议概述" +linkTitle: "协议概述" +weight: 1 +--- + + +{{% pageinfo %}} +作者：沈理 + +文档版权：[Apache 2.0许可证 署名-禁止演绎](http://www.apache.org/licenses/LICENSE-2.0) + +本文篇幅较长，因为REST本身涉及面较多。另外，本文参照 Spring 等的文档风格，不仅仅局限于框架用法的阐述，同时也努力呈现框架的设计理念和优良应用的架构思想。 +对于想粗略了解 dubbo 和 REST 的人，只需浏览 概述 至 标准Java REST API：JAX-RS简介 几节即可。 +{{% /pageinfo %}} + + + +## 目录 + +* 概述 +* REST的优点 +* 应用场景 +* 快速入门 +* 标准Java REST API：JAX-RS简介 +* REST服务提供端详解 + * HTTP POST/GET的实现 + * Annotation放在接口类还是实现类 + * JSON、XML等多数据格式的支持 + * 中文字符支持 + * XML数据格式的额外要求 + * 定制序列化 + * 配置REST Server的实现 + * 获取上下文（Context）信息 + * 配置端口号和Context Path + * 配置线程数和IO线程数 + * 配置长连接 + * 配置最大的HTTP连接数 + * 配置每个消费端的超时时间和HTTP连接数 + * GZIP数据压缩 + * 用Annotation取代部分Spring XML配置 + * 添加自定义的Filter、Interceptor等 + * 添加自定义的Exception处理 + * 配置HTTP日志输出 + * 输入参数的校验 + * 是否应该透明发布REST服务 + * Dubbo的REST提供端在被调用时使用header +* REST服务消费端详解 + * 场景1：非dubbo的消费端调用dubbo的REST服务 + * 场景2：dubbo消费端调用dubbo的REST服务 + * 场景3：dubbo的消费端调用非dubbo的REST服务 + * Dubbo的消费端在调用REST服务时配置自定义header +* Dubbo中JAX-RS的限制 +* REST常见问题解答（REST FAQ） + * Dubbo REST的服务能和Dubbo注册中心、监控中心集成吗？ + * Dubbo REST中如何实现负载均衡和容错（failover）？ + * JAX-RS中重载的方法能够映射到同一URL地址吗？ + * JAX-RS中作POST的方法能够接收多个参数吗？ +* Dubbo当前体系可能的不足之处（与REST相关的） + * RpcContext的侵入性 + * Protocol配置的局限性 + * XML命名不符合spring规范 +* REST最佳实践 +* 性能基准测试 + * 测试环境 + * 测试脚本 + * 测试结果 +* 扩展讨论 + * REST与Thrift、Protobuf等的对比 + * REST与传统WebServices的对比 + * JAX-RS与Spring MVC的对比 +* 未来 + +## 概述 + +dubbo支持多种远程调用方式，例如dubbo RPC（二进制序列化 + tcp协议）、http invoker（二进制序列化 + http协议，至少在开源版本没发现对文本序列化的支持）、hessian（二进制序列化 + http协议）、WebServices （文本序列化 + http协议）等等，但缺乏对当今特别流行的REST风格远程调用（文本序列化 + http协议）的支持。 + +有鉴于此，我们基于标准的Java REST API——JAX-RS 2.0（Java API for RESTful Web Services的简写），为dubbo提供了接近透明的REST调用支持。由于完全兼容Java标准API，所以为dubbo开发的所有REST服务，未来脱离dubbo或者任何特定的REST底层实现一般也可以正常运行。 + +特别值得指出的是，我们并不需要完全严格遵守REST的原始定义和架构风格。即使著名的Twitter REST API也会根据情况做适度调整，而不是机械的遵守原始的REST风格。 + +> 附注：我们将这个功能称之为REST风格的远程调用，即RESTful Remoting（抽象的远程处理或者调用），而不是叫RESTful RPC（具体的远程“过程”调用），是因为REST和RPC本身可以被认为是两种不同的风格。在dubbo的REST实现中，可以说有两个面向，其一是提供或消费正常的REST服务，其二是将REST作为dubbo RPC体系中一种协议实现，而RESTful Remoting同时涵盖了这两个面向。 + +## REST的优点 + +以下摘自维基百科： + +* 可更高效利用缓存来提高响应速度 +* 通讯本身的无状态性可以让不同的服务器的处理一系列请求中的不同请求，提高服务器的扩展性 +* 浏览器即可作为客户端，简化软件需求 +* 相对于其他叠加在HTTP协议之上的机制，REST的软件依赖性更小 +* 不需要额外的资源发现机制 +* 在软件技术演进中的长期的兼容性更好 + +这里我还想特别补充REST的显著优点：基于简单的文本格式消息和通用的HTTP协议，使它具备极广的适用性，几乎所有语言和平台都对它提供支持，同时其学习和使用的门槛也较低。 + +## 应用场景 + +正是由于REST在适用性方面的优点，所以在dubbo中支持REST，可以为当今多数主流的远程调用场景都带来（显著）好处： + +1. 显著简化企业内部的异构系统之间的（跨语言）调用。此处主要针对这种场景：dubbo的系统做服务提供端，其他语言的系统（也包括某些不基于dubbo的java系统）做服务消费端，两者通过HTTP和文本消息进行通信。即使相比Thrift、ProtoBuf等二进制跨语言调用方案，REST也有自己独特的优势（详见后面讨论） + +2. 显著简化对外Open API（开放平台）的开发。既可以用dubbo来开发专门的Open API应用，也可以将原内部使用的dubbo service直接“透明”发布为对外的Open REST API（当然dubbo本身未来最好可以较透明的提供诸如权限控制、频次控制、计费等诸多功能） + +3. 显著简化手机（平板）APP或者PC桌面客户端开发。类似于2，既可以用dubbo来开发专门针对无线或者桌面的服务器端，也可以将原内部使用的dubbo service直接”透明“的暴露给手机APP或桌面程序。当然在有些项目中，手机或桌面程序也可以直接访问以上场景2中所述的Open API。 + +4. 显著简化浏览器AJAX应用的开发。类似于2，既可以用dubbo来开发专门的AJAX服务器端，也可以将原内部使用的dubbo service直接”透明“的暴露给浏览器中JavaScript。当然，很多AJAX应用更适合与web框架协同工作，所以直接访问dubbo service在很多web项目中未必是一种非常优雅的架构。 + +5. 为企业内部的dubbo系统之间（即服务提供端和消费端都是基于dubbo的系统）提供一种基于文本的、易读的远程调用方式。 + +6. 一定程度简化dubbo系统对其它异构系统的调用。可以用类似dubbo的简便方式“透明”的调用非dubbo系统提供的REST服务（不管服务提供端是在企业内部还是外部） + +需要指出的是，我认为1～3是dubbo的REST调用最有价值的三种应用场景，并且我们为dubbo添加REST调用，其最主要到目的也是面向服务的提供端，即开发REST服务来提供给非dubbo的（异构）消费端。 + +归纳起来，所有应用场景如下图所示： +![rest](/imgs/user/rest.jpg) + +借用Java过去最流行的宣传语，为dubbo添加REST调用后，可以实现服务的”一次编写，到处访问“，理论上可以面向全世界开放，从而真正实现比较理想化的面向服务架构（SOA）。 + +当然，传统的WebServices（WSDL/SOAP）也基本同样能满足以上场景（除了场景4）的要求（甚至还能满足那些需要企业级特性的场景），但由于其复杂性等问题，现在已经越来越少被实际采用了。 + +## 快速入门 + +在dubbo中开发一个REST风格的服务会比较简单，下面以一个注册用户的简单服务为例说明。 + +这个服务要实现的功能是提供如下URL（注：这个URL不是完全符合REST的风格，但是更简单实用）： + +``` +http://localhost:8080/users/register +``` + +而任何客户端都可以将包含用户信息的JSON字符串POST到以上URL来完成用户注册。 + +首先，开发服务的接口： + +```java +public interface UserService { + void registerUser(User user); +} +``` + +然后，开发服务的实现： + +```java +@Path("users") +public class UserServiceImpl implements UserService { + + @POST + @Path("register") + @Consumes({MediaType.APPLICATION_JSON}) + public void registerUser(User user) { + // save the user... + } +} +``` +上面的服务实现代码非常简单，但是由于REST服务是要被发布到特定HTTP URL，供任意语言客户端甚至浏览器来访问，所以这里要额外添加了几个JAX-RS的标准annotation来做相关的配置： + +@Path("users")：指定访问UserService的URL相对路径是/users，即http://localhost:8080/users + +@Path("register")：指定访问registerUser()方法的URL相对路径是/register，再结合上一个@Path为UserService指定的路径，则调用UserService.register()的完整路径为http://localhost:8080/users/register + +@POST：指定访问registerUser()用HTTP POST方法 + +@Consumes({MediaType.APPLICATION_JSON})：指定registerUser()接收JSON格式的数据。REST框架会自动将JSON数据反序列化为User对象 + +最后，在spring配置文件中添加此服务，即完成所有服务开发工作： + + ```xml + + + + + + + + +``` + +## 标准Java REST API：JAX-RS简介 + +JAX-RS是标准的Java REST API，得到了业界的广泛支持和应用，其著名的开源实现就有很多，包括Oracle的Jersey，RedHat的RestEasy，Apache的CXF和Wink，以及restlet等等。另外，所有支持JavaEE 6.0以上规范的商用JavaEE应用服务器都对JAX-RS提供了支持。因此，JAX-RS是一种已经非常成熟的解决方案，并且采用它没有任何所谓vendor lock-in的问题。 + +JAX-RS在网上的资料非常丰富，例如下面的入门教程： + +* Oracle官方的tutorial：http://docs.oracle.com/javaee/7/tutorial/doc/jaxrs.htm +* IBM developerWorks中国站文章：http://www.ibm.com/developerworks/cn/java/j-lo-jaxrs/ + +更多的资料请自行google或者百度一下。就学习JAX-RS来说，一般主要掌握其各种annotation的用法即可。 + +> 注意：dubbo是基于JAX-RS 2.0版本的，有时候需要注意一下资料或REST实现所涉及的版本。 + +## REST服务提供端详解 + +下面我们扩充“快速入门”中的UserService，进一步展示在dubbo中REST服务提供端的开发要点。 + +### HTTP POST/GET的实现 + +REST服务中虽然建议使用HTTP协议中四种标准方法POST、DELETE、PUT、GET来分别实现常见的“增删改查”，但实际中，我们一般情况直接用POST来实现“增改”，GET来实现“删查”即可（DELETE和PUT甚至会被一些防火墙阻挡）。 + +前面已经简单演示了POST的实现，在此，我们为UserService添加一个获取注册用户资料的功能，来演示GET的实现。 + +这个功能就是要实现客户端通过访问如下不同URL来获取不同ID的用户资料： + +``` +http://localhost:8080/users/1001 +http://localhost:8080/users/1002 +http://localhost:8080/users/1003 +``` + +当然，也可以通过其他形式的URL来访问不同ID的用户资料，例如： + +``` +http://localhost:8080/users/load?id=1001 +``` + +JAX-RS本身可以支持所有这些形式。但是上面那种在URL路径中包含查询参数的形式（http://localhost:8080/users/1001） 更符合REST的一般习惯，所以更推荐大家来使用。下面我们就为UserService添加一个getUser()方法来实现这种形式的URL访问： + +```java +@GET +@Path("{id : \\d+}") +@Produces({MediaType.APPLICATION_JSON}) +public User getUser(@PathParam("id") Long id) { + // ... +} +``` + +@GET：指定用HTTP GET方法访问 + +@Path("{id : \\d+}")：根据上面的功能需求，访问getUser()的URL应当是“http://localhost:8080/users/ + 任意数字"，并且这个数字要被做为参数传入getUser()方法。 这里的annotation配置中，@Path中间的{id: xxx}指定URL相对路径中包含了名为id参数，而它的值也将被自动传递给下面用@PathParam("id")修饰的方法参数id。{id:后面紧跟的\\d+是一个正则表达式，指定了id参数必须是数字。 + +@Produces({MediaType.APPLICATION_JSON})：指定getUser()输出JSON格式的数据。框架会自动将User对象序列化为JSON数据。 + +### Annotation放在接口类还是实现类 + +在Dubbo中开发REST服务主要都是通过JAX-RS的annotation来完成配置的，在上面的示例中，我们都是将annotation放在服务的实现类中。但其实，我们完全也可以将annotation放到服务的接口上，这两种方式是完全等价的，例如： + +```java +@Path("users") +public interface UserService { + + @GET + @Path("{id : \\d+}") + @Produces({MediaType.APPLICATION_JSON}) + User getUser(@PathParam("id") Long id); +} +``` + +在一般应用中，我们建议将annotation放到服务实现类，这样annotation和java实现代码位置更接近，更便于开发和维护。另外更重要的是，我们一般倾向于避免对接口的污染，保持接口的纯净性和广泛适用性。 + +但是，如后文所述，如果我们要用dubbo直接开发的消费端来访问此服务，则annotation必须放到接口上。 + +如果接口和实现类都同时添加了annotation，则实现类的annotation配置会生效，接口上的annotation被直接忽略。 + +### JSON、XML等多数据格式的支持 + +在dubbo中开发的REST服务可以同时支持传输多种格式的数据，以给客户端提供最大的灵活性。其中我们目前对最常用的JSON和XML格式特别添加了额外的功能。 + +比如，我们要让上例中的getUser()方法支持分别返回JSON和XML格式的数据，只需要在annotation中同时包含两种格式即可： + +```java +@Produces({MediaType.APPLICATION_JSON, MediaType.TEXT_XML}) +User getUser(@PathParam("id") Long id); +``` + +或者也可以直接用字符串（还支持通配符）表示MediaType： + +```java +@Produces({"application/json", "text/xml"}) +User getUser(@PathParam("id") Long id); +``` + +如果所有方法都支持同样类型的输入输出数据格式，则我们无需在每个方法上做配置，只需要在服务类上添加annotation即可： + +```java +@Path("users") +@Consumes({MediaType.APPLICATION_JSON, MediaType.TEXT_XML}) +@Produces({MediaType.APPLICATION_JSON, MediaType.TEXT_XML}) +public class UserServiceImpl implements UserService { + // ... +} + +``` + +在一个REST服务同时对多种数据格式支持的情况下，根据JAX-RS标准，一般是通过HTTP中的MIME header（content-type和accept）来指定当前想用的是哪种格式的数据。 + +但是在dubbo中，我们还自动支持目前业界普遍使用的方式，即用一个URL后缀（.json和.xml）来指定想用的数据格式。例如，在添加上述annotation后，直接访问http://localhost:8888/users/1001.json则表示用json格式，直接访问http://localhost:8888/users/1002.xml则表示用xml格式，比用HTTP Header更简单直观。Twitter、微博等的REST API都是采用这种方式。 + +如果你既不加HTTP header，也不加后缀，则dubbo的REST会优先启用在以上annotation定义中排位最靠前的那种数据格式。 + +> 注意：这里要支持XML格式数据，在annotation中既可以用MediaType.TEXT_XML，也可以用MediaType.APPLICATION_XML，但是TEXT_XML是更常用的，并且如果要利用上述的URL后缀方式来指定数据格式，只能配置为TEXT_XML才能生效。 + +### 中文字符支持 + +为了在dubbo REST中正常输出中文字符，和通常的Java web应用一样，我们需要将HTTP响应的contentType设置为UTF-8编码。 + +基于JAX-RS的标准用法，我们只需要做如下annotation配置即可： + +```java +@Produces({"application/json; charset=UTF-8", "text/xml; charset=UTF-8"}) +User getUser(@PathParam("id") Long id); +``` + +为了方便用户，我们在dubbo REST中直接添加了一个支持类，来定义以上的常量，可以直接使用，减少出错的可能性。 + +```java +@Produces({ContentType.APPLICATION_JSON_UTF_8, ContentType.TEXT_XML_UTF_8}) +User getUser(@PathParam("id") Long id); +``` + +### XML数据格式的额外要求 + +由于JAX-RS的实现一般都用标准的JAXB（Java API for XML Binding）来序列化和反序列化XML格式数据，所以我们需要为每一个要用XML传输的对象添加一个类级别的JAXB annotation，否则序列化将报错。例如为getUser()中返回的User添加如下： + +```java +@XmlRootElement +public class User implements Serializable { + // ... +} +``` + +此外，如果service方法中的返回值是Java的 primitive类型（如int，long，float，double等），最好为它们添加一层wrapper对象，因为JAXB不能直接序列化primitive类型。 + +例如，我们想让前述的registerUser()方法返回服务器端为用户生成的ID号： + +```java +long registerUser(User user); +``` + +由于primitive类型不被JAXB序列化支持，所以添加一个wrapper对象： + +```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; + } +} +``` + +并修改service方法： + +```java +RegistrationResult registerUser(User user); +``` + +这样不但能够解决XML序列化的问题，而且使得返回的数据都符合XML和JSON的规范。例如，在JSON中，返回的将是如下形式： + +```javascript +{"id": 1001} +``` + +如果不加wrapper，JSON返回值将直接是 + +``` +1001 +``` + +而在XML中，加wrapper后返回值将是： + +```xml + + 1002 + +``` + +这种wrapper对象其实利用所谓Data Transfer Object（DTO）模式，采用DTO还能对传输数据做更多有用的定制。 + +### 定制序列化 + +如上所述，REST的底层实现会在service的对象和JSON/XML数据格式之间自动做序列化/反序列化。但有些场景下，如果觉得这种自动转换不满足要求，可以对其做定制。 + +Dubbo中的REST实现是用JAXB做XML序列化，用Jackson做JSON序列化，所以在对象上添加JAXB或Jackson的annotation即可以定制映射。 + +例如，定制对象属性映射到XML元素的名字： + +```java +@XmlRootElement +@XmlAccessorType(XmlAccessType.FIELD) +public class User implements Serializable { + + @XmlElement(name="username") + private String name; +} +``` + +定制对象属性映射到JSON字段的名字： + +```java +public class User implements Serializable { + + @JsonProperty("username") + private String name; +} +``` + +更多资料请参考JAXB和Jackson的官方文档，或自行google。 + +### 配置REST Server的实现 + +目前在dubbo中，我们支持5种嵌入式rest server的实现，并同时支持采用外部应用服务器来做rest server的实现。rest server的实现是通过如下server这个XML属性来选择的： + +```xml + +``` + +以上配置选用了嵌入式的jetty来做rest server，同时，如果不配置server属性，rest协议默认也是选用jetty。jetty是非常成熟的java servlet容器，并和dubbo已经有较好的集成（目前5种嵌入式server中只有jetty和后面所述的tomcat、tjws，与dubbo监控系统等完成了无缝的集成），所以，如果你的dubbo系统是单独启动的进程，你可以直接默认采用jetty即可。 + + +```xml + +``` + +以上配置选用了嵌入式的tomcat来做rest server。在嵌入式tomcat上，REST的性能比jetty上要好得多（参见后面的基准测试），建议在需要高性能的场景下采用tomcat。 + +```xml + +``` + +以上配置选用嵌入式的netty来做rest server。（TODO more contents to add） + +```xml + (tjws is now deprecated) + +``` + +以上配置选用嵌入式的tjws或Sun HTTP server来做rest server。这两个server实现非常轻量级，非常方便在集成测试中快速启动使用，当然也可以在负荷不高的生产环境中使用。 注：tjws目前已经被deprecated掉了，因为它不能很好的和servlet 3.1 API工作。 + +如果你的dubbo系统不是单独启动的进程，而是部署到了Java应用服务器中，则建议你采用以下配置： + +```xml + +``` + +通过将server设置为servlet，dubbo将采用外部应用服务器的servlet容器来做rest server。同时，还要在dubbo系统的web.xml中添加如下配置： + +```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 + /* + + +``` + +即必须将dubbo的BootstrapListener和DispatherServlet添加到web.xml，以完成dubbo的REST功能与外部servlet容器的集成。 + +> 注意：如果你是用spring的ContextLoaderListener来加载spring，则必须保证BootstrapListener配置在ContextLoaderListener之前，否则dubbo初始化会出错。 + +其实，这种场景下你依然可以坚持用嵌入式server，但外部应用服务器的servlet容器往往比嵌入式server更加强大（特别是如果你是部署到更健壮更可伸缩的WebLogic，WebSphere等），另外有时也便于在应用服务器做统一管理、监控等等。 + +### 获取上下文（Context）信息 + +在远程调用中，值得获取的上下文信息可能有很多种，这里特别以获取客户端IP为例。 + +在dubbo的REST中，我们有两种方式获取客户端IP。 + +第一种方式，用JAX-RS标准的@Context annotation： + +```java +public User getUser(@PathParam("id") Long id, @Context HttpServletRequest request) { + System.out.println("Client address is " + request.getRemoteAddr()); +} +``` + +用Context修饰getUser()的一个方法参数后，就可以将当前的HttpServletRequest注入进来，然后直接调用servlet api获取IP。 + +> 注意：这种方式只能在设置server="tjws"或者server="tomcat"或者server="jetty"或者server="servlet"的时候才能工作，因为只有这几种REST server的实现才提供了servlet容器。另外，标准的JAX-RS还支持用@Context修饰service类的一个实例字段来获取HttpServletRequest，但在dubbo中我们没有对此作出支持。 + +第二种方式，用dubbo中常用的RpcContext： + +```java +public User getUser(@PathParam("id") Long id) { + System.out.println("Client address is " + RpcContext.getContext().getRemoteAddressString()); +} +``` + +> 注意：这种方式只能在设置server="jetty"或者server="tomcat"或者server="servlet"或者server="tjws"的时候才能工作。另外，目前dubbo的RpcContext是一种比较有侵入性的用法，未来我们很可能会做出重构。 + +如果你想保持你的项目对JAX-RS的兼容性，未来脱离dubbo也可以运行，请选择第一种方式。如果你想要更优雅的服务接口定义，请选用第二种方式。 + +此外，在最新的dubbo rest中，还支持通过RpcContext来获取HttpServletRequest和HttpServletResponse，以提供更大的灵活性来方便用户实现某些复杂功能，比如在dubbo标准的filter中访问HTTP Header。用法示例如下： + +```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()); +} +``` + +> 注意：为了保持协议的中立性，RpcContext.getRequest()和RpcContext.getResponse()返回的仅仅是一个Object类，而且可能为null。所以，你必须自己做null和类型的检查。 + +> 注意：只有在设置server="jetty"或者server="tomcat"或者server="servlet"的时候，你才能通过以上方法正确的得到HttpServletRequest和HttpServletResponse，因为只有这几种server实现了servlet容器。 + +为了简化编程，在此你也可以用泛型的方式来直接获取特定类型的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)); +} +``` + +如果request/response不符合指定的类型，这里也会返回null。 + +### 配置端口号和Context Path + +dubbo中的rest协议默认将采用80端口，如果想修改端口，直接配置： + +```xml + +``` + +另外，如前所述，我们可以用@Path来配置单个rest服务的URL相对路径。但其实，我们还可以设置一个所有rest服务都适用的基础相对路径，即java web应用中常说的context path。 + +只需要添加如下contextpath属性即可： + +```xml + +``` + +以前面代码为例： + +```java +@Path("users") +public class UserServiceImpl implements UserService { + + @POST + @Path("register") + @Consumes({MediaType.APPLICATION_JSON}) + public void registerUser(User user) { + // save the user... + } +} +``` + +现在registerUser()的完整访问路径为： + +``` +http://localhost:8888/services/users/register +``` + +注意：如果你是选用外部应用服务器做rest server，即配置: + +```xml + +``` + +则必须保证这里设置的port、contextpath，与外部应用服务器的端口、DispatcherServlet的上下文路径（即webapp path加上servlet url pattern）保持一致。例如，对于部署为tomcat ROOT路径的应用，这里的contextpath必须与web.xml中DispacherServlet的``完全一致： + +```xml + + dispatcher + /services/* + +``` + +### 配置线程数和IO线程数 + +可以为rest服务配置线程池大小： + +```xml + +``` + +> 注意：目前线程池的设置只有当server="netty"或者server="jetty"或者server="tomcat"的时候才能生效。另外，如果server="servlet"，由于这时候启用的是外部应用服务器做rest server，不受dubbo控制，所以这里的线程池设置也无效。 + +如果是选用netty server，还可以配置Netty的IO worker线程数： + +```xml + +``` + +### 配置长连接 + +Dubbo中的rest服务默认都是采用http长连接来访问，如果想切换为短连接，直接配置： + +```xml + +``` + +> 注意：这个配置目前只对server="netty"和server="tomcat"才能生效。 + +### 配置最大的HTTP连接数 + +可以配置服务器提供端所能同时接收的最大HTTP连接数，防止REST server被过多连接撑爆，以作为一种最基本的自我保护机制： + +```xml + +``` + +当然，由于这个配置针对消费端生效的，所以也可以在消费端配置： + +```xml + +``` + +但是，通常我们建议配置在服务提供端提供此类配置。按照dubbo官方文档的说法：“Provider上尽量多配置Consumer端的属性，让Provider实现者一开始就思考Provider服务特点、服务质量的问题。” + +> 注意：如果dubbo的REST服务是发布给非dubbo的客户端使用，则这里``上的配置完全无效，因为这种客户端不受dubbo控制。 + +### GZIP数据压缩 + +Dubbo的REST支持用GZIP压缩请求和响应的数据，以减少网络传输时间和带宽占用，但这种方式会也增加CPU开销。 + +TODO more contents to add + +### 用Annotation取代部分Spring XML配置 + +以上所有的讨论都是基于dubbo在spring中的xml配置。但是，dubbo/spring本身也支持用annotation来作配置，所以我们也可以按dubbo官方文档中的步骤，把相关annotation加到REST服务的实现中，取代一些xml配置，例如： + +```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); + } +} +``` + +annotation的配置更简单更精确，经常也更便于维护（当然现代IDE都可以在xml中支持比如类名重构，所以就这里的特定用例而言，xml的维护性也很好）。而xml对代码的侵入性更小一些，尤其有利于动态修改配置，特别是比如你要针对单个服务配置连接超时时间、每客户端最大连接数、集群策略、权重等等。另外，特别对复杂应用或者模块来说，xml提供了一个中心点来涵盖的所有组件和配置，更一目了然，一般更便于项目长时期的维护。 + +当然，选择哪种配置方式没有绝对的优劣，和个人的偏好也不无关系。 + +### 添加自定义的Filter、Interceptor等 + +Dubbo的REST也支持JAX-RS标准的Filter和Interceptor，以方便对REST的请求与响应过程做定制化的拦截处理。 + +其中，Filter主要用于访问和设置HTTP请求和响应的参数、URI等等。例如，设置HTTP响应的cache header： + +```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主要用于访问和修改输入与输出字节流，例如，手动添加GZIP压缩： + +```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(); + } +} +``` + +在标准JAX-RS应用中，我们一般是为Filter和Interceptor添加@Provider annotation，然后JAX-RS runtime会自动发现并启用它们。而在dubbo中，我们是通过添加XML配置的方式来注册Filter和Interceptor： + +```xml + +``` + +在此，我们可以将Filter、Interceptor和DynamicFeature这三种类型的对象都添加到`extension`属性上，多个之间用逗号分隔。（DynamicFeature是另一个接口，可以方便我们更动态的启用Filter和Interceptor，感兴趣请自行google。） + +当然，dubbo自身也支持Filter的概念，但我们这里讨论的Filter和Interceptor更加接近协议实现的底层，相比dubbo的filter，可以做更底层的定制化。 + +> 注：这里的XML属性叫extension，而不是叫interceptor或者filter，是因为除了Interceptor和Filter，未来我们还会添加更多的扩展类型。 + +如果REST的消费端也是dubbo系统（参见下文的讨论），则也可以用类似方式为消费端配置Interceptor和Filter。但注意，JAX-RS中消费端的Filter和提供端的Filter是两种不同的接口。例如前面例子中服务端是ContainerResponseFilter接口，而消费端对应的是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()); + } +} +``` + +### 添加自定义的Exception处理 + +Dubbo的REST也支持JAX-RS标准的ExceptionMapper，可以用来定制特定exception发生后应该返回的HTTP响应。 + +```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(); + } +} +``` + +和Interceptor、Filter类似，将其添加到XML配置文件中即可启用： + +```xml + +``` + +### 配置HTTP日志输出 + +Dubbo rest支持输出所有HTTP请求/响应中的header字段和body消息体。 + +在XML配置中添加如下自带的REST filter： + +```xml + +``` + +**然后在logging配置中至少为org.apache.dubbo.rpc.protocol.rest.support打开INFO级别日志输出**，例如，在log4j.xml中配置： + +```xml + + + + +``` + +当然，你也可以直接在ROOT logger打开INFO级别日志输出： + +```xml + + + + +``` + +然后在日志中会有类似如下的内容输出： + +``` +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 is: +{"id":1,"name":"dang"} +``` + +打开HTTP日志输出后，除了正常日志输出的性能开销外，也会在比如HTTP请求解析时产生额外的开销，因为需要建立额外的内存缓冲区来为日志的输出做数据准备。 + +### 输入参数的校验 + +dubbo的rest支持采用Java标准的bean validation annotation（JSR 303)来做输入校验http://beanvalidation.org/ + +为了和其他dubbo远程调用协议保持一致，在rest中作校验的annotation必须放在服务的接口上，例如： + +```java +public interface UserService { + + User getUser(@Min(value=1L, message="User ID must be greater than 1") Long id); +} + +``` + +当然，在很多其他的bean validation的应用场景都是将annotation放到实现类而不是接口上。把annotation放在接口上至少有一个好处是，dubbo的客户端可以共享这个接口的信息，dubbo甚至不需要做远程调用，在本地就可以完成输入校验。 + +然后按照dubbo的标准方式在XML配置中打开验证： + +```xml + +``` + +在dubbo的其他很多远程调用协议中，如果输入验证出错，是直接将`RpcException`抛向客户端，而在rest中由于客户端经常是非dubbo，甚至非java的系统，所以不便直接抛出Java异常。因此，目前我们将校验错误以XML的格式返回： + +```xml + + + getUserArgument0 + User ID must be greater than 1 + 0 + + +``` + +稍后也会支持其他数据格式的返回值。至于如何对验证错误消息作国际化处理，直接参考bean validation的相关文档即可。 + +如果你认为默认的校验错误返回格式不符合你的要求，可以如上面章节所述，添加自定义的ExceptionMapper来自由的定制错误返回格式。需要注意的是，这个ExceptionMapper必须用泛型声明来捕获dubbo的RpcException，才能成功覆盖dubbo rest默认的异常处理策略。为了简化操作，其实这里最简单的方式是直接继承dubbo rest的RpcExceptionMapper，并覆盖其中处理校验异常的方法即可： + +```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())); + } + // 采用json输出代替xml输出 + return Response.status(Response.Status.INTERNAL_SERVER_ERROR).entity(report).type(ContentType.APPLICATION_JSON_UTF_8).build(); + } +} +``` + +然后将这个ExceptionMapper添加到XML配置中即可： + +```xml + +``` + +### 是否应该透明发布REST服务 + +Dubbo的REST调用和dubbo中其它某些RPC不同的是，需要在服务代码中添加JAX-RS的annotation（以及JAXB、Jackson的annotation），如果你觉得这些annotation一定程度“污染”了你的服务代码，你可以考虑编写额外的Facade和DTO类，在Facade和DTO上添加annotation，而Facade将调用转发给真正的服务实现类。当然事实上，直接在服务代码中添加annotation基本没有任何负面作用，而且这本身是Java EE的标准用法，另外JAX-RS和JAXB的annotation是属于java标准，比我们经常使用的spring、dubbo等等annotation更没有vendor lock-in的问题，所以一般没有必要因此而引入额外对象。 + +另外，如果你想用前述的@Context annotation，通过方法参数注入HttpServletRequest（如`public User getUser(@PathParam("id") Long id, @Context HttpServletRequest request)`），这时候由于改变了服务的方法签名，并且HttpServletRequest是REST特有的参数，**所以如果你的服务要支持多种RPC机制的话**，则引入额外的Facade类是比较适当的。 + +当然，在没有添加REST调用之前，你的服务代码可能本身已经就充当了Facade和DTO的角色（至于为什么有些场景需要这些角色，有兴趣可参考[微观SOA：服务设计原则及其实践方式](http://www.infoq.com/cn/articles/micro-soa-1)）。这种情况下，在添加REST之后，如果你再额外添加与REST相关的Facade和DTO，就相当于对原有代码对再一次包装，即形成如下调用链： + +`RestFacade/RestDTO -> Facade/DTO -> Service` + +这种体系比较繁琐，数据转换之类的工作量也不小，所以一般应尽量避免如此。 + +### dubbo的提供端在调用REST服务时使用header + +Dubbo通过RpcContextFilter将header取出分解之后设置到RpcContext的attachments，所以在提供端可以直接从RpcContext的attachments中获取到消费端设置的header信息： + +``` + RpcContext.getContext().getAttachment(key1) + RpcContext.getContext().getAttachment(key2) +``` + +## REST服务消费端详解 + +这里我们用三种场景来分别讨论： + +1. 非dubbo的消费端调用dubbo的REST服务（non-dubbo --> dubbo） +2. dubbo消费端调用dubbo的REST服务 （dubbo --> dubbo） +3. dubbo的消费端调用非dubbo的REST服务 （dubbo --> non-dubbo） + +### 场景1：非dubbo的消费端调用dubbo的REST服务 + +这种场景的客户端与dubbo本身无关，直接选用相应语言和框架中合适的方式即可。 + +如果是还是java的客户端（但没用dubbo），可以考虑直接使用标准的JAX-RS Client API或者特定REST实现的Client API来调用REST服务。下面是用JAX-RS Client API来访问上述的UserService的registerUser()： + +```java +User user = new User(); +user.setName("Larry"); + +Client client = ClientBuilder.newClient(); +WebTarget target = client.target("http://localhost:8080/services/users/register.json"); +Response response = target.request().post(Entity.entity(user, MediaType.APPLICATION_JSON_TYPE)); + +try { + if (response.getStatus() != 200) { + throw new RuntimeException("Failed with HTTP error code : " + response.getStatus()); + } + System.out.println("The generated id is " + response.readEntity(RegistrationResult.class).getId()); +} finally { + response.close(); + client.close(); // 在真正开发中不要每次关闭client，比如HTTP长连接是由client持有的 +} +``` + +上面代码片段中的User和RegistrationResult类都是消费端自己编写的，JAX-RS Client API会自动对它们做序列化/反序列化。 + +当然，在java中也可以直接用自己熟悉的比如HttpClient，FastJson，XStream等等各种不同技术来实现REST客户端，在此不再详述。 + +### 场景2：dubbo消费端调用dubbo的REST服务 + +这种场景下，和使用其他dubbo的远程调用方式一样，直接在服务提供端和服务消费端共享Java服务接口，并添加spring xml配置（当然也可以用spring/dubbo的annotation配置），即可透明的调用远程REST服务： + +```xml + +``` + +如前所述，这种场景下必须把JAX-RS的annotation添加到服务接口上，这样在dubbo在消费端才能共享相应的REST配置信息，并据之做远程调用: + +```java +@Path("users") +public interface UserService { + + @GET + @Path("{id : \\d+}") + @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) + User getUser(@PathParam("id") Long id); +} +``` + +如果服务接口的annotation中配置了多种数据格式，这里由于两端都是dubbo系统，REST的大量细节被屏蔽了，所以不存在用前述URL后缀之类选择数据格式的可能。目前在这种情况下，排名最靠前的数据格式将直接被使用。 + +因此，我们建议你在定义annotation的时候最好把最合适的数据格式放到前面，比如以上我们是把json放在xml前面，因为json的传输性能优于xml。 + +### 场景3：dubbo的消费端调用非dubbo的REST服务 + +这种场景下，可以直接用场景1中描述的Java的方式来调用REST服务。但其实也可以采用场景2中描述的方式，即更透明的调用REST服务，即使这个服务并不是dubbo提供的。 + +如果用场景2的方式，由于这里REST服务并非dubbo提供，一般也就没有前述的共享的Java服务接口，所以在此我们需要根据外部REST服务的情况，自己来编写Java接口以及相应参数类，并添加JAX-RS、JAXB、Jackson等的annotation，dubbo的REST底层实现会据此去自动生成请求消息，自动解析响应消息等等，从而透明的做远程调用。或者这种方式也可以理解为，我们尝试用JAX-RS的方式去仿造实现一遍外部的REST服务提供端，然后把写成服务接口放到客户端来直接使用，dubbo的REST底层实现就能像调用dubbo的REST服务一样调用其他REST服务。 + +例如，我们要调用如下的外部服务 + +``` +http://api.foo.com/services/users/1001 +http://api.foo.com/services/users/1002 +``` + +获取不同ID的用户资料，返回格式是JSON + +```javascript +{ + "id": 1001, + "name": "Larry" +} +``` + +我们可根据这些信息，编写服务接口和参数类即可： + +```java +@Path("users") +public interface UserService { + + @GET + @Path("{id : \\d+}") + @Produces({MediaType.APPLICATION_JSON}) + User getUser(@PathParam("id") Long id); +} +``` + +```java +public class User implements Serializable { + + private Long id; + + private String name; + + // … +} +``` + +对于spring中的配置，因为这里的REST服务不是dubbo提供的，所以无法使用dubbo的注册中心，直接配置外部REST服务的url地址即可（如多个地址用逗号分隔）： + +```xml + +``` + +> 注意：这里协议必须用rest://而不是http://之类。如果外部的REST服务有context path，则在url中也必须添加上（除非你在每个服务接口的@Path annotation中都带上context path），例如上面的/services/。同时这里的services后面必须带上/，这样才能使dubbo正常工作。 + +另外，这里依然可以配置客户端可启动的最大连接数和超时时间： + +```xml + +``` + +### dubbo的消费端在调用REST服务时配置自定义header + +Dubbo进行rest调用的时候，采用的是将RpcContext的attachment转换为header的方式，所以，dubbo消费端可以按以下方式进行自定义header的设置： + +``` + RpcContext.getContext().setAttachment("key1", "value1"); + RpcContext.getContext().setAttachment("key2", "value2"); +``` + +即可设置如下格式的header: + +``` + key1=value1 + key2=value2 +``` + + +## Dubbo中JAX-RS的限制 + +Dubbo中的REST开发是完全兼容标准JAX-RS的，但其支持的功能目前是完整JAX-RS的一个子集，部分因为它要受限于dubbo和spring的特定体系。 + +在dubbo中使用的JAX-RS的局限包括但不限于： + +1. 服务实现只能是singleton的，不能支持per-request scope和per-lookup scope +2. 不支持用@Context annotation对服务的实例字段注入 ServletConfig、ServletContext、HttpServletRequest、HttpServletResponse等等，但可以支持对服务方法参数的注入。但对某些特定REST server实现，（祥见前面的叙述），也不支持对服务方法参数的注入。 + +## REST常见问题解答（REST FAQ） + +### Dubbo REST的服务能和Dubbo注册中心、监控中心集成吗？ + +可以的，而且是自动集成的，也就是你在dubbo中开发的所有REST服务都会自动注册到注册中心和监控中心，可以通过它们做管理。 + +但是，只有当REST的消费端也是基于dubbo的时候，注册中心中的许多服务治理操作才能完全起作用。而如果消费端是非dubbo的，自然不受注册中心管理，所以其中很多操作是不会对消费端起作用的。 + +### Dubbo REST中如何实现负载均衡和容错（failover）？ + +如果dubbo REST的消费端也是dubbo的，则Dubbo REST和其他dubbo远程调用协议基本完全一样，由dubbo框架透明的在消费端做load balance、failover等等。 + +如果dubbo REST的消费端是非dubbo的，甚至是非java的，则最好配置服务提供端的软负载均衡机制，目前可考虑用LVS、HAProxy、 Nginx等等对HTTP请求做负载均衡。 + +### JAX-RS中重载的方法能够映射到同一URL地址吗？ + +http://stackoverflow.com/questions/17196766/can-resteasy-choose-method-based-on-query-params + +### JAX-RS中作POST的方法能够接收多个参数吗？ + +http://stackoverflow.com/questions/5553218/jax-rs-post-multiple-objects + +## Dubbo当前体系的不足之处（与REST相关的） + +我认为dubbo当前体系中显然也有不少不足之处，这里列出几个与REST有关的、并影响用户使用的问题（不包括内部实现的问题），供参考评论，为下一步重构作准备。 + +### RpcContext的侵入性 + +在前文，前面我们已经提到过RpcContext用法的侵入性，由于它是用单例的方式来访问上下文信息，这完全不符合spring应用的一般风格，不利于应用扩展和单元测试。未来我们可能用依赖注入方式注入一个接口，再用它去访问ThreadLocal中的上下文信息。 + +### Protocol配置的局限性 + +dubbo支持多种远程调用方式，但所有调用方式都是用``来配置的，例如： + +```xml + +``` + +其实，上面很多属性实际上dubbo RPC远程调用方式特有的，很多dubbo中的其它远程调用方式根本就不支持例如server, client, codec, iothreads, accepts, payload等等（当然，有的是条件所限不支持，有的是根本没有必要支持）。这给用户的使用徒增很多困惑，用户也并不知道有些属性（比如做性能调优）添加了实际上是不起作用的。 + +另一方面，各种远程调用方式往往有大量自己独特的配置需要，特别是我们逐步为每种远程调用方式都添加更丰富、更高级的功能，这就不可避免的扩展``中的属性（例如目前我们在REST中已经添加了keepalive和extension两个属性），到最后会导致``臃肿不堪，用户的使用也更加困惑。 + +当然，dubbo中有一种扩展``的方式是用``，但这种方式显然很有局限性，而且用法复杂，缺乏schema校验。 + +所以，最好的方式是为每种远程调用方式设置自己的protocol元素，比如``，``等等，每种元素用XML schema规定自己的属性（当然属性在各种远程调用方式之间能通用是最好的）。 + +如此一来，例如前面提到过的extension配置也可以用更自由的方式，从而更清楚更可扩展（以下只是举例，当然也许有更好的方式）: + +```xml + + someInterceptor + someFilter + someDynamicFeature + someEntityProvider + +``` + +### XML命名不符合spring规范 + +dubbo的XML配置中大量命名都不符合spring规范，比如： + +```xml + +``` + +上面threadpool应该改为thread-pool，iothreads应该改为io-threads，单词之间应该用"-"分隔。这虽然看起来是个小问题，但也涉及到了可读性，特别是可扩展性，因为有时候我们不可避免要用更多单词来描述XML元素和属性。 + +其实dubbo本身也是建议遵守spring到XML的命名规范。 + + +## REST最佳实践 + +TODO + +## 性能基准测试 + +### 测试环境 + +粗略如下： + +* 两台独立服务器 +* 4核Intel(R) Xeon(R) CPU E5-2603 0 @ 1.80GHz +* 8G内存 +* 服务器之间网络通过百兆交换机 +* CentOS 5 +* JDK 7 +* Tomcat 7 +* JVM参数-server -Xms1g -Xmx1g -XX:PermSize=64M -XX:+UseConcMarkSweepGC + +### 测试脚本 + +和dubbo自身的基准测试保持接近： + +10个并发客户端持续不断发出请求： + +* 传入嵌套复杂对象（但单个数据量很小），不做任何处理，原样返回 +* 传入50K字符串，不做任何处理，原样返回（TODO：结果尚未列出） + +进行5分钟性能测试。（引用dubbo自身测试的考虑：“主要考察序列化和网络IO的性能，因此服务端无任何业务逻辑。取10并发是考虑到http协议在高并发下对CPU的使用率较高可能会先打到瓶颈。”） + +### 测试结果 + +下面的结果主要对比的是REST和dubbo RPC两种远程调用方式，并对它们作不同的配置，例如： + +* “REST: Jetty + XML + GZIP”的意思是：测试REST，并采用jetty server，XML数据格式，启用GZIP压缩。 +* “Dubbo: hessian2”的意思是：测试dubbo RPC，并采用hessian2序列化方式。 + +针对复杂对象的结果如下（响应时间越小越好，TPS越大越好）： + +| 远程调用方式 | 平均响应时间 | 平均TPS（每秒事务数） | +| ----------- | ------------- | ------------- | +| 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) + + +仅就目前的结果，一点简单总结： + +* dubbo RPC（特别是基于高效java序列化方式如kryo，fst）比REST的响应时间和吞吐量都有较显著优势，内网的dubbo系统之间优先选择dubbo RPC。 +* 在REST的实现选择上，仅就性能而言，目前tomcat7和netty最优（当然目前使用的jetty和netty版本都较低）。tjws和sun http server在性能测试中表现极差，平均响应时间超过200ms，平均tps只有50左右（为了避免影响图片效果，没在上面列出）。 +* 在REST中JSON数据格式性能优于XML（数据暂未在以上列出）。 +* 在REST中启用GZIP对企业内网中的小数据量复杂对象帮助不大，性能反而有下降（数据暂未在以上列出）。 + +## 性能优化建议 + +如果将dubbo REST部署到外部Tomcat上，并配置server="servlet"，即启用外部的tomcat来做为rest server的底层实现，则最好在tomcat上添加如下配置： + +```xml + +``` + +特别是maxKeepAliveRequests="-1"，这个配置主要是保证tomcat一直启用http长连接，以提高REST调用性能。但是请注意，如果REST消费端不是持续的调用REST服务，则一直启用长连接未必是最好的做法。另外，一直启用长连接的方式一般不适合针对普通webapp，更适合这种类似rpc的场景。所以为了高性能，在tomcat中，dubbo REST应用和普通web应用最好不要混合部署，而应该用单独的实例。 + +TODO more contents to add + +## 扩展讨论 + +### REST与Thrift、Protobuf等的对比 + +TODO + +### REST与传统WebServices的对比 + +TODO + +### JAX-RS与Spring MVC的对比 + +初步看法，摘自http://www.infoq.com/cn/news/2014/10/dubbox-open-source?utm_source=infoq&utm_medium=popular_links_homepage#theCommentsSection + +> 谢谢，对于jax-rs和spring mvc，其实我对spring mvc的rest支持还没有太深入的看过，说点初步想法，请大家指正： +> +> spring mvc也支持annotation的配置，其实和jax-rs看起来是非常非常类似的。 +> +> 我个人认为spring mvc相对更适合于面向web应用的restful服务，比如被AJAX调用，也可能输出HTML之类的，应用中还有页面跳转流程之类，spring mvc既可以做好正常的web页面请求也可以同时处理rest请求。但总的来说这个restful服务是在展现层或者叫web层之类实现的 +> +> 而jax-rs相对更适合纯粹的服务化应用，也就是传统Java EE中所说的中间层服务，比如它可以把传统的EJB发布成restful服务。在spring应用中，也就把spring中充当service之类的bean直接发布成restful服务。总的来说这个restful服务是在业务、应用层或者facade层。而MVC层次和概念在这种做比如（后台）服务化的应用中通常是没有多大价值的。 +> +> 当然jax-rs的有些实现比如jersey，也试图提供mvc支持，以更好的适应上面所说的web应用，但应该是不如spring mvc。 +> +> 在dubbo应用中，我想很多人都比较喜欢直接将一个本地的spring service bean（或者叫manager之类的）完全透明的发布成远程服务，则这里用JAX-RS是更自然更直接的，不必额外的引入MVC概念。当然，先不讨论透明发布远程服务是不是最佳实践，要不要添加facade之类。 +> +> 当然，我知道在dubbo不支持rest的情况下，很多朋友采用的架构是spring mvc restful调用dubbo (spring) service来发布restful服务的。这种方式我觉得也非常好，只是如果不修改spring mvc并将其与dubbo深度集成，restful服务不能像dubbo中的其他远程调用协议比如webservices、dubbo rpc、hessian等等那样，享受诸多高级的服务治理的功能，比如：注册到dubbo的服务注册中心，通过dubbo监控中心监控其调用次数、TPS、响应时间之类，通过dubbo的统一的配置方式控制其比如线程池大小、最大连接数等等，通过dubbo统一方式做服务流量控制、权限控制、频次控制。另外spring mvc仅仅负责服务端，而在消费端，通常是用spring restTemplate，如果restTemplate不和dubbo集成，有可能像dubbo服务客户端那样自动或者人工干预做服务降级。如果服务端消费端都是dubbo系统，通过spring的rest交互，如果spring rest不深度整合dubbo，则不能用dubbo统一的路由分流等功能。 +> +> 当然，其实我个人认为这些东西不必要非此即彼的。我听说spring创始人rod johnson总是爱说一句话，the customer is always right，其实与其非要探讨哪种方式更好，不如同时支持两种方式就是了，所以原来在文档中也写过计划支持spring rest annoation，只是不知道具体可行性有多高。 + +## 未来 + +稍后可能要实现的功能： + +* spring mvc的rest annotation支持 +* 安全 +* OAuth +* 异步调用 +* 完善gzip +* 最大payload限制 + diff --git a/content/zh/docs3-building/java-sdk/reference-manual/protocol/rmi/_index.md b/content/zh/docs3-building/java-sdk/reference-manual/protocol/rmi/_index.md new file mode 100755 index 000000000000..68ef52230b40 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/protocol/rmi/_index.md @@ -0,0 +1,8 @@ + +--- +type: docs +title: "Rmi协议" +linkTitle: "Rmi协议" +weight: 8 +--- + diff --git a/content/zh/docs3-building/java-sdk/reference-manual/protocol/rmi/guide.md b/content/zh/docs3-building/java-sdk/reference-manual/protocol/rmi/guide.md new file mode 100644 index 000000000000..e7dc335e25ae --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/protocol/rmi/guide.md @@ -0,0 +1,86 @@ +--- +type: docs +title: "使用说明" +linkTitle: "使用说明" +weight: 2 +--- + + +RMI 协议采用 JDK 标准的 `java.rmi.*` 实现，采用阻塞式短连接和 JDK 标准序列化方式。 + +注意：如果正在使用 RMI 提供服务给外部访问 [^1]，同时应用里依赖了老的 common-collections 包 [^2] 的情况下，存在反序列化安全风险 [^3]。 + +## 特性 + +* 连接个数：多连接 +* 连接方式：短连接 +* 传输协议：TCP +* 传输方式：同步传输 +* 序列化：Java 标准二进制序列化 +* 适用范围：传入传出参数数据包大小混合，消费者与提供者个数差不多，可传文件。 +* 适用场景：常规远程服务方法调用，与原生RMI服务互操作 + +## 约束 + +* 参数及返回值需实现 `Serializable` 接口 +* dubbo 配置中的超时时间对 RMI 无效，需使用 java 启动参数设置：`-Dsun.rmi.transport.tcp.responseTimeout=3000`，参见下面的 RMI 配置 + + +## RMI配置 + +```sh +java -Dsun.rmi.transport.tcp.responseTimeout=3000 +``` +更多 RMI 优化参数请查看 [JDK 文档](https://docs.oracle.com/javase/6/docs/technotes/guides/rmi/sunrmiproperties.html) + + +## 接口 + +如果服务接口继承了 `java.rmi.Remote` 接口，可以和原生 RMI 互操作，即： + +* 提供者用 Dubbo 的 RMI 协议暴露服务，消费者直接用标准 RMI 接口调用， +* 或者提供方用标准 RMI 暴露服务，消费方用 Dubbo 的 RMI 协议调用。 + +如果服务接口没有继承 `java.rmi.Remote` 接口： + +* 缺省 Dubbo 将自动生成一个 `com.xxx.XxxService$Remote` 的接口，并继承 `java.rmi.Remote` 接口，并以此接口暴露服务， +* 但如果设置了 ``，将不生成 `$Remote` 接口，而使用 Spring 的 `RmiInvocationHandler` 接口暴露服务，和 Spring 兼容。 + +## 配置 + +定义 RMI 协议： + +```xml + +``` + +设置默认协议： + +```xml + +``` + +设置某个服务的协议： + +```xml + +``` + +多端口： + +```xml + + + + +``` + +Spring 兼容性： + +```xml + +``` + +[^1]: 公司内网环境应该不会有攻击风险 +[^2]: dubbo 不会依赖这个包，请排查自己的应用有没有使用 +[^3]: 请检查应用：将 commons-collections3 请升级到 [3.2.2](https://commons.apache.org/proper/commons-collections/release_3_2_2.html)；将 commons-collections4 请升级到 [4.1](https://commons.apache.org/proper/commons-collections/release_4_1.html)。新版本的 commons-collections 解决了该问题 diff --git a/content/zh/docs3-building/java-sdk/reference-manual/protocol/rmi/overview.md b/content/zh/docs3-building/java-sdk/reference-manual/protocol/rmi/overview.md new file mode 100644 index 000000000000..ed5e7234ba58 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/protocol/rmi/overview.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "协议概述" +linkTitle: "协议概述" +weight: 1 +--- diff --git a/content/zh/docs3-building/java-sdk/reference-manual/protocol/thrift/_index.md b/content/zh/docs3-building/java-sdk/reference-manual/protocol/thrift/_index.md new file mode 100755 index 000000000000..9a9fc5aa721c --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/protocol/thrift/_index.md @@ -0,0 +1,8 @@ + +--- +type: docs +title: "Thrift协议" +linkTitle: "Thrift协议" +weight: 7 +--- + diff --git a/content/zh/docs3-building/java-sdk/reference-manual/protocol/thrift/guide.md b/content/zh/docs3-building/java-sdk/reference-manual/protocol/thrift/guide.md new file mode 100644 index 000000000000..264112e7927d --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/protocol/thrift/guide.md @@ -0,0 +1,45 @@ +--- +type: docs +title: "使用说明" +linkTitle: "使用说明" +weight: 2 +--- + + + +当前 dubbo 支持的 thrift 协议是对 thrift 原生协议 [^1] 的扩展，在原生协议的基础上添加了一些额外的头信息，比如 service name，magic number 等。 + +{{% alert title="提示" color="primary" %}} +`2.3.0` 以上版本支持 +{{% /alert %}} + +使用 dubbo thrift 协议同样需要使用 thrift 的 idl compiler 编译生成相应的 java 代码，后续版本中会在这方面做一些增强。 + +## 依赖 + +```xml + + org.apache.thrift + libthrift + 0.8.0 + +``` + +## 配置 + +所有服务共用一个端口 [^2]： + +```xml + +``` + +## 使用 + +可以参考 [dubbo 项目中的示例代码](https://github.com/apache/dubbo/tree/master/dubbo-rpc/dubbo-rpc-thrift/src/test/java/org/apache/dubbo/rpc/protocol/thrift) + +## 常见问题 + +* Thrift 不支持 null 值，即：不能在协议中传递 null 值 + +[^1]: [Thrift](http://thrift.apache.org) 是 Facebook 捐给 Apache 的一个 RPC 框架 +[^2]: 与原生Thrift不兼容 diff --git a/content/zh/docs3-building/java-sdk/reference-manual/protocol/thrift/overview.md b/content/zh/docs3-building/java-sdk/reference-manual/protocol/thrift/overview.md new file mode 100644 index 000000000000..ed5e7234ba58 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/protocol/thrift/overview.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "协议概述" +linkTitle: "协议概述" +weight: 1 +--- diff --git a/content/zh/docs3-building/java-sdk/reference-manual/protocol/triple/_index.md b/content/zh/docs3-building/java-sdk/reference-manual/protocol/triple/_index.md new file mode 100755 index 000000000000..d6933892ab73 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/protocol/triple/_index.md @@ -0,0 +1,8 @@ + +--- +type: docs +title: "Triple协议" +linkTitle: "Triple协议" +weight: 3 +--- + diff --git a/content/zh/docs3-building/java-sdk/reference-manual/protocol/triple/guide.md b/content/zh/docs3-building/java-sdk/reference-manual/protocol/triple/guide.md new file mode 100644 index 000000000000..0754620bc1dc --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/protocol/triple/guide.md @@ -0,0 +1,283 @@ +--- +type: docs +title: "使用说明" +linkTitle: "使用说明" +weight: 2 +--- + +Triple 协议是 Dubbo3 的主力协议，完整兼容 gRPC over HTTP/2，并在协议层面扩展了负载均衡和流量控制相关机制。本文档旨在指导用户正确的使用 Triple 协议。 + +在开始前，需要决定服务使用的序列化方式，如果为新服务，推荐使用 protobuf 作为默认序列化，在性能和跨语言上的效果都会更好。如果是原有服务想进行协议升级，Triple 协议也已经支持其他序列化方式，如 Hessian / JSON 等 + + + +### Protobuf + +1. 编写 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; + + // 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. 添加编译 protobuf 的 extension 和 plugin (以 maven 为例) + ```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. 构建/ 编译生成 protobuf Message 类 + ```shell + $ mvn clean install + ``` + +### Unary 方式 + +4. 编写 Java 接口 + ```java + import org.apache.dubbo.hello.HelloReply; + import org.apache.dubbo.hello.HelloRequest; + + public interface IGreeter { + /** + * 
+         *  Sends a greeting
+         *
+ */ + HelloReply sayHello(HelloRequest request); + + } + ``` + +5. 创建 Provider + ```java + public static void main(String[] args) throws InterruptedException { + ServiceConfig service = new ServiceConfig<>(); + service.setInterface(IGreeter.class); + service.setRef(new IGreeter1Impl()); + // 这里需要显示声明使用的协议为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. 创建 Consumer + + ```java + public static void main(String[] args) throws IOException { + ReferenceConfig ref = new ReferenceConfig<>(); + ref.setInterface(IGreeter.class); + ref.setCheck(false); + 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. 运行 Provider 和 Consumer ,可以看到请求正常返回了 + > Reply:message: "name" + +### stream 方式 + +8. 编写 Java 接口 + ```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. 编写实现类 + ```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. 创建 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. 创建 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. 运行 Provider 和 Consumer ,可以看到请求正常返回了 + > onNext\ + > receive name:tony\ + > onNext\ + > receive name:nick\ + > onCompleted + +### 其他序列化方式 +省略上文中的 1-3 步，指定 Provider 和 Consumer 使用的协议即可完成协议升级。 + +### 示例程序 +本文的示例程序可以在 [triple-samples](https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-triple) 找到 + + + \ No newline at end of file diff --git a/content/zh/docs3-building/java-sdk/reference-manual/protocol/triple/overview.md b/content/zh/docs3-building/java-sdk/reference-manual/protocol/triple/overview.md new file mode 100644 index 000000000000..ed5e7234ba58 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/protocol/triple/overview.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "协议概述" +linkTitle: "协议概述" +weight: 1 +--- diff --git a/content/zh/docs3-building/java-sdk/reference-manual/protocol/webservice/_index.md b/content/zh/docs3-building/java-sdk/reference-manual/protocol/webservice/_index.md new file mode 100755 index 000000000000..059ef4ba98c9 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/protocol/webservice/_index.md @@ -0,0 +1,8 @@ + +--- +type: docs +title: "Webservice协议" +linkTitle: "Webservice协议" +weight: 11 +--- + diff --git a/content/zh/docs3-building/java-sdk/reference-manual/protocol/webservice/guide.md b/content/zh/docs3-building/java-sdk/reference-manual/protocol/webservice/guide.md new file mode 100644 index 000000000000..afb1ee2e3f07 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/protocol/webservice/guide.md @@ -0,0 +1,119 @@ +--- +type: docs +title: "使用说明" +linkTitle: "使用说明" +weight: 2 +--- + + +基于 WebService 的远程调用协议，基于 [Apache CXF](http://cxf.apache.org) [^1] 的 `frontend-simple` 和 `transports-http` 实现。 + +{{% alert title="提示" color="primary" %}} +`2.3.0` 以上版本支持 +{{% /alert %}} + +可以和原生 WebService 服务互操作，即： + +* 提供者用 Dubbo 的 WebService 协议暴露服务，消费者直接用标准 WebService 接口调用， +* 或者提供方用标准 WebService 暴露服务，消费方用 Dubbo 的 WebService 协议调用。 + +## 依赖 + +```xml + + org.apache.cxf + cxf-rt-frontend-simple + 2.6.1 + + + org.apache.cxf + cxf-rt-transports-http + 2.6.1 + +``` + +## 特性 + +* 连接个数：多连接 +* 连接方式：短连接 +* 传输协议：HTTP +* 传输方式：同步传输 +* 序列化：SOAP 文本序列化 +* 适用场景：系统集成，跨语言调用 + +## 约束 + +* 参数及返回值需实现 `Serializable` 接口 +* 参数尽量使用基本类型和 POJO + +## 配置 + +配置协议： + +```xml + +``` + +配置默认协议： + +```xml + +``` + +配置服务协议： + +```xml + +``` + +多端口： + +```xml + + +``` + +直连： + +```xml + +``` + +WSDL： + +``` +http://10.20.153.10:8080/com.foo.HelloWorld?wsdl +``` + +Jetty Server (默认)： + +```xml + +``` + +Servlet Bridge Server (推荐)： + +```xml + +``` + +配置 DispatcherServlet： + +```xml + + dubbo + org.apache.dubbo.remoting.http.servlet.DispatcherServlet + 1 + + + dubbo + /* + +``` + +注意，如果使用 servlet 派发请求： + +* 协议的端口 `` 必须与 servlet 容器的端口相同， +* 协议的上下文路径 `` 必须与 servlet 应用的上下文路径相同。 + +[^1]: CXF 是 Apache 开源的一个 RPC 框架，由 Xfire 和 Celtix 合并而来 diff --git a/content/zh/docs3-building/java-sdk/reference-manual/protocol/webservice/overview.md b/content/zh/docs3-building/java-sdk/reference-manual/protocol/webservice/overview.md new file mode 100644 index 000000000000..ed5e7234ba58 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/protocol/webservice/overview.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "协议概述" +linkTitle: "协议概述" +weight: 1 +--- diff --git a/content/zh/docs3-building/java-sdk/reference-manual/qos/_index.md b/content/zh/docs3-building/java-sdk/reference-manual/qos/_index.md new file mode 100755 index 000000000000..dd8e0eba9a15 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/qos/_index.md @@ -0,0 +1,8 @@ + +--- +type: docs +title: "QOS 操作手册" +linkTitle: "QOS 操作手册" +weight: 3 +--- + diff --git a/content/zh/docs3-building/java-sdk/reference-manual/qos/command.md b/content/zh/docs3-building/java-sdk/reference-manual/qos/command.md new file mode 100644 index 000000000000..40eaa6cc6c95 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/qos/command.md @@ -0,0 +1,243 @@ +--- +type: docs +title: "QOS 命令手册" +linkTitle: "QOS 命令手册" +weight: 2 +description: "新版本 telnet 命令使用说明" +--- + +dubbo `2.5.8` 新版本增加了 QOS 模块，提供了新的 telnet 命令支持。 + +## 端口 +新版本的 telnet 端口 与 dubbo 协议的端口是不同的端口，默认为 `22222`，可通过配置文件`dubbo.properties` 修改: + +``` +dubbo.application.qos-port=33333 +``` + +或者通过设置 JVM 参数: + +``` +-Ddubbo.application.qos-port=33333 +``` + +## 安全 + +默认情况下，dubbo 接收任何主机发起的命令，可通过配置文件`dubbo.properties` 修改: + +``` +dubbo.application.qos-accept-foreign-ip=false +``` + +或者通过设置 JVM 参数: + +``` +-Ddubbo.application.qos-accept-foreign-ip=false +``` + +拒绝远端主机发出的命令，只允许服务本机执行 + + +## telnet 与 http 协议 + +telnet 模块现在同时支持 http 协议和 telnet 协议，方便各种情况的使用 + +示例如下： + +``` +➜ ~ 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| ++---------------------+---+ +``` + +## 支持的命令 + +### ls 列出消费者和提供者 + +``` +dubbo>ls +As Provider side: ++----------------------------------+---+ +| Provider Service Name |PUB| ++----------------------------------+---+ +|org.apache.dubbo.demo.DemoService| Y | ++----------------------------------+---+ +As Consumer side: ++---------------------+---+ +|Consumer Service Name|NUM| ++---------------------+---+ +``` + +列出 dubbo 的所提供的服务和消费的服务，以及消费的服务地址数 + +### Online 上线服务命令 + +当使用延迟发布功能的时候(通过设置 org.apache.dubbo.config.AbstractServiceConfig#register 为 false)，后续需要上线的时候，可通过 Online 命令 + +``` +//上线所有服务 +dubbo>online +OK + +//根据正则，上线部分服务 +dubbo>online com.* +OK +``` + +常见使用场景： + + - 当线上的 QPS 比较高的时候，当刚重启机器的时候，由于没有进行JIT 预热或相关资源没有预热，可能会导致大量超时，这个时候，可通过分批发布服务，逐渐加大流量 + - 当由于某台机器由于某种原因，需要下线服务，然后又需要重新上线服务 + + + +### Offline 下线服务命令 + +由于故障等原因，需要临时下线服务保持现场，可以使用 Offline 下线命令。 + + +``` +//下线所有服务 +dubbo>offline +OK + +//根据正则，下线部分服务 +dubbo>offline com.* +OK +``` + +### help 命令 + + + +``` +//列出所有命令 +dubbo>help + +//列出单个命令的具体使用情况 +dubbo>help online ++--------------+----------------------------------------------------------------------------------+ +| COMMAND NAME | online | ++--------------+----------------------------------------------------------------------------------+ +| EXAMPLE | online dubbo | +| | online xx.xx.xxx.service | ++--------------+----------------------------------------------------------------------------------+ + +dubbo> +``` + +## 相关参数说明 + +QoS提供了一些启动参数，来对启动进行配置，他们主要包括： + +| 参数 | 说明 | 默认值 | +| ------------------ | ----------------- | ------ | +| qos-enable | 是否启动QoS | true | +| qos-port | 启动QoS绑定的端口 | 22222 | +| qos-accept-foreign-ip | 是否允许远程访问 | false | + +> 注意，从2.6.4/2.7.0开始，qos-accept-foreign-ip默认配置改为false，如果qos-accept-foreign-ip设置为true，有可能带来安全风险，请仔细评估后再打开。 + +QoS参数可以通过如下方式进行配置 + +* 系统属性 +* dubbo.properties +* XML方式 +* Spring-boot自动装配方式 + +其中，上述方式的优先顺序为系统属性 > dubbo.properties > XML/Spring-boot自动装配方式。 + +### 使用系统属性方式进行配置 + +``` +-Ddubbo.application.qos-enable=true +-Ddubbo.application.qos-port=33333 +-Ddubbo.application.qos-accept-foreign-ip=false +``` + +### 使用dubbo.properties文件进行配置 + +在项目的`src/main/resources`目录下添加dubbo.properties文件，内容如下: +``` +dubbo.application.qos-enable=true +dubbo.application.qos-port=33333 +dubbo.application.qos-accept-foreign-ip=false +``` + +### 使用XML方法进行配置 + +如果要通过XML配置响应的QoS相关的参数，可以进行如下配置： + +```xml + + + + + + + + + + + + +``` + +### 使用spring-boot自动装配方式配置 + +如果是spring-boot的应用，可以在`application.properties`或者`application.yml`上配置: + +``` +dubbo.application.qos-enable=true +dubbo.application.qos-port=33333 +dubbo.application.qos-accept-foreign-ip=false +``` + + + diff --git a/content/zh/docs3-building/java-sdk/reference-manual/qos/overview.md b/content/zh/docs3-building/java-sdk/reference-manual/qos/overview.md new file mode 100644 index 000000000000..a8efb54f6966 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/qos/overview.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "QOS 概述" +linkTitle: "QOS 概述" +weight: 1 +--- diff --git a/content/zh/docs3-building/java-sdk/reference-manual/registry/_index.md b/content/zh/docs3-building/java-sdk/reference-manual/registry/_index.md new file mode 100644 index 000000000000..1c0c3c19970a --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/registry/_index.md @@ -0,0 +1,7 @@ +--- +type: docs +title: "注册中心参考手册" +linkTitle: "注册中心参考手册" +weight: 5 +description: "" +--- diff --git a/content/zh/docs3-building/java-sdk/reference-manual/registry/multicast/_index.md b/content/zh/docs3-building/java-sdk/reference-manual/registry/multicast/_index.md new file mode 100644 index 000000000000..dcf9708c305c --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/registry/multicast/_index.md @@ -0,0 +1,7 @@ +--- +type: docs +title: "广播" +linkTitle: "广播" +weight: 5 +description: "" +--- diff --git a/content/zh/docs3-building/java-sdk/reference-manual/registry/multicast/guide.md b/content/zh/docs3-building/java-sdk/reference-manual/registry/multicast/guide.md new file mode 100644 index 000000000000..643a01127eac --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/registry/multicast/guide.md @@ -0,0 +1,46 @@ +--- +type: docs +title: "使用说明" +linkTitle: "使用说明" +weight: 2 +--- + + +Multicast 注册中心不需要启动任何中心节点，只要广播地址一样，就可以互相发现。 + +![/user-guide/images/multicast.jpg](/imgs/user/multicast.jpg) + +0. 提供方启动时广播自己的地址 +1. 消费方启动时广播订阅请求 +2. 提供方收到订阅请求时，单播自己的地址给订阅者，如果设置了 `unicast=false`，则广播给订阅者 +3. 消费方收到提供方地址时，连接该地址进行 RPC 调用。 + +组播受网络结构限制，只适合小规模应用或开发阶段使用。组播地址段: 224.0.0.0 - 239.255.255.255 + +## 配置 + +```xml + +``` + +或 + +```xml + +``` + +为了减少广播量，Dubbo 缺省使用单播发送提供者地址信息给消费者，如果一个机器上同时启了多个消费者进程，消费者需声明 `unicast=false`，否则只会有一个消费者能收到消息; 当服务者和消费者运行在同一台机器上，消费者同样需要声明`unicast=false`，否则消费者无法收到消息，导致No provider available for the service异常： + +```xml + + + +``` + +或 + +```xml + + + +``` diff --git a/content/zh/docs3-building/java-sdk/reference-manual/registry/multicast/overview.md b/content/zh/docs3-building/java-sdk/reference-manual/registry/multicast/overview.md new file mode 100644 index 000000000000..c087fc3b6f43 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/registry/multicast/overview.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "概述" +linkTitle: "概述" +weight: 1 +--- diff --git a/content/zh/docs3-building/java-sdk/reference-manual/registry/multiple-registry/_index.md b/content/zh/docs3-building/java-sdk/reference-manual/registry/multiple-registry/_index.md new file mode 100644 index 000000000000..6ed4ddc4e412 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/registry/multiple-registry/_index.md @@ -0,0 +1,7 @@ +--- +type: docs +title: "多注册中心" +linkTitle: "多注册中心" +weight: 6 +description: "" +--- diff --git a/content/zh/docs3-building/java-sdk/reference-manual/registry/multiple-registry/guide.md b/content/zh/docs3-building/java-sdk/reference-manual/registry/multiple-registry/guide.md new file mode 100644 index 000000000000..37430b92141b --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/registry/multiple-registry/guide.md @@ -0,0 +1,7 @@ +--- +type: docs +title: "使用说明" +linkTitle: "使用说明" +weight: 2 +--- + diff --git a/content/zh/docs3-building/java-sdk/reference-manual/registry/multiple-registry/overview.md b/content/zh/docs3-building/java-sdk/reference-manual/registry/multiple-registry/overview.md new file mode 100644 index 000000000000..c087fc3b6f43 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/registry/multiple-registry/overview.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "概述" +linkTitle: "概述" +weight: 1 +--- diff --git a/content/zh/docs3-building/java-sdk/reference-manual/registry/nacos/_index.md b/content/zh/docs3-building/java-sdk/reference-manual/registry/nacos/_index.md new file mode 100644 index 000000000000..7fed8cf789af --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/registry/nacos/_index.md @@ -0,0 +1,7 @@ +--- +type: docs +title: "Nacos" +linkTitle: "Nacos" +weight: 3 +description: "" +--- diff --git a/content/zh/docs3-building/java-sdk/reference-manual/registry/nacos/guide.md b/content/zh/docs3-building/java-sdk/reference-manual/registry/nacos/guide.md new file mode 100644 index 000000000000..a27ab64cac9f --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/registry/nacos/guide.md @@ -0,0 +1,135 @@ +--- +type: docs +title: "使用说明" +linkTitle: "使用说明" +weight: 2 +--- + +Nacos 是 Dubbo 生态系统中重要的注册中心实现，其中 [`dubbo-registry-nacos`](https://github.com/apache/incubator-dubbo/tree/master/dubbo-registry/dubbo-registry-nacos) 则是 Dubbo 融合 Nacos 注册中心的实现。 + +## 预备工作 + +当您将 [dubbo-registry-nacos](https://github.com/apache/incubator-dubbo/tree/master/dubbo-registry/dubbo-registry-nacos) 整合到您的 Dubbo 工程之前，请确保后台已经启动 Nacos 服务。如果您尚且不熟悉 Nacos 的基本使用的话，可先行参考 [Nacos 快速入门](https://nacos.io/en-us/docs/quick-start.html)。建议使用 Nacos `1.0.0` 及以上的版本。 + +## 快速上手 + +Dubbo 融合 Nacos 成为注册中心的操作步骤非常简单，大致步骤可分为“增加 Maven 依赖”以及“配置注册中心“。 + + +### 增加 Maven 依赖 + +首先，您需要将 `dubbo-registry-nacos` 的 Maven 依赖添加到您的项目 `pom.xml` 文件中，并且强烈地推荐您使用 Dubbo `2.6.5`： + +```xml + + + ... + + + + com.alibaba + dubbo-registry-nacos + 0.0.2 + + + + + com.alibaba.nacos + nacos-client + [0.6.1,) + + + + + com.alibaba + dubbo + 2.6.5 + + + + + com.alibaba.spring + spring-context-support + 1.0.2 + + + ... + + +``` + +当项目中添加 `dubbo-registry-nacos` 后，您无需显式地编程实现服务发现和注册逻辑，实际实现由该三方包提供，接下来配置 Naocs 注册中心。 + +### 配置注册中心 + +假设您 Dubbo 应用使用 Spring Framework 装配，将有两种配置方法可选，分别为：[Dubbo Spring 外部化配置](https://mercyblitz.github.io/2018/01/18/Dubbo-%E5%A4%96%E9%83%A8%E5%8C%96%E9%85%8D%E7%BD%AE/)以及 Spring XML 配置文件，推荐前者。 + + +### Dubbo Spring 外部化配置 + +> [参考](https://mercyblitz.github.io/2018/01/18/Dubbo-%E5%A4%96%E9%83%A8%E5%8C%96%E9%85%8D%E7%BD%AE/) + +Dubbo Spring 外部化配置是由 Dubbo `2.5.8` 引入的新特性，可通过 Spring `Environment` 属性自动地生成并绑定 Dubbo 配置 Bean，实现配置简化，并且降低微服务开发门槛。 + +假设您的 Nacos Server 同样运行在服务器 `10.20.153.10` 上，并使用默认 Nacos 服务端口 `8848`，您只需将 `dubbo.registry.address` 属性调整如下： + +```properties +## 其他属性保持不变 + +## Nacos registry address +dubbo.registry.address = nacos://10.20.153.10:8848 +... +``` + +随后，重启您的 Dubbo 应用，Dubbo 的服务提供和消费信息在 Nacos 控制台中可以显示： + +![dubbo-registry-nacos-1.png](/imgs/blog/dubbo-registry-nacos-1.png) + + + +如图所示，服务名前缀为 `providers:` 的信息为服务提供者的元信息，`consumers:` 则代表服务消费者的元信息。点击“**详情**”可查看服务状态详情： + +![image-dubbo-registry-nacos-2.png](/imgs/blog/dubbo-registry-nacos-2.png) + +如果您正在使用 Spring XML 配置文件装配 Dubbo 注册中心的话，请参考下一节。 + +### Spring XML 配置文件 + +与 [Dubbo Spring 外部化配置](https://mercyblitz.github.io/2018/01/18/Dubbo-%E5%A4%96%E9%83%A8%E5%8C%96%E9%85%8D%E7%BD%AE/) 配置类似，只需要调整 `address` 属性配置即可： + +```xml + + + + + + + + + ... + +``` + + + +重启 Dubbo 应用后，您同样也能发现服务提供方和消费方的注册元信息呈现在 Nacos 控制台中： + +![dubbo-registry-nacos-3.png](/imgs/blog/dubbo-registry-nacos-3.png) + + +**附加信息**: 在nacos-server@`1.0.0`版本后，支持客户端通过上报一些包含特定的元数据的实例到服务端来控制实例的一些行为。 + +例如: +`preserved.heart.beat.timeout` : 该实例在不发送心跳后，从健康到不健康的时间。（单位:毫秒） +`preserved.ip.delete.timeout` : 该实例在不发送心跳后，被服务端下掉该实例的时间。（单位:毫秒） +`preserved.heart.beat.interval` : 该实例在客户端上报心跳的间隔时间。（单位:毫秒） +`preserved.instance.id.generator`: 该实例的id生成策略，值为`snowflake`时，从0开始增加。 +`preserved.register.source` : 保留键，目前未使用。 + +该功能将在Dubbo@`2.7.10`开始支持，通过在address中增加参数来进行配置. +例如: `nacos://10.20.153.10:8848?preserved.heart.beat.timeout=15000&preserved.ip.delete.timeout=30000&preserved.heart.beat.interval=10000` + + diff --git a/content/zh/docs3-building/java-sdk/reference-manual/registry/nacos/overview.md b/content/zh/docs3-building/java-sdk/reference-manual/registry/nacos/overview.md new file mode 100644 index 000000000000..c087fc3b6f43 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/registry/nacos/overview.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "概述" +linkTitle: "概述" +weight: 1 +--- diff --git a/content/zh/docs3-building/java-sdk/reference-manual/registry/overview/_index.md b/content/zh/docs3-building/java-sdk/reference-manual/registry/overview/_index.md new file mode 100644 index 000000000000..15061f9901ac --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/registry/overview/_index.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "注册中心概述" +linkTitle: "注册中心概述" +weight: 1 +--- diff --git a/content/zh/docs3-building/java-sdk/reference-manual/registry/redis/_index.md b/content/zh/docs3-building/java-sdk/reference-manual/registry/redis/_index.md new file mode 100644 index 000000000000..34200f813988 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/registry/redis/_index.md @@ -0,0 +1,7 @@ +--- +type: docs +title: "Redis" +linkTitle: "Redis" +weight: 4 +description: "" +--- diff --git a/content/zh/docs3-building/java-sdk/reference-manual/registry/redis/guide.md b/content/zh/docs3-building/java-sdk/reference-manual/registry/redis/guide.md new file mode 100644 index 000000000000..206f48c01459 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/registry/redis/guide.md @@ -0,0 +1,86 @@ +--- +type: docs +title: "使用说明" +linkTitle: "使用说明" +weight: 2 +--- + + +基于 Redis [^1] 实现的注册中心。 + +{{% alert title="提示" color="primary" %}} +从 `2.1.0` 版本开始支持。 + +Redis 过期数据通过心跳的方式检测脏数据，服务器时间必须同步，并且对服务器有一定压力，否则过期检测会不准确 +{{% /alert %}} + +![/user-guide/images/dubbo-redis-registry.jpg](/imgs/user/dubbo-redis-registry.jpg) + +使用 Redis 的 Key/Map 结构存储数据结构： + +* 主 Key 为服务名和类型 +* Map 中的 Key 为 URL 地址 +* Map 中的 Value 为过期时间，用于判断脏数据，脏数据由监控中心删除 [^3] + +使用 Redis 的 Publish/Subscribe 事件通知数据变更： + +* 通过事件的值区分事件类型：`register`, `unregister`, `subscribe`, `unsubscribe` +* 普通消费者直接订阅指定服务提供者的 Key，只会收到指定服务的 `register`, `unregister` 事件 +* 监控中心通过 `psubscribe` 功能订阅 `/dubbo/*`，会收到所有服务的所有变更事件 + +调用过程： + +0. 服务提供方启动时，向 `Key:/dubbo/com.foo.BarService/providers` 下，添加当前提供者的地址 +1. 并向 `Channel:/dubbo/com.foo.BarService/providers` 发送 `register` 事件 +2. 服务消费方启动时，从 `Channel:/dubbo/com.foo.BarService/providers` 订阅 `register` 和 `unregister` 事件 +3. 并向 `Key:/dubbo/com.foo.BarService/consumers` 下，添加当前消费者的地址 +4. 服务消费方收到 `register` 和 `unregister` 事件后，从 `Key:/dubbo/com.foo.BarService/providers` 下获取提供者地址列表 +5. 服务监控中心启动时，从 `Channel:/dubbo/*` 订阅 `register` 和 `unregister`，以及 `subscribe` 和`unsubsribe `事件 +6. 服务监控中心收到 `register` 和 `unregister` 事件后，从 `Key:/dubbo/com.foo.BarService/providers` 下获取提供者地址列表 +7. 服务监控中心收到 `subscribe` 和 `unsubsribe` 事件后，从 `Key:/dubbo/com.foo.BarService/consumers` 下获取消费者地址列表 + + +## 配置 + +```xml + +``` + +或 + +```xml + +``` + +或 + +```xml + +``` + +或 + +```xml + +``` + +## 选项 + +* 可通过 `` 设置 redis 中 key 的前缀，缺省为 `dubbo`。 +* 可通过 `` 设置 redis 集群策略，缺省为 `failover`： + * `failover`: 只写入和读取任意一台，失败时重试另一台，需要服务器端自行配置数据同步 + * `replicate`: 在客户端同时写入所有服务器，只读取单台，服务器端不需要同步，注册中心集群增大，性能压力也会更大 + + +## 可靠性声明 + +阿里内部并没有采用 Redis 做为注册中心，而是使用自己实现的基于数据库的注册中心，即：Redis 注册中心并没有在阿里内部长时间运行的可靠性保障，此 Redis 桥接实现只为开源版本提供，其可靠性依赖于 Redis 本身的可靠性。 + + +## 安装 + + +安装方式参见: [Redis安装手册]( ../../../admin/install/redis.md)，只需搭一个原生的 Redis 服务器，并将 [Quick Start](../../preface/usage.md) 中 Provider 和 Consumer 里的 `conf/dubbo.properties` 中的 `dubbo.registry.address` 的值改为 `redis://127.0.0.1:6379` 即可使用。 + + +[^1]: [Redis](http://redis.io) 是一个高效的 KV 存储服务器 diff --git a/content/zh/docs3-building/java-sdk/reference-manual/registry/redis/overview.md b/content/zh/docs3-building/java-sdk/reference-manual/registry/redis/overview.md new file mode 100644 index 000000000000..c087fc3b6f43 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/registry/redis/overview.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "概述" +linkTitle: "概述" +weight: 1 +--- diff --git a/content/zh/docs3-building/java-sdk/reference-manual/registry/zookeeper/_index.md b/content/zh/docs3-building/java-sdk/reference-manual/registry/zookeeper/_index.md new file mode 100644 index 000000000000..2864a6f0b145 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/registry/zookeeper/_index.md @@ -0,0 +1,7 @@ +--- +type: docs +title: "Zookeeper" +linkTitle: "Zookeeper" +weight: 2 +description: "" +--- diff --git a/content/zh/docs3-building/java-sdk/reference-manual/registry/zookeeper/guide.md b/content/zh/docs3-building/java-sdk/reference-manual/registry/zookeeper/guide.md new file mode 100644 index 000000000000..5e4123f03a1f --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/registry/zookeeper/guide.md @@ -0,0 +1,171 @@ +--- +type: docs +title: "使用说明" +linkTitle: "使用说明" +weight: 2 +--- + + +[Zookeeper](http://zookeeper.apache.org) 是 Apache Hadoop 的子项目，是一个树型的目录服务，支持变更推送，适合作为 Dubbo 服务的注册中心，工业强度较高，可用于生产环境，并推荐使用 [^1]。 + +![/user-guide/images/zookeeper.jpg](/imgs/user/zookeeper.jpg) + +流程说明： + +* 服务提供者启动时: 向 `/dubbo/com.foo.BarService/providers` 目录下写入自己的 URL 地址 +* 服务消费者启动时: 订阅 `/dubbo/com.foo.BarService/providers` 目录下的提供者 URL 地址。并向 `/dubbo/com.foo.BarService/consumers` 目录下写入自己的 URL 地址 +* 监控中心启动时: 订阅 `/dubbo/com.foo.BarService` 目录下的所有提供者和消费者 URL 地址。 + +支持以下功能： + +* 当提供者出现断电等异常停机时，注册中心能自动删除提供者信息 +* 当注册中心重启时，能自动恢复注册数据，以及订阅请求 +* 当会话过期时，能自动恢复注册数据，以及订阅请求 +* 当设置 `` 时，记录失败注册和订阅请求，后台定时重试 +* 可通过 `` 设置 zookeeper 登录信息 +* 可通过 `` 设置 zookeeper 的根节点，不配置将使用默认的根节点。 +* 支持 `*` 号通配符 ``，可订阅服务的所有分组和所有版本的提供者 + +## 使用 + +在 provider 和 consumer 中增加 zookeeper 客户端 jar 包依赖： + +```xml + + org.apache.zookeeper + zookeeper + 3.8.0 + +``` + +或直接[下载](http://repo1.maven.org/maven2/org/apache/zookeeper/zookeeper)。 + +Dubbo 支持 zkclient 和 curator 两种 Zookeeper 客户端实现： + +**注意:在2.7.x的版本中已经移除了zkclient的实现,如果要使用zkclient客户端,需要自行拓展** + +### 使用 zkclient 客户端 + +从 `2.2.0` 版本开始缺省为 zkclient 实现，以提升 zookeeper 客户端的健壮性。[zkclient](https://github.com/sgroschupf/zkclient) 是 Datameer 开源的一个 Zookeeper 客户端实现。 + +缺省配置： + +```xml + +``` + +或： + +```sh +dubbo.registry.client=zkclient +``` + +或： + +```sh +zookeeper://10.20.153.10:2181?client=zkclient +``` + +需依赖或直接[下载](http://repo1.maven.org/maven2/com/github/sgroschupf/zkclient)： + +```xml + + com.github.sgroschupf + zkclient + 0.11 + +``` + + +### 使用 curator 客户端 + +从 `2.3.0` 版本开始支持可选 curator 实现。[Curator](https://github.com/apache/curator) 是 Netflix 开源的一个 Zookeeper 客户端实现。 + +如果需要改为 curator 实现，请配置： + +```xml + +``` + +或： + +```sh +dubbo.registry.client=curator +``` + +或： + +```sh +zookeeper://10.20.153.10:2181?client=curator +``` + +需依赖或直接下载[curator-framework](https://repo1.maven.org/maven2/org/apache/curator/curator-framework/), [curator-recipes](https://repo1.maven.org/maven2/org/apache/curator/curator-recipes/)： + +```xml + + 5.2.1 + + + + org.apache.curator + curator-framework + ${curator.version} + + + org.apache.curator + curator-recipes + ${curator.version} + + + org.apache.curator + curator-x-discovery + ${curator.version} + +``` + +Zookeeper 单机配置: + +```xml + +``` + +或： + +```xml + +``` + +Zookeeper 集群配置： + +```xml + + +``` + +或： + +```xml + +``` + +同一 Zookeeper，分成多组注册中心: + +```xml + + +``` + +## zookeeper 安装 + +安装方式参见: [Zookeeper安装手册](../../../../docsv2.7/admin/install/zookeeper)，只需搭一个原生的 Zookeeper 服务器，并将 [Quick Start](../../../quick-start) 中 Provider 和 Consumer 里的 `conf/dubbo.properties` 中的 `dubbo.registry.address` 的值改为 `zookeeper://127.0.0.1:2181` 即可使用。 + + +## 可靠性声明 + +阿里内部并没有采用 Zookeeper 做为注册中心，而是使用自己实现的基于数据库的注册中心，即：Zookeeper 注册中心并没有在阿里内部长时间运行的可靠性保障，此 Zookeeper 桥接实现只为开源版本提供，其可靠性依赖于 Zookeeper 本身的可靠性。 + +## 兼容性声明 + +因 `2.0.8` 最初设计的 zookeeper 存储结构不能扩充不同类型的数据，`2.0.9` 版本做了调整，所以不兼容，需全部改用 `2.0.9` 版本才行，以后的版本会保持兼容 `2.0.9`。`2.2.0` 版本改为基于 zkclient 实现，需增加 zkclient 的依赖包，`2.3.0` 版本增加了基于 curator 的实现，作为可选实现策略。 + +[^1]: 建议使用 `2.3.3` 以上版本的 zookeeper 注册中心客户端 diff --git a/content/zh/docs3-building/java-sdk/reference-manual/registry/zookeeper/overview.md b/content/zh/docs3-building/java-sdk/reference-manual/registry/zookeeper/overview.md new file mode 100644 index 000000000000..c087fc3b6f43 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/registry/zookeeper/overview.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "概述" +linkTitle: "概述" +weight: 1 +--- diff --git a/content/zh/docs3-building/java-sdk/reference-manual/spi/_index.md b/content/zh/docs3-building/java-sdk/reference-manual/spi/_index.md new file mode 100755 index 000000000000..4201d07472a0 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/spi/_index.md @@ -0,0 +1,8 @@ + +--- +type: docs +title: "SPI扩展使用手册" +linkTitle: "SPI扩展使用手册" +weight: 2 +--- + diff --git a/content/zh/docs3-building/java-sdk/reference-manual/spi/description/_index.md b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/_index.md new file mode 100644 index 000000000000..285cc5f79cf9 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/_index.md @@ -0,0 +1,6 @@ +--- +type: docs +title: "Dubbo SPI扩展实现说明" +linkTitle: "Dubbo SPI扩展实现说明" +weight: 2 +--- diff --git a/content/zh/docs3-building/java-sdk/reference-manual/spi/description/cache.md b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/cache.md new file mode 100644 index 000000000000..7e5f8ff9cdbe --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/cache.md @@ -0,0 +1,88 @@ +--- +type: docs +title: "缓存扩展" +linkTitle: "缓存扩展" +weight: 24 +--- + +## 扩展说明 + +用请求参数作为 key，缓存返回结果。 + +## 扩展接口 + +`org.apache.dubbo.cache.CacheFactory` + +## 扩展配置 + +```xml + + + + + +``` + +## 已知扩展 + +* `org.apache.dubbo.cache.support.lru.LruCacheFactory` +* `org.apache.dubbo.cache.support.threadlocal.ThreadLocalCacheFactory` +* `org.apache.dubbo.cache.support.jcache.JCacheFactory` + + +## 扩展示例 + +Maven 项目结构： + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxCacheFactory.java (实现CacheFactory接口) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.cache.CacheFactory (纯文本文件，内容为：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 +``` diff --git a/content/zh/docs3-building/java-sdk/reference-manual/spi/description/cluster.md b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/cluster.md new file mode 100644 index 000000000000..1d2cf8c04f67 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/cluster.md @@ -0,0 +1,83 @@ +--- +type: docs +title: "集群扩展" +linkTitle: "集群扩展" +weight: 5 +--- + +## 扩展说明 + +当有多个服务提供方时，将多个服务提供方组织成一个集群，并伪装成一个提供方。 + +## 扩展接口 + +`org.apache.dubbo.rpc.cluster.Cluster` + +## 扩展配置 + +```xml + + + +``` + +## 已知扩展 + +* `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` + +## 扩展示例 + +Maven 项目结构： + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxCluster.java (实现Cluster接口) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.rpc.cluster.Cluster (纯文本文件，内容为：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 +``` diff --git a/content/zh/docs3-building/java-sdk/reference-manual/spi/description/compiler.md b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/compiler.md new file mode 100644 index 000000000000..bdc9fda8ebab --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/compiler.md @@ -0,0 +1,60 @@ +--- +type: docs +title: "编译器扩展" +linkTitle: "编译器扩展" +weight: 13 +--- + +## 扩展说明 + +Java 代码编译器，用于动态生成字节码，加速调用。 + +## 扩展接口 + +`org.apache.dubbo.common.compiler.Compiler` + +## 扩展配置 + +自动加载 + +## 已知扩展 + +* `org.apache.dubbo.common.compiler.support.JdkCompiler` +* `org.apache.dubbo.common.compiler.support.JavassistCompiler` + +## 扩展示例 + +Maven 项目结构： + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxCompiler.java (实现Compiler接口) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.common.compiler.Compiler (纯文本文件，内容为：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 +``` diff --git a/content/zh/docs3-building/java-sdk/reference-manual/spi/description/config-center.md b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/config-center.md new file mode 100644 index 000000000000..90d192f6367b --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/config-center.md @@ -0,0 +1,103 @@ +--- +type: docs +title: "配置中心扩展" +linkTitle: "配置中心扩展" +weight: 13 +--- + +## 设计目的 + +配置中心的核心功能是作为 Key-Value 存储，Dubbo 框架告知配置中心其关心的 key，配置中心返回该key对应的 value 值。 + +按照应用场景划分，配置中心在 Dubbo 框架中主要承担以下职责： + +- 作为外部化配置中心，即存储 dubbo.properties 配置文件，此时，key 值通常为文件名如 dubbo.properties，value 则为配置文件内容。 +- 存储单个配置项，如各种开关项、常量值等。 +- 存储服务治理规则，此时key通常按照 "服务名+规则类型" 的格式来组织，而 value 则为具体的治理规则。 + +为了进一步实现对 key-value 的分组管理，Dubbo 的配置中心还加入了 namespace、group 的概念，这些概念在很多专业的第三方配置中心中都有体现，通常情况下，namespace 用来隔离不同的租户，group 用来对同一租户的key集合做分组。 + +当前，Dubbo 配置中心实现了对 Zookeeper、Nacos、Etcd、Consul、Apollo 的对接，接下来我们具体看一下 Dubbo 抽象的配置中心是怎么映射到具体的第三方实现中的。 + +## 扩展接口 + +* `org.apache.dubbo.configcenter.DynamicConfigurationFactory` +* `org.apache.dubbo.configcenter.DynamicConfiguration` + +## 已知扩展 + +* `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` + +## 实现原理 + +### Zookeeper + +zookeeper提供了一个树状的存储模型，其实现原理如下： + +![image-20190127225608553](/imgs/dev/configcenter_zk_model.jpg) + +namespace, group, key 等分别对应不同层级的 ZNode 节点，而 value 则作为根 ZNode 节点的值存储。 + +1. 外部化配置中心 dubbo.properties + + ![image-20190127225608553](/imgs/dev/configcenter_zk_properties.jpg) + + 上图展示了两个不同作用域的 dubbo.properties 文件在 zookeeper 中的存储结构： + - 命名空间namespace都为：dubbo + - 分组 group：全局级别为 dubbo，所有应用共享；应用级别为应用名 demo-provider，只对该应用生效 + - key：dubbo.properties + +2. 单个配置项 + + ![image-20190127225608553](/imgs/dev/configcenter_zk_singleitem.jpg) + + 设置优雅停机事件为15000： + - 命名空间 namespace：dubbo + - 分组 group：dubbo + - key：dubbo.service.shutdown.wait + - value：15000 + +3. 服务治理规则 + + ![image-20190127225608553](/imgs/dev/configcenter_zk_rule.jpg) + + 上图展示了一条应用级别的条件路由规则： + + - 命名空间 namespace：dubbo + - 分组 group：dubbo + - key：governance-conditionrouter-consumer.condition-router，其中 governance-conditionrouter-consumer 为应用名，condition-router 代表条件路由 + + + > 注意: + > + > Dubbo同时支持应用、服务两种粒度的服务治理规则，对于这两种粒度，其key取值规则如下： + > * 应用粒度 {应用名 + 规则后缀}。如: `demo-application.configurators`、`demo-application.tag-router`等 + > * 服务粒度 {服务接口名:[服务版本]:[服务分组] + 规则后缀}，其中服务版本、服务分组是可选的，如果它们有配置则在key中体现，没被配置则用":"占位。如 + > `org.apache.dubbo.demo.DemoService::.configurators`、`org.apache.dubbo.demo.DemoService:1.0.0:group1.configurators` + +### Etcd & Consul + +Etcd 和 Consul 本质上也是一种类似 zookeeper 的树状存储结构，实现请参考 zookeeper。 + +### Nacos + +Nacos 作为一个专业的第三方配置中心，拥有专门为配置中心设计的存储结构，包括内置的 namespace、group、dataid 等概念。并且这几个概念基本上与 Dubbo 框架抽象的配置中心是一一对应的。 + +与 Zookeeper 实现的对应关系如下： + +![image-20190127225608553](/imgs/dev/configcenter_nacos_model.jpg) + +参考上文关于 zookeeper 实现中描述的示例，这里的 dataid 可能为： +* 外部化配置中心：dubbo.properties +* 单个配置项：dubbo.service.shutdown.wait +* 服务治理规则：org.apache.dubbo.demo.DemoService:1.0.0:group1.configurators + +### Apollo + +Apollo 与 Nacos 类似，请参考动态配置中心使用文档中关于 Apollo 部分的描述。 + diff --git a/content/zh/docs3-building/java-sdk/reference-manual/spi/description/container.md b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/container.md new file mode 100644 index 000000000000..355227d81417 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/container.md @@ -0,0 +1,67 @@ +--- +type: docs +title: "容器扩展" +linkTitle: "容器扩展" +weight: 22 +--- + +## 扩展说明 + +服务容器扩展，用于自定义加载内容。 + +## 扩展接口 + +`org.apache.dubbo.container.Container` + +## 扩展配置 + +```sh +java org.apache.dubbo.container.Main spring jetty log4j +``` + +## 已知扩展 + +* `org.apache.dubbo.container.spring.SpringContainer` +* `org.apache.dubbo.container.spring.JettyContainer` +* `org.apache.dubbo.container.spring.Log4jContainer` + +## 扩展示例 + +Maven 项目结构： + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxContainer.java (实现Container接口) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.container.Container (纯文本文件，内容为：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 +``` diff --git a/content/zh/docs3-building/java-sdk/reference-manual/spi/description/dispatcher.md b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/dispatcher.md new file mode 100644 index 000000000000..9338fa963081 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/dispatcher.md @@ -0,0 +1,67 @@ +--- +type: docs +title: "消息派发扩展" +linkTitle: "消息派发扩展" +weight: 14 +--- + +## 扩展说明 + +通道信息派发器，用于指定线程池模型。 + +## 扩展接口 + +`org.apache.dubbo.remoting.Dispatcher` + +## 扩展配置 + +```xml + + + +``` + +## 已知扩展 + +* `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` + +## 扩展示例 + +Maven 项目结构： + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxDispatcher.java (实现Dispatcher接口) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.remoting.Dispatcher (纯文本文件，内容为：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 +``` diff --git a/content/zh/docs3-building/java-sdk/reference-manual/spi/description/dubbo-spi.md b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/dubbo-spi.md new file mode 100644 index 000000000000..e374804898b1 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/dubbo-spi.md @@ -0,0 +1,693 @@ +--- +type: docs +title: "扩展点开发指南" +linkTitle: "扩展点开发指南" +weight: 0 +description: "本文介绍了 Dubbo SPI 的原理和实现细节" +--- + +## 1.简介 + +SPI 全称为 Service Provider Interface，是一种服务发现机制。SPI 的本质是将接口实现类的全限定名配置在文件中，并由服务加载器读取配置文件，加载实现类。这样可以在运行时，动态为接口替换实现类。正因此特性，我们可以很容易的通过 SPI 机制为我们的程序提供拓展功能。SPI 机制在第三方框架中也有所应用，比如 Dubbo 就是通过 SPI 机制加载所有的组件。不过，Dubbo 并未使用 Java 原生的 SPI 机制，而是对其进行了增强，使其能够更好的满足需求。在 Dubbo 中，SPI 是一个非常重要的模块。基于 SPI，我们可以很容易的对 Dubbo 进行拓展。 +Dubbo 中，SPI 主要有两种用法，一种是加载固定的扩展类，另一种是加载自适应扩展类。这两种方式会在下面详细的介绍。 +需要特别注意的是: 在 Dubbo 中，基于 SPI 扩展加载的类是单例的。 + +### 1.1 加载固定的扩展类 + +如果让你来设计加载固定扩展类，你会怎么做了？ +一种常见思路是读取特定目录下的配置文件，然后解析出全类名，通过反射机制来实例化这个类，然后将这个类放在集合中存起来，如果有需要的时候，直接从集合中取。Dubbo 中的实现也是这么一个思路。 +不过在 Dubbo 中，实现的更加完善，它实现类了 IOC 和 AOP 的功能。IOC 就是说如果这个扩展类依赖其他属性，Dubbo 会自动的将这个属性进行注入。这个功能如何实现了？一个常见思路是获取这个扩展类的 setter + 方法，调用 setter 方法进行属性注入。AOP 指的是什么了？这个说的是 Dubbo 能够为扩展类注入其包装类。比如 DubboProtocol 是 Protocol 的扩展类，ProtocolListenerWrapper 是 DubboProtocol 的包装类。 + +### 1.2 加载自适应扩展类 + +先说明下自适应扩展类的使用场景。比如我们有需求，在调用某一个方法时，基于参数选择调用到不同的实现类。和工厂方法有些类似，基于不同的参数，构造出不同的实例对象。 +在 Dubbo 中实现的思路和这个差不多，不过 Dubbo 的实现更加灵活，它的实现和策略模式有些类似。每一种扩展类相当于一种策略，基于 URL 消息总线，将参数传递给 ExtensionLoader，通过 ExtensionLoader 基于参数加载对应的扩展类，实现运行时动态调用到目标实例上。 + +## 2. Dubbo SPI 源码分析 + +### 2.1 加载固定的扩展类 + +Dubbo 中，SPI 加载固定扩展类的入口是 ExtensionLoader 的 getExtension 方法，下面我们对拓展类对象的获取过程进行详细的分析。 + +```java +public T getExtension(String name) { + if (name == null || name.length() == 0) + throw new IllegalArgumentException("Extension name == null"); + if ("true".equals(name)) { + // 获取默认的拓展实现类 + return getDefaultExtension(); + } + // Holder，顾名思义，用于持有目标对象 + Holder holder = cachedInstances.get(name); + // 这段逻辑保证了只有一个线程能够创建 Holder 对象 + if (holder == null) { + cachedInstances.putIfAbsent(name, new Holder()); + holder = cachedInstances.get(name); + } + Object instance = holder.get(); + // 双重检查 + if (instance == null) { + synchronized (holder) { + instance = holder.get(); + if (instance == null) { + // 创建拓展实例 + instance = createExtension(name); + // 设置实例到 holder 中 + holder.set(instance); + } + } + } + return (T) instance; +} +``` + +上面代码的逻辑比较简单，首先检查缓存，缓存未命中则创建拓展对象。下面我们来看一下创建拓展对象的过程是怎样的。 + +```java +private T createExtension(String name, boolean wrap) { + // 从配置文件中加载所有的拓展类，可得到“配置项名称”到“配置类”的映射关系表 + Class clazz = getExtensionClasses().get(name); + // 如果没有该接口的扩展，或者该接口的实现类不允许重复但实际上重复了，直接抛出异常 + if (clazz == null || unacceptableExceptions.contains(name)) { + throw findException(name); + } + try { + T instance = (T) EXTENSION_INSTANCES.get(clazz); + // 这段代码保证了扩展类只会被构造一次，也就是单例的. + if (instance == null) { + EXTENSION_INSTANCES.putIfAbsent(clazz, clazz.getDeclaredConstructor().newInstance()); + instance = (T) EXTENSION_INSTANCES.get(clazz); + } + // 向实例中注入依赖 + injectExtension(instance); + + // 如果启用包装的话，则自动为进行包装. + // 比如我基于 Protocol 定义了 DubboProtocol 的扩展，但实际上在 Dubbo 中不是直接使用的 DubboProtocol, 而是其包装类 + // ProtocolListenerWrapper + if (wrap) { + + List> wrapperClassesList = new ArrayList<>(); + if (cachedWrapperClasses != null) { + wrapperClassesList.addAll(cachedWrapperClasses); + wrapperClassesList.sort(WrapperComparator.COMPARATOR); + Collections.reverse(wrapperClassesList); + } + + // 循环创建 Wrapper 实例 + 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))) { + // 将当前 instance 作为参数传给 Wrapper 的构造方法，并通过反射创建 Wrapper 实例。 + // 然后向 Wrapper 实例中注入依赖，最后将 Wrapper 实例再次赋值给 instance 变量 + instance = injectExtension((T) wrapperClass.getConstructor(type).newInstance(instance)); + } + } + } + } + // 初始化 + initExtension(instance); + return instance; + } catch (Throwable t) { + throw new IllegalStateException("Extension instance (name: " + name + ", class: " + + type + ") couldn't be instantiated: " + t.getMessage(), t); + } +} +``` + +createExtension 方法的逻辑稍复杂一下，包含了如下的步骤： + +1. 通过 getExtensionClasses 获取所有的拓展类 +2. 通过反射创建拓展对象 +3. 向拓展对象中注入依赖 +4. 将拓展对象包裹在相应的 Wrapper 对象中 +5. 初始化拓展对象 + +以上步骤中，第一个步骤是加载拓展类的关键，第三和第四个步骤是 Dubbo IOC 与 AOP 的具体实现。在接下来的章节中，将会重点分析 getExtensionClasses 方法的逻辑，以及简单介绍 Dubbo IOC 的具体实现。 + +### 2.1.1 获取所有的拓展类 + +我们在通过名称获取拓展类之前，首先需要根据配置文件解析出拓展项名称到拓展类的映射关系表（Map\<名称, 拓展类\>），之后再根据拓展项名称从映射关系表中取出相应的拓展类即可。相关过程的代码分析如下： + +```java +private Map> getExtensionClasses() { + // 从缓存中获取已加载的拓展类 + Map> classes = cachedClasses.get(); + // 双重检查 + if (classes == null) { + synchronized (cachedClasses) { + classes = cachedClasses.get(); + if (classes == null) { + // 加载拓展类 + classes = loadExtensionClasses(); + cachedClasses.set(classes); + } + } + } + return classes; +} +``` + +这里也是先检查缓存，若缓存未命中，则通过 synchronized 加锁。加锁后再次检查缓存，并判空。此时如果 classes 仍为 null，则通过 loadExtensionClasses 加载拓展类。下面分析 loadExtensionClasses 方法的逻辑。 + +```java +private Map> loadExtensionClasses() { + // 缓存默认的 SPI 扩展名 + cacheDefaultExtensionName(); + + Map> extensionClasses = new HashMap<>(); + + // 基于策略来加载指定文件夹下的文件 + // 目前有四种策略，分别读取 META-INF/services/ META-INF/dubbo/ META-INF/dubbo/internal/ META-INF/dubbo/external/ 这四个目录下的配置文件 + 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; +} +``` + +loadExtensionClasses 方法总共做了两件事情，一是对 SPI 注解进行解析，二是调用 loadDirectory 方法加载指定文件夹配置文件。SPI 注解解析过程比较简单，无需多说。下面我们来看一下 loadDirectory 做了哪些事情。 + +```java +private void loadDirectory(Map> extensionClasses, String dir, String type, + boolean extensionLoaderClassLoaderFirst, boolean overridden, String... excludedPackages) { + // fileName = 文件夹路径 + type 全限定名 + 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); + } + } + // 根据文件名加载所有的同名文件 + 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(); + // 加载资源 + loadResource(extensionClasses, classLoader, resourceURL, overridden, excludedPackages); + } + } + } catch (Throwable t) { + logger.error("Exception occurred when loading extension class (interface: " + + type + ", description file: " + fileName + ").", t); + } +} +``` + +loadDirectory 方法先通过 classLoader 获取所有资源链接，然后再通过 loadResource 方法加载资源。我们继续跟下去，看一下 loadResource 方法的实现。 + +```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; + // 按行读取配置内容 + while ((line = reader.readLine()) != null) { + // 定位 # 字符 + final int ci = line.indexOf('#'); + if (ci >= 0) { + // 截取 # 之前的字符串，# 之后的内容为注释，需要忽略 + line = line.substring(0, ci); + } + line = line.trim(); + if (line.length() > 0) { + try { + String name = null; + // 以等于号 = 为界，截取键与值 + int i = line.indexOf('='); + if (i > 0) { + name = line.substring(0, i).trim(); + clazz = line.substring(i + 1).trim(); + } else { + clazz = line; + } + // 加载类，并通过 loadClass 方法对类进行缓存 + 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); + } +} +``` + +loadResource 方法用于读取和解析配置文件，并通过反射加载类，最后调用 loadClass 方法进行其他操作。loadClass 方法用于主要用于操作缓存，该方法的逻辑如下： + +```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."); + } + // 检测目标类上是否有 Adaptive 注解 + if (clazz.isAnnotationPresent(Adaptive.class)) { + cacheAdaptiveClass(clazz, overridden); + } else if (isWrapperClass(clazz)) { + // 缓存包装类 + cacheWrapperClass(clazz); + } else { + // 进入到这里，表明只是该类只是一个普通的拓展类 + // 检测 clazz 是否有默认的构造方法，如果没有，则抛出异常 + clazz.getConstructor(); + if (StringUtils.isEmpty(name)) { + // 如果 name 为空，则尝试从 Extension 注解中获取 name，或使用小写的类名作为 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)) { + // 如果类上有 Activate 注解，则使用 names 数组的第一个元素作为键， + // 存储 name 到 Activate 注解对象的映射关系 + cacheActivateClass(clazz, names[0]); + for (String n : names) { + // 存储 Class 到名称的映射关系 + cacheName(clazz, n); + // 存储 name 到 Class 的映射关系. + // 如果存在同一个扩展名对应多个实现类，基于 override 参数是否允许覆盖，如果不允许，则抛出异常. + saveInExtensionClass(extensionClasses, clazz, n, overridden); + } + } + } +} +``` + +如上，loadClass 方法操作了不同的缓存，比如 cachedAdaptiveClass、cachedWrapperClasses 和 cachedNames 等等。除此之外，该方法没有其他什么逻辑了。 + +到此，关于缓存类加载的过程就分析完了。整个过程没什么特别复杂的地方，大家按部就班的分析即可，不懂的地方可以调试一下。接下来，我们来聊聊 Dubbo IOC 方面的内容。 + +### 2.1.2 Dubbo IOC + +Dubbo IOC 是通过 setter 方法注入依赖。Dubbo 首先会通过反射获取到实例的所有方法，然后再遍历方法列表，检测方法名是否具有 setter 方法特征。若有，则通过 ObjectFactory 获取依赖对象，最后通过反射调用 setter 方法将依赖设置到目标对象中。整个过程对应的代码如下： + +```java +private T injectExtension(T instance) { + + if (objectFactory == null) { + return instance; + } + + try { + // 遍历目标类的所有方法 + for (Method method : instance.getClass().getMethods()) { + // 检测方法是否以 set 开头，且方法仅有一个参数，且方法访问级别为 public + if (!isSetter(method)) { + continue; + } + /** + * 检测是否有 DisableInject 注解修饰. + */ + if (method.getAnnotation(DisableInject.class) != null) { + continue; + } + // 基本类型不注入 + Class pt = method.getParameterTypes()[0]; + if (ReflectUtils.isPrimitives(pt)) { + continue; + } + + try { + // 获取属性名，比如 setName 方法对应属性名 name + String property = getSetterProperty(method); + // 从 ObjectFactory 中获取依赖对象 + Object object = objectFactory.getExtension(pt, property); + if (object != null) { + // 注入 + 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; +} +``` + +在上面代码中，objectFactory 变量的类型为 AdaptiveExtensionFactory，AdaptiveExtensionFactory 内部维护了一个 ExtensionFactory 列表，用于存储其他类型的 ExtensionFactory。Dubbo 目前提供了两种 ExtensionFactory，分别是 SpiExtensionFactory 和 SpringExtensionFactory。前者用于创建自适应的拓展，后者是用于从 Spring 的 IOC 容器中获取所需的拓展。这两个类的类的代码不是很复杂，这里就不一一分析了。 + +Dubbo IOC 目前仅支持 setter 方式注入，总的来说，逻辑比较简单易懂。 + +### 2.2 加载自适应扩展类 + +自适应扩展类的含义是说，基于参数，在运行时动态选择到具体的目标类，然后执行。 +在 Dubbo 中，很多拓展都是通过 SPI 机制进行加载的，比如 Protocol、Cluster、LoadBalance 等。有时，有些拓展并不想在框架启动阶段被加载，而是希望在拓展方法被调用时，根据运行时参数进行加载。这听起来有些矛盾。拓展未被加载，那么拓展方法就无法被调用（静态方法除外）。拓展方法未被调用，拓展就无法被加载。对于这个矛盾的问题，Dubbo 通过自适应拓展机制很好的解决了。自适应拓展机制的实现逻辑比较复杂，首先 Dubbo 会为拓展接口生成具有代理功能的代码。然后通过 javassist 或 jdk 编译这段代码，得到 Class 类。最后再通过反射创建代理类，整个过程比较复杂。 + +加载自适应扩展类的入口是 ExtensionLoader 的 getAdaptiveExtension 方法。 + +```java +public T getAdaptiveExtension() { + // 从缓存中获取自适应拓展 + Object instance = cachedAdaptiveInstance.get(); + if (instance == null) { + // 如果存在异常，则直接抛出 + 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 { + // 创建自适应拓展 + // 这里分为两种情况：一种是存在 Adaptive 类，另一个是需要生成 Adaptive 类 + instance = createAdaptiveExtension(); + cachedAdaptiveInstance.set(instance); + } catch (Throwable t) { + createAdaptiveInstanceError = t; + throw new IllegalStateException("Failed to create adaptive instance: " + t.toString(), t); + } + } + } + } + + return (T) instance; +} +``` + +getAdaptiveExtension 方法首先会检查缓存，缓存未命中，则调用 createAdaptiveExtension 方法创建自适应拓展。下面，我们看一下 createAdaptiveExtension 方法的代码。 + +```java +private T createAdaptiveExtension() { + try { + // 获取自适应拓展类，并通过反射实例化 + return injectExtension((T) getAdaptiveExtensionClass().newInstance()); + } catch (Exception e) { + throw new IllegalStateException("Can not create adaptive extension ..."); + } +} +``` +createAdaptiveExtension 方法的代码比较少，但却包含了三个逻辑，分别如下： + +1. 调用 getAdaptiveExtensionClass 方法获取自适应拓展 Class 对象 +2. 通过反射进行实例化 +3. 调用 injectExtension 方法向拓展实例中注入依赖 + +前两个逻辑比较好理解，第三个逻辑用于向自适应拓展对象中注入依赖。这个逻辑看似多余，但有存在的必要，这里简单说明一下。前面说过，Dubbo 中有两种类型的自适应拓展，一种是手工编码的，一种是自动生成的。手工编码的自适应拓展中可能存在着一些依赖，而自动生成的 Adaptive 拓展则不会依赖其他类。这里调用 injectExtension 方法的目的是为手工编码的自适应拓展注入依赖，这一点需要大家注意一下。关于 injectExtension 方法，前文已经分析过了，这里不再赘述。接下来，分析 getAdaptiveExtensionClass 方法的逻辑。 + +```java +private Class getAdaptiveExtensionClass() { + // 通过 SPI 获取所有的拓展类 + getExtensionClasses(); + // 检查缓存，若缓存不为空，则直接返回缓存 + if (cachedAdaptiveClass != null) { + return cachedAdaptiveClass; + } + // 创建自适应拓展类 + return cachedAdaptiveClass = createAdaptiveExtensionClass(); +} +``` + +getAdaptiveExtensionClass 方法同样包含了三个逻辑，如下： + +1. 调用 getExtensionClasses 获取所有的拓展类 +2. 检查缓存，若缓存不为空，则返回缓存 +3. 若缓存为空，则调用 createAdaptiveExtensionClass 创建自适应拓展类 + +这三个逻辑看起来平淡无奇，似乎没有多讲的必要。但是这些平淡无奇的代码中隐藏了着一些细节，需要说明一下。首先从第一个逻辑说起，getExtensionClasses 这个方法用于获取某个接口的所有实现类。比如该方法可以获取 Protocol 接口的 DubboProtocol、HttpProtocol、InjvmProtocol 等实现类。在获取实现类的过程中，如果某个实现类被 Adaptive 注解修饰了，那么该类就会被赋值给 cachedAdaptiveClass 变量。此时，上面步骤中的第二步条件成立（缓存不为空），直接返回 cachedAdaptiveClass 即可。如果所有的实现类均未被 Adaptive 注解修饰，那么执行第三步逻辑，创建自适应拓展类。相关代码如下： + +```java +private Class createAdaptiveExtensionClass() { + // 构建自适应拓展代码 + String code = new AdaptiveClassCodeGenerator(type, cachedDefaultName).generate(); + ClassLoader classLoader = findClassLoader(); + // 获取编译器实现类 + org.apache.dubbo.common.compiler.Compiler compiler = ExtensionLoader.getExtensionLoader(org.apache.dubbo.common.compiler.Compiler.class).getAdaptiveExtension(); + // 编译代码，生成 Class + return compiler.compile(code, classLoader); +} +``` + +createAdaptiveExtensionClass 方法用于生成自适应拓展类，该方法首先会生成自适应拓展类的源码，然后通过 Compiler 实例（Dubbo 默认使用 javassist 作为编译器）编译源码，得到代理类 Class 实例。接下来，我们把重点放在代理类代码生成的逻辑上，其他逻辑大家自行分析。 + +### 2.2.1 自适应拓展类代码生成 + +AdaptiveClassCodeGenerator#generate 方法生成扩展类代码 +```java +public String generate() { + // 如果该接口中没有方法被 @Adaptive 注解修饰，直接抛出异常 + if (!hasAdaptiveMethod()) { + throw new IllegalStateException("No adaptive method exist on extension " + type.getName() + ", refuse to create the adaptive class!"); + } + + StringBuilder code = new StringBuilder(); + // 生成包名、import、方法等. + 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 生成方法 + +上面代码中，生成方法的逻辑是最关键的，我们详细分析下。 +```java +private String generateMethod(Method method) { + String methodReturnType = method.getReturnType().getCanonicalName(); + String methodName = method.getName(); + // 生成方法内容 + String methodContent = generateMethodContent(method); + String methodArgs = generateMethodArguments(method); + String methodThrows = generateMethodThrows(method); + return String.format(CODE_METHOD_DECLARATION, methodReturnType, methodName, methodArgs, methodThrows, methodContent); +} +``` + +generateMethodContent 分析 + +```java +private String generateMethodContent(Method method) { + // 该方法上必须有 @Adaptive 注解修饰 + Adaptive adaptiveAnnotation = method.getAnnotation(Adaptive.class); + StringBuilder code = new StringBuilder(512); + if (adaptiveAnnotation == null) { + // 没有 @Adaptive 注解修饰，生成异常信息 + return generateUnsupported(method); + } else { + // 获取 URL 在参数列表上的索引 + int urlTypeIndex = getUrlTypeIndex(method); + + if (urlTypeIndex != -1) { + // 如果参数列表上存在 URL，生成对 URL 进行空检查 + code.append(generateUrlNullCheck(urlTypeIndex)); + } else { + // 如果参数列表不存在 URL 类型的参数，那么就看参数列表上参数对象中是否包含 getUrl 方法 + // 有的话，生成 URL 空检查 + code.append(generateUrlAssignmentIndirectly(method)); + } + // 解析 Adaptive 注解上的 value 属性 + String[] value = getMethodAdaptiveValue(adaptiveAnnotation); + // 如果参数列表上有 Invocation 类型的参数，生成空检查并获取 methodName. + boolean hasInvocation = hasInvocationArgument(method); + + code.append(generateInvocationArgumentNullCheck(method)); + // 这段逻辑主要就是为了生成 extName(也就是扩展名) + // 分为多种情况： + // 1.defaultExtName 是否存在 + // 2.参数中是否存在 invocation 类型参数 + // 3.是否是为 protocol 生成代理 + // 为什么要对 protocol 单独考虑了？因为 URL 中有获取 protocol 值的方法 + code.append(generateExtNameAssignment(value, hasInvocation)); + // check extName == null? + code.append(generateExtNameNullCheck(value)); + + // 生成获取扩展(使用 ExtensionLoader.getExtension 方法) + code.append(generateExtensionAssignment()); + + // 生成返回语句 + code.append(generateReturnAndInvocation(method)); + } + + return code.toString(); +} +``` + +上面那段逻辑主要做了如下几件事： +1.检查方法上是否 Adaptive 注解修饰 +2.为方法生成代码的时候，参数列表上要有 URL(或参数对象中有 URL) +3.使用 ExtensionLoader.getExtension 获取扩展 +4.执行对应的方法 + +### 2.2.3 附一个动态生成代码后的例子 + +```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 空校验 + if (arg0 == null) { + throw new IllegalArgumentException("url == null"); + } + + org.apache.dubbo.common.URL url = arg0; + // 获取扩展名 + String extName = url.getParameter("has.adaptive.ext", "adaptive"); + // 扩展名空校验 + 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])"); + } + // 获取扩展 + 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); + // 执行对应的方法 + return extension.echo(arg0, arg1); + } +} + +``` + + +## 3.SPI 扩展示例 + +### 3.1 加载固定扩展类 + +### 3.1.1 编写 SPI 接口及实现类 + +不管是 Java SPI，还是 Dubbo 中实现的 SPI，都需要编写接口。不过 Dubbo 中的接口需要被 @SPI 注解修饰。 + +```java +@SPI +public interface DemoSpi { + void say(); +} + +public class DemoSpiImpl implements DemoSpi { + public void say() { + } +} +``` + +#### 3.1.2 将实现类放在特定目录下 + +从上面的代码可知，dubbo 在加载扩展类的时候，会从四个目录中读取。我们在 META-INF/dubbo 目录下新建一个以 DemoSpi 接口名为文件名的文件，内容如下： + + +```text +demoSpiImpl = com.xxx.xxx.DemoSpiImpl(为 DemoSpi 接口实现类的全类名) +``` + +#### 3.1.3 使用 + +```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 加载自适应扩展类 + +这个以 Protocol 为例进行说明 + +### 3.2.1 Protocol 接口(抽取部分核心方法) + +```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 将实现类放在特定目录下 +在 dubbo 中，该配置路径 META-INF/dubbo/internal/org.apache.dubbo.rpc.Protocol +```text +dubbo=org.apache.dubbo.rpc.protocol.dubbo.DubboProtocol +``` + +需要说明一点的是，在 dubbo 中，并不是直接使用 DubboProtocol 的，而是使用的是其包装类。 + +### 3.2.3 使用 + +```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); + } +} +``` + diff --git a/content/zh/docs3-building/java-sdk/reference-manual/spi/description/exchanger.md b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/exchanger.md new file mode 100644 index 000000000000..967bf84c3521 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/exchanger.md @@ -0,0 +1,96 @@ +--- +type: docs +title: "信息交换扩展" +linkTitle: "信息交换扩展" +weight: 18 +--- + +## 扩展说明 + +基于传输层之上，实现 Request-Response 信息交换语义。 + +## 扩展接口 + +* `org.apache.dubbo.remoting.exchange.Exchanger` +* `org.apache.dubbo.remoting.exchange.ExchangeServer` +* `org.apache.dubbo.remoting.exchange.ExchangeClient` + +## 扩展配置 + +```xml + + + +``` + +## 已知扩展 + +`org.apache.dubbo.remoting.exchange.exchanger.HeaderExchanger` + +## 扩展示例 + +Maven 项目结构： + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxExchanger.java (实现Exchanger接口) + |-XxxExchangeServer.java (实现ExchangeServer接口) + |-XxxExchangeClient.java (实现ExchangeClient接口) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.remoting.exchange.Exchanger (纯文本文件，内容为：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 +``` diff --git a/content/zh/docs3-building/java-sdk/reference-manual/spi/description/exporter-listener.md b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/exporter-listener.md new file mode 100644 index 000000000000..0ea4c9057c75 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/exporter-listener.md @@ -0,0 +1,71 @@ +--- +type: docs +title: "暴露监听扩展" +linkTitle: "暴露监听扩展" +weight: 4 +--- + +## 扩展说明 + +当有服务暴露时，触发该事件。 + +## 扩展接口 + +`org.apache.dubbo.rpc.ExporterListener` + +## 扩展配置 + +```xml + + + + +``` + +## 已知扩展 + +`org.apache.dubbo.registry.directory.RegistryExporterListener` + +## 扩展示例 + +Maven 项目结构： + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxExporterListener.java (实现ExporterListener接口) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.rpc.ExporterListener (纯文本文件，内容为：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 +``` + diff --git a/content/zh/docs3-building/java-sdk/reference-manual/spi/description/extension-factory.md b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/extension-factory.md new file mode 100644 index 000000000000..4901b5546f3f --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/extension-factory.md @@ -0,0 +1,62 @@ +--- +type: docs +title: "扩展点加载扩展" +linkTitle: "扩展点加载扩展" +weight: 11 +--- + +## 扩展说明 + +扩展点本身的加载容器，可从不同容器加载扩展点。 + +## 扩展接口 + +`org.apache.dubbo.common.extension.ExtensionFactory` + +## 扩展配置 + +```xml + +``` + +## 已知扩展 + +* `org.apache.dubbo.common.extension.factory.SpiExtensionFactory` +* `org.apache.dubbo.config.spring.extension.SpringExtensionFactory` + +## 扩展示例 + +Maven 项目结构： + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxExtensionFactory.java (实现ExtensionFactory接口) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.common.extension.ExtensionFactory (纯文本文件，内容为：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 +``` diff --git a/content/zh/docs3-building/java-sdk/reference-manual/spi/description/filter.md b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/filter.md new file mode 100644 index 000000000000..92b916813c08 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/filter.md @@ -0,0 +1,94 @@ +--- +type: docs +title: "调用拦截扩展" +linkTitle: "调用拦截扩展" +weight: 2 +--- + +## 扩展说明 + +服务提供方和服务消费方调用过程拦截，Dubbo 本身的大多功能均基于此扩展点实现，每次远程方法执行，该拦截都会被执行，请注意对性能的影响。 + +约定： + +* 用户自定义 filter 默认在内置 filter 之后。 +* 特殊值 `default`，表示缺省扩展点插入的位置。比如：`filter="xxx,default,yyy"`，表示 `xxx` 在缺省 filter 之前，`yyy` 在缺省 filter 之后。 +* 特殊符号 `-`，表示剔除。比如：`filter="-foo1"`，剔除添加缺省扩展点 `foo1`。比如：`filter="-default"`，剔除添加所有缺省扩展点。 +* provider 和 service 同时配置的 filter 时，累加所有 filter，而不是覆盖。比如：`` 和 ``，则 `xxx`,`yyy`,`aaa`,`bbb` 均会生效。如果要覆盖，需配置：`` + +## 扩展接口 + +`org.apache.dubbo.rpc.Filter` + +## 扩展配置 + +```xml + + + + + + + + +``` + +## 已知扩展 + +* `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` + +## 扩展示例 + +Maven 项目结构： + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxFilter.java (实现Filter接口) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.rpc.Filter (纯文本文件，内容为：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/zh/docs3-building/java-sdk/reference-manual/spi/description/invoker-listener.md b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/invoker-listener.md new file mode 100644 index 000000000000..a6e130058a7e --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/invoker-listener.md @@ -0,0 +1,69 @@ +--- +type: docs +title: "引用监听扩展" +linkTitle: "引用监听扩展" +weight: 3 +--- + +## 扩展说明 + +当有服务引用时，触发该事件。 + +## 扩展接口 + +`org.apache.dubbo.rpc.InvokerListener` + +## 扩展配置 + +```xml + + + + +``` + +## 已知扩展 + +`org.apache.dubbo.rpc.listener.DeprecatedInvokerListener` + +## 扩展示例 + +Maven 项目结构： + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxInvokerListener.java (实现InvokerListener接口) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.rpc.InvokerListener (纯文本文件，内容为：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 +``` diff --git a/content/zh/docs3-building/java-sdk/reference-manual/spi/description/load-balance.md b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/load-balance.md new file mode 100644 index 000000000000..fa934238547d --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/load-balance.md @@ -0,0 +1,70 @@ +--- +type: docs +title: "负载均衡扩展" +linkTitle: "负载均衡扩展" +weight: 7 +--- + +## 扩展说明 + +从多个服务提供方中选择一个进行调用 + +## 扩展接口 + +`org.apache.dubbo.rpc.cluster.LoadBalance` + +## 扩展配置 + +```xml + + + +``` + +## 已知扩展 + +* `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` + +## 扩展示例 + +Maven 项目结构： + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxLoadBalance.java (实现LoadBalance接口) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.rpc.cluster.LoadBalance (纯文本文件，内容为：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 +``` diff --git a/content/zh/docs3-building/java-sdk/reference-manual/spi/description/logger-adapter.md b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/logger-adapter.md new file mode 100644 index 000000000000..55fac975a12c --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/logger-adapter.md @@ -0,0 +1,89 @@ +--- +type: docs +title: "日志适配扩展" +linkTitle: "日志适配扩展" +weight: 26 +--- + +## 扩展说明 + +日志输出适配扩展点。 + +## 扩展接口 + +`org.apache.dubbo.common.logger.LoggerAdapter` + +## 扩展配置 + +```xml + +``` + +或者： + +```sh +-Ddubbo:application.logger=xxx +``` + +## 已知扩展 + +* `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` + +## 扩展示例 + +Maven 项目结构： + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxLoggerAdapter.java (实现LoggerAdapter接口) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.common.logger.LoggerAdapter (纯文本文件，内容为：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/zh/docs3-building/java-sdk/reference-manual/spi/description/merger.md b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/merger.md new file mode 100644 index 000000000000..549b39be5a8f --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/merger.md @@ -0,0 +1,73 @@ +--- +type: docs +title: "合并结果扩展" +linkTitle: "合并结果扩展" +weight: 8 +--- + +## 扩展说明 + +合并返回结果，用于分组聚合。 + +## 扩展接口 + +`org.apache.dubbo.rpc.cluster.Merger` + +## 扩展配置 + +```xml + +``` + +## 已知扩展 + +* `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` + +## 扩展示例 + +Maven 项目结构： + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxMerger.java (实现Merger接口) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.rpc.cluster.Merger (纯文本文件，内容为：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 +``` + diff --git a/content/zh/docs3-building/java-sdk/reference-manual/spi/description/monitor.md b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/monitor.md new file mode 100644 index 000000000000..8e7c07cf9ffb --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/monitor.md @@ -0,0 +1,80 @@ +--- +type: docs +title: "监控中心扩展" +linkTitle: "监控中心扩展" +weight: 10 +--- + +## 扩展说明 + +负责服务调用次和调用时间的监控。 + +## 扩展接口 + +* `org.apache.dubbo.monitor.MonitorFactory` +* `org.apache.dubbo.monitor.Monitor` + +## 扩展配置 + +```xml + + +``` + +## 已知扩展 + +org.apache.dubbo.monitor.support.dubbo.DubboMonitorFactory + +## 扩展示例 + +Maven 项目结构： + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxMonitorFactoryjava (实现MonitorFactory接口) + |-XxxMonitor.java (实现Monitor接口) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.monitor.MonitorFactory (纯文本文件，内容为：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/zh/docs3-building/java-sdk/reference-manual/spi/description/networker.md b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/networker.md new file mode 100644 index 000000000000..74a81332956b --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/networker.md @@ -0,0 +1,64 @@ +--- +type: docs +title: "组网扩展" +linkTitle: "组网扩展" +weight: 19 +--- + +## 扩展说明 + +对等网络节点组网器。 + +## 扩展接口 + +`org.apache.dubbo.remoting.p2p.Networker` + +## 扩展配置 + +```xml + + + +``` + +## 已知扩展 + +* `org.apache.dubbo.remoting.p2p.support.MulticastNetworker` +* `org.apache.dubbo.remoting.p2p.support.FileNetworker` + +## 扩展示例 + +Maven 项目结构： + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxNetworker.java (实现Networker接口) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.remoting.p2p.Networker (纯文本文件，内容为：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 +``` diff --git a/content/zh/docs3-building/java-sdk/reference-manual/spi/description/page.md b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/page.md new file mode 100644 index 000000000000..f12c38d45d93 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/page.md @@ -0,0 +1,61 @@ +# 页面扩展 + +## 扩展说明 + +对等网络节点组网器。 + +## 扩展接口 + +`org.apache.dubbo.container.page.PageHandler` + +## 扩展配置 + +```xml + + + +``` + +## 已知扩展 + +* `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` + +## 扩展示例 + +Maven 项目结构： + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxPageHandler.java (实现PageHandler接口) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.container.page.PageHandler (纯文本文件，内容为：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 +``` diff --git a/content/zh/docs3-building/java-sdk/reference-manual/spi/description/protocol.md b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/protocol.md new file mode 100644 index 000000000000..6eee12537641 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/protocol.md @@ -0,0 +1,158 @@ +--- +type: docs +title: "协议扩展" +linkTitle: "协议扩展" +weight: 1 +--- + +## 扩展说明 + +RPC 协议扩展，封装远程调用细节。 + +契约： + +* 当用户调用 `refer()` 所返回的 `Invoker` 对象的 `invoke()` 方法时，协议需相应执行同 URL 远端 `export()` 传入的 `Invoker` 对象的 `invoke()` 方法。 +* 其中，`refer()` 返回的 `Invoker` 由协议实现，协议通常需要在此 `Invoker` 中发送远程请求，`export()` 传入的 `Invoker` 由框架实现并传入，协议不需要关心。 + +注意： + +* 协议不关心业务接口的透明代理，以 `Invoker` 为中心，由外层将 `Invoker` 转换为业务接口。 +* 协议不一定要是 TCP 网络通讯，比如通过共享文件，IPC 进程间通讯等。 + +## 扩展接口 + +* `org.apache.dubbo.rpc.Protocol` +* `org.apache.dubbo.rpc.Exporter` +* `org.apache.dubbo.rpc.Invoker` + +```java +public interface Protocol { + /** + * 暴露远程服务：
+ * 1. 协议在接收请求时，应记录请求来源方地址信息：RpcContext.getContext().setRemoteAddress();
+ * 2. export()必须是幂等的，也就是暴露同一个URL的Invoker两次，和暴露一次没有区别。
+ * 3. export()传入的Invoker由框架实现并传入，协议不需要关心。
+ * + * @param 服务的类型 + * @param invoker 服务的执行体 + * @return exporter 暴露服务的引用，用于取消暴露 + * @throws RpcException 当暴露服务出错时抛出，比如端口已占用 + */ + Exporter export(Invoker invoker) throws RpcException; + + /** + * 引用远程服务：
+ * 1. 当用户调用refer()所返回的Invoker对象的invoke()方法时，协议需相应执行同URL远端export()传入的Invoker对象的invoke()方法。
+ * 2. refer()返回的Invoker由协议实现，协议通常需要在此Invoker中发送远程请求。
+ * 3. 当url中有设置check=false时，连接失败不能抛出异常，需内部自动恢复。
+ * + * @param 服务的类型 + * @param type 服务的类型 + * @param url 远程服务的URL地址 + * @return invoker 服务的本地代理 + * @throws RpcException 当连接服务提供方失败时抛出 + */ + Invoker refer(Class type, URL url) throws RpcException; + +} +``` + +## 扩展配置 + +```xml + + + + + + +``` + +## 已知扩展 + +* `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` + +## 扩展示例 + +Maven项目结构： + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxProtocol.java (实现Protocol接口) + |-XxxExporter.java (实现Exporter接口) + |-XxxInvoker.java (实现Invoker接口) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.rpc.Protocol (纯文本文件，内容为：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 +``` diff --git a/content/zh/docs3-building/java-sdk/reference-manual/spi/description/proxy-factory.md b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/proxy-factory.md new file mode 100644 index 000000000000..ff712ba75dc0 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/proxy-factory.md @@ -0,0 +1,70 @@ +--- +type: docs +title: "动态代理扩展" +linkTitle: "动态代理扩展" +weight: 12 +--- + +## 扩展说明 + +将 `Invoker` 接口转换成业务接口。 + +## 扩展接口 + +`org.apache.dubbo.rpc.ProxyFactory` + +## 扩展配置 + +```xml + + + +``` + +## 已知扩展 + +* `org.apache.dubbo.rpc.proxy.JdkProxyFactory` +* `org.apache.dubbo.rpc.proxy.JavassistProxyFactory` + +## 扩展示例 + +Maven 项目结构： + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxProxyFactory.java (实现ProxyFactory接口) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.rpc.ProxyFactory (纯文本文件，内容为：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 +``` diff --git a/content/zh/docs3-building/java-sdk/reference-manual/spi/description/registry.md b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/registry.md new file mode 100644 index 000000000000..b6b738720676 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/registry.md @@ -0,0 +1,210 @@ +--- +type: docs +title: "注册中心扩展" +linkTitle: "注册中心扩展" +weight: 9 +--- + +## 扩展说明 + +负责服务的注册与发现。 + +## 扩展接口 + +* `org.apache.dubbo.registry.RegistryFactory` +* `org.apache.dubbo.registry.Registry` + +## 扩展配置 + +```xml + + + + + + +``` + +## 扩展契约 + +RegistryFactory.java： + +```java +public interface RegistryFactory { + /** + * 连接注册中心. + * + * 连接注册中心需处理契约：
+ * 1. 当设置check=false时表示不检查连接，否则在连接不上时抛出异常。
+ * 2. 支持URL上的username:password权限认证。
+ * 3. 支持backup=10.20.153.10备选注册中心集群地址。
+ * 4. 支持file=registry.cache本地磁盘文件缓存。
+ * 5. 支持timeout=1000请求超时设置。
+ * 6. 支持session=60000会话超时或过期设置。
+ * + * @param url 注册中心地址，不允许为空 + * @return 注册中心引用，总不返回空 + */ + Registry getRegistry(URL url); +} +``` + +RegistryService.java： + +```java +public interface RegistryService { // Registry extends RegistryService + /** + * 注册服务. + * + * 注册需处理契约：
+ * 1. 当URL设置了check=false时，注册失败后不报错，在后台定时重试，否则抛出异常。
+ * 2. 当URL设置了dynamic=false参数，则需持久存储，否则，当注册者出现断电等情况异常退出时，需自动删除。
+ * 3. 当URL设置了category=overrides时，表示分类存储，缺省类别为providers，可按分类部分通知数据。
+ * 4. 当注册中心重启，网络抖动，不能丢失数据，包括断线自动删除数据。
+ * 5. 允许URI相同但参数不同的URL并存，不能覆盖。
+ * + * @param url 注册信息，不允许为空，如：dubbo://10.20.153.10/com.alibaba.foo.BarService?version=1.0.0&application=kylin + */ + void register(URL url); + + /** + * 取消注册服务. + * + * 取消注册需处理契约：
+ * 1. 如果是dynamic=false的持久存储数据，找不到注册数据，则抛IllegalStateException，否则忽略。
+ * 2. 按全URL匹配取消注册。
+ * + * @param url 注册信息，不允许为空，如：dubbo://10.20.153.10/com.alibaba.foo.BarService?version=1.0.0&application=kylin + */ + void unregister(URL url); + + /** + * 订阅服务. + * + * 订阅需处理契约：
+ * 1. 当URL设置了check=false时，订阅失败后不报错，在后台定时重试。
+ * 2. 当URL设置了category=overrides，只通知指定分类的数据，多个分类用逗号分隔，并允许星号通配，表示订阅所有分类数据。
+ * 3. 允许以interface,group,version,classifier作为条件查询，如：interface=com.alibaba.foo.BarService&version=1.0.0
+ * 4. 并且查询条件允许星号通配，订阅所有接口的所有分组的所有版本，或：interface=*&group=*&version=*&classifier=*
+ * 5. 当注册中心重启，网络抖动，需自动恢复订阅请求。
+ * 6. 允许URI相同但参数不同的URL并存，不能覆盖。
+ * 7. 必须阻塞订阅过程，等第一次通知完后再返回。
+ * + * @param url 订阅条件，不允许为空，如：consumer://10.20.153.10/com.alibaba.foo.BarService?version=1.0.0&application=kylin + * @param listener 变更事件监听器，不允许为空 + */ + void subscribe(URL url, NotifyListener listener); + + /** + * 取消订阅服务. + * + * 取消订阅需处理契约：
+ * 1. 如果没有订阅，直接忽略。
+ * 2. 按全URL匹配取消订阅。
+ * + * @param url 订阅条件，不允许为空，如：consumer://10.20.153.10/com.alibaba.foo.BarService?version=1.0.0&application=kylin + * @param listener 变更事件监听器，不允许为空 + */ + void unsubscribe(URL url, NotifyListener listener); + + /** + * 查询注册列表，与订阅的推模式相对应，这里为拉模式，只返回一次结果。 + * + * @see org.apache.dubbo.registry.NotifyListener#notify(List) + * @param url 查询条件，不允许为空，如：consumer://10.20.153.10/com.alibaba.foo.BarService?version=1.0.0&application=kylin + * @return 已注册信息列表，可能为空，含义同{@link org.apache.dubbo.registry.NotifyListener#notify(List)}的参数。 + */ + List lookup(URL url); + +} +``` + +NotifyListener.java： + +```java +public interface NotifyListener { + /** + * 当收到服务变更通知时触发。 + * + * 通知需处理契约：
+ * 1. 总是以服务接口和数据类型为维度全量通知，即不会通知一个服务的同类型的部分数据，用户不需要对比上一次通知结果。
+ * 2. 订阅时的第一次通知，必须是一个服务的所有类型数据的全量通知。
+ * 3. 中途变更时，允许不同类型的数据分开通知，比如：providers, consumers, routes, overrides，允许只通知其中一种类型，但该类型的数据必须是全量的，不是增量的。
+ * 4. 如果一种类型的数据为空，需通知一个empty协议并带category参数的标识性URL数据。
+ * 5. 通知者(即注册中心实现)需保证通知的顺序，比如：单线程推送，队列串行化，带版本对比。
+ * + * @param urls 已注册信息列表，总不为空，含义同{@link org.apache.dubbo.registry.RegistryService#lookup(URL)}的返回值。 + */ + void notify(List urls); + +} +``` + +## 已知扩展 + +`org.apache.dubbo.registry.support.dubbo.DubboRegistryFactory` + +## 扩展示例 + +Maven 项目结构： + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxRegistryFactoryjava (实现RegistryFactory接口) + |-XxxRegistry.java (实现Registry接口) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.registry.RegistryFactory (纯文本文件，内容为：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/zh/docs3-building/java-sdk/reference-manual/spi/description/remoting.md b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/remoting.md new file mode 100644 index 000000000000..e243e8942fa1 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/remoting.md @@ -0,0 +1,127 @@ +--- +type: docs +title: "网络传输扩展" +linkTitle: "网络传输扩展" +weight: 17 +--- + +## 扩展说明 + +远程通讯的服务器及客户端传输实现。 + +## 扩展接口 + +* `org.apache.dubbo.remoting.Transporter` +* `org.apache.dubbo.remoting.Server` +* `org.apache.dubbo.remoting.Client` + +## 扩展配置 + +```xml + + + + + + +``` + +## 已知扩展 + +* `org.apache.dubbo.remoting.transport.transporter.netty.NettyTransporter` +* `org.apache.dubbo.remoting.transport.transporter.mina.MinaTransporter` +* `org.apache.dubbo.remoting.transport.transporter.grizzly.GrizzlyTransporter` + +## 扩展示例 + +Maven 项目结构： + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxTransporter.java (实现Transporter接口) + |-XxxServer.java (实现Server接口) + |-XxxClient.java (实现Client接口) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.remoting.Transporter (纯文本文件，内容为：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 +``` diff --git a/content/zh/docs3-building/java-sdk/reference-manual/spi/description/router.md b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/router.md new file mode 100644 index 000000000000..24d11d06b1d6 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/router.md @@ -0,0 +1,69 @@ +--- +type: docs +title: "路由扩展" +linkTitle: "路由扩展" +weight: 6 +--- + +## 扩展说明 + +从多个服务提供方中选择一个进行调用。 + +## 扩展接口 + +* `org.apache.dubbo.rpc.cluster.RouterFactory` +* `org.apache.dubbo.rpc.cluster.Router` + +## 已知扩展 + +* `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` + +## 扩展示例 + +Maven 项目结构： + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxRouterFactory.java (实现RouterFactory接口) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.rpc.cluster.RouterFactory (纯文本文件，内容为：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 +``` + + diff --git a/content/zh/docs3-building/java-sdk/reference-manual/spi/description/serialize.md b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/serialize.md new file mode 100644 index 000000000000..f8e5be849cb8 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/serialize.md @@ -0,0 +1,77 @@ +--- +type: docs +title: "序列化扩展" +linkTitle: "序列化扩展" +weight: 16 +--- + +## 扩展说明 + +将对象转成字节流，用于网络传输，以及将字节流转为对象，用于在收到字节流数据后还原成对象。 + +## 扩展接口 + +* `org.apache.dubbo.common.serialize.Serialization` +* `org.apache.dubbo.common.serialize.ObjectInput` +* `org.apache.dubbo.common.serialize.ObjectOutput` + +## 扩展配置 + +```xml + + + + +``` + +## 已知扩展 + +* `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` + +## 扩展示例 + +Maven 项目结构： + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxSerialization.java (实现Serialization接口) + |-XxxObjectInput.java (实现ObjectInput接口) + |-XxxObjectOutput.java (实现ObjectOutput接口) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.common.serialize.Serialization (纯文本文件，内容为：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 +``` diff --git a/content/zh/docs3-building/java-sdk/reference-manual/spi/description/status-checker.md b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/status-checker.md new file mode 100644 index 000000000000..3caece6d1fc9 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/status-checker.md @@ -0,0 +1,69 @@ +--- +type: docs +title: "状态检查扩展" +linkTitle: "状态检查扩展" +weight: 21 +--- + +## 扩展说明 + +检查服务依赖各种资源的状态，此状态检查可同时用于 telnet 的 status 命令和 hosting 的 status 页面。 + +## 扩展接口 + +`org.apache.dubbo.common.status.StatusChecker` + +## 扩展配置 + +```xml + + + +``` + +## 已知扩展 + +* `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` + +## 扩展示例 + +Maven 项目结构： + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxStatusChecker.java (实现StatusChecker接口) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.common.status.StatusChecker (纯文本文件，内容为：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 +``` diff --git a/content/zh/docs3-building/java-sdk/reference-manual/spi/description/telnet-handler.md b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/telnet-handler.md new file mode 100644 index 000000000000..b4a8e5d9f09f --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/telnet-handler.md @@ -0,0 +1,82 @@ +--- +type: docs +title: "Telnet 命令扩展" +linkTitle: "Telnet 命令扩展" +weight: 20 +--- + +## 扩展说明 + +所有服务器均支持 telnet 访问，用于人工干预。 + +## 扩展接口 + +`org.apache.dubbo.remoting.telnet.TelnetHandler` + +## 扩展配置 + +```xml + + + +``` + +## 已知扩展 + +* `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` + +## 扩展示例 + +Maven 项目结构： + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxTelnetHandler.java (实现TelnetHandler接口) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.remoting.telnet.TelnetHandler (纯文本文件，内容为：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 +``` + +## 用法 + +```sh +telnet 127.0.0.1 20880 +dubbo> xxx args +``` diff --git a/content/zh/docs3-building/java-sdk/reference-manual/spi/description/threadpool.md b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/threadpool.md new file mode 100644 index 000000000000..466456d684fc --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/threadpool.md @@ -0,0 +1,66 @@ +--- +type: docs +title: "线程池扩展" +linkTitle: "线程池扩展" +weight: 15 +--- + +## 扩展说明 + +服务提供方线程池实现策略，当服务器收到一个请求时，需要在线程池中创建一个线程去执行服务提供方业务逻辑。 + +## 扩展接口 + +`org.apache.dubbo.common.threadpool.ThreadPool` + +## 扩展配置 + +```xml + + + +``` + +## 已知扩展 + +* `org.apache.dubbo.common.threadpool.FixedThreadPool` +* `org.apache.dubbo.common.threadpool.CachedThreadPool` + +## 扩展示例 + +Maven 项目结构： + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxThreadPool.java (实现ThreadPool接口) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.common.threadpool.ThreadPool (纯文本文件，内容为：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 +``` + diff --git a/content/zh/docs3-building/java-sdk/reference-manual/spi/description/validation.md b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/validation.md new file mode 100644 index 000000000000..a5e0178bd615 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/spi/description/validation.md @@ -0,0 +1,80 @@ +--- +type: docs +title: "验证扩展" +linkTitle: "验证扩展" +weight: 25 +--- + +## 扩展说明 + +参数验证扩展点。 + +## 扩展接口 + +`org.apache.dubbo.validation.Validation` + +## 扩展配置 + +```xml + + + +``` + +## 已知扩展 + +`org.apache.dubbo.validation.support.jvalidation.JValidation` + +## 扩展示例 + +Maven 项目结构： + +``` +src + |-main + |-java + |-com + |-xxx + |-XxxValidation.java (实现Validation接口) + |-resources + |-META-INF + |-dubbo + |-org.apache.dubbo.validation.Validation (纯文本文件，内容为：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/zh/docs3-building/java-sdk/reference-manual/spi/overview/_index.md b/content/zh/docs3-building/java-sdk/reference-manual/spi/overview/_index.md new file mode 100644 index 000000000000..1e4143d8d413 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/reference-manual/spi/overview/_index.md @@ -0,0 +1,101 @@ +--- +type: docs +title: "Dubbo SPI概述" +linkTitle: "Dubbo SPI概述" +weight: 1 +description: "Dubbo 通过 SPI 机制提供了非常灵活的可扩展性" +--- + +## 扩展设计理念 + +可扩展性是任何一个系统所追求的，对于 Dubbo 来说是同样适用。 + +### 什么是可扩展性 + +可扩展性是一种设计理念，代表了我们对未来的一种预想，我们希望在现有的架构或设计基础上，当未来某些方面发生变化的时候，我们能够以最小的改动来适应这种变化。 + +### 可扩展性的优点 + +可扩展性的优点主要表现模块之间解耦，它符合开闭原则，对扩展开放，对修改关闭。当系统增加新功能时，不需要对现有系统的结构和代码进行修改，仅仅新增一个扩展即可。 + +### 扩展实现方式 + +一般来说，系统会采用 Factory、IoC、OSGI 等方式管理扩展(插件)生命周期。考虑到 Dubbo 的适用面，不想强依赖 Spring 等 IoC 容器。 +而自己造一个小的 IoC 容器，也觉得有点过度设计，所以选择最简单的 Factory 方式管理扩展(插件)。在 Dubbo 中，所有内部实现和第三方实现都是平等的。 + +### Dubbo 中的可扩展性 + +* 平等对待第三方的实现。在 Dubbo 中，所有内部实现和第三方实现都是平等的，用户可以基于自身业务需求，替换 Dubbo 提供的原生实现。 +* 每个扩展点只封装一个变化因子，最大化复用。每个扩展点的实现者，往往都只是关心一件事。如果用户有需求需要进行扩展，那么只需要对其关注的扩展点进行扩展就好，极大的减少用户的工作量。 + +## Dubbo 扩展的特性 + +Dubbo 中的扩展能力是从 JDK 标准的 SPI 扩展点发现机制加强而来，它改进了 JDK 标准的 SPI 以下问题： + +* JDK 标准的 SPI 会一次性实例化扩展点所有实现，如果有扩展实现初始化很耗时，但如果没用上也加载，会很浪费资源。 +* 如果扩展点加载失败，连扩展点的名称都拿不到了。比如：JDK 标准的 ScriptEngine，通过 getName() 获取脚本类型的名称，但如果 RubyScriptEngine 因为所依赖的 jruby.jar 不存在，导致 RubyScriptEngine 类加载失败，这个失败原因被吃掉了，和 ruby 对应不起来，当用户执行 ruby 脚本时，会报不支持 ruby，而不是真正失败的原因。 + +用户能够基于 Dubbo 提供的扩展能力，很方便基于自身需求扩展其他协议、过滤器、路由等。下面介绍下 Dubbo 扩展能力的特性。 + +* 按需加载。Dubbo 的扩展能力不会一次性实例化所有实现，而是用那个扩展类则实例化那个扩展类，减少资源浪费。 +* 增加扩展类的 IOC 能力。Dubbo 的扩展能力并不仅仅只是发现扩展服务实现类，而是在此基础上更进一步，如果该扩展类的属性依赖其他对象，则 Dubbo 会自动的完成该依赖对象的注入功能。 +* 增加扩展类的 AOP 能力。Dubbo 扩展能力会自动的发现扩展类的包装类，完成包装类的构造，增强扩展类的功能。 +* 具备动态选择扩展实现的能力。Dubbo 扩展会基于参数，在运行时动态选择对应的扩展类，提高了 Dubbo 的扩展能力。 +* 可以对扩展实现进行排序。能够基于用户需求，指定扩展实现的执行顺序。 +* 提供扩展点的 Adaptive 能力。该能力可以使的一些扩展类在 consumer 端生效，一些扩展类在 provider 端生效。 + +从 Dubbo 扩展的设计目标可以看出，Dubbo 实现的一些例如动态选择扩展实现、IOC、AOP 等特性，能够为用户提供非常灵活的扩展能力。 + +## Dubbo 扩展加载流程 + +Dubbo 加载扩展的整个流程如下： + +![//imgs/v3/concepts/extension-load.png](/imgs/v3/concepts/extension-load.png) + +主要步骤为 4 个： +* 读取并解析配置文件 +* 缓存所有扩展实现 +* 基于用户执行的扩展名，实例化对应的扩展实现 +* 进行扩展实例属性的 IOC 注入以及实例化扩展的包装类，实现 AOP 特性 + +## 如何使用 Dubbo 扩展能力进行扩展 + +下面以扩展注册中心为例进行说明如何利用 Dubbo 提供的扩展能力扩展 Triple 协议。 + +(1) 在协议的实现 jar 包内放置文本文件：META-INF/dubbo/org.apache.dubbo.remoting.api.WireProtocol +```text +tri=org.apache.dubbo.rpc.protocol.tri.TripleHttp2Protocol +``` + +(2) 实现类内容 +```java +@Activate +public class TripleHttp2Protocol extends Http2WireProtocol { + // ... +} +``` + +说明下：Http2WireProtocol 实现了 WireProtocol 接口 + +(3) Dubbo 配置模块中，扩展点均有对应配置属性或标签，通过配置指定使用哪个扩展实现。比如： +```text + +``` + +从上面的扩展步骤可以看出，用户基本在黑盒下就完成了扩展。 + +## Dubbo 扩展的应用 + +Dubbo 的扩展能力非常灵活，在自身功能的实现上无处不在。 + +![//imgs/v3/concepts/extension-use.png](/imgs/v3/concepts/extension-use.png) + +Dubbo 扩展能力使得 Dubbo 项目很方便的切分成一个一个的子模块，实现热插拔特性。用户完全可以基于自身需求，替换 Dubbo 原生实现，来满足自身业务需求。 + +## 使用场景 + +* 如果你需要自定义负载均衡策略，你可以使用 Dubbo 扩展能力。 +* 如果你需要实现自定义的注册中心，你可以使用 Dubbo 扩展能力。 +* 如果你需要实现自定义的过滤器，你可以使用 Dubbo 扩展能力。 + +Dubbo 扩展平等的对待内部实现和第三方实现。更多使用场景，参见 [SPI 扩展实现](../../references/spis/) \ No newline at end of file diff --git a/content/zh/docs3-building/java-sdk/upgrades-and-compatibility/2.x-to-3.x-compatibility-guide.md b/content/zh/docs3-building/java-sdk/upgrades-and-compatibility/2.x-to-3.x-compatibility-guide.md new file mode 100644 index 000000000000..86265a57b6f9 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/upgrades-and-compatibility/2.x-to-3.x-compatibility-guide.md @@ -0,0 +1,46 @@ +--- +type: docs +title: "2.x升级至3.x操作指南" +linkTitle: "2.x升级至3.x操作指南" +weight: 1 +description: "快速了解 Dubbo3 的升级步骤与兼容性" +--- + +**无需改动任何代码，直接升级到 Dubbo 3.0。** + +在 3.0 版本的设计与开发之初，我们就定下了兼容老版本 Dubbo 用户（2.5、2.6、2.7）的目标。因此，往 3.0 版本的升级过程将会是完全透明的，用户无需做任何业务改造，升级 3.x 后的框架行为将保持与 2.x 版本完全一致。 + +```xml + + org.apache.dubbo + dubbo + 3.0.0 + +``` + + +但也要注意，透明升级仅仅是通往 3.0 的第一步，因为 "框架行为保持一致" 也就意味着用户将无法体验到 3.0 的新特性。**如果要启用 3.0 的带来的新特性，用户则需要进行一定的改造，我们称这个过程为迁移，这是一个按需开启的过程。** + + + +因此，对老用户而言，有两条不同的迁移路径： + +* **分两步走，先以兼容模式推动业务升级到 3.0 版本（无需改造），之后在某些时机按需启用新特性（按需改造）；** +* **升级与迁移同步完成，在业务升级到 3.0 版本的同时，完成改造并启用新特性；** + + + +Dubbo 3.0 提供的新特性包括： + +* **新的地址发现模型（应用级服务发现）。** + * 查看[应用级服务发现的迁移步骤](../migration-service-discovery) + * 查看[应用级服务发现的使用方式]() + * 查看[应用级服务发现设计与实现]()。 +* **下一代基于 HTTP/2 的 Triple 协议。** + * 查看[Triple 协议迁移步骤](../migration-triple) + * 查看 [Triple 协议使用方式](../../references/protocols/tri) + * 查看 Triple 协议设计与实现。 +* **统一的路由规则。** + * 查看[统一路由规则的迁移步骤](../migration-routingrule) + * 查看[统一路由规则使用方式](../../references/routerule) + * 查看统一路由规则设计与实现 \ No newline at end of file diff --git a/content/zh/docs3-building/java-sdk/upgrades-and-compatibility/_index.md b/content/zh/docs3-building/java-sdk/upgrades-and-compatibility/_index.md new file mode 100755 index 000000000000..9598f4b44120 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/upgrades-and-compatibility/_index.md @@ -0,0 +1,8 @@ + +--- +type: docs +title: "升级和兼容性" +linkTitle: "升级和兼容性" +weight: 6 +--- + diff --git a/content/zh/docs3-building/java-sdk/upgrades-and-compatibility/migration-service-discovery.md b/content/zh/docs3-building/java-sdk/upgrades-and-compatibility/migration-service-discovery.md new file mode 100644 index 000000000000..9e009e4340bf --- /dev/null +++ b/content/zh/docs3-building/java-sdk/upgrades-and-compatibility/migration-service-discovery.md @@ -0,0 +1,160 @@ +--- +type: docs +title: "接口级服务发现迁移至应用级服务发现指南" +linkTitle: "接口级服务发现迁移至应用级服务发现指南" +weight: 3 +description: "本文档专门针对使用 2.x 版本的老用户，详细阐述了升级到 3.x 后的默认地址注册与发现行为、如何平滑的迁移到新版本的地址模型。" +--- + +**总体上来说，在地址注册与发现环节，3.x 是完全兼容 2.x 版本的，这意味着，用户可以选择将集群内任意数量的应用或机器升级到 3.x，同时在这个过程中保持与 2.x 版本的互操作性。** + + + +## 1 快速升级步骤 + +简单的修改 pom.xml 到最新版本就可以完成升级，如果要迁移到应用级地址，只需要调整开关控制 3.x 版本的默认行为。 + +1. 升级 Provider 应用到最新 3.x 版本依赖，配置双注册开关`dubbo.application.register-mode=all`（建议通过全局配置中心设置，默认已自动开启），完成应用发布。 +2. 升级 Consumer 应用到最新 3.x 版本依赖，配置双订阅开关`dubbo.application.service-discovery.migration=APPLICATION_FIRST`（建议通过全局配置中心设置，默认已自动开启），完成应用发布。 +3. 在确认 Provider 的上有 Consumer 全部完成应用级地址迁移后，Provider 切到应用级地址单注册。完成升级 + + + +以下是关于迁移流程的详细描述。 + +## 2 Provider 端升级过程详解 + +在不改变任何 Dubbo 配置的情况下，可以将一个应用或实例升级到 3.x 版本，升级后的 Dubbo 实例会默保保证与 2.x 版本的兼容性，即会正常注册 2.x 格式的地址到注册中心，因此升级后的实例仍会对整个集群仍保持可见状态。 + + + +同时新的地址发现模型（注册应用级别的地址）也将会自动注册。 + +![//imgs/v3/migration/provider-registration.png](/imgs/v3/migration/provider-registration.png) + +通过 -D 参数，可以指定 provider 启动时的注册行为 + +```text +-Ddubbo.application.register-mode=all +# 可选值 interface、instance、all，默认是 all，即接口级地址、应用级地址都注册 +``` + + + +另外，可以在配置中心修改全局默认行为，来控制所有 3.x 实例注册行为。其中，全局性开关的优先级低于 -D 参数。 + + + +为了保证平滑迁移，即升级到 3.x 的实例能同时被 2.x 与 3.x 的消费者实例发现，3.x 实例需要开启双注册；当所有上游的消费端都迁移到 3.x 的地址模型后，提供端就可以切换到 instance 模式（只注册应用级地址）。对于如何升级消费端到 3.x 请参见下一小节。 + +### 2.1 双注册带来的资源消耗 + +双注册不可避免的会带来额外的注册中心存储压力，但考虑到应用级地址发现模型的数据量在存储方面的极大优势，即使对于一些超大规模集群的用户而言，新增的数据量也并不会带来存储问题。总体来说，对于一个普通集群而言，数据增长可控制在之前数据总量的 1/100 ~ 1/1000 + +以一个中等规模的集群实例来说： 2000 实例、50个应用（500 个 Dubbo 接口，平均每个应用 10 个接口）。 + +​ 假设每个接口级 URL 地址平均大小为 5kb，每个应用级 URL 平均大小为 0.5kb + +​ 老的接口级地址量：2000 * 500 * 5kb ≈ 4.8G + +​ 新的应用级地址量：2000 * 50 * 0.5kb ≈ 48M + +​ 双注册后仅仅增加了 48M 的数据量。 + + + +## 3 Consumer 端升级过程 + +对于 2.x 的消费者实例，它们看到的自然都是 2.x 版本的提供者地址列表； + +对于 3.x 的消费者，它具备同时发现 2.x 与 3.x 提供者地址列表的能力。在默认情况下，如果集群中存在可以消费的 3.x 的地址，将自动消费 3.x 的地址，如果不存在新地址则自动消费 2.x 的地址。Dubbo3 提供了开关来控制这个行为： + +```text +dubbo.application.service-discovery.migration=APPLICATION_FIRST +# 可选值 +# FORCE_INTERFACE，只消费接口级地址，如无地址则报错，单订阅 2.x 地址 +# APPLICATION_FIRST，智能决策接口级/应用级地址，双订阅 +# FORCE_APPLICATION，只消费应用级地址，如无地址则报错，单订阅 3.x 地址 +``` + +`dubbo.application.service-discovery.migration ` 支持通过 `-D` 以及 `全局配置中心` 两种方式进行配置。 + + + +![//imgs/v3/migration/consumer-subscription.png](/imgs/v3/migration/consumer-subscription.png) + + +接下来，我们就具体看一下，如何通过双订阅模式（APPLICATION_FIRST）让升级到 3.x 的消费端迁移到应用级别的地址。在具体展开之前，先明确一条消费端的选址行为：**对于双订阅的场景，消费端虽然可同时持有 2.x 地址与 3.x 地址，但选址过程中两份地址是完全隔离的：要么用 2.x 地址，要么用 3.x 地址，不存在两份地址混合调用的情况，这个决策过程是在收到第一次地址通知后就完成了的。** + + + +下面，我们看一个`APPLICATION_FIRST`策略的具体操作过程。 + +首先，提前在全局配置中心 Nacos 配置一条配置项（所有消费端都将默认执行这个选址策略）： + +![//imgs/v3/migration/nacos-migration-item.png](/imgs/v3/migration/nacos-migration-item.png) + + + +紧接着，升级消费端到 3.x 版本并启动，这时消费端读取到`APPLICATION_FIRST`配置后，执行双订阅逻辑（订阅 2.x 接口级地址与 3.x 应用级地址） + + + +至此，升级操作就完成了，剩下的就是框架内部的执行了。在调用发生前，框架在消费端会有一个“选址过程”，注意这里的选址和之前 2.x 版本是有区别的，选址过程包含了两层筛选： + +* 先进行地址列表（ClusterInvoker）筛选（接口级地址 or 应用级地址） +* 再进行实际的 provider 地址（Invoker）筛选。 + +![//imgs/v3/migration/migration-cluster-item.png](/imgs/v3/migration/migration-cluster-invoker.png) + +ClusterInvoker 筛选的依据，可以通过 MigrationAddressComparator SPI 自行定义，目前官方提供了一个简单的地址数量比对策略，即当 `应用级地址数量 == 接口级地址数量` 满足时则进行迁移。 + +> 其实 FORCE_INTERFACE、APPLICATION_FIRST、FORCE_APPLICATION 控制的都是这里的 ClusterInvoker 类型的筛选策略 + + + +### 3.1 双订阅带来的资源消耗 + +双订阅不可避免的会增加消费端的内存消耗，但由于应用级地址发现在地址总量方面的优势，这个过程通常是可接受的，我们从两个方面进行分析： + +1. 双订阅带来的地址推送数据量增长。这点我们在 ”双注册资源消耗“ 一节中做过介绍，应用级服务发现带来的注册中心数据量增长非常有限。 +2. 双订阅带来的消费端内存增长。要注意双订阅只存在于启动瞬态，在ClusterInvoker选址决策之后其中一份地址就会被完全销毁；对单个服务来说，启动阶段双订阅带来的内存增长大概能控制在原内存量的 30% ~ 40%，随后就会下降到单订阅水平，如果切到应用级地址，能实现内存 50% 的下降。 + + + +### 3.2 消费端更细粒度的控制 + +除了全局的迁移策略之外，Dubbo 在消费端提供了更细粒度的迁移策略支持。控制单位可以是某一个消费者应用，它消费的服务A、服务B可以有各自独立的迁移策略，具体是用方式是在消费端配置迁移规则： + + +```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 +``` + +使用这种方式能做到比较精细迁移控制，但是当下及后续的改造成本会比较高，除了一些特别场景，我们不太推荐启用这种配置方式。 +([迁移指南](../../advanced/migration-invoker/)) **官方推荐使用的全局的开关式的迁移策略，让消费端实例在启动阶段自行决策使用哪份可用的地址列表。** + + + +## 4 迁移状态的收敛 + +为了同时兼容 2.x 版本，升级到 3.x 版本的应用在一段时间内要么处在双注册状态，要么处在双订阅状态。 + +解决这个问题，我们还是从 Provider 视角来看，当所有的 Provider 都切换到应用级地址注册之后，也就不存在双订阅的问题了。 + +### 4.1 不同的升级策略影响很大 + +毫无疑问越早越彻底的升级，就能尽快摆脱这个局面。设想，如果可以将组织内所有的应用都升级到 3.x 版本，则版本收敛就变的非常简单：升级过程中 Provider 始终保持双注册，当所有的应用都升级到 3.x 之后，就可以调整全局默认行为，让 Provider 都变成应用级地址单注册了，这个过程并不会给 Consumer 应用带来困扰，因为它们已经是可以识别应用级地址的 3.x 版本了。 + +如果没有办法做到应用的全量升级，甚至在相当长的时间内只能升级一部分应用，则不可避免的迁移状态要持续比较长的时间。 +在这种情况下，我们追求的只能是尽量保持已升级应用的上下游实现版本及功能收敛。推动某些 Provider 的上游消费者都升级到 Dubbo3，这样就可以解除这部分 Provider 的双注册，要做到这一点，可能需要一些辅助统计工具的支持。 + +1. 要能分析出应用间的依赖关系，比如一个 Provdier 应用被哪些消费端应用消费，这可以通过 Dubbo 提供的服务元数据上报能力来实现。 +2. 要能知道每个应用当前使用的 dubbo 版本，可以通过扫描或者主动上报手段。 diff --git a/content/zh/docs3-building/java-sdk/upgrades-and-compatibility/migration-triple.md b/content/zh/docs3-building/java-sdk/upgrades-and-compatibility/migration-triple.md new file mode 100644 index 000000000000..c9c4095ee014 --- /dev/null +++ b/content/zh/docs3-building/java-sdk/upgrades-and-compatibility/migration-triple.md @@ -0,0 +1,344 @@ +--- +type: docs +title: "Dubbo协议迁移至Triple协议指南" +linkTitle: "Dubbo协议迁移至Triple协议指南" +weight: 2 +description: "Triple协议迁移指南" +--- + +## Triple 介绍 + +`Triple` 协议的格式和原理请参阅 [RPC 通信协议](https://dubbo.apache.org/zh/docs/concepts/rpc-protocol/) + +根据 Triple 设计的目标，`Triple` 协议有以下优势: + +- 具备跨语言交互的能力，传统的多语言多 SDK 模式和 Mesh 化跨语言模式都需要一种更通用易扩展的数据传输协议。 +- 提供更完善的请求模型，除了支持传统的 Request/Response 模型（Unary 单向通信），还支持 Stream（流式通信） 和 Bidirectional（双向通信）。 +- 易扩展、穿透性高，包括但不限于 Tracing / Monitoring 等支持，也应该能被各层设备识别，网关设施等可以识别数据报文，对 Service Mesh 部署友好，降低用户理解难度。 +- 完全兼容 grpc，客户端/服务端可以与原生grpc客户端打通。 +- 可以复用现有 grpc 生态下的组件, 满足云原生场景下的跨语言、跨环境、跨平台的互通需求。 + +当前使用其他协议的 Dubbo 用户，框架提供了兼容现有序列化方式的迁移能力，在不影响线上已有业务的前提下，迁移协议的成本几乎为零。 + +需要新增对接 Grpc 服务的 Dubbo 用户，可以直接使用 Triple 协议来实现打通，不需要单独引入 grpc client 来完成，不仅能保留已有的 Dubbo 易用性，也能降低程序的复杂度和开发运维成本，不需要额外进行适配和开发即可接入现有生态。 + +对于需要网关接入的 Dubbo 用户，Triple 协议提供了更加原生的方式，让网关开发或者使用开源的 grpc 网关组件更加简单。网关可以选择不解析 payload ，在性能上也有很大提高。在使用 Dubbo 协议时，语言相关的序列化方式是网关的一个很大痛点，而传统的 HTTP 转 Dubbo 的方式对于跨语言序列化几乎是无能为力的。同时，由于 Triple 的协议元数据都存储在请求头中，网关可以轻松的实现定制需求，如路由和限流等功能。 + + +## Dubbo2 协议迁移流程 + +Dubbo2 的用户使用 dubbo 协议 + 自定义序列化，如 hessian2 完成远程调用。 + +而 Grpc 的默认仅支持 Protobuf 序列化，对于 Java 语言中的多参数以及方法重载也无法支持。 + +Dubbo3的之初就有一条目标是完美兼容 Dubbo2，所以为了 Dubbo2 能够平滑升级， Dubbo 框架侧做了很多工作来保证升级的无感，目前默认的序列化和 Dubbo2 保持一致为`hessian2`。 + +所以，如果决定要升级到 Dubbo3 的 `Triple` 协议，只需要修改配置中的协议名称为 `tri` (注意: 不是triple)即可。 + +接下来我们我们以一个使用 Dubbo2 协议的[工程](https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-triple/src/main/java/org/apache/dubbo/sample/tri/migration) 来举例，如何一步一步安全的升级。 + +1. 仅使用 `dubbo` 协议启动 `provider` 和 `consumer`，并完成调用。 +2. 使用 `dubbo` 和 `tri` 协议 启动`provider`，以 `dubbo` 协议启动 `consumer`，并完成调用。 +3. 仅使用 `tri` 协议 启动 `provider`和 `consumer`，并完成调用。 + +### 定义服务 + +1. 定义接口 +```java +public interface IWrapperGreeter { + + //... + + /** + * 这是一个普通接口，没有使用 pb 序列化 + */ + String sayHello(String request); + +} +``` + +2. 实现类如下 +```java +public class IGreeter2Impl implements IWrapperGreeter { + + @Override + public String sayHello(String request) { + return "hello," + request; + } +} +``` + +### 仅使用 dubbo 协议 + +为保证兼容性，我们先将部分 provider 升级到 `dubbo3` 版本并使用 `dubbo` 协议。 + +使用 `dubbo` 协议启动一个 [`Provider`](https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-triple/src/main/java/com/apache/dubbo/sample/basic/migration/ApiMigrationDubboProvider) 和 [`Consumer`](https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-triple/src/main/java/com/apache/dubbo/sample/basic/migration/ApiMigrationDubboConsumer) ,完成调用，输出如下: +![result](/imgs/v3/migration/tri/dubbo3-tri-migration-dubbo-dubbo-result.png) + +### 同时使用 dubbo 和 triple 协议 + +对于线上服务的升级，不可能一蹴而就同时完成 provider 和 consumer 升级, 需要按步操作，保证业务稳定。 +第二步, provider 提供双协议的方式同时支持 dubbo + tri 两种协议的客户端。 + +结构如图所示: +![strust](/imgs/v3/migration/tri/migrate-dubbo-tri-strust.png) + +> 按照推荐升级步骤，provider 已经支持了tri协议，所以 dubbo3的 consumer 可以直接使用 tri 协议 + +使用`dubbo`协议和`triple`协议启动[`Provider`](https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-triple/src/main/java/com/apache/dubbo/sample/basic/migration/ApiMigrationBothProvider)和[`Consumer`](https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-triple/src/main/java/com/apache/dubbo/sample/basic/migration/ApiMigrationBothConsumer),完成调用，输出如下: + +![result](/imgs/v3/migration/tri/dubbo3-tri-migration-both-dubbo-tri-result.png) + + +### 仅使用 triple 协议 + +当所有的 consuemr 都升级至支持 `Triple` 协议的版本后，provider 可切换至仅使用 `Triple` 协议启动 + +结构如图所示: +![strust](/imgs/v3/migration/tri/migrate-only-tri-strust.png) + +[Provider](https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-triple/src/main/java/com/apache/dubbo/sample/basic/migration/ApiMigrationTriProvider) +和 [Consumer](https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-triple/src/main/java/com/apache/dubbo/sample/basic/migration/ApiMigrationTriConsumer) 完成调用，输出如下: + +![result](/imgs/v3/migration/tri/dubbo3-tri-migration-tri-tri-result.png) + + +### 实现原理 + +通过上面介绍的升级过程，我们可以很简单的通过修改协议类型来完成升级。框架是怎么帮我们做到这些的呢？ + +通过对 `Triple` 协议的介绍，我们知道Dubbo3的 `Triple` 的数据类型是 `protobuf` 对象，那为什么非 `protobuf` 的 java 对象也可以被正常传输呢。 + +这里 Dubbo3 使用了一个巧妙的设计，首先判断参数类型是否为 `protobuf` 对象，如果不是。用一个 `protobuf` 对象将 `request` 和 `response` 进行 wrapper，这样就屏蔽了其他各种序列化带来的复杂度。在 `wrapper` 对象内部声明序列化类型，来支持序列化的扩展。 + +wrapper 的`protobuf`的 IDL如下: +```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; +} +``` + +对于请求，使用`TripleRequestWrapper`进行包装，对于响应使用`TripleResponseWrapper`进行包装。 + +> 对于请求参数，可以看到 args 被`repeated`修饰，这是因为需要支持 java 方法的多个参数。当然，序列化只能是一种。序列化的实现沿用 Dubbo2 实现的 spi + + +## 多语言用户 (正在使用 Protobuf) +> 建议新服务均使用该方式 + +对于 Dubbo3 和 Triple 来说，主推的是使用 `protobuf` 序列化，并且使用 `proto` 定义的 `IDL` 来生成相关接口定义。以 `IDL` 做为多语言中的通用接口约定，加上 `Triple` 与 `Grpc` 的天然互通性，可以轻松地实现跨语言交互，例如 Go 语言等。 + + +将编写好的 `.proto` 文件使用 `dubbo-compiler` 插件进行编译并编写实现类，完成方法调用： + +![result](/imgs/v3/migration/tri/dubbo3-tri-migration-tri-tri-result.png) + +从上面升级的例子我们可以知道，`Triple` 协议使用 `protbuf` 对象序列化后进行传输，所以对于本身就是 `protobuf` 对象的方法来说，没有任何其他逻辑。 + +使用 `protobuf` 插件编译后接口如下： +```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); +} +``` + +## 开启 Triple 新特性 —— Stream (流) +Stream 是 Dubbo3 新提供的一种调用类型，在以下场景时建议使用流的方式: + +- 接口需要发送大量数据，这些数据无法被放在一个 RPC 的请求或响应中，需要分批发送，但应用层如果按照传统的多次 RPC 方式无法解决顺序和性能的问题，如果需要保证有序，则只能串行发送 +- 流式场景，数据需要按照发送顺序处理, 数据本身是没有确定边界的 +- 推送类场景，多个消息在同一个调用的上下文中被发送和处理 + +Stream 分为以下三种: +- SERVER_STREAM(服务端流) +![SERVER_STREAM](/imgs/v3/migration/tri/migrate-server-stream.png) +- CLIENT_STREAM(客户端流) +![CLIENT_STREAM](/imgs/v3/migration/tri/migrate-client-stream.png) +- BIDIRECTIONAL_STREAM(双向流) +![BIDIRECTIONAL_STREAM](/imgs/v3/migration/tri/migrate-bi-stream.png) + +> 由于 `java` 语言的限制，BIDIRECTIONAL_STREAM 和 CLIENT_STREAM 的实现是一样的。 + +在 Dubbo3 中，流式接口以 `SteamObserver` 声明和使用，用户可以通过使用和实现这个接口来发送和处理流的数据、异常和结束。 + +> 对于 Dubbo2 用户来说，可能会对StreamObserver感到陌生，这是Dubbo3定义的一种流类型，Dubbo2 中并不存在 Stream 的类型，所以对于迁移场景没有任何影响。 + +流的语义保证 +- 提供消息边界，可以方便地对消息单独处理 +- 严格有序，发送端的顺序和接收端顺序一致 +- 全双工，发送不需要等待 +- 支持取消和超时 + +### 非 PB 序列化的流 +1. api +```java +public interface IWrapperGreeter { + + StreamObserver sayHelloStream(StreamObserver response); + + void sayHelloServerStream(String request, StreamObserver response); +} +``` + +> Stream 方法的方法入参和返回值是严格约定的，为防止写错而导致问题，Dubbo3 框架侧做了对参数的检查, 如果出错则会抛出异常。 +> 对于 `双向流(BIDIRECTIONAL_STREAM)`, 需要注意参数中的 `StreamObserver` 是响应流，返回参数中的 `StreamObserver` 为请求流。 + +2. 实现类 +```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. 调用方式 +```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(); +``` + +## 使用 Protobuf 序列化的流 + +对于 `Protobuf` 序列化方式，推荐编写 `IDL` 使用 `compiler` 插件进行编译生成。生成的代码大致如下: +```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); +} +``` + +### 流的实现原理 + +`Triple`协议的流模式是怎么支持的呢？ + +- 从协议层来说，`Triple` 是建立在 `HTTP2` 基础上的，所以直接拥有所有 `HTTP2` 的能力，故拥有了分 `stream` 和全双工的能力。 + +- 框架层来说，`StreamObserver` 作为流的接口提供给用户，用于入参和出参提供流式处理。框架在收发 stream data 时进行相应的接口调用, 从而保证流的生命周期完整。 + +## Triple 与应用级注册发现 + +关于 Triple 协议的应用级服务注册和发现和其他语言是一致的，可以通过下列内容了解更多。 + +- [服务发现](https://dubbo.apache.org/zh/docs/concepts/service-discovery/) +- [应用级地址发现迁移指南](https://dubbo.apache.org/zh/docs/migration/migration-service-discovery/) + +## 与 GRPC 互通 + +通过对于协议的介绍，我们知道 `Triple` 协议是基于 `HTTP2` 并兼容 `GRPC`。为了保证和验证与`GRPC`互通能力，Dubbo3 也编写了各种从场景下的测试。详细的可以通过[这里](https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-triple/README.MD) 了解更多。 + +## 未来: Everything on Stub + +用过 `Grpc` 的同学应该对 `Stub` 都不陌生。 +Grpc 使用 `compiler` 将编写的 `proto` 文件编译为相关的 protobuf 对象和相关 rpc 接口。默认的会同时生成几种不同的 `stub` + +- blockingStub +- futureStub +- reactorStub +- ... + +`stub` 用一种统一的使用方式帮我们屏蔽了不同调用方式的细节。不过目前 `Dubbo3` 暂时只支持传统定义接口并进行调用的使用方式。 + +在不久的未来，`Triple` 也将实现各种常用的 `Stub`，让用户写一份`proto`文件，通过 `comipler` 可以在任意场景方便的使用，请拭目以待。 \ No newline at end of file diff --git a/content/zh/users/_index.md b/content/zh/users/_index.md index 5a9cfe6dfc93..ee2f7b5005e3 100644 --- a/content/zh/users/_index.md +++ b/content/zh/users/_index.md @@ -1,30 +1,62 @@ + --- -title: 用户 +title: "用户案例" +weight: 3 +description: Dubbo 用户案例分享，涵盖最新 3.0 版本 menu: main: - weight: 70 + weight: 20 --- - -{{% blocks/lead color="info" %}} -谁在使用 Dubbo - -请在 [Wanted: who's using dubbo](https://github.com/apache/dubbo/issues/1012) 上提供信息来帮助 Dubbo 做的更好。 -{{% /blocks/lead %}} - -{{< blocks/section color="white">}} -{{< figure src="/imgs/users_alibaba.png" height="80" width="140">}} -{{< figure src="/imgs/users_icbc.png" height="80" width="140">}} -{{< figure src="/imgs/users_telecom.png" height="80" width="140">}} -{{< figure src="/imgs/users_yinlian.png" height="80" width="140">}} -{{< figure src="/imgs/users_chinalife.png" height="80" width="140">}} -{{< figure src="/imgs/users_wanglian.png" height="80" width="140">}} -{{< figure src="/imgs/users_zhengcaiyun.png" height="80" width="140">}} -{{< figure src="/imgs/users_kaola.png" height="80" width="140">}} -{{< figure src="/imgs/users_didi.png" height="80" width="140">}} -{{< figure src="/imgs/users_qunar.png" height="80" width="140">}} -{{< figure src="/imgs/users_handu.png" height="80" width="140">}} -{{< figure src="/imgs/users_dangdang.png" height="80" width="140">}} -{{< figure src="/imgs/users_weidian.png" height="80" width="140">}} -{{< figure src="/imgs/users_kingdee.png" height="80" width="140">}} -{{< /blocks/section >}} +{{< blocks/cover height="sm" color="primary" >}} +{{< page/header >}} +{{< /blocks/cover >}} + +
+ +
+{{< page/toc collapsed=true placement="inline" >}} +
+ +
+
+ +Apache Dubbo 诞生于阿里巴巴微服务实践之中，在开源之后深受企业用户喜爱并迅速成为国内开源服务框架选型的事实标准产品，用户范围涵盖互联网、金融保险、科技公司、制造业、零售物流等领域的几乎所有头部用户。 + + +{{< cardpane >}} + {{< card header="阿里巴巴的 Dubbo3 落地实践" >}} +阿里巴巴电商核心系统已成功升级到 Dubbo3 版本，用于取代上一代 HSF2 服务框架，2022 年起双 11 核心链路都将跑在 Dubbo3 之上。
+了解更多 + {{< /card >}} + + {{< card header="工商银行 Dubbo3 应用级服务发现实践" >}} + 工商银行为什么要选型 Dubbo3 应用级服务发现架构那？核心原因是 2.x 版本架构在超大规模集群实战上的性能和容量瓶颈。
+ 了解更多 + {{< /card >}} + + {{< card header="小米的 Dubbo3 实践" >}} + 小米对 Dubbo 多语言版本 Java、Golang 都有着广泛的使用。
+ 了解更多 + {{< /card >}} +{{< /cardpane >}} + + {{< cardpane >}} + {{< card header="饿了么全站成功升级 Dubbo3" >}} + 饿了么当前有超过 2000 应用，10 万实例跑在 Dubbo3 之上，通过应用级服务发现与 Triple 协议解决了跨单元的互联互通问题。
+ 了解更多 + {{< /card >}} + {{< card header="平安健康" >}} + 平安健康目前正从 2.x 版本迁移到 Dubbo3
+ 了解更多 + {{< /card >}} + {{< card header="烽火递" >}} + 烽火递的所有新业务都使用 Dubbo3 构建，由于没有 dubbo2 的迁移成本，业务得以很快的稳定上线。
+ 了解更多 + {{< /card >}} + {{< /cardpane >}} + + +
+
+
\ No newline at end of file diff --git a/content/zh/users/alibaba.md b/content/zh/users/alibaba.md new file mode 100644 index 000000000000..983179735c75 --- /dev/null +++ b/content/zh/users/alibaba.md @@ -0,0 +1,7 @@ +--- +type: docs +title: "阿里巴巴" +linkTitle: "阿里巴巴" +weight: 1 +description: Dubbo 用户案例分享，涵盖最新 3.0 版本 +--- \ No newline at end of file diff --git a/content/zh/users/icbc.md b/content/zh/users/icbc.md new file mode 100644 index 000000000000..745974d6c4a7 --- /dev/null +++ b/content/zh/users/icbc.md @@ -0,0 +1,7 @@ +--- +type: docs +title: "阿里巴巴" +linkTitle: "阿里巴巴" +weight: 2 +description: Dubbo 用户案例分享，涵盖最新 3.0 版本 +--- \ No newline at end of file diff --git a/content/zh/users/xiaomi.md b/content/zh/users/xiaomi.md new file mode 100644 index 000000000000..4b67996f0d56 --- /dev/null +++ b/content/zh/users/xiaomi.md @@ -0,0 +1,7 @@ +--- +type: docs +title: "小米" +linkTitle: "小米" +weight: 3 +description: Dubbo 用户案例分享，涵盖最新 3.0 版本 +--- \ No newline at end of file diff --git a/layouts/partials/docs/prog-lang-home.html b/layouts/partials/docs/prog-lang-home.html new file mode 100644 index 000000000000..211934832c15 --- /dev/null +++ b/layouts/partials/docs/prog-lang-home.html @@ -0,0 +1,35 @@ +{{ $Lang := .Params.title | default .Params.language }} + +
+
+
+
+

+ Quick start +

+

+ Run your first {{ replace $Lang " " "-" }} gRPC app in minutes! +

+
+
+
+ + {{ if .GetPage "basics" }} +
+
+
+

+ Basics tutorial +

+

+ Learn about {{ replace $Lang " " "-" }} gRPC basics. +

+
+
+
+ {{ end }} +
+ {{ with .Content }} +
+ {{ . }} + {{ end }} \ No newline at end of file diff --git a/layouts/partials/docs/toc-inline.html b/layouts/partials/docs/toc-inline.html new file mode 100644 index 000000000000..0e2bd3833b4c --- /dev/null +++ b/layouts/partials/docs/toc-inline.html @@ -0,0 +1,14 @@ +{{ if not .Params.notoc }} + {{ with .TableOfContents }} + {{ if ge (len .) 200 }} + +
+ {{ . }} +
+ + {{ end }} + {{ end }} +{{ end }} diff --git a/layouts/shortcodes/docs/content_box.md b/layouts/shortcodes/docs/content_box.md new file mode 100644 index 000000000000..85fd54a2f411 --- /dev/null +++ b/layouts/shortcodes/docs/content_box.md @@ -0,0 +1,27 @@ +{{ $lang := lower ($.Page.Params.language | default $.Page.Params.title) -}} +{{ $src_repo_url := $.Page.Params.src_repo | default (printf "https://github.com/apache/dubbo-%s" $lang) -}} +{{ $src_repo_link := printf "[dubbo-%s repo](%s)" $lang $src_repo_url -}} + +{{ with .Page.Params.content -}} +
+{{ range $list_entry := . }} +{{ range $heading, $items := $list_entry }} +{{ $hd := printf "### %s" (humanize $heading) -}} + +{{ range $items }} +
+
+
+ {{ $item := replace . "$src_repo_url" $src_repo_url }} + {{ $item = replace $item "$src_repo_link" $src_repo_link }} +

+ {{ $item | $.Page.RenderString }} +

+
+
+
+{{ end }} +{{ end }} +{{ end }} +
+{{ end -}} diff --git a/layouts/shortcodes/docs/prog-lang-home-content.md b/layouts/shortcodes/docs/prog-lang-home-content.md new file mode 100644 index 000000000000..77c56456a647 --- /dev/null +++ b/layouts/shortcodes/docs/prog-lang-home-content.md @@ -0,0 +1,25 @@ +{{ $lang := lower ($.Page.Params.language | default $.Page.Params.title) -}} +{{ $src_repo_url := $.Page.Params.src_repo | default (printf "https://github.com/apache/dubbo-%s" $lang) -}} +{{ $src_repo_link := printf "[dubbo-%s repo](%s)" $lang $src_repo_url -}} + +{{ with .Page.Params.content -}} +
+{{ range $list_entry := . }} +{{ range $heading, $items := $list_entry }} +{{ $hd := printf "### %s" (humanize $heading) -}} +
+ +{{ $hd }} + +
    +{{ range $items }} + {{ $item := replace . "$src_repo_url" $src_repo_url }} + {{ $item = replace $item "$src_repo_link" $src_repo_link }} +
  • {{ $item | $.Page.RenderString }}
    • +{{ end }} +
+
+{{ end }} +{{ end }} +
+{{ end -}} diff --git a/layouts/shortcodes/page/header.html b/layouts/shortcodes/page/header.html new file mode 100644 index 000000000000..2d579e836b08 --- /dev/null +++ b/layouts/shortcodes/page/header.html @@ -0,0 +1,13 @@ +{{ $title := $.Page.Params.title -}} +{{ $desc := $.Page.Params.description | markdownify -}} +
+

+ {{- $title -}} +

+ + {{- with $desc -}} +

+ {{- . -}} +

+ {{ end -}} +
\ No newline at end of file diff --git a/layouts/shortcodes/page/page-meta-links.html b/layouts/shortcodes/page/page-meta-links.html new file mode 100644 index 000000000000..5a1d4d3a22e2 --- /dev/null +++ b/layouts/shortcodes/page/page-meta-links.html @@ -0,0 +1,3 @@ +
+ {{ partial "page-meta-links" .Page }} +
\ No newline at end of file diff --git a/layouts/shortcodes/page/toc.html b/layouts/shortcodes/page/toc.html new file mode 100644 index 000000000000..5fe1433eefa5 --- /dev/null +++ b/layouts/shortcodes/page/toc.html @@ -0,0 +1,30 @@ +{{ $collapsed := .Get "collapsed" | default false }} +{{ $placement := .Get "placement" | default "sidebar" }} + +{{ with .Page.TableOfContents }} + {{ if (eq $placement "sidebar") }} +
+
+ {{ else if (eq $placement "inline") }} +
+
+ {{ end }} + {{ if $collapsed }} + +
+ {{ . }} +
+ + {{ else }} +
Contents
+ {{ partial "page-meta-links.html" $.Page }} +
+ {{ . }} +
+ {{ end }} +
+
+{{ end }} \ No newline at end of file diff --git a/static/imgs/v3/concepts/architecture-1.png b/static/imgs/v3/concepts/architecture-1.png new file mode 100644 index 000000000000..972ed5437451 Binary files /dev/null and b/static/imgs/v3/concepts/architecture-1.png differ diff --git a/static/imgs/v3/concepts/capacity.png b/static/imgs/v3/concepts/capacity.png new file mode 100644 index 000000000000..8e081476acd8 Binary files /dev/null and b/static/imgs/v3/concepts/capacity.png differ diff --git a/static/imgs/v3/concepts/dubbo-hsf.png b/static/imgs/v3/concepts/dubbo-hsf.png new file mode 100644 index 000000000000..aee67ab4e1ca Binary files /dev/null and b/static/imgs/v3/concepts/dubbo-hsf.png differ diff --git a/static/imgs/v3/concepts/dubbo3-goals.png b/static/imgs/v3/concepts/dubbo3-goals.png new file mode 100644 index 000000000000..cfbf3cf1753c Binary files /dev/null and b/static/imgs/v3/concepts/dubbo3-goals.png differ diff --git a/static/imgs/v3/concepts/rpc.png b/static/imgs/v3/concepts/rpc.png new file mode 100644 index 000000000000..702b126e25ba Binary files /dev/null and b/static/imgs/v3/concepts/rpc.png differ diff --git a/static/imgs/v3/mesh/dubbo-proxyless.png b/static/imgs/v3/mesh/dubbo-proxyless.png new file mode 100644 index 000000000000..b33be1cba2b4 Binary files /dev/null and b/static/imgs/v3/mesh/dubbo-proxyless.png differ diff --git a/static/imgs/v3/mesh/dubbo-sidecar.png b/static/imgs/v3/mesh/dubbo-sidecar.png new file mode 100644 index 000000000000..8dc7b83cd228 Binary files /dev/null and b/static/imgs/v3/mesh/dubbo-sidecar.png differ diff --git a/static/imgs/v3/mesh/istio.jpg b/static/imgs/v3/mesh/istio.jpg new file mode 100644 index 000000000000..fc2cf4eaaf58 Binary files /dev/null and b/static/imgs/v3/mesh/istio.jpg differ diff --git a/static/imgs/v3/mesh/mix-meshj.png b/static/imgs/v3/mesh/mix-meshj.png new file mode 100644 index 000000000000..be0f5ab75c87 Binary files /dev/null and b/static/imgs/v3/mesh/mix-meshj.png differ