基於Spring Boot構建應用開發規範
阿新 • • 發佈:2018-03-01
SpringBoot 項目規範 1.規範的意義和作用
- 編碼規範可以最大限度的提高團隊開發的合作效率
- 編碼規範可以盡可能的減少一個軟件的維護成本 , 並且幾乎沒有任何一個軟件,在其整個生命周期中,均由最初的開發人員來維護
- 編碼規範可以改善軟件的可讀性,可以讓開發人員盡快而徹底地理解新的代碼
- 規範性編碼還可以讓開發人員養成好的編碼習慣,甚至鍛煉出更加嚴謹的思維
2.代碼倉庫規範
2.1公共組件
- 公共組件通常指Java庫,提供特定問題的處理程序包
- 公共組件倉庫地址:https://git.netposa.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.netposa.com/vias-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.netposa.com/vias-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}目錄
基於Spring Boot構建應用開發規範