Java開發規範(一)

隨着《阿里巴巴Java開發手冊》的公開，從新又掀起一股編碼規範的風口。結合《華爲java編程規範》以及團隊內部的實踐，咱們也作了一段開發規範。不求最全，但求有效。

裏面的規範，暫時只分兩類。「強制」，即若是違反就不能使用級別。好比說，在codereview有遇到 ，那就會直接把pull request打回去，拒絕合併到開發者穩定分支上。「推薦」，即建議怎麼作，可是不強制，根據不一樣的水平能夠作一些參考。

通用規範

全部的狀況下都通用

一、 【強制】命名所有使用英文，禁止中文或者中英混合。項目名除外，由於有的項目是按域名來命名的，域名自己有多是中文拼音。

例子：

域名：kecheng.xxx.com
項目名：xxx-web-kecheng
複製代碼

二、 【強制】禁止使用縮寫，除非提供一個縮寫列表

反例：

# 這裏的t究竟是什麼意思？topic_id?仍是teacher_id?
字段：t_id
複製代碼

三、 【強制】禁止出現除了後綴或者前綴3個單詞。若是超過3個，說明想表達的職責太多，能夠拆分或者封裝。

編程語言

這裏主要指的是Java語言，其餘的語言也能夠借鑑這些準則

類

一、 【強制】須要有統一的後綴或者前綴。爲了一看類名，就知道這個類幹什麼的。

前綴列表：

• 抽象類（Abstract）
• 接口（I）
  正例：

接口：IViewTag
抽象類：AbstractViewTag  
具體實現類：UserViewTag
複製代碼

後綴列表：

