JAVA後端開發規範

時間 2019-11-16

標籤 java 後端開發規範欄目 Java 简体版

原文原文鏈接

基於阿里巴巴JAVA開發規範整理程序員

1、命名風格

【強制】類名使用 UpperCamelCase 風格，必須聽從駝峯形式，但如下情形例外：DO / BO / DTO / VO / AO正則表達式

正例：MarcoPolo / UserDO / XmlService / TcpUdpDeal / TaPromotion
反例：macroPolo / UserDo / XMLService / TCPUDPDeal / TAPromotion數據庫
【強制】方法名、參數名、成員變量、局部變量都統一使用 lowerCamelCase 風格，必須聽從駝峯形式。編程

正例： localValue / getHttpMessage() / inputUserId數組
【強制】常量命名所有大寫，單詞間用下劃線隔開，力求語義表達完整清楚，不要嫌名字長。緩存

正例：MAX_STOCK_COUNT 反例：MAX_COUNT數據結構
【強制】抽象類命名使用 Abstract 或 Base 開頭；異常類命名使用 Exception 結尾；測試類命名以它要測試的類的名稱開始，以 Test 結尾。併發
【強制】Model 類中布爾類型的變量，都不要加 is，不然部分框架解析會引發序列化錯誤。app

反例：定義爲基本數據類型 Boolean isDeleted；的屬性，它的方法也是 isDeleted()，RPC框架在反向解析的時候，「覺得」對應的屬性名稱是 deleted，致使屬性獲取不到，進而拋出異常。框架
【強制】對於 Service 和 DAO 類，基於 SOA 的理念，暴露出來的服務必定是接口，內部的實現類用 Impl 的後綴與接口區別。正例：CacheManagerImpl 實現 CacheManager 接口。
【推薦】爲了達到代碼自解釋的目標，任何自定義編程元素在命名時，使用盡可能完整的單詞組合來表達其意。

正例：從遠程倉庫拉取代碼的類命名爲PullCodeFromRemoteRepository
反例：變量int a;的隨意命名方式。

【推薦】接口類中的方法和屬性不要加任何修飾符號（public 也不要加），保持代碼的簡潔性，並加上有效的Javadoc 註釋。儘可能不要在接口裏定義變量，若是必定要定義變量，確定是與接口方法相關，而且是整個應用的基礎常量。

正例：接口方法簽名：void f(); 接口基礎常量表示：String COMPANY = "alibaba";
反例：接口方法定義：public abstract void f();
說明：JDK8 中接口容許有默認實現，那麼這個default方法，是對全部實現類都有價值的默認實現。

【參考】枚舉類名建議帶上 Enum 後綴，枚舉成員名稱須要全大寫，單詞間用下劃線隔開。
說明：枚舉其實就是特殊的常量類，且構造方法被默認強制是私有。
正例：枚舉名字爲 ProcessStatusEnum 的成員名稱：SUCCESS / UNKOWN_REASON。
【參考】各層命名規約：
A) Service/DAO 層方法命名規約
1）獲取單個對象的方法用 get 作前綴。
2）獲取多個對象的方法用 list 作前綴。
3）獲取統計值的方法用 count 作前綴。
4）插入的方法用 save/insert 作前綴。
5）刪除的方法用 remove/delete 作前綴。
6）修改的方法用 update 作前綴。

2、變量定義

【推薦】不要使用一個常量類維護全部常量，按常量功能進行歸類，分開維護。說明：大而全的常量類，非得使用查找功能才能定位到修改的常量，不利於理解和維護。

正例：緩存相關常量放在類 CacheConsts 下；系統配置相關常量放在類 ConfigConsts 下。

3、代碼格式

【強制】大括號的使用約定。若是是大括號內爲空，則簡潔地寫成{}便可，不須要換行；若是是非空代碼塊則：
1）左大括號前不換行。
2）左大括號後換行。
3）右大括號前換行。
4）右大括號後還有 else 等代碼則不換行表示終止的右大括號後必須換行。
【強制】左小括號和字符之間不出現空格；一樣，右小括號和字符之間也不出現空格。
反例：if (空格a == b空格)
【強制】if/for/while/switch/do 等保留字與括號之間都必須加空格。
【強制】任何二目、三目運算符的左右兩邊都須要加一個空格。
說明：運算符包括賦值運算符=、邏輯運算符&&、加減乘除符號等。
【強制】採用 4 個空格縮進，禁止使用 tab 字符。
說明：Vue工程採用2個空格縮進
【強制】註釋的雙斜線與註釋內容之間有且僅有一個空格。
正例：// 註釋內容，注意在//和註釋內容之間有一個空格。
【強制】方法參數在定義和傳入時，多個參數逗號後邊必須加空格。
正例：下例中實參的"a",後邊必需要有一個空格。method("a", "b", "c");
【強制】IDE 的 text file encoding 設置爲 UTF-8; IDE 中文件的換行符使用 Unix 格式，不要使用 Windows 格式。
【推薦】方法體內的執行語句組、變量的定義語句組、不一樣的業務邏輯之間或者不一樣的語義之間插入一個空行。相同業務邏輯和語義之間不須要插入空行。
說明：沒有必要插入多個空行進行隔開。

