《阿里巴巴Java開發手冊(正式版)》--工程規約
(一)應用分層
1.【推薦】圖中預設上層依賴於下層,箭頭關係表示可直接依賴,如:開放介面層可以依賴於Web層,也可以直接依賴於 Service層,依此類推:
開放介面層:可直接封裝 Service介面暴露成 RPC介面;通過 Web封裝成 http介面;閘道器控制層等。
終端顯示層:各個端的模板渲染並執行顯示層。當前主要是 velocity渲染,JS渲染,JSP渲染,移動端展示層等。
• Web層:主要是對訪問控制進行轉發,各類基本引數校驗,或者不復用的業務簡單處理等。
• Service層:相對具體的業務邏輯服務層。
• Manager層:通用業務處理層,它有如下特徵:
1) 對第三方平臺封裝的層,預處理返回結果及轉化異常資訊;
2) 對 Service層通用能力的下沉,如快取方案、中介軟體通用處理;
3) 與 DAO層互動,對 DAO的業務通用能力的封裝。
• DAO層:資料訪問層,與底層 MySQL、Oracle、Hbase進行資料互動。
外部介面或第三方平臺:包括其它部門 RPC開放介面,基礎平臺,其它公司的 HTTP介面。
2.【參考】 (分層異常處理規約)在 DAO層,產生的異常型別有很多,無法用細粒度異常進行catch,使用 catch(Exceptione)方式,並 thrownewDAOException(e),不需要列印日誌,因為日誌在 Manager/Service層一定需要捕獲並打到日誌檔案中去,如果同臺伺服器再打日誌,浪費效能和儲存。在 Service層出現異常時,必須記錄日誌資訊到磁碟,儘可能帶上引數資訊,相當於保護案發現場。如果 Manager層與 Service同機部署,日誌方式與 DAO層處理一致,如果是單獨部署,則採用與 Service一致的處理方式。Web層絕不應該繼續往上拋異常,因為已經處於頂層,無繼續處理異常的方式,如果意識到這個異常將導致頁面無法正常渲染,那麼就應該直接跳轉到友好錯誤頁面,儘量加上友好的錯誤提示資訊。開放介面層要將異常處理成錯誤碼和錯誤資訊方式返回。
3.【參考】分層領域模型規約:
• DO(Data Object):與資料庫表結構一一對應,通過 DAO層向上傳輸資料來源物件。
• DTO(Data Transfer Object):資料傳輸物件,Service和 Manager向外傳輸的物件。
• BO(Business Object):業務物件。可以由 Service層輸出的封裝業務邏輯的物件。
• QUERY:資料查詢物件,各層接收上層的查詢請求。注:超過 2個引數的查詢封裝,禁止使用 Map類來傳輸。
• VO(View Object):顯示層物件,通常是 Web向模板渲染引擎層傳輸的物件。
(二)二方庫規約
1.【強制】定義 GAV遵從以下規則:
1) GroupID格式:com.{公司/BU }.業務線.[子業務線],最多 4級。
說明:{公司/BU} 例如:alibaba/taobao/tmall/aliexpress等 BU一級;子業務線可選。
正例:com.taobao.jstorm 或 com.alibaba.dubbo.register
2) ArtifactID格式:產品線名-模組名。語義不重複不遺漏,先到倉庫中心去查證一下。
正例:dubbo-client / fastjson-api / jstorm-tool
3) Version:詳細規定參考下方。
2.【強制】二方庫版本號命名方式:主版本號.次版本號.修訂號
1) 主版本號:當做了不相容的 API 修改,或者增加了能改變產品方向的新功能。
2) 次版本號:當做了向下相容的功能性新增(新增類、介面等)。
3) 修訂號:修復 bug,沒有修改方法簽名的功能加強,保持 API 相容性。
說明:起始版本號必須為:1.0.0,而不是 0.0.1
3.【強制】線上應用不要依賴 SNAPSHOT版本(安全包除外);正式釋出的類庫必須使用 RELEASE版本號升級+1的方式,且版本號不允許覆蓋升級,必須去中央倉庫進行查證。
說明:不依賴 SNAPSHOT版本是保證應用釋出的冪等性。另外,也可以加快編譯時的打包構建。
4.【強制】二方庫的新增或升級,保持除功能點之外的其它 jar包仲裁結果不變。如果有改變,必須明確評估和驗證,建議進行 dependency:resolve前後資訊比對,如果仲裁結果完全不一致,那麼通過 dependency:tree命令,找出差異點,進行排除 jar包。
5.【強制】二方庫裡可以定義列舉型別,引數可以使用列舉型別,但是介面返回值不允許使用列舉型別或者包含列舉型別的 POJO物件。
6.【強制】依賴於一個二方庫群時,必須定義一個統一版本變數,避免版本號不一致。
說明:依賴 springframework-core,-context,-beans,它們都是同一個版本,可以定義一
個變數來儲存版本:${spring.version},定義依賴的時候,引用該版本。
7.【強制】禁止在子專案的 pom依賴中出現相同的 GroupId,相同的 ArtifactId,但是不同的Version。
說明:在本地除錯時會使用各子專案指定的版本號,但是合併成一個 war,只能有一個版本號出現在最後的 lib目錄中。曾經出現過線下除錯是正確的,釋出到線上出故障的先例。
8.【推薦】所有 pom檔案中的依賴宣告放在語句塊中,所有版本仲裁放在
<dependencyManagement>語句塊中。
說明:<dependencyManagement>裡只是宣告版本,並不實現引入,因此子專案需要顯式的宣告依賴,version和 scope都讀取自父 pom。而<dependencies>所有宣告在主 pom的<dependencies>裡的依賴都會自動引入,並預設被所有的子專案繼承。
9.【推薦】二方庫儘量不要有配置項,最低限度不要再增加配置項。
10.【參考】為避免應用二方庫的依賴衝突問題,二方庫釋出者應當遵循以下原則:
1)精簡可控原則。移除一切不必要的 API和依賴,只包含 Service API、必要的領域模型物件、Utils類、常量、列舉等。如果依賴其它二方庫,儘量是 provided引入,讓二方庫使用者去依賴具體版本號;無 log具體實現,只依賴日誌框架。
2)穩定可追溯原則。每個版本的變化應該被記錄,二方庫由誰維護,原始碼在哪裡,都需要能方便查到。除非使用者主動升級版本,否則公共二方庫的行為不應該發生變化。
(三)伺服器規約
1.【推薦】高併發伺服器建議調小 TCP協議的 time_wait超時時間。
說明:作業系統預設 240秒後,才會關閉處於 time_wait狀態的連線,在高併發訪問下,伺服器端會因為處於 time_wait的連線數太多,可能無法建立新的連線,所以需要在伺服器上調小此等待值。
正例:在 linux伺服器上請通過變更/etc/sysctl.conf檔案去修改該預設值(秒):
net.ipv4.tcp_fin_timeout = 30
2.【推薦】調大伺服器所支援的最大檔案控制代碼數(File Descriptor,簡寫為 fd)。
說明:主流作業系統的設計是將 TCP/UDP連線採用與檔案一樣的方式去管理,即一個連線對應於一個 fd。主流的 linux伺服器預設所支援最大 fd數量為 1024,當併發連線數很大時很容易因為 fd不足而現“opentoomanyfiles”錯誤,導致新的連線無法建立。 建議將 linux伺服器所支援的最大控制代碼數調高數倍(與伺服器的記憶體數量相關)。
3.【推薦】給 JVM設定-XX:+HeapDumpOnOutOfMemoryError引數,讓 JVM碰到 OOM場景時輸出dump資訊。
說明:OOM的發生是有概率的,甚至有規律地相隔數月才出現一例,出現時的現場資訊對查錯非常有價值。
4.【參考】伺服器內部重定向使用 forward;外部重定向地址使用 URL拼裝工具類來生成,否則會帶來 URL維護不一致的問題和潛在的安全風險。
整理本文的目的是方便自己閱讀,標註等,如有侵權,立馬刪除。