軟件開(kāi)發(fā)編碼規(guī)范說(shuō)明

1、軟件開(kāi)發(fā)編碼規(guī)范說(shuō)明 梁峰 2017-5-312017一、高級(jí)語(yǔ)言21.1適用范圍21.2程序風(fēng)格21.2.1.代碼縮進(jìn)21.2.2.變量申明21.2.3.代碼塊長(zhǎng)度21.2.4.代碼換行21.2.5.空行及空格31.3命名31.3.1.變量命名31.3.2.常量命名41.3.3.函數(shù)或方法命名41.3.4.文件命名41.4注釋51.4.1.代碼注釋51.4.2.變量注釋51.4.3.函數(shù)注釋51.4.4.文件注釋61.5錯(cuò)誤和異常處理61.5.1.錯(cuò)誤處理61.5.2.異常處理61.6注意事項(xiàng)91.6.1.變量的使用91.6.2.代碼實(shí)現(xiàn)91.7日志規(guī)約10二、結(jié)構(gòu)化查詢語(yǔ)言112.1.程序

2、風(fēng)格112.1.1.SQL語(yǔ)句112.1.2.存儲(chǔ)過(guò)程132.1.3.存儲(chǔ)過(guò)程命名132.1.4.變量命名132.1.5.游標(biāo)命名142.1.6.常量命名142.2.建表規(guī)約142.1.安全規(guī)約152.3.注釋172.3.1.代碼注釋172.3.2.存儲(chǔ)過(guò)程注釋172.3.3.常量及變量注釋172.4.錯(cuò)誤和和異常處理172.5.注意事項(xiàng)18一、 高級(jí)語(yǔ)言1.1 適用范圍主要針對(duì)JSP，CSS和JAVA高級(jí)編程語(yǔ)言，其它高級(jí)語(yǔ)言可參照?qǐng)?zhí)行。1.2 程序風(fēng)格1.2.1. 代碼縮進(jìn)程序塊（包括函數(shù)、過(guò)程、結(jié)構(gòu)的定義及循環(huán)、判斷等語(yǔ)句）要嚴(yán)格采用縮進(jìn)風(fēng)格編寫(xiě)，對(duì)齊只使用空格鍵，不使用TAB鍵，所有的

3、縮進(jìn)為4個(gè)空格。1.2.2. 變量申明在函數(shù)內(nèi)部申明變量時(shí)，必須在函數(shù)的開(kāi)始位置。1.2.3. 代碼塊長(zhǎng)度單個(gè)函數(shù)的程序行數(shù)不得超過(guò)200行。一個(gè)程序文件的長(zhǎng)度不得超過(guò)5000行代碼。1.2.4. 代碼換行1. 較長(zhǎng)的語(yǔ)句（>80字符）要分成多行書(shū)寫(xiě)，長(zhǎng)表達(dá)式要在低優(yōu)先級(jí)操作符處劃分新行，操作符放在新行之首，劃分出的新行要進(jìn)行適當(dāng)?shù)目s進(jìn)，使排版整齊，語(yǔ)句可讀。2. 不允許把多個(gè)短語(yǔ)句寫(xiě)在一行中，即一行只允許寫(xiě)一條語(yǔ)句（如if 、for 、do 、while、case 、switch等語(yǔ)句自占一行）。3. 程序塊的分界符必須各自獨(dú)占一行并且位于同一列，同時(shí)與引用它們的語(yǔ)句左對(duì)齊。1.2.5

4、. 空行及空格1. 通過(guò)摘要注釋分隔的兩個(gè)代碼塊之間、局部變量和它后邊的語(yǔ)句之間、函數(shù)之間留一個(gè)空行。2. 在所有關(guān)鍵字和逗號(hào)之后要留一個(gè)空格，方法名之后不要留空格，緊跟左括號(hào)“（”，以與關(guān)鍵字區(qū)別。3. 如果“;”不是一行的結(jié)束符號(hào)，其后要留空格，如for (initialization; condition; update)。4. 賦值操作符、比較操作符、算術(shù)操作符、邏輯操作符、位域操作符，如“=”、“+=” “>=”、“<=”、“+”、“*”、“%”、“&&”、“|”、“<<”，“”等二元操作符的前后要加空格。5. 一元操作符如“!”、“”、“+”

5、、“-”、“&”（地址運(yùn)算符）等前后不加空格。諸如“”、“.”、“->”這類操作符前后不加空格。1.3 命名1.3.1. 變量命名1. 變量的名字須使用“名詞”或者“形容詞名詞”。 變量的命名要求符合匈牙利命名法則，即開(kāi)頭字母用變量的類型（第一個(gè)字母小寫(xiě)），其余部分用變量的英文意思或其英文意思的縮寫(xiě)（盡量避免用中文的拼音），中間單詞的第一個(gè)字母要大寫(xiě)。即： 變量名=變量類型+變量的英文意思（或縮寫(xiě)）。2. 變量名稱須準(zhǔn)確、完整地描述變量的含義。循環(huán)計(jì)數(shù)變量的名稱須有含義。如果循環(huán)語(yǔ)句的長(zhǎng)度超過(guò)了兩行或者存在著嵌套循環(huán)，避免使用i、j或k之類的變量，須使用有意義的變量，有利于程序的

