Java開發規範

時間  2019-11-18
標籤 java 開發 規範 欄目 Java 简体版
原文   原文鏈接

Java開發規範

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

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

通用規範

全部的狀況下都通用css

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

例子：java

域名：kecheng.xxx.com
項目名：xxx-web-kecheng

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

反例：web

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

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

編程語言

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

類

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

前綴列表：

  • 抽象類（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八、 【推薦】公開的接口，一旦發佈成穩定版，禁止修改方法簽名（方法名，參數）

若是要修改,須要提供新的接口，老的不能修改。老的接口上添加@Deprecated註解，而且使用@see清晰的說明採用新接口或新服務是什麼

由於一修改方法簽名。好比：js調用可能就報錯了，功能就沒辦法使用；工具類接口一變，其餘項目就會報錯了，沒辦法向下兼容。

1九、 【推薦】方法放置順序：public-->protected-->private。一個類，每每使用者更關注的是public的。構造方法、重載方法、雷同方法，按順序放在一塊兒

註釋

一、 【強制】格式結構統一使用eclipse模板，禁止自定義。

二、 【強制】類、方法、屬性都必須有註釋。若是實在來不及，能夠先生成TODO。由於能夠經過TODO視圖，把註解補回來。

三、 【強制】類上必需要有做者，若是有修改，還要添加上修改者，若是有結隊也要寫上。要有用戶名還要有郵箱

例子：

/** * 字典 * * @author ZhuangJunxiang(529572571@qq.com) * @version 2017-03-06 */

四、 【強制】註釋要直譯，描述要寫算法或者思路或者注意事項。不要在註釋上代碼裏的每一行徹底暴露出來，使用者根本不關注實現。

反例：

/** * 學生分頁查詢 #方法里根據沒有學生。。。。 * * @param page 分頁對象 * @param studentForm 學生 * @return 分頁對象 */
public Page<Map<String, Object>> findPageList(Page<Map<String, Object>> page, StudentForm studentForm) {

五、 【強制】方法裏禁止寫註釋。不要有多餘的註釋，讓變量和屬性自描述或者抽取方法。若是有算法寫到方法註釋上。

反例：

//填充基本信息
fillBaseInfo();
//填充帳號信息
fillAccoutInfo();

六、 【強制】方法裏禁止註釋掉代碼。統一經過版本控制軟件（git)來解決。邏輯是正確的，可是如今暫時不能使用，能夠暫時註釋，可是必須寫上TODO。

TODO格式： TODO 標記人 緣由

例子：

//TODO 張三 當前用戶還未處理，由於登陸尚未調通
//long userId = fetchUser.getCurrentUserId();
long userId = 1L;
....

數據庫

這裏主要指的是MySQL，其餘的數據庫也能夠借鑑這些準則

表

一、【強制】統一使用表名命名規範

表名規範：分層+項目名縮寫+下劃線+實體名（小寫字母）【+下劃線+實體名（小寫字母）+rel】

例子：

表名：bc_course  對應的信息：基礎服務層，項目縮寫爲c裏對應的CourseEntity實體對應的表

表名：sc_course_knowledge_rel 對應的信息：綜合服務層，項目縮寫爲c裏對應的CourseEntity實體和KnowledgeEntity實體的關係表

分層：

  • 基礎服務：b
  • 綜合服務：s
  • webapp服務：a

表的種類：

  • 映射實體的表：前綴_實體名（小寫字母）。實體裏有多個單詞，用下劃線隔開。
  • 關係表：前綴_實體名1（小寫字母）_實體名2（小寫字母）_rel。同一個實體裏有多個單詞,拼接在一塊

例子：

bc_course_group -->CourseGroupEntity
sc_coursegroup_coursepack_rel -->CourseGroupEntity和CoursePackEntity的關係表

二、 【強制】統一使用innoDB引擎。

三、 【推薦】表名不要關聯其餘表名信息
反例：

bc_course
bc_course_video
bc_course_video_study_log

正例：

