【Java】阿里巴巴Java开发手册

官方文档

• github

一、编程规约

命名风格

通用

1. 不能以_或$开始及结束。
2. 使用正确的英文拼写和语法，禁止不规范的缩写，禁止使用拼音。
3. 禁止歧视性词语：
   1. blackList$\to$blockList
   2. whiteList$\to$allowList
   3. slave$\to$replica
   4. master$\to$main/default

   在美国各州的BlackLivesMatter（黑人的命同等重要）运动中，Google浏览器Chrome为了表示对反种族歧视运动的支持，未来将不再使用“Blacklist”（黑名单）、“Whitelist”（白名单）等词，改为“Blocklist”（禁止名单）与“Allowlist”（通行名单），以避开含有种族歧视的暗示。Google Chrome的开发团队在官方代码样式指南中加入《如何编写种族中立代码》的条文，提醒Chrome的开发人员应避免使用“Blacklist”、“Whitelist”等词，改用中性词汇如“Blocklist”和“Allowlist”。团队指出，Blacklist、Whitelist这类词汇长期使用下来，会让用户产生「黑＝坏」、「白＝好」的观念，增强种族歧视的概念。这项变动甚至涉及2000处的内部代码。

包名

使用小写，.之间仅有一个自然语义的英语单词，使用单数形式（此规则是参考spring的框架结构）。
例：com.alibaba.app.util.MessageUtils。

类名

1. 使用UpperCamelCase（大驼峰命名法），BO、PO、VO、DTO等领域模型例外。
2. 抽象类使用Abstract或Base开头，异常类使用Exception结尾，测试类使用“它要测试的类的名称+Test”。
3. 可用复数形式。

接口

1. 方法和属性不加任何修饰符号，保持代码的简洁性。
2. 基于SOA的理念的Service和DAO类，暴露出来的服务一定是接口，内部的实现类用Impl的后缀与接口区别，例如：
3. 若是形容能力的接口名称，取对应的形容词为接口名，通常是以able为词根的形容词，例如：AbstractTranslator实现Translatable接口。

方法名、参数名、成员变量、局部变量

1. 使用lowerCamelCase（小驼峰命名法）。
2. 禁止子父类的成员变量之间或不同代码块的局部变量之间采用完全相同的命名，这会使可读性降低，构造函数及“getter/setter”除外：
   反例：

public class ConfusingName {
   
	public int stock;
	public void get(String alibaba) {
   
		if (condition) {
   
			final int money = 666;
		}
		for (int i = 0; i < 10; i++) {
   
			// 反例1
			final int money = 15978;
		}
	}
}
class Son extends ConfusingName {
   
	// 反例2
	public int stock;
}

数组

用类型与中括号紧挨表示。

• 正例：int[] arry = {1, 2};
• 反例：int arry[] = {1, 2};

枚举

类名带上Enum后缀，枚举成员名称需要全大写，单词间用下划线隔开。
说明：枚举其实就是特殊的常量类，且构造方法被默认强制是私有。

总结

望文生义

常量

命名

1. （final static）全部大写，单词间用下划线隔开。
   正例：
   1. private final Contract delegate;
   2. public final static Map<String, MethodMetadata> METADATA_MAP = new HashMap<>();
2. 常量与变量命名时，表示类型的名词放在词尾以提升辨识度：
   1. QueueOfWork$\to$workQueue
   2. listName$\to$nameList
   3. COUNT_TERMINATED_THREAD$\to$TERMINATED_THREAD_COUNT

定义

1. 禁止魔法值。
2. 按功能进行归类。
3. 复用层次：
   1. 跨应用共享常量
   2. 应用内共享常量：子模块的constant目录下
   3. 子工程内共享常量：子工程的constant目录下
   4. 包内共享常量：包的constant目录下
   5. 类内共享常量

POJO

定义

1. POJO：在本规约中专指只有setter/getter/toString的简单类，包括DO/DTO/BO/VO等。
2. DO（Data Object）：阿里巴巴专指数据库表一一对应的POJO类。此对象与数据库表结构一一对应，通过DAO层向上传输数据源对象。
3. DTO（Data Transfer Object）：数据传输对象，Service或Manager向外传输的对象。
4. BO（Business Object）：业务对象，可以由Service层输出的封装业务逻辑的对象。
5. Query：数据查询对象，用于各层接收上层的查询请求。有超过2个参数的查询封装时禁止使用Map类来传输。
6. VO（View Object）：显示层对象，通常是Web向模板渲染引擎层传输的对象。
7. AO（Application Object）：阿里巴巴专指Application Object，即在Service层上，极为贴近业务的复用代码。

命名

布尔类型的变量禁止加is前缀，否则部分框架解析会引起序列化错误。

初始化

1. 禁止设定任何属性的默认值。
2. 必须写toString方法（勿忘加super.toString）。
3. 禁止同时存在对应属性xxx的isXxx()和getXxx()方法。

代码格式

1. 单个方法的行数（除注释）不超过80行。
2. 不同的逻辑、语义、业务的代码之间可插入一个空行分隔开来以提升可读性，但任何情形下都没必要插入多个空行进行分隔。

OOP规约

Object Oriented Programming（面向对象编程）

方法

1. 重写方法必须加@Override：在编译期就可判断是否覆盖成功。
2. 不允许修改外部正在调用的接口的方法签名，避免对接口调用方产生影响，若接口过时则必须加@Deprecated，并说明采用的新接口或新服务。
3. 禁止使用过时的类或方法。

数据类型

1. 所有货币金额均以以最小货币单位的整型来进行存储。
2. 定义数据对象类（DO）时，属性类型要与数据库字段类型相匹配，如bigint必须对应Long，若bigint unsigned对应Integer，则可能会溢出成负数。
3. POJO类的属性、RPC方法的返回值和参数都必须使用包装数据类型。