JAVA編碼規(guī)范

1、JAVA編碼規(guī)范移動(dòng)產(chǎn)品研發(fā)部 概述概述編寫目的預(yù)期讀者 重要規(guī)范重要規(guī)范操作規(guī)范日志規(guī)范異常處理安全規(guī)范 命名規(guī)范命名規(guī)范包命名規(guī)則類接口命名規(guī)則方法命名規(guī)則變量命名規(guī)則常量命名規(guī)則 注釋規(guī)范注釋規(guī)范注釋的介紹類注釋規(guī)范方法注釋規(guī)范程序塊注釋規(guī)范廢棄代碼注釋保留特殊代碼注釋規(guī)范 其他規(guī)范和實(shí)踐其他規(guī)范和實(shí)踐目錄目錄p1.1編寫目的本文描述了JAVA開(kāi)發(fā)中的一些需要注意的編程規(guī)范和經(jīng)驗(yàn)，以及可以增強(qiáng)代碼可讀性的包、類、接口、方法、等的命名規(guī)則和注釋規(guī)范，文檔最后還介紹了一些編程的實(shí)踐和技巧。p1.2預(yù)期讀者和適用范圍開(kāi)發(fā)組全體成員。適用于開(kāi)發(fā)組所有基于JAVA開(kāi)發(fā)的項(xiàng)目。第一章概述p2.1操作

2、規(guī)范1、SVN代碼提交為防止代碼沖突，在提交代碼前必須先更新代碼，然后再提交自己新加的代碼，提交時(shí)必須添加本次變更注釋。當(dāng)多個(gè)文件有變更時(shí)，要成批一次性提交代碼，不允許一次單個(gè)文件提交。如果更新后代碼有沖突，要及時(shí)找相關(guān)人員共同解決沖突，堅(jiān)決不允許私自刪除或覆蓋其他人的代碼。2、垃圾清理對(duì)于項(xiàng)目改造或變更后，項(xiàng)目中沒(méi)有用到的類、方法、變量、配置和引用（import）要及時(shí)清理掉。第二章重要規(guī)范p2.2日志規(guī)范1、日志輸出（1）日志輸出統(tǒng)一使用logger進(jìn)行輸出，不允許使用System.out形式輸出；（ 2 ）日志輸出內(nèi)容必須與系統(tǒng)中原日志輸出格式保持一致；（ 3 ）每條日志輸出都必須以日志

3、跟蹤號(hào)開(kāi)頭correlationIDxxx，并且保持一個(gè)請(qǐng)求的的correlationID一致，對(duì)于有會(huì)話session的交易，要保持整個(gè)session的correlationID一致；（ 4 ）內(nèi)部dubbo系統(tǒng)調(diào)用異常必須捕獲處理，并輸出日志；（ 5 ）客戶端，通過(guò)對(duì)象交互的交易接口中，可在調(diào)用關(guān)鍵接口完成后，輸出retcode及retmsg；通過(guò)json或xml為數(shù)據(jù)交換的接口中，輸出請(qǐng)求及響應(yīng)報(bào)文；第二章重要規(guī)范（ 6 ）服務(wù)端，對(duì)關(guān)鍵交易請(qǐng)求要素進(jìn)行日志輸出，交易處理完成后輸出處理結(jié)果；（ 7 ）和外部系統(tǒng)交互，可將日志輸出詳細(xì)些，日志中盡量包括：請(qǐng)求地址、內(nèi)容、http響應(yīng)碼等狀態(tài)

4、信息、外部系統(tǒng)響應(yīng)內(nèi)容等信息；（ 8 ）數(shù)據(jù)庫(kù)操作，捕獲SQLException并對(duì)異常進(jìn)行輸出，可增加數(shù)據(jù)庫(kù)操作錯(cuò)誤排查；（ 9 ）捕獲異常后要對(duì)異常信息輸出ERROR級(jí)別的日志，輸出示例：logger.error(“XXX操作異常：”+e.getMassage(),e);（ 10 ） ERROR級(jí)別日志輸出一般原則：對(duì)于由于系統(tǒng)原因造成業(yè)務(wù)處理失敗的事件，需要記錄錯(cuò)誤日志。非系統(tǒng)原因的業(yè)務(wù)處理失敗，不應(yīng)該記錄錯(cuò)誤日志（推薦使用warn級(jí)別），避免錯(cuò)誤日志過(guò)大，影響緊急情況下的故障分析和診斷；第二章重要規(guī)范2、記錄操作日志對(duì)于商戶/用戶密碼變更，訂單/支付單狀態(tài)變更等安全性要求較高的操作，需

