2020回顧過往：Java命名規範及易混淆知識歸納

由 ramostear 發佈 2020-01-01T00:17:35+00:00

通常，包命使用小寫英文字母進行命名，並使用「.」進行分割，每個被分割的單元只能包含一個名詞。一般地，包命名常採用頂級域名作為前綴，例如com，net，org，edu，gov，cn，io等，隨後緊跟公司/組織/個人名稱以及功能模塊名稱。下面是一些包命名示例：packageorg.s

前言：2020年新年伊始，花點時間總結一下Java編程中的命名規範。作為新年第一篇總結性的文章，承上啟下，總結過去七年的學習歷程，展望新的未來。

簡介

​ 在本文中，將從大到小，從外到內，總結Java編程中的命名規範。文中將會涉及到日常工作中常見的命名示例，如包命名，類命名，接口命名，方法命名，變量命名，常類命名，抽象類命名，異常類命名以及擴展類命名等。我將按照項目工程目錄結構，從包，類(接口，抽象類，異常類)，方法，變量和常量的順序展開介紹。



1. 包命名規範

​

包(Package)的作用是將功能相似或相關的類或者接口進行分組管理，便於類的定位和查找，同時也可以使用包來避免類名的衝突和訪問控制，使代碼更容易維護。通常，包命使用小寫英文字母進行命名，並使用「.」進行分割，每個被分割的單元只能包含一個名詞。一般地，包命名常採用頂級域名作為前綴，例如com，net，org，edu，gov，cn，io等，隨後緊跟公司/組織/個人名稱以及功能模塊名稱。下面是一些包命名示例：

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. 類命名規範

