JAVA開發規範

 貼一份我以前整理的 JAVA開發規範：

 

 

 

JAVA開發規範

luo@leader.cn

代碼總體風格             

• Controller類，不要直接使用Map，HttpServletRequest request,HttpServletResponse response 做爲參數，不要使用 Servlet API的接口          
• 一個service類不該該引用其餘service類，可是能夠引用多個dao層對象
• mapper類應該儘可能輕量級，不要過多的自定義sql
• 使用BeanUtil,而不是setXxx(info.getXxx)                       
• 避免重複代碼，代碼段出現過3次，必定要提取更多的公共代碼到基礎層， 好比mint
• 方法不超過200行，一個類不超過1000                      
• 看到醜陋代碼， 重構它！時不時 重構！                  
• 使用設計模式！
• 代碼要 提升 複用， 可是不能複製，複製一時爽，可是並不能提升 複用性！~      
• 對本身作的模塊負責， 對其業務邏輯要一清二楚！ 不然就 不合格~@！         
• 面向對象編程，更重要的是 面向接口
• 同一個含義的枚舉， 全局應該只出現一次，而不是每一個模塊一次， 不然改起來仍是很麻煩！避免枚舉類氾濫
• 不要動不動就mq，避免消息氾濫
•  
• 不超過3層 if else                   
• 專業術語的 英文名字要統一，簡寫也要統一 
• 通常狀況下，方法簽名不要拋出異常，除非涉及資源的工具類 ！
• 不該該使用 硬編碼
•  
• 提升 內聚， 下降耦合！ 不要一個Service就一個方法， 不要引用太多其餘的Service， 分得太散了就會 致使 太鬆散，內聚性太差！ 看代碼，調試都會很痛苦！
•  
• 杜絕代碼壞味道！囉嗦 / 低級 / 重複代碼， 一律拒絕！
• 可以提取的， 必定要提取到公共位置， 杜絕 複製黏貼， 杜絕醜陋代碼！
• 代碼保持簡單，靈活，複用性，獨立，高內聚，低耦合
• 每一個方法要 邏輯十分清晰， 一目瞭然
• 代碼應該清晰可讀，儘可能保持簡單易讀
• 統一的code style
• 不要爲了 微服務而 微服務 ！

 

你們使用統一的規範，方便交流，減小維護成本             

服務分層、命名規範        

服務名\服務名-api\src\main\java\com\wisdom\服務名\                                                   

         service              全部的服務接口，統一前綴爲I,後綴爲 Service                          

                   子模塊名x                                 

                            IXxxService                         

                   子模塊名y                                 

                            IXxxService                         

                   IMainXxx1Service    不要出現         XxxParam、 XxxSearch

                   IMainXxx2Service   

                   IMainXxx3Service                               

                   bank other service                     

 

     dto            全部的先後端交互對象，統一後綴爲 DTO

        

         exception                  全部的自定義異常，應該繼承於運行時異常，統一後綴爲Exception                      

                                                       

服務名\服務名-provider\src\main\java\com\wisdom\服務名\                                                  

         common           全部全局的共享東西：全部的常量、枚舉、靜態類，包括各類工具類，redis、mq訪問工具類                         

                   Constants         當前服務共用的常量類                  

                   XxxUtil               當前服務共用的工具類                  

                   XxxBaseService        當前服務共用的服務類                  

                   XxxRedisUtil              當前服務共用的redis工具類                

                   XxxRabbitMqUtil      當前服務共用的mq工具類          

                   XxxConfig          示例：com.wisdom.jasmine.mvc.CheckLoginInterceptor

                   XxxHandler       示例：com.wisdom.jasmine.mvc.GlobalExceptionHandler

XxxException 特有的異常類

                                                       

         service              處理業務邏輯，全部的服務接口實現類，統一後綴爲 ServiceImpl，若有必要，下面還能夠建立一層package，代表子模塊名，可是package不宜太深                      

                   子模塊名x                                 

                            XxxServiceImpl                           

                   子模塊名y                                 

                            YyyServiceImpl                           

                   MainXxx1ServiceImpl                                  

                   MainXxx2ServiceImpl                                  

                   MainXxx3ServiceImpl                                  

                                                       

         mapper             全部的數據庫訪問類，統一後綴爲Mapper                         

                   XxxMapper                                  

                   YyyMapper                         只有複雜的 查詢sql， 不該該有修改、新增、刪除sql

                                              

         model                全部的數據庫實體映射類，統一後綴爲Model                   

                  XxxModel                           

                   YyyModel

                                              

  message  後端和mq 交互的pojo，儘可能少使用，應該使用DTO

 

                                                       

                                    

Web層就是controller層，直接前端對接項目，服務名必定要有一個 web 後綴

 