bc_course
bc_video
bc_study_log

索引

一、 【強制】業務上具備惟一特性的字段，即便是組合字段，必須使用惟一索引。好比： 用戶名，編號等。若是沒有添加惟一索引，即便在應用層作了很是完善的校驗和控制，只要沒有惟一索引，必然有髒數據

二、 【強制】惟一索引命名：uk_字段名,普通索引命名：idx_字段名

三、 【強制】禁止對text定義索引。若是有對這類字段搜索的需求，能夠經過全文索引方法來實現功能。

四、 【推薦】varchar定義索引長度。通常有搜索的話，用戶也不會輸入太多字。長度統一10爲倍數，不要超過50

字段

一、 【強制】主鍵禁止使用自增。不一樣庫同步數據的時候，會出問題。影響插入性能。

二、 【強制】字段所有禁止爲空。爲空的話，很容易在使用的時候出現npe。若是能夠不填，經過默認值方法來處理。

三、 【強制】禁止使用外鍵，只能在概念和應用層次使用外鍵

外鍵的字段命名：表名去除前綴+id

四、 【強制】禁止使用枚舉、集合類型

五、 【強制】禁止在數據庫使用blog存在文件。數據庫只存相對的url路徑

六、 【強制】類型使用規範

  • 布爾：bit
  • 時間（精確到天）：date
  • 時間（精確到秒）：datetime
  • 浮點:deciaml
  • 字符串（長度小於10或者長度大於10可是長度相同）：char
  • 字符串（長度爲10~5000,長度不相同）：varchar
  • 字符串（富文本）：text

七、 【強制】必有字段

  • 主鍵
  • 建立時間
  • 修改時間
  • 假刪狀態（若是是資源數據必須有，若是是關係數據禁止有）

八、 【推薦】能夠適合添加冗餘數據，這樣能夠增快查詢數據。

冗餘類型：

  • 計數器、計分器等統計數據
  • 一旦生成不會修改的數據

九、 【推薦】字段順序：自描述-->關聯其餘表的描述-->功能性-->必有字段

註釋

一、 【強制】表名或者字段註釋的格式：直譯【（補充說明）】

反例：

表名：t_first_login，註釋：本表用於處理河北聯通卡的臨時業務問題，記錄已經使用web登陸過的卡號

正例：

表名：t_first_login，註釋：首次登陸（用於處理河北聯通卡的臨時業務問題，記錄已經使用web登陸過的卡號）

二、 【強制】禁止帶「表」，「數據」等多餘的字眼

反例：

表名：aw_input_batch，註釋：輸入批次表
表名：t_admission_110000，註釋：北京院校專業數據

三、 【推薦】若是類型字段，有變動，同步註釋

例子：

status   狀態（0：成功，1：失敗）
//過了一段時間，又多了一個凍結的狀態
status   狀態（0：成功，1：失敗，2：凍結）

sql

一、 【強制】禁止select *。數據庫查看執行時間性能沒有響應。可是返回的數據量會變大，對網絡開銷有影響，最終仍是會影響性能，並且也會影響數據庫的二進步日誌

二、 【強制】使用select count(*)。select count(name) 不記錄null的行數。並且官方已經澄清過，不影響性能 。

反例：

select count(1)
select count(id)

三、 【強制】使用sum函數時，必須使用IFNULL(sum(),0)。若是sum函數沒有查到結果返回null，容易出現npe。

四、 【推薦】禁止出現or。能夠經過使用in或者unit all來替換

五、 【推薦】order by的場景，建立索引時order by 後面的字段也必須是組合索引的一部分，而且放在索引順序的最後，避免出現file_sort

正例：

where a=？ and b=? order by c; 索引：a_b_c

六、 【推薦】建立組合索引時，區分度最高的放在最左邊

正例：

where a=? and b=?  若是a幾乎接近惟一，那麼只要建idx_a便可。

七、 【推薦】禁止更新表的全部字段，必須指定要更新的字段

禁止項