4、OOP規約

【強制】全部的覆寫方法，必須加@Override 註解。
【強制】不能使用過期的類或方法。
【強制】Object 的 equals 方法容易拋空指針異常，應使用常量或肯定有值的對象來調用 equals。
正例："test".equals(object);
反例：object.equals("test");
【強制】全部的相同類型的包裝類對象之間值的比較，所有使用 equals 方法比較。
說明：對於 Integer var = ? 在-128 至 127 範圍內的賦值，Integer 對象是在IntegerCache.cache 產生，會複用已有對象，這個區間內的 Integer 值能夠直接使用==進行判斷，可是這個區間以外的全部數據，都會在堆上產生，並不會複用已有對象，這是一個大坑，推薦使用 equals 方法進行判斷。
【強制】RPC 方法的返回值和參數必須使用包裝數據類型。
【強制】構造方法裏面禁止加入任何業務邏輯，若是有初始化邏輯，請放在 init 方法中。
【推薦】當一個類有多個構造方法，或者多個同名方法，這些方法應該按順序放置在一塊兒，便於閱讀。
【推薦】循環體內，字符串的鏈接方式，使用 StringBuilder 的 append 方法進行擴展。說明：反編譯出的字節碼文件顯示每次循環都會 new 出一個 StringBuilder 對象，而後進行 append 操做，最後經過 toString 方法返回 String 對象，形成內存資源浪費。
反例：

String str = "start";
  for (int i = 0; i < 100; i++) {
  str = str + "hello";
  }
複製代碼

【推薦】慎用 Object 的 clone 方法來拷貝對象。說明：對象的 clone 方法默認是淺拷貝，若想實現深拷貝須要重寫 clone 方法實現屬性對象的拷貝。

5、集合處理

【強制】使用集合轉數組的方法，必須使用集合的 toArray(T[] array)，傳入的是類型徹底同樣的數組，大小就是 list.size()。
說明：使用 toArray 帶參方法，入參分配的數組空間不夠大時，toArray 方法內部將從新分配內存空間，並返回新數組地址；若是數組元素大於實際所需，下標爲[ list.size() ]的數組元素將被置爲 null，其它數組元素保持原值，所以最好將方法入參數組大小定義與集合元素個數一致。正例：

List<String> list = new ArrayList<String>(2);
list.add("guan");
list.add("bao");
String[] array = new String[list.size()];
array = list.toArray(array);
複製代碼

反例：直接使用 toArray 無參方法存在問題，此方法返回值只能是 Object[]類，若強轉其它類型數組將出現 ClassCastException 錯誤。

【強制】不要在 foreach 循環裏進行元素的 remove/add 操做。remove 元素請使用 Iterator方式，若是併發操做，須要對 Iterator 對象加鎖。
正例：

Iterator<String> iterator = list.iterator();
  while (iterator.hasNext()) {
      String item = iterator.next();
      if (刪除元素的條件) {
        iterator.remove();
      }
  }
複製代碼

反例：

List<String> list = new ArrayList<String>();
  list.add("1");
  list.add("2");
  for (String item : list) {
    if ("1".equals(item)) {
      list.remove(item);
    }
  }
複製代碼

【推薦】使用 entrySet 遍歷 Map 類集合 KV，而不是 keySet 方式進行遍歷。

6、控制語句

【強制】在一個 switch 塊內，每一個 case 要麼經過 break/return 等來終止，要麼註釋說明程序將繼續執行到哪個 case 爲止；在一個 switch 塊內，都必須包含一個 default 語句而且放在最後，即便它什麼代碼也沒有。
【強制】在 if/else/for/while/do 語句中必須使用大括號。即便只有一行代碼，避單行的編碼方式：if (condition) statements;
【推薦】除經常使用方法（如 getXxx/isXxx）等外，不要在條件判斷中執行其它複雜的語句，將復雜邏輯判斷的結果賦值給一個有意義的布爾變量名，以提升可讀性。說明：不少 if 語句內的邏輯至關複雜，閱讀者須要分析條件表達式的最終結果，才能明確什麼樣的條件執行什麼樣的語句，那麼，若是閱讀者分析邏輯表達式錯誤呢？
正例： // 僞代碼以下