6、理解。（單字符的變量名一般只用于生命期非常短暫的變量）。3. 對(duì)于所有布爾型變量的命名，能夠直接從名稱上看出為真的條件。枚舉類型的變量名稱須包含基礎(chǔ)類型，以方便分辨變量的類型。例如，用Color變量表示ColorRed和ColorGreen枚舉類型的值。4. 在所有全局變量前首字母必須使用v， 接口指針必須使用“pi”，后跟接口名稱縮寫(xiě)。在申明變量時(shí)要避免局部變量與公共變量同名、塊內(nèi)部變量與它外部變量同名。1.3.2. 常量命名常量的命名須代表抽象的實(shí)體，而非它們所代表的值，即對(duì)于涉及物理狀態(tài)或者含有物理意義的常量，不允許直接使用不易理解的數(shù)字，必須用有意義的枚舉或宏來(lái)代替。所有常量名均全部大

7、寫(xiě)，由英文或其縮寫(xiě)，單詞間以_隔開(kāi)，如int MAX_NUM。1.3.3. 函數(shù)或方法命名函數(shù)或方法的命名應(yīng)該盡量用英文表達(dá)出函數(shù)或方法完成的功能。遵循動(dòng)賓結(jié)構(gòu)的命名法則，函數(shù)或方法名中動(dòng)詞在前，類的成員函數(shù)或方法須只使用“動(dòng)詞”， 第一個(gè)字母是小寫(xiě)，但是中間單詞的第一個(gè)字母是大寫(xiě)。如果是返回一個(gè)成員變量的值，名稱一般為get+成員變量名，如若返回的值是bool變量，一般以is作為前綴。如果是修改一個(gè)成員變量的值，名稱一般為：set + 成員變量名。函數(shù)或方法名的長(zhǎng)度不得少于8個(gè)字母。1.3.4. 文件命名文件的名字應(yīng)該使用名詞。每個(gè)單詞第一個(gè)字母須大寫(xiě)。文件的命名應(yīng)該盡量用英文表達(dá)出文件的內(nèi)

8、容。避免使用單詞的縮寫(xiě)，除非它的縮寫(xiě)已經(jīng)廣為人知，如HTTP。文件的名字中應(yīng)能反映出文件的類型（針對(duì)不同的編程語(yǔ)言，有不同類型的文件。要求文件名的長(zhǎng)度不得少于5個(gè)字母。對(duì)于文件中類的命名，前綴用大寫(xiě)字母J，后跟類的功能，中間單詞第一個(gè)字母要大寫(xiě)。1.4 注釋1.4.1. 代碼注釋注釋將增加代碼的清晰度。注釋需簡(jiǎn)潔、明了，含義準(zhǔn)確，防止注釋二義性，避免在注釋中使用縮寫(xiě)，特別是非常用縮寫(xiě)。注釋不允許包括其他的特殊字符?？梢韵葘?xiě)注釋，后寫(xiě)代碼，但對(duì)代碼的注釋不可放在代碼下面，須放在代碼上方或右方相鄰位置。1.4.2. 變量注釋1. 對(duì)于變量的注釋必須緊跟在變量的后面說(shuō)明變量的作用。對(duì)于所有有物理含義

9、的變量、常量、數(shù)據(jù)結(jié)構(gòu)聲明(包括數(shù)組、結(jié)構(gòu)、類、枚舉等)，如果其命名不是充分自注釋的，在聲明時(shí)都必須加以注釋，說(shuō)明其物理含義。原則上對(duì)于每個(gè)變量都應(yīng)該注釋，但對(duì)于意義非常明顯的變量，可以不注釋。2. 對(duì)于全局變量必須有較詳細(xì)的注釋，包括對(duì)其功能、取值范圍、哪些函數(shù)或過(guò)程存取它以及存取時(shí)注意事項(xiàng)等進(jìn)行說(shuō)明。1.4.3. 函數(shù)注釋1. 對(duì)于函數(shù)，須在函數(shù)頭部從函數(shù)的目的、功能、輸入?yún)?shù)、輸出參數(shù)、返回值、調(diào)用關(guān)系（函數(shù)、表）、“算法”、“日期”等方面進(jìn)行注釋。不允許在一行代碼或表達(dá)式的中間插入注釋。在定義函數(shù)原型時(shí)，須對(duì)每一個(gè)參數(shù)加以注釋。2. 對(duì)于函數(shù)體內(nèi)的分支語(yǔ)句（條件分支、循環(huán)語(yǔ)句等）必須編