5、要調(diào)用logServer添加操作日志。日志內(nèi)容應(yīng)該包括關(guān)鍵要素，方便后續(xù)追蹤。3、用戶敏感信息保護(hù) 用戶的敏感信息包括：密碼、短信驗(yàn)證碼、支付驗(yàn)證碼、身份證號(hào)、銀行卡號(hào)、信用卡CVV碼、信用卡有效期、銀行密鑰，商戶密鑰等信息；用戶敏感信息不能泄露，否則可能會(huì)帶來(lái)不安全因素。 可能會(huì)導(dǎo)致敏感信息泄露的方式有：Logger、URL的get參數(shù)QQ聊天（在為商戶客服或技術(shù)解答問(wèn)題時(shí)，如果需要回復(fù)身份證號(hào)、信用卡CVV碼、信用卡有效期、商戶密鑰等敏感數(shù)據(jù)時(shí)，要加*處理或單獨(dú)私聊）。另外，項(xiàng)目中使用的log4j包是經(jīng)過(guò)改造擴(kuò)展后的日志輸出jar包，會(huì)根據(jù)log4j.xml的配置內(nèi)容，自動(dòng)對(duì)一些敏感信息進(jìn)

6、行加*處理。第二章重要規(guī)范p2.3異常處理1、java異常的體系結(jié)構(gòu) Java把異常當(dāng)作對(duì)象來(lái)處理，并定義一個(gè)基類java.lang.Throwable作為所有異常的超類。 在Java API中已經(jīng)定義了許多異常類，這些異常類分為兩大類，錯(cuò)誤Error和異常Exception。在Java中，異常分為受檢查的異常,與運(yùn)行時(shí)異常. 兩者都在異常類層次結(jié)構(gòu)中。 Java異常體系結(jié)構(gòu)呈樹(shù)狀，其層次結(jié)構(gòu)圖如圖所示：第二章重要規(guī)范第二章重要規(guī)范 受檢查的異常：粉紅色的是受檢查的異常(checked exceptions),其必須被 trycatch語(yǔ)句塊所捕獲,或者在方法簽名里通過(guò)throws子句聲明.受

7、檢查的異常必須在編譯時(shí)被捕捉處理，命名為 CHecked Exception 是因?yàn)镴ava編譯器要進(jìn)行檢查,Java虛擬機(jī)也要進(jìn)行檢查,以確保這個(gè)規(guī)則得到遵守。 運(yùn)行時(shí)異常：綠色的異常是運(yùn)行時(shí)異常(runtime exceptions)，需要程序員自己分析代碼決定是否捕獲和處理,比如 空指針,被0除. 而聲明為Error的，則屬于嚴(yán)重錯(cuò)誤，需要根據(jù)業(yè)務(wù)信息進(jìn)行特殊處理,Error不需要捕捉。第二章重要規(guī)范2、異常的捕獲 受檢查的異常必須捕獲，捕獲后輸出ERROR級(jí)別的日志。 調(diào)用子系統(tǒng)服務(wù)必須捕獲異常，捕獲后輸出ERROR級(jí)別的日志。 對(duì)于運(yùn)行時(shí)異常，要認(rèn)真分析是否有必要進(jìn)行捕獲，捕獲后輸出

8、ERROR級(jí)別的日志。 ERROR級(jí)別的日志輸出示例：logger.error(“XXX操作異常:” +e.getMassage(),e);第二章重要規(guī)范p2.4安全規(guī)范1、WEB安全規(guī)范 對(duì)于前臺(tái)的web頁(yè)面，必須加上表單防重復(fù)提交功能。 對(duì)于業(yè)務(wù)關(guān)鍵字段（用戶編號(hào)、支付單號(hào)、支付金額等）需要加上防篡改的功能，否則可能被客戶端惡意修改。 對(duì)于前臺(tái)的web頁(yè)面，嚴(yán)禁出現(xiàn)方便調(diào)試的后門頁(yè)面。2、其他安全規(guī)范 對(duì)系統(tǒng)資源的訪問(wèn)，使用后必須釋放系統(tǒng)資源。這類資源包括：文件流、線程、網(wǎng)絡(luò)連接、數(shù)據(jù)庫(kù)連接等。 對(duì)于文件、流的IO操作，必須通過(guò)finally關(guān)閉。 對(duì)于線程，線程資源必須通過(guò)線程池提供，不

9、允許在應(yīng)用中自行顯式創(chuàng)建線程。 對(duì)于網(wǎng)絡(luò)連接與數(shù)據(jù)庫(kù)連接，必須由框架通過(guò)連接池提供，不允許應(yīng)用中自行建立網(wǎng)絡(luò)與數(shù)據(jù)庫(kù)連接。 對(duì)于大批量數(shù)據(jù)的處理，要考慮是否可能會(huì)導(dǎo)致系統(tǒng)出現(xiàn)內(nèi)存不足，最好的解決方式是采用分批處理。 避免將URL、文件名、系統(tǒng)開(kāi)關(guān)參數(shù)、業(yè)務(wù)規(guī)則的可變參數(shù)等硬編碼。 第二章重要規(guī)范p3、1包命名規(guī)則 java開(kāi)發(fā)中產(chǎn)生的包分為兩類，一類是與各業(yè)務(wù)系統(tǒng)相關(guān)的包；另一類是與業(yè)務(wù)系統(tǒng)無(wú)關(guān)的、可公用的包。規(guī)則：包名應(yīng)全部是小寫字母;包名中不能出現(xiàn)下劃線和其他特殊字符;第一個(gè)字母不能是數(shù)字。示例：與業(yè)務(wù)系統(tǒng)相關(guān)的包命名格式為：com. lianpay. 其中：為項(xiàng)目英文簡(jiǎn)稱或縮寫；為模塊英

10、文名稱或簡(jiǎn)稱，如果無(wú)細(xì)分模塊的話可省略模塊名。與業(yè)務(wù)系統(tǒng)無(wú)關(guān)的、可公用的包：com. lianpay.share./所有項(xiàng)目通用第三章命名規(guī)范p3.2類接口命名規(guī)則規(guī)則：類的名稱應(yīng)使用名詞；類和接口首字母必須大寫，每個(gè)單詞的首字母應(yīng)大寫（駱駝法則）；接口名稱應(yīng)以大寫I開(kāi)始，接口實(shí)現(xiàn)類以Impl結(jié)尾。示例：public class UserBase;/類public interface IUserBaseService; /接口public class UserBaseServiceImpl implements IUserBaseService; /接口實(shí)現(xiàn)類第三章命名規(guī)范p3.3方法命名規(guī)則

11、規(guī)則：方法名應(yīng)是一個(gè)動(dòng)詞或動(dòng)名結(jié)構(gòu)；方法名首字母應(yīng)使用小寫，其后每個(gè)單詞的首字母大寫（駱駝法則）；方法返回類型boolean類型時(shí)，一般以is作為前綴。示例：getUserBase();boolean isValid();第三章命名規(guī)范p3.4變量命名規(guī)則規(guī)則:變量命名首字母小寫，其后單詞的首字母大寫（駱駝法則）;變量名一般不要用數(shù)字、下劃線、$等特殊字符開(kāi)頭；變量名應(yīng)簡(jiǎn)短且有意義，即，能夠指出其用途，不要像出現(xiàn)a、b、str這樣的命名。采用該領(lǐng)域的術(shù)語(yǔ)對(duì)變量進(jìn)行命名。對(duì)于集合或數(shù)組類型的變量，可以使用其復(fù)數(shù)形式命名。示例：String fileName;String fileNames;Li

12、st fileList;第三章命名規(guī)范兩變量比較時(shí)，變量命令盡可能具有意義。String version;String serverVersion；/ 避免使用 version1String clientVersion；/避免使用version2第三章命名規(guī)范字段字段類型類型firstName字符串字符串 address 地址對(duì)象地址對(duì)象 persistent 布爾值布爾值 customerNo 整型整型orderItems OrderItem的對(duì)象數(shù)組的對(duì)象數(shù)組 p3.5常量命名規(guī)則常量名所有字母全部大寫，單詞間以_隔開(kāi)。public static final String TRANS_QU

13、ERY_RESULT_LIST = result;第三章命名規(guī)范p4.1注釋的介紹在Java程序的編寫過(guò)程中我們需要對(duì)一些程序進(jìn)行注釋，除了自己方便閱讀，更為別人更好理解自己的程序，所以我們需要進(jìn)行一些注釋，可以是編程思路或者是程序的作用，總而言之就是方便自己他人更好的閱讀。對(duì)于Java注釋主要有三種：1、/ 注釋一行2、/* . */ 注釋若干行3、/*/文檔注釋（javadoc提取注釋的工具/*注釋內(nèi)容*/）第四章注釋規(guī)范p4.2類注釋規(guī)范1、添加注釋模板（1）在MyEclipse中，打開(kāi)Window-Preference-Java-Code Style-Code Template-Com

14、ments-Types（2）參照（3）注釋規(guī)范，點(diǎn)擊Edit.對(duì)應(yīng)設(shè)置即可。（3）注釋規(guī)范：/* * Copyright: 連連銀通電子支付有限公司 * Description: $todo(用一句話描述該類做什么) * author: guoyx * date: $date $time * version: V1.0 */第四章注釋規(guī)范2、配置自動(dòng)注釋（1）在MyEclipse中，打開(kāi)Window-Preference-Java-Code Style-Code Template-Code-New Java files（2）參照（3）注釋規(guī)范，點(diǎn)擊Edit.對(duì)應(yīng)設(shè)置即可。（3）注釋規(guī)范：$fi

15、lecomment$package_declaration/* * Copyright: 連連銀通電子支付有限公司 * Description: $todo(用一句話描述該類做什么) * author: guoyx * date: $date $time * version: V1.0 */$typecomment$type_declaration第四章注釋規(guī)范p4.3方法注釋1、添加注釋模板1、在MyEclipse中，打開(kāi)Window-Preference-Java-Code Style-Code Template-Comments-Methods2、參照（3）注釋規(guī)范，點(diǎn)擊Edit.對(duì)應(yīng)設(shè)

16、置即可。3、注釋規(guī)范：/* * Title: $enclosing_method * Description: $todo(這里用一句話描述這個(gè)方法的作用) * param: $tags * return: $return_type * throws */第四章注釋規(guī)范p4.4程序塊注釋規(guī)范注釋要點(diǎn)：語(yǔ)句和程序塊的注釋要在被說(shuō)明語(yǔ)句的上面行書寫，縮進(jìn)方式與被說(shuō)明語(yǔ)句相同；對(duì)不易理解的分支條件表達(dá)式加注釋；復(fù)雜的循環(huán)，說(shuō)明出口條件；過(guò)長(zhǎng)的方法實(shí)現(xiàn)，按功能實(shí)現(xiàn)進(jìn)行分段概括說(shuō)明；示例：第四章注釋規(guī)范p4.5廢棄代碼注釋保留注解要點(diǎn)：用“ /* */ ”實(shí)現(xiàn)廢棄代碼保留，不允許使用“ / ”；盡量完整

17、的將代碼注釋掉，最好完整的注釋掉一個(gè)程序段；請(qǐng)說(shuō)明注釋掉的原因、人員和時(shí)間；示例：第四章注釋規(guī)范p4.6特殊代碼注釋代碼質(zhì)量不好但能正常運(yùn)行，或者還沒(méi)有實(shí)現(xiàn)的代碼用/TODO: 聲明存在錯(cuò)誤隱患的代碼用/FIXME:聲明示例：第四章注釋規(guī)范p5.1其他規(guī)范if語(yǔ)句中（即使無(wú)else子句，即使只有一句代碼），也要將語(yǔ)句體中的代碼用大括弧“”括起來(lái)。函數(shù)的長(zhǎng)度要控制在100語(yǔ)句行以內(nèi)（不包括注釋），程序有特殊要求時(shí)（如速度要求等）可以例外。在一個(gè)程序段完成后，加入一個(gè)空行，增加可讀寫性。盡可能利用括號(hào)表示表達(dá)式之間的優(yōu)先級(jí)，即使它對(duì)你而言是理所當(dāng)然的，要知道， 別人的水平可能不如你。即使不加括號(hào)時(shí)

18、運(yùn)算順序不會(huì)改變，也應(yīng)當(dāng)用括號(hào)確定表達(dá)式的操作順序。例如： if (a = b & c = d) / AVOID if (a = b) & (c = d) / GOOD 第五章其他規(guī)范和實(shí)踐其他規(guī)范和實(shí)踐如果三元表達(dá)式的判斷條件是一段子語(yǔ)句，請(qǐng)使用括號(hào)： (null= user) ?”不存在” : “存在”; 不要在循環(huán)內(nèi)執(zhí)行重復(fù)操作?？稍谘h(huán)外調(diào)用一次的，就避免在循環(huán)內(nèi)進(jìn)行不必要的反復(fù)調(diào)用。示例： for (int i = 0; i signedList.size(); i+) 應(yīng)寫成： int size = signedList.size (); for (int i = 0; i size; i+) 在對(duì)字符串有較多附加操作時(shí)，使用StringBuffer而非String。使用StringBuffer性能會(huì)好很多。 if.esle.(盡量少用else，更要避免嵌套的情況出現(xiàn))。第五章其他規(guī)范和實(shí)踐其他規(guī)范和實(shí)踐p5.2Eclipse常用快捷鍵書寫常用：CTRL+C：復(fù)制 CTRL+V：粘貼CTRL+X：切剪 CTRL+A：全選 CTRL+F：查找 或替換CTRL+Z：撤銷 CTRL+Y：重做 CTRL+S：保存CTRL+D: 刪除當(dāng)前行CTRL+/