原則上,禁止採用這些技術。除非架構上有這些考慮。

  • 存儲過程
  • 外鍵
  • 視圖
  • 觸發器
  • 分庫、分表、分區。（單錶行數超過500萬行或者單表容量超過2GB，才推薦進行分庫分表）

工程|項目

項目

語法：平臺-分層職責-服務名稱

例子：

# uxuexi是平臺,web是分層,course是服務名稱(由於是web，因此對應的是子域名)，對應的域名是course.uxuexi.com
uxuexi-web-course
# uxuexi是平臺,business是分層，sso是服務名稱
uxuexi-business-sso
# uxuexi是平臺,base是分層，course是服務名稱
uxuexi-base-course
# we是平臺(由於是通用的，沒有對應的域名，因此使用we),business是分層，sso是服務名稱
we-business-sso
# we是平臺(由於是通用的，沒有對應的域名，因此使用we),core是分層，db是服務名稱
we-core-db

一、 平臺

使用的域名去掉組織後綴。

例子：

域名：www.uxuexi.com
-------
子域名：www
平臺名：uxuexi
組織：com

二、 分層職責

  • core(能力層。與具體業務無關，提供能力）
  • base(基礎服務層。能夠獨立存在，有且只有一個具備實際意義的服務，不依賴於其餘的服務）
  • business(業務服務層。依賴多個基礎服務，通常是一個流程性的服務)
  • webapp(應用層。對互聯網用戶提供直接服務)

三、 服務名稱

若是是web項目，使用子域名看成服務名稱。其餘的項目，根據職責劃分來自行命名。

分包

java源碼

一、 根目錄

語法：域名組織-項目名。若是web層項目，直接使用對應的域名倒置便可。

例子：

# web層項目，直接使用對應的域名倒置便可
項目名：uxuexi-web-course 
根目錄爲：com.uxuexi.course
# 其餘層項目，使用：域名組織+項目名
項目名：uxuexi-business-sso 
根目錄爲：com.uxuexi.business.sso

二、 java包

語法：分包【+子模塊】+文件（類+後綴）。其中子模塊是參考業務的包纔有，通用功能能夠沒有子模塊。

分包清單：

  • module：http路由，負責根據不一樣的業務跳轉到不一樣的url。
  • form：負責http參數的封裝、驗證、傳輸。負責sql的編寫
  • entity：數據庫持久對象。數據的持久及對象自己業務的實現
  • dto：接口返回的實體
  • service：邏輯單元。邏輯處理或者叫計算單元
  • util：工具
  • enums：枚舉
  • vt：視圖標籤
  • ...

有子模塊的業務包有：module,form,entity,dto,service。若是有通用的邏輯，可使用common子模塊包名

例子：

包名：module.student.course ，類名：StudentCourseModule
包名：module.user,類名：UserModule
包名：util,類名：StringUtil

資源文件

一、 根目錄

resources

二、 sql包

和service及form的包名一致，文件名和java調用的類名一致

例子：

# java 
# com.uxuexi.www 根目錄
# module 分包
# student.course 子模塊
# StudentCourseViewService.java 文件
com.uxuexi.wwww.module.student.course.StudentCourseViewService.java

# sql
# resources 根目錄
# sql 分包
# student.course 子模塊
# StudentCourseViewService.sql 文件
resources.sql.student.course.StudentCourseViewService.sql

視圖文件

一、 根目錄

WEB-INF

二、 視圖包

module類單詞小寫分隔，文件名和module裏的方法名一致

例子：

# java 
# com.uxuexi.www 根目錄
# module 分包
# student.course 子模塊
# StudentCourseModule 文件
# list 方法
com.uxuexi.wwww.module.student.course.StudentCourseModule.list()

# 視圖
# WEB-INF 根目錄
# student.course 子模塊
# list.jsp 文件
WEB-INF.student.course.list.jsp

完整例子：





相關文章
相關標籤/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公眾號
   歡迎關注本站公眾號,獲取更多信息
聯繫我們 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程