10、寫(xiě)注釋，對(duì)于前后順序不能顛倒的情況，建議在注釋中增加序號(hào)。對(duì)于從一個(gè)case子句進(jìn)入后續(xù)的case子句，須用注釋“ Fall through”明確標(biāo)記。當(dāng)代碼段較長(zhǎng)，特別是多重嵌套時(shí)，這樣做可以使代碼更清晰，更便于閱讀。3. 如果部分代碼不再使用，但還要保存，須使用#if UNUSED標(biāo)識(shí)。如果部分代碼目前不能使用，但最后肯定要用，須使用#if LATER標(biāo)識(shí)。使用“TODO: comment”標(biāo)記未完成代碼，“ BUG: comment”標(biāo)記錯(cuò)誤代碼。1.4.4. 文件注釋1. 每個(gè)源文件有效注釋量必須占代碼量的20以上。必須在每個(gè)源文件的頭部進(jìn)行注釋，注釋須包含：版權(quán)說(shuō)明、版本號(hào)、生成日期

11、、作者、主要函數(shù)及其功能的簡(jiǎn)要說(shuō)明、與其它文件的關(guān)系、修改日志（說(shuō)明對(duì)文件的修改內(nèi)容、修改原因以及修改日期）。2. 修改代碼的同時(shí)必須修改相應(yīng)的注釋，以保證注釋與代碼的一致性。不再有用的注釋要?jiǎng)h除。1.5 錯(cuò)誤和異常處理1.5.1. 錯(cuò)誤處理系統(tǒng)在正常狀態(tài)下以及無(wú)重載和硬件失效狀態(tài)下，不應(yīng)產(chǎn)生任何異常。發(fā)生異?；蝈e(cuò)誤時(shí)，對(duì)于應(yīng)用服務(wù)層不允許拋出異常中斷服務(wù)程序的運(yùn)行，須由系統(tǒng)自行處理保持程序正常運(yùn)行，必須采用日志機(jī)制來(lái)報(bào)告異常，包括異常發(fā)生的時(shí)刻，錯(cuò)誤說(shuō)明，可能的原因、嚴(yán)重程度，發(fā)生異?；蝈e(cuò)誤的位置等。1.5.2. 異常處理不允許使用異常實(shí)現(xiàn)來(lái)控制程序的正常流程，異常實(shí)現(xiàn)只用于異常和錯(cuò)誤發(fā)生時(shí)

12、如何使程序回到正常流程。在捕獲語(yǔ)句的拋出異常子句中，必須拋出原始異常，用以維護(hù)原始錯(cuò)誤的堆棧分配。1. 【強(qiáng)制】Java 類庫(kù)中定義的一類RuntimeException可以通過(guò)預(yù)先檢查進(jìn)行規(guī)避，而不應(yīng)該通過(guò)catch 來(lái)處理，比如：IndexOutOfBoundsException，NullPointerException等等。說(shuō)明：無(wú)法通過(guò)預(yù)檢查的異常除外，如在解析一個(gè)外部傳來(lái)的字符串形式數(shù)字時(shí)，通過(guò)catch NumberFormatException來(lái)實(shí)現(xiàn)。 正例：if (obj != null) . 反例：try obj.method() catch (NullPointerExce

13、ption e) . 2. 【強(qiáng)制】異常不要用來(lái)做流程控制，條件控制，因?yàn)楫惓５奶幚硇时葪l件分支低。3. 【強(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)的異常處理。4. 【強(qiáng)制】捕獲異常是為了處理它，不要捕獲了卻什么都不處理而拋棄之，如果不想處理它，請(qǐng)將該異常拋給它的調(diào)用者。最外層的業(yè)務(wù)使用者，必須處理異常，將其轉(zhuǎn)化為用戶可以理解的內(nèi)容。5. 【強(qiáng)制】有try塊放到了事務(wù)代碼中，catch異常后，如果需要回滾事務(wù)，一定要注意手動(dòng)回滾事務(wù)。6.

14、 【強(qiáng)制】finally塊必須對(duì)資源對(duì)象、流對(duì)象進(jìn)行關(guān)閉，有異常也要做try-catch。 說(shuō)明：如果JDK7及以上，可以使用try-with-resources方式。7. 【強(qiáng)制】不能在finally塊中使用return，finally塊中的return返回后方法結(jié)束執(zhí)行，不會(huì)再執(zhí)行try塊中的return語(yǔ)句。8. 【強(qiáng)制】捕獲異常與拋異常，必須是完全匹配，或者捕獲異常是拋異常的父類。 說(shuō)明：如果預(yù)期對(duì)方拋的是繡球，實(shí)際接到的是鉛球，就會(huì)產(chǎn)生意外情況。9. 【推薦】方法的返回值可以為null，不強(qiáng)制返回空集合，或者空對(duì)象等，必須添加注釋充分說(shuō)明什么情況下會(huì)返回null值。調(diào)用方需要進(jìn)行nu

