JAVA後端開發規範

silianpan發表於2018-04-21
Java後端

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

一、命名風格

  1. 【強制】類名使用 UpperCamelCase 風格，必須遵從駝峰形式，但以下情形例外：DO / BO / DTO / VO / AO

    正例：MarcoPolo / UserDO / XmlService / TcpUdpDeal / TaPromotion
    反例：macroPolo / UserDo / XMLService / TCPUDPDeal / TAPromotion

  2. 【強制】方法名、引數名、成員變數、區域性變數都統一使用 lowerCamelCase 風格，必須遵從 駝峰形式。

    正例： localValue / getHttpMessage() / inputUserId

  3. 【強制】常量命名全部大寫，單詞間用下劃線隔開，力求語義表達完整清楚，不要嫌名字長。

    正例：MAX_STOCK_COUNT 反例：MAX_COUNT

  4. 【強制】抽象類命名使用 Abstract 或 Base 開頭；異常類命名使用 Exception 結尾；測試類命名以它要測試的類的名稱開始，以 Test 結尾。

  5. 【強制】Model 類中布林型別的變數，都不要加 is，否則部分框架解析會引起序列化錯誤。

    反例：定義為基本資料型別 Boolean isDeleted；的屬性，它的方法也是 isDeleted()，RPC框架在反向解析的時候，“以為”對應的屬性名稱是 deleted，導致屬性獲取不到，進而丟擲異常。

  6. 【強制】對於 Service 和 DAO 類，基於 SOA 的理念，暴露出來的服務一定是介面，內部的實現類用 Impl 的字尾與介面區別。 正例：CacheManagerImpl 實現 CacheManager 介面。

  7. 【推薦】為了達到程式碼自解釋的目標，任何自定義程式設計元素在命名時，使用盡量完整的單片語合來表達其意。

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

  1. 【推薦】介面類中的方法和屬性不要加任何修飾符號（public 也不要加），保持程式碼的簡潔 性，並加上有效 的Javadoc 註釋。儘量不要在介面裡定義變數，如果一定要定義變數，肯定是 與介面方法相關，並且是整個應用的基礎常量。

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

  1. 【參考】列舉類名建議帶上 Enum 字尾，列舉成員名稱需要全大寫，單詞間用下劃線隔開。
    說明：列舉其實就是特殊的常量類，且構造方法被預設強制是私有。
    正例：列舉名字為 ProcessStatusEnum 的成員名稱：SUCCESS / UNKOWN_REASON。

  2. 【參考】各層命名規約：
    A) Service/DAO 層方法命名規約
    1） 獲取單個物件的方法用 get 做字首。
    2） 獲取多個物件的方法用 list 做字首。
    3） 獲取統計值的方法用 count 做字首。
    4） 插入的方法用 save/insert 做字首。
    5） 刪除的方法用 remove/delete 做字首。
    6） 修改的方法用 update 做字首。

二、變數定義

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

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

三、程式碼格式

  1. 【強制】大括號的使用約定。如果是大括號內為空，則簡潔地寫成{}即可，不需要換行；如果 是非空程式碼塊則：
    1） 左大括號前不換行。
    2） 左大括號後換行。
    3） 右大括號前換行。
    4） 右大括號後還有 else 等程式碼則不換行 表示終止的右大括號後必須換行。

  2. 【強制】 左小括號和字元之間不出現空格；同樣，右小括號和字元之間也不出現空格。
    反例：if (空格a == b空格)

  3. 【強制】if/for/while/switch/do 等保留字與括號之間都必須加空格。

  4. 【強制】任何二目、三目運算子的左右兩邊都需要加一個空格。
    說明：運算子包括賦值運算子=、邏輯運算子&&、加減乘除符號等。

  5. 【強制】採用 4 個空格縮排，禁止使用 tab 字元。
    說明：Vue工程採用2個空格縮排

  6. 【強制】註釋的雙斜線與註釋內容之間有且僅有一個空格。
    正例：// 註釋內容，注意在//和註釋內容之間有一個空格。

  7. 【強制】方法引數在定義和傳入時，多個引數逗號後邊必須加空格。
    正例：下例中實參的"a",後邊必須要有一個空格。method("a", "b", "c");

  8. 【強制】IDE 的 text file encoding 設定為 UTF-8; IDE 中檔案的換行符使用 Unix 格式，不要使用 Windows 格式。

  9. 【推薦】方法體內的執行語句組、變數的定義語句組、不同的業務邏輯之間或者不同的語義之間插入一個空行。相同業務邏輯和語義之間不需要插入空行。
    說明：沒有必要插入多個空行進行隔開。