服務名\服務名-web\src\main\java\com\wisdom\服務名\                                                          

         controller          處理視圖，全部的Controller類，統一後綴爲 Controller                           

                   XxxController                              

                                                       

api 服務的dto，provider服務的model 應該不相同，不然考慮是否服務沒定義 / 劃分好。

 

每一個表對應一個model，一個mapper。但不須要每個model 一個service，好比一些關聯表的查詢/新增/修改/刪除操做，直接在主表對於的service完成。

 

每一個service應該有對應的一個主表。但有時候也可能有多個。

 

通常狀況下，service和mapper和model和數據庫表 同名。

 

XxxParam、 XxxSearch、XxxMessage 不能忘文知義，增長溝通成本，並且轉換起來很麻煩。

 

爲何Service層不能調用其它Service？               

比較清晰的單向關聯：

 

 

N向關聯（可能存在循環依賴）：

 

 

 

通常命名規範

Controller層	Service層	DAO層
query/page	getOne	selectOne	獲取單個實體,參數就是實體自己
	getByYyy	selectById	按照ID獲取單個實體
	list Page	selectByXxx	按照某條件獲取單個實體,參數就是實體某個字段
			按照某條件,獲取實體的list集合
	listAll	selectAll	返回全部行
add	add	insert	新增單個實體。不存在 insertByXxx 方法
modify	modify	update	更新單個實體
		updateByXxx	這個狀況少見， 通常是經過id 進行更新
save	save		新增或修改， 不須要saveOrUpdate 方法名
業務方法	相同 業務方法	相同或不須要

 

Service 層：

list獲取實體的list集合

page 分頁查詢，統一返回， PageInfo<實體Model>

 

數據流轉：

 

 

 

 

數據庫層命名規範             

字段使用要統一， state、status、                                統一 status

表： 表的業務含義應該清晰明確， 不宜使用過多字段。<  30 ..                

                  

princ         inter

不要這樣引發誤會的縮寫，        

要麼就不使用縮寫，而是全寫，要麼使用通用的縮寫，        

 

 

pom 規範             

         pom 提取公共配置 commons                        

         使用最少的dependency，儘可能從parent中繼承                          

         依賴應該儘可能簡化                           

         須要仔細考慮每個dependency 是不是必須的

                                    

註釋規範              

         每一個類寫明 用途、註釋、做者、關聯                         

         每次修改 寫明緣由、做者、時間      

/**
 * 這個類是爲了作什麼，主要用途是abc

 *
 * @author LK(lk@qq.com)
 * @Time 2018-12-29
 */

 

javadoc 註釋標籤語法

@author   對類的說明 標明開發該類模塊的做者

@version   對類的說明 標明該類模塊的版本

@see     對類、屬性、方法的說明 參考轉向，也就是相關主題

@param    對方法的說明 對方法中某參數的說明

@return   對方法的說明 對方法返回值的說明

@exception  對方法的說明 對方法可能拋出的異常進行說明

日誌規範              

         理解和使用 debug、info、warn、error 各個級別，通常日誌使用info基本，捕捉到錯誤若是要記錄異常，必須使用 error 級別。

                                    

異常處理規範             

• Controller 作主要的參數檢驗，空指針檢查。不作具體的異常處理， 異常處理統一到MVC的ExceptionHandler

 

• Service層捕捉全部的已知異常（受檢異常），對系統異常封裝返回，對業務異常返回錯誤碼和錯誤信息，空指針檢查。（處理已知異常，運行時異常不用管）

 

• dao/mapper 不捕捉異常      

 

儘可能不要try catch(Exception e) 這個由統一的MVC的ExceptionHandler 來作

不合理的示例                             

mapper.AttachmentMapper#deleteAttachmentByObject 方法是否是能夠簡化爲 delete ？

mapper.AttachmentMapper#queryByObject                      queryByObject -> query

provider.RepayOverdueProvider#insertOrUpdateCommit 奇怪的命名

provider.CreditorAdvanceProvider           provider 是什麼？ service 仍是Dao？

lock.LockKeys                              lock 一個package 只有一個類， 是否是放到 constants 更好？

invite.enums.QueryDateTypeEnum         enums 是否是放到 constants 更好？

invite.utils.ActivityInviteUtil                      不須要單獨創建util 包                                    

product.utils.UploadUtils                           UploadUtils 並非 product 纔有的一個工具類

product.service.impl.ProductServiceImpl        provider 服務 使用service 仍是 service.impl ？ 至少應該是統一

domain.custom.CollectionCalendarView                                             

search.CreditorAdvanceSearch                                           

com.wisdom.daffodil.model.bank.BindCardReq     不要搞特殊化，統一使用DTO就好

 

 

