團隊作業第五次--代碼規範、沖刺任務與計劃

這個作業屬于哪個課程	2020春|S班（福州大學）
這個作業要求在哪裡	團隊作業第五次——站立式會議+alpha沖刺
團隊名稱	軟工實踐互動評價小組
這個作業的目标	—站立式會議+alpha沖刺
作業正文
其他參考文獻	簡書

二、沖刺任務與計劃

時間\任務	前端	後端
4.26	項目部署、熟悉開發環境
4.28	登入注冊頁面	登入注冊、使用者資訊接口
4.30	前台擷取表單清單及内容；背景主要功能布局	表單相關接口實作
5.1	前台表單送出功能；背景部分表格實作	人員管理接口
5.2	前台小組頁面；背景表格實作	班級、團隊接口
5.3	統計頁面	分數核算功能
5.4	功能完善	資訊統計接口
5.5-5.7	前後端連接配接測試與完善

二、代碼規範

• 參考主流代碼規範：【參考連結】

1. 命名規範

1.1 總體命名規則

1. 名字含義要明确，做到見名知義,如: User，Customer
2. 盡量少用縮寫，必須確定能讓人看懂含義。  
           

1.2 變量名

1. 小駝峰式命名，變量名首字母必須為小寫字母，不使用 “_” 作為變量名(包括成員變量)開頭
2. 盡量使用英文作為變量名， 若使用漢語拼音，必須注釋清楚
3. 正确：userName   錯誤：UserName，_UserName,username ```
           

1.3 常量名

1. 常量名必須全部為大寫
2. 各單詞必須以下劃線分開，以便區分
3. 對于枚舉類常量，如：狀态，盡量使用Enums定義 如
public enum ApplStatus implements ResponseService{ APPROVING("AP","申請中")， PASSS("PS"， “已認證”)， REJECT("RJ"， “已拒絕”) }
           

1.4 包名

1. 包名必須小寫
2. 包名盡量簡潔，一個單詞或縮寫
3. 包名不能以數字開頭，盡量隻包含字母
4. 所有系統包命名須在：com.qihoo.finance，如：com.qihoo.finance.msf；maven依賴，groupId：com.qihoo.finance.xxx，artifactid： xxx-app, xxx-api等
           

1.5 類名

1. 大駝峰式命名，即單詞首字母大寫，如：UserService
2. 接口名不加字首
3. 抽象類名以Abstract開頭
4. 接口實作類名必須加上Impl，以Impl結尾，如：UserServiceImpl
           

2. 排版規範

1. 縮進必須用space，不能使用tab鍵，可以在eclipse或其他開發工具配置一個tab用4個space代替。
2. 單行字元數不超過120個
3. 開發工具建議使用intellij Idea，工具穩定性好，智能化，記憶體消耗穩定。
4. 其他？可以使用工具自動格式化功能
           

3. 注釋規範

1. 類名，功能方法接口名稱必須有注釋
2. 複雜代碼邏輯必須有注釋
3. 代碼注釋不超過一行使用'//'，超過一行使用‘/* */’
           

4. 代碼送出規範

1. 原則上完成一個完整功能并自測無異常後，方可checkin代碼，必須保證無編譯報錯
2. 送出代碼必須寫注釋，能夠完整描述本次送出變更的内容
例如：
缺陷/需求編号：（如果有）
修複/送出說明：修複自動擷取執行個體編号并發啟動擷取失敗問題/增加kryo序列化擴充，并設定為dubbo協定預設的序列化元件
           

5. 業務開發規範

5.1 包路徑規範

1. 按公司域名，系統，子系統[子產品]方式命名， 如：com.qihoo.msf.app.cust
2. 在子系統/子產品下，業務開發一般包含以下幾個包：
    service         定義服務接口
    domain/entity   定義實體類
    Exception       定義異常類已經異常錯誤定義
    dao             資料通路層
           

5.2 配置檔案路徑規範

配置檔案統一規劃在 src/main/resources 目錄下，按照配置檔案類型可以劃分為一下幾個子目錄
    spring          spring相關配置檔案，可以根據元件或子產品拆分為幾個檔案，啟動application.xml預設加載配置檔案夾
    properties      存放*.properties檔案夾，與環境相關的配置在此類檔案中，系統會初始化加載，測試生産放在特殊路徑，與執行個體部署無關，以達到配置分離目的。
    mybatis/mappings/子子產品  Mybatis的Mapper檔案，分子產品存放
    dubbo-service/[consumer/privider]-service    服務注冊配置，consumer-service檔案夾存放所有依賴的外部服務注冊，按依賴系統分檔案，如：loan-service.xml，customer-service.xml；provider-service檔案夾存放執行個體提供的服務配置。
    META-INF/dubbo/internal   dubbo擴充包，對dubbo服務擴充在此注冊，dubbo基于spi擴充。
           

5.3 MAVEN項目規範

1. maven命名規則，com.qihoo.系統名
2. 任何一個子系統的服務接口定義和服務實作必須劃分為兩個項目，如：loan-provider，loan-api
    a. 服務接口項目主要包含以下幾個子產品:
        service         接口定義類
        domain/entity   接口相關執行個體定義
        exception       異常定義
    b. 服務實作項目主要包含：
        業務邏輯實作
        dao接口定義及實作
           

5.4 測試代碼編寫規範

1. 測試相關代碼必須在 src/test/java 目錄下
2. 測試相關的配置必須在 src/test/resources 目錄下
3. 測試代碼必須采用Junit方式編寫，基礎加載讀取資料可以繼承SpringTestCase即可
4. 測試案例必須有斷言結果，如：Assert.assertEquals("Error20001", actualResult);
           

5.5 異常及錯誤編碼規範

5.5.1 異常說明
1. 異常可分為業務異常和系統異常，系統異常的基類為SystemException， 業務異常的基類為BusinessException。父類為ServiceException
2. 業務邏輯校驗異常，抛出BusinessException
3. msf服務體系内所有暴露服務接口定義抛出ServiceException，外部系統調用服務，通過狀态碼傳回異常資訊
3. 所有的錯誤代碼采用Enum定義
           

5.5.2 錯誤代碼命名規範

1. 系統異常代碼由7位組成， 規則為：S+3位系統代碼+3位數字編碼，如：SAPV001   服務調用逾時
2. 業務異常代碼由7位代碼組成，規則為：B+3位系統代碼+3位數字， 如BAPV000   請求參數為空
3. enum常量命名格式為：子產品代碼+‘_’+異常變量，異常變量含義與中文一緻，命名含義清晰，見字識義
4. 錯誤代碼按子產品連續編碼，不同子產品之間起始位數字不一樣，如下圖所示：
           

5.6 日志規範

1. 日志統一采用log4j2，是log4j的更新版本，性能是log4j的10倍，暫時采用預設的log4j
2. Logger的擷取方式統一采用class的方式，使用dubbo提供的Logger，LoggerFactory類，如：
    private static final Logger logger = LoggerFactory.getLogger(UserService.class);
3. 業務關鍵環節必須列印日志
4. 外部接口調用必須列印日志，并統計接口調用耗時，以便統計趨勢圖
5. error級别以上的日志，必須記錄關鍵業務資訊，如方法的入參，錯誤發生時的變量現場，以便回溯追蹤問題。
6. 禁止列印密碼等敏感資訊
           

5.7 事務規範

事務統一在spring配置檔案中聲明，按照方法比對方式，服務開發隻需要遵守命名規則即可
1. 不允許通過注解的方式定義事務，因事務源切換，事務控制機制等不易統一管理
2. 外部接口必須禁止在事務中
3. 禁止長事務，長事務切分為多個短事務，最好dml集中使用事務
4. 禁止嵌套事務，嵌套事務不易掌控
5. 事務必須顯式聲明，方法名比對方式，‘*Trx’，‘\*NewTrx’,方法預設非事務運作
           

6. 系統設計規範

6.1 接口設計規範

1. 一切基于接口開發，提供業務邏輯服務必須提供接口
2. 接口方法參數超過3個，需要轉換為dto屬性，對象入參
3. 對外提供服務接口JSON傳回結構[狀态,錯誤代碼,錯誤描述,資料]
4. Module内部服務接口類名以Service結尾，接口方法細粒度;對外提供接口類名以Facade結尾，接口方法定義粗粒度，禁止跨域調用DAO。
5. Service實作内部細粒度業務邏輯，Service不能跨域調用Service。
6. Façade層負責對外提供粗粒度功能方法，采用模闆設計模式方法，實作僅包括：1. 入參校驗；2.入參轉換、清洗；3. 粗粒度業務功能流程控制（具體實作下沉到Service層，超過5個步驟應考慮下沉到Service）；4.出參資料轉換。
7. Facade調用：不同釋出單元接口（Façade）調用，封裝成内部Service方式，并實作入參出參記錄，耗時統計等，系統内部隻與内部Service互動；系統内不同待拆分子產品之前接口調用Façade。
8. 盡量使用緩存：配置類資料使用記憶體（一級）緩存；業務類資料使用redis（二級）緩存
9. 服務必須設計為無狀态服務，即，請求可以在任何執行個體完成處理
10. 服務設計為基于https短連接配接服務
11. 服務設計可并發執行、幂等性
12. 禁止使用Map作為入參出參，會增加接口複雜度，容易造成序列化、反序列化失敗
13. 接口入參出參禁止删除字段、修改參數字段名，
14. 接口可以新增入參，出參；如果接口邏輯不相容修改，必須使用版本号，并通知下遊修改
15. 接口預設使用dubbo協定，單次請求入參、出參不能超過100k，否則必須更換hessian協定
           

6.2 領域設計規範

1. 服務類基于業務領域子產品劃分，劃分原則可以與業務表對應
2. 盡量減少表連接配接，杜絕兩個業務領域的表連接配接
3. 禁止大表連接配接（超過100w資料）
4. 禁止在SQL語句中使用1=1
5. 禁止批量資料用in關鍵詞分組排序，即在In條件複雜查詢語句
6. 更新操作條件必須有索引，通過explain确認執行計劃走索引，盡量使用pk主鍵
7. 查詢條件必須走索引
8. 原則上不允許應用使用delete語句，如有需要，必須記log，經過團隊評審
9. 實體類與資料庫表對應，api接口下的實體與dao層不一緻，dao層實體命名為XxxEntity，防止修改内部實體類影響接口穩定性。
           

6.3 資料庫設計規範

1. 禁止删除字段
    2. 禁止更新字段名稱，類型,減少長度；可以修改增加字段長度或備注
    3. 資料庫腳本支援提前上線，否則會影響熱釋出或者灰階釋出
    4. 每個領域實體表必須有一個領域主鍵驅動，便于資訊查詢
    5. 查詢結果按需讀取，防止因字段過大造成資料傳輸開銷
    6. SQL命名準确，功能要單一，不能包含多種含義功能，維護會更複雜
           

6.4 redis緩存使用規範

1. 存放業務資料，必須設定ttl
           

6.5 記憶體緩存使用規範

1. 記憶體緩存隻能存放開關類配置資料
           

7. main目錄下的代碼中不能包含以下代碼,test目錄下可以有

1. public staitc void main(String[] args) 
    2. System.out.println();
    3. e.printStackTrace();
           

8. 輸入輸出流要再finally塊中關閉

9. 定義變量用static final，而不是final static。

1 public static 必須加上final，防止被篡改
2 protected static 可以不用加上final
           

10. 泛型在定義變量時已經指定類型，執行個體化時不需要再指定泛型的類型。

//不建議的示例
Map<String, Object> map = new HashMap<String, Object>;
List<Map<String, Object>> resltList = new ArrayList<Map<String, Object>>();
//建議的示例
Map<String, Object> map = new HashMap<>;
List<Map<String, Object>> resltList = new ArrayList<>();
           

11. 不能直接catch throwable。因為throwable裡包含OOM等異常，而此類異常是不需要捕獲的。

12. 方法或者方法體，都不能直接抛出一個Exception，隻能抛出一個自定義的Exception子類,例如SeriviceException

因為如果直接抛出Exception，調用該方法的調用者有可能無法識别異常是系統抛出的還是應用抛出的。