簡介
在本文中,將從大到小,從外到內(nèi),總結(jié)Java編程中的命名規(guī)范。文中將會(huì)涉及到日常工作中常見的命名示例,如包命名,類命名,接口命名,方法命名,變量命名,常類命名,抽象類命名,異常類命名以及擴(kuò)展類命名等。我將按照項(xiàng)目工程目錄結(jié)構(gòu),從包,類(接口,抽象類,異常類),方法,變量和常量的順序展開介紹。
1. 包命名規(guī)范
包(Package)的作用是將功能相似或相關(guān)的類或者接口進(jìn)行分組管理,便于類的定位和查找,同時(shí)也可以使用包來避免類名的沖突和訪問控制,使代碼更容易維護(hù)。通常,包命使用小寫英文字母進(jìn)行命名,并使用“.”進(jìn)行分割,每個(gè)被分割的單元只能包含一個(gè)名詞。一般地,包命名常采用頂級(jí)域名作為前綴,例如com,net,org,edu,gov,cn,io等,隨后緊跟公司/組織/個(gè)人名稱以及功能模塊名稱。下面是一些包命名示例:
package org.springframework.boot.autoconfigure.cloud
package org.springframework.boot.util
package org.hibernate.action
package org.hibernate.cfg
package com.alibaba.druid
package com.alibaba.druid.filter
package com.alibaba.nacos.client.config
package com.ramostear.blog.web
下面是Oracle Java的一些常見包命名例子:
package java.beans
package java.io
package java.lang
package java.net
package java.util
package javax.annotation
2. 類命名規(guī)范
類(Class)通常采用名詞進(jìn)行命名,且首字母大寫,如果一個(gè)類名包含兩個(gè)以上名詞,建議使用駝峰命名(Camel-Case)法書寫類名,每個(gè)名詞首字母也應(yīng)該大寫。一般地,類名的書寫盡量使其保持簡單和描述的完整性,因此在書寫類名時(shí)不建議使用縮寫(一些約定俗成的命名除外,例如Internationalization and Localization縮寫成i18n,Uniform Resource Identifier縮寫成URI,Data Access Object縮寫成DAO,JSON Web Token縮寫成JWT,HyperText Markup Language縮寫成HTML等等)。下列是一些常見的類命名示例:
public class UserDTO{
//TODO...
}
class EmployeeService{
//TODO...
}
class StudentDAO{
//TODO...
}
class OrderItemEntity{
//TODO...
}
public class UserServiceImpl{
//TODO...
}
public class OrderItemController{
//TODO...
}
下面是Oracle Java中的一些標(biāo)準(zhǔn)命名示例:
public class HTMLEditorKit{
//...
}
public abstract class HttpContext{
//...
}
public interface ImageObserver{
//...
}
public class ArrayIndexOutOfBoundsException{
//...
}
public class enum Thread.State{
//...
}
2.1 接口命名規(guī)范
首先,接口(Interface)是一種表述某一類型對(duì)象動(dòng)作的特殊類;簡單來說,接口也是類(不太嚴(yán)謹(jǐn)),所以,接口的名稱的書寫也應(yīng)該符合類名書寫規(guī)范,首字母應(yīng)該大寫,與普通類名不同的是,接口命名時(shí)通常采用形容詞或動(dòng)詞來描述接口的動(dòng)作行為。下列是Oracle Java中一些標(biāo)準(zhǔn)庫的接口使用形容詞命名示例:
public interface Closeable{
//...
}
public interface Cloneable{
//...
}
public interface Runnable{
//...
}
public interface Comparable{
//...
}
public interface CompletionService{
//...
}
public interface Iterable{
//...
}
public interface EventListener{
//...
}
在Spring Framework標(biāo)準(zhǔn)庫中,通常采用名詞+動(dòng)詞/形容詞的組合方式來命名接口,下列是Spring Framework中一些接口命名示例:
public interface AfterAdvice{
//...
}
public interface TargetClassAware{
//...
}
public interface ApplicationContextAware{
//...
}
public interface MessageSourceResolvable{
//...
}
2.2 抽象類命名規(guī)范
抽象類(Abstract Class)是一種特殊的類,其命名與普通類的命名規(guī)范相當(dāng)。一般地,為了將抽象類與普通類和接口做出區(qū)別,提高抽象類的可讀性,在命名抽象類時(shí),會(huì)以“Abstract”/“Base”作為類命的前綴。下面是編程中一些常規(guī)的命名示例:
public abstract class AbstractRepository{
//...
}
public abstract class AbstractController{
//...
}
public abstract class BaseDao{
//...
}
public abstract class AbstractCommonService{
//...
}
以下是Spring Framework中常見的抽象類示例:
public abstract class AbstractAspectJAdvice{
//...
}
public abstract class AbstractSingletonProxyFactoryBean{
//...
}
public abstract class AbstractBeanFactoryPointcutAdvisor{
//...
}
public abstract class AbstractCachingConfiguration{
//...
}
public abstract class AbstractContextLoaderInitializer{
//...
}
2.3 異常類命名規(guī)范
異常類(Exception Class)也是類的一種,但與普通類命名不同的是,異常類在命名時(shí)需要使用“Exception”作為其后綴。下面是常見的異常類命名示例:
public class FileNotFoundException{
//...
}
public class UserAlreadyExistException{
//...
}
public class TransactionException{
//...
}
public class ClassNotFoundException{
//...
}
public class IllegalArgumentException{
//...
}
public class IndexOutOfBoundsException{
//...
}
另外,在Java中還有另外一類異常類,它們屬于系統(tǒng)異常,這一類異常類的命名使用“Error”作為其后綴,以區(qū)分Exception(編碼,環(huán)境,操作等異常)。下面是系統(tǒng)異常(非檢查異常)的命名示例:
public abstract class VirtualMachineError{
//...
}
public class StackOverflowError{
//...
}
public class OutOfMemoryError{
//...
}
public class IllegalAccessError{
//...
}
public class NoClassDefFoundError{
//...
}
public class NoSuchFieldError{
//...
}
public class NoSuchMethodError{
//...
}
3.方法命名規(guī)范
方法(Method)命名時(shí),其首字母應(yīng)該小寫,如果方法簽名由多個(gè)單詞組成,則從第二個(gè)單詞起,使用駝峰命名法進(jìn)行書寫。一般地,在對(duì)方法進(jìn)行命名時(shí),通常采用動(dòng)詞/動(dòng)詞+名詞的組合,下面是方法命名的一些常見示例。
3.1 表述獲取
如果一個(gè)方法用于獲取某個(gè)值,通常使用“get”作為其前綴,例如:
public String getUserName(){
//...
}
public List getUserIds(){
//...
}
public User getOne(){
//...
}
3.2 表述查詢
如果方法需要通過查詢或篩選的方式獲取某個(gè)數(shù)據(jù),通常使用“find”/“query”作為其前綴,例如:
public List findOne(Integer id){
//...
}
public List findAll(){
//...
}
public List queryOrders(){
//...
}
3.3 表述條件
如果一個(gè)方法需要一些條件參數(shù),則可以使用“by”/“with”等字符作為方法名中條件的連接符,例如:
public User findByUsername(String username){
//...
}
public List getUserIdsWithState(boolean state){
//...
}
public List findAllByUsernameOrderByIdDesc(String username){
//...
}
3.4 表述設(shè)置
如果一個(gè)方法是要設(shè)置,插入,修改,刪除等操作,應(yīng)該將對(duì)應(yīng)的動(dòng)詞(set,insert,update,delete)作為其名詞的前綴,例如:
public void setName(String name){
//...
}
public User insert(User user){
//...
}
public void update(User user){
//...
}
public void clearAll(){
//...
}
3.5 其他規(guī)范
如果一個(gè)方法用于獲取某組數(shù)據(jù)的長度或數(shù)量,則該方法應(yīng)該使用length或size命名;如果方法的返回值為布爾類型(Boolean),則該方法應(yīng)該使用“is”或”has”作為前綴;如果方法用于將一種類型的數(shù)據(jù)轉(zhuǎn)換為另一種數(shù)據(jù)數(shù)類型,則可以使用“to”作為前綴。下面是綜合示例:
public long length(){
//...
}
public int size(){
//...
}
public boolean isOpen(){
//...
}
public boolean isNotEmpty(){
//...
}
public boolean hasLength(){
//...
}
public Set mapToSet(Map map){
//...
}
public UserDto convertTo(User user){
//...
}
public String toString(Object obj){
//...
}
4. 變量命名規(guī)范
變量(Variable)命名包括參數(shù)名稱,成員變量和局部變量。變量命名通常以小寫字母開頭,如果變量名由多個(gè)單詞構(gòu)成,則從第二個(gè)單詞起首字母需要大寫,在變量命名過程中,不建議使用“_”作為前綴或者單詞之間的分割符號(hào)。下面是一些常見的變量命名示例:
private String nickName;
private String mobileNumber;
private Long id;
private String username;
private Long orderId;
private Long orderItemId;
5. 常量命名規(guī)范
一般地,常量名稱采用全部大寫的英文單詞書寫,如果常量名稱由多個(gè)單詞組成,則單詞之間統(tǒng)一使用“_”進(jìn)行分割,下面是常量命名示例:
public static final String LOGIN_USER_SESSION_KEY = "current_login_user";
public static final int MAX_AGE_VALUE = 120;
public static final int DEFAULT_PAGE_NO = 1;
public static final long MAX_PAGE_SIZE = 1000;
public static final boolean HAS_LICENSE = false;
public static final boolean IS_CHECKED = false;
6. 枚舉命名規(guī)范
枚舉(Enum)類是一種特殊的類,其命名規(guī)范遵循普通類的命名約束條件,首字母大寫,采用駝峰命名法;枚舉類中定義的值的名稱遵循常量的命名規(guī)范,且枚舉值的名稱需要與類名有一定的關(guān)聯(lián)性,下面是枚舉的一些示例:
public enum Color{
RED,YELLOW,BLUE,GREEN,WHITE;
}
public enum PhysicalSize{
TINY,SMALL,MEDIUM,LARGE,HUGE,GIGANTIC;
}
下面是Oracle Java標(biāo)準(zhǔn)庫中的一個(gè)示例:
public enum ElementType{
TYPE,
FIELD,
METHOD,
PARAMETER,
CONSTRUCTOR,
LOCAL_VARIABLE,
ANNOTATION_TYPE,
PACKAGE,
TYPE_PARAMETER,
TYPE_USE;
}
7. 其他命名規(guī)范
7.1 數(shù)組
在定義數(shù)組時(shí),為了便于閱讀,盡量保持以下的書寫規(guī)范:
int[] array = new int[10];
int[] idArray ={1,2,3,4,5};
String[] nameArray = {"First","Yellow","Big"}
public List getNameById(Integer[] ids){
//...
}
//或者
public List getNameById(Integer...ids){
//...
}
7.2 表述復(fù)數(shù)或者集合
如果一個(gè)變量用于描述多個(gè)數(shù)據(jù)時(shí),盡量使用單詞的復(fù)數(shù)形式進(jìn)行書寫,例如:
Collection orders;
int[] values;
List items;
另外,如果表述的是一個(gè)Map數(shù)據(jù),則應(yīng)使用“map”作為其后綴,例如:
Map userMap;
Map listMap;
7.3 泛型類
在書寫泛型類時(shí),通常做以下的約定:
- E表示Element,通常用在集合中;
- ID用于表示對(duì)象的唯一標(biāo)識(shí)符類型
- T表示Type(類型),通常指代類;
- K表示Key(鍵),通常用于Map中;
- V表示Value(值),通常用于Map中,與K結(jié)對(duì)出現(xiàn);
- N表示Number,通常用于表示數(shù)值類型;
- ?表示不確定的Java類型;
- X用于表示異常;
- U,S表示任意的類型。
下面時(shí)泛型類的書寫示例:
public class HashSet extends AbstractSet{
//...
}
public class HashMap extends AbstractMap{
//...
}
public class ThreadLocal{
//...
}
public interface Functor{
T val() throws X;
}
public class Container{
private K key;
private V value;
Container(K key,V value){
this.key = key;
this.value = value;
}
//getter and setter ...
}
public interface BaseRepository{
T findById(ID id);
void update(T t);
List findByIds(ID...ids);
}
public static List methodName(Class clz){
List dataList = getByClz(clz);
return dataList;
}
7.4 接口實(shí)現(xiàn)類
為了便于閱讀,在通常情況下,建議接口實(shí)現(xiàn)類使用“Impl作為后綴”,不建議使用大寫的“I”作為接口前綴,下面是接口和接口實(shí)現(xiàn)類的書寫示例。
推薦寫法:
public interface OrderService{
//...
}
public class OrderServiceImpl implements OrderService{
//...
}
不建議的寫法:
public interface IOrderService{
//...
}
public class OrderService implements IOrderService{
//...
}
7.5 測(cè)試類和測(cè)試方法
在項(xiàng)目中,測(cè)試類采用被測(cè)試業(yè)務(wù)模塊名/被測(cè)試接口/被測(cè)試類+“Test”的方法進(jìn)行書寫,測(cè)試類中的測(cè)試函數(shù)采用“test”+用例操作_狀態(tài)的組合方式進(jìn)行書寫,例如:
public class UserServiceTest{
public void testFindByUsernameAndPassword(){
//...
}
public void testUsernameExist_notExist(){
//...
}
public void testDeleteById_isOk(){
//...
}
}
8 擴(kuò)展:速記Java開發(fā)中的各種O
最后,通過一張表和圖快速對(duì)Java中的BO
,DTO
,DAO
,PO
,POJO
,VO
之間的含義,區(qū)別以及聯(lián)系進(jìn)行梳理。
名稱 | 使用范圍 | 解釋說明 |
---|---|---|
BO | 用于Service,Manager,Business等業(yè)務(wù)相關(guān)類的命名 | Business Object業(yè)務(wù)處理對(duì)象,主要作用是把業(yè)務(wù)邏輯封裝成一個(gè)對(duì)象。 |
DTO | 經(jīng)過加工后的PO對(duì)象,其內(nèi)部屬性可能增加或減少 | Data Transfer Object數(shù)據(jù)傳輸對(duì)象,主要用于遠(yuǎn)程調(diào)用等需要大量傳輸數(shù)據(jù)的地方,例如,可以將一個(gè)或多個(gè)PO類的部分或全部屬性封裝為DTO進(jìn)行傳輸 |
DAO | 用于對(duì)數(shù)據(jù)庫進(jìn)行讀寫操作的類進(jìn)行命名 | Data Access Object數(shù)據(jù)訪問對(duì)象,主要用來封裝對(duì)數(shù)據(jù)庫的訪問,通過DAO可以將POJO持久化為PO,也可以利用PO封裝出VO和DTO |
PO | Bean,Entity等類的命名 | Persistant Object持久化對(duì)象,數(shù)據(jù)庫表中的數(shù)據(jù)在Java對(duì)象中的映射狀態(tài),可以簡單的理解為一個(gè)PO對(duì)象即為數(shù)據(jù)庫表中的一條記錄 |
POJO | POJO是DO/DTO/BO/VO的統(tǒng)稱 | Plain Ordinary Java Object 簡單Java對(duì)象,它是一個(gè)簡單的普通Java對(duì)象,禁止將類命名為XxxxPOJO |
VO | 通常是視圖控制層和模板引擎之間傳遞的數(shù)據(jù)對(duì)象 | Value Object 值對(duì)象,主要用于視圖層,視圖控制器將視圖層所需的屬性封裝成一個(gè)對(duì)象,然后用一個(gè)VO對(duì)象在視圖控制器和視圖之間進(jìn)行數(shù)據(jù)傳輸。 |
AO | 應(yīng)用層對(duì)象 | Application Object,在Web層與Service層之間抽象的復(fù)用對(duì)象模型,很少用。 |
下面將通過一張圖來理解上述幾種O之間相互轉(zhuǎn)換的關(guān)系: