一、編程規約

(一) 命名風格

1. 【強制】代碼中的命名均不能以下劃線或美元符號開始，也不能以下劃線或美元符號結束。

反例：_name / __name / $name / name_ / name$ / name__

2. 【強制】代碼中的命名嚴禁使用拼音與英文混合的方式，更不允許直接使用中文的方式。說明：正確的英文拼寫和語法可以讓閱讀者易于理解，避免歧義。注意，即使純拼音命名方式也要避免采用。正例：alibaba / taobao / youku / hangzhou 等國際通用的名稱，可視同英文。

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

3. 【強制】類名使用UpperCamelCase風格，但以下情形例外：DO / BO / DTO / VO / AO /

PO / UID等。

正例：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. 【強制】類型與中括號緊挨相連來表示數組。正例：定義整形數組 int[] arrayDemo; 反例：在 main 參數中，使用 String args[]來定義。

8. 【強制】POJO類中布爾類型的變量，都不要加is前綴，否則部分框架解析會引起序列化錯誤。反例：定義為基本數據類型Boolean isDeleted的屬性，它的方法也是isDeleted()，RPC 框架在反向解析的時候，“誤以為”對應的屬性名稱是deleted，導致屬性獲取不到，進而拋出異常。

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

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

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

反例：AbstractClass“縮寫”命名成AbsClass；condition“縮寫”命名成 condi，此類隨意縮寫嚴重降低了代碼的可閱讀性。

11. 【推薦】為了達到代碼自解釋的目標，任何自定義編程元素在命名時，使用盡量完整的單詞組合來表達其意。

正例：在 JDK 中，表達原子更新的類名為：AtomicReferenceFieldUpdater。

反例：變量 int a 的隨意命名方式。

12. 【推薦】如果模塊、接口、類、方法使用了設計模式，在命名時需體現出具體模式。

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

正例：public class OrderFactory; public class LoginProxy;

public class ResourceObserver;

13. 【推薦】接口類中的方法和屬性不要加任何修飾符號（public 也不要加），保持代碼的簡潔性，并加上有效的Javadoc注釋。盡量不要在接口里定義變量，如果一定要定義變量，肯定是與接口方法相關，并且是整個應用的基礎常量。

正例：接口方法簽名void commit();

接口基礎常量String COMPANY = "alibaba";

反例：接口方法定義public abstract void f();

說明：JDK8中接口允許有默認實現，那么這個default方法，是對所有實現類都有價值的默認實現。

14. 接口和實現類的命名有兩套規則：

1） 【強制】對于Service和DAO類，基于SOA的理念，暴露出來的服務一定是接口，內部的實現類用Impl的后綴與接口區別。

正例：CacheServiceImpl實現CacheService接口。

2） 【推薦】 如果是形容能力的接口名稱，取對應的形容詞為接口名（通常是–able的形式）。

正例：AbstractTranslator實現 Translatable接口。

15. 【參考】枚舉類名建議帶上Enum后綴，枚舉成員名稱需要全大寫，單詞間用下劃線隔開。

說明：枚舉其實就是特殊的類，域成員均為常量，且構造方法被默認強制是私有。

正例：枚舉名字為ProcessStatusEnum的成員名稱：SUCCESS / UNKNOWN_REASON。

16. 【參考】各層命名規約：

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

1） 獲取單個對象的方法用get做前綴。

2） 獲取多個對象的方法用list做前綴，復數形式結尾如：listObjects。

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） 應用內共享常量：放置在一方庫中，通常是子模塊中的constant目錄下。

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

“是”的變量：

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

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

A.YES.equals(B.YES)，預期是true，但實際返回為false，導致線上問題。

3） 子工程內部共享常量：即在當前子工程的constant目錄下。

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

5） 類內共享常量：直接在類內部private static final定義。

5. 【推薦】如果變量值僅在一個固定范圍內變化用 enum 類型來定義。

說明：如果存在名稱之外的延伸屬性應使用 enum 類型，下面正例中的數字就是延伸信息，表示一年中的第幾個季節。

正例：

public enum SeasonEnum {

SPRING(1), SUMMER(2), AUTUMN(3), WINTER(4); private int seq;

SeasonEnum(int seq){ this.seq = seq;

}

}

(三) 代碼格式

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

1） 左大括號前不換行。

2） 左大括號后換行。

3） 右大括號前換行。

4） 右大括號后還有else等代碼則不換行；表示終止的右大括號后必須換行。

2. 【強制】左小括號和字符之間不出現空格；同樣，右小括號和字符之間也不出現空格；而左大括號前需要空格。詳見第5條下方正例提示。

空格

a == b

空格

反例：if ()

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，不用換行

} else {

System.out.println("ok");

// 在右大括號后直接結束，則必須換行

}

}

6. 【強制】注釋的雙斜線與注釋內容之間有且僅有一個空格。

正例：

// 這是示例注釋，請注意在雙斜線之后有一個空格

String ygb = new String();

7. 【強制】單行字符數限制不超過 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);

8. 【強制】方法參數在定義和傳入時，多個參數逗號后邊必須加空格。

正例：下例中實參的args1，后邊必須要有一個空格。

method(args1, args2, args3);

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

10. 【推薦】單個方法的總行數不超過 80 行。

說明：包括方法簽名、結束右大括號、方法內代碼、注釋、空行、回車及任何不可見字符的總行數不超過 80 行。

正例：代碼邏輯分清紅花和綠葉，個性和共性，綠葉邏輯單獨出來成為額外方法，使主干代碼更加清晰；共性邏輯抽取成為共性方法，便于復用和維護。

11. 【推薦】沒有必要增加若干空格來使某一行的字符與上一行對應位置的字符對齊。

正例：

int one = 1;

long two = 2L;

float three = 3F;

StringBuffer sb = new StringBuffer();

說明：增加sb這個變量，如果需要對齊，則給a、b、c都要增加幾個空格，在變量比較多的情況下，是非常累贅的事情。

12. 【推薦】不同邏輯、不同語義、不同業務的代碼之間插入一個空行分隔開來以提升可讀性。

說明：任何情形，沒有必要插入多個空行進行隔開。

(四) OOP規約

1. 【強制】避免通過一個類的對象引用訪問此類的靜態變量或靜態方法，無謂增加編譯器解析成本，直接用類名來訪問即可。

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

說明：getObject()與get0bject()的問題。一個是字母的O，一個是數字的0，加@Override 可以準確判斷是否覆蓋成功。另外，如果在抽象類中對方法簽名進行修改，其實現類會馬上編譯報錯。

3. 【強制】相同參數類型，相同業務含義，才可以使用Java的可變參數，避免使用Object。

