基於Spring Boot構建應用開發規範

1.規範的意義和做用

• 編碼規範能夠最大限度的提升團隊開發的合做效率
• 編碼規範能夠儘量的減小一個軟件的維護成本 , 而且幾乎沒有任何一個軟件，在其整個生命週期中，均由最初的開發人員來維護
• 編碼規範能夠改善軟件的可讀性，可讓開發人員儘快而完全地理解新的代碼
• 規範性編碼還可讓開發人員養成好的編碼習慣，甚至鍛煉出更加嚴謹的思惟

2.代碼倉庫規範

2.1公共組件

• 公共組件一般指Java庫，提供特定問題的處理程序包
• 公共組件倉庫地址：https://git.company.com/java-library-group
• 公共組件的座標命名規範
  • 分組編號：<groupId>com.company.library</groudId> 固定取值
  • 組件名稱：<artifactId>name</artifactId> name根據組件名稱定義
  • 組件版本：<version>x.y.z</versio> x.y.z根據組件實際版本狀況定義

2.2服務組件

• 服務組件一般指能夠獨立部署，運行，維護的服務程序包
• 服務組件倉庫地址：https://git.company.com/server-microservice-group
• 應用組件的座標命名規範
  • 分組編號：<groupId>com.company.server</groudId>固定取值
  • 組件名稱：<artifactId>name</artifactId> name根據組件名稱定義
  • 組件版本：<version>x.y.z</versio> x.y.z根據組件實際版本狀況定義

3開發環境規範

• 開發環境：JDK1.7+
• 開發工具：IntelliJ IDEA 2017（安裝Lombok Plugin）
• 構建工具：Maven3.x
• 代碼管理工具：Git /TortoiseGit

4.項目結構規範

4.1簡述

一個項目對應代碼倉庫中的一個倉庫，項目結構是指一個基於Maven建立的項目目錄結構。公共組件項目，一般會建立一個Maven普通項目。服務組件項目，一般會建立一個Maven聚合項目，並在聚合項目目錄下建立多個繼承Maven聚合項目的Maven模塊，它們一塊兒做爲服務組件項目的組成部分。

4.2項目名

• 要求
  • 英文名稱，做爲倉庫，項目，項目根目錄，組件（公共組件，服務組件）的名稱
  • 中文名稱，用於代碼倉庫的描述
  • 項目名稱和代碼倉庫的名稱保持一致
• 定義
  • 項目名稱一般由團隊負責人肯定
• 示例
  • 項目中文名：人臉數據倉庫
  • 項目英文名：data-warehouse-face
  • 項目目錄名：data-warehouse-face
  • 項目倉庫地址：https://git.company.com/server-microservice-group/data-warehouse-face.git
  • 初始版本：1.0.0
  • 示例是一個服務組件，根據上面定義的信息肯定該服務組件的Maven座標命名：

<groupId>com.company.server</groupId>
<artifactId>data-warehouse-face</artifactId>
<version>1.0.0</version>

4.3模塊命名

• 要求
  • 模塊名稱：{項目名稱}-{模塊名稱} 模塊名稱簡潔體現職責
  • 模塊名字做爲模塊組件的名稱
• 示例
• 人臉數據倉庫的數據接入模塊名稱：data-warehouse-face-access

4.4項目目錄

• 項目目錄遵循Maven約定目錄格式

4.5源碼目錄

• 源碼目錄指：{項目目錄}/src/main/
• 打包定義目錄：src/main/assembly
• 代碼目錄：src/main/java
• 資源目錄：src/main/resources
  • /db：數據庫腳本歸檔
  • /data：內部依賴數據歸檔
• 文檔目錄：src/main/docs
• 腳本目錄：src/main/bin
  • run-manage.sh 運行管理腳本（經過參數start, stop, status, help info控制程序運行）
  • sh：服務組件啓動腳本
  • sh：服務組件中止腳本

5.編碼規範

5.1包規範

• 項目基本包：com.company.{項目英文名（較長時適當簡化）}.{模塊名（可選）}
• config：配置類
• startup：與服務啓動相關的類
• client：提供客戶端實現的相關類
• common：公共類，定義常量類，組件
• entity: 數據庫相關的實體類
• model:數據模型類(參數模型，數據傳輸模型等）
• control:控制層接口
• service: 服務層
• dao：數據庫訪問層

5.2日誌記錄

• 統一使用SLF4j接口

5.3異常處理

• 運行時異常：經過參數檢查等方式避免或拋出運行時異常，日誌記錄
• 檢查異常：檢查異常須要捕獲，處理，日誌記錄

5.4接口定義

• 原則
  • 接口地址定義代表用意
  • 接口地址定義清晰，簡潔，無歧義
  • 同一個服務組件的接口定義具備一致性
• 格式
  • 控制類的頂層地址格式:/{頂層分類名}，例如：/library 人員庫相關接口的頂層地址
  • 接口定義使用Swagger的API註解說明
  • 標註完整的請求信息，請求方法，請求地址，參數可選性，接口描述
• 請求方式
  • GET URL-Params
  • POST Form-Data
  • POST RequestBody(JSON格式)
  • POST Mulitpart
• 響應方式
  • 統一的響應模型

5.5輔助工具

• 字符串處理：apache common-lang3
• 時間日期處理：joda-time
• JSON處理：Gson，Fastjson
• 集合擴展工具：guava
• 文件和流處理：commons-io
• 編解碼：commons-codec
• 建議：儘量使用開源組件

5.6代碼註釋

• 類，接口，枚舉頂層註釋
• 接口方法註釋
• 靜態方法註釋
• 公開方法註釋
• 類的屬性字段註釋
• 常量註釋
• 不限於以上

6.代碼控制規範

6.1拉取原則

• 強制
  • 每日開始工做拉取
• 約定
  • 提交以前拉取

6.2提交原則

• 強制
  • 提交代碼必須構建成功（好比：編譯，打包成共）
  • 提交代碼必須完整（好比：少提文件）
  • 提交代碼必須忽略到本地臨時文件（好比：target, logs, .idea, *.iml,dist 等）
• 約定
  • 完成一個功能提交
  • 修改一個Bug修改提交
  • 解決衝突提交
  • 每日結束工做提交

6.3提交註釋

• 強制
  • 中文填寫註釋
  • 註釋反映本次提交變動狀況
• 約定
  • 註釋描述添加前綴，前綴以下
  • [建立] 一般在項目建立時使用
  • [新增]
  • [修改]
  • [刪除]
  • [修復-number] 修復Bug使用，number是Bug編號

7.構建規範

7.1公共組件構建規範

• 構建輸出組件包
• 構建輸出組件源碼包
• 構建發佈到公司私有倉庫

7.2服務組件構建規範

• 服務組件包命名：{組件名稱}-{版本號}-bin.zip
• 構建輸出到工程根目錄下的dist/{組件名稱}-{yyyyMMddHH}目錄