企業(yè)Java開(kāi)發(fā)規(guī)范

易族智匯Java開(kāi)發(fā)規(guī)范目錄前言 2一、 編程規(guī)約 3(一) 命名規(guī)約 3(二) 格式規(guī)約 5(三) 注解規(guī)約 6(四) 其它 7二、 異常日志 7(一) 異常處理 7(二) 日志規(guī)約 8三、 工程規(guī)約 8(一) 應(yīng)用分層 8四、 安全規(guī)約 9附1：版本歷史 10附2：常用單詞對(duì)照表 11前言《易族智匯Java開(kāi)發(fā)規(guī)范手冊(cè)》是公司技術(shù)團(tuán)隊(duì)的集體經(jīng)驗(yàn)總結(jié),現(xiàn)代軟件行業(yè)的高速發(fā)展對(duì)開(kāi)發(fā)者的綜合素質(zhì)要求越來(lái)越高,因?yàn)椴粌H是編程知識(shí)點(diǎn),其它維度的知識(shí)點(diǎn)也會(huì)影響到軟件的最終交付質(zhì)量。比如:數(shù)據(jù)庫(kù)的表結(jié)構(gòu)和索引設(shè)計(jì)缺陷可能帶來(lái)軟件上的架構(gòu)缺陷或性能風(fēng)險(xiǎn);工程結(jié)構(gòu)混亂導(dǎo)致后續(xù)維護(hù)艱難;沒(méi)有鑒權(quán)的漏洞代碼被黑客攻擊等等。所以本手冊(cè)以Java開(kāi)發(fā)者為中心視角,劃分為編程規(guī)約、異常日志規(guī)約、MySQL規(guī)約、工程規(guī)約、安全規(guī)約五大塊,再根據(jù)內(nèi)容特征,細(xì)分成若干二級(jí)子目錄。根據(jù)約束力強(qiáng)弱及故障敏感性,規(guī)約依次分為強(qiáng)制、推薦、參考三大類(lèi)。對(duì)于規(guī)約條目的延伸信息中,“說(shuō)明”對(duì)內(nèi)容做了引申和解釋;“正例”倡什么樣的編碼和實(shí)現(xiàn)方式;“反例”說(shuō)明需要防的雷區(qū),以及真實(shí)的錯(cuò)誤案例。本手冊(cè)的愿景是碼出質(zhì)量、碼出高效。代碼的字里行間流淌的是軟件生命中的血液,質(zhì)量的升是盡可能少踩坑,杜絕踩重復(fù)的坑,切實(shí)升質(zhì)量意識(shí)。另外,現(xiàn)代軟件架構(gòu)都需要協(xié)同開(kāi)發(fā)完成,高效協(xié)作即降低協(xié)同成本,升溝通效率,所謂無(wú)規(guī)矩不成方圓,無(wú)規(guī)范不能協(xié)作。眾所周知,制訂交通法規(guī)表面上是要限制行車(chē)權(quán),實(shí)際上是保障公眾的人身安全。試想如果沒(méi)有限速,沒(méi)有紅綠燈,誰(shuí)還敢上路行駛。對(duì)軟件來(lái)說(shuō),適當(dāng)?shù)囊?guī)范和標(biāo)準(zhǔn)絕不是消滅代碼內(nèi)容的創(chuàng)造性、優(yōu)雅性,而是限制過(guò)度個(gè)性化,以一種普遍認(rèn)可的統(tǒng)一方式一起做事,升協(xié)作效率。編程規(guī)約命名規(guī)約【強(qiáng)制】代碼中的命名均不能以下劃線(xiàn)或美元符號(hào)開(kāi)始,也不能以下劃線(xiàn)或美元符號(hào)結(jié)束。反例:_name/__name/$Object/name_/name$/Object$【強(qiáng)制】代碼中的命名嚴(yán)禁使用拼音與英文混合的方式,更不允許直接使用中文的方式。反例:DaZhePromotion[打折]/getPingfenByName()[評(píng)分]/int某變量=3正例:alibaba/taobao/youku/hangzhou等國(guó)際通用的名稱(chēng),可視同英文。【強(qiáng)制】類(lèi)名使用UpperCamelCase風(fēng)格,必須遵從駝峰形式。正例：MemberListManager?！緩?qiáng)制】方法名、參數(shù)名、成員變量、局部變量都統(tǒng)一使用lowerCamelCase風(fēng)格,必須遵從駝峰形式。正例:localValue/getHttpMessage()/inputUserId【強(qiáng)制】常量命名全部大寫(xiě),單詞間用下劃線(xiàn)隔開(kāi),力求語(yǔ)義表達(dá)完整清楚,不要嫌名字長(zhǎng)。正例:MAX_STOCK_COUNT反例:MAX_COUNT【強(qiáng)制】抽象類(lèi)命名使用Abstract或Base開(kāi)頭;異常類(lèi)命名使用Exception結(jié)尾;測(cè)試類(lèi)命名以它要測(cè)試的類(lèi)的名稱(chēng)開(kāi)始,以Test結(jié)尾?！緩?qiáng)制】中括號(hào)是數(shù)組類(lèi)型的一部分,數(shù)組定義如下:String[]args;反例:使用Stringargs[]的方式來(lái)定義?！緩?qiáng)制】包名統(tǒng)一使用小寫(xiě),點(diǎn)分隔符之間有且僅有一個(gè)自然語(yǔ)義的英語(yǔ)單詞。包名統(tǒng)一使用單數(shù)形式,但是類(lèi)名如果有復(fù)數(shù)含義,類(lèi)名可以使用復(fù)數(shù)形式。正例:應(yīng)用工具類(lèi)包名為com.alibaba.open.util、類(lèi)名為MessageUtils(此規(guī)則參考spring的框架結(jié)構(gòu))【強(qiáng)制】杜絕完全不規(guī)范的縮寫(xiě),避免望文不知義。反例:AbstractClass“縮寫(xiě)”命名成AbsClass;condition“縮寫(xiě)”命名成condi,此類(lèi)隨意縮寫(xiě)嚴(yán)重降低了代碼的可閱讀性?！緩?qiáng)制】對(duì)于Service和DAO類(lèi),基于SOA的理念,暴露出來(lái)的服務(wù)一定是接口,內(nèi)部的實(shí)現(xiàn)類(lèi)與接口用I的前綴區(qū)別。正例:MemberManager實(shí)現(xiàn)IMemberManager接口?！緩?qiáng)制】Controller類(lèi)為區(qū)分前臺(tái)商城和平臺(tái)管理調(diào)用的不同，前臺(tái)商城需要以ApiController結(jié)尾，平臺(tái)管理以Controller結(jié)尾。正例：前臺(tái)商城MemberApiController，平臺(tái)管理MemberController?！緩?qiáng)制】標(biāo)簽類(lèi)，全部以Tag結(jié)尾。正例：MemberListTag?！緩?qiáng)制】組件類(lèi)，全部以Component結(jié)尾正例：MemberComponent。【強(qiáng)制】插件類(lèi)，全部以Plugin結(jié)尾正例：MemberPointPlugin?！緩?qiáng)制】Controller類(lèi)中的方法，下面提供通用的方法名，如其他業(yè)務(wù)，請(qǐng)看10標(biāo)準(zhǔn)。add到添加頁(yè)edit到修改頁(yè)saveAdd保存添加saveEdit保存修改delete刪除list到列表頁(yè)listJson列表的json 【強(qiáng)制】Controller類(lèi)的RequestMapping的路徑格式?；驹瓌t：將駝峰命名改為以中橫線(xiàn)連接，將駝峰的大寫(xiě)母小寫(xiě)，注意不能以下劃線(xiàn)連接，如listJson，則訪(fǎng)問(wèn)路徑為：list-json。get-member?！緩?qiáng)制】各層命名規(guī)約Service/DAO層方法命名規(guī)約獲取單個(gè)對(duì)象的方法用get做前綴。獲取多個(gè)對(duì)象的方法用list做前綴。獲取統(tǒng)計(jì)值的方法用count做前綴。插入的方法用save(推薦)或insert做前綴。刪除的方法用remove(推薦)或delete做前綴。修改的方法用update做前綴。格式規(guī)約【強(qiáng)制】大括號(hào)的使用約定。如果是大括號(hào)內(nèi)為空,則簡(jiǎn)潔地寫(xiě)成{}即可,不需要換行;如果是非空代碼塊則:1)左大括號(hào)前不換行。2)左大括號(hào)后換行。3)右大括號(hào)前換行。4)右大括號(hào)后還有else等代碼則不換行;表示終止的右大括號(hào)后必須換行?！緩?qiáng)制】左小括號(hào)和右邊相鄰字符之間不出現(xiàn)空格;同樣,右小括號(hào)和左邊相鄰字符之間也不出現(xiàn)空格。詳見(jiàn)第5條下方正例提示?！緩?qiáng)制】if/for/while/switch/do等保留字與小括號(hào)之間都必須加空格?！緩?qiáng)制】任何運(yùn)算符左右必須加一個(gè)空格。說(shuō)明:運(yùn)算符包括賦值運(yùn)算符=、邏輯運(yùn)算符&&、加減乘除符號(hào)、三目運(yùn)算符等?！緩?qiáng)制】縮進(jìn)采用tab字符，禁止使用空格。正例:(涉及1-5點(diǎn))publicstaticvoidmain(String[]args){//縮進(jìn)1個(gè)tabStringsay="hello";//運(yùn)算符的左右必須有一個(gè)空格intflag=0;//關(guān)鍵詞if與括號(hào)之間必須有一個(gè)空格,括號(hào)內(nèi)的f與左括號(hào),0與右括號(hào)不需要空格if(flag==0){ System.out.println(say);}//左大括號(hào)前加空格且不換行;左大括號(hào)后換行if(flag==1){ System.out.println("world");//右大括號(hào)前換行,右大括號(hào)后有else,不用換行}else{System.out.println("ok");//在右大括號(hào)后直接結(jié)束,則必須換行}}【強(qiáng)制】單行字符數(shù)限制不超過(guò)120個(gè),超出需要換行,換行時(shí)遵循如下原則:1)第二行相對(duì)第一行縮進(jìn)1個(gè)TAB,從第三行開(kāi)始,不再繼續(xù)縮進(jìn),參考示例。2)運(yùn)算符與下文一起換行。3)方法調(diào)用的點(diǎn)符號(hào)與下文一起換行。4)在多個(gè)參數(shù)超長(zhǎng),逗號(hào)后進(jìn)行換行。5)在括號(hào)前不要換行,見(jiàn)反例。正例:StringBuffersb=newStringBuffer();//超過(guò)120個(gè)字符的情況下,換行縮進(jìn)1個(gè)TAB,并且方法前的點(diǎn)符號(hào)一起換行sb.append("zi").append("xin")append("huang")append("huang")append("huang");反例:StringBuffersb=newStringBuffer();//超過(guò)120個(gè)字符的情況下,不要在括號(hào)前換行sb.append("zi").append("xin")...append("huang");//參數(shù)很多的方法調(diào)用可能超過(guò)120個(gè)字符,不要在逗號(hào)前換行method(args1,args2,args3,...,argsX);【強(qiáng)制】方法參數(shù)在定義和傳入時(shí),多個(gè)參數(shù)逗號(hào)后邊必須加空格。正例：下例中實(shí)參的"a",后邊必須要有一個(gè)空格。method("a","b","c");注解規(guī)約【強(qiáng)制】類(lèi)、類(lèi)屬性、類(lèi)方法的注釋必須使用Javadoc規(guī)范, 使用/**內(nèi)容*/格式,不得使用//xxx方式。說(shuō)明：在IDE編輯窗口中,Javadoc方式會(huì)提示相關(guān)注釋,生成Javadoc可以正確輸出相應(yīng)注釋;在IDE中,工程調(diào)用方法時(shí),不進(jìn)入方法即可懸浮提示方法、參數(shù)、返回值的意義,提高閱讀效率?！緩?qiáng)制】所有的抽象方法(包括接口中的方法)必須要用Javadoc注釋、除了返回值、參數(shù)、異常說(shuō)明外,還必須指出該方法做什么事情,實(shí)現(xiàn)什么功能。說(shuō)明：對(duì)子類(lèi)的實(shí)現(xiàn)要求,或者調(diào)用注意事項(xiàng),請(qǐng)一并說(shuō)明?！緩?qiáng)制】所有的類(lèi)都必須添加創(chuàng)建者和創(chuàng)建日期?！緩?qiáng)制】方法內(nèi)部單行注釋,在被注釋語(yǔ)句上方另起一行,使用//注釋。方法內(nèi)部多行注釋使用/**/注釋?zhuān)⒁馀c代碼對(duì)齊。【強(qiáng)制】所有的枚舉類(lèi)型字段必須要有注釋,說(shuō)明每個(gè)數(shù)據(jù)項(xiàng)的用途。【推薦】與其“半吊子”英文來(lái)注釋,不如用中文注釋把問(wèn)題說(shuō)清楚。專(zhuān)有名詞與關(guān)鍵字保持英文原文即可。反例:“TCP連接超時(shí)”解釋成“傳輸控制協(xié)議連接超時(shí)”,理解反而費(fèi)腦筋?！就扑]】代碼修改的同時(shí),注釋也要進(jìn)行相應(yīng)的修改,尤其是參數(shù)、返回值、異常、核心邏輯等的修改。說(shuō)明：代碼與注釋更新不同步,就像路網(wǎng)與導(dǎo)航軟件更新不同步一樣,如果導(dǎo)航軟件嚴(yán)重滯后,就失去了導(dǎo)航的意義。其它【強(qiáng)制】SVN目錄規(guī)范，兩個(gè)主目錄。產(chǎn)品：/product，項(xiàng)目：/project若有新產(chǎn)品或者新項(xiàng)目則在對(duì)應(yīng)的主目錄下創(chuàng)建子目錄。每個(gè)產(chǎn)品或項(xiàng)目結(jié)構(gòu)的規(guī)范：+trunk/+branches/+dev_1.0+tags/+release_1.0 說(shuō)明；trunk：主開(kāi)發(fā)分支：正在開(kāi)發(fā)中的主分支branches:一些特殊開(kāi)發(fā)需要的分支，和主分支并行開(kāi)發(fā)用，命名規(guī)范為“dev_”開(kāi)頭，連接本分支有意義的單詞或拼音，如“dev_tongji”tags：定版的，命名規(guī)則：“release_版本號(hào)”異常日志異常處理【強(qiáng)制】Java類(lèi)庫(kù)中定義的一類(lèi)RuntimeException可以通過(guò)預(yù)先檢查進(jìn)行規(guī)避,而不應(yīng)該通過(guò)catch來(lái)處理,比如:IndexOutOfBoundsException,NullPointerException等等。說(shuō)明:無(wú)法通過(guò)預(yù)檢查的異常除外,如在解析一個(gè)外部傳來(lái)的字符串形式數(shù)字時(shí),通過(guò)catchNumberFormatException來(lái)實(shí)現(xiàn)。正例：if(obj!=null){...}反例：try{obj.method()}catch(NullPointerExceptione){...}【強(qiáng)制】異常不要用來(lái)做流程控制,條件控制,因?yàn)楫惓５奶幚硇时葪l件分支低?！緩?qiáng)制】對(duì)大段代碼進(jìn)行try-catch,這是不負(fù)責(zé)任的表現(xiàn)。catch時(shí)請(qǐng)分清穩(wěn)定代碼和非穩(wěn)定代碼,穩(wěn)定代碼指的是無(wú)論如何不會(huì)出錯(cuò)的代碼。對(duì)于非穩(wěn)定代碼的catch盡可能進(jìn)行區(qū)分異常類(lèi)型,再做對(duì)應(yīng)的異常處理。【強(qiáng)制】捕獲異常是為了處理它,不要捕獲了卻什么都不處理而拋棄之,如果不想處理它,請(qǐng)將該異常拋給它的調(diào)用者。最外層的業(yè)務(wù)使用者,必須處理異常,將其轉(zhuǎn)化為用戶(hù)可以理解的內(nèi)容。【強(qiáng)制】有try塊放到了事務(wù)代碼中,catch異常后,如果需要回滾事務(wù),一定要注意手動(dòng)回滾事務(wù)?！緩?qiáng)制】finally塊必須對(duì)資源對(duì)象、流對(duì)象進(jìn)行關(guān)閉,有異常也要做try-catch。說(shuō)明:如果JDK7及以上,可以使用try-with-resources方式?！緩?qiáng)制】不能在finally塊中使用return,finally塊中的return返回后方法結(jié)束執(zhí)行,不會(huì)再執(zhí)行try塊中的return語(yǔ)句?！緩?qiáng)制】捕獲異常與拋異常,必須是完全匹配,或者捕獲異常是拋異常的父類(lèi)。說(shuō)明:如果預(yù)期對(duì)方拋的是繡球,實(shí)際接到的是鉛球,就會(huì)產(chǎn)生意外情況?！就扑]】防止NPE,是程序員的基本修養(yǎng),注意NPE產(chǎn)生的場(chǎng)景:返回類(lèi)型為基本數(shù)據(jù)類(lèi)型,return包裝數(shù)據(jù)類(lèi)型的對(duì)象時(shí),自動(dòng)拆箱有可能產(chǎn)生NPE。反例:publicintf(){returnInteger對(duì)象},如果為null,自動(dòng)解箱拋NPE。數(shù)據(jù)庫(kù)的查詢(xún)結(jié)果可能為null。集合里的元素即使isNotEmpty,取出的數(shù)據(jù)元素也可能為null。遠(yuǎn)程調(diào)用返回對(duì)象時(shí),一律要求進(jìn)行空指針判斷,防止NPE。對(duì)于Session中獲取的數(shù)據(jù),建議NPE檢查,避免空指針。級(jí)聯(lián)調(diào)用obj.getA().getB().getC();一連串調(diào)用,易產(chǎn)生NPE。正例：可以使用JDK8的Optional類(lèi)來(lái)防止NPE問(wèn)題。日志規(guī)約【強(qiáng)制】應(yīng)用中需要記錄日志，使用日志系統(tǒng)Log4j中的API，記錄日志。Importorg.apache.log4j.Logger;privatefinalLoggerlogger=Logger.getLogger(getClass());工程規(guī)約應(yīng)用分層【推薦】圖中默認(rèn)上層依賴(lài)于下層，箭頭關(guān)系表示可直接依賴(lài)。如開(kāi)放接口層可以依賴(lài)于Controller層，也可以直接依賴(lài)Managet層，以此類(lèi)推：開(kāi)放接口層：可直接封裝Manager方法暴露成RPC接口。終端顯示器：各個(gè)端的模板渲染并執(zhí)行顯示的層。當(dāng)前主要是fr