• 實體(Entity)。數據庫持久對象。
• 表單（Form)。用於封裝、校驗http參數。
• 數據傳輸對象(DTO)。用於暴露接口的返回數據
• 基礎服務(BaseService)。單實體能夠自描述的服務。
• 業務服務(BusinessService)。集合多個單實體的服務。
• 頁面服務(ViewService)。涉及到視圖頁面的服務。
• 模塊(Module)。http入口模塊。
• 異常(Exception)
• 工具(Util)
• 枚舉(Enum)
• 視圖標籤（ViewTag）
• ....(其餘的，好比：Filter之類）
  正例：

實體：UserEntity
基礎服務：UserBaseService 
業務服務：AuthorityBusinessService
複製代碼

二、 【強制】全部參與業務的類禁止使用內部類。

屬性

一、 【強制】常量必須是：大寫+下劃線，禁止多個單詞連在一塊兒

正例：

private final static String PAGE_SIZE=10;
複製代碼

反例：

private final static String PAGESIZE=10;
private final static String pageSize=10;
複製代碼

二、 【強制】布爾類型禁止添加"is"前綴。部分框架解析會引發序列化錯誤。

反例：

# 對應的getter和setter爲：isRead和setRead
private boolean isRead
複製代碼

正例:

# 對應的getter和setter爲：isRead和setRead
private boolean read;
複製代碼

三、 【強制】計數器禁止使用複數

反例：

private int readCounts;
複製代碼

正例:

private int readCount;
複製代碼

四、 【強制】自描述屬性裏不要出現類名的描述

反例：

#UserEntity類
private String userName;
private int userAge;
複製代碼

正例：

#UserEntity類
private String name;
private int age;
複製代碼

五、【強制】關聯其餘實體的屬性命名規則：對應的實體去掉後綴+用途

正例：

屬性名：teacherId ,對應的實體是TeacherEntity
屬性名：favorCount，對應的實體是FavorEntity
複製代碼

反例：

屬性名：tId。根本不知道是哪一個實體的外鍵。有多是Teacher有多是Topic，還得猜半天
複製代碼

六、 【強制】禁止經過定義定義成常量（1，2）來維護類型值，須要經過枚舉

反例：

private final static int SUCESS=1;
private final static int FAIL=2;
複製代碼

正例：

定義一個枚舉
複製代碼

方法

一、 【強制】接口裏的方法禁止有修飾符。
反例

#接口裏的方法public void eat();
複製代碼

正例：

#接口裏的方法void eat();
複製代碼

二、 【推薦】方法參數必須使用final來修飾。final可提升程序響應效率。能夠經過Eclipse的cleanup來實現。
正例：

public void eat(final int size);
複製代碼

反例

：

public void eat(int size);
複製代碼

三、 【強制】每個方法參數都須要被處理。module層的方法裏的對象參數
能夠不判空，由於架構已經作處理了，不可能爲空。
被處理指的是：

• 拋異常。
• 直接返回。
• 有對應的業務處理邏輯。

例子：

public void add(long userId,String content){
    //異常驗證
    ExceptionUtil.checkId(userId,"用戶id")
    //直接返回
    if(Util.isEmpty(content)){
        return ;
    }
}

public List<CourseEntity> list(int type){
    Cnd cnd = Cnd.limit();
    //有對應的業務邏輯處理
    if(type>0){
        cnd.and("type","=",type);
    }
    return dbDao.query(CourseEntity.class,cnd,null);
}
複製代碼

四、 【強制】同一個類裏有多個一致的參數（3個以上）的方法，須要抽取接口或者經過實體來承載

反例

public FavorEntity add(int type,long sourceId,long userId);
public FavorEntity delete(int type,long sourceId,long userId);
複製代碼

正例

public FavorEntity add(IFavor favor);
public FavorEntity delete(IFavor favor);
複製代碼

五、 【強制】方法名必須是動詞或者動賓。http接口須要知明達意，能夠不按這個規則。好比：mycourse,home,banner
方法命名格式：

• is+動詞|形容詞
• 動詞【+名詞|形容詞】

例子：

public void isSucess();
public void on();
public void sendEmail();
複製代碼

統一命名列表：

• add 新增
• update 修改
• delete 刪除
• get 獲取單個對象
• list 獲取集合對象
• getMap 獲取map數據
• count 數量

方法前綴後綴命名說明：
原則上不添加後綴，若是添加後綴的話，若是有添加，命名格式爲：updatexxxx4yyyyByzzzz

• xxxx：表示對象的屬性
• yyyy：表示查詢的條件（根據自描述屬性查詢）
• zzzz：表示查詢的條件（根據其餘描述屬性查詢）

例子：

--xxxx狀況:用戶
public void updateName();();
public void updateNickName();
--yyyy狀況：資訊
public List<NewsEntity> list4Latest();
public List<NewsEntity> list4Top();     
--zzzz狀況：課程
public List<CourseEntity> listByTeacher();
public List<CourseEntity> listByKnowledge();

--綜合使用
public List<CourseEntity> listCourse4TopByTeacher();
複製代碼

六、　【強制】一個方法裏代碼行數不能超過1屏（即30行）。通常來講超過30的行，業務關注點、複雜數比較高，很難維護。超過３０行須要封裝方法
七、 【強制】局部變量命名不能有連續的名稱。連續的命名不具備可維護性。每一個變量都須要有清晰的概念。

反例

：

String head1;
String head2;
複製代碼

正例：

String title;
String content;
複製代碼

八、 【強制】禁止有任何魔鬼數據獨立存在。能夠定義一個有含義的變量來承載

反例

：

if(type ==1){
 //審覈成功
  下面15行代碼
}
複製代碼

正例：

private final static int SUCESS=1;
...
.if(type ==SUCESS){ 
下面15行代碼
}
複製代碼

九、 【強制】判斷表達式要使用布爾變量或者封裝方法。表達式是變化點。在維護的時候，表達式不知名達意。

反例

：

if(user!=null&&!Util.isEmpty(user.name)&&!Util.isEmpty(user.provicne)){
 //下面15行代碼
}
複製代碼

正例：

if(isFilledBaseInfo(user)){
 //下面15行代碼
}
複製代碼

十、【強制】if()...else if()...else個數不能多於4個，嵌套不能深於3層
能夠經過如下的方法來消除：

• 設計模式
• 抽取方法
• 使用return

反例

：

if(isAdmin()){
 ...
}else if(isTeacher()){
 ...
}
複製代碼

正例：

if(isAdmin()){
 ... return;
}if(isTeacher()){
 ... return;
}
複製代碼

十一、 【推薦】採用防護式編程，先判斷錯誤的業務，而後再寫正確的業務。防護式編程結構清晰分明：先把全部錯誤窮舉，而後集中處理正確邏輯。

反例

：

if(null!=user && user.hasAuth()){
 正確邏輯
}
複製代碼

正例：

if(null==user || ！user.hasAuth()){ return;}
正確邏輯
複製代碼

十二、 【推薦】for裏不建議寫io。io包括：數據庫、緩存，文件讀寫等
1三、 【強制】多個不一樣的結構（業務相近的代碼），須要有且只有一個空行

反例

：

long userId = fetchUser.getCurrentUserId();
Sql sql = latentCustomerQueryForm.pager(sqlManager);
Map<String, Object> map = FormUtil.list(dbDao, sql, pager);
List<DictInfoEntity> grades = dictBaseService.listDict(DictInfoEnum.GRADE.stringKey());
List<DictInfoEntity> infoOrigins = dictBaseService.listDict(DictInfoEnum.INFOORIGIN.stringKey());
map.put("queryForm", latentCustomerQueryForm);
map.put("grades", grades);
map.put("infoOrigins", infoOrigins);
return map;
複製代碼

正例：

long userId = fetchUser.getCurrentUserId();
Sql sql = latentCustomerQueryForm.pager(sqlManager);
Map<String, Object> map = FormUtil.list(dbDao, sql, pager); 

List<DictInfoEntity> grades = dictBaseService.listDict(DictInfoEnum.GRADE.stringKey());
List<DictInfoEntity> infoOrigins = dictBaseService.listDict

map.put("queryForm", latentCustomerQueryForm);
map.put("grades", grades);
map.put("infoOrigins", infoOrigins);
return map;
複製代碼

1四、 【推薦】不參與計算的變量不要定義變量

反例

：

long userId = fetchUser.getCurrentUserId();
Sql sql = latentCustomerQueryForm.pager(sqlManager);
Map<String, Object> map = FormUtil.list(dbDao, sql, pager); 

List<DictInfoEntity> grades = dictBaseService.listDict(DictInfoEnum.GRADE.stringKey());
List<DictInfoEntity> infoOrigins = dictBaseService.listDict(DictInfoEnum.INFOORIGIN.stringKey());

map.put("queryForm", latentCustomerQueryForm);
map.put("grades", grades);
map.put("infoOrigins", infoOrigins);
return map;
複製代碼

正例：

long userId = fetchUser.getCurrentUserId();
Sql sql = latentCustomerQueryForm.pager(sqlManager);
Map<String, Object> map = FormUtil.list(dbDao, sql, pager); 

map.put("grades", dictBaseService.listDict(DictInfoEnum.GRADE.stringKey()));
map.put("infoOrigins", dictBaseService.listDict(DictInfoEnum.INFOORIGIN.stringKey()));
return map;
複製代碼

1五、 【強制】若是有捕獲異常，必須有對應的處理業務。若是沒有對應的處理業務，不要捕獲，能夠直接throw，讓架構統一處理
你本身catch，確定不但願用戶看到錯誤日誌，那麼 從用戶那邊看到是正常業務。catch了什麼都沒幹，用戶每每看到的是什麼都沒發生，他會覺得網站掛了或者功能快。

1六、 【強制】禁止使用exception.getMessge()處理錯誤信息。應該使用exception.toString()。由於exception.getMessage()，在npe拋出異常的時候，什麼信息都不顯示。

反例

：

} catch (Exception e) { 
logger.error(e.getMessage());
 }
複製代碼

正例：

} catch (Exception e) {
 logger.error(e.toString());
 }
複製代碼

1七、 【強制】禁止使用System.out.print。統一使用Eclipse的log4e插件生成日誌（不要定義具體的日誌實現，要定義的是slf4j的接口）
1八、 【推薦】公開的接口，一旦發佈成穩定版，禁止修改方法簽名（方法名，參數）
若是要修改,須要提供新的接口，老的不能修改。由於一修改方法簽名。
好比：js調用可能就報錯了，功能就沒辦法使用；工具類接口一變，其餘項目就會報錯了，沒辦法向下兼容。
1九、 【推薦】方法放置順序：public-->protected-->private。一個類，每每使用者更關注的是public的。構造方法、重載方法、雷同方法，按順序放在一塊兒

歡迎加入學習交流羣569772982，你們一塊兒學習交流。