2. 程式人生 > >阿里 java 開發手冊

阿里 java 開發手冊

阿新 • • 發佈：2019-01-11

本文引用阿里Java開發手冊。 
GitHub閱讀地址：Java程式設計規範

目錄

程式設計規約

命名規約

1、【強制】 所有程式設計相關命名均不能以下劃線或美元符號開始，也不能以下劃線或美元符號結束

　　反例：  _name / __name / $Object / name_ / name$ / Object$
  • 1
  • 1

2、【強制】 所有程式設計相關的命名嚴禁使用拼音與英語混合的方式，更不允許直接使用中的方式。

　　說明： 正確的英文拼寫和語法可以讓閱讀者易於理解，避免歧義。注意，即純拼音的命名方式也要避免採用。

　　反例： DaZhePromotion [打折] / getPingfenByName() [評分] / int 變數 = 3;

　　正例： ali / alibaba / taobao / cainiao / aliyun / youku / hangzhou 等國際通用的名稱，可視為英文。
  • 1
  • 2
  • 3
  • 4
  • 5
  • 1
  • 2
  • 3
  • 4
  • 5

3、【強制】 類名使用 UpperCamelCase 風格，必須遵從駝峰形式，但以下情形例外：（領域模型的相關命名） DO / DTO / VO / DAO 等。

　　正例： MarcoPolo / UserDO / XmlService / TcpUdpDeal / TaPromotion

　　反例： macroPolo / UserDo / XMLService / TCPUDPDeal / TAPromotion
  • 1
  • 2
  • 3
  • 1
  • 2
  • 3

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

　　正例： localValue / getHttpMessage() / inputUserId
  • 1
  • 1

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

　　正例： MAX_STOCK_COUNT

　　反例： MAX_COUNT
  • 1
  • 2
  • 3
  • 1
  • 2
  • 3

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

7、【強制】 中括號是陣列型別的一部分，陣列定義如下： String[] args ;

　　反例： 請勿使用 String args[] 的方式來定義
  • 1
  • 1

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

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

9、【強制】 包名統一使用小寫，點分隔符之間有且僅有一個自然語義的英語單詞。包名統一使用單數形式，但是類名如果有複數含義，類名可以使用複數形式。

　　正例： 應用工具類包名為 com.alibaba.mpp.util、類名為 MessageUtils （此規則參考 spring的框架結構）
  • 1
  • 1

10、【強制】 杜絕完全不規範的縮寫，避免望文不知義。

　　反例： <某業務程式碼>AbstractClass“ 縮寫” 命名成 AbsClass； condition“ 縮寫” 命名成condi，此類隨意縮寫嚴重降低了程式碼的可閱讀性。
  • 1
  • 1

11、【推薦】 如果使用到了設計模式，建議在類名中體現出具體模式。

　　說明： 將設計模式體現在名字中，有利於閱讀者快速理解架構設計思想。

　　正例： public class OrderFactory; public class LoginProxy; public class ResourceObserver;
  • 1
  • 2
  • 3
  • 1
  • 2
  • 3

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

　　正例： 介面方法簽名： void f(); 介面基礎常量表示： String COMPANY = "alibaba";

　　反例： 介面方法定義： public abstract void f();

　　說明： JDK8 中介面允許有預設實現，那麼這個 default 方法，是對所有實現類都有價值的預設實現。
  • 1
  • 2
  • 3
  • 4
  • 5
  • 1
  • 2
  • 3
  • 4
  • 5

13、介面和實現類的命名有兩套規則：

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

　　２）【推薦】 如果是形容能力的介面名稱，取對應的形容詞做介面名（通常是–able 的形式）。正例： AbstractTranslator 實現 Translatable。
  • 1
  • 2
  • 3
  • 1
  • 2
  • 3

14、【參考】 列舉類名建議帶上 Enum 字尾，列舉成員名稱需要全大寫，單詞間用下劃線隔開。

　　說明： 列舉其實就是特殊的常量類，且構造方法被預設強制是私有。