15、ll判斷防止NPE問(wèn)題。 說(shuō)明：本手冊(cè)明確防止NPE是調(diào)用者的責(zé)任。即使被調(diào)用方法返回空集合或者空對(duì)象，對(duì)調(diào)用者來(lái)說(shuō)，也并非高枕無(wú)憂，必須考慮到遠(yuǎn)程調(diào)用失敗、序列化失敗、運(yùn)行時(shí)異常等場(chǎng)景返回null的情況。10. 【推薦】防止NPE，是程序員的基本修養(yǎng)，注意NPE產(chǎn)生的場(chǎng)景：s 返回類型為基本數(shù)據(jù)類型，return包裝數(shù)據(jù)類型的對(duì)象時(shí)，自動(dòng)拆箱有可能產(chǎn)生NPE。反例：public int f() return Integer對(duì)象， 如果為null，自動(dòng)解箱拋NPE。s 數(shù)據(jù)庫(kù)的查詢結(jié)果可能為null。s 集合里的元素即使isNotEmpty，取出的數(shù)據(jù)元素也可能為null。s 遠(yuǎn)程調(diào)用返回對(duì)象

16、時(shí)，一律要求進(jìn)行空指針判斷，防止NPE。s 對(duì)于Session中獲取的數(shù)據(jù)，建議NPE檢查，避免空指針。s 級(jí)聯(lián)調(diào)用obj.getA().getB().getC()；一連串調(diào)用，易產(chǎn)生NPE。正例：使用JDK8的Optional類來(lái)防止NPE問(wèn)題。11. 【推薦】定義時(shí)區(qū)分unchecked / checked 異常，避免直接拋出newRuntimeException()，更不允許拋出Exception或者Throwable，應(yīng)使用有業(yè)務(wù)含義的自定義異常。推薦業(yè)界已定義過(guò)的自定義異常，s 如：DAOException / ServiceException等。12. 【參考】在代碼中使用“拋異常

17、”還是“返回錯(cuò)誤碼”，對(duì)于公司外的http/api開(kāi)放接口必須使用“錯(cuò)誤碼”；而應(yīng)用內(nèi)部推薦異常拋出；跨應(yīng)用間RPC調(diào)用優(yōu)先考慮使用Result方式，封裝isSuccess()方法、“錯(cuò)誤碼”、“錯(cuò)誤簡(jiǎn)短信息”。 說(shuō)明：關(guān)于RPC方法返回方式使用Result方式的理由：s 使用拋異常返回方式，調(diào)用方如果沒(méi)有捕獲到就會(huì)產(chǎn)生運(yùn)行時(shí)錯(cuò)誤。s 如果不加棧信息，只是new自定義異常，加入自己的理解的error message，對(duì)于調(diào)用端解決問(wèn)題的幫助不會(huì)太多。如果加了棧信息，在頻繁調(diào)用出錯(cuò)的情況下，數(shù)據(jù)序列化和傳輸?shù)男阅軗p耗也是問(wèn)題。13. 【參考】避免出現(xiàn)重復(fù)的代碼（Dont Repeat Yours

18、elf），即DRY原則。 說(shuō)明：隨意復(fù)制和粘貼代碼，必然會(huì)導(dǎo)致代碼的重復(fù)，在以后需要修改時(shí)，需要修改所有的副本，容易遺漏。必要時(shí)抽取共性方法，或者抽象公共類，甚至是共用模塊。正例：一個(gè)類中有多個(gè)public方法，都需要進(jìn)行數(shù)行相同的參數(shù)校驗(yàn)操作，這個(gè)時(shí)候請(qǐng)抽?。簆rivate boolean checkParam(DTO dto) . 1.6 注意事項(xiàng)1.6.1. 變量的使用1. 公共變量是增大模塊間耦合的重要原因之一，在開(kāi)發(fā)過(guò)程中能不用公共變量盡量不要使用。2. 臨時(shí)或局部變量，使用時(shí)必須首先初始化，嚴(yán)禁使用未經(jīng)初始化的變量作為右值。初始化類的實(shí)例時(shí)，除非十分必要，否則不要賦null值，在創(chuàng)

19、建新對(duì)象時(shí)必須檢查返回值，或者采用標(biāo)準(zhǔn)方法處理內(nèi)存管理錯(cuò)誤。3. 盡量不要提供public 和 protected的成員變量，應(yīng)使用屬性來(lái)代替。1.6.2. 代碼實(shí)現(xiàn)1. 不要在程序中使用運(yùn)算符的默認(rèn)優(yōu)先級(jí)，應(yīng)使用括號(hào)明確表達(dá)式的操作順序。2. 對(duì)于要返回指針但可能出錯(cuò)的函數(shù)，應(yīng)返回一個(gè)BOOL值和指向參數(shù)的指針。3. 每個(gè)接口不應(yīng)該只有一個(gè)成員，最多也不應(yīng)超過(guò)20個(gè)，盡量使每個(gè)接口中包含35個(gè)成員，并且接口成員中不要包含事件。4. 如果只有成員函數(shù)或操作符，應(yīng)該使用類，而不用結(jié)構(gòu)。5. 定義類成員時(shí)，應(yīng)明確定義其屬性public、protected或private，并按照此順序分組定義。在類

