阿里巴巴Java开发编程规约（整理详细版）

前言

1.编程规约

1.1 命名风格

1.2 常量定义

1.3 代码格式

1.4 OOP 规约

1.5 日期时间

1.6 集合处理

1.7 并发处理

1.8 控制语句

1.9 注释规约

1.10 前后端规约

1.11 其他

前言

规约依次分为【重要】、【建议】、【参考】，整理开发规范的目的在于写出更加高效、质量更高的代码。

1.编程规约

1.1 命名风格

1. 【重要】所有编程相关的命名既不能以下划线或美元符号开始，也不能以下划线或美元符号结束。

反例：_name / $name / name_ / name$

2.【重要】所有编程相关的命名不能使用拼音与英文混合命名，更不能使用中文直接命名。

说明：遵循英文拼写和语法更易于码农理解代码，也可以使用英文缩写

正例：使用 alibaba / aliyun / PIN ( Personal Identity number 个人识别码)

反例：ShouFeiRecord【记录】/ getGeRenInfo 【获取个人信息】

3.【重要】代码和注释避免使用侮辱性词语。

正例：blockList / allowList / secondary

反例：blackList / whiteList / BT / SB

4.【重要】类名使用大驼峰式命名法（upper camel case），每一个单词的首字母都采用大写字母。DO / PO / DTO / BO / VO / UID 等除外。

正例：UserDO / FirstName / LastName / HtmlDTO

反例：userDO / firstName / lastName / htmlDTO

5. 【重要】方法名、参数名、成员变量、局部变量都使用小驼峰式命名法（lower camel case），第一个单词以小写字母开始，第二个单词的首字母大写。

正例：userDO / firstName / lastName / htmlDTO

6.【重要】常量命名应该全部大写，单词之间使用下划线分隔，力求语义表达完整清楚，名字可以长一些。

正例：MAX_STOCK_COUNT / CACHE_EXPIRED_TIME

反例：MAX_COUNT / EXPIRED_TIME

7.【重要】抽象类命名使用Abstract 或 Base 开头；异常类命名使用 Exception 结尾，测试类命名以它要测试的类的名称开始，以 Test 结尾。

8.【重要】类型与中括号紧挨相连定义数组。

正例：定义整形数组 int[] arrayDemo。

反例：在 main 参数中，使用 String args[] 来定义。

9.【重要】POJO 类中的任何布尔类型的变量，都不要加 is 前缀，否则部分框架解析会引起序列化错误。

说明：本文 MySQL 规约中的建表约定第 1 条，表达是与否的变量采用 is_xxx 的命名方式，所以需要在设置从 is_xxx 到 xxx 的映射关系。

反例：定义为布尔类型 Boolean isDeleted 的字段，它的 getter 方法也是 isDeleted()，部分框架在反向解析时，“误以为”对应的字段名称是 deleted，导致字段获取不到，得到意料之外的结果或抛出异常。

10.【重要】包名统一使用小写，点分隔符之间有且仅有一个自然语义的英语单词。包名统一使用单数形式，但是类名如果有复数含义，类名可以使用复数形式。

正例：应用工具类包名为 com.alibaba.ei.kunlun.aap.util；类名为 MessageUtils（此规则参考 spring 的框架结构）。

11.【重要】避免在子父类的成员变量之间、或者不同代码块的局部变量之间采用完全相同的命名，使可理解性降低。

说明：子类、父类成员变量名相同，即使是 public 也是能够通过编译，而局部变量在同一方法内的不同代码块中同名也是合法的，但是要避免使用。对于非 setter / getter 的参数名称也要避免与成员变量名称相同。

反例：

public class ConfusingName { 

    protected int stock; 

    protected String alibaba; 

    // 非 setter/getter 的参数名称，不允许与本类成员变量同名 

    public void access(String alibaba) { 

        if (condition) { 

            final int money = 666; 

            // ... 

        } 

        for (int i = 0; i < 10; i++) { 

            // 在同一方法体中，不允许与其它代码块中的 money 命名相同 

            final int money = 15978; 

            // ... 

        } 

    } 

} 

class Son extends ConfusingName { 

    // 不允许与父类的成员变量名称相同 

    private int stock; 

}

12.【重要】杜绝完全不规范的英文缩写，避免望文不知义。

反例：AbstractClass“缩写”成 AbsClass；condition“缩写”成 condi；Function“缩写”成 Fu，此类随意缩写严重降低了代码的可阅读性。

13.【建议】为了达到代码自解释的目标，任何自定义编程元素在命名时，使用完整的单词组合来表达。

正例：在 JDK 中，对某个对象引用的 volatile 字段进行原子更新的类名为 AtomicReferenceFieldUpdater。

反例：常见的方法内变量为 int a; 的定义方式。

14.【建议】在常量与变量命名时，表示类型的名词放在词尾，以提升辨识度。

正例：startTime / workQueue / nameList / TERMINATED_THREAD_COUNT

反例：startedAt / QueueOfWork / listName / COUNT_TERMINATED_THREAD

15.【建议】如果模块、接口、类、方法使用了设计模式，在命名时要体现出具体模式。

说明：将设计模式体现在名字中，有利于阅读者快速理解架构设计思想。

正例：public class OrderFactory;

public class LoginProxy;

public class ResourceObserver;

16.【建议】接口类中的方法和属性不要加任何修饰符号（public 也不要加），保持代码的简洁性，并加上有效的 Javadoc 注释。尽量不要在接口里定义常量，如果一定要定义，最好确定该常量与接口的方法相关，并且是整个应用的基础常量。

正例：接口方法签名 void commit();

接口基础常量 String COMPANY = "alibaba";

反例：接口方法定义 public abstract void commit();

说明：JDK8 中接口允许有默认实现，那么这个 default 方法，是对所有实现类都有价值的默认实现。

17.接口和实现类的命名有两套规则：

1）【重要】对于 Service 和 DAO 类，基于 SOA 的理念，暴露出来的服务一定是接口，内部的实现类用 Impl 的后缀与接口区别。

正例：CacheServiceImpl 实现 CacheService 接口。

2）【建议】如果是形容能力的接口名称，取对应的形容词为接口名（通常是 –able 结尾的形容词）。

正例：AbstractTranslator 实现 Translatable。

18.【参考】枚举类名带上 Enum 后缀，枚举成员名称需要全大写，单词间用下划线隔开。

说明：枚举其实就是特殊的常量类，且构造方法被默认强制是私有。

正例：枚举名字为 ProcessStatusEnum 的成员名称：SUCCESS / UNKNOWN_REASON

19.【参考】各层命名规约：

A）Service / DAO 层方法命名规约：

1）获取单个对象的方法用 get 做前缀。

2）获取多个对象的方法用 list 做前缀，复数结尾，如：listObjects

3）获取统计值的方法用 count 做前缀。

4）插入的方法用 save / insert 做前缀。

5）删除的方法用 remove / delete 做前缀。

6）修改的方法用 update 做前缀。

B）领域模型命名规约：

1）数据对象：xxxDO，xxx 即为数据表名。

2）数据传输对象：xxxDTO，xxx 为业务领域相关的名称。

3）展示对象：xxxVO，xxx 一般为网页名称。

4）POJO 是 DO / DTO / BO / VO 的统称，禁止命名成 xxxPOJO。

1.2 常量定义

1.【重要】不允许任何魔法值（即未经预先定义的常量）直接出现在代码中。

反例：

// 开发者 A 定义了缓存的 key。 
String key = "Id#taobao_" + tradeId; 
cache.put(key, value); 

// 开发者 B 使用缓存时直接复制少了下划线，即 key 是"Id#taobao" + tradeId，导致出现故障。 
String key = "Id#taobao" + tradeId; 
cache.get(key);

2.【重要】long 或 Long 赋值时，数值后使用大写 L，不能是小写 l，小写容易跟数字混淆，造成误解。

说明：public static final Long NUM = 2l; 写的是数字的 21，还是 Long 型的 2？

3.【重要】浮点数类型的数值后缀统一为大写的 D 或 F。

正例：

public static final double HEIGHT = 175.5D; 

public static final float WEIGHT = 150.3F;

4.【建议】不要使用一个常量类维护所有常量，要按常量功能进行归类，分开维护。

说明：大而全的常量类，杂乱无章，使用查找功能才能定位到要修改的常量，不利于理解，也不利于维护。

正例：缓存相关常量放在类 CacheConsts 下；系统配置相关常量放在类 SystemConfigConsts 下。

5.【建议】常量的复用层次有五层：跨应用共享常量、应用内共享常量、子工程内共享常量、包内共享常量、类内共享常量。

1）跨应用共享常量：放置在二方库中，通常是 client.jar 中的 constant 目录下。

2）应用内共享常量：放置在一方库中，通常是子模块中的 constant 目录下。

反例：易懂常量也要统一定义成应用内共享常量，两个程序员在两个类中分别定义了表示“是”的常量：

类 A 中：public static final String YES = "yes";

类 B 中：public static final String YES = "y";

A.YES.equals(B.YES)，预期是 true，但实际返回为 false，导致线上问题。

3）子工程内部共享常量：即在当前子工程的 constant 目录下。

4）包内共享常量：即在当前包下单独的 constant 目录下。

5）类内共享常量：直接在类内部 private static final 定义。

6.【建议】如果变量值仅在一个固定范围内变化用 enum 类型来定义。

说明：如果存在名称之外的延伸属性应使用 enum 类型，下面正例中的数字就是延伸信息，表示一年中的第几个季节。

正例：

public enum SeasonEnum { 

    SPRING(1), SUMMER(2), AUTUMN(3), WINTER(4); 

    private int seq; 

    SeasonEnum(int seq) { 

        this.seq = seq; 

    } 

    public int getSeq() { 

        return seq; 

    } 
}