四、OOP規約

  1. 【強制】所有的覆寫方法，必須加@Override 註解。

  2. 【強制】不能使用過時的類或方法。

  3. 【強制】Object 的 equals 方法容易拋空指標異常，應使用常量或確定有值的物件來呼叫 equals。
    正例："test".equals(object);
    反例：object.equals("test");

  4. 【強制】所有的相同型別的包裝類物件之間值的比較，全部使用 equals 方法比較。
    說明：對於 Integer var = ? 在-128 至 127 範圍內的賦值，Integer 物件是在IntegerCache.cache 產生，會複用已有物件，這個區間內的 Integer 值可以直接使用==進行判斷，但是這個區間之外的所有資料，都會在堆上產生，並不會複用已有物件，這是一個大坑， 推薦使用 equals 方法進行判斷。

  5. 【強制】RPC 方法的返回值和引數必須使用包裝資料型別。

  6. 【強制】構造方法裡面禁止加入任何業務邏輯，如果有初始化邏輯，請放在 init 方法中。

  7. 【推薦】當一個類有多個構造方法，或者多個同名方法，這些方法應該按順序放置在一起， 便於閱讀。

  8. 【推薦】迴圈體內，字串的連線方式，使用 StringBuilder 的 append 方法進行擴充套件。 說明：反編譯出的位元組碼檔案顯示每次迴圈都會 new 出一個 StringBuilder 物件，然後進行 append 操作，最後通過 toString 方法返回 String 物件，造成記憶體資源浪費。
    反例：

  String str = "start";
  for (int i = 0; i < 100; i++) {
  str = str + "hello";
  }
複製程式碼
  1. 【推薦】慎用 Object 的 clone 方法來拷貝物件。 說明：物件的 clone 方法預設是淺拷貝，若想實現深拷貝需要重寫 clone 方法實現屬性物件 的拷貝。

五、集合處理

  1. 【強制】使用集合轉陣列的方法，必須使用集合的 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 錯誤。

  1. 【強制】不要在 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);
    }
  }
複製程式碼
  1. 【推薦】使用 entrySet 遍歷 Map 類集合 KV，而不是 keySet 方式進行遍歷。

六、控制語句

  1. 【強制】在一個 switch 塊內，每個 case 要麼通過 break/return 等來終止，要麼註釋說明程式將繼續執行到哪一個 case 為止；在一個 switch 塊內，都必須包含一個 default 語句並且 放在最後，即使它什麼程式碼也沒有。

  2. 【強制】在 if/else/for/while/do 語句中必須使用大括號。即使只有一行程式碼，避 單行的編碼方式：if (condition) statements;

  3. 【推薦】除常用方法（如 getXxx/isXxx）等外，不要在條件判斷中執行其它複雜的語句，將復 雜邏輯判斷的結果賦值給一個有意義的布林變數名，以提高可讀性。 說明：很多 if 語句內的邏輯相當複雜，閱讀者需要分析條件表示式的最終結果，才能明確什麼 樣的條件執行什麼樣的語句，那麼，如果閱讀者分析邏輯表示式錯誤呢？
    正例： // 虛擬碼如下

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

反例：

if ((file.open(fileName, "w") != null) && (...) || (...)) {
  ...
}
複製程式碼
  1. 【推薦】迴圈體中的語句要考量效能，以下操作儘量移至迴圈體外處理，如定義物件、變數、 獲取資料庫連線，進行不必要的 try-catch 操作（這個 try-catch 是否可以移至迴圈體外）。
  2. 【參考】下列情形，需要進行引數校驗：
    1） 呼叫頻次低的方法。
    2） 執行時間開銷很大的方法。此情形中，引數校驗時間幾乎可以忽略不計，但如果因為參 數錯誤導致中間執行回退，或者錯誤，那得不償失。
    3） 需要極高穩定性和可用性的方法。
    4） 對外提供的開放介面，不管是 RPC/API/HTTP 介面。 5） 敏感許可權入口。

