Java開發(fā)手冊完整

Java開發(fā)手冊(1.0.0)版本號更新日期備注t.o.o2022-。11首次發(fā)布試運行。重慶北冰洋科技有限公司《Java開發(fā)手冊》主要包含工程結(jié)構(gòu)、編程規(guī)約、異常日志、單元測試、安全規(guī)約、設(shè)計規(guī)約6個維度的內(nèi)容，再根據(jù)內(nèi)容特征，細分成若干二級子目錄。依據(jù)約束力強弱及故障敏感性，規(guī)約依次分為【強制】、【推薦】、L..］三大類。在延伸信息中，“說明”對規(guī)約做了適當擴展和解釋；“止例"提倡什么樣的編碼和實現(xiàn)方式；“反例”說明需要提防的雷區(qū)，以及真實的錯誤案例。手冊的目的是提高代碼的可讀性和易維護性。遵守適當?shù)囊?guī)范和標準，能讓代碼可讀性強，可讀性強的代碼能提升團隊的協(xié)作效率，降低溝通成本和提供維護性更好的系統(tǒng)。別外，質(zhì)量的提升是盡可能少踩坑，杜絕踩重復(fù)的坑，切實提升系統(tǒng)的穩(wěn)定性，碼出質(zhì)量。目錄TOC\o"1-5"\h\z\o"CurrentDocument"\h一、 工程結(jié)構(gòu) 1\o"CurrentDocument"\h二、 編程規(guī)約 6（一） 命名風(fēng)格 6\o"CurrentDocument"\h（二） 常量定義 10\o"CurrentDocument"\h（三） 代碼格式 12（四） OOP規(guī)約 16（五） 日期時間 23（六） 集合處理 25（七） 并發(fā)處理 32\o"CurrentDocument"\h（八） 控制語句 39\o"CurrentDocument"\h（九） 注解規(guī)約 44（十）前后端規(guī)約 46（十一）其他 48\o"CurrentDocument"\h三、 異常日志 50（一） 異常處理 50（二） 日志規(guī)約 52\o"CurrentDocument"\h四、 單元測試 55\o"CurrentDocument"\h五、 安全規(guī)約 58\o"CurrentDocument"\h六、 設(shè)計規(guī)約 59\o"CurrentDocument"\h附件1：版本歷史 63\o"CurrentDocument"\h附件2:專有各詞解釋 64第第#頁共70頁除。說明：代碼被注釋掉有兩種可能性：1)后續(xù)會恢復(fù)此段代碼邏輯。2)永久不用。前者如果沒有備注信息，難以知曉注釋動機。后者建議直接刪掉即可，假如需要查閱歷史代碼，登錄代碼倉庫即可。W.[<]對于注釋的要求：第一、能夠準確反映設(shè)計思想和代碼邏輯；第二、能夠描述業(yè)務(wù)含義，使別的程序員能夠迅速了解到代碼背后的信息。完全沒有注釋的大段代碼對于閱讀者形同天書，注釋是給自己看的，即使隔很長時間，也能清晰理解當時的思路；注釋也是給繼任者看的，使其能夠快速接替自己的工作。21、【‘"】好的命名、代碼結(jié)構(gòu)是自解釋的，注釋力求精簡準確、表達到位。避免出現(xiàn)注釋的一個極端：過多過濫的注釋，代碼的邏輯一旦修改，修改注釋又是相當大的負擔。反例：//putelepkaiatiiatofridgeput(dephav\t,fridge)方法名put,加上兩個有意義的變量名以甲血"和fWdge,己經(jīng)說明了這是在干什么，語義清晰的代碼不需要額外的注釋。(十)前后端規(guī)約2、【強制】前后端交互的API,需要明確協(xié)議、域名、路徑、請求方法、請求內(nèi)容、狀態(tài)碼、響應(yīng)體。說明：路徑：每一個API需對應(yīng)一個路徑，表示API具體的請求地址：&)代表一種資源，只能為名詞，推薦使用復(fù)數(shù)，不能為動詞，請求方法己經(jīng)表達動作意義。URL路徑不能使用大寫，單詞如果需要分隔，統(tǒng)一使用下劃線。路徑禁止攜帶表示請求內(nèi)容類型的后綴，比如勺soXy.xmM通過accept頭表達即可。請求方法：對具體操作的定義，常見的請求方法如下：■)GET：從服務(wù)器取出資源。POST：在服務(wù)器新建一個資源.PUT：在服務(wù)器更新資源。DELETE：從服務(wù)器刪除資源。請求內(nèi)容：URL帶的參數(shù)必須無敏感信息或符合安全要求；body里帶參數(shù)時必須設(shè)置Content-Type0④響應(yīng)體：響應(yīng)體bodynf放置多種數(shù)據(jù)類型，由Content-Type頭來確定。2、 【強制】前后端數(shù)據(jù)列表相關(guān)的接口返回，如果為空，則返回空數(shù)組口或空集合&。說明：此條約定有利于數(shù)據(jù)層面上的協(xié)作更加高效，減少前端很多瑣碎的mx"判斷。3、 【強制】在前后端交互的JSON格式數(shù)據(jù)中，所有的key必須為小寫字母開始的low^Cai^elCase風(fēng)格，符合英文表達習(xí)慣，且表意完整。正例terrorCode/errorMessage/assetStatus/kv\e^uList/oK-derList/co^figFlag反例：ERRORCODE/ERROR_CODE/errorj4Aess々ge/ermr-kv\essnge/errorFv\essnge/Ekvo—Me燙ge/msg4、 【強制】對于需要使用超大整數(shù)的場景，服務(wù)端一律使用St巾g字符串類型返回，禁止使用Long類型。說明：Java服務(wù)端如果直接返回Long整型數(shù)據(jù)給前端，JS會自動轉(zhuǎn)換為Number類型(注：此類型為雙精度浮點數(shù)，表示原理與取值范圍等同于Java中的Double).Long類型能表示的最大值是2的63次方-1,在取值范圍之內(nèi)，超過2的53次方(牝Q7M925474692)的數(shù)值轉(zhuǎn)化為JS的Number時，有些數(shù)值會有精度損失。擴展說明，在Long取值范圍內(nèi)，任何2的指數(shù)次整數(shù)都是絕對不會存在精度損失的，所以說精度損失是…個概率問題。若浮點數(shù)尾數(shù)位與指數(shù)位空間不限，則可以精確表示任何整數(shù)，但很不幸，雙精度浮點數(shù)的尾數(shù)位只有52位。反例：通常在訂單號或交易號大于等于1G位，大概率會出現(xiàn)前后端單據(jù)不一致的情況，比如，"orderld"：36(2^C?96C>13746176<?(2,前端拿到的值卻是：36(2^<?6C)137461766C>o5、 【強制】HTTP請求通過URL傳遞參數(shù)時，不能超過2Q48字節(jié)。說明：不同瀏覽器對于URL的最大長度限制略有不同，并且對超出最大長度的處理邏輯也有差異，2048字節(jié)是取所有瀏覽器的最小值。反例：某業(yè)務(wù)將退貨的商品id列表放在URL中作為參數(shù)傳遞，當一次退貨商品數(shù)量過多時，URL參數(shù)超長，傳遞到后端的參數(shù)被截斷，導(dǎo)致部分商品未能正確退貨。么、【強制】HTTP請求通過bodg傳遞內(nèi)容時，必須控制長度，超出最大長度后，后端解析會岀錯。說明：ng泌x默認限制是1MB,tomcat默認限制為2MB,當確實有業(yè)務(wù)需要傳較大內(nèi)容時，可以通過調(diào)大服務(wù)器端的限制。7、 【強制】在翻頁場景中，用戶輸入?yún)?shù)的小于2,則前端返回第一頁參數(shù)給后端；后端發(fā)現(xiàn)用戶輸入的參數(shù)大于總頁數(shù)，直接返回最后…頁。8、 【強制】服務(wù)器內(nèi)部重定向必須使用forward；外部重定向地址必須使用URL統(tǒng)一代理模塊生成，否則會因線上釆用HTTPS協(xié)議而導(dǎo)致瀏覽器提示“不安全”，并且還會帶來URL維護不一致的問題。3、【推薦】服務(wù)器返回信息必須被標記是否可以緩存，如果緩存，客戶端可能會重用之前的請求結(jié)果。說明：緩存有利于減少交互次數(shù)，減少交互的平均延遲。正例：http1.1中，s-moxnge告訴服務(wù)器進行緩存，時間單位為秒，用法如下：-Control", +cackeSecoiads）;比、【推薦】服務(wù)端返回的數(shù)據(jù)，使用JSON格式而非XML。說明：盡管HTTP支持使用不同的輸出格式，例如純文本，JSON,CSV,XML,RSS甚至HTML.如果我們使用的面向用戶的服務(wù)，應(yīng)該選擇JSON作為通信中使用的標準數(shù)據(jù)交換格式，包括請求和響應(yīng)。此外，叩ph'c陽＜m/JSON是?種通用的MIME類型，具有實用、精簡、易讀的特點。21、【推薦】前后端的時間格式統(tǒng)一為〃gggg-MM-dd 統(tǒng)一為GMT。12、【 ］在接口路徑中不要加入版本號，版本控制在HTTP頭信息中體現(xiàn)，有利于向前兼容。說明：當用戶在低版本與高版本之間反復(fù)切換工作時，會導(dǎo)致遷移復(fù)雜度升高，存在數(shù)據(jù)錯亂風(fēng)險。（）其他2、【強制】在使用正則表達式時，利用好其預(yù)編譯功能，可以有效加快正則匹配速度。說明：不要在方法體內(nèi)定義：Patternpattens=Pattern.cokv\pite(ff規(guī)則”);2、 【強制】避免用ApackeBeai^utils進行屬性的copg。說明：Ap"辰BeaiaUtils性能較差，可以使用其他方案比如SpringBcaiaUtils,CglibBea^Copier.注意均是淺拷貝。3、 【強制】velocity調(diào)用POJO類的屬性時，直接使用屬性名取值即可，模板引擎會自動按規(guī)范調(diào)用POJ。的getXxx。，如果是boolean基本數(shù)據(jù)類型變量(boolean命名不需要加is前綴)，會自動調(diào)用isXxx()方法。說明：注意如果是Boolean包裝類對象，優(yōu)先調(diào)用getXxx()的方法。4、 【強制】后臺輸送給頁面的變量必須加f!{var}一一中間的感嘆號。說明：如果 等于心"或者不存在，那么呼會直接顯示在頁面上。5、 【強制】注意Ma払.m"om()這個方法返回是double類型，注意取值的范圍6><x<X(能夠取到零值，注意除零異常)，如果想獲取整數(shù)類型的隨機數(shù)，不要將X放大2Q的若干倍然后取整，直接使用R亦4。心對象的next/Fit或者MxtLoiag方法。6、 【推薦】不要在視圖模板中加入任何復(fù)雜的邏輯。說明：根據(jù)MVC理論，視圖的職責是展示，不要搶模型和控制器的活。7、 【推薦】任何數(shù)據(jù)結(jié)構(gòu)的構(gòu)造或初始化，都應(yīng)指定大小，避免數(shù)據(jù)結(jié)構(gòu)無限增長吃光內(nèi)存。8、 【推薦】及時清理不再使用的代碼段或配置信息。說明：對于垃圾代碼或過時配置，堅決清理干凈，避免程序過度臃腫，代碼冗余。正例：對于暫時被注釋掉，后續(xù)可能恢復(fù)使用的代碼片斷，在注釋代碼上方，統(tǒng)一規(guī)定使用三個斜杠(///)來說明注釋掉代碼的理由。如：publicstaticvoidhello(){///業(yè)務(wù)方通知活動暫停//Businessbusiness=newBusiness(); //business.active();System.out.println("it'sfinished")：三、異常日志(-)異常處理2、【強制】Java類庫中定義的可以通過預(yù)檢查方式規(guī)避的Rtx八打hwExcepti。八異常不應(yīng)該通過catch的方式來處理，比如：NcdlPo訊terException,liadexOiAtOfBoiAiadsExceptio^等等。說明：無法通過預(yù)檢查的異常除外，比如，在解析字符串形式的數(shù)字時，可能存在數(shù)字格式錯誤，不得不通過catckNui^\berForw\atExceptiov\來實現(xiàn)。正例：if(obj!=null){...}反例：try(o好me払。d。；}catcl^(NullPointerExceptioiae)2、 【強制】異常捕獲后不要用來做流程控制，條件控制。說明：異常設(shè)計的初衷是解決程序運行中的各種意外情況，且異常的處理效率比條件判斷方式要低很多。3、 【強制時請分清穩(wěn)定代碼和非穩(wěn)定代碼，穩(wěn)定代碼指的是無論如何不會出錯的代碼。對于非穩(wěn)定代碼的catch盡可能進行區(qū)分異常類型，再做對應(yīng)的異常處理。說明：對大段代碼進行t^-catcK使程序無法根據(jù)不同的異常做出正確的應(yīng)激反應(yīng)，也不利于定位問題，這是一種不負責任的表現(xiàn)。正例：用戶注冊的場景中，如果用戶輸入非法字符，或用戶名稱已存在，或用戶輸入密碼過于簡單，在程序上作出分門別類的判斷，并提示給用戶。4、 【強制】捕獲異常是為了處理它，不要捕獲了卻什么都不處理而拋棄之，如果不想處理它，請將該異常拋給它的調(diào)用者。最外層的業(yè)務(wù)使用者，必須處理異常，將其轉(zhuǎn)化為用戶可以理解的內(nèi)容。5、 【強制】事務(wù)場景中，拋出異常被catch后，如果需要回滾，一定要注意手動回滾事務(wù)。G、【強制】finally塊必須對資源對象、流對象進行關(guān)閉，有異常也要做try-catcK說明：如果JDK7及以上，可以使用try-\A/itk-resources方式。7、 【強制】不要在finally塊中使用return0說明5塊中的return語句執(zhí)行成功后，并不馬上返回，而是繼續(xù)執(zhí)行finally塊中的語句，如果此處存在return語句，則在此直接返回，無情丟棄掉trg塊中的返回點。反例：privatemtx=OpublicStc虹eckReturn。{try{〃x等于幻此處不返回return++x；}finally{//返回的結(jié)果是2return++x；}18、 【強制】捕獲異常與拋異常，必須是完全匹配，或者捕獲異常是拋異常的父類。說明：如果預(yù)期對方拋的是繡球，實際接到的是鉛球，就會產(chǎn)生意外情況。9、 【強制】在調(diào)用RPC、二方包、或動態(tài)生成類的相關(guān)方法時，捕捉異常必須使用Throwable類來進行攔截。說明：通過反射機制來調(diào)用方法，如果找不到方法，拋出NoSuc代Met代。dException。什么情況會拋出NoSucMetkodError呢？二方包在類沖突時，仲裁機制可能導(dǎo)致引入非預(yù)期的版本使類的方法簽名不匹配，或者在字節(jié)碼修改框架(比如：ASM)動態(tài)創(chuàng)建或修改類時，修改了相應(yīng)的方法簽名。這些情況，即使代碼編譯期是正確的，但在代碼運行期時，會拋出NoSucMetkodE^or-1Q、【推薦】方法的返回值可以為樹,不強制返回空集合，或者空對象等，必須添加注釋充分說明什么情況下會返回null值。說明：本手冊明確防止NPE是調(diào)用者的責任。即使被調(diào)用方法返回空集合或者空對象，對調(diào)用者來說，也并非高枕無憂，必須考慮到遠程調(diào)用失敗、序列化失敗、運行時異常等場景返回八的情況。21、 【推薦】防止NPE,是程序員的基本修養(yǎng)，注意NPE產(chǎn)生的場景：返回類型為基本數(shù)據(jù)類型，return包裝數(shù)據(jù)類型的對象時，自動拆箱有可能產(chǎn)生NPE。反例1publicintf(){returnInteger對象},如果為W自動解箱拋NPE。數(shù)據(jù)庫的查詢結(jié)果可能為nul/o集合里的元素即使isNotEmptg,取出的數(shù)據(jù)元素也可能為心心遠程調(diào)用返回對象時，一律要求進行空指針判斷，防止NPE。對于S處夕'。八中獲取的數(shù)據(jù)，建議進行NPE檢查，避免空指針。級聯(lián)調(diào)用。bj.getAO.getBO.gctCO；一連串調(diào)用，易產(chǎn)生NPE。正例：使用JDK8的Optional類來防止NPE問題。22、 【推薦】定義時區(qū)分me代ecked/ckecked異常，避免直接拋出newR.iAi^tii^eExceptio^O,更不允許拋出Exception或者Throwablef應(yīng)使用有業(yè)務(wù)含義的自定義異常。推薦業(yè)界已定義過的自定義異常，如：DAOExceptio^/ServiceExceptioi^(―)日志規(guī)約1、【強制】應(yīng)用中不可直接使用日志系統(tǒng)（Log句、Logback）中的API,而應(yīng)依賴使用日志框架（SLF4J、JCL--JakartaComm。八sLogging）中的API,使用門面模式的日志框架，有利于維護和各個類的日志處理方式統(tǒng)一。說明：日志框架（SLF4J、JCL—JaknrtnComkaohsLogging）的使用方式（推薦使用SLF4J）使用SLF4J：importorg.s（f4jLoggerimportorgs網(wǎng)LoggerFactorgprivatestaticfilialLoggerlogger=LoggerFactory.getLogger（Test.cla^）;使用JCL：importorgapache.cokv\i^\on$.logging丄og：importorg.apacke.coKv\^v\o^.logging.LogFact。，g.privatestaticfilialLoglog=LogFactory.getLog(Test.class)2、【強制】所有日志文件至少保存15天，因為有些異常具備以“周”為頻次發(fā)生的特點。對于當天日志，以"應(yīng)用名.她”來保存，保存在應(yīng)用名/logs/目錄下，過往日志格式為:｛log^ai^e].log.｛保存日期｝,日期格式：gggg-MM-dd正例：以aap應(yīng)用為例，日志保存在aapse^ver/logs/aap.log,歷史日志名稱為aap.log.20^<b-03-O13、【強制】根據(jù)國家法律，網(wǎng)絡(luò)運行狀態(tài)、網(wǎng)絡(luò)安全事件、個人敏感信息操作等相關(guān)記錄，留存的日志不少于六個月。4、【強制】應(yīng)用中的擴展日志（如打點、臨時監(jiān)控、訪問日志等）命名方式:appNai^e_logType_logNa^v\e.(ogalogTypc：日志類型，如stats/mcmitor/mcess等;（ogNa^e：□志描述。這種命名的好處：通過文件名就可知道日志文件屬于什么應(yīng)用，什么類型，什么目的，也有利于歸類查找。說明：推薦對日志進行分類，如將錯誤H志和業(yè)務(wù)日志分開存放，便于開發(fā)人員查看，也便于通過日志對系統(tǒng)進行及時監(jiān)控。正例tmppserver應(yīng)用中單獨控時區(qū)轉(zhuǎn)換異常，如：m件serve匕m。八初仁mneZoneCogert她5、 【強制】在日志輸出時，字符串變量之間的拼接使用占位符的方式。說明：因為String字符串的拼接會使用的叩習(xí)乂（）方式，有一定的性能損耗。使用占位符僅是替換動作，可以有效提升性能。正例：loggerdebugsProcessingtradewithid:任々以sykvxfaof：Q",id,symbo/）-6、 【強制】對于t^ace/debug/i^fo級別的日志輸出，必須進行日志級別的開關(guān)判斷。說明：雖然在debug（參數(shù)）的方法體內(nèi)第一行代碼isDkn象d（L"以DEBUG」NT）為真時（S啊的常見實現(xiàn)Log4j和Logback）,就直接return，但是參數(shù)可?能會進行字符串拼接運算。此外，如果de況（g（getAMme。）這種參數(shù)內(nèi)有g(shù)etNa^e（）方法調(diào)用，無謂浪費方法調(diào)用的開銷。正例：//如果判斷為真，那么可以輸出trace和debug級別的日志if（loggerisDebugEEMed。）{loggerdebugsCurrentIPis：{}v\aw\e怎{}'id,getN口me。）}7、 【強制】避免重復(fù)打印日志，浪費磁盤空間，務(wù)必在日志配置文件中設(shè)置additivity=fake。正例：〈loggerM^e="co^.taobao.dubbo.co^fig"additivity^fal^'y9、【強制】生產(chǎn)環(huán)境禁止直接使用Syste^v\.out或Systcm.err輸出日志或使用e.priiatStackTrace0打印異常堆棧。說明：標準日志輸出與標準錯誤輸出文件每次Jboss重啟時才滾動，如果大量輸出送往這兩個文件,容易造成文件大小超過操作系統(tǒng)大小限制。9、【強制】異常信息應(yīng)該包括兩類信息：案發(fā)現(xiàn)場信息和異常堆棧信息。如果不處理，那么通過關(guān)鍵字throws往上拋出。正例：《?！汜娦摹?。匕("的兒圮。忍ms：(}imderrorMess^ge：&七各類參數(shù)或者對象toStriv\g(),e.getMessngeO,e);1。 、【強制】日志打印時禁止直接用JSON工具將對象轉(zhuǎn)換成String.說明：如果對象里某些ge七方法被覆寫，存在拋岀異常的情況，則可能會因為打印日志而影響正常業(yè)務(wù)流程的執(zhí)行。 正例：打印日志時僅打印出業(yè)務(wù)相關(guān)屬性值或者調(diào)用其對象的toSt正付()方法。11、【推薦】謹慎地記錄日志。生產(chǎn)環(huán)境禁止輸岀debug日志；有選擇地輸出Mo日志；如果使用wow來記錄剛上線時的業(yè)務(wù)行為信息，一定要注意日志輸出量的問題，避免把服務(wù)器磁盤撐爆，并記得及時刪除這些觀察日志。說明：大量地輸出無效日志，不利于系統(tǒng)性能提升，也不利于快速定位錯誤點。記錄日志時請思考：這些日志真的有人看嗎？看到這條口志你能做什么？能不能給問題排查帶來好處？22、【推薦】可以使用warn日志級別來記錄用戶輸入?yún)?shù)錯誤的情況，避免用戶投訴時，無所適從。如非必要，請不要在此場景打出error級別，避免頻繁報警。說明：注意日志輸出的級別，error級別只記錄系統(tǒng)邏輯出錯、異常或者重要的錯誤信息。13、【推薦】盡量用英文來描述日志錯誤信息，如果日志中的錯誤信息用英文描述不清楚的話使用中文描述即可，否則容易產(chǎn)生歧義。說明：國際化團隊或海外部署的服務(wù)器由于字符集問題，使用全英文來注釋和描述日志錯誤信息。四、單元測試2、 【強制】好的單元測試必須遵守A/R原則。說明：單元測試在線上運行時，感覺像空氣（AIR）一樣感覺不到，但在測試質(zhì)最的保障上，卻是非常關(guān)鍵的。好的單元測試宏觀上來說，具有自動化、獨立性、可重復(fù)執(zhí)行的特點。A：Automatic（自動化）I：liadepeiadeiat（獨立性）R：Repeatable（可重復(fù)）2、 【強制】單元測試應(yīng)該是全自動執(zhí)行的，并且非交互式的。測試用例通常是被定期執(zhí)行的，執(zhí)行過程必須完全自動化才有意義。輸岀結(jié)果需要人工檢查的測試不是一個好的單元測試。單元測試中不準使用System.out來進行人肉驗證，必須使用assert來驗證。3、 【強制】保持單元測試的獨立性。為了保證單元測試穩(wěn)定可靠且便于維護，單元測試用例之間決不能互相調(diào)用，也不能依賴執(zhí)行的先后次序。反例1me払od2需要依賴metMoiZl的執(zhí)行，將執(zhí)行結(jié)果作為me払od2的輸入。4、 ［:強制】單元測試是可以重復(fù)執(zhí)行的，不能受到外界環(huán)境的影響。說明：單元測試通常會被放到持續(xù)集成中，每次有代碼check譏時單元測試都會被執(zhí)行。如果單測對外部環(huán)境（網(wǎng)絡(luò)、服務(wù)、中間件等）有依賴，容易導(dǎo)致持續(xù)集成機制的不可用。正例：為了不受外界環(huán)境影響，要求設(shè)計代碼時就把SUT的依賴改成注入，在測試時用spn認g這樣的少框架注入?個本地（內(nèi)存）實現(xiàn)或者Mock實現(xiàn)。5、 【強制】對于單元測試，要保證測試粒度足夠小，有助于精確定位問題。單測粒度至多是類級別，一般是方法級別。說明：只有測試粒度小才能在出錯時盡快定位到出錯位置。單測不負責檢查跨類或者跨系統(tǒng)的交互邏輯，那是集成測試的領(lǐng)域。么、【強制】核心業(yè)務(wù)、核心應(yīng)用、核心模塊的增量代碼確保單元測試通過。說明：新增代碼及時補充單元測試，如果新增代碼影響了原有單元測試，請及時修正。7、【強制】單元測試代碼必須寫在如下工程目錄：不允許寫在業(yè)務(wù)代碼目錄下。說明：源碼編譯時會跳過此目錄，而單元測試框架默認是掃描此目錄。8、 【推薦】單元測試的基本目標：語句覆蓋率達到7。％；核心模塊的語句覆蓋率和分支覆蓋率都要達到18%。說明：在工程規(guī)約的應(yīng)用分層中提到的DAO層，Manager層，可重用度高的Service,都應(yīng)該進行單元測試。9、 【推薦】編寫單元測試代碼遵守BCDE原則，以保證被測試模塊的交付質(zhì)量。B：B。以見，邊界值測試，包括循環(huán)邊界、特殊取值、特殊時間點、數(shù)據(jù)順序等。C：Correct,正確的輸入，并得到預(yù)期的結(jié)果。P：Design,與設(shè)計文檔相結(jié)合，來編寫單元測試。?E：Error,強制錯誤信息輸入（如：非法數(shù)據(jù)、異常流程、業(yè)務(wù)允許外等），并得到預(yù)期的結(jié)果。20、【推薦】對于數(shù)據(jù)庫相關(guān)的查詢，更新，刪除等操作，不能假設(shè)數(shù)據(jù)庫里的數(shù)據(jù)是存在的，或者直接操作數(shù)據(jù)庫把數(shù)據(jù)插入進去，請使用程序插入或者導(dǎo)入數(shù)據(jù)的方式來準備數(shù)據(jù)。反例：刪除某一行數(shù)據(jù)的單元測試，在數(shù)據(jù)庫中，先直接手動增加一行作為刪除目標，但是這一行新增數(shù)據(jù)并不符合業(yè)務(wù)插入規(guī)則，導(dǎo)致測試結(jié)果異常。22、 【推薦】和數(shù)據(jù)庫相關(guān)的單元測試，可以設(shè)定自動回滾機制，不給數(shù)據(jù)庫造成臟數(shù)據(jù)?；蛘邔卧獪y試產(chǎn)生的數(shù)據(jù)有明確的前后綴標識。正例：內(nèi)部單元測試中，使用ENTERPRSE」NTELLI&EN使E_UNrrj~EST_的前綴來標識單元測試相關(guān)代碼。12、【推薦】對于不可測的代碼在適當?shù)臅r機做必要的重構(gòu)，使代碼變得可測，避免為了達到測試要求而書寫不規(guī)范測試代碼。23、 【推薦】在設(shè)計評審階段，開發(fā)人員需要和測試人員一起確定單元測試范圍，單元測試最好覆蓋所有測試用例（UC）。14、【推薦】單元測試作為一種質(zhì)量保障手段，在項目提測前完成單元測試，不建議項目發(fā)布后補充單元測試用例。25、【【打】為了更方便地進行單元測試，業(yè)務(wù)代碼應(yīng)避免以下情況：構(gòu)造方法中做的事情過多。存在過多的全局變量和靜態(tài)方法。存在過多的外部依賴。存在過多的條件語句。說明：多層條件語句建議使用衛(wèi)語句、策略模式、狀態(tài)模式等方式重構(gòu)。16.[:]不要對單元測試存在如下誤解：那是測試同學(xué)干的事情。本文是開發(fā)手冊，凡是本文內(nèi)容都是與開發(fā)同學(xué)強相關(guān)的。單元測試代碼是多余的。系統(tǒng)的整體功能與各單元部件的測試正常與否是強相關(guān)的。單元測試代碼不需要維護。一年半載后，那么單元測試幾乎處于廢棄狀態(tài)。單元測試與線上故障沒有辯證關(guān)系。好的單元測試能夠最大限度地規(guī)避線上故障。五、安全規(guī)約1、 【強制】隸屬于用戶個人的頁面或者功能必須進行權(quán)限控制校驗。說明：防止沒有做水平權(quán)限校驗就可隨意訪問、修改、刪除別人的數(shù)據(jù)，比如査看他人的私信內(nèi)容。2、 【強制】用戶敏感數(shù)據(jù)禁止直接展示，必須對展示數(shù)據(jù)進行脫敏。說明：中國大陸個人手機號碼顯示：139****2219,隱藏中間4位，防止隱私泄露。3、 【強制】用戶輸入的SQL參數(shù)嚴格使用參數(shù)綁定或者METADATA字段值限定，防止SQL注入，禁止字符串拼接SQL訪問數(shù)據(jù)庫。反例：某系統(tǒng)簽名大量被惡意修改，即是因為對于危險字符#--沒有進行轉(zhuǎn)義，導(dǎo)致數(shù)據(jù)庫更新時,where后邊的信息被注釋掉，對全庫進行更新。4、 【強制】用戶請求傳入的任何參數(shù)必須做有效性驗證。說明：忽略參數(shù)校驗可能導(dǎo)致：page,size過大導(dǎo)致內(nèi)存溢出?惡意。以"by導(dǎo)致數(shù)據(jù)庫慢査詢-緩存擊穿SSRF?任意重定向?SQL注入，S代eH注入，反序列化注入?正則輸入源串拒絕服務(wù)ReDoSJava代碼用正則來驗證客戶端的輸入，有些正則寫法驗證普通用戶輸入沒有問題，但是如果攻擊人員使用的是特殊構(gòu)造的字符串來驗證，有可能導(dǎo)致死循環(huán)的結(jié)果。5、 【強制】禁止向HTML頁面輸出未經(jīng)安全過濾或未正確轉(zhuǎn)義的用戶數(shù)據(jù)。6、 【強制】表單、AJAX提交必須執(zhí)行CSRF安全驗證。說明：CSRF(Cmss-s沏requestforgery)跨站請求偽造是啖常見編程漏洞。對于存在CSRF漏洞的應(yīng)用/網(wǎng)站，攻擊者可以事先構(gòu)造好URL,只要受害者用戶一訪問，后臺便在用戶不知情的情況下對數(shù)據(jù)庫中用戶參數(shù)進行相應(yīng)修改。7、 【強制】在使用平臺資源，譬如短信、郵件、電話、下單、支付，必須實現(xiàn)正確的防重放的機制，如數(shù)量限制、疲勞度控制、驗證碼校驗，避免被濫刷而導(dǎo)致資損。說明：如注冊時發(fā)送驗證碼到手機，如果沒有限制次數(shù)和頻率，那么可以利用此功能騷擾到其它用戶，并造成短信平臺資源浪費。六、設(shè)計規(guī)約1、【強制】存儲方案和底層數(shù)據(jù)結(jié)構(gòu)的設(shè)計獲得評審一致通過，并沉淀成為文檔。說明：有缺陷的底層數(shù)據(jù)結(jié)構(gòu)容易導(dǎo)致系統(tǒng)風(fēng)險上升，可擴展性下降，重構(gòu)成本也會因歷史數(shù)據(jù)遷移和系統(tǒng)平滑過渡而陡然増加，所以，存儲方案和數(shù)據(jù)結(jié)構(gòu)需要認真地進行設(shè)計和評審，生產(chǎn)環(huán)境提交執(zhí)行后，需要進行doublecheck正例：評審內(nèi)容包括存儲介質(zhì)選型、表結(jié)構(gòu)設(shè)計能否滿足技術(shù)方案、存取性能和存儲空間能否滿足業(yè)務(wù)發(fā)展、表或字段之間的辯證關(guān)系、字段名稱、字段類型、索引等；數(shù)據(jù)結(jié)構(gòu)變更（如在原有表中新增字段）也需要進行評審?fù)ㄟ^后上線。2、 【強制】在需求分析階段，如果與系統(tǒng)交互的User超過一類并且相關(guān)的UserCa^超過5個，使用用例圖來表達更加清晰的結(jié)構(gòu)化需求。3、 【強制】如果某個業(yè)務(wù)對象的狀態(tài)超過3個，使用狀態(tài)圖來表達并且明確狀態(tài)變化的各個觸發(fā)條件。說明：狀態(tài)圖的核心是對象狀態(tài)，首先明確對象有多少種狀態(tài)，然后明確兩兩狀態(tài)之間是否存在直接轉(zhuǎn)換關(guān)系，再明確觸發(fā)狀態(tài)轉(zhuǎn)換的條件是什么。正例：訂單狀態(tài)有己下單、待付款、己付款、待發(fā)貨、己發(fā)貨、己收貨等。比如已下單與己收貨這兩種狀態(tài)之間是不可能有直接轉(zhuǎn)換關(guān)系的。4、 【強制】如果系統(tǒng)中某個功能的調(diào)用鏈路上的涉及對象超過3個，使用時序圖來表達并且明確各調(diào)用環(huán)節(jié)的輸入與輸出。說明：時庁圖反映了一系列對象間的交互與協(xié)作關(guān)系，清晰立體地反映系統(tǒng)的調(diào)用縱深鏈路。5、 【強制】如果系統(tǒng)中模型類超過5個，并且存在復(fù)雜的依賴關(guān)系，使用類圖來表達并且明確類之間的關(guān)系。說明：類圖像建筑領(lǐng)域的施工圖，如果搭平房，可能不需要，但如果建造螞蟻Z空間大樓，肯定需要詳細的施工圖。G、【強制】如果系統(tǒng)中超過2個對象之間存在協(xié)作關(guān)系，并且需要表示復(fù)雜的處理流程，使用活動圖來表示。說明：活動圖是流程圖的擴展，增加了能夠體現(xiàn)協(xié)作關(guān)系的對象泳道，支持表示并發(fā)等。7、 【推薦】系統(tǒng)架構(gòu)設(shè)計時明確以下目標：確定系統(tǒng)邊界。確定系統(tǒng)在技術(shù)層面上的做與不做。確定系統(tǒng)內(nèi)模塊之間的關(guān)系。確定模塊之間的依賴關(guān)系及模塊的宏觀輸入與輸出。確定指導(dǎo)后續(xù)設(shè)計與演化的原則。使后續(xù)的子系統(tǒng)或模塊設(shè)計在一個既定的框架內(nèi)和技術(shù)方向上繼續(xù)演化。確定非功能性需求。非功能性需求是指安全性、可用性、可擴展性等。8、 【推薦】需求分析與系統(tǒng)設(shè)計在考慮主干功能的同時，需要充分評估異常流程與業(yè)務(wù)邊界。反例：用戶在付款過程中，銀行扣款成功，發(fā)送給用戶扣款成功短信，但是支付寶入款時由于斷網(wǎng)演練產(chǎn)生異常，訂單頁面依然顯示未付款，導(dǎo)致用戶投訴。9、【推薦】類在設(shè)計與實現(xiàn)時要符合單一原則。說明：單一原則最易理解卻是最難實現(xiàn)的一條規(guī)則，隨著系統(tǒng)演進，很多時候，忘記了類設(shè)計的初衷。1Q、【推薦】謹慎使用繼承的方式來進行擴展，優(yōu)先使用聚合/組合的方式來實現(xiàn)。說明：不得己使用繼承的話，必須符合里氏代換原則，此原則說父類能夠出現(xiàn)的地方子類一定能夠出現(xiàn)，比如，“把錢交出來”，錢的子類美元、歐元、人民幣等都可以出現(xiàn)。21、【推薦】系統(tǒng)設(shè)計階段，根據(jù)依賴倒置原則，盡量依賴抽象類與接口，有利于擴展與維護。說明：低層次模塊依賴于高層次模塊的抽象，方便系統(tǒng)間的解耦。12、 【推薦】系統(tǒng)設(shè)計階段，注意對擴展開放，對修改閉合。說明：極端情況下，交付的代碼是不可修改的，同一業(yè)務(wù)域內(nèi)的需求變化，通過模塊或類的擴展來實現(xiàn)。13、 【推薦】系統(tǒng)設(shè)計階段，共性業(yè)務(wù)或公共行為抽取出來公共模塊、公共配置、公共類、公共方法等，在系統(tǒng)中不出現(xiàn)重復(fù)代碼的情況，即DR丫原則(Do^tRepeatYousif).說明：隨著代碼的重復(fù)次數(shù)不斷增加，維護成本指數(shù)級上升。隨意復(fù)制和粘貼代碼，必然會導(dǎo)致代碼的重復(fù)，在維護代碼時，需要修改所有的副本，容易遺漏。必要時抽取共性方法，或者抽象公共類，甚至是組件化。正例：?個類中有多個public方法，都需要進行數(shù)行相同的參數(shù)校驗操作，這個時候請抽?。簆rivatebooleancheckParai^(DTOdto){...}14、【推薦】避免如下誤解：敏捷開發(fā)=講故事+編碼+發(fā)布。說明：敏捷開發(fā)是快速交付迭代可用的系統(tǒng)，省略多余的設(shè)計方案，摒棄傳統(tǒng)的審批流程，但核心關(guān)鍵點上的必要設(shè)計和文檔沉淀是需要的。反例：某團隊為了業(yè)務(wù)快速發(fā)展，敏捷成了產(chǎn)品經(jīng)理催進度的借口，系統(tǒng)中均是勉強能運行但像面條一樣的代碼，可維護性和可擴展性極差，一年之后，不得不進行大規(guī)模重構(gòu)，得不償失。25、【 ］設(shè)計文檔的作用是明確需求、理順邏輯、后期維護，次要目的用于指導(dǎo)編碼。說明：避免為了設(shè)計而設(shè)計，系統(tǒng)設(shè)計文檔有助于后期的系統(tǒng)維護和重構(gòu)，所以設(shè)計結(jié)果需要進行分類歸檔保存。26、 】可擴展性的本質(zhì)是找到系統(tǒng)的變化點，并隔離變化點。說明：世間眾多設(shè)計模式其實就是-種設(shè)計模式即隔離變化點的模式。正例：極致擴展性的標志，就是需求的新增，不會在原有代碼交付物上進行任何形式的修改。27、 設(shè)計的本質(zhì)就是識別和表達系統(tǒng)難點。說明：識別和表達完全是兩冋事，很多人錯誤地認為識別到系統(tǒng)難點在哪里，表達只是自然而然的事情，但是大家在設(shè)計評審中經(jīng)常出現(xiàn)語焉不詳，甚至是詞不達意的情況。準確地表達系統(tǒng)難點需要具備如下能力：表達規(guī)則和表達工具的熟練性。抽象思維和總結(jié)能力的局