dubbo-go v3 版本 go module 踩坑记
作者 | 董劍輝、盛傲飛
來源 | 阿里巴巴云原生公眾號
?
問題背景
?
該問題源于我們想對 dubbo-go 的 module path 做一次變更，使用 dubbo.apache.org/dubbo-go/v3 替換之前的 github.com/apache/dubbo-go。
?
首先，我們做了路徑映射，在 dubbo.apache.org 下放置了一個 dubbogo/v3 文件，內容如下：
?
?
其次，我們修改了 go.mod 的 module 和對應的所有 import，并修改了所有子模塊引用 dubbo-go 使用的 module 路徑。
?
問題分析
?
在做完上述的修改后，我們提 PR 時，發現 CI 失敗，經過進一步的日志排查，我們確定是 CI 在跑集成測試時發生了錯誤，具體的錯誤提示信息如下：
?
這一段的執行邏輯是希望利用 docker 對 dubbo-go 中的集成測試內容構建鏡像，并啟動容器進行測試，該鏡像打包所用的 Dockerfile 路徑在 github.com/apache/dubbo-go/test/integrate/dubbo/go-server 目錄下，對照錯誤日志的 STEP 標識，我們可以定位到具體錯誤發生下面的兩個步驟：
?
?
在 STEP 9 中，我們使用 go mod edit -replace 替換了 dubbogo 的依賴路徑，將其替換為發起 PR 請求的倉庫地址和 commit id。在此基礎上，當鏡像構建跑到 STEP11 ，嘗試使用 go mod tidy 拉包時發生了錯誤。
?
回過頭查看錯誤日志，我們可以發現：
?
由于我們只指定了 commit id，因此在 go mod 實際運行過程中，它會為我們生成一個假定版本號（關于假定版本號的更多說明可以查看本文最后的問題拓展），這個假定版本號抓取遠程倉庫的最新有效 tag 為 v1.4.1【注：此處遠程倉庫為 github.com/Mulavar/dubbo-go，這是我自己的 dubbo-go 分支，該分支拉取 fork 的時間比較早，其最后 tag 是 v1.4.1】，并自增為 v1.4.2，主版本是 v1。但在先前，我們的 dubbogo module path 是聲明為 dubbo.apache.org/dubbogo/v3，主版本是 v3，這導致了 go mod edit -replace 前后的依賴主版本分別是 v3 和 v1 ，出現了不一致，實際拉取 dubbogo 依賴的時候出錯。
?
問題解決
?
在問題分析一節中我們定位到這個問題在鏡像構建的 STEP 9，即：
?
?
這一步，我們使用 go mod edit -replace 時將一個 v3 版本的 go module 替換成了一個 v1 版本的 module，導致主版本不一致發生錯誤，因此我們只需在替換依賴路徑時指定替換后的 module 主版本也為 v3 即可，我們在 go mod edit -replace 后的模塊依賴路徑后也加上 v3 后綴如下所示。
?
修改前：
?
go mod edit -replace=dubbo.apache.org/dubbo-go/v3=github.com/{PR_ORIGIN_REPO}@${PR_ORIGIN_COMMITID}
?
? 修改后：
?
go mod edit -replace=dubbo.apache.org/dubbo-go/v3=github.com/${PR_ORIGIN_REPO}/v3@${PR_ORIGIN_COMMITID}
?
修復該問題后我們提交代碼查看 CI，在 STEP 8 打印的日志信息中，可以看到替換后的 dubbogo 路徑多了 v3，并且在拉包的時候跟的版本號（v3.0.0-20210509140455-2574eab5ad0b）主版本同樣是 v3，成功拉取了依賴。
?
問題拓展
?
1. Semantic Import Versioning
?
在我們使用 Go modules 去構建項目的依賴關系時，對 go 項目的依賴都需要聲明我們所使用的版本號，考慮到每次發布新版本時，兼容一直是開發者最為重視和頭痛的問題，因此 go 通過**語義導入版本控制（Semantic Import Versioning）**來制定版本號的標準，來確保每個開發者能夠根據自己的項目需求指定使用的依賴版本。根據 go 的語義導入版本控制準則，版本號由三部分構成：
?
注：上圖及以上部分內容參考自《Go Modules 詳解》一文。
其中 Major version 表示這是一個新的大版本，甚至這個新版本可能和舊版本是不兼容的。
?
而 Minor version 則表示這是一個大版本中的迭代，主要用于新增 feature 時遞增。
?
Patch version 則是粒度最細的版本更新，表示一些 bug 的修復。
?
而指定主版本則有兩種方式，一種是如上的直接聲明，另一種則是在項目路徑的最后加上版本后綴，如 dubbogo 3.0 版本聲明的 module 則是 dubbo.apache.org/dubbo-go/v3，其中 v3 就是一個主版本的聲明。
?
2. pseudo-version
?
Go 在使用依賴時推崇我們指定明確的版本號，比如 dubbogo 的 go.mod 中聲明的對 cloud.google.com/go 的依賴：
?
但考慮到在某些場景下，我們想要使用模塊依賴的某個未發版的版本（該模塊只有一個已知的 commit id），如 dubbogo 聲明的 github.com/Microsoft/go-winio 依賴，就可以使用一個假定版本號（pseudo-version）去替代真實的版本號。假定版本號的格式為：
?
?
可以看到 pseudo-version 被短斜杠分為三部分，其中第一部分 X.Y.Z 與 4.1 節提到的一致，分別是 major version、minor version、patch version，而第二部分是一個格式為 yyyymmddhhmmss 的時間戳，第三部分是一個 12 位的 commit hash，可以手動指定，如果沒有，則由 go 自動生成。
?
關于 pseudo-version，go 的生成規則如下：
?
- 查詢該項目對應主版本（若項目依賴路徑沒有顯式的 v2/v3 后綴，則默認為 v1 版本）的最新 tag。
- 有 tag 則使用最新 tag 遞增 patch version。
- 無 tag ，根據項目路徑帶的后綴版本號自動生成（如 v3 則自動生成一個 3.0.0 開頭的 pseudo-version）。
遵循這個規則，回頭看前文的問題分析和問題解決，我們就可以明白為什么在一開始 dubbo-go 的 pseudo-version 是 v1.4.2，這正是因為 go 認為 replace 后的 dubbogo 依賴主版本是 v1，去查找了該主版本下的最新 tag，并遞增了 patch version，從而導致前后主版本不一致，當我們對版本路徑加上 v3 后，go 查找不到對應主版本下的 tag，為我們自動生成了 v3.0.0，從而通過了 CI 。
?
3. Go 模塊嵌套
?
和 Java 不同，go 其實是沒有子模塊概念的。即使有些時候，我們會看到有個 repo 里有多個 Go modules，比如項目的根目錄有一個 go.mod ，里面有些子目錄里又有 go.mod 。
?
這在 Go modules 被稱為嵌套模塊，而非父子模塊，即兩個模塊沒有任何關系，是相互獨立的。
?
那什么時候才需要單 repo 多模塊呢？一般來說，碰到以下兩種情況我們才會考慮使用單 repo 多模塊的開發形式。
?
兩種情況其實本質都是兩個模塊之間沒什么強的版本綁定關系，但是由于一些其他原因需要放在一個 rpeo 下，因此形成了單 repo 多模塊的局面。
?
4. dubbogo 靜態映射文件內容解析
?
dubbo-go 使用了靜態文件映射的方式實現了模塊重定向，靜態文件的內容如下：
?
其中的核心部分是 meta 標簽 go-import 和 go-source。
?
?
1）go-import
?
go-import 的作用，是告訴 go get 去哪兒可以找到源碼，content 分為三部分：
?
- dubbo.apache.org/dubbo-go/v3：這個項目的 module 聲明。
- git：使用的版本控制工具。
- <https://github.com/apache/dubbo-go>：告訴 go get 這個項目應該去哪兒找源代碼。
2）go-source
?
go-source 的作用，則是給項目生成具體的 go doc（現為 pkg.go.dev ) 文檔，一共有 4 部分，前兩部分和 go-import 一樣，是該項目的 module 聲明和版本控制工具，后兩部分則分別起如下作用：
?
- <https://github.com/apache/dubbo-go/tree/3.0{/dir}>：聲明該項目的源代碼所在位置。
- <https://github.com/apache/dubbo-go/blob/3.0{/dir}/{file}#L{line}>：映射文檔和代碼，幫助我們在點擊文檔的目錄樹時，可以跳轉到對應的具體內容。
比如在 https://pkg.go.dev/dubbo.apache.org/dubbo-go/v3 上，我們點擊其中一個文件：
就會跳轉到對應文件對應的文檔。
?
歡迎對 apache/dubbo-go 項目有興趣的同學搜索釘釘群號 31363295，加入釘釘交流群！
?
參考資料
- 《The Go Blog — Using Go Modules》：https://blog.golang.org/using-go-modules
- 《Go Modules Reference》：https://golang.org/ref/mod
- 《Go Module 如何發布 v2 及以上版本》：https://blog.cyeam.com/go/2019/03/12/go-version
- 《Go Modules 詳解》：https://www.sulinehk.com/post/go-modules-details/
作者簡介
?
董劍輝(github @Mulavar)，剛從 浙江大學 VLIS 實驗室畢業，目前在任 猿輔導 服務端開發工程師。
?
盛傲飛(github @aofei)，goproxy.cn 項目作者，曾給 go 源碼【如 mod 工具】提交過很多 PR。
總結
以上是生活随笔為你收集整理的dubbo-go v3 版本 go module 踩坑记的全部內容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： 暑期 2021 | Serverless
- 下一篇： 阿里云携手 VMware 共建云原生 I