XX公司Java開發(fā)規(guī)范v1_0

1、Java開發(fā)規(guī)范xxxxJava開發(fā)規(guī)范目錄前言21、 編程規(guī)約3（一）命名規(guī)約 3（二）格式規(guī)約 5（三）注解規(guī)約 6（四）其它 72、 異常日志7（1） 異常處理 7（2） 日志規(guī)約 83、 工程規(guī)約8（一）應(yīng)用分層 84、 安全規(guī)約9附1:版本歷史 11附2:常用單詞對(duì)照表11、/ 、 刖百XXXXJava開發(fā)規(guī)范手冊(cè)是公司技術(shù)團(tuán)隊(duì)的集體經(jīng)驗(yàn)總結(jié)，現(xiàn)代軟件行業(yè) 的高速發(fā)展對(duì)開發(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)的漏洞

2、代碼 被黑客攻擊等等。所以本手冊(cè)以 Java開發(fā)者為中心視角, 劃分為編程規(guī)約、異常日志 規(guī)約、MySQL規(guī)約、工程規(guī)約、安全規(guī)約五大塊， 再根據(jù)內(nèi)容特征，細(xì)分成若干二級(jí)子目錄。根據(jù)約束力強(qiáng)弱及故障敏感性，規(guī)約依 次分為強(qiáng)制、推薦、參考三大類。對(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é)同開發(fā)完成，高效協(xié)作即降低協(xié)同成本，升溝通效率，所

3、謂無(wú)規(guī) 矩不成方圓，無(wú)規(guī)范不能協(xié)作。眾所周知，制訂交通法規(guī)表面上是要限制行車權(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ī)約1 .【強(qiáng)制】 代碼中的命名均不能以 下劃線或美元符號(hào) 開始,也不能以下劃線或美 元符號(hào)結(jié)束。反例： _name / _name / $Object / name_ / name$ / Object$2 .【強(qiáng)制】 代碼中的命名嚴(yán)禁使用拼音與英文混合的方式，更不允許直接使用中文的方式。反

4、例：DaZhePromotion 打折/getPingfenByName()評(píng)分/int 某變量 =3 正例：alibaba / taobao / youku / hangzhou 等國(guó)際通用的名稱，可視同英文。3 .【強(qiáng)制】類名使用UpperCamelCase風(fēng)格，必須遵從駝峰形式正例：MemberListManager。4 .【強(qiáng)制】方法名、參數(shù)名、成員變量、局部變量都統(tǒng)一使用lowerCamelCase風(fēng)格，必須遵從 駝峰形式。正例：localValue / getHttpMessage()/ inputUserId5 .【強(qiáng)制】常量命名全部大寫，單詞間用下劃線隔開，力求語(yǔ)義表達(dá)完整清

5、楚，不要嫌名字長(zhǎng)。正例：MAX_STOCK_COUNT反例：MAX_COUNT6 .【強(qiáng)制】抽象類命名使用Abstract或Base開頭；異常類命名使用Exception結(jié)尾;測(cè)試類 命名以它要測(cè)試的類的名稱開始，以Test結(jié)尾。7 .【強(qiáng)制】中括號(hào)是數(shù)組類型的一部分，數(shù)組定義如下String口 args;反例:使用String args口的方式來(lái)定義。8 .【強(qiáng)制】包名統(tǒng)一使用小寫，點(diǎn)分隔符之間有且僅有一個(gè)自然語(yǔ)義的英 語(yǔ)單詞。包名統(tǒng)一使用單數(shù)形式，但是類名如果有復(fù)數(shù)含義，類名可以使 用復(fù)數(shù)形式。正例：應(yīng)用工具類包名為 com.alibaba.open.util、類名為 MessageUti