final boolean existed = (file.open(fileName, "w") != null) && (...) || (...);
if (existed) {
  ...
}
複製代碼

反例：

if ((file.open(fileName, "w") != null) && (...) || (...)) {
  ...
}
複製代碼

【推薦】循環體中的語句要考量性能，如下操做盡可能移至循環體外處理，如定義對象、變量、獲取數據庫鏈接，進行沒必要要的 try-catch 操做（這個 try-catch 是否能夠移至循環體外）。
【參考】下列情形，須要進行參數校驗：
1）調用頻次低的方法。
2）執行時間開銷很大的方法。此情形中，參數校驗時間幾乎能夠忽略不計，但若是由於參數錯誤致使中間執行回退，或者錯誤，那得不償失。
3）須要極高穩定性和可用性的方法。
4）對外提供的開放接口，無論是 RPC/API/HTTP 接口。 5）敏感權限入口。

7、註釋規約

【強制】類、類屬性、類方法的註釋必須使用 Javadoc 規範，使用/**內容*/ 格式，不得使用 // xxx 方式。
【強制】全部的抽象方法（包括接口中的方法）必需要用 Javadoc 註釋、除了返回值、參數、異常說明外，還必須指出該方法作什麼事情，實現什麼功能。說明：對子類的實現要求，或者調用注意事項，請一併說明。
【強制】全部的類都必須添加建立者和建立日期。
【強制】方法內部單行註釋，在被註釋語句上方另起一行，使用//註釋。方法內部多行註釋使用/* */註釋，注意與代碼對齊。
【強制】全部的枚舉類型字段必需要有註釋，說明每一個數據項的用途。
【推薦】代碼修改的同時，註釋也要進行相應的修改，尤爲是參數、返回值、異常、核心邏輯等的修改。說明：代碼與註釋更新不一樣步，就像路網與導航軟件更新不一樣步同樣，若是導航軟件嚴重滯後，就失去了導航的意義。
【參考】謹慎註釋掉代碼。在上方詳細說明，而不是簡單地註釋掉。若是無用，則刪除。
【參考】對於註釋的要求：第1、可以準確反應設計思想和代碼邏輯；第2、可以描述業務含義，使別的程序員可以迅速瞭解到代碼背後的信息。徹底沒有註釋的大段代碼對於閱讀者形同天書，註釋是給本身看的，即便隔很長時間，也能清晰理解當時的思路；註釋也是給繼任者看的，使其可以快速接替本身的工做。
【參考】好的命名、代碼結構是自解釋的，註釋力求精簡準確、表達到位。避免出現註釋的一個極端：過多過濫的註釋，代碼的邏輯一旦修改，修改註釋是至關大的負擔。
【參考】特殊註釋標記，請註明標記人與標記時間。注意及時處理這些標記，經過標記掃描，常常清理此類標記。線上故障有時候就是來源於這些標記處的代碼。
1）待辦事宜（TODO）:（標記人，標記時間，[預計處理時間]）表示須要實現，但目前還未實現的功能。這其實是一個 Javadoc 的標籤，目前的 Javadoc 尚未實現，但已經被普遍使用。只能應用於類，接口和方法（由於它是一個 Javadoc 標籤）。
2）錯誤，不能工做（FIXME）:（標記人，標記時間，[預計處理時間]）在註釋中用 FIXME 標記某代碼是錯誤的，並且不能工做，須要及時糾正的狀況。

8、其餘

【強制】在使用正則表達式時，利用好其預編譯功能，能夠有效加快正則匹配速度。說明：不要在方法體內定義：Pattern pattern = Pattern.compile(規則);
【強制】注意 Math.random() 這個方法返回是 double 類型，注意取值的範圍 0≤x<1（可以取到零值，注意除零異常），若是想獲取整數類型的隨機數，不要將 x 放大 10 的若干倍而後取整，直接使用 Random 對象的 nextInt 或者 nextLong 方法。
【強制】獲取當前毫秒數 System.currentTimeMillis(); 而不是 new Date().getTime();
【推薦】任何數據結構的構造或初始化，都應指定大小，避免數據結構無限增加吃光內存。

9、異常處理

【強制】捕獲異常是爲了處理它，不要捕獲了卻什麼都不處理而拋棄之，若是不想處理它，請將該異常拋給它的調用者。最外層的業務使用者，必須處理異常，將其轉化爲用戶能夠理解的內容。

10、MySQL數據庫

創建表規約