七、註釋規約

  1. 【強制】類、類屬性、類方法的註釋必須使用 Javadoc 規範，使用/**內容*/ 格式，不得使用 // xxx 方式。

  2. 【強制】所有的抽象方法（包括介面中的方法）必須要用 Javadoc 註釋、除了返回值、引數、 異常說明外，還必須指出該方法做什麼事情，實現什麼功能。 說明：對子類的實現要求，或者呼叫注意事項，請一併說明。

  3. 【強制】所有的類都必須新增建立者和建立日期。

  4. 【強制】方法內部單行註釋，在被註釋語句上方另起一行，使用//註釋。方法內部多行註釋 使用/* */註釋，注意與程式碼對齊。

  5. 【強制】所有的列舉型別欄位必須要有註釋，說明每個資料項的用途。

  6. 【推薦】程式碼修改的同時，註釋也要進行相應的修改，尤其是引數、返回值、異常、核心邏輯 等的修改。 說明：程式碼與註釋更新不同步，就像路網與導航軟體更新不同步一樣，如果導航軟體嚴重滯後， 就失去了導航的意義。

  7. 【參考】謹慎註釋掉程式碼。在上方詳細說明，而不是簡單地註釋掉。如果無用，則刪除。

  8. 【參考】對於註釋的要求：第一、能夠準確反應設計思想和程式碼邏輯；第二、能夠描述業務含 義，使別的程式設計師能夠迅速瞭解到程式碼背後的資訊。完全沒有註釋的大段程式碼對於閱讀者形同 天書，註釋是給自己看的，即使隔很長時間，也能清晰理解當時的思路；註釋也是給繼任者看 的，使其能夠快速接替自己的工作。

  9. 【參考】好的命名、程式碼結構是自解釋的，註釋力求精簡準確、表達到位。避免出現註釋的 一個極端：過多過濫的註釋，程式碼的邏輯一旦修改，修改註釋是相當大的負擔。

  10. 【參考】特殊註釋標記，請註明標記人與標記時間。注意及時處理這些標記，通過標記掃描， 經常清理此類標記。線上故障有時候就是來源於這些標記處的程式碼。
    1） 待辦事宜（TODO）:（ 標記人，標記時間，[預計處理時間]） 表示需要實現，但目前還未實現的功能。這實際上是一個 Javadoc 的標籤，目前的 Javadoc 還沒有實現，但已經被廣泛使用。只能應用於類，介面和方法（因為它是一個 Javadoc 標籤）。
    2） 錯誤，不能工作（FIXME）:（標記人，標記時間，[預計處理時間]） 在註釋中用 FIXME 標記某程式碼是錯誤的，而且不能工作，需要及時糾正的情況。

八、其他

  1. 【強制】在使用正規表示式時，利用好其預編譯功能，可以有效加快正則匹配速度。 說明：不要在方法體內定義：Pattern pattern = Pattern.compile(規則);

  2. 【強制】注意 Math.random() 這個方法返回是 double 型別，注意取值的範圍 0≤x<1（能夠 取到零值，注意除零異常），如果想獲取整數型別的隨機數，不要將 x 放大 10 的若干倍然後 取整，直接使用 Random 物件的 nextInt 或者 nextLong 方法。

  3. 【強制】獲取當前毫秒數 System.currentTimeMillis(); 而不是 new Date().getTime();

  4. 【推薦】任何資料結構的構造或初始化，都應指定大小，避免資料結構無限增長吃光記憶體。

九、異常處理

  1. 【強制】捕獲異常是為了處理它，不要捕獲了卻什麼都不處理而拋棄之，如果不想處理它，請 將該異常拋給它的呼叫者。最外層的業務使用者，必須處理異常，將其轉化為使用者可以理解的 內容。

十、MySQL資料庫