6、ls(t匕 規(guī)則參考spring的框架結(jié)構(gòu))9 .【強(qiáng)制】杜絕完全不規(guī)范的縮寫，避免望文不知義。反例：AbstractClass縮寫”命名成 AbsClass;condition縮寫”命名成 condi, 此類 隨意縮寫嚴(yán)重降低了代碼的可閱讀性。10 .【強(qiáng)制】對(duì)于Service和DAO類，基于SOA的理念，暴露出來(lái)的服務(wù)一 定是接口，內(nèi)部的實(shí)現(xiàn)類與接口用I的前綴區(qū)別。正例：MemberManager 實(shí)現(xiàn) IMemberManager 接口。11 .【強(qiáng)制】Controller類為區(qū)分前臺(tái)商城和平臺(tái)管理調(diào)用的不同，前臺(tái)商 城需要以ApiController結(jié)尾，平臺(tái)管理以Controller

7、結(jié)尾。正例：前臺(tái)商城 MemberApiController,平臺(tái)管理 MemberController。12 .【強(qiáng)制】標(biāo)簽類，全部以Tag結(jié)尾。正例： MemberListTag13 .【強(qiáng)制】組件類，全部以 Component結(jié)尾正例： MemberComponent。14 .【強(qiáng)制】插件類，全部以Plugin結(jié)尾正例： MemberPointPlugin。15 .【強(qiáng)制】Controller類中的方法，下面提供通用的方法名，如其他業(yè)務(wù), 請(qǐng)看10標(biāo)準(zhǔn)。add到添加頁(yè)edit到修改頁(yè)saveAdd保存添加saveEdit保存修改delete刪除list到列表頁(yè)listJson列表的jso

8、n16 .【強(qiáng)制】Controller類的RequestMapping的路徑格式。基本原則：將駝峰命名改為以中橫線連接，將駝峰的大寫母小寫，注意不能以下劃線連接，如listJson,則訪問(wèn)品&徑為：list-json。為區(qū)分前臺(tái)商城和平臺(tái)后臺(tái)的區(qū)別正例：前臺(tái)商城路徑規(guī)范：/api/應(yīng)用名路徑/業(yè)務(wù)名/方法名.do正例：平臺(tái)后臺(tái)路徑規(guī)范：/應(yīng)用名路徑/admin/業(yè)務(wù)名/方法名.do17 .【強(qiáng)制】Controller類中方法的RequestMapping的路徑格式?；驹瓌t：將駝峰命名改為以中橫線連接，將駝峰的大寫母小寫，注意 不能以下劃線連接。正例：如方法名為 getMember,Reque

9、stMapping路徑貝U為 get-member。18 .【強(qiáng)制】各層命名規(guī)約a) Service/DAO層方法命名規(guī)約1)獲取單個(gè)對(duì)象的方法用get做前綴。2)3)4)5)6)獲取多個(gè)對(duì)象的方法用list做前綴。獲取統(tǒng)計(jì)值的方法用count做前綴。插入的方法用save/隹薦)或insert做前綴。刪除的方法用remove(推薦)或delete做前綴。修改的方法用update做前綴。(二)格式規(guī)約1 .【強(qiáng)制】大括號(hào)的使用約定。如果是大括號(hào)內(nèi)為空，則簡(jiǎn)潔地寫成即可, 不需要換行；如果是非空代碼塊則：1)左大括號(hào)前不換行。2)左大括號(hào)后換行。3)右大括號(hào)前換行。4)右大括號(hào)后還有else等代碼

10、則不換行；表示終止的右大括號(hào)后必須 換行。2 .【強(qiáng)制】左小括號(hào)和右邊相鄰字符之間不出現(xiàn)空格；同樣,右小括號(hào)和左邊相鄰字符之間也不出現(xiàn)空格。詳見第5條下方正例提示。3 .【強(qiáng)制】if/for/while/switch/do 等保留字與小括號(hào)之間都必須加空格。4 .【強(qiáng)制】任何運(yùn)算符左右必須加一個(gè)空格。說(shuō)明:運(yùn)算符包括賦值運(yùn)算符=、邏輯運(yùn)算符&、加減乘除符號(hào)、三目運(yùn)5 .【強(qiáng)制】縮進(jìn)采用tab字符，禁止使用空格。正例：(涉及1-5點(diǎn))public static void main(String口 args) /縮進(jìn)1個(gè)tabString say = hello;/運(yùn)算符的左右必須有一個(gè)空格int