20、中不要說(shuō)明全局?jǐn)?shù)據(jù)成員，可以使用內(nèi)嵌訪問(wèn)函數(shù)，以提高性能。6. 不要使用虛函數(shù)，如多態(tài)，除非必須使用，因?yàn)樘摵瘮?shù)的開(kāi)銷較大，如果使用多態(tài)，其基類的構(gòu)造函數(shù)必須是虛函數(shù)。為了清楚其間，重載虛方法時(shí)，應(yīng)明確說(shuō)明為virtual。7. 在實(shí)現(xiàn)構(gòu)造函數(shù)時(shí)，最好不要實(shí)現(xiàn)復(fù)雜費(fèi)時(shí)的功能，但要確保初始化所有數(shù)據(jù)成員。同時(shí)要保證構(gòu)造函數(shù)、析構(gòu)函數(shù)不能失敗，應(yīng)在一個(gè)方法中實(shí)現(xiàn)內(nèi)存分配，或潛在的錯(cuò)誤處理。如果部分資源在析構(gòu)函數(shù)執(zhí)行之前釋放，要確保全部域復(fù)位，如釋放對(duì)象并將指針置為NULL，以避免多次釋放出現(xiàn)異常。8. 每個(gè)類最好存放在單獨(dú)的文件中，并且一個(gè)文件只能有一個(gè)命名空間，避免將多個(gè)命名空間放在同一個(gè)文件里

21、面，每個(gè)命名空間對(duì)應(yīng)一個(gè)目錄。1.7 日志規(guī)約1. 【強(qiáng)制】應(yīng)用中不可直接使用日志系統(tǒng)（Log4j、Logback）中的API，而應(yīng)依賴使用日志框架SLF4J中的API，使用門面模式的日志框架，有利于維護(hù)和各個(gè)類的日志處理方式統(tǒng)一。 import org.slf4j.Logger;import org.slf4j.LoggerFactory;private static final Logger logger = LoggerFactory.getLogger(Abc.class);2. 【強(qiáng)制】日志文件推薦至少保存15天，因?yàn)橛行┊惓＞邆湟浴爸堋睘轭l次發(fā)生的特點(diǎn)。3. 【強(qiáng)制】應(yīng)用中的擴(kuò)展日

22、志（如打點(diǎn)、臨時(shí)監(jiān)控、訪問(wèn)日志等）命名方式：appName_logType_logName.log。logType:日志類型，推薦分類有stats/desc/monitor/visit等；logName:日志描述。這種命名的好處：通過(guò)文件名就可知道日志文件屬于什么應(yīng)用，什么類型，什么目的，也有利于歸類查找。正例：mppserver應(yīng)用中單獨(dú)監(jiān)控時(shí)區(qū)轉(zhuǎn)換異常。如：mppserver_monitor_timeZoneConvert.log 說(shuō)明：推薦對(duì)日志進(jìn)行分類，如將錯(cuò)誤日志和業(yè)務(wù)日志分開(kāi)存放，便于開(kāi)發(fā)人員查看，也便于通過(guò)日志對(duì)系統(tǒng)進(jìn)行及時(shí)監(jiān)控。4. 【強(qiáng)制】對(duì)trace/debug/info級(jí)