建立表規約

  1. 【強制】表名、欄位名必須使用小寫字母或數字，禁止出現數字開頭，禁止兩個下劃線中間只 出現數字。資料庫欄位名的修改代價很大，因為無法進行預釋出，所以欄位名稱需要慎重考慮。
    說明：MySQL 在 Windows 下不區分大小寫，但在 Linux 下預設是區分大小寫。因此，資料庫 名、表名、欄位名，都不允許出現任何大寫字母，避免節外生枝。
    正例：aliyun_admin，rdc_config，level3_name 反例：AliyunAdmin，rdcConfig，level_3_name

  2. 【強制】禁用保留字，如 desc、range、match、delayed 等，請參考 MySQL 官方保留字。

  3. 【強制】主鍵索引名為 pk_欄位名；唯一索引名為 uk_欄位名；普通索引名則為 idx_欄位名。 說明：pk_ 即 primary key；uk_ 即 unique key；idx_ 即 index 的簡稱。

  4. 【強制】小數型別為 decimal，禁止使用 float 和 double。

  5. 【強制】如果儲存的字串長度幾乎相等，使用 char 定長字串型別。

  6. 【強制】varchar 是可變長字串，不預先分配儲存空間，長度不要超過 5000，如果儲存長度大於此值，定義欄位型別為 text。

  7. 【強制】表必備三個欄位：id，create_time, update_time, delete_flag

  8. 【強制】對於Boolean型的欄位，採用decimal型別

  9. 【強制】表和欄位都需要新增註釋資訊。

  10. 【推薦】單錶行數超過 500 萬行或者單表容量超過 2GB，才推薦進行分庫分表。 說明：如果預計三年後的資料量根本達不到這個級別，請不要在建立表時就分庫分表。

  11. 【參考】合適的字元儲存長度，不但節約資料庫表空間、節約索引儲存，更重要的是提升檢 索速度。

索引規約

  1. 【強制】業務上具有唯一特性的欄位，即使是多個欄位的組合，也必須建成唯一索引。
    說明：不要以為唯一索引影響了 insert 速度，這個速度損耗可以忽略，但提高查詢速度是明 顯的；另外，即使在應用層做了非常完善的校驗控制，只要沒有唯一索引，根據墨菲定律，必 然有髒資料產生。

  2. 【強制】超過三個表禁止 join。需要 join 的欄位，資料型別必須絕對一致；多表關聯查詢時， 保證被關聯的欄位需要有索引。
    說明：即使雙表 join 也要注意表索引、SQL 效能。

  3. 【強制】在 varchar 欄位上建立索引時，必須指定索引長度，沒必要對全欄位建立索引，根據 實際文字區分度決定索引長度即可。
    說明：索引的長度與區分度是一對矛盾體，一般對字串型別資料，長度為 20 的索引，區分度會高達 90%以上，可以使用 count(distinct left(列名, 索引長度))/count(*)的區分度 來確定。

  4. 【參考】建立索引時避免有如下極端誤解：
    1）寧濫勿缺。認為一個查詢就需要建一個索引。
    2）寧缺勿濫。認為索引會消耗空間、嚴重拖慢更新和新增速度。
    3）抵制惟一索引。認為業務的惟一性一律需要在應用層通過“先查後插”方式解決。

SQL語句

  1. 【強制】不要使用 count(列名)或 count(常量)來替代 count(*)，count(*)是 SQL92 定義的 標準統計行數的語法，跟資料庫無關，跟 NULL 和非 NULL 無關。
    說明：count(*)會統計值為 NULL 的行，而 count(列名)不會統計此列為 NULL 值的行。

  2. 【強制】count(distinct col) 計算該列除 NULL 之外的不重複行數，注意 count(di col1, col2) 如果其中一列全為 NULL，那麼即使另一列有不同的值，也返回為 0。

  3. 【強制】當某一列的值全是 NULL 時，count(col)的返回結果為 0，但 sum(col)的返回結果為NULL.

  4. 【強制】不得使用外來鍵與級聯，一切外來鍵概念必須在應用層解決。

  5. 【強制】禁止使用儲存過程，儲存過程難以除錯和擴充套件，更沒有移植性。

  6. 【推薦】in 操作能避免則避免，若實在避免不了，需要仔細評估 in 後邊的集合元素數量，控 制在 1000 個之內。

  7. 【參考】如果有全球化需要，所有的字元儲存與表示，均以 utf-8 編碼，注意字元 的區別。
    說明： SELECT LENGTH("輕鬆工作")； 返回為 12 SELECT CHARACTER_LENGTH("輕鬆工作")； 返回為 4 如果需要儲存表情，那麼選擇 utfmb4 來進行儲存，注意它與 -8 編碼的區別。

  8. 【強制】更新資料表記錄時，必須同時更新記錄對應的 update_time 欄位值為當前時間。

  9. 【參考】@Transactional 事務不要濫用。事務會影響資料庫的 QPS，另外使用事務的地方需 要考慮各方面的回滾方案，包括快取回滾、搜尋引擎回滾、訊息補償、統計修正等。

相關文章