【強制】表名、字段名必須使用小寫字母或數字，禁止出現數字開頭，禁止兩個下劃線中間只出現數字。數據庫字段名的修改代價很大，由於沒法進行預發佈，因此字段名稱須要慎重考慮。
說明：MySQL 在 Windows 下不區分大小寫，但在 Linux 下默認是區分大小寫。所以，數據庫名、表名、字段名，都不容許出現任何大寫字母，避免節外生枝。
正例：aliyun_admin，rdc_config，level3_name 反例：AliyunAdmin，rdcConfig，level_3_name
【強制】禁用保留字，如 desc、range、match、delayed 等，請參考 MySQL 官方保留字。
【強制】主鍵索引名爲 pk_字段名；惟一索引名爲 uk_字段名；普通索引名則爲 idx_字段名。說明：pk_ 即 primary key；uk_ 即 unique key；idx_ 即 index 的簡稱。
【強制】小數類型爲 decimal，禁止使用 float 和 double。
【強制】若是存儲的字符串長度幾乎相等，使用 char 定長字符串類型。
【強制】varchar 是可變長字符串，不預先分配存儲空間，長度不要超過 5000，若是存儲長度大於此值，定義字段類型爲 text。
【強制】表必備三個字段：id，create_time, update_time, delete_flag
【強制】對於Boolean型的字段，採用decimal類型
【強制】表和字段都須要添加註釋信息。
【推薦】單錶行數超過 500 萬行或者單表容量超過 2GB，才推薦進行分庫分表。說明：若是預計三年後的數據量根本達不到這個級別，請不要在建立表時就分庫分表。
【參考】合適的字符存儲長度，不但節約數據庫表空間、節約索引存儲，更重要的是提高檢索速度。

索引規約

【強制】業務上具備惟一特性的字段，即便是多個字段的組合，也必須建成惟一索引。
說明：不要覺得惟一索引影響了 insert 速度，這個速度損耗能夠忽略，但提升查找速度是明顯的；另外，即便在應用層作了很是完善的校驗控制，只要沒有惟一索引，根據墨菲定律，必然有髒數據產生。
【強制】超過三個表禁止 join。須要 join 的字段，數據類型必須絕對一致；多表關聯查詢時，保證被關聯的字段須要有索引。
說明：即便雙表 join 也要注意表索引、SQL 性能。
【強制】在 varchar 字段上創建索引時，必須指定索引長度，不必對全字段創建索引，根據實際文本區分度決定索引長度便可。
說明：索引的長度與區分度是一對矛盾體，通常對字符串類型數據，長度爲 20 的索引，區分度會高達 90%以上，可使用 count(distinct left(列名, 索引長度))/count(*)的區分度來肯定。
【參考】建立索引時避免有以下極端誤解：
1）寧濫勿缺。認爲一個查詢就須要建一個索引。
2）寧缺勿濫。認爲索引會消耗空間、嚴重拖慢更新和新增速度。
3）抵制唯一索引。認爲業務的唯一性一概須要在應用層經過「先查後插」方式解決。

SQL語句

【強制】不要使用 count(列名)或 count(常量)來替代 count(*)，count(*)是 SQL92 定義的標準統計行數的語法，跟數據庫無關，跟 NULL 和非 NULL 無關。
說明：count(*)會統計值爲 NULL 的行，而 count(列名)不會統計此列爲 NULL 值的行。
【強制】count(distinct col) 計算該列除 NULL 以外的不重複行數，注意 count(di col1, col2) 若是其中一列全爲 NULL，那麼即便另外一列有不一樣的值，也返回爲 0。
【強制】當某一列的值全是 NULL 時，count(col)的返回結果爲 0，但 sum(col)的返回結果爲NULL.
【強制】不得使用外鍵與級聯，一切外鍵概念必須在應用層解決。
【強制】禁止使用存儲過程，存儲過程難以調試和擴展，更沒有移植性。
【推薦】in 操做能避免則避免，若實在避免不了，須要仔細評估 in 後邊的集合元素數量，控制在 1000 個以內。
【參考】若是有全球化須要，全部的字符存儲與表示，均以 utf-8 編碼，注意字符的區別。
說明： SELECT LENGTH("輕鬆工做")；返回爲 12 SELECT CHARACTER_LENGTH("輕鬆工做")；返回爲 4 若是須要存儲表情，那麼選擇 utfmb4 來進行存儲，注意它與 -8 編碼的區別。
【強制】更新數據表記錄時，必須同時更新記錄對應的 update_time 字段值爲當前時間。
【參考】@Transactional 事務不要濫用。事務會影響數據庫的 QPS，另外使用事務的地方需要考慮各方面的回滾方案，包括緩存回滾、搜索引擎回滾、消息補償、統計修正等。