23、別的日志輸出，必須使用條件輸出形式或者使用占位符的方式。 說(shuō)明：logger.debug("Processing trade with id: " + id + " symbol: " + symbol); 如果日志級(jí)別是warn，上述日志不會(huì)打印，但是會(huì)執(zhí)行字符串拼接操作，如果symbol是對(duì)象，會(huì)執(zhí)行toString()方法，浪費(fèi)了系統(tǒng)資源，執(zhí)行了上述操作，最終日志卻沒(méi)有打印。 正例：（條件） if (logger.isDebugEnabled() logger.debug("Processing trade with id: "

24、 + id + " symbol: " + symbol); 正例：（占位符） logger.debug("Processing trade with id: symbol : ", id, symbol); 5. 【強(qiáng)制】避免重復(fù)打印日志，浪費(fèi)磁盤空間，務(wù)必在log4j.xml中設(shè)置additivity=false。正例：<logger name="com.taobao.dubbo.config" additivity="false"> 6. 【強(qiáng)制】異常信息應(yīng)該包括兩類信息：案發(fā)現(xiàn)場(chǎng)信息和異常堆棧信

25、息。如果不處理，那么通過(guò)關(guān)鍵字throws往上拋出。 正例：logger.error(各類參數(shù)或者對(duì)象toString + "_" + e.getMessage(), e); 7. 【推薦】謹(jǐn)慎地記錄日志。生產(chǎn)環(huán)境禁止輸出debug日志；有選擇地輸出info日志；如果使用warn來(lái)記錄剛上線時(shí)的業(yè)務(wù)行為信息，一定要注意日志輸出量的問(wèn)題，避免把服務(wù)器磁盤撐爆，并記得及時(shí)刪除這些觀察日志。 說(shuō)明：大量地輸出無(wú)效日志，不利于系統(tǒng)性能提升，也不利于快速定位錯(cuò)誤點(diǎn)。記錄日志時(shí)請(qǐng)思考：這些日志真的有人看嗎？看到這條日志你能做什么？能不能給問(wèn)題排查帶來(lái)好處？8. 【參考】可以使用warn

26、日志級(jí)別來(lái)記錄用戶輸入?yún)?shù)錯(cuò)誤的情況，避免用戶投訴時(shí)，無(wú)所適從。注意日志輸出的級(jí)別，error級(jí)別只記錄系統(tǒng)邏輯出錯(cuò)、異常等重要的錯(cuò)誤信息。如非必要，請(qǐng)不要在此場(chǎng)景打出error級(jí)別。二、 結(jié)構(gòu)化查詢語(yǔ)言2.1. 程序風(fēng)格2.1.1. SQL語(yǔ)句1. 【強(qiáng)制】不要使用count(列名)或count(常量)來(lái)替代count(*)，count(*)是SQL92定義的標(biāo)準(zhǔn)統(tǒng)計(jì)行數(shù)的語(yǔ)法，跟數(shù)據(jù)庫(kù)無(wú)關(guān)，跟NULL和非NULL無(wú)關(guān)。說(shuō)明：count(*)會(huì)統(tǒng)計(jì)值為NULL的行，而count(列名)不會(huì)統(tǒng)計(jì)此列為NULL值的行。2. 【強(qiáng)制】count(distinct col) 計(jì)算該列除NULL之外的

27、不重復(fù)行數(shù)，注意 count(distinct col1, col2) 如果其中一列全為NULL，那么即使另一列有不同的值，也返回為0。3. 【強(qiáng)制】當(dāng)某一列的值全是NULL時(shí)，count(col)的返回結(jié)果為0，但sum(col)的返回結(jié)果為NULL，因此使用sum()時(shí)需注意NPE問(wèn)題。正例：可以使用如下方式來(lái)避免sum的NPE問(wèn)題：SELECT IF(ISNULL(SUM(g),0,SUM(g) FROM table; 4. 【強(qiáng)制】使用ISNULL()來(lái)判斷是否為NULL值。注意：NULL與任何值的直接比較都為NULL。 說(shuō)明：s NULL<>NULL的返回結(jié)果是NULL，

28、而不是false。s NULL=NULL的返回結(jié)果是NULL，而不是true。s NULL<>1的返回結(jié)果是NULL，而不是true。5. 【強(qiáng)制】 在代碼中寫(xiě)分頁(yè)查詢邏輯時(shí)，若count為0應(yīng)直接返回，避免執(zhí)行后面的分頁(yè)語(yǔ)句。6. 【強(qiáng)制】不得使用外鍵與級(jí)聯(lián)，一切外鍵概念必須在應(yīng)用層解決。 說(shuō)明：（概念解釋）學(xué)生表中的student_id是主鍵，那么成績(jī)表中的student_id則為外鍵。如果更新學(xué)生表中的student_id，同時(shí)觸發(fā)成績(jī)表中的student_id更新，則為級(jí)聯(lián)更新。外鍵與級(jí)聯(lián)更新適用于單機(jī)低并發(fā)，不適合分布式、高并發(fā)集群；級(jí)聯(lián)更新是強(qiáng)阻塞，存在數(shù)據(jù)庫(kù)更新風(fēng)暴的

29、風(fēng)險(xiǎn)；外鍵影響數(shù)據(jù)庫(kù)的插入速度。7. 【強(qiáng)制】禁止使用存儲(chǔ)過(guò)程，存儲(chǔ)過(guò)程難以調(diào)試和擴(kuò)展，更沒(méi)有移植性。8. 【強(qiáng)制】數(shù)據(jù)訂正時(shí)，刪除和修改記錄時(shí)，要先select，避免出現(xiàn)誤刪除，確認(rèn)無(wú)誤才能執(zhí)行更新語(yǔ)句。9. 【推薦】in操作能避免則避免，若實(shí)在避免不了，需要仔細(xì)評(píng)估in后邊的集合元素?cái)?shù)量，控制在1000個(gè)之內(nèi)。10. 【參考】如果有全球化需要，所有的字符存儲(chǔ)與表示，均以u(píng)tf-8編碼，注意字符統(tǒng)計(jì)函數(shù)的區(qū)別。說(shuō)明：SELECT LENGTH("輕松工作")； 返回為12 SELECT CHARACTER_LENGTH("輕松工作")； 返回為4 如果

