1.規(guī)范的意義和作用

· 編碼規(guī)范可以最大限度的提高團隊開發(fā)的合作效率

· 編碼規(guī)范可以盡可能的減少一個軟件的維護成本 , 并且?guī)缀鯖]有任何一個軟件，在其整個生命周期中，均由最初的開發(fā)人員來維護

· 編碼規(guī)范可以改善軟件的可讀性，可以讓開發(fā)人員盡快而徹底地理解新的代碼

· 規(guī)范性編碼還可以讓開發(fā)人員養(yǎng)成好的編碼習慣，甚至鍛煉出更加嚴謹?shù)乃季S

2.代碼倉庫規(guī)范

2.1公共組件

· 公共組件通常指Java庫，提供特定問題的處理程序包

· 公共組件倉庫地址：https://git.company.com/java-library-group

· 公共組件的坐標命名規(guī)范

o 分組編號：<groupId>com.company.library</groudId> 固定取值

o 組件名稱：<artifactId>name</artifactId> name根據(jù)組件名稱定義

o 組件版本：<version>x.y.z</versio> x.y.z根據(jù)組件實際版本情況定義

2.2服務組件

· 服務組件通常指可以獨立部署，運行，維護的服務程序包

· 服務組件倉庫地址：https://git.company.com/server-microservice-group

· 應用組件的坐標命名規(guī)范

o 分組編號：<groupId>com.company.server</groudId>固定取值

o 組件名稱：<artifactId>name</artifactId> name根據(jù)組件名稱定義

o 組件版本：<version>x.y.z</versio> x.y.z根據(jù)組件實際版本情況定義

3開發(fā)環(huán)境規(guī)范

· 開發(fā)環(huán)境：JDK1.7+

· 開發(fā)工具：IntelliJ IDEA 2017（安裝Lombok Plugin）

· 構(gòu)建工具：Maven3.x

· 代碼管理工具：Git /TortoiseGit

4.項目結(jié)構(gòu)規(guī)范

4.1簡述

一個項目對應代碼倉庫中的一個倉庫，項目結(jié)構(gòu)是指一個基于Maven創(chuàng)建的項目目錄結(jié)構(gòu)。公共組件項目，通常會創(chuàng)建一個Maven普通項目。服務組件項目，通常會創(chuàng)建一個Maven聚合項目，并在聚合項目目錄下創(chuàng)建多個繼承Maven聚合項目的Maven模塊，它們一起作為服務組件項目的組成部分。

4.2項目名

· 要求

o 英文名稱，作為倉庫，項目，項目根目錄，組件（公共組件，服務組件）的名稱

o 中文名稱，用于代碼倉庫的描述

o 項目名稱和代碼倉庫的名稱保持一致

· 定義

o 項目名稱通常由團隊負責人確定

· 示例

o 項目中文名：人臉數(shù)據(jù)倉庫

o 項目英文名：data-warehouse-face

o 項目目錄名：data-warehouse-face

o 項目倉庫地址：https://git.company.com/server-microservice-group/data-warehouse-face.git

o 初始版本：1.0.0

o 示例是一個服務組件，根據(jù)上面定義的信息確定該服務組件的Maven坐標命名：

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

4.3模塊命名

· 要求

o 模塊名稱：{項目名稱}-{模塊名稱} 模塊名稱簡潔體現(xiàn)職責

o 模塊名字作為模塊組件的名稱

· 示例

· 人臉數(shù)據(jù)倉庫的數(shù)據(jù)接入模塊名稱：data-warehouse-face-access

4.4項目目錄

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

4.5源碼目錄

· 源碼目錄指：{項目目錄}/src/main/

· 打包定義目錄：src/main/assembly

· 代碼目錄：src/main/java

· 資源目錄：src/main/resources

o /db：數(shù)據(jù)庫腳本歸檔

o /data：內(nèi)部依賴數(shù)據(jù)歸檔

· 文檔目錄：src/main/docs

· 腳本目錄：src/main/bin

o run-manage.sh 運行管理腳本（通過參數(shù)start, stop, status, help info控制程序運行）

o sh：服務組件啟動腳本

o sh：服務組件停止腳本

5.編碼規(guī)范

5.1包規(guī)范

· 項目基本包：com.company.{項目英文名（較長時適當簡化）}.{模塊名（可選）}

· config：配置類

· startup：與服務啟動相關的類

· client：提供客戶端實現(xiàn)的相關類

· common：公共類，定義常量類，組件

· entity: 數(shù)據(jù)庫相關的實體類

· model:數(shù)據(jù)模型類(參數(shù)模型，數(shù)據(jù)傳輸模型等）

· control:控制層接口

· service: 服務層

· dao：數(shù)據(jù)庫訪問層

5.2日志記錄

· 統(tǒng)一使用SLF4j接口

5.3異常處理

· 運行時異常：通過參數(shù)檢查等方式避免或拋出運行時異常，日志記錄

· 檢查異常：檢查異常需要捕獲，處理，日志記錄

5.4接口定義

· 原則

o 接口地址定義表明用意

o 接口地址定義清晰，簡潔，無歧義

o 同一個服務組件的接口定義具有一致性

· 格式

o 控制類的頂層地址格式:/{頂層分類名}，例如：/library 人員庫相關接口的頂層地址

o 接口定義使用Swagger的API注解說明

o 標注完整的請求信息，請求方法，請求地址，參數(shù)可選性，接口描述

· 請求方式

o GET URL-Params

o POST Form-Data

o POST RequestBody(JSON格式)

o POST Mulitpart

· 響應方式

o 統(tǒng)一的響應模型

5.5輔助工具

· 字符串處理：apache common-lang3

· 時間日期處理：joda-time

· JSON處理：Gson，F(xiàn)astjson

· 集合擴展工具：guava

· 文件和流處理：commons-io

· 編解碼：commons-codec

· 建議：盡可能使用開源組件

5.6代碼注釋

· 類，接口，枚舉頂層注釋

· 接口方法注釋

· 靜態(tài)方法注釋

· 公開方法注釋

· 類的屬性字段注釋

· 常量注釋

· 不限于以上

6.代碼控制規(guī)范

6.1拉取原則

· 強制

o 每日開始工作拉取

· 約定

o 提交之前拉取

6.2提交原則

· 強制

o 提交代碼必須構(gòu)建成功（比如：編譯，打包成共）

o 提交代碼必須完整（比如：少提文件）

o 提交代碼必須忽略到本地臨時文件（比如：target, logs, .idea, *.iml,dist 等）

· 約定

o 完成一個功能提交

o 修改一個Bug修改提交

o 解決沖突提交

o 每日結(jié)束工作提交

6.3提交注釋

· 強制

o 中文填寫注釋

o 注釋反映本次提交變更情況

· 約定

o 注釋描述添加前綴，前綴如下

o [創(chuàng)建] 通常在項目創(chuàng)建時使用

o [新增]

o [修改]

o [刪除]

o [修復-number] 修復Bug使用，number是Bug編號

7.構(gòu)建規(guī)范

7.1公共組件構(gòu)建規(guī)范

· 構(gòu)建輸出組件包

· 構(gòu)建輸出組件源碼包

· 構(gòu)建發(fā)布到公司私有倉庫

7.2服務組件構(gòu)建規(guī)范

· 服務組件包命名：{組件名稱}-{版本號}-bin.zip

· 構(gòu)建輸出到工程根目錄下的dist/{組件名稱}-{yyyyMMddHH}目錄