目錄
一、 編程規約................................................................................................................................................................................1
(一)命名規約................................................................................................................................................................1
(二)常量定義................................................................................................................................................................3
(三)格式規約................................................................................................................................................................4
(四) OOP規約................................................................................................................................................................6
(五)集合處理.............................................................................................................................................................10
(六)并發處理.............................................................................................................................................................12
(七)控制語句.............................................................................................................................................................15
(八)注釋規約.............................................................................................................................................................16
(九)其它.......................................................................................................................................................................17
二、異常日志.............................................................................................................................................................................19
(一)異常處理.............................................................................................................................................................19
(二)日志規約.............................................................................................................................................................20
三、MySQL規約.......................................................................................................................................................................22
(一)建表規約.............................................................................................................................................................22
(二)索引規約.............................................................................................................................................................23
(三) SQL規約.............................................................................................................................................................25
(四) ORM規約.............................................................................................................................................................26
四、工程規約.............................................................................................................................................................................27
(一)應用分層.............................................................................................................................................................27
(二)二方庫規約.........................................................................................................................................................28
(三)服務器規約.........................................................................................................................................................30
五、安全規約.............................................................................................................................................................................31
阿里巴巴Java開發手冊
——禁止用于商業用途，違者必究——1/34
Java開發手冊
1.0.0阿里巴巴集團技術團隊2017.2.9正式版
一、 編程規約
(一)命名規約
1.【強制】 代碼中的命名均不能以下劃線或美元符號開始，也不能以下劃線或美元符號結束。
反例：_name / __name / $Object / name_ / name$ / Object$
2.【強制】 代碼中的命名嚴禁使用拼音與英文混合的方式，更不允許直接使用中文的方式。
說明：正確的英文拼寫和語法可以讓閱讀者易于理解，避免歧義。注意，即使純拼音命名方式
也要避免采用。
反例：DaZhePromotion [打折]/getPingfenByName() [評分]/int某變量= 3
正例：alibaba/taobao/youku/hangzhou等國際通用的名稱， 可視同英文。
3.【強制】類名使用UpperCamelCase風格，必須遵從駝峰形式，但以下情形例外：（領域模型
的相關命名）DO/BO/DTO/VO等。
正例：MarcoPolo/UserDO/XmlService/TcpUdpDeal/TaPromotion
反例：macroPolo/UserDo/XMLService/TCPUDPDeal/TAPromotion
4.【強制】方法名、參數名、成員變量、局部變量都統一使用lowerCamelCase風格，必須遵從
駝峰形式。
正例：localValue/getHttpMessage()/inputUserId
5.【 強制】常量命名全部大寫，單詞間用下劃線隔開，力求語義表達完整清楚，不要嫌名字長。
正例：MAX_STOCK_COUNT
反例：MAX_COUNT
6.【強制】抽象類命名使用Abstract或Base開頭；異常類命名使用Exception結尾；測試類
命名以它要測試的類的名稱開始，以Test結尾。
7.【強制】中括號是數組類型的一部分，數組定義如下：String[]args;
反例：請勿使用String args[]的方式來定義。
阿里巴巴Java開發手冊
——禁止用于商業用途，違者必究——2/34
8.【強制】POJO類中布爾類型的變量，都不要加is，否則部分框架解析會引起序列化錯誤。
反例：定義為基本數據類型boolean isSuccess；的屬性，它的方法也是isSuccess()，RPC
框架在反向解析的時候，“以為”對應的屬性名稱是success，導致屬性獲取不到，進而拋出異
常。
9.【強制】包名統一使用小寫，點分隔符之間有且僅有一個自然語義的英語單詞。包名統一使用
單數形式，但是類名如果有復數含義，類名可以使用復數形式。
正例：應用工具類包名為com.alibaba.open.util、類名為MessageUtils（此規則參考
spring的框架結構）
10.【強制】杜絕完全不規范的縮寫， 避免望文不知義。
反例：AbstractClass“ 縮寫” 命名成AbsClass；condition“ 縮寫” 命名成condi，此類
隨意縮寫嚴重降低了代碼的可閱讀性。
11.【推薦】如果使用到了設計模式，建議在類名中體現出具體模式。
說明：將設計模式體現在名字中，有利于閱讀者快速理解架構設計思想。
正例：public class OrderFactory;
public class LoginProxy;
public class ResourceObserver;
12.【推薦】接口類中的方法和屬性不要加任何修飾符號（public也不要加），保持代碼的簡潔
性，并加上有效的Javadoc注釋。盡量不要在接口里定義變量，如果一定要定義變量，肯定是
與接口方法相關，并且是整個應用的基礎常量。
正例：接口方法簽名：void f();
接口基礎常量表示：String COMPANY= "alibaba";
反例：接口方法定義：public abstractvoid f();
說明：JDK8中接口允許有默認實現，那么這個default方法，是對所有實現類都有價值的默
認實現。
13.接口和實現類的命名有兩套規則：
1）【強制】對于Service和DAO類，基于SOA的理念，暴露出來的服務一定是接口，內部
的實現類用Impl的后綴與接口區別。
正例：CacheServiceImpl實現CacheService接口。
2）【推薦】 如果是形容能力的接口名稱，取對應的形容詞做接口名（通常是–able的形式）。
正例：AbstractTranslator實現Translatable。
14.【參考】枚舉類名建議帶上Enum后綴，枚舉成員名稱需要全大寫，單詞間用下劃線隔開。
說明：枚舉其實就是特殊的常量類，且構造方法被默認強制是私有。
正例：枚舉名字：DealStatusEnum，成員名稱：SUCCESS/UNKOWN_REASON。
阿里巴巴Java開發手冊
——禁止用于商業用途，違者必究——3/34
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.【強制】不允許出現任何魔法值（即未經定義的常量）直接出現在代碼中。
反例：String key="Id#taobao_"+tradeId；
cache.put(key,value);
2.【強制】long或者Long初始賦值時，必須使用大寫的L，不能是小寫的l，小寫容易跟數字
1混淆，造成誤解。
說明：Long a= 2l;寫的是數字的21，還是Long型的2?
3.【推薦】不要使用一個常量類維護所有常量，應該按常量功能進行歸類，分開維護。如：緩存
相關的常量放在類：CacheConsts下；系統配置相關的常量放在類：ConfigConsts下。
說明：大而全的常量類，非得使用查找功能才能定位到修改的常量，不利于理解和維護。
4.【推薦】常量的復用層次有五層：跨應用共享常量、應用內共享常量、子工程內共享常量、包
內共享常量、類內共享常量。
1）跨應用共享常量：放置在二方庫中，通常是client.jar中的constant目錄下。
2）應用內共享常量：放置在一方庫的modules中的constant目錄下。
反例：易懂變量也要統一定義成應用內共享常量，兩位攻城師在兩個類中分別定義 了
表示“是”的變量：
類A中：public static final String YES= "yes";
類B中：public static final String YES= "y";
A.YES.equals(B.YES)，預期是true，但實際返回為false，導致產生線上問題。
阿里巴巴Java開發手冊
——禁止用于商業用途，違者必究——4/34
3）子工程內部共享常量：即在當前子工程的constant目錄下。
4）包內共享常量：即在當前包下單獨的constant目錄下。
5）類內共享常量：直接在類內部private static final定義。
5.【推薦】如果變量值僅在一個范圍內變化用Enum類。如果還帶有名稱之外的延伸屬性，必須
使用Enum類，下面正例中的數字就是延伸信息，表示星期幾。
正例：public Enum{MONDAY(1),TUESDAY(2),WEDNESDAY(3),THURSDAY(4),FRIDAY(5),
SATURDAY(6),SUNDAY(7);}
(三)格式規約
1.【強制】大括號的使用約定。如果是大括號內為空，則簡潔地寫成{}即可，不需要換行；如果
是非空代碼塊則：
1）左大括號前不換行。
2）左大括號后換行。
3）右大括號前換行。
4）右大括號后還有else等代碼則不換行；表示終止右大括號后必須換行。
2.【強制】 左括號和后一個字符之間不出現空格；同樣，右括號和前一個字符之間也不出現空
格。詳見第5條下方正例提示。
3.【強制】if/for/while/switch/do等保留字與左右括號之間都必須加空格。
4.【強制】任何運算符左右必須加一個空格。
說明：運算符包括賦值運算符=、邏輯運算符&&、加減乘除符號、三目運行符等。
5.【強制】 縮進采用4個空格，禁止使用tab字符。
說明：如果使用tab縮進，必須設置1個tab為4個空格。IDEA設置tab為4個空格時，
請勿勾選Use tab character；而在eclipse中，必須勾選insert spaces for tabs。
正例：（涉及1-5點）
public static void main(String args[]) {
//縮進4個空格
String say = "hello";
//運算符的左右必須有一個空格
int flag = 0;
//關鍵詞if與括號之間必須有一個空格，括號內的f與左括號，0與右括號不需要空格
if (flag == 0) {
System.out.println(say);
}
//左大括號前加空格且不換行；左大括號后換行
if (flag == 1) {
System.out.println("world");
//右大括號前換行，右大括號后有else，不用換行
阿里巴巴Java開發手冊
——禁止用于商業用途，違者必究——5/34
} else {
System.out.println("ok");
//在右大括號后直接結束，則必須換行
}
}
6.【強制】單行字符數限制不超過120個，超出需要換行，換行時遵循如下原則：
1） 第二行相對第一行縮進4個空格，從第三行開始，不再繼續縮進，參考示例。
2）運算符與下文一起換行。
3）方法調用的點符號與下文一起換行。
4）在多個參數超長，逗號后進行換行。
5）在括號前不要換行，見反例。
正例：
StringBuffer sb = new StringBuffer();
//超過120個字符的情況下，換行縮進4個空格，并且方法前的點符號一起換行
sb.append("zi").append("xin")...
.append("huang")...
.append("huang")...
.append("huang");
反例：
StringBuffer sb = new StringBuffer();
//超過120個字符的情況下，不要在括號前換行
sb.append("zi").append("xin")...append
("huang");
//參數很多的方法調用可能超過120個字符， 不要在逗號前換行
method(args1, args2, args3, ...
, argsX);
7.【強制】方法參數在定義和傳入時，多個參數逗號后邊必須加空格。
正例：下例中實參的"a",后邊必須要有一個空格。
method("a", "b", "c");
8.【強制】IDE的text file encoding設置為UTF-8; IDE中文件的換行符使用Unix格式，
不要使用windows格式。
9.【推薦】沒有必要增加若干空格來使某一行的字符與上一行的相應字符對齊。
正例：
int a = 3;
long b = 4L;
float c = 5F;
StringBuffer sb = new StringBuffer();
說明：增加sb這個變量，如果需要對齊，則給a、b、c都要增加幾個空格，在變量比較多的
情況下，是一種累贅的事情。
阿里巴巴Java開發手冊
——禁止用于商業用途，違者必究——6/34
10.【推薦】方法體內的執行語句組、變量的定義語句組、不同的業務邏輯之間或者不同的語義
之間插入一個空行。相同業務邏輯和語義之間不需要插入空行。
說明：沒有必要插入多行空格進行隔開。
(四)OOP規約
1.【強制】避免通過一個類的對象引用訪問此類的靜態變量或靜態方法，無謂增加編譯器解析成
本，直接用類名來訪問即可。
2.【強制】所有的覆寫方法，必須加@Override注解。
反例：getObject()與get0bject()的問題。一個是字母的O，一個是數字的0，加@Override
可以準確判斷是否覆蓋成功。另外，如果在抽象類中對方法簽名進行修改，其實現類會馬上編
譯報錯。
3.【強制】相同參數類型，相同業務含義，才可以使用Java的可變參數，避免使用Object。
說明：可變參數必須放置在參數列表的最后。（提倡同學們盡量不用可變參數編程）
正例：public User getUsers(String type, Integer... ids)
4.【強制】對外暴露的接口簽名，原則上不允許修改方法簽名，避免對接口調用方產生影響。接
口過時必須加@Deprecated注解，并清晰地說明采用的新接口或者新服務是什么。
5.【強制】不能使用過時的類或方法。
說明：java.net.URLDecoder中的方法decode(String encodeStr)這個方法已經過時，應
該使用雙參數decode(String source, String encode)。接口提供方既然明確是過時接口，
那么有義務同時提供新的接口；作為調用方來說，有義務去考證過時方法的新實現是什么。
6.【強制】Object的equals方法容易拋空指針異常，應使用常量或確定有值的對象來調用
equals。
正例："test".equals(object);
反例：object.equals("test");
說明：推薦使用java.util.Objects#equals（JDK7引入的工具類）
7.【強制】所有的相同類型的包裝類對象之間值的比較，全部使用equals方法比較。
說明：對于Integer var=?在-128至127之間的賦值，Integer對象是在
IntegerCache.cache產生，會復用已有對象，這個區間內的Integer值可以直接使用==進行
判斷，但是這個區間之外的所有數據，都會在堆上產生，并不會復用已有對象，這是一個大坑，
推薦使用equals方法進行判斷。
阿里巴巴Java開發手冊
——禁止用于商業用途，違者必究——7/34
8.【強制】關于基本數據類型與包裝數據類型的使用標準如下：
1）所有的POJO類屬性必須使用包裝數據類型。
2）RPC方法的返回值和參數必須使用包裝數據類型。
3）所有的局部變量【 推薦】 使用基本數據類型。
說明：POJO類屬性沒有初值是提醒使用者在需要使用時，必須自己顯式地進行賦值，任何
NPE問題，或者入庫檢查，都由使用者來保證。
正例：數據庫的查詢結果可能是null，因為自動拆箱，用基本數據類型接收有NPE風險。
反例：比如顯示成交總額漲跌情況，即正負x%，x為基本數據類型，調用的RPC服務，調用
不成功時，返回的是默認值，頁面顯示：0%，這是不合理的，應該顯示成中劃線-。所以包裝
數據類型的null值，能夠表示額外的信息， 如：遠程調用失敗，異常退出。
9.【強制】定義DO/DTO/VO等POJO類時，不要設定任何屬性默認值。
反例：POJO類的gmtCreate默認值為new Date();但是這個屬性在數據提取時并沒有置入具
體值，在更新其它字段時又附帶更新了此字段，導致創建時間被修改成當前時間。
10.【強制】序列化類新增屬性時，請不要修改serialVersionUID字段，避免反序列失敗；如
果完全不兼容升級，避免反序列化混亂，那么請修改serialVersionUID值。
說明：注意serialVersionUID不一致會拋出序列化運行時異常。
11.【強制】構造方法里面禁止加入任何業務邏輯，如果有初始化邏輯，請放在init方法中。
12.【強制】POJO類必須寫toString方法。使用IDE的中工具：source>generate toString
時，如果繼承了另一個POJO類，注意在前面加一下super.toString。
說明：在方法執行拋出異常時，可以直接調用POJO的toString()方法打印其屬性值，便于排
查問題。
13.【推薦】使用索引訪問用String的split方法得到的數組時，需做最后一個分隔符后有無
內容的檢查，否則會有拋IndexOutOfBoundsException的風險。
說明：
String str = "a,b,c,,";
String[] ary = str.split(",");
//預期大于3，結果是3
System.out.println(ary.length);
14.【推薦】當一個類有多個構造方法，或者多個同名方法，這些方法應該按順序放置在一起，
便于閱讀。
阿里巴巴Java開發手冊
——禁止用于商業用途，違者必究——8/34
15.【推薦】 類內方法定義順序依次是：公有方法或保護方法>私有方法>getter/setter
方法。
說明：公有方法是類的調用者和維護者最關心的方法，首屏展示最好；保護方法雖然只是子類
關心，也可能是“模板設計模式”下的核心方法；而私有方法外部一般不需要特別關心，是一個
黑盒實現；因為方法信息價值較低，所有Service和DAO的getter/setter方法放在類體最
后。
16.【推薦】setter方法中，參數名稱與類成員變量名稱一致，this.成員名=參數名。在
getter/setter方法中，盡量不要增加業務邏輯，增加排查問題的難度。
反例：
public Integer getData(){
if(true) {
return data + 100;
} else {
return data - 100;
}
}
17.【推薦】循環體內，字符串的聯接方式，使用StringBuilder的append方法進行擴展。
反例：
String str = "start";
for(int i=0; i<100; i++){
str = str + "hello";
}
說明：反編譯出的字節碼文件顯示每次循環都會new出一個StringBuilder對象，然后進行
append操作，最后通過toString方法返回String對象，造成內存資源浪費。
18.【推薦】final可提高程序響應效率，聲明成final的情況：
1）不需要重新賦值的變量，包括類屬性、局部變量。
2）對象參數前加final，表示不允許修改引用的指向。
3）類方法確定不允許被重寫。
19.【推薦】慎用Object的clone方法來拷貝對象。
說明：對象的clone方法默認是淺拷貝，若想實現深拷貝需要重寫clone方法實現屬性對象
的拷貝。
阿里巴巴Java開發手冊
——禁止用于商業用途，違者必究——9/34
20.【推薦】類成員與方法訪問控制從嚴：
1）如果不允許外部直接通過new來創建對象，那么構造方法必須是private。
2）工具類不允許有public或default構造方法。
3）類非static成員變量并且與子類共享，必須是protected。
4）類非static成員變量并且僅在本類使用，必須是private。
5）類static成員變量如果僅在本類使用，必須是private。
6）若是static成員變量，必須考慮是否為final。
7）類成員方法只供類內部調用，必須是private。
8）類成員方法只對繼承類公開，那么限制為protected。
說明：任何類、方法、參數、變量，嚴控訪問范圍。過寬泛的訪問范圍，不利于模塊解耦。思
考：如果是一個private的方法，想刪除就刪除，可是一個public的Service方法，或者一
個public的成員變量，刪除一下，不得手心冒點汗嗎？變量像自己的小孩，盡量在自己的視
線內，變量作用域太大，如果無限制的到處跑，那么你會擔心的。
阿里巴巴Java開發手冊
——禁止用于商業用途，違者必究——10/34
(五)集合處理
1.【強制】 關于hashCode和equals的處理，遵循如下規則：
1） 只要重寫equals，就必須重寫hashCode。
2） 因為Set存儲的是不重復的對象，依據hashCode和equals進行判斷，所以Set存儲的
對象必須重寫這兩個方法。
3） 如果自定義對象做為Map的鍵，那么必須重寫hashCode和equals。
正例：String重寫了hashCode和equals方法，所以我們可以非常愉快地使用String對象
作為key來使用。
2.【強制】ArrayList的subList結果不可強轉成ArrayList，否則會拋出ClassCastException
異常：java.util.RandomAccessSubList cannot be cast to java.util.ArrayList ;
說明：subList返回的是ArrayList的內部類SubList，并不是ArrayList，而是
ArrayList的一個視圖，對于SubList子列表的所有操作最終會反映到原列表上。
3.【強制】 在subList場景中，高度注意對原集合元素個數的修改，會導致子列表的遍歷、增
加、刪除均產生ConcurrentModificationException異常。
4.【強制】使用集合轉數組的方法，必須使用集合的toArray(T[] array)，傳入的是類型完全
一樣的數組，大小就是list.size()。
反例：直接使用toArray無參方法存在問題，此方法返回值只能是Object[]類，若強轉其它
類型數組將出現ClassCastException錯誤。
正例：
List list = new ArrayList(2);
list.add("guan");
list.add("bao");
String[] array = new String[list.size()];
array = list.toArray(array);
說明：使用toArray帶參方法，入參分配的數組空間不夠大時，toArray方法內部將重新分配
內存空間，并返回新數組地址；如果數組元素大于實際所需，下標為[ list.size() ]的數組
元素將被置為null，其它數組元素保持原值，因此最好將方法入參數組大小定義與集合元素
個數一致。
5.【強制】使用工具類Arrays.asList()把數組轉換成集合時，不能使用其修改集合相關的方
法，它的add/remove/clear方法會拋出UnsupportedOperationException異常。
說明：asList的返回對象是一個Arrays內部類，并沒有實現集合的修改方法。Arrays.asList
體現的是適配器模式，只是轉換接口，后臺的數據仍是數組。
String[] str = new String[] { "a", "b" };
List list = Arrays.asList(str);
第一種情況：list.add("c");運行時異常。
第二種情況：str[0]= "gujin";那么list.get(0)也會隨之修改。
阿里巴巴Java開發手冊
——禁止用于商業用途，違者必究——11/34
6.【強制】泛型通配符來接收返回的數據，此寫法的泛型集合不能使用add方
法。
說明：蘋果裝箱后返回一個對象，此對象就不能往里加任何水果，包括
蘋果。
7.【強制】不要在foreach循環里進行元素的remove/add操作。remove元素請使用Iterator
方式，如果并發操作，需要對Iterator對象加鎖。
反例：
List a = new ArrayList();
a.add("1");
a.add("2");
for (String temp : a) {
if("1".equals(temp)){
a.remove(temp);
}
}
說明：以上代碼的執行結果肯定會出乎大家的意料，那么試一下把“1”換成“2”，會是同樣的
結果嗎？
正例：
Iterator it = a.iterator();
while(it.hasNext()){
String temp = it.next();
if(刪除元素的條件){
it.remove();
}
}
8.【強制】 在JDK7版本以上，Comparator要滿足自反性，傳遞性，對稱性，不然Arrays.sort，
Collections.sort會報IllegalArgumentException異常。
說明：
1）自反性：x，y的比較結果和y，x的比較結果相反。
2）傳遞性：x>y,y>z,則x>z。
3）對稱性：x=y,則x,z比較結果和y，z比較結果相同。
反例：下例中沒有處理相等的情況，實際使用中可能會出現異常：
new Comparator() {
@Override
public int compare(Student o1, Student o2) {
return o1.getId() > o2.getId() ? 1 : -1;
}
}
阿里巴巴Java開發手冊
——禁止用于商業用途，違者必究——12/34
9.【推薦】集合初始化時，盡量指定集合初始值大小。
說明：ArrayList盡量使用ArrayList(int initialCapacity)初始化。
10.【推薦】使用entrySet遍歷Map類集合KV，而不是keySet方式進行遍歷。
說明：keySet其實是遍歷了2次，一次是轉為Iterator對象，另一次是從hashMap中取出
key所對應的value。而entrySet只是遍歷了一次就把key和value都放到了entry中，效
率更高。如果是JDK8，使用Map.foreach方法。
正例：values()返回的是V值集合，是一個list集合對象；keySet()返回的是K值集合，是
一個Set集合對象；entrySet()返回的是K-V值組合集合。
11.【推薦】高度注意Map類集合K/V能不能存儲null值的情況，如下表格：
Hashtable不允許為null不允許為nullDictionary線程安全
ConcurrentHashMap不允許為null不允許為nullAbstractMap分段鎖技術
TreeMap不允許為null允許為nullAbstractMap線程不安全
HashMap允許為null允許為nullAbstractMap線程不安全
反例：由于HashMap的干擾，很多人認為ConcurrentHashMap是可以置入null值，注意存儲
null值時會拋出NPE異常。
12.【參考】合理利用好集合的有序性(sort)和穩定性(order)，避免集合的無序性(unsort)和
不穩定性(unorder)帶來的負面影響。
說明：穩定性指集合每次遍歷的元素次序是一定的。有序性是指遍歷的結果是按某種比較規則
依次排列的。如：ArrayList是order/unsort；HashMap是unorder/unsort；TreeSet是
order/sort。
13.【參考】利用Set元素唯一的特性，可以快速對一個集合進行去重操作，避免使用List的
contains方法進行遍歷、對比、 去重操作。
(六)并發處理
1.【強制】 獲取單例對象需要保證線程安全，其中的方法也要保證線程安全。
說明：資源驅動類、工具類、單例工廠類都需要注意。
2.【強制】創建線程或線程池時請指定有意義的線程名稱，方便出錯時回溯。
正例：
public class TimerTaskThread extends Thread {
public TimerTaskThread(){
super.setName("TimerTaskThread"); ...
}
阿里巴巴Java開發手冊
——禁止用于商業用途，違者必究——13/34
3.【強制】線程資源必須通過線程池提供，不允許在應用中自行顯式創建線程。
說明：使用線程池的好處是減少在創建和銷毀線程上所花的時間以及系統資源的開銷，解決資
源不足的問題。如果不使用線程池，有可能造成系統創建大量同類線程而導致消耗完內存或者
“過度切換”的問題。
4.【強制】線程池不允許使用Executors去創建，而是通過ThreadPoolExecutor的方式，這樣
的處理方式讓寫的同學更加明確線程池的運行規則，規避資源耗盡的風險。
說明：Executors返回的線程池對象的弊端如下：
1）FixedThreadPool和SingleThreadPool:
允許的請求隊列長度為Integer.MAX_VALUE，可能會堆積大量的請求，從而導致OOM。
2）CachedThreadPool和ScheduledThreadPool:
允許的創建線程數量為Integer.MAX_VALUE， 可能會創建大量的線程，從而導致OOM。
5.【強制】SimpleDateFormat是線程不安全的類，一般不要定義為static變量，如果定義為
static，必須加鎖，或者使用DateUtils工具類。
正例：注意線程安全，使用DateUtils。亦推薦如下處理：
private static final ThreadLocal df = new ThreadLocal() {
@Override
protected DateFormat initialValue() {
return new SimpleDateFormat("yyyy-MM-dd");
}
};
說明：如果是JDK8的應用，可以使用Instant代替Date，LocalDateTime代替Calendar，
DateTimeFormatter代替Simpledateformatter，官方給出的解釋：simple beautiful strong
immutable thread-safe。
6.【強制】高并發時，同步調用應該去考量鎖的性能損耗。能用無鎖數據結構，就不要用鎖；能
鎖區塊，就不要鎖整個方法體；能用對象鎖，就不要用類鎖。
7.【強制】對多個資源、數據庫表、對象同時加鎖時，需要保持一致的加鎖順序，否則可能會造
成死鎖。
說明：線程一需要對表A、B、C依次全部加鎖后才可以進行更新操作，那么線程二的加鎖順序
也必須是A、B、C，否則可能出現死鎖。
8.【強制】并發修改同一記錄時，避免更新丟失，要么在應用層加鎖，要么在緩存加鎖，要么在
數據庫層使用樂觀鎖，使用version作為更新依據。
說明：如果每次訪問沖突概率小于20%，推薦使用樂觀鎖，否則使用悲觀鎖。樂觀鎖的重試次
數不得小于3次。
9.【強制】多線程并行處理定時任務時，Timer運行多個TimeTask時，只要其中之一沒有捕獲
拋出的異常，其它任務便會自動終止運行，使用ScheduledExecutorService則沒有這個問題。
阿里巴巴Java開發手冊
——禁止用于商業用途，違者必究——14/34
10.【推薦】使用CountDownLatch進行異步轉同步操作，每個線程退出前必須調用countDown
方法，線程執行代碼注意catch異常，確保countDown方法可以執行，避免主線程無法執行
至countDown方法，直到超時才返回結果。
說明：注意，子線程拋出異常堆棧，不能在主線程try-catch到。
11.【推薦】避免Random實例被多線程使用，雖然共享該實例是線程安全的，但會因競爭同一
seed導致的性能下降。
說明：Random實例包括java.util.Random的實例或者Math.random()實例。
正例：在JDK7之后，可以直接使用API ThreadLocalRandom，在JDK7之前，可以做到每個
線程一個實例。
12.【推薦】通過雙重檢查鎖（double-checked locking）（在并發場景）實現延遲初始化的優
化問題隱患(可參考The"Double-Checked Locking is Broken"Declaration),推薦問題
解決方案中較為簡單一種（適用于JDK5及以上版本），將目標屬性聲明為volatile型。
反例：
class Foo {
private Helper helper = null;
public Helper getHelper() {
if (helper == null) synchronized(this) {
if (helper == null)
helper = new Helper();
}
return helper;
}
// other functions and members...
}
13.【參考】volatile解決多線程內存不可見問題。對于一寫多讀，是可以解決變量同步問題，
但是如果多寫，同樣無法解決線程安全問題。如果是count++操作，使用如下類實現：
AtomicInteger count=new AtomicInteger(); count.addAndGet(1);如果是JDK8，推
薦使用LongAdder對象，比AtomicLong性能更好（減少樂觀鎖的重試次數）。
14.【參考】HashMap在容量不夠進行resize時由于高并發可能出現死鏈，導致CPU飆升，在
開發過程中注意規避此風險。
15.【參考】ThreadLocal無法解決共享對象的更新問題，ThreadLocal對象建議使用static
修飾。這個變量是針對一個線程內所有操作共有的，所以設置為靜態變量，所有此類實例共享
此靜態變量 ，也就是說在類第一次被使用時裝載，只分配一塊存儲空間，所有此類的對象(只
要是這個線程內定義的)都可以操控這個變量。
阿里巴巴Java開發手冊
——禁止用于商業用途，違者必究——15/34
(七)控制語句
1.【強制】在一個switch塊內，每個case要么通過break/return等來終止，要么注釋說明程
序將繼續執行到哪一個case為止；在一個switch塊內，都必須包含一個default語句并且
放在最后，即使它什么代碼也沒有。
2.【強制】在if/else/for/while/do語句中必須使用大括號，即使只有一行代碼，避免使用
下面的形式：if (condition) statements;
3.【推薦】推薦盡量少用else，if-else的方式可以改寫成：
if(condition){
...
return obj;
}
//接著寫else的業務邏輯代碼;
說明：如果非得使用if()...else if()...else...方式表達邏輯，【強制】請勿超過3層，
超過請使用狀態設計模式。
正例：邏輯上超過3層的if-else代碼可以使用衛語句，或者狀態模式來實現。
4.【推薦】除常用方法（如getXxx/isXxx）等外，不要在條件判斷中執行其它復雜的語句，將復
雜邏輯判斷的結果賦值給一個有意義的布爾變量名，以提高可讀性。
說明：很多if語句內的邏輯相當復雜，閱讀者需要分析條件表達式的最終結果，才能明確什么
樣的條件執行什么樣的語句，那么，如果閱讀者分析邏輯表達式錯誤呢？
正例：
//偽代碼如下
boolean existed = (file.open(fileName, "w") != null)&&(...) || (...);
if (existed) {
...
}
反例：
if ((file.open(fileName, "w") != null)&&(...) || (...)) {
...
}
5.【推薦】循環體中的語句要考量性能，以下操作盡量移至循環體外處理，如定義對象、變量、
獲取數據庫連接，進行不必要的try-catch操作（這個try-catch是否可以移至循環體外）。
6.【推薦】接口入參保護，這種場景常見的是用于做批量操作的接口。
7.【參考】方法中需要進行參數校驗的場景：
1）調用頻次低的方法。
2）執行時間開銷很大的方法，參數校驗時間幾乎可以忽略不計，但如果因為參數錯誤導致
中間執行回退，或者錯誤，那得不償失。
阿里巴巴Java開發手冊
——禁止用于商業用途，違者必究——16/34
3）需要極高穩定性和可用性的方法。
4）對外提供的開放接口，不管是RPC/API/HTTP接口。
5） 敏感權限入口。
8.【 參考】方法中不需要參數校驗的場景：
1）極有可能被循環調用的方法，不建議對參數進行校驗。但在方法說明里必須注明外部參
數檢查。
2）底層的方法調用頻度都比較高，一般不校驗。畢竟是像純凈水過濾的最后一道，參數錯
誤不太可能到底層才會暴露問題。一般DAO層與Service層都在同一個應用中，部署在同一
臺服務器中，所以DAO的參數校驗，可以省略。
3）被聲明成private只會被自己代碼所調用的方法，如果能夠確定調用方法的代碼傳入參
數已經做過檢查或者肯定不會有問題，此時可以不校驗參數。
(八)注釋規約
1.【強制】 類、類屬性、類方法的注釋必須使用Javadoc規范，使用/**內容*/格式，不得使用
//xxx方式。
說明：在IDE編輯窗口中，Javadoc方式會提示相關注釋，生成Javadoc可以正確輸出相應注
釋；在IDE中，工程調用方法時，不進入方法即可懸浮提示方法、參數、返回值的意義，提高
閱讀效率。
2.【強制】所有的抽象方法（包括接口中的方法）必須要用Javadoc注釋、除了返回值、參數、
異常說明外，還必須指出該方法做什么事情，實現什么功能。
說明：對子類的實現要求，或者調用注意事項，請一并說明。
3.【強制】所有的類都必須添加創建者信息。
4.【強制】方法內部單行注釋，在被注釋語句上方另起一行，使用//注釋。方法內部多行注釋
使用/* */注釋，注意與代碼對齊。
5.【強制】所有的枚舉類型字段必須要有注釋，說明每個數據項的用途。
6.【推薦】與其“半吊子”英文來注釋，不如用中文注釋把問題說清楚。專有名詞與關鍵字保持
英文原文即可。
反例：“TCP連接超時”解釋成“傳輸控制協議連接超時”，理解反而費腦筋。
7.【推薦】代碼修改的同時，注釋也要進行相應的修改，尤其是參數、返回值、異常、核心邏輯
等的修改。
說明：代碼與注釋更新不同步，就像路網與導航軟件更新不同步一樣，如果導航軟件嚴重滯后，
就失去了導航的意義。
阿里巴巴Java開發手冊
——禁止用于商業用途，違者必究——17/34
8.【參考】注釋掉的代碼盡量要配合說明，而不是簡單的注釋掉。
說明：代碼被注釋掉有兩種可能性：1）后續會恢復此段代碼邏輯。2）永久不用。前者如果沒
有備注信息，難以知曉注釋動機。后者建議直接刪掉（代碼倉庫保存了歷史代碼）。
9.【參考】對于注釋的要求：第一、能夠準確反應設計思想和代碼邏輯；第二、能夠描述業務含
義，使別的程序員能夠迅速了解到代碼背后的信息。完全沒有注釋的大段代碼對于閱讀者形同
天書，注釋是給自己看的，即使隔很長時間，也能清晰理解當時的思路；注釋也是給繼任者看
的，使其能夠快速接替自己的工作。
10.【參考】好的命名、代碼結構是自解釋的，注釋力求精簡準確、表達到位。避免出現注釋的
一個極端：過多過濫的注釋，代碼的邏輯一旦修改，修改注釋是相當大的負擔。
反例：
// put elephant into fridge
put(elephant, fridge);
方法名put，加上兩個有意義的變量名elephant和fridge，已經說明了這是在干什么，語
義清晰的代碼不需要額外的注釋。
11.【參考】特殊注釋標記，請注明標記人與標記時間。注意及時處理這些標記，通過標記掃描，
經常清理此類標記。線上故障有時候就是來源于這些標記處的代碼。
1）待辦事宜（TODO）:（標記人，標記時間，[預計處理時間]）
表示需要實現，但目前還未實現的功能。這實際上是一個Javadoc的標簽，目前的Javadoc
還沒有實現，但已經被廣泛使用。只能應用于類，接口和方法（因為它是一個Javadoc標簽）。
2）錯誤，不能工作（FIXME）:（標記人，標記時間，[預計處理時間]）
在注釋中用FIXME標記某代碼是錯誤的，而且不能工作，需要及時糾正的情況。
(九)其它
1.【強制】在使用正則表達式時，利用好其預編譯功能，可以有效加快正則匹配速度。
說明：不要在方法體內定義：Pattern pattern=Pattern.compile(規則);
2.【強制】velocity調用POJO類的屬性時，建議直接使用屬性名取值即可，模板引擎會自動按
規范調用POJO的getXxx()，如果是boolean基本數據類型變量（boolean命名不需要加is
前綴），會自動調用isXxx()方法。
說明：注意如果是Boolean包裝類對象，優先調用getXxx()的方法。
3.【強制】后臺輸送給頁面的變量必須加$!{var}——中間的感嘆號。
說明：如果var=null或者不存在，那么${var}會直接顯示在頁面上。
4.【強制】注意Math.random()這個方法返回是double類型，注意取值的范圍0≤x<1（能夠
取到零值，注意除零異常），如果想獲取整數類型的隨機數，不要將x放大10的若干倍然后
取整，直接使用Random對象的nextInt或者nextLong方法。
阿里巴巴Java開發手冊
——禁止用于商業用途，違者必究——18/34
5.【強制】獲取當前毫秒數System.currentTimeMillis();而不是new Date().getTime();
說明：如果想獲取更加精確的納秒級時間值，用System.nanoTime()。在JDK8中，針對統計
時間等場景，推薦使用Instant類。
6.【推薦】盡量不要在vm中加入變量聲明、邏輯運算符，更不要在vm模板中加入任何復雜的邏
輯。
7.【推薦】 任何數據結構的構造或初始化，都應指定大小，避免數據結構無限增長吃光內存。
8.【推薦】對于“明確停止使用的代碼和配置”，如方法、變量、類、配置文件、動態配置屬性
等要堅決從程序中清理出去，避免造成過多垃圾。
阿里巴巴Java開發手冊
——禁止用于商業用途，違者必究——19/34
二、異常日志
(一)異常處理
1.【強制】不要捕獲Java類庫中定義的繼承自RuntimeException的運行時異常類，如：
IndexOutOfBoundsException / NullPointerException，這類異常由程序員預檢查
來規避，保證程序健壯性。
正例：if(obj != null) {...}
反例：try { obj.method() } catch(NullPointerException e){...}
2.【強制】異常不要用來做流程控制，條件控制，因為異常的處理效率比條件分支低。
3.【強制】對大段代碼進行try-catch，這是不負責任的表現。catch時請分清穩定代碼和非穩
定代碼，穩定代碼指的是無論如何不會出錯的代碼。對于非穩定代碼的catch盡可能進行區分
異常類型，再做對應的異常處理。
4.【強制】捕獲異常是為了處理它，不要捕獲了卻什么都不處理而拋棄之，如果不想處理它，請
將該異常拋給它的調用者。最外層的業務使用者，必須處理異常，將其轉化為用戶可以理解的
內容。
5.【強制】有try塊放到了事務代碼中，catch異常后，如果需要回滾事務，一定要注意手動回
滾事務。
6.【強制】finally塊必須對資源對象、流對象進行關閉，有異常也要做try-catch。
說明：如果JDK7，可以使用try-with-resources方式。
7.【強制】不能在finally塊中使用return，finally塊中的return返回后方法結束執行，不
會再執行try塊中的return語句。
8.【強制】捕獲異常與拋異常，必須是完全匹配，或者捕獲異常是拋異常的父類。
說明：如果預期對方拋的是繡球，實際接到的是鉛球，就會產生意外情況。
9.【推薦】方法的返回值可以為null，不強制返回空集合，或者空對象等，必須添加注釋充分
說明什么情況下會返回null值。調用方需要進行null判斷防止NPE問題。
說明：本規約明確防止NPE是調用者的責任。即使被調用方法返回空集合或者空對象，對調用
者來說，也并非高枕無憂，必須考慮到遠程調用失敗，運行時異常等場景返回null的情況。
10.【推薦】防止NPE，是程序員的基本修養，注意NPE產生的場景：
1）返回類型為包裝數據類型，有可能是null，返回int值時注意判空。
反例：public int f(){return Integer對象};如果為null，自動解箱拋NPE。
2）數據庫的查詢結果可能為null。
3）集合里的元素即使isNotEmpty，取出的數據元素也可能為null。
阿里巴巴Java開發手冊
——禁止用于商業用途，違者必究——20/34
4）遠程調用返回對象，一律要求進行NPE判斷。
5）對于Session中獲取的數據，建議NPE檢查，避免空指針。
6）級聯調用obj.getA().getB().getC()；一連串調用，易產生NPE。
11.【推薦】在代碼中使用“拋異常”還是“返回錯誤碼”，對于公司外的http/api開放接口必須
使用“錯誤碼”；而應用內部推薦異常拋出；跨應用間RPC調用優先考慮使用Result方式，封
裝isSuccess、“錯誤碼”、“錯誤簡短信息”。
說明：關于RPC方法返回方式使用Result方式的理由：
1）使用拋異常返回方式，調用方如果沒有捕獲到就會產生運行時錯誤。
2）如果不加棧信息，只是new自定義異常，加入自己的理解的error message，對于調用
端解決問題的幫助不會太多。如果加了棧信息，在頻繁調用出錯的情況下，數據序列化和傳輸
的性能損耗也是問題。
12.【推薦】定義時區分unchecked/checked異常，避免直接使用RuntimeException拋出，
更不允許拋出Exception或者Throwable，應使用有業務含義的自定義異常。推薦業界已定義
過的自定義異常，如：DAOException/ServiceException等。
13.【參考】避免出現重復的代碼（Don’t Repeat Yourself），即DRY原則。
說明：隨意復制和粘貼代碼，必然會導致代碼的重復，在以后需要修改時，需要修改所有的副
本，容易遺漏。必要時抽取共性方法，或者抽象公共類，甚至是共用模塊。
正例：一個類中有多個public方法，都需要進行數行相同的參數校驗操作，這個時候請抽取：
private boolean checkParam(DTO dto){...}