30、要使用表情，那么使用utfmb4來(lái)進(jìn)行存儲(chǔ)，注意它與utf-8編碼的區(qū)別。11. 【參考】 TRUNCATE TABLE 比 DELETE 速度快，且使用的系統(tǒng)和事務(wù)日志資源少，但TRUNCATE無(wú)事務(wù)且不觸發(fā)trigger，有可能造成事故，故不建議在開(kāi)發(fā)代碼中使用此語(yǔ)句。說(shuō)明：TRUNCATE TABLE 在功能上與不帶 WHERE 子句的 DELETE 語(yǔ)句相同。2.1.2. 存儲(chǔ)過(guò)程a) 在存儲(chǔ)過(guò)程內(nèi)部申明變量時(shí)，必須在存儲(chǔ)過(guò)程的開(kāi)始位置；b) 通過(guò)摘要注釋分隔的兩個(gè)語(yǔ)句塊之間、局部變量和它后邊的語(yǔ)句之間留一個(gè)空行。2.1.3. 存儲(chǔ)過(guò)程命名用戶存儲(chǔ)過(guò)程要按照：USP _ + 系統(tǒng)模塊縮

31、寫(xiě)+ 功能標(biāo)識(shí) +表名（不帶前綴）或功能的英文單詞或英文單詞縮寫(xiě)的方式命名。 2.1.4. 變量命名存儲(chǔ)過(guò)程中變量名全部采用小寫(xiě)，局部變量名使用“v_”開(kāi)頭，輸入?yún)?shù)以“i_開(kāi)頭，輸出參數(shù)以“o_”開(kāi)頭，輸入輸出參數(shù)用io_開(kāi)頭。所有輸入?yún)?shù)必須顯示聲明。當(dāng)變量代表列時(shí)，應(yīng)使用%TYPE屬性對(duì)變量命名。2.1.5. 游標(biāo)命名游標(biāo)應(yīng)統(tǒng)一用后綴 “_cur” 命名。2.1.6. 常量命名常量應(yīng)統(tǒng)一用 cn_ 的前綴命名。2.2. 建表規(guī)約 1. 【強(qiáng)制】表達(dá)是與否概念的字段，必須使用is_xxx的方式命名，數(shù)據(jù)類型是unsigned tinyint（ 1表示是，0表示否）。 說(shuō)明：任何字段如果為非

32、負(fù)數(shù)，必須是unsigned。正例：表達(dá)邏輯刪除的字段名is_deleted，1表示刪除，0表示未刪除。2. 【強(qiáng)制】表名、字段名必須使用小寫(xiě)字母或數(shù)字，禁止出現(xiàn)數(shù)字開(kāi)頭，禁止兩個(gè)下劃線中間只出現(xiàn)數(shù)字。數(shù)據(jù)庫(kù)字段名的修改代價(jià)很大，因?yàn)闊o(wú)法進(jìn)行預(yù)發(fā)布，所以字段名稱需要慎重考慮。正例：getter_admin，task_config，level3_name 反例：GetterAdmin，taskConfig，level_3_name 3. 【強(qiáng)制】表名不使用復(fù)數(shù)名詞。 說(shuō)明：表名應(yīng)該僅僅表示表里面的實(shí)體內(nèi)容，不應(yīng)該表示實(shí)體數(shù)量，對(duì)應(yīng)于DO類名也是單數(shù)形式，符合表達(dá)習(xí)慣。4. 【強(qiáng)制】禁用保留字，如

33、desc、range、match、delayed等，請(qǐng)參考MySQL官方保留字。5. 【強(qiáng)制】主鍵索引名為pk_字段名；唯一索引名為uk_字段名；普通索引名則為idx_字段名。說(shuō)明：pk_ 即primary key；uk_ 即 unique key；idx_ 即index的簡(jiǎn)稱。6. 【強(qiáng)制】小數(shù)類型為decimal，禁止使用float和double。說(shuō)明：float和double在存儲(chǔ)的時(shí)候，存在精度損失的問(wèn)題，很可能在值的比較時(shí)，得到不正確的結(jié)果。如果存儲(chǔ)的數(shù)據(jù)范圍超過(guò)decimal的范圍，建議將數(shù)據(jù)拆成整數(shù)和小數(shù)分開(kāi)存儲(chǔ)。7. 【強(qiáng)制】如果存儲(chǔ)的字符串長(zhǎng)度幾乎相等，使用char定長(zhǎng)字符串

