一、命名風格
- 【強制】類名使用 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,否則部分框架解析會引起序列化錯誤。
反例:定義爲基本數據類型 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 做前綴。
二、變量定義
- 【推薦】不要使用一個常量類維護所有常量,按常量功能進行歸類,分開維護。 說明:大而全的常量類,非得使用查找功能才能定位到修改的常量,不利於理解和維護。
正例:緩存相關常量放在類 CacheConsts 下;系統配置相關常量放在類 ConfigConsts 下。
三、代碼格式
- 【強制】大括號的使用約定。如果是大括號內爲空,則簡潔地寫成{}即可,不需要換行;如果 是非空代碼塊則:
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 格式。
- 【推薦】方法體內的執行語句組、變量的定義語句組、不同的業務邏輯之間或者不同的語義之間插入一個空行。相同業務邏輯和語義之間不需要插入空行。
說明:沒有必要插入多個空行進行隔開。
四、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 方法實現屬性對象 的拷貝。
五、集合處理
- 【強制】使用集合轉數組的方法,必須使用集合的 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 方式進行遍歷。
六、控制語句
- 【強制】在一個 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) 敏感權限入口。
七、註釋規約
- 【強制】類、類屬性、類方法的註釋必須使用 Javadoc 規範,使用/**內容*/ 格式,不得使用 // xxx 方式。
- 【強制】所有的抽象方法(包括接口中的方法)必須要用 Javadoc 註釋、除了返回值、參數、 異常說明外,還必須指出該方法做什麼事情,實現什麼功能。 說明:對子類的實現要求,或者調用注意事項,請一併說明。
- 【強制】所有的類都必須添加創建者和創建日期。
- 【強制】方法內部單行註釋,在被註釋語句上方另起一行,使用//註釋。方法內部多行註釋 使用/* */註釋,注意與代碼對齊。
- 【強制】所有的枚舉類型字段必須要有註釋,說明每個數據項的用途。
- 【推薦】代碼修改的同時,註釋也要進行相應的修改,尤其是參數、返回值、異常、核心邏輯 等的修改。 說明:代碼與註釋更新不同步,就像路網與導航軟件更新不同步一樣,如果導航軟件嚴重滯後, 就失去了導航的意義。
- 【參考】謹慎註釋掉代碼。在上方詳細說明,而不是簡單地註釋掉。如果無用,則刪除。
- 【參考】對於註釋的要求:第一、能夠準確反應設計思想和代碼邏輯;第二、能夠描述業務含 義,使別的程序員能夠迅速瞭解到代碼背後的信息。完全沒有註釋的大段代碼對於閱讀者形同 天書,註釋是給自己看的,即使隔很長時間,也能清晰理解當時的思路;註釋也是給繼任者看 的,使其能夠快速接替自己的工作。
- 【參考】好的命名、代碼結構是自解釋的,註釋力求精簡準確、表達到位。避免出現註釋的 一個極端:過多過濫的註釋,代碼的邏輯一旦修改,修改註釋是相當大的負擔。
- 【參考】特殊註釋標記,請註明標記人與標記時間。注意及時處理這些標記,通過標記掃描, 經常清理此類標記。線上故障有時候就是來源於這些標記處的代碼。
1) 待辦事宜(TODO):( 標記人,標記時間,[預計處理時間]) 表示需要實現,但目前還未實現的功能。這實際上是一個 Javadoc 的標籤,目前的 Javadoc 還沒有實現,但已經被廣泛使用。只能應用於類,接口和方法(因爲它是一個 Javadoc 標籤)。
2) 錯誤,不能工作(FIXME):(標記人,標記時間,[預計處理時間]) 在註釋中用 FIXME 標記某代碼是錯誤的,而且不能工作,需要及時糾正的情況。
八、其他
- 【強制】在使用正則表達式時,利用好其預編譯功能,可以有效加快正則匹配速度。 說明:不要在方法體內定義:Pattern pattern = Pattern.compile(規則);
- 【強制】注意 Math.random() 這個方法返回是 double 類型,注意取值的範圍 0≤x<1(能夠 取到零值,注意除零異常),如果想獲取整數類型的隨機數,不要將 x 放大 10 的若干倍然後 取整,直接使用 Random 對象的 nextInt 或者 nextLong 方法。
- 【強制】獲取當前毫秒數 System.currentTimeMillis(); 而不是 new Date().getTime();
- 【推薦】任何數據結構的構造或初始化,都應指定大小,避免數據結構無限增長吃光內存。
九、異常處理
- 【強制】捕獲異常是爲了處理它,不要捕獲了卻什麼都不處理而拋棄之,如果不想處理它,請 將該異常拋給它的調用者。最外層的業務使用者,必須處理異常,將其轉化爲用戶可以理解的 內容。
十、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,另外使用事務的地方需 要考慮各方面的回滾方案,包括緩存回滾、搜索引擎回滾、消息補償、統計修正等。