隨着《阿里巴巴Java開發手冊》的公開，重新又掀起一股編碼規范的風口。結合《華為java編程規范》以及團隊內部的實踐，我們也做了一段開發規范。不求最全，但求有效。
里面的規范，暫時只分兩類。“強制”，即如果違反就不能使用級別。比如說，在codereview有遇到 ，那就會直接把pull request打回去，拒絕合並到開發者穩定分支上。“推薦”，即建議怎么做，但是不強制，根據不同的水平可以做一些參考。
通用規范
所有的情況下都通用
1、 【強制】命名全部使用英文，禁止中文或者中英混合。項目名除外，因為有的項目是按域名來命名的，域名本身有可能是中文拼音。
例子：
域名：kecheng.xxx.com
項目名：xxx-web-kecheng
2、 【強制】禁止使用縮寫，除非提供一個縮寫列表
反例：
# 這里的t到底是什么意思？topic_id?還是teacher_id?
字段：t_id
3、 【強制】禁止出現除了后綴或者前綴3個單詞。如果超過3個，說明想表達的職責太多，可以拆分或者封裝。
編程語言
這里主要指的是Java語言，其他的語言也可以借鑒這些准則
類
1、 【強制】需要有統一的后綴或者前綴。為了一看類名，就知道這個類干什么的。
前綴列表：
- 抽象類（Abstract）
- 接口（I）
正例：
接口：IViewTag
抽象類：AbstractViewTag
具體實現類：UserViewTag
后綴列表：
- 實體(Entity)。數據庫持久對象。
- 表單（Form)。用於封裝、校驗http參數。
- 數據傳輸對象(DTO)。用於暴露接口的返回數據
- 基礎服務(BaseService)。單實體可以自描述的服務。
- 業務服務(BusinessService)。集合多個單實體的服務。
- 頁面服務(ViewService)。涉及到視圖頁面的服務。
- 模塊(Module)。http入口模塊。
- 異常(Exception)
- 工具(Util)
- 枚舉(Enum)
- 視圖標簽（ViewTag）
- ....(其他的，比如：Filter之類）
正例：
實體：UserEntity
基礎服務：UserBaseService
業務服務：AuthorityBusinessService
2、 【強制】所有參與業務的類禁止使用內部類。
屬性
1、 【強制】常量必須是：大寫+下划線，禁止多個單詞連在一起
正例：
private final static String PAGE_SIZE=10;
反例：
private final static String PAGESIZE=10;
private final static String pageSize=10;
2、 【強制】布爾類型禁止添加"is"前綴。部分框架解析會引起序列化錯誤。
反例：
# 對應的getter和setter為：isRead和setRead
private boolean isRead
正例:
# 對應的getter和setter為：isRead和setRead
private boolean read;
3、 【強制】計數器禁止使用復數
反例：
private int readCounts;
正例:
private int readCount;
4、 【強制】自描述屬性里不要出現類名的描述
反例：
#UserEntity類
private String userName;
private int userAge;
正例：
#UserEntity類
private String name;
private int age;
5、【強制】關聯其他實體的屬性命名規則：對應的實體去掉后綴+用途
正例：
屬性名：teacherId ,對應的實體是TeacherEntity
屬性名：favorCount，對應的實體是FavorEntity
反例：
屬性名：tId。根本不知道是哪個實體的外鍵。有可能是Teacher有可能是Topic，還得猜半天
6、 【強制】禁止通過定義定義成常量（1，2）來維護類型值，需要通過枚舉
反例：
private final static int SUCESS=1;
private final static int FAIL=2;
正例：
定義一個枚舉
方法
1、 【強制】接口里的方法禁止有修飾符。
反例：
#接口里的方法
public void eat();
正例：
#接口里的方法
void eat();
2、 【推薦】方法參數必須使用final來修飾。final可提高程序響應效率。可以通過Eclipse的cleanup來實現。
正例：
public void eat(final int size);
反例：
public void eat(int size);
3、 【強制】每一個方法參數都需要被處理。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);
}
4、 【強制】同一個類里有多個一致的參數（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);
5、 【強制】方法名必須是動詞或者動賓。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();
6、 【強制】一個方法里代碼行數不能超過1屏（即30行）。一般來說超過30的行，業務關注點、復雜數比較高，很難維護。超過３０行需要封裝方法
7、 【強制】局部變量命名不能有連續的名稱。連續的命名不具有可維護性。每個變量都需要有清晰的概念。
反例：
String head1;
String head2;
正例：
String title;
String content;
8、 【強制】禁止有任何魔鬼數據獨立存在。可以定義一個有含義的變量來承載
反例：
if(type ==1){
//審核成功
下面15行代碼
}
正例：
private final static int SUCESS=1;
....
if(type ==SUCESS){
下面15行代碼
}
9、 【強制】判斷表達式要使用布爾變量或者封裝方法。表達式是變化點。在維護的時候，表達式不知名達意。
反例：
if(user!=null&&!Util.isEmpty(user.name)&&!Util.isEmpty(user.provicne)){
//下面15行代碼
}
正例：
if(isFilledBaseInfo(user)){
//下面15行代碼
}
10、【強制】if()...else if()...else個數不能多於4個，嵌套不能深於3層
可以通過以下的方法來消除：
- 設計模式
- 抽取方法
- 使用return
反例：
if(isAdmin()){
...
}else if(isTeacher()){
...
}
正例：
if(isAdmin()){
...
return;
}
if(isTeacher()){
...
return;
}
11、 【推薦】采用防御式編程，先判斷錯誤的業務，然后再寫正確的業務。防御式編程結構清晰分明：先把所有錯誤窮舉，然后集中處理正確邏輯。
反例：
if(null!=user && user.hasAuth()){
正確邏輯
}
正例：
if(null==user || ！user.hasAuth()){
return;
}
正確邏輯
12、 【推薦】for里不建議寫io。io包括：數據庫、緩存，文件讀寫等
13、 【強制】多個不同的結構（業務相近的代碼），需要有且只有一個空行
反例：
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;
14、 【推薦】不參與計算的變量不要定義變量
反例：
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;
15、 【強制】如果有捕獲異常，必須有對應的處理業務。如果沒有對應的處理業務，不要捕獲，可以直接throw，讓架構統一處理
你自己catch，肯定不希望用戶看到錯誤日志，那么 從用戶那邊看到是正常業務。catch了什么都沒干，用戶往往看到的是什么都沒發生，他會以為網站掛了或者功能快。
16、 【強制】禁止使用exception.getMessge()處理錯誤信息。應該使用exception.toString()。因為exception.getMessage()，在npe拋出異常的時候，什么信息都不顯示。
反例：
} catch (Exception e) {
logger.error(e.getMessage());
}
正例：
} catch (Exception e) {
logger.error(e.toString());
}
17、 【強制】禁止使用System.out.print。統一使用Eclipse的log4e插件生成日志（不要定義具體的日志實現，要定義的是slf4j的接口）
18、 【推薦】公開的接口，一旦發布成穩定版，禁止修改方法簽名（方法名，參數）
如果要修改,需要提供新的接口，老的不能修改。老的接口上添加@Deprecated注解，並且使用@see清晰的說明采用新接口或新服務是什么
因為一修改方法簽名。比如：js調用可能就報錯了，功能就沒辦法使用；工具類接口一變，其他項目就會報錯了，沒辦法向下兼容。
19、 【推薦】方法放置順序：public-->protected-->private。一個類，往往使用者更關注的是public的。構造方法、重載方法、雷同方法，按順序放在一起
注釋
1、 【強制】格式結構統一使用eclipse模板，禁止自定義。
2、 【強制】類、方法、屬性都必須有注釋。如果實在來不及，可以先生成TODO。因為可以通過TODO視圖，把注解補回來。
3、 【強制】類上必須要有作者，如果有修改，還要添加上修改者，如果有結隊也要寫上。要有用戶名還要有郵箱
例子：
/**
* 字典
*
* @author ZhuangJunxiang(529572571@qq.com)
* @version 2017-03-06
*/
4、 【強制】注釋要直譯，描述要寫算法或者思路或者注意事項。不要在注釋上代碼里的每一行完全暴露出來，使用者根本不關注實現。
反例：
/**
* 學生分頁查詢 #方法里根據沒有學生。。。。
*
* @param page 分頁對象
* @param studentForm 學生
* @return 分頁對象
*/
public Page<Map<String, Object>> findPageList(Page<Map<String, Object>> page, StudentForm studentForm) {
5、 【強制】方法里禁止寫注釋。不要有多余的注釋，讓變量和屬性自描述或者抽取方法。如果有算法寫到方法注釋上。
反例：
//填充基本信息
fillBaseInfo();
//填充賬號信息
fillAccoutInfo();
6、 【強制】方法里禁止注釋掉代碼。統一通過版本控制軟件（git)來解決。邏輯是正確的，但是現在暫時不能使用，可以暫時注釋，但是必須寫上TODO。
TODO格式： TODO 標記人 原因
例子：
//TODO 張三 當前用戶還未處理，因為登錄還沒有調通
//long userId = fetchUser.getCurrentUserId();
long userId = 1L;
....
數據庫
這里主要指的是MySQL，其他的數據庫也可以借鑒這些准則
表
1、【強制】統一使用表名命名規范
表名規范：分層+項目名縮寫+下划線+實體名（小寫字母）【+下划線+實體名（小寫字母）+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的關系表
2、 【強制】統一使用innoDB引擎。
3、 【推薦】表名不要關聯其他表名信息
反例：
bc_course
bc_course_video
bc_course_video_study_log
正例：
bc_course
bc_video
bc_study_log
索引
1、 【強制】業務上具有唯一特性的字段，即使是組合字段，必須使用唯一索引。比如： 用戶名，編號等。如果沒有添加唯一索引，即使在應用層做了非常完善的校驗和控制，只要沒有唯一索引，必然有臟數據
2、 【強制】唯一索引命名：uk_字段名,普通索引命名：idx_字段名
3、 【強制】禁止對text定義索引。如果有對這類字段搜索的需求，可以通過全文索引方法來實現功能。
4、 【推薦】varchar定義索引長度。一般有搜索的話，用戶也不會輸入太多字。長度統一10為倍數，不要超過50
字段
1、 【強制】主鍵禁止使用自增。不同庫同步數據的時候，會出問題。影響插入性能。
2、 【強制】字段全部禁止為空。為空的話，很容易在使用的時候出現npe。如果可以不填，通過默認值方法來處理。
3、 【強制】禁止使用外鍵，只能在概念和應用層次使用外鍵
外鍵的字段命名：表名去除前綴+id
4、 【強制】禁止使用枚舉、集合類型
5、 【強制】禁止在數據庫使用blog存在文件。數據庫只存相對的url路徑
6、 【強制】類型使用規范
- 布爾：bit
- 時間（精確到天）：date
- 時間（精確到秒）：datetime
- 浮點:deciaml
- 字符串（長度小於10或者長度大於10但是長度相同）：char
- 字符串（長度為10~5000,長度不相同）：varchar
- 字符串（富文本）：text
7、 【強制】必有字段
- 主鍵
- 創建時間
- 修改時間
- 假刪狀態（如果是資源數據必須有，如果是關系數據禁止有）
8、 【推薦】可以適合添加冗余數據，這樣可以增快查詢數據。
冗余類型：
- 計數器、計分器等統計數據
- 一旦生成不會修改的數據
9、 【推薦】字段順序：自描述-->關聯其他表的描述-->功能性-->必有字段
注釋
1、 【強制】表名或者字段注釋的格式：直譯【（補充說明）】
反例：
表名：t_first_login，注釋：本表用於處理河北聯通卡的臨時業務問題，記錄已經使用web登錄過的卡號
正例：
表名：t_first_login，注釋：首次登錄（用於處理河北聯通卡的臨時業務問題，記錄已經使用web登錄過的卡號）
2、 【強制】禁止帶“表”，“數據”等多余的字眼
反例：
表名：aw_input_batch，注釋：輸入批次表
表名：t_admission_110000，注釋：北京院校專業數據
3、 【推薦】如果類型字段，有變更，同步注釋
例子：
status 狀態（0：成功，1：失敗）
//過了一段時間，又多了一個凍結的狀態
status 狀態（0：成功，1：失敗，2：凍結）
sql
1、 【強制】禁止select *。數據庫查看執行時間性能沒有響應。但是返回的數據量會變大，對網絡開銷有影響，最終還是會影響性能，而且也會影響數據庫的二進步日志
2、 【強制】使用select count(*)。select count(name) 不記錄null的行數。而且官方已經澄清過，不影響性能 。
反例：
select count(1)
select count(id)
3、 【強制】使用sum函數時，必須使用IFNULL(sum(),0)。如果sum函數沒有查到結果返回null，容易出現npe。
4、 【推薦】禁止出現or。可以通過使用in或者unit all來替換
5、 【推薦】order by的場景，創建索引時order by 后面的字段也必須是組合索引的一部分，並且放在索引順序的最后，避免出現file_sort
正例：
where a=？ and b=? order by c; 索引：a_b_c
6、 【推薦】創建組合索引時，區分度最高的放在最左邊
正例：
where a=? and b=? 如果a幾乎接近唯一，那么只要建idx_a即可。
7、 【推薦】禁止更新表的所有字段，必須指定要更新的字段
禁止項
原則上,禁止采用這些技術。除非架構上有這些考慮。
- 存儲過程
- 外鍵
- 視圖
- 觸發器
- 分庫、分表、分區。（單表行數超過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
1、 平台
使用的域名去掉組織后綴。
例子：
域名：www.uxuexi.com
-------
子域名：www
平台名：uxuexi
組織：com
2、 分層職責
- core(能力層。與具體業務無關，提供能力）
- base(基礎服務層。可以獨立存在，有且只有一個具有實際意義的服務，不依賴於其他的服務）
- business(業務服務層。依賴多個基礎服務，一般是一個流程性的服務)
- webapp(應用層。對互聯網用戶提供直接服務)
3、 服務名稱
如果是web項目，使用子域名當作服務名稱。其他的項目，根據職責划分來自行命名。
分包
java源碼
1、 根目錄
語法：域名組織-項目名。如果web層項目，直接使用對應的域名倒置即可。
例子：
# web層項目，直接使用對應的域名倒置即可
項目名：uxuexi-web-course
根目錄為：com.uxuexi.course
# 其他層項目，使用：域名組織+項目名
項目名：uxuexi-business-sso
根目錄為：com.uxuexi.business.sso
2、 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
資源文件
1、 根目錄
resources
2、 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
視圖文件
1、 根目錄
WEB-INF
2、 視圖包
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
完整例子：