​ 類(Class)通常採用名詞進行命名，且首字母大寫，如果一個類名包含兩個以上名詞，建議使用駝峰命名(Camel-Case)法書寫類名,每個名詞首字母也應該大寫。一般地，類名的書寫儘量使其保持簡單和描述的完整性，因此在書寫類名時不建議使用縮寫(一些約定俗成的命名除外，例如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中的一些標準命名示例：

public class HTMLEditorKit{
    //...
}
public abstract class HttpContext{
    //...
}
public interface ImageObserver{
    //...
}
public class ArrayIndexOutOfBoundsException{
    //...
}
public class enum Thread.State{
    //...
}

2.1 接口命名規範

​ 首先，接口(Interface)是一種表述某一類型對象動作的特殊類；簡單來說，接口也是類(不太嚴謹)，所以，接口的名稱的書寫也應該符合類名書寫規範，首字母應該大寫，與普通類名不同的是，接口命名時通常採用形容詞或動詞來描述接口的動作行為。下列是Oracle Java中一些標準庫的接口使用形容詞命名示例：

public interface Closeable{
    //...
}
public interface Cloneable{
    //...
}
public interface RunnableP{
    //...
}
public interface Comparable<T>{
    //...
}
public interface CompletionService<V>{
    //...
}
public interface Iterable<T>{
    //...
}
public interface EventListener{
    //...
}

在Spring Framework標準庫中，通常採用名詞+動詞/形容詞的組合方式來命名接口，下列是Spring Framework中一些接口命名示例：

public interface AfterAdvice{
    //...
}
public interface TargetClassAware{
    //...
}
public interface ApplicationContextAware{
    //...
}
public interface MessageSourceResolvable{
    //...
}

2.2 抽象類命名規範

​ 抽象類(Abstract Class)是一種特殊的類，其命名與普通類的命名規範相當。一般地，為了將抽象類與普通類和接口做出區別，提高抽象類的可讀性，在命名抽象類時，會以「Abstract」/「Base」作為類命的前綴。下面是編程中一些常規的命名示例：

public abstract class AbstractRepository<T>{
    //...
}
public abstract class AbstractController{
    //...
}
public abstract class BaseDao<T,ID>{
    //...
}
public abstract class AbstractCommonService<T>{
    //...
}

以下是Spring Framework中常見的抽象類示例：

public abstract class AbstractAspectJAdvice{
    //...
}
public abstract class AbstractSingletonProxyFactoryBean{
    //...
}
public abstract class AbstractBeanFactoryPointcutAdvisor{
    //...
}
public abstract class AbstractCachingConfiguration{
    //...
}
public abstract class AbstractContextLoaderInitializer{
    //...
}

2.3 異常類命名規範

​ 異常類(Exception Class)也是類的一種，但與普通類命名不同的是，異常類在命名時需要使用「Exception」作為其後綴。下面是常見的異常類命名示例：

public class FileNotFoundException{
    //...
}
public class UserAlreadyExistException{
    //...
}
public class TransactionException{
    //...
}
public class ClassNotFoundException{
    //...
}
public class IllegalArgumentException{
    //...
}
public class IndexOutOfBoundsException{
    //...
}

另外，在Java中還有另外一類異常類，它們屬於系統異常，這一類異常類的命名使用「Error」作為其後綴，以區分Exception(編碼，環境，操作等異常)。下面是系統異常(非檢查異常)的命名示例：

public abstract class VirtualMachineError{
    //...
}
public class StackOverflowError{
    //...
}
public class OutOfMemoryError{
    //...
}
public class IllegalAccessError{
    //...
}
public class NoClassDefFoundError{
    //...
}
public class NoSuchFieldError{
    //...
}
public class NoSuchMethodError{
    //...
}

3.方法命名規範

​ 方法(Method)命名時,其首字母應該小寫，如果方法簽名由多個單詞組成，則從第二個單詞起，使用駝峰命名法進行書寫。一般地，在對方法進行命名時，通常採用動詞/動詞+名詞的組合，下面是方法命名的一些常見示例。

3.1 表述獲取

​ 如果一個方法用於獲取某個值，通常使用「get」作為其前綴，例如：

public String getUserName(){
    //...
}
public List<Integer> getUserIds(){
    //...
}
public User getOne(){
    //...
}

3.2 表述查詢

​ 如果方法需要通過查詢或篩選的方式獲取某個數據，通常使用「find」/「query」作為其前綴，例如：

public List<User> findOne(Integer id){
    //...
}
public List<Integer> findAll(){
    //...
} 
public List<String> queryOrders(){
    //...
}

3.3 表述條件

​ 如果一個方法需要一些條件參數，則可以使用「by」/「with」等字符作為方法名中條件的連接符，例如：

public User findByUsername(String username){
    //...
}
public List<Integer> getUserIdsWithState(boolean state){
    //...
}
public List<User> findAllByUsernameOrderByIdDesc(String username){
    //...
}

3.4 表述設置

​ 如果一個方法是要設置，插入，修改，刪除等操作，應該將對應的動詞(set,insert,update,delete)作為其名詞的前綴，例如：

public void setName(String name){
    //...
}
public User insert(User user){
    //...
}
public void update(User user){
    //...
}
public void clearAll(){
    //...
}

3.5 其他規範

​ 如果一個方法用於獲取某組數據的長度或數量，則該方法應該使用length或size命名；如果方法的返回值為布爾類型(Boolean)，則該方法應該使用「is」或」has」作為前綴；如果方法用於將一種類型的數據轉換為另一種數據數類型，則可以使用「to」作為前綴。下面是綜合示例：

public long length(){
    //...
}
public int size(){
    //...
}
public boolean isOpen(){
    //...
}
public boolean isNotEmpty(){
    //...
}
public boolean hasLength(){
    //...
}
public Set<Integer> mapToSet(Map map){
    //...
}
public UserDto convertTo(User user){
    //...
}
public String toString(Object obj){
    //...
}

4. 變量命名規範

​ 變量(Variable)命名包括參數名稱，成員變量和局部變量。變量命名通常以小寫字母開頭，如果變量名由多個單詞構成，則從第二個單詞起首字母需要大寫，在變量命名過程中，不建議使用「_」作為前綴或者單詞之間的分割符號。下面是一些常見的變量命名示例：

private String nickName;
private String mobileNumber;
private Long id;
private String username;
private Long orderId;
private Long orderItemId;

5. 常量命名規範

​ 一般地，常量名稱採用全部大寫的英文單詞書寫，如果常量名稱由多個單詞組成，則單詞之間統一使用「_」進行分割，下面是常量命名示例：

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. 枚舉命名規範

枚舉(Enum)類是一種特殊的類，其命名規範遵循普通類的命名約束條件，首字母大寫，採用駝峰命名法；枚舉類中定義的值的名稱遵循常量的命名規範，且枚舉值的名稱需要與類名有一定的關聯性，下面是枚舉的一些示例：

public enum Color{
    RED,YELLOW,BLUE,GREEN,WHITE;
}
public enum PhysicalSize{
    TINY,SMALL,MEDIUM,LARGE,HUGE,GIGANTIC;
}

下面是Oracle Java標準庫中的一個示例：

public enum ElementType{
    TYPE,
    FIELD,
    METHOD,
    PARAMETER,
    CONSTRUCTOR,
    LOCAL_VARIABLE,
    ANNOTATION_TYPE,
    PACKAGE,
    TYPE_PARAMETER,
    TYPE_USE;
}

7. 其他命名規範



7.1 數組

​ 在定義數組時，為了便於閱讀，儘量保持以下的書寫規範：

int[] array = new int[10];
int[] idArray ={1,2,3,4,5};
String[] nameArray = {"First","Yellow","Big"}

public List<String> getNameById(Integer[] ids){
    //...
}
//或者
public List<String> getNameById(Integer...ids){
    //...
}

7.2 表述複數或者集合

​ 如果一個變量用於描述多個數據時，儘量使用單詞的複數形式進行書寫，例如：

Collection<Order> orders;
int[] values;
List<Item> items;

另外，如果表述的是一個Map數據，則應使用「map」作為其後綴，例如：

Map<String,User> userMap;
Map<String,List<Object>> listMap;

7.3 泛型類

在書寫泛型類時，通常做以下的約定：

  • E表示Element，通常用在集合中；
  • ID用於表示對象的唯一標識符類型
  • T表示Type(類型)，通常指代類；
  • K表示Key(鍵),通常用於Map中；
  • V表示Value(值),通常用於Map中，與K結對出現；
  • N表示Number,通常用於表示數值類型；
  • ？表示不確定的Java類型；
  • X用於表示異常；
  • U,S表示任意的類型。

下面時泛型類的書寫示例：

public class HashSet<E> extends AbstractSet<E>{
    //...
}
public class HashMap<K,V> extends AbstractMap<K,V>{
    //...
}
public class ThreadLocal<T>{
    //...
}
public interface Functor<T,X extends Throwable>{
    T val() throws X;
}
public class Container<K,V>{
    private K key;
    private V value;
    Container(K key,V value){
        this.key = key;
        this.value = value;
    }
    //getter and setter ...
}

public interface BaseRepository<T,ID>{
    T findById(ID id);

    void update(T t);

    List<T> findByIds(ID...ids);
}

public static <T> List<T> methodName(Class<T> clz){
    List<T> dataList = getByClz(clz);
    return dataList;
}

7.4 接口實現類

​ 為了便於閱讀，在通常情況下，建議接口實現類使用「Impl作為後綴」，不建議使用大寫的「I」作為接口前綴，下面是接口和接口實現類的書寫示例。

推薦寫法：

public interface OrderService{
    //...
}
public class OrderServiceImpl implements OrderService{
    //...
}

不建議的寫法：

public interface IOrderService{
    //...
}
public class OrderService implements IOrderService{
    //...
}

7.5 測試類和測試方法

​ 在項目中，測試類採用被測試業務模塊名/被測試接口/被測試類+「Test」的方法進行書寫，測試類中的測試函數採用「test」+用例操作_狀態的組合方式進行書寫，例如：

public class UserServiceTest{

    public void testFindByUsernameAndPassword(){
        //...
    }

    public void testUsernameExist_notExist(){
        //...
    }

    public void testDeleteById_isOk(){
        //...
    }
}

8 擴展：速記Java開發中的各種O

​ 最後，通過一張表和圖快速對Java中的BO,DTO,DAO,PO,POJO,VO之間的含義，區別以及聯繫進行梳理。



下面將通過一張圖來理解上述幾種O之間相互轉換的關係：

關鍵字：
#tech #科技 #ramostear

【amz嚴選】精準上妝_LED廣角化妝鏡

售價 NT$ 690

Nature Tree_玫瑰抗皺_精華液

售價 NT$ 990

Nature Tree_夏日控油_精華液

售價 NT$ 990

三倍滲透_熱感SPA_33°C精華液

售價 NT$ 990

【PP波瑟楓妮】醫療級石墨烯撞色腰夾

售價 NT$ 1,980

MAGICOM美肌之鏡_零著感卸妝霜

售價 NT$ 680-2,760

【amz嚴選】麋鹿熱壓吐司烤盤

售價 NT$ 360

【amz獨家組合】Relove_私密美白_傳明酸潔淨凝露

售價 NT$ 1,200-2,650