二方庫規(guī)約
1. 【強制】定義 GAV 遵從以下規(guī)則:
1 ) G GroupID 格式: com .{公司/ BU }.業(yè)務(wù)線. [ 子業(yè)務(wù)線 ] ,最多 4 級。
說明:{公司/ BU } 例如: alibaba / taobao / tmall / aliexpress 等 BU 一級 ; 子業(yè)務(wù)線可選。
正例: com . taobao . jstorm 或 com.alibaba.dubbo.register
2 ) A ArtifactID 格式:產(chǎn)品線名-模塊名。語義不重復(fù)不遺漏,先到倉庫中心去查證一下。
正例: dubbo - client / fastjson - api / jstorm - tool
3 ) V Version :詳細規(guī)定參考下方。
2. 【強制】二方庫版本號命名方式:主版本號.次版本號.修訂號
1 ) 主版本號 主版本號:當(dāng)做了不兼容的 API 修改,或者增加了能改變產(chǎn)品方向的新功能。
2 ) 次版本號 次版本號:當(dāng)做了向下兼容的功能性新增 ( 新增類、接口等 ) 。
3 ) 修訂號 修訂號:修復(fù) bug ,沒有修改方法簽名的功能加強,保持 API 兼容性。
說明:起始版本號必須為: 1.0.0 ,而不是 0.0.1
3. 【強制】線上應(yīng)用不要依賴 SNAPSHOT 版本 ( 安全包除外 ); 正式發(fā)布的類庫必須使用 RELEASE版本號升級+1 的方式,且版本號不允許覆蓋升級,必須去中央倉庫進行查證。
說明:不依賴 SNAPSHOT 版本是保證應(yīng)用發(fā)布的冪等性。另外,也可以加快編譯時的打包構(gòu)建。
4. 【強制】二方庫的新增或升級,保持除功能點之外的其它 jar 包仲裁結(jié)果不變。如果有改變,必須明確評估和驗證,建議進行 dependency : resolve 前后信息比對,如果仲裁結(jié)果完全不一致,那么通過 dependency : tree 命令,找出差異點,進行< excludes >排除 jar 包。
5. 【強制】二方庫里可以定義枚舉類型,參數(shù)可以使用枚舉類型,但是接口返回值不允許使用枚舉類型或者包含枚舉類型的 POJO 對象。
6. 【強制】依賴于一個二方庫群時,必須定義一個統(tǒng)一版本變量,避免版本號不一致。
說明:依賴 springframework - core ,- context ,- beans ,它們都是同一個版本,可以定義一個變量來保存版本:${ spring . version },定義依賴的時候,引用該版本。
7. 【強制】禁止在子項目的 pom 依賴中出現(xiàn)相同的 GroupId ,相同的 ArtifactId ,但是不同的Version 。
說明:在本地調(diào)試時會使用各子項目指定的版本號,但是合并成一個 war ,只能有一個版本號出現(xiàn)在最后的 lib 目錄中。曾經(jīng)出現(xiàn)過線下調(diào)試是正確的,發(fā)布到線上出故障的先例。
8. 【推薦】所有 pom 文件中的依賴聲明放在< dependencies >語句塊中,所有版本仲裁放在< dependencyManagement >語句塊中。
說明:< dependencyManagement >里只是聲明版本,并不實現(xiàn)引入,因此子項目需要顯式的聲明依賴, version 和 scope 都讀取自父 pom 。而< dependencies >所有聲明在主 pom 的< dependencies >里的依賴都會自動引入,并默認被所有的子項目繼承。
9. 【推薦】二方庫盡量不要有配置項,最低限度不要再增加配置項。
10. 【參考】為避免應(yīng)用二方庫的依賴沖突問題,二方庫發(fā)布者應(yīng)當(dāng)遵循以下原則:
1 ) 精簡可控原則。移除一切不必要的 API 和依賴,只包含 Service API 、必要的領(lǐng)域模型對
象、 Utils 類、常量、枚舉等。如果依賴其它二方庫,盡量是 provided 引入,讓二方庫使用
者去依賴具體版本號 ; 無 log 具體實現(xiàn),只依賴日志框架。
2 ) 穩(wěn)定可追溯原則。每個版本的變化應(yīng)該被記錄,二方庫由誰維護,源碼在哪里,都需要能
方便查到。除非用戶主動升級版本,否則公共二方庫的行為不應(yīng)該發(fā)生變化。