說明：可變參數必須放置在參數列表的最后。（提倡同學們盡量不用可變參數編程）正例：public List<User> listUsers(String type, Long... 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方法進行判斷。

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. 【強制】禁止在POJO類中，同時存在對應屬性xxx的isXxx()和getXxx()方法。

說明：框架在調用屬性 xxx 的提取方法時，并不能確定哪個方法一定是被優先調用到。

14. 【推薦】使用索引訪問用String的split方法得到的數組時，需做最后一個分隔符后有無內容的檢查，否則會有拋IndexOutOfBoundsException的風險。說明：

String str = "a,b,c,,";

String[] ary = str.split(",");

// 預期大于3，結果是3

System.out.println(ary.length);

15. 【推薦】當一個類有多個構造方法，或者多個同名方法，這些方法應該按順序放置在一起，便于閱讀，此條規則優先于第16條規則。

16. 【推薦】 類內方法定義的順序依次是：公有方法或保護方法 > 私有方法 > getter/setter 方法。

說明：公有方法是類的調用者和維護者最關心的方法，首屏展示最好；保護方法雖然只是子類關心，也可能是“模板設計模式”下的核心方法；而私有方法外部一般不需要特別關心，是一個黑盒實現；因為承載的信息價值較低，所有Service和DAO的getter/setter方法放在類體最后。

17. 【推薦】setter方法中，參數名稱與類成員變量名稱一致，this.成員名 = 參數名。在 getter/setter方法中，不要增加業務邏輯，增加排查問題的難度。

反例：

public Integer getData() { if (condition) { return this.data + 100;

} else { return this.data - 100;

}

}

18. 【推薦】循環體內，字符串的連接方式，使用StringBuilder的append方法進行擴展。說明：下例中，反編譯出的字節碼文件顯示每次循環都會new出一個StringBuilder對象，然后進行append操作，最后通過toString方法返回String對象，造成內存資源浪費。

反例：

String str = "start"; for (int i = 0; i < 100; i++) { str = str + "hello";

}

19. 【推薦】final可以聲明類、成員變量、方法、以及本地變量，下列情況使用final關鍵字： 1） 不允許被繼承的類，如：String類。

2） 不允許修改引用的域對象。

3） 不允許被重寫的方法，如：POJO類的setter方法。

4） 不允許運行過程中重新賦值的局部變量。

5） 避免上下文重復使用一個變量，使用final描述可以強制重新定義一個變量，方便更好地進行重構。

20. 【推薦】慎用Object的clone方法來拷貝對象。

說明：對象的clone方法默認是淺拷貝，若想實現深拷貝需要重寫clone方法實現域對象的深度遍歷式拷貝。

21. 【推薦】類成員與方法訪問控制從嚴：

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成員方法或成員變量，刪除一下，不得手心冒點汗嗎？變量像自己的小孩，盡量在自己的視線內，變量作用域太大，無限制的到處跑，那么你會擔心的。

(五) 集合處理

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帶參方法，入參分配的數組空間不夠大時，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錯誤。

5. 【強制】使用工具類Arrays.asList()把數組轉換成集合時，不能使用其修改集合相關的方法，它的add/remove/clear方法會拋出UnsupportedOperationException異常。

說明：asList的返回對象是一個Arrays內部類，并沒有實現集合的修改方法。Arrays.asList 體現的是適配器模式，只是轉換接口，后臺的數據仍是數組。

String[] str = new String[] { "you", "wu" }; List list = Arrays.asList(str);

第一種情況：list.add("yangguanbao"); 運行時異常。

第二種情況：str[0] = "gujin"; 那么list.get(0)也會隨之修改。

6. 【強制】泛型通配符<? extends T>來接收返回的數據，此寫法的泛型集合不能使用add方法，而<? super T>不能使用get方法，作為接口調用賦值時易出錯。

說明：擴展說一下PECS(Producer Extends Consumer Super)原則：第一、頻繁往外讀取內容的，適合用<? extends T>。第二、經常往里插入的，適合用<? super T>。

7. 【強制】不要在foreach循環里進行元素的remove/add操作。remove元素請使用Iterator 方式，如果并發操作，需要對Iterator對象加鎖。正例：

List<String> list = new ArrayList<>(); list.add("1"); list.add("2");

Iterator<String> iterator = list.iterator(); while (iterator.hasNext()) {

String item = iterator.next(); if (刪除元素的條件) { iterator.remove(); }

}

反例：

for (String item : list) { if ("1".equals(item)) { list.remove(item);

}

}

說明：以上代碼的執行結果肯定會出乎大家的意料，那么試一下把“1”換成“2”，會是同樣的結果嗎？

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<Student>() {

@Override public int compare(Student o1, Student o2) { return o1.getId() > o2.getId() ? 1 : -1; } };

9. 【推薦】集合泛型定義時，在JDK7及以上，使用diamond語法或全省略。說明：菱形泛型，即diamond，直接使用<>來指代前邊已經指定的類型。

正例：

// <> diamond方式

HashMap<String, String> userCache = new HashMap<>(16);

// 全省略方式

ArrayList<User> users = new ArrayList(10);

10. 【推薦】集合初始化時，指定集合初始值大小。

說明：HashMap使用HashMap(int initialCapacity) 初始化。

正例：initialCapacity = (需要存儲的元素個數 / 負載因子) + 1。注意負載因子（即loader factor）默認為0.75，如果暫時無法確定初始值大小，請設置為16（即默認值）。

反例：HashMap需要放置1024個元素，由于沒有設置容量初始大小，隨著元素不斷增加，容量 7 次被迫擴大，resize需要重建hash表，嚴重影響性能。

11. 【推薦】使用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值組合集合。

12. 【推薦】高度注意Map類集合K/V能不能存儲null值的情況，如下表格：

集合類

Key

Value

Super

說明

Hashtable

不允許為null

不允許為null

Dictionary

線程安全

ConcurrentHashMap

不允許為null

不允許為null

AbstractMap

鎖分段技術（JDK8:CAS）

TreeMap

不允許為null

允許為null

AbstractMap

線程不安全

HashMap

允許為null

允許為null

AbstractMap

線程不安全

反例： 由于HashMap的干擾，很多人認為ConcurrentHashMap是可以置入null值，而事實上，存儲null值時會拋出NPE異常。

13. 【參考】合理利用好集合的有序性(sort)和穩定性(order)，避免集合的無序性(unsort)和不穩定性(unorder)帶來的負面影響。

說明：有序性是指遍歷的結果是按某種比較規則依次排列的。穩定性指集合每次遍歷的元素次

序是一定的。如：ArrayList是order/unsort；HashMap是unorder/unsort；TreeSet是 order/sort。

14. 【參考】利用Set元素唯一的特性，可以快速對一個集合進行去重操作，避免使用List的

contains方法進行遍歷、對比、去重操作。

(六) 并發處理

1. 【強制】獲取單例對象需要保證線程安全，其中的方法也要保證線程安全。說明：資源驅動類、工具類、單例工廠類都需要注意。

2. 【強制】創建線程或線程池時請指定有意義的線程名稱，方便出錯時回溯。

正例：

public class TimerTaskThread extends Thread { public TimerTaskThread() { super.setName("TimerTaskThread");

...

}

}

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<DateFormat> df = new ThreadLocal<DateFormat>() {

@Override

protected DateFormat initialValue() {

return new SimpleDateFormat("yyyy-MM-dd");

}

};

說明：如果是JDK8的應用，可以使用Instant代替Date，LocalDateTime代替Calendar，

DateTimeFormatter代替SimpleDateFormat，官方給出的解釋：simple beautiful strong immutable thread-safe。

6. 【強制】高并發時，同步調用應該去考量鎖的性能損耗。能用無鎖數據結構，就不要用鎖；能鎖區塊，就不要鎖整個方法體；能用對象鎖，就不要用類鎖。

說明：盡可能使加鎖的代碼塊工作量盡可能的小，避免在鎖代碼塊中調用 RPC 方法。

7. 【強制】對多個資源、數據庫表、對象同時加鎖時，需要保持一致的加鎖順序，否則可能會造成死鎖。

說明：線程一需要對表A、B、C依次全部加鎖后才可以進行更新操作，那么線程二的加鎖順序也必須是A、B、C，否則可能出現死鎖。

8. 【強制】并發修改同一記錄時，避免更新丟失，需要加鎖。要么在應用層加鎖，要么在緩存加

鎖，要么在數據庫層使用樂觀鎖，使用version作為更新依據。

說明：如果每次訪問沖突概率小于20%，推薦使用樂觀鎖，否則使用悲觀鎖。樂觀鎖的重試次數不得小于3次。

9. 【強制】多線程并行處理定時任務時，Timer運行多個TimeTask時，只要其中之一沒有捕獲

拋出的異常，其它任務便會自動終止運行，使用ScheduledExecutorService則沒有這個問題。

10. 【推薦】使用CountDownLatch進行異步轉同步操作，每個線程退出前必須調用countDown 方法，線程執行代碼注意catch異常，確保countDown方法被執行到，避免主線程無法執行至await方法，直到超時才返回結果。

說明：注意，子線程拋出異常堆棧，不能在主線程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 LazyInitDemo { private Helper helper = null; public Helper getHelper() { if (helper == null) synchronized(this) { if (helper == null) helper = new Helper();

} return helper;

}

// other methods and fields... }

13. 【參考】volatile解決多線程內存不可見問題。對于一寫多讀，是可以解決變量同步問題，但是如果多寫，同樣無法解決線程安全問題。如果是count++操作，使用如下類實現：

AtomicInteger count = new AtomicInteger(); count.addAndGet(1); 如果是JDK8，推薦使用LongAdder對象，比AtomicLong性能更好（減少樂觀鎖的重試次數）。

14. 【參考】 HashMap在容量不夠進行resize時由于高并發可能出現死鏈，導致CPU飆升，在開發過程中可以使用其它數據結構或加鎖來規避此風險。

15. 【參考】ThreadLocal無法解決共享對象的更新問題，ThreadLocal對象建議使用static

修飾。這個變量是針對一個線程內所有操作共享的，所以設置為靜態變量，所有此類實例共享此靜態變量 ，也就是說在類第一次被使用時裝載，只分配一塊存儲空間，所有此類的對象(只要是這個線程內定義的)都可以操控這個變量。

(七) 控制語句

1. 【強制】在一個switch塊內，每個case要么通過break/return等來終止，要么注釋說明程序將繼續執行到哪一個case為止；在一個switch塊內，都必須包含一個default語句并且放在最后，即使空代碼。

2. 【強制】在if/else/for/while/do語句中必須使用大括號。即使只有一行代碼，避免采用

單行的編碼方式：if (condition) statements;

3.【強制】在高并發場景中，避免使用”等于”判斷作為中斷或退出的條件。

說明：如果并發控制沒有處理好，容易產生等值判斷被“擊穿”的情況，使用大于或小于的區間判斷條件來代替。

反例：判斷剩余獎品數量等于 0 時，終止發放獎品，但因為并發處理錯誤導致獎品數量瞬間變成了負數，這樣的話，活動無法終止。

4. 【推薦】表達異常的分支時，少用if-else方式，這種方式可以改寫成：

if (condition) { ...

return obj;

}

// 接著寫else的業務邏輯代碼; 說明：如果非得使用if()...else if()...else...方式表達邏輯，【強制】避免后續代碼維護困難，請勿超過3層。 正例：超過3層的 if-else 的邏輯判斷代碼可以使用衛語句、策略模式、狀態模式等來實現，其中衛語句示例如下：

public void today() { if (isBusy()) {

System.out.println(“change time.”);

return;

}

if (isFree()) {

System.out.println(“go to travel.”); return;

}

System.out.println(“stay at home to learn Alibaba Java Coding Guidelines.”); return;

}

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

// 偽代碼如下

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

}

反例：

if ((file.open(fileName, "w") != null) && (...) || (...)) { ...

}

6.【推薦】循環體中的語句要考量性能，以下操作盡量移至循環體外處理，如定義對象、變量、

獲取數據庫連接，進行不必要的try-catch操作（這個try-catch是否可以移至循環體外）。

7. 【推薦】避免采用取反邏輯運算符。

說明：取反邏輯不利于快速理解，并且取反邏輯寫法必然存在對應的正向邏輯寫法。

正例：使用if (x < 628) 來表達 x 小于 628。

反例：使用if (!(x >= 628)) 來表達 x 小于 628。

8. 【推薦】接口入參保護，這種場景常見的是用作批量操作的接口。

9. 【參考】下列情形，需要進行參數校驗：

1） 調用頻次低的方法。

2） 執行時間開銷很大的方法。此情形中，參數校驗時間幾乎可以忽略不計，但如果因為參數錯誤導致中間執行回退，或者錯誤，那得不償失。

3） 需要極高穩定性和可用性的方法。

4） 對外提供的開放接口，不管是RPC/API/HTTP接口。

5） 敏感權限入口。

10. 【參考】下列情形，不需要進行參數校驗：

1） 極有可能被循環調用的方法。但在方法說明里必須注明外部參數檢查要求。

2） 底層調用頻度比較高的方法。畢竟是像純凈水過濾的最后一道，參數錯誤不太可能到底層才會暴露問題。一般DAO層與Service層都在同一個應用中，部署在同一臺服務器中，所以DAO的參數校驗，可以省略。

3） 被聲明成private只會被自己代碼所調用的方法，如果能夠確定調用方法的代碼傳入參數已經做過檢查或者肯定不會有問題，此時可以不校驗參數。

(八) 注釋規約

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

// xxx方式。

說明：在IDE編輯窗口中，Javadoc方式會提示相關注釋，生成Javadoc可以正確輸出相應注釋；在IDE中，工程調用方法時，不進入方法即可懸浮提示方法、參數、返回值的意義，提高閱讀效率。

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

3. 【強制】所有的類都必須添加創建者和創建日期。

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

5. 【強制】所有的枚舉類型字段必須要有注釋，說明每個數據項的用途。

6. 【推薦】與其“半吊子”英文來注釋，不如用中文注釋把問題說清楚。專有名詞與關鍵字保持英文原文即可。

反例：“TCP連接超時”解釋成“傳輸控制協議連接超時”，理解反而費腦筋。

7. 【推薦】代碼修改的同時，注釋也要進行相應的修改，尤其是參數、返回值、異常、核心邏輯等的修改。

說明：代碼與注釋更新不同步，就像路網與導航軟件更新不同步一樣，如果導航軟件嚴重滯后，就失去了導航的意義。

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方法。

5. 【強制】獲取當前毫秒數System.currentTimeMillis(); 而不是new Date().getTime(); 說明：如果想獲取更加精確的納秒級時間值，使用System.nanoTime()的方式。在JDK8中，針對統計時間等場景，推薦使用Instant類。

6. 【推薦】不要在視圖模板中加入任何復雜的邏輯。

說明：根據 MVC 理論，視圖的職責是展示，不要搶模型和控制器的活。

7. 【推薦】任何數據結構的構造或初始化，都應指定大小，避免數據結構無限增長吃光內存。

8. 【推薦】及時清理不再使用的代碼段或配置信息。

說明：對于垃圾代碼或過時配置，堅決清理干凈，避免程序過度臃腫，代碼冗余。

正例：對于暫時被注釋掉，后續可能恢復使用的代碼片斷，在注釋代碼上方，統一規定使用三個斜杠(///)來說明注釋掉代碼的理由。

二、異常日志

(一) 異常處理

1. 【強制】Java 類庫中定義的可以通過預檢查方式規避的RuntimeException異常不應該通過 catch 的方式來處理，比如：NullPointerException，IndexOutOfBoundsException等等。

說明：無法通過預檢查的異常除外，比如，在解析字符串形式的數字時，不得不通過catch

NumberFormatException來實現。

正例：if (obj != null) {...}

反例：try { obj.method(); } catch (NullPointerException e) {…}

2. 【強制】異常不要用來做流程控制，條件控制。

說明：異常設計的初衷是解決程序運行中的各種意外情況，且異常的處理效率比條件判斷方式要低很多。

3. 【強制】catch時請分清穩定代碼和非穩定代碼，穩定代碼指的是無論如何不會出錯的代碼。

對于非穩定代碼的catch盡可能進行區分異常類型，再做對應的異常處理。

說明：對大段代碼進行try-catch，使程序無法根據不同的異常做出正確的應激反應，也不利于定位問題，這是一種不負責任的表現。

正例：用戶注冊的場景中，如果用戶輸入非法字符，或用戶名稱已存在，或用戶輸入密碼過于簡單，在程序上作出分門別類的判斷，并提示給用戶。

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

5. 【強制】有try塊放到了事務代碼中，catch異常后，如果需要回滾事務，一定要注意手動回滾事務。

6. 【強制】finally塊必須對資源對象、流對象進行關閉，有異常也要做try-catch。

說明：如果JDK7及以上，可以使用try-with-resources方式。

7. 【強制】不要在finally塊中使用return。

說明：finally塊中的return返回后方法結束執行，不會再執行try塊中的return語句。

8. 【強制】捕獲異常與拋異常，必須是完全匹配，或者捕獲異常是拋異常的父類。

說明：如果預期對方拋的是繡球，實際接到的是鉛球，就會產生意外情況。

9. 【推薦】方法的返回值可以為null，不強制返回空集合，或者空對象等，必須添加注釋充分

說明什么情況下會返回null值。

說明：本手冊明確防止NPE是調用者的責任。即使被調用方法返回空集合或者空對象，對調用者來說，也并非高枕無憂，必須考慮到遠程調用失敗、序列化失敗、運行時異常等場景返回 null的情況。

10. 【推薦】防止NPE，是程序員的基本修養，注意NPE產生的場景：

1） 返回類型為基本數據類型，return包裝數據類型的對象時，自動拆箱有可能產生NPE。 反例：public int f() { return Integer對象}， 如果為null，自動解箱拋NPE。

2） 數據庫的查詢結果可能為null。

3） 集合里的元素即使isNotEmpty，取出的數據元素也可能為null。

4） 遠程調用返回對象時，一律要求進行空指針判斷，防止NPE。

5） 對于Session中獲取的數據，建議NPE檢查，避免空指針。

6） 級聯調用obj.getA().getB().getC()；一連串調用，易產生NPE。

正例：使用JDK8的Optional類來防止NPE問題。

11. 【推薦】定義時區分unchecked / checked 異常，避免直接拋出new RuntimeException()，更不允許拋出Exception或者Throwable，應使用有業務含義的自定義異常。推薦業界已定義過的自定義異常，如：DAOException / ServiceException等。

12. 【參考】對于公司外的http/api開放接口必須使用“錯誤碼”；而應用內部推薦異常拋出；跨應用間RPC調用優先考慮使用Result方式，封裝isSuccess()方法、“錯誤碼”、“錯誤簡短信息”。

說明：關于RPC方法返回方式使用Result方式的理由：

1） 使用拋異常返回方式，調用方如果沒有捕獲到就會產生運行時錯誤。

2） 如果不加棧信息，只是new自定義異常，加入自己的理解的error message，對于調用端解決問題的幫助不會太多。如果加了棧信息，在頻繁調用出錯的情況下，數據序列化和傳輸的性能損耗也是問題。

13. 【參考】避免出現重復的代碼（Don’t Repeat Yourself），即DRY原則。

說明：隨意復制和粘貼代碼，必然會導致代碼的重復，在以后需要修改時，需要修改所有的副本，容易遺漏。必要時抽取共性方法，或者抽象公共類，甚至是組件化。

正例：一個類中有多個public方法，都需要進行數行相同的參數校驗操作，這個時候請抽取：

private boolean checkParam(DTO dto) {...}

(二) 日志規約

1. 【強制】應用中不可直接使用日志系統（Log4j、Logback）中的API，而應依賴使用日志框架

SLF4J中的API，使用門面模式的日志框架，有利于維護和各個類的日志處理方式統一。

import org.slf4j.Logger;

import org.slf4j.LoggerFactory;

private static final Logger logger = LoggerFactory.getLogger(Abc.class);

2. 【強制】日志文件至少保存15天，因為有些異常具備以“周”為頻次發生的特點。

3. 【強制】應用中的擴展日志（如打點、臨時監控、訪問日志等）命名方式：

appName_logType_logName.log。

logType:日志類型，如stats/monitor/access等；logName:日志描述。這種命名的好處：通過文件名就可知道日志文件屬于什么應用，什么類型，什么目的，也有利于歸類查找。

正例：mppserver應用中單獨監控時區轉換異常，如：

mppserver_monitor_timeZoneConvert.log

說明：推薦對日志進行分類，如將錯誤日志和業務日志分開存放，便于開發人員查看，也便于通過日志對系統進行及時監控。

4. 【強制】對trace/debug/info級別的日志輸出，必須使用條件輸出形式或者使用占位符的方式。

說明：logger.debug("Processing trade with id: " + id + " and symbol: " + symbol); 如果日志級別是warn，上述日志不會打印，但是會執行字符串拼接操作，如果symbol是對象，會執行toString()方法，浪費了系統資源，執行了上述操作，最終日志卻沒有打印。

正例：（條件）建設采用如下方式

if (logger.isDebugEnabled()) {

logger.debug("Processing trade with id: " + id + " and symbol: " + symbol);

}

正例：（占位符）

logger.debug("Processing trade with id: {} and symbol : {} ", id, symbol);

5. 【強制】避免重復打印日志，浪費磁盤空間，務必在log4j.xml中設置additivity=false。

正例：<logger name="com.taobao.dubbo.config" additivity="false">

6. 【強制】異常信息應該包括兩類信息：案發現場信息和異常堆棧信息。如果不處理，那么通過關鍵字throws往上拋出。

正例：logger.error(各類參數或者對象toString() + "_" + e.getMessage(), e);

7. 【推薦】謹慎地記錄日志。生產環境禁止輸出debug日志；有選擇地輸出info日志；如果使用warn來記錄剛上線時的業務行為信息，一定要注意日志輸出量的問題，避免把服務器磁盤撐爆，并記得及時刪除這些觀察日志。

說明：大量地輸出無效日志，不利于系統性能提升，也不利于快速定位錯誤點。記錄日志時請思考：這些日志真的有人看嗎？看到這條日志你能做什么？能不能給問題排查帶來好處？

8. 【推薦】可以使用 warn 日志級別來記錄用戶輸入參數錯誤的情況，避免用戶投訴時，無所適

從。如非必要，請不要在此場景打出 error 級別，避免頻繁報警。

說明：注意日志輸出的級別，error 級別只記錄系統邏輯出錯、異常或者重要的錯誤信息。

9. 【推薦】盡量用英文來描述日志錯誤信息，如果日志中的錯誤信息用英文描述不清楚的話使用中文描述即可，否則容易產生歧義。國際化團隊或海外部署的服務器由于字符集問題，【強制】使用全英文來注釋和描述日志錯誤信息。

三、單元測試

1. 【強制】好的單元測試必須遵守AIR原則。

說明：單元測試在線上運行時，感覺像空氣（AIR）一樣并不存在，但在測試質量的保障上，卻是非常關鍵的。好的單元測試宏觀上來說，具有自動化、獨立性、可重復執行的特點。

l A：Automatic（自動化）

l I：Independent（獨立性）

l R：Repeatable（可重復）

2. 【強制】單元測試應該是全自動執行的，并且非交互式的。測試用例通常是被定期執行的，執行過程必須完全自動化才有意義。輸出結果需要人工檢查的測試不是一個好的單元測試。單元測試中不準使用System.out來進行人肉驗證，必須使用assert來驗證。

3. 【強制】保持單元測試的獨立性。為了保證單元測試穩定可靠且便于維護，單元測試用例之間決不能互相調用，也不能依賴執行的先后次序。

反例：method2需要依賴method1的執行，將執行結果作為method2的輸入。

4. 【強制】單元測試是可以重復執行的，不能受到外界環境的影響。

說明：單元測試通常會被放到持續集成中，每次有代碼check in時單元測試都會被執行。如果單測對外部環境（網絡、服務、中間件等）有依賴，容易導致持續集成機制的不可用。

正例：為了不受外界環境影響，要求設計代碼時就把SUT的依賴改成注入，在測試時用spring 這樣的DI框架注入一個本地（內存）實現或者Mock實現。

5. 【強制】對于單元測試，要保證測試粒度足夠小，有助于精確定位問題。單測粒度至多是類級別，一般是方法級別。

說明：只有測試粒度小才能在出錯時盡快定位到出錯位置。單測不負責檢查跨類或者跨系統的交互邏輯，那是集成測試的領域。

6. 【強制】核心業務、核心應用、核心模塊的增量代碼確保單元測試通過。

說明：新增代碼及時補充單元測試，如果新增代碼影響了原有單元測試，請及時修正。

7. 【強制】單元測試代碼必須寫在如下工程目錄：src/test/java，不允許寫在業務代碼目錄下。

說明：源碼構建時會跳過此目錄，而單元測試框架默認是掃描此目錄。

8. 【推薦】單元測試的基本目標：語句覆蓋率達到70%；核心模塊的語句覆蓋率和分支覆蓋率都要達到100%

說明：在工程規約的應用分層中提到的DAO層，Manager層，可重用度高的Service，都應該進行單元測試。

9. 【推薦】編寫單元測試代碼遵守BCDE原則，以保證被測試模塊的交付質量。

l B：Border，邊界值測試，包括循環邊界、特殊取值、特殊時間點、數據順序等。

l C：Correct，正確的輸入，并得到預期的結果。

l D：Design，與設計文檔相結合，來編寫單元測試。

l E：Error，強制錯誤信息輸入（如：非法數據、異常流程、非業務允許輸入等），并得到預期的結果。

10. 【推薦】對于數據庫相關的查詢，更新，刪除等操作，不能假設數據庫里的數據是存在的，或者直接操作數據庫把數據插入進去，請使用程序插入或者導入數據的方式來準備數據。

反例：刪除某一行數據的單元測試，在數據庫中，先直接手動增加一行作為刪除目標，但是這一行新增數據并不符合業務插入規則，導致測試結果異常。

11. 【推薦】和數據庫相關的單元測試，可以設定自動回滾機制，不給數據庫造成臟數據。或者對單元測試產生的數據有明確的前后綴標識。

正例：在RDC內部單元測試中，使用RDC_UNIT_TEST_的前綴標識數據。

12. 【推薦】對于不可測的代碼建議做必要的重構，使代碼變得可測，避免為了達到測試要求而書寫不規范測試代碼。

13. 【推薦】在設計評審階段，開發人員需要和測試人員一起確定單元測試范圍，單元測試最好覆蓋所有測試用例。

14. 【推薦】單元測試作為一種質量保障手段，不建議項目發布后補充單元測試用例，建議在項目提測前完成單元測試。

15. 【參考】為了更方便地進行單元測試，業務代碼應避免以下情況：

l 構造方法中做的事情過多。

l 存在過多的全局變量和靜態方法。

l 存在過多的外部依賴。

l 存在過多的條件語句。

說明：多層條件語句建議使用衛語句、策略模式、狀態模式等方式重構。

16. 【參考】不要對單元測試存在如下誤解：

l 那是測試同學干的事情。本文是開發手冊，凡是本文內容都是與開發同學強相關的。 l 單元測試代碼是多余的。系統的整體功能與各單元部件的測試正常與否是強相關的。

l 單元測試代碼不需要維護。一年半載后，那么單元測試幾乎處于廢棄狀態。

l 單元測試與線上故障沒有辯證關系。好的單元測試能夠最大限度地規避線上故障。

四、安全規約

1. 【強制】隸屬于用戶個人的頁面或者功能必須進行權限控制校驗。

說明：防止沒有做水平權限校驗就可隨意訪問、修改、刪除別人的數據，比如查看他人的私信內容、修改他人的訂單。

2. 【強制】用戶敏感數據禁止直接展示，必須對展示數據進行脫敏。

說明：中國大陸個人手機號碼顯示為:158****9119，隱藏中間4位，防止隱私泄露。

3. 【強制】用戶輸入的SQL參數嚴格使用參數綁定或者METADATA字段值限定，防止SQL注入，禁止字符串拼接SQL訪問數據庫。

4. 【強制】用戶請求傳入的任何參數必須做有效性驗證。

說明：忽略參數校驗可能導致：

l page size過大導致內存溢出

l 惡意order by導致數據庫慢查詢

l 任意重定向

l SQL注入

l 反序列化注入

l 正則輸入源串拒絕服務ReDoS

說明：Java 代碼用正則來驗證客戶端的輸入，有些正則寫法驗證普通用戶輸入沒有問題，但是如果攻擊人員使用的是特殊構造的字符串來驗證，有可能導致死循環的結果。

5. 【強制】禁止向HTML頁面輸出未經安全過濾或未正確轉義的用戶數據。

6. 【強制】表單、AJAX提交必須執行CSRF安全驗證。

說明：CSRF(Cross-site request forgery)跨站請求偽造是一類常見編程漏洞。對于存在

CSRF漏洞的應用/網站，攻擊者可以事先構造好URL，只要受害者用戶一訪問，后臺便在用戶不知情的情況下對數據庫中用戶參數進行相應修改。

7. 【強制】在使用平臺資源，譬如短信、郵件、電話、下單、支付，必須實現正確的防重放的機制，如數量限制、疲勞度控制、驗證碼校驗，避免被濫刷而導致資損。

說明：如注冊時發送驗證碼到手機，如果沒有限制次數和頻率，那么可以利用此功能騷擾到其它用戶，并造成短信平臺資源浪費。

8. 【推薦】發貼、評論、發送即時消息等用戶生成內容的場景必須實現防刷、文本內容違禁詞過濾等風控策略。

五、MySQL數據庫

(一) 建表規約

1. 【強制】表達是與否概念的字段，必須使用is_xxx的方式命名，數據類型是unsigned tinyint

（1 表示是，0 表示否）。

說明：任何字段如果為非負數，必須是unsigned。

注意：POJO類中的任何布爾類型的變量，都不要加is前綴，所以，需要在<resultMap>設置從is_xxx到Xxx的映射關系。數據庫表示是與否的值，使用tinyint類型，堅持is_xxx的命名方式是為了明確其取值含義與取值范圍。

正例：表達邏輯刪除的字段名is_deleted，1 表示刪除，0 表示未刪除。

2. 【強制】表名、字段名必須使用小寫字母或數字，禁止出現數字開頭，禁止兩個下劃線中間只出現數字。數據庫字段名的修改代價很大，因為無法進行預發布，所以字段名稱需要慎重考慮。

說明：MySQL在Windows下不區分大小寫，但在 Linux 下默認是區分大小寫。因此，數據庫名、表名、字段名，都不允許出現任何大寫字母，避免節外生枝。

正例：aliyun_admin，rdc_config，level3_name 反例：AliyunAdmin，rdcConfig，level_3_name

3. 【強制】表名不使用復數名詞。

說明：表名應該僅僅表示表里面的實體內容，不應該表示實體數量，對應于DO類名也是單數形式，符合表達習慣。

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

5. 【強制】主鍵索引名為pk_字段名；唯一索引名為uk_字段名；普通索引名則為idx_字段名。

說明：pk_ 即primary key；uk_ 即 unique key；idx_ 即index的簡稱。

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

說明：float和double在存儲的時候，存在精度損失的問題，很可能在值的比較時，得到不

正確的結果。如果存儲的數據范圍超過decimal的范圍，建議將數據拆成整數和小數分開存儲。

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

8. 【強制】varchar是可變長字符串，不預先分配存儲空間，長度不要超過5000，如果存儲長度大于此值，定義字段類型為text，獨立出來一張表，用主鍵來對應，避免影響其它字段索引效率。

9. 【強制】表必備三字段：id, gmt_create, gmt_modified。

說明：其中id必為主鍵，類型為bigint unsigned、單表時自增、步長為 1。gmt_create,

gmt_modified的類型均為datetime類型，前者現在時表示主動創建，后者過去分詞表示被動更新。

10. 【推薦】表的命名最好是加上“業務名稱_表的作用”。

正例：alipay_task / force_project / trade_config

11. 【推薦】庫名與應用名稱盡量一致。

12. 【推薦】如果修改字段含義或對字段表示的狀態追加時，需要及時更新字段注釋。

13. 【推薦】字段允許適當冗余，以提高查詢性能，但必須考慮數據一致。冗余字段應遵循：

（1 不是頻繁修改的字段。

（2 不是varchar超長字段，更不能是text字段。

正例：商品類目名稱使用頻率高，字段長度短，名稱基本一成不變，可在相關聯的表中冗余存儲類目名稱，避免關聯查詢。

14. 【推薦】單表行數超過500萬行或者單表容量超過2GB，才推薦進行分庫分表。

說明：如果預計三年后的數據量根本達不到這個級別，請不要在創建表時就分庫分表。

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

正例：如下表，其中無符號值可以避免誤存負數，且擴大了表示范圍。

對象

年齡區間

類型

字節

表示范圍

人

150歲之內

tinyint unsigned

1

無符號值：0到255

龜

數百歲

smallint unsigned

2

無符號值：0到65535

恐龍化石

數千萬年

int unsigned

4

無符號值：0到約42.9億

太陽

約50億年

bigint unsigned

8

無符號值：0到約10的19次方

(二) 索引規約

1. 【強制】業務上具有唯一特性的字段，即使是多個字段的組合，也必須建成唯一索引。

說明：不要以為唯一索引影響了insert速度，這個速度損耗可以忽略，但提高查找速度是明顯的；另外，即使在應用層做了非常完善的校驗控制，只要沒有唯一索引，根據墨菲定律，必然有臟數據產生。

2. 【強制】超過三個表禁止join。需要join的字段，數據類型必須絕對一致；多表關聯查詢時，保證被關聯的字段需要有索引。

說明：即使雙表join也要注意表索引、SQL性能。

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

4. 【強制】頁面搜索嚴禁左模糊或者全模糊，如果需要請走搜索引擎來解決。

說明：索引文件具有B-Tree的最左前綴匹配特性，如果左邊的值未確定，那么無法使用此索引。

5. 【推薦】如果有order by的場景，請注意利用索引的有序性。order by 最后的字段是組合索引的一部分，并且放在索引組合順序的最后，避免出現file_sort的情況，影響查詢性能。

正例：where a=? and b=? order by c; 索引：a_b_c

反例：索引中有范圍查找，那么索引有序性無法利用，如：WHERE a>10 ORDER BY b; 索引 a_b無法排序。

6. 【推薦】利用覆蓋索引來進行查詢操作，避免回表。

說明：如果一本書需要知道第11章是什么標題，會翻開第11章對應的那一頁嗎？目錄瀏覽一下就好，這個目錄就是起到覆蓋索引的作用。

正例：能夠建立索引的種類分為主鍵索引、唯一索引、普通索引三種，而覆蓋索引只是一種查詢的一種效果，用explain的結果，extra列會出現：using index。

7. 【推薦】利用延遲關聯或者子查詢優化超多分頁場景。

說明：MySQL并不是跳過offset行，而是取offset+N行，然后返回放棄前offset行，返回 N行，那當offset特別大的時候，效率就非常的低下，要么控制返回的總頁數，要么對超過特定閾值的頁數進行SQL改寫。

正例：先快速定位需要獲取的id段，然后再關聯：

SELECT a.* FROM 表1 a, (select id from 表1 where 條件 LIMIT 100000,20 ) b where a.id=b.id

8. 【推薦】 SQL性能優化的目標：至少要達到 range 級別，要求是ref級別，如果可以是consts 最好。說明：

1） consts 單表中最多只有一個匹配行（主鍵或者唯一索引），在優化階段即可讀取到數據。

2） ref 指的是使用普通的索引（normal index）。

3） range 對索引進行范圍檢索。

反例：explain表的結果，type=index，索引物理文件全掃描，速度非常慢，這個index級別比較range還低，與全表掃描是小巫見大巫。

9. 【推薦】建組合索引的時候，區分度最高的在最左邊。

正例：如果where a=? and b=? ，如果a列的幾乎接近于唯一值，那么只需要單建idx_a 索引即可。

說明：存在非等號和等號混合時，在建索引時，請把等號條件的列前置。如：where c>? and d=? 那么即使c的區分度更高，也必須把d放在索引的最前列，即索引idx_d_c。

10. 【推薦】防止因字段類型不同造成的隱式轉換，導致索引失效。

11. 【參考】創建索引時避免有如下極端誤解：

1） 寧濫勿缺。認為一個查詢就需要建一個索引。

2） 寧缺勿濫。認為索引會消耗空間、嚴重拖慢更新和新增速度。

3） 抵制惟一索引。認為業務的惟一性一律需要在應用層通過“先查后插”方式解決。

(三) SQL語句

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

說明：count(*)會統計值為NULL的行，而count(列名)不會統計此列為NULL值的行。

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

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

NULL，因此使用sum()時需注意NPE問題。

正例：可以使用如下方式來避免sum的NPE問題：SELECT IF(ISNULL(SUM(g)),0,SUM(g))

FROM table;

4. 【強制】使用ISNULL()來判斷是否為NULL值。

說明：NULL與任何值的直接比較都為NULL。

1） NULL<>NULL的返回結果是NULL，而不是false。

2） NULL=NULL的返回結果是NULL，而不是true。

3） NULL<>1的返回結果是NULL，而不是true。

5. 【強制】 在代碼中寫分頁查詢邏輯時，若count為0應直接返回，避免執行后面的分頁語句。

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

說明：以學生和成績的關系為例，學生表中的student_id是主鍵，那么成績表中的student_id 則為外鍵。如果更新學生表中的student_id，同時觸發成績表中的student_id更新，即為級聯更新。外鍵與級聯更新適用于單機低并發，不適合分布式、高并發集群；級聯更新是強阻塞，存在數據庫更新風暴的風險；外鍵影響數據庫的插入速度。

7. 【強制】禁止使用存儲過程，存儲過程難以調試和擴展，更沒有移植性。

8. 【強制】數據訂正（特別是刪除、修改記錄操作）時，要先select，避免出現誤刪除，確認無誤才能執行更新語句。

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

10. 【參考】如果有國際化需要，所有的字符存儲與表示，均以utf-8編碼，注意字符統計函數的區別。

說明：

SELECT LENGTH("輕松工作")； 返回為12

SELECT CHARACTER_LENGTH("輕松工作")； 返回為4

如果需要存儲表情，那么選擇utf8mb4來進行存儲，注意它與utf-8編碼的區別。

11. 【參考】 TRUNCATE TABLE 比 DELETE 速度快，且使用的系統和事務日志資源少，但TRUNCATE 無事務且不觸發trigger，有可能造成事故，故不建議在開發代碼中使用此語句。

說明：TRUNCATE TABLE 在功能上與不帶 WHERE 子句的 DELETE 語句相同。

(四) ORM映射

1. 【強制】在表查詢中，一律不要使用 * 作為查詢的字段列表，需要哪些字段必須明確寫明。

說明：1）增加查詢分析器解析成本。2）增減字段容易與resultMap配置不一致。3）無用字段增加網絡消耗，尤其是text類型的字段。

2. 【強制】POJO類的布爾屬性不能加is，而數據庫字段必須加is_，要求在resultMap中進行字段與屬性之間的映射。

說明：參見定義POJO類以及數據庫字段定義規定，在<resultMap>中增加映射，是必須的。在MyBatis Generator生成的代碼中，需要進行對應的修改。

3. 【強制】不要用resultClass當返回參數，即使所有類屬性名與數據庫字段一一對應，也需要定義；反過來，每一個表也必然有一個POJO類與之對應。

說明：配置映射關系，使字段與DO類解耦，方便維護。

4. 【強制】sql.xml配置參數使用：#{}，#param# 不要使用${} 此種方式容易出現SQL注入。

5. 【強制】iBATIS自帶的queryForList(String statementName,int start,int size)不推薦使用。

說明：其實現方式是在數據庫取到statementName對應的SQL語句的所有記錄，再通過subList 取start,size的子集合。

正例：Map<String, Object> map = new HashMap<>();

map.put("start", start); map.put("size", size);

6. 【強制】不允許直接拿HashMap與Hashtable作為查詢結果集的輸出。

說明：resultClass=”Hashtable”，會置入字段名和屬性值，但是值的類型不可控。

7. 【強制】更新數據表記錄時，必須同時更新記錄對應的gmt_modified字段值為當前時間。

8. 【推薦】不要寫一個大而全的數據更新接口。傳入為POJO類，不管是不是自己的目標更新字段，都進行update table set c1=value1,c2=value2,c3=value3; 這是不對的。執行SQL 時，不要更新無改動的字段，一是易出錯；二是效率低；三是增加binlog存儲。

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

10. 【參考】<isEqual>中的compareValue是與屬性值對比的常量，一般是數字，表示相等時帶上此條件；<isNotEmpty>表示不為空且不為null時執行；<isNotNull>表示不為null值時執行。

六、工程結構

(一) 應用分層

1. 【推薦】圖中默認上層依賴于下層，箭頭關系表示可直接依賴，如：開放接口層可以依賴于

Web層，也可以直接依賴于Service層，依此類推：

? 開放接口層：可直接封裝Service方法暴露成RPC接口；通過Web封裝成http接口；進行網關安全控制、流量控制等。

? 終端顯示層：各個端的模板渲染并執行顯示的層。當前主要是velocity渲染，JS渲染，

JSP渲染，移動端展示等。

? Web層：主要是對訪問控制進行轉發，各類基本參數校驗，或者不復用的業務簡單處理等。

? Service層：相對具體的業務邏輯服務層。

? Manager層：通用業務處理層，它有如下特征：

1） 對第三方平臺封裝的層，預處理返回結果及轉化異常信息；

2） 對Service層通用能力的下沉，如緩存方案、中間件通用處理；

3） 與DAO層交互，對多個DAO的組合復用。

? DAO層：數據訪問層，與底層MySQL、Oracle、Hbase等進行數據交互。

? 外部接口或第三方平臺：包括其它部門RPC開放接口，基礎平臺，其它公司的HTTP接口。

2. 【參考】 （分層異常處理規約）在DAO層，產生的異常類型有很多，無法用細粒度的異常進

行catch，使用catch(Exception e)方式，并throw new DAOException(e)，不需要打印日志，因為日志在Manager/Service層一定需要捕獲并打印到日志文件中去，如果同臺服務器再打日志，浪費性能和存儲。在Service層出現異常時，必須記錄出錯日志到磁盤，盡可能帶上參數信息，相當于保護案發現場。如果Manager層與Service同機部署，日志方式與DAO 層處理一致，如果是單獨部署，則采用與Service一致的處理方式。Web層絕不應該繼續往上拋異常，因為已經處于頂層，如果意識到這個異常將導致頁面無法正常渲染，那么就應該直接跳轉到友好錯誤頁面，加上用戶容易理解的錯誤提示信息。開放接口層要將異常處理成錯誤碼和錯誤信息方式返回。

3. 【參考】分層領域模型規約：

? DO（Data Object）：此對象與數據庫表結構一一對應，通過DAO層向上傳輸數據源對象。

? DTO（Data Transfer Object）：數據傳輸對象，Service或Manager向外傳輸的對象。

? BO（Business Object）：業務對象，由Service層輸出的封裝業務邏輯的對象。

? AO（Application Object）：應用對象，在Web層與Service層之間抽象的復用對象模型，極為貼近展示層，復用度不高。

? VO（View Object）：顯示層對象，通常是Web向模板渲染引擎層傳輸的對象。

? Query：數據查詢對象，各層接收上層的查詢請求。注意超過2個參數的查詢封裝，禁止使用Map類來傳輸。

(二) 二方庫依賴

1. 【強制】定義GAV遵從以下規則：

1） GroupID格式：com.{公司/BU }.業務線 [.子業務線]，最多4級。

說明：{公司/BU} 例如：alibaba/taobao/tmall/aliexpress等BU一級；子業務線可選。

正例：com.taobao.jstorm 或 com.alibaba.dubbo.register

2） ArtifactID格式：產品線名-模塊名。語義不重復不遺漏，先到中央倉庫去查證一下。

正例：dubbo-client / fastjson-api / jstorm-tool

3） Version：詳細規定參考下方。

2. 【強制】二方庫版本號命名方式：主版本號.次版本號.修訂號

1） 主版本號：產品方向改變，或者大規模API不兼容，或者架構不兼容升級。

2） 次版本號：保持相對兼容性，增加主要功能特性，影響范圍極小的API不兼容修改。

3） 修訂號：保持完全兼容性，修復BUG、新增次要功能特性等。

說明：注意起始版本號必須為：1.0.0，而不是0.0.1 正式發布的類庫必須先去中央倉庫進行查證，使版本號有延續性，正式版本號不允許覆蓋升級。如當前版本：1.3.3，那么下一個合理的版本號：1.3.4 或 1.4.0 或 2.0.0

3. 【強制】線上應用不要依賴SNAPSHOT版本（安全包除外）。

說明：不依賴SNAPSHOT版本是保證應用發布的冪等性。另外，也可以加快編譯時的打包構建。

4. 【強制】二方庫的新增或升級，保持除功能點之外的其它jar包仲裁結果不變。如果有改變，

必須明確評估和驗證，建議進行dependency:resolve前后信息比對，如果仲裁結果完全不一致，那么通過dependency:tree命令，找出差異點，進行<excludes>排除jar包。

5. 【強制】二方庫里可以定義枚舉類型，參數可以使用枚舉類型，但是接口返回值不允許使用枚舉類型或者包含枚舉類型的POJO對象。

6. 【強制】依賴于一個二方庫群時，必須定義一個統一的版本變量，避免版本號不一致。

說明：依賴springframework-core,-context,-beans，它們都是同一個版本，可以定義一個變量來保存版本：${spring.version}，定義依賴的時候，引用該版本。

7. 【強制】禁止在子項目的pom依賴中出現相同的GroupId，相同的ArtifactId，但是不同的

Version。

說明：在本地調試時會使用各子項目指定的版本號，但是合并成一個war，只能有一個版本號出現在最后的lib目錄中。可能出現線下調試是正確的，發布到線上卻出故障的問題。

8. 【推薦】所有pom文件中的依賴聲明放在<dependencies>語句塊中，所有版本仲裁放在

<dependencyManagement>語句塊中。

說明：<dependencyManagement>里只是聲明版本，并不實現引入，因此子項目需要顯式的聲

明依賴，version和scope都讀取自父pom。而<dependencies>所有聲明在主pom的

<dependencies>里的依賴都會自動引入，并默認被所有的子項目繼承。

9. 【推薦】二方庫不要有配置項，最低限度不要再增加配置項。

10. 【參考】為避免應用二方庫的依賴沖突問題，二方庫發布者應當遵循以下原則：

1） 精簡可控原則。移除一切不必要的API和依賴，只包含 Service API、必要的領域模型對象、Utils類、常量、枚舉等。如果依賴其它二方庫，盡量是provided引入，讓二方庫使用者去依賴具體版本號；無log具體實現，只依賴日志框架。

2） 穩定可追溯原則。每個版本的變化應該被記錄，二方庫由誰維護，源碼在哪里，都需要能方便查到。除非用戶主動升級版本，否則公共二方庫的行為不應該發生變化。

(三) 服務器

1. 【推薦】高并發服務器建議調小TCP協議的time_wait超時時間。

說明：操作系統默認240秒后，才會關閉處于time_wait狀態的連接，在高并發訪問下，服務器端會因為處于time_wait的連接數太多，可能無法建立新的連接，所以需要在服務器上調小此等待值。

正例：在linux服務器上請通過變更/etc/sysctl.conf文件去修改該缺省值（秒）： net.ipv4.tcp_fin_timeout = 30

2. 【推薦】調大服務器所支持的最大文件句柄數（File Descriptor，簡寫為fd）。

說明：主流操作系統的設計是將TCP/UDP連接采用與文件一樣的方式去管理，即一個連接對應于一個fd。主流的linux服務器默認所支持最大fd數量為1024，當并發連接數很大時很容易因為fd不足而出現“open too many files”錯誤，導致新的連接無法建立。 建議將linux 服務器所支持的最大句柄數調高數倍（與服務器的內存數量相關）。

3. 【推薦】給JVM環境參數設置-XX:+HeapDumpOnOutOfMemoryError參數，讓JVM碰到OOM場景時輸出dump信息。

說明：OOM的發生是有概率的，甚至相隔數月才出現一例，出錯時的堆內信息對解決問題非常有幫助。

4. 【推薦】在線上生產環境，JVM的Xms和Xmx設置一樣大小的內存容量，避免在GC 后調整堆大小帶來的壓力。

5. 【參考】服務器內部重定向使用forward；外部重定向地址使用URL拼裝工具類來生成，否則會帶來URL維護不一致的問題和潛在的安全風險。

七、設計規約

1. 【強制】存儲方案和底層數據結構的設計獲得評審一致通過，并沉淀成為文檔。

說明：有缺陷的底層數據結構容易導致系統風險上升，可擴展性下降，重構成本也會因歷史數據遷移和系統平滑過渡而陡然增加，所以，存儲方案和數據結構需要認真地進行設計和評審，生產環境提交執行后，需要進行double check。

正例：評審內容包括存儲介質選型、表結構設計能否滿足技術方案、存取性能和存儲空間能否滿足業務發展、表或字段之間的辯證關系、字段名稱、字段類型、索引等；數據結構變更（如在原有表中新增字段）也需要進行評審通過后上線。

2. 【強制】在需求分析階段，如果與系統交互的User超過一類并且相關的User Case超過5個，使用用例圖來表達更加清晰的結構化需求。

3. 【強制】如果某個業務對象的狀態超過3個，使用狀態圖來表達并且明確狀態變化的各個觸發條件。

說明：狀態圖的核心是對象狀態，首先明確對象有多少種狀態，然后明確兩兩狀態之間是否存在直接轉換關系，再明確觸發狀態轉換的條件是什么。

正例：淘寶訂單狀態有已下單、待付款、已付款、待發貨、已發貨、已收貨等。比如已下單與已收貨這兩種狀態之間是不可能有直接轉換關系的。

4. 【強制】如果系統中某個功能的調用鏈路上的涉及對象超過3個，使用時序圖來表達并且明確各調用環節的輸入與輸出。

說明：時序圖反映了一系列對象間的交互與協作關系，清晰立體地反映系統的調用縱深鏈路。

5. 【強制】如果系統中模型類超過5個，并且存在復雜的依賴關系，使用類圖來表達并且明確類之間的關系。

說明：類圖像建筑領域的施工圖，如果搭平房，可能不需要，但如果建造螞蟻Z空間大樓，肯定需要詳細的施工圖。

6. 【強制】如果系統中超過2個對象之間存在協作關系，并且需要表示復雜的處理流程，使用活動圖來表示。

說明：活動圖是流程圖的擴展，增加了能夠體現協作關系的對象泳道，支持表示并發等。

7. 【推薦】需求分析與系統設計在考慮主干功能的同時，需要充分評估異常流程與業務邊界。反例：用戶在淘寶付款過程中，銀行扣款成功，發送給用戶扣款成功短信，但是支付寶入款時由于斷網演練產生異常，淘寶訂單頁面依然顯示未付款，導致用戶投訴。

8. 【推薦】類在設計與實現時要符合單一原則。

說明：單一原則最易理解卻是最難實現的一條規則，隨著系統演進，很多時候，忘記了類設計的初衷。

9. 【推薦】謹慎使用繼承的方式來進行擴展，優先使用聚合/組合的方式來實現。

說明：不得已使用繼承的話，必須符合里氏代換原則，此原則說父類能夠出現的地方子類一定能夠出現，比如，“把錢交出來”，錢的子類美元、歐元、人民幣等都可以出現。

10.【推薦】系統設計時，根據依賴倒置原則，盡量依賴抽象類與接口，有利于擴展與維護。

說明：低層次模塊依賴于高層次模塊的抽象，方便系統間的解耦。

11.【推薦】系統設計時，注意對擴展開放，對修改閉合。

說明：極端情況下，交付的代碼都是不可修改的，同一業務域內的需求變化，通過模塊或類的擴展來實現。

12.【推薦】系統設計階段，共性業務或公共行為抽取出來公共模塊、公共配置、公共類、公共方法等，避免出現重復代碼或重復配置的情況。

說明：隨著代碼的重復次數不斷增加，維護成本指數級上升。

13. 【推薦】避免如下誤解：敏捷開發 = 講故事 + 編碼 + 發布。

說明：敏捷開發是快速交付迭代可用的系統，省略多余的設計方案，摒棄傳統的審批流程，但核心關鍵點上的必要設計和文檔沉淀是需要的。

反例：某團隊為了業務快速發展，敏捷成了產品經理催進度的借口，系統中均是勉強能運行但

像面條一樣的代碼，可維護性和可擴展性極差，一年之后，不得不進行大規模重構，得不償失。

14.【參考】系統設計主要目的是明確需求、理順邏輯、后期維護，次要目的用于指導編碼。

說明：避免為了設計而設計，系統設計文檔有助于后期的系統維護，所以設計結果需要進行分類歸檔保存。

15.【參考】設計的本質就是識別和表達系統難點，找到系統的變化點，并隔離變化點。

說明：世間眾多設計模式目的是相同的，即隔離系統變化點。

16. 【參考】系統架構設計的目的：

l 確定系統邊界。確定系統在技術層面上的做與不做。

l 確定系統內模塊之間的關系。確定模塊之間的依賴關系及模塊的宏觀輸入與輸出。

l 確定指導后續設計與演化的原則。使后續的子系統或模塊設計在規定的框架內繼續演化。

確定非功能性需求。非功能性需求是指安全性、可用性、可擴展性等。