11、 flag = 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é)束，則必須換行6 .【強(qiáng)制】單行字符數(shù)限制不超過(guò)120個(gè),超出需要換行，換行時(shí)遵循如下 原則：1)第二行相對(duì)第一行縮進(jìn)1個(gè)TAB從第三行開始，不再繼續(xù)縮進(jìn)，參考示例。2)運(yùn)算符

12、與下文一起換行。3)方法調(diào)用的點(diǎn)符號(hào)與下文一起換行。4)在多個(gè)參數(shù)超長(zhǎng)，逗號(hào)后進(jìn)行換行。5)在括號(hào)前不要換行，見反例。正例：StringBuffer sb = new StringBuffer();超過(guò)120個(gè)字符的情況下，換行縮進(jìn)1個(gè)TAB并且方法前的點(diǎn)符號(hào)一起換行sb.append(zi).append(xin).append(huang).append(huang).append(huang);反例：StringBuffer sb = new StringBuffer();超過(guò)120個(gè)字符的情況下，不要在括號(hào)前換行sb.append(zi).append(xin)append(huang

13、);/參數(shù)很多的方法調(diào)用可能超過(guò)120個(gè)字符，不要在逗號(hào)前換行method(args1, args2, args3,argsX);7 .【強(qiáng)制】方法參數(shù)在定義和傳入時(shí)，多個(gè)參數(shù)逗號(hào)后邊必須加空格。正例：下例中實(shí)參的a”,后邊必須要有一個(gè)空格。 method(a, b, c);(三)注解規(guī)約1 .【強(qiáng)制】類、類屬性、類方法的注釋必須使用Javadoc規(guī)范，使用/*內(nèi)容*/格式，不得使用/XXX方式。說(shuō)明：在IDE編輯窗口中Javadoc方式會(huì)提示相關(guān)注釋，生成Javadoc 可以正確輸出相應(yīng)注 釋;在IDE中，工程調(diào)用方法時(shí)，不進(jìn)入方法即可懸 浮提示方法、參數(shù)、返回值的意義，提高 閱讀效率。2

14、.【強(qiáng)制】所有的抽象方法(包括接口中的方法)必須要用Javadoc注釋、 除了返回值、參數(shù)、異常說(shuō)明外，還必須指出該方法做什么事情，實(shí)現(xiàn)什 么功能。說(shuō)明：對(duì)子類的實(shí)現(xiàn)要求，或者調(diào)用注意事項(xiàng)，請(qǐng)一并說(shuō)明。3 .【強(qiáng)制】所有的類都必須添加創(chuàng)建者和創(chuàng)建日期。4 .【強(qiáng)制】方法內(nèi)部單行注釋，在被注釋語(yǔ)句上方另起一行，使用注釋。方 法內(nèi)部多行注釋使用/* */注釋，注意與代碼對(duì)齊。5 .【強(qiáng)制】所有的枚舉類型字段必須要有注釋，說(shuō)明每個(gè)數(shù)據(jù)項(xiàng)的用途。6 .【推薦】與其“半吊子”英文來(lái)注釋，不如用中文注釋把問(wèn)題說(shuō)清楚。專 有名詞與關(guān)鍵字保持 英文原文即可。反例：“TCP連接超時(shí)”解釋成“傳輸控制協(xié)議連接超時(shí)

