四 、工程規約

(一)應用分層

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(Exception e)方式，並throw new DAOException(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 版本號有延續性，版本號不允許覆蓋升級。

說明:不依賴 SNAPSHOT 版本是保證應用釋出的冪等性。另外，也可以加快編譯時的打包構建。 當前版本:1.3.3，那麼下一個合理的版本號:1.3.4 或 1.4.0 或 2.0.0

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 檔案中的依賴宣告放在語句塊中，所有版本仲裁放在 語句塊中。 說明:裡只是宣告版本，並不實現引入，因此子專案需要顯式的聲 明依賴，version 和 scope 都讀取自父 pom。而所有宣告在主 pom 的 裡的依賴都會自動引入，並預設被所有的子專案繼承。

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 不足而出現“open too many files”錯誤，導致新的連線無法建立。 建議將 linux 伺服器所支援的最大控制程式碼數調高數倍(與伺服器的記憶體數量相關)。

3. 【推薦】給 JVM 設定-XX:+HeapDumpOnOutOfMemoryError 引數，讓 JVM 碰到 OOM 場景時輸出 dump 資訊。

說明:OOM 的發生是有概率的，甚至有規律地相隔數月才出現一例，出現時的現場資訊對查錯 非常有價值。

4. 【參考】伺服器內部重定向使用 forward;外部重定向地址使用 URL 拼裝工具類來生成，否則 會帶來 URL 維護不一致的問題和潛在的安全風險。(這個是重點，化下來，以後必考)