阿里巴巴規範             

         【強制】POJO 類中布爾類型的變量，都不要加 is ，不然部分框架解析會引發序列化錯誤。                          

         【強制】不要使用一個常量類維護全部常量，應該按常量功能進行歸類，分開維護                           

                                    

         【強制】全部的覆寫方法，必須加@ Override 註解。                      

         【強制】全部的相同類型的包裝類對象之間值的比較，所有使用 equals 方法比較。                        

         【強制】關於基本數據類型與包裝數據類型的使用標準以下：                      

                   1 ） 全部的 POJO 類屬性必須使用包裝數據類型。               

                   2 ） RPC 方法的返回值和參數必須使用包裝數據類型。               

                   3 ） 全部的局部變量【推薦】使用基本數據類型。               

         【強制】定義 DO / DTO / VO 等 POJO 類時，不要設定任何屬性默認值。                           

         【強制】 POJO 類必須寫 toString 方法。使用 IDE 的中工具： source > generate ，toString時，若是繼承了另外一個 POJO 類，注意在前面加一下 super.toString 。                       

         【強制】關於 hashCode 和 equals 的處理，遵循以下規則：                        

                   1） 只要重寫 equals ，就必須重寫 hashCode 。          

                   2） 由於 Set 存儲的是不重複的對象，依據 hashCode 和 equals 進行判斷，因此 Set 存儲的對象必須重寫這兩個方法。                  

                   3） 若是自定義對象作爲 Map 的鍵，那麼必須重寫 hashCode 和 equals 。           

                                    

         【強制】 ArrayList 的 subList 結果不可強轉成 ArrayList ， 不然會拋出 ClassCastException異常： java . util . RandomAccessSubList cannot be cast to java . util . ArrayList ;                       

         【強制】 在 subList 場景中，高度注意對原集合元素個數的修改，會致使子列表的遍歷、增長、刪除均產生 ConcurrentModificationException 異常。                      

         【強制】使用工具類 Arrays . asList() 把數組轉換成集合時，不能使用其修改集合相關的方法，它的 add / remove / clear 方法會拋出UnsupportedOperationException 異常。                      

                                    

                                    

         【強制】線程資源必須經過線程池提供，不容許在應用中自行顯式建立線程。                           

         【強制】線程池不容許使用 Executors 去建立，而是經過 ThreadPoolExecutor 的方式，這樣的處理方式讓寫的同窗更加明確線程池的運行規則，規避資源耗盡的風險。                           

         【強制】 SimpleDateFormat 是線程不安全的類，通常不要定義爲 static 變量，若是定義爲                         

                   static ，必須加鎖，或者使用 DateUtils 工具類。          

         【強制】對多個資源、數據庫表、對象同時加鎖時，須要保持一致的加鎖順序，不然可能會形成死鎖。                      

         【強制】多線程並行處理定時任務時， Timer 運行多個 TimeTask 時，只要其中之一沒有捕獲拋出的異常，其它任務便會自動終止運行，使用 ScheduledExecutorService 則沒有這個問題。                         

         【強制】在一個 switch 塊內，每一個 case 要麼經過 break / return 等來終止，要麼註釋說明程序將繼續執行到哪個 case 爲止 ； 在一個 switch 塊內，都必須包含一個 default 語句而且放在最後，即便它什麼代碼也沒有。                     

                                    

         【強制】不要捕獲 Java 類庫中定義的繼承自 RuntimeException 的運行時異常類，如：                          

                   IndexOutOfBoundsException / NullPointerException，這類異常由程序員預檢查              

                   來規避，保證程序健壯性。                  

         【強制】異常不要用來作流程控制，條件控制，由於異常的處理效率比條件分支低。                      

         【強制】對大段代碼進行try-catch，這是不負責任的表現。catch時請分清穩定代碼和非穩定代碼，穩定代碼指的是不管如何不會出錯的代碼。對於非穩定代碼的catch儘量進行區分異常類型，再作對應的異常處理。                   

         【強制】捕獲異常是爲了處理它，不要捕獲了卻什麼都不處理而拋棄之，若是不想處理它，請將該異常拋給它的調用者。最外層的業務使用者，必須處理異常，將其轉化爲用戶能夠理解的內容。                           

         【參考】在代碼中使用「拋異常」仍是「返回錯誤碼」，對於公司外的http/api開放接口必須使用「錯誤碼」；而應用內部推薦異常拋出；跨應用間RPC調用優先考慮使用Result方式，封裝isSuccess()方法、「錯誤碼」、「錯誤簡短信息」。                           

 

文件是：

https://files.cnblogs.com/files/FlyAway2013/2018-JAVA%E5%BC%80%E5%8F%91%E8%A7%84%E8%8C%83.rar