15、”，理解反而費(fèi)腦筋。7 .【推薦】代碼修改的同時(shí)，注釋也要進(jìn)行相應(yīng)的修改，尤其是參數(shù)、返回 值、異常、核心邏輯等的修改。說(shuō)明：代碼與注釋更新不同步，就像路網(wǎng)與導(dǎo)航軟件更新不同步一樣，如 果導(dǎo)航軟件嚴(yán)重滯后，就失去了導(dǎo)航的意義。(四)其它1 .【強(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/+dev1.0+tags/+release1.0說(shuō)明；trunk：主開發(fā)分支：正在開發(fā)中的主分支branches。些特殊開發(fā)需要的分支，和主分支并行開發(fā)用，命名

16、規(guī)范為 “dev_”開頭，連接本分支有意義的單詞或拼音，如dev_tongji”tags：定版的，命名規(guī)則：“ release_fi本號(hào)”、異常日志(一)異常處理2 .【強(qiáng)制】Java類庫(kù)中定義的一類RuntimeException可以通過(guò)預(yù)先檢查 進(jìn)行規(guī)避，而不應(yīng)該 通過(guò) catch 來(lái)處理，比 如:IndexOutOfBoundsException,NullPointerExceptior 等。 說(shuō)明:無(wú)法通 過(guò)預(yù)檢查的異常除外，如在解析一個(gè)外部傳來(lái)的字符串形式數(shù)字時(shí)，通過(guò) catch NumberFormatException 來(lái)實(shí)現(xiàn)。正例：if (obj != null) 反例：try

17、 obj.method() catch (NullPointerException e) .3 .【強(qiáng)制】異常不要用來(lái)做流程控制，條件控制，因?yàn)楫惓５奶幚硇时葪l 件分支低。4 .【強(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ū)分 異常類型，再做對(duì)應(yīng)的異常 處理。5 .【強(qiáng)制】捕獲異常是為了處理它，不要捕獲了卻什么都不處理而拋棄之， 如果不想處理它，請(qǐng) 將該異常拋給它的調(diào)用者。最外層的業(yè)務(wù)使用者，必 須處理異常，將其轉(zhuǎn)化為用戶可以理解的內(nèi)容。6 .【強(qiáng)制】有tr

18、y塊放到了事務(wù)代碼中，catch異常后，如果需要回滾事務(wù), 一定要注意手動(dòng)回 滾事務(wù)。7 .【強(qiáng)制】finally塊必須對(duì)資源對(duì)象、流對(duì)象進(jìn)行關(guān)閉，有異常也要做try- catch。說(shuō)明:如果JDK7及以上，可以使用try-with-resources方式。8 .【強(qiáng)制】不能在 finally塊中使用return,finally塊中的return返回后 方法結(jié)束執(zhí)行，不 會(huì)再執(zhí)行try塊中的return語(yǔ)句。9 .【強(qiáng)制】捕獲異常與拋異常，必須是完全匹配，或者捕獲異常是拋異常的 父類。說(shuō)明:如果預(yù)期對(duì)方拋的是繡球，實(shí)際接到的是鉛球，就會(huì)產(chǎn)生意 外情況。10 【推薦】防止NPE是程序員的基本修養(yǎng)

19、，注意NPE產(chǎn)生的場(chǎng)景：1)返回類型為基本數(shù)據(jù)類型，return包裝數(shù)據(jù)類型的對(duì)象時(shí)，自動(dòng)拆箱 有可能產(chǎn)生 NPE 反例:public int f() return Integer對(duì)象,如果為 null,自動(dòng)解箱拋NPE2)數(shù)據(jù)庫(kù)的查詢結(jié)果可能為null。3)集合里的元素即使isNotEmpty,取出的數(shù)據(jù)元素也可能為null。4)遠(yuǎn)程調(diào)用返回對(duì)象時(shí)，一律要求進(jìn)行空指針判斷，防止NPE5) 對(duì)于Session中獲取的數(shù)據(jù)，建議NPE檢查,避免空指針。6) 級(jí)聯(lián)調(diào)用obj.getA().getB().getC()二連串調(diào)用，易產(chǎn)生NPE正例：可以使用JDK8的Optional類來(lái)防止NPE問(wèn)題。

20、(二)日志規(guī)約1.【強(qiáng)制】應(yīng)用中需要記錄日志，使用日志系統(tǒng) Log4j中的API,記錄日志。Import org.apache.log4j.Logger;private final Logger logger=Logger.getLogger(getClass();三、工程規(guī)約(一)應(yīng)用分層1.【推薦】圖中默認(rèn)上層依賴于下層，箭頭關(guān)系表示可直接依賴。如 開放接口層可以依賴于 Controller層,也可以直接依賴Managet層, 以此類推：終疑顯示器開放接口n c密求處理（C前肥r層）一。 L請(qǐng)求處理（ Manage層；介rHr特溫(DAOS)GU外部接口婢三方平臺(tái) （開放接口層：可直接封裝Manager方法暴露成RPC1 口。終端顯示器：各個(gè)端的模板渲染并執(zhí)行顯示的