Dubbo 3 是 Dubbo 新的里程碑，Dubbo 的生態元件（包括 Dubbo Java SDK，Dubbo Golang SDK 等）都在向 Dubbo 3 的目標靠攏，在使用者實踐方面，包括阿里巴巴、淘寶、天貓、餓了麼、工商銀行、平安健康等企業都已成功升級 Dubbo 3 版本，隨著更多的企業和使用者關注或升級 Dubbo 3，整個社群對 Dubbo 3 的文件的需求開始變得更加迫切，以幫助使用者正確使用 Dubbo 3 功能或知道如何排查遇到的問題。

為了提升 Dubbo 3 文件的質量，Dubbo 社群在 6 月份中旬的時候發出了《Dubbo 3 官方文件貢獻者召集令》。這兩個月以來，Dubbo 官網收到了近 250 個 Commit，正是因為有了社群各位夥伴的踴躍貢獻，Dubbo 官方文件的結構和內容有了許許多多的改變。

![1.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/9626029860334610ba856c986de5e7bd~tplv-k3u1fbpfcp-zoom-1.image "1.png")

apache/dubbo-website 提交活躍度

## 本次體驗最佳化聚焦的關注點

### 1. 文件全面對齊最新 Dubbo 3 版本

Dubbo 3 作為 Dubbo 的一個里程碑版本，做了眾多的最佳化和架構調整。在本次文件最佳化中，我們重點關注了這部分的文件問題，補充完善了 Dubbo 架構調整的內容、全新的應用級服務發現模型和 Triple 協議等的說明使用文件。另外我們也對一些快速開始用例和已有功能的文件做了一定的最佳化調整，來對齊 Dubbo 3 版本。

### 2. 文件架構最佳化，抽離出面向新手的入門文件

本次體驗最佳化的過程中，我們把原有的文件拆分為入門文件和 SDK 文件兩個部分。面向 Dubbo 的入門使用者，在入門文件模組可以快速瞭解什麼是 Dubbo、Dubbo 3 的新特性、快速開始使用 Dubbo、基於場景示例的實踐等。和入門文件模組與之對應的是 SDK 手冊，SDK 手冊中存放了各個 SDK、工具的文件，包括了 Java SDK、Golang SDK、Dubbo Go Pixiu 等，面向想要深入瞭解各個 SDK 的使用者。

除了總體架構的分級，我們也對 Java SDK 中一些子目錄的結構進行了最佳化，如高階特性和用法目錄下按照不同的場景分離出流量治理、診斷與調優、提升安全性等子目錄。

![2.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/16cd28b6ad7c439ba1ad6c3b07eb2ec7~tplv-k3u1fbpfcp-zoom-1.image "2.png")

![3.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/80a9b28fd4e3469a818f741be2d3e746~tplv-k3u1fbpfcp-zoom-1.image "3.png")

![4.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/2ef25bef59c44eff902d78543ed7dc6c~tplv-k3u1fbpfcp-zoom-1.image "4.png")

![5.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/e09502e1687341c5aa34e969c2a1cb99~tplv-k3u1fbpfcp-zoom-1.image "5.png")

入門文件部分

![6.jpeg](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/a74d4370e996418eaea8518590af7dc2~tplv-k3u1fbpfcp-zoom-1.image "6.jpeg")

![7.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/3992887330e549b496ec235bc2bcdc7e~tplv-k3u1fbpfcp-zoom-1.image "7.png")

![8.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/9811c35c8447477695d5b7dbb87431c5~tplv-k3u1fbpfcp-zoom-1.image "8.png")

![9.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/daa7ca5ac51540ec9eb636fb714e69a7~tplv-k3u1fbpfcp-zoom-1.image "9.png")

![10.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/f882a6ea96434078a944d35b194528b4~tplv-k3u1fbpfcp-zoom-1.image "10.png")

SDK 手冊部分

### 3. 搜尋

Dubbo 作為一個 RPC 底層框架，提供了眾多的功能，為了講清楚功能怎麼用、配置怎麼配、原理是怎麼樣的等問題，設計了眾多的文件。當前 Dubbo 的總文件數達到了一千多篇，縱使文件架構再怎麼最佳化，大部分使用者也無法很快定位到具體的一篇文件。為了解決這個問題，我們引入了 Algolia 搜尋工具，最佳化了對應的文件抓取邏輯，期望使用者可以透過關鍵字搜尋快速找到所需要的文件。

![11.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/fa69f3a7dfb945e9948821f3c1f0e5db~tplv-k3u1fbpfcp-zoom-1.image "11.png")

Algolia 搜尋結果示例

#### 4. 多語言生態

在 Dubbo 的發展規劃中，多語言生態是一個重要的組成部分，各個語言子社群都是 Dubbo 不可分離的一個部分。在本次文件體驗升級的過程中我們也將各個子社群分散的文件進行了整合，目前大部分的文件都已經遷移到了 SDK 手冊中，入門文件的部分示例也和 Golang SDK 聯合做了適配。

### 5. 異常連結修正

Dubbo 官網在歷史上經歷過好幾個版本的大的迭代，很多網頁的跳轉連結存在著失效的問題，給瀏覽者帶來了很不好的體驗。在 dubbo-website 的 issue 列表中也有很多關於外鏈失效的反饋。為了從根本上解決這個問題，我們在 GitHub Actions 工作流中引入了基於 htmltest 的連結校驗邏輯，在每次提交的時候都會檢查頁面上的連結是否都還是有效，如果失效的話會有對應的報錯報告，以此來確保跳轉都是有效的。在第一次整體調整的過程中，我們一共修復了 600+ 個連結失效問題。

## 規劃中的內容

### 1. Dubbo 3 原始碼導讀

Dubbo 3 作為 Dubbo 的里程碑版本做了很多的技術架構調整，為了讓社群的小夥伴更容易理解 Dubbo 的原理設計，Dubbo 社群在規劃完成新版的程式碼導讀系列，預計在近期會和大家見面。

### 2. 使用  FAQ 文件

Dubbo 作為一個 RPC 框架，和開發態、運維態的工作都極為緊密，在使用 Dubbo 的過程中難免會遇到非預期的報錯，但是苦於對原始碼不夠熟悉無法進行高效的排查。Dubbo 3 將全新升級 FAQ 文件機制，在報錯的時候自動連結到官方文件中對應的 FAQ 文件，提高異常的排查效率，提升總體使用體驗。

![12.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/40b126ac57664086954d65273ec3aa09~tplv-k3u1fbpfcp-zoom-1.image "12.png")

## 寫在最後

本次文件的最佳化只是 Dubbo 在易用性體驗最佳化上的一個開端，由於 Dubbo 官方文件的數量眾多，難免存在疏漏的地方，我們歡迎大家持續對包括 Dubbo 官方文件在內的 Dubbo 易用性體驗提出問題建議（直接提交 issue 就可以啦）。在未來我們也將持續投入在 Dubbo 易用性最佳化的部分上，讓 Dubbo 能被更多的人更容易地用上、用好。

點選[此處](https://dubbo.apache.org/zh/index.html)，直達 Dubbo 官網。

Dubbo 3 易用性升級之 Dubbo 官網大改版

相關文章