34、類型。8. 【強(qiáng)制】varchar是可變長(zhǎng)字符串，不預(yù)先分配存儲(chǔ)空間，長(zhǎng)度不要超過(guò)5000，如果存儲(chǔ)長(zhǎng)度大于此值，定義字段類型為text，獨(dú)立出來(lái)一張表，用主鍵來(lái)對(duì)應(yīng)，避免影響其它字段索引效率。9. 【強(qiáng)制】表必備三字段：id, gmt_create, gmt_modified。說(shuō)明：其中id必為主鍵，類型為unsigned bigint、單表時(shí)自增、步長(zhǎng)為1。gmt_create, gmt_modified的類型均為date_time類型。10. 【推薦】表的命名最好是加上“業(yè)務(wù)名稱_表的作用”。正例：tiger_task / tiger_reader / mpp_config 11. 【推

35、薦】庫(kù)名與應(yīng)用名稱盡量一致。12. 【推薦】如果修改字段含義或?qū)ψ侄伪硎镜臓顟B(tài)追加時(shí)，需要及時(shí)更新字段注釋。13. 【推薦】字段允許適當(dāng)冗余，以提高查詢性能，但必須考慮數(shù)據(jù)一致。冗余字段應(yīng)遵循：s 不是頻繁修改的字段。s 不是varchar超長(zhǎng)字段，更不能是text字段。 正例：商品類目名稱使用頻率高，字段長(zhǎng)度短，名稱基本一成不變，可在相關(guān)聯(lián)的表中冗余存儲(chǔ)類目名稱，避免關(guān)聯(lián)查詢。14. 【推薦】單表行數(shù)超過(guò)500萬(wàn)行或者單表容量超過(guò)2GB，才推薦進(jìn)行分庫(kù)分表。 說(shuō)明：如果預(yù)計(jì)三年后的數(shù)據(jù)量根本達(dá)不到這個(gè)級(jí)別，請(qǐng)不要在創(chuàng)建表時(shí)就分庫(kù)分表。15. 【參考】合適的字符存儲(chǔ)長(zhǎng)度，不但節(jié)約數(shù)據(jù)庫(kù)表空間、

36、節(jié)約索引存儲(chǔ)，更重要的是提升檢索速度。正例：如下表，其中無(wú)符號(hào)值可以避免誤存負(fù)數(shù)，且擴(kuò)大了表示范圍。2.1. 安全規(guī)約1. 【強(qiáng)制】隸屬于用戶個(gè)人的頁(yè)面或者功能必須進(jìn)行權(quán)限控制校驗(yàn)。說(shuō)明：防止沒(méi)有做水平權(quán)限校驗(yàn)就可隨意訪問(wèn)、修改、刪除別人的數(shù)據(jù)，比如查看他人的私信內(nèi)容、修改他人的訂單。2. 【強(qiáng)制】用戶敏感數(shù)據(jù)禁止直接展示，必須對(duì)展示數(shù)據(jù)進(jìn)行脫敏。說(shuō)明：查看個(gè)人手機(jī)號(hào)碼會(huì)顯示成:158*9119，隱藏中間4位，防止隱私泄露。3. 【強(qiáng)制】用戶輸入的SQL參數(shù)嚴(yán)格使用參數(shù)綁定或者M(jìn)ETADATA字段值限定，防止SQL注入，禁止字符串拼接SQL訪問(wèn)數(shù)據(jù)庫(kù)。4. 【強(qiáng)制】用戶請(qǐng)求傳入的任何參數(shù)必須做

37、有效性驗(yàn)證。說(shuō)明：忽略參數(shù)校驗(yàn)可能導(dǎo)致：s page size過(guò)大導(dǎo)致內(nèi)存溢出s 惡意order by導(dǎo)致數(shù)據(jù)庫(kù)慢查詢s 任意重定向s SQL注入s 反序列化注入s 正則輸入源串拒絕服務(wù)ReDoS說(shuō)明：Java代碼用正則來(lái)驗(yàn)證客戶端的輸入，有些正則寫(xiě)法驗(yàn)證普通用戶輸入沒(méi)有問(wèn)題，但是如果攻擊人員使用的是特殊構(gòu)造的字符串來(lái)驗(yàn)證，有可能導(dǎo)致死循環(huán)的結(jié)果。5. 【強(qiáng)制】禁止向HTML頁(yè)面輸出未經(jīng)安全過(guò)濾或未正確轉(zhuǎn)義的用戶數(shù)據(jù)。6. 【強(qiáng)制】表單、AJAX提交必須執(zhí)行CSRF安全過(guò)濾。說(shuō)明：CSRF(Cross-site request forgery)跨站請(qǐng)求偽造是一類常見(jiàn)編程漏洞。對(duì)于存在CSRF漏洞的應(yīng)用/網(wǎng)站，攻擊者可以事先構(gòu)造好URL，只要受害者用戶一訪問(wèn)，后臺(tái)便在用戶不知情情況下對(duì)數(shù)據(jù)庫(kù)中用戶參數(shù)進(jìn)行相應(yīng)修改。7. 【強(qiáng)制】在使用平臺(tái)資源，譬如短信、郵件、電話、下單、支付，必須實(shí)現(xiàn)正確的防