　　正例： 列舉名字： DealStatusEnum；成員名稱： SUCCESS / UNKOWN_REASON。
  • 1
  • 2
  • 3
  • 1
  • 2
  • 3

15、【參考】 各層命名規約：

　　A) Service/DAO 層方法命名規約

　　　　1） 獲取單個物件的方法用 get 做字首。

　　　　2） 獲取多個物件的方法用 list 做字首。

　　　　3） 獲取統計值的方法用 count 做字首。

　　　　4） 插入的方法用 save（推薦）或 insert 做字首。

　　　　5） 刪除的方法用 remove（推薦）或 delete 做字首。

　　　　6） 修改的方法用 update 做字首。

　　B) 領域模型命名規約

　　　　1） 資料物件： xxxDO， xxx 即為資料表名。

　　　　2） 資料傳輸物件： xxxDTO， xxx 為業務領域相關的名稱。

　　　　3） 展示物件： xxxVO， xxx 一般為網頁名稱。

　　　　4） POJO 是 DO/DTO/BO/VO 的統稱，禁止命名成 xxxPOJO。
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23

常量定義

1、【強制】 不允許出現任何魔法值（即未經定義的常量）直接出現在程式碼中。

　　反例： String key="Id#taobao_"+tradeId； cache.put(key, value);
  • 1
  • 1

2、【強制】 long 或者 Long 初始賦值時，必須使用大寫的 L，不能是小寫的 l，小寫容易跟數字 1混淆，造成誤解。

　　說明： Long a = 2l; 寫的是數字的 21，還是 Long 型的 2?
  • 1
  • 1

3、【推薦】 不要使用一個常量類維護所有常量，應該按常量功能進行歸類，分開維護。如：快取相關的常量放在類： CacheConsts 下；系統配置相關的常量放在類： ConfigConsts 下。

　　說明： 大而全的常量類，非得 ctrl+f 才定位到修改的常量，不利於理解，也不利於維護。
  • 1
  • 1

4、【推薦】 常量的複用層次有五層：跨應用共享常量、應用內共享常量、子工程內共享常量、包內共享常量、類內共享常量。

　　1） 跨應用共享常量：放置在二方庫中，通常是 client.jar 中的 const 目錄下。

　　2） 應用內共享常量：放置在一方庫的 modules 中的 const 目錄下。

　　反例： 易懂變數也要統一定義成應用內共享常量，兩位攻城師在兩個類中分別定義了表示“ 是” 的變數：

　　類 A 中： public static final String YES = "yes";

　　類 B 中： public static final String YES = "y";

　　A.YES.equals(B.YES)，預期是 true，但實際返回為 false，導致產生線上問題。
　　
　　3） 子工程內部共享常量：即在當前子工程的 const 目錄下。

　　4） 包內共享常量：即在當前包下單獨的 const 目錄下。

　　5） 類內共享常量：直接在類內部 private static final 定義。
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17

５、【推薦】 如果變數值僅在一個範圍內變化用 Enum 類。如果還帶有名稱之外的延伸屬性，必須使用 Enum 類，下面正例中的數字就是延伸資訊，表示星期幾。

　　正例： public Enum{ MONDAY(1), TUESDAY(2), WEDNESDAY(3), THURSDAY(4), FRIDAY(5),SATURDAY(6), SUNDAY(7);}
  • 1
  • 1

格式規範

1、【強制】 大括號的使用約定。如果是大括號內為空，則簡潔地寫成{}即可，不需要換行； 如果是非空程式碼塊則：

　　1） 左大括號前不換行。

　　2） 左大括號後換行。

　　3） 右大括號前換行。

　　4） 右大括號後還有 else 等程式碼則不換行； 表示終止右大括號後必須換行。
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7

2、【強制】 左括號和後一個字元之間不出現空格； 同樣，右括號和前一個字元之間也不出現空格。詳見第 5 條下方正例提示。

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

4、【強制】 任何運算子左右必須加一個空格。

　　說明： 運算子包括賦值運算子=、邏輯運算子&&、加減乘除符號、三目執行符等。
  • 1
  • 1

5、【強制】 縮排採用 4 個空格，禁止使用 tab 字元。