阿里巴巴Java开发手册（部分）-黄山

一、命名规则

1、代码中的命名均不能以下划线或美元符号开始，也不能以下划线或美元符号结束

反例： _name / __name / $Object/nam{e}_{/}name$ / Object$

2、代码中的命名严禁使用拼音与英文混合的方式，更不允许直接使用中文的方式

说明：正确的英文拼写和语法可以让阅读者易于理解，避免歧义。注意，即使纯拼音命名方式也要避免采用

反例： DaZhePromotion [ 打折 ] / getPingfenByName() [ 评分 ] / int 某变量 = 3

3、类名使用 UpperCamelCase 风格，必须遵从驼峰形式

正例： MarcoPolo / UserDO / XmlService / TcpUdpDeal / TaPromotion

反例： macroPolo / UserDo / XMLService / TCPUDPDeal / TAPromotion

4、方法名、参数名、成员变量、局部变量都统一使用 lowerCamelCase 风格，必须遵从

驼峰形式,首字母小写

正例： localValue / getHttpMessage() / inputUserId

5、常量命名全部大写，单词间用下划线隔开，力求语义表达完整清楚，不要嫌名字长

正例： MAX _ STOCK _ COUNT

反例： MAX _ COUNT

6、抽象类命名使用 Abstract 或 Base 开头 ； 异常类命名使用 Exception 结尾 ； 测试类

命名以它要测试的类的名称开始，以 Test 结尾

7、中括号是数组类型的一部分，数组定义如下： String[] args

8、包名统一使用小写，点分隔符之间有且仅有一个自然语义的英语单词。包名统一使用

单数形式，但是类名如果有复数含义，类名可以使用复数形式。

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

9、杜绝完全不规范的缩写，避免望文不知义

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

10、为了达到代码自解释的目标，任何自定义编程元素在命名时，使用尽量完整的单词

组合来表达其意。

正例：从远程仓库拉取代码的类命名为 PullCodeFromRemoteRepository。

反例：变量 int a; 的随意命名方式。

11、如果模块、接口、类、方法使用了设计模式，在命名时体现出具体模式。

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

正例：
public class OrderFactory;
public class LoginProxy;
public class ResourceObserver;

12、接口类中的方法和属性不要加任何修饰符号 （public 也不要加 ） ，保持代码的简性，并加上有效的 Javadoc 注释。尽量不要在接口里定义变量，如果一定要定义变量，肯定是与接口方法相关，并且是整个应用的基础常量

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

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

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

13、接口和实现类的命名有两套规则

1）对于 Service 和 DAO 类，基于 SOA 的理念，暴露出来的服务一定是接口，内部

的实现类用 Impl 的后缀与接口区别。

正例： CacheServiceImpl 实现 CacheService 接口。

2）如果是形容能力的接口名称，取对应的形容词做接口名 （ 通常是– able 的形式 ）

13、各层命名规约

A) Service / DAO 层方法命名规约

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

2 ） 获取多个对象的方法用 list 做前缀。

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、long 或者 Long 初始赋值时，使用大写的 L ，不能是小写的 l ，小写容易跟数字 1 混

淆，造成误解

说明： Long a = 2 l; 写的是数字的 21，还是 Long 型的 2?

3、不要使用一个常量类维护所有常量，按常量功能进行归类，分开维护

说明：大而全的常量类，非得使用查找功能才能定位到修改的常量，不利于理解和维护。

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

代码格式

1、大括号的使用约定。如果是大括号内为空，则简洁地写成{}即可，不需要换行 ； 如果

是非空代码块则：

1 ） 左大括号前不换行。

2 ） 左大括号后换行。

3 ） 右大括号前换行。

4 ） 右大括号后还有 else 等代码则不换行 ； 表示终止的右大括号后必须换行。

2、左小括号和字符之间不出现空格 ； 同样，右小括号和字符之间也不出现空格。详见

第 5 条下方正例提示。

反例： if (空格 a == b 空格)

3、if / for / while / switch / do 等保留字与括号之间都必须加空格

4、任何二目、三目运算符的左右两边都需要加一个空格

说明：运算符包括赋值运算符=、逻辑运算符&&、加减乘除符号等

5、注释的双斜线与注释内容之间有且仅有一个空格

正例： // 注释内容，注意在 // 和注释内容之间有一个空格。

6、单行字符数限制不超过 120 个，超出需要换行，换行时遵循如下原则：

1） 第二行相对第一行缩进 4 个空格，从第三行开始，不再继续缩进，参考示例。

2 ） 运算符与下文一起换行。

3 ） 方法调用的点符号与下文一起换行。

4 ） 方法调用时，多个参数，需要换行时，在逗号后进行。

5 ） 在括号前不要换行，见反例

正例：

StringBuffer sb = new StringBuffer();
// 超过 120 个字符的情况下，换行缩进 4 个空格，点号和方法名称一起换行
sb.append("zi").append("xin")...
  .append("huang")...
  .append("huang")...
  .append("huang");

反例：

StringBuffer sb = new StringBuffer();
// 超过 120 个字符的情况下，不要在括号前换行
sb.append("zi").append("xin")...append
("huang");
// 参数很多的方法调用可能超过 120 个字符，不要在逗号前换行
method(args1, args2, args3, ...
, argsX);

7、方法参数在定义和传入时，多个参数逗号后边必须加空格。

正例：下例中实参的" a ",后边必须要有一个空格。

method(“a”, “b”, “c”);

8、方法体内的执行语句组、变量的定义语句组、不同的业务逻辑之间或者不同的语义

之间插入一个空行。相同业务逻辑和语义之间不需要插入空行

说明：没有必要插入多个空行进行隔开。

oop规约

1、避免通过一个类的对象引用访问此类的静态变量或静态方法，无谓增加编译器解析成

本，直接用类名来访问即可。

2、所有的覆写方法，必须加@ Override 注解。

3、 Object 的 equals 方法容易抛空指针异常，应使用常量或确定有值的对象来调用equals

正例：" test " .equals(object);

反例： object.equals( " test " );

4、关于基本数据类型与包装数据类型的使用标准如下：

1） 所有的 POJO 类属性必须使用包装数据类型。

2） 所有的局部变量使用基本数据类型【推荐】。

5、定义 DO / DTO / VO 等 POJO 类时，不要设定任何属性默认值。

6、构造方法里面禁止加入任何业务逻辑，如果有初始化逻辑，请放在 init 方法中。

7、当一个类有多个构造方法，或者多个同名方法，这些方法应该按顺序放置在一起。

8、类内方法定义顺序依次是：公有方法或保护方法 > 私有方法 > getter / setter方法。

9、setter 方法中，参数名称与类成员变量名称一致， this .成员名 = 参数名。在getter / setter 方法中，不要增加业务逻辑，增加排查问题的难度。

反例：

public Integer getData() {
   if (true) {
      return this.data + 100;
  } else {
      return this.data - 100;
  }
}

10、类成员与方法访问控制从严：

1）如果不允许外部直接通过 new 来创建对象，那么构造方法必须是 private（单例模式采用这种方式）。

2）工具类不允许有 public 或 default 构造方法。

3）类非 static 成员变量并且仅在本类使用，必须是 private。

4）若是 static 成员变量，必须考虑是否为 final 。

5）类成员方法只供类内部调用，必须是 private 。

6）类成员方法只对继承类公开，那么限制为 protected 。

控制语句

1、在一个 switch 块内，每个 case 要么通过 break / return 等来终止，要么注释说明程序将继续执行到哪一个 case 为止 ； 在一个 switch 块内，都必须包含一个 default 语句并且放在最后，即使它什么代码也没有。

2、在 if / else / for / while / do 语句中必须使用大括号。即使只有一行代码，避免采用单行的编码方式： if (condition) statements;

注释

1、类、类属性、类方法的注释必须使用 Javadoc 规范，使用/*内容/格式，不得使用

// xxx 方式。

2、方法内部单行注释，在被注释语句上方另起一行，使用//注释。方法内部多行注释

使用/* */注释，注意与代码对齐。

3、代码修改的同时，注释也要进行相应的修改，尤其是参数、返回值、异常、核心逻辑

等的修改

4、谨慎注释掉代码。在上方详细说明，而不是简单地注释掉。如果无用，则删除。

说明：代码被注释掉有两种可能性：1 ） 后续会恢复此段代码逻辑。2 ） 永久不用。前者如果没有备注信息，难以知晓注释动机。后者建议直接删掉 （ 代码仓库保存了历史代码 ） 。

5、对于注释的要求：第一、能够准确反应设计思想和代码逻辑 ； 第二、能够描述业务含

义，使别的程序员能够迅速了解到代码背后的信息。完全没有注释的大段代码对于阅读者形同天书，注释是给自己看的，即使隔很长时间，也能清晰理解当时的思路 ； 注释也是给继任者看的，使其能够快速接替自己的工作。

6、好的命名、代码结构是自解释的，注释力求精简准确、表达到位。避免出现注释的

一个极端：过多过滥的注释，代码的逻辑一旦修改，修改注释是相当大的负担。

异常

1、对大段代码进行 try - catch ，这是不负责任的表现。 catch 时请分清稳定代码和非稳

定代码，稳定代码指的是无论如何不会出错的代码。对于非稳定代码的 catch 尽可能进行区分异常类型，再做对应的异常处理。

2、有 try 块放到了事务代码中， catch 异常后，如果需要回滚事务，一定要注意手动回

滚事务。

3、finally 块必须对资源对象、流对象进行关闭，有异常也要做 try - catch

4、不能在 finally 块中使用 return ， finally 块中的 return 返回后方法结束执行，不会再执行 try 块中的 return 语句。

5、捕获异常与抛异常，必须是完全匹配，或者捕获异常是抛异常的父类

说明：如果预期对方抛的是绣球，实际接到的是铅球，就会产生意外情况

6、方法的返回值可以为 null ，不强制返回空集合，或者空对象等，必须添加注释充分

说明什么情况下会返回 null 值。调用方需要进行 null 判断防止 NPE 问题

NPE是NullPointerException的简称，就是空指针异常，通常是在调用某个空变量的方法或者属性爆出的，比如 String s = null; Sytem.out.println(s.charAt(0);

MySQL数据库

1、表名、字段名必须使用小写字母或数字 ， 禁止出现数字开头，禁止两个下划线中间只

出现数字。数据库字段名的修改代价很大，因为无法进行预发布，所以字段名称需要慎重考虑

说明：MySQL 在 Windows 下不区分大小写，但在 Linux 下默认是区分大小写。因此，数据库名、表名、字段名，都不允许出现任何大写字母，避免节外生枝。

正例： aliyun _ admin ， rdc _ config ， level 3_ name

反例： AliyunAdmin ， rdcConfig ， level 3 name

2、表名不使用复数名词

说明：表名应该仅仅表示表里面的实体内容，不应该表示实体数量，对应于 DO 类名也是单数形式，符合表达习惯。

3、主键索引名为 pk_ 字段名；唯一索引名为 uk _字段名 ； 普通索引名则为 idx _字段名。

说明： pk_ 即 primary key；uk _ 即 unique key；idx _ 即 index 的简称

4、小数类型为 decimal ，禁止使用 float 和 double

5、varchar 是可变长字符串，不预先分配存储空间，长度不要超过 5000，如果存储长

度大于此值，定义字段类型为 text ，独立出来一张表，用主键来对应，避免影响其它字段索引效率

6、varchar 是可变长字符串，不预先分配存储空间，长度不要超过 5000，如果存储长

度大于此值，定义字段类型为 text ，独立出来一张表，用主键来对应，避免影响其它字段索引效率

7、表的命名最好是加上“业务名称_表的作用”。

正例： alipay _ task / force _ project / trade _ config

1、如果修改字段含义或对字段表示的状态追加时，需要及时更新字段注释。

2、单表行数超过 500 万行或者单表容量超过 2 GB ，才推荐进行分库分表。

《Java 开发手册》是 Java 社区爱好者的集体智慧结晶和经验总结，经历了多次大规模一线实战的检验及不断完善，整理成册后，众多社区开发者踊跃参与打磨完善，系统化地整理成册，当前的最新版本是黄山版。现代软件行业的高速发展对开发者的综合素质要求越来越高，因为不仅是编程知识点，其它维度的知识点也会影响到软件的最终交付质量。比如：五花八门的错误码会人为 地增加排查问题的难度；数据库的表结构和索引设计缺陷带来的系统架构缺陷或性能风险；工程结构混乱导致后续项目维护艰难；没有鉴权的漏洞代码容易被黑客攻击等。所以本手册以 Java 开发者为中心视角，划分为编程规约、异常日志、单元测试、安全规约、MySQL 数据库、工程结构、设计规约七个维度，再根据内容特征，细分成若干二级子目录。此外，依据约束力强弱及故障敏感性，规约依次分为【强制】、【推荐】、【参考】三大类。在延伸的信息中，“说明”对规约做了适当扩展和解释；“正例”提倡什么样的编码和实现方式；“反例”说明需要提防的雷区，以及真实
的错误案例。
手册的愿景是码出高效，码出质量。现代软件架构的复杂性需要协同开发完成，如何高效地协同呢？无规矩不成方圆，无规范难以协同，比如，制定交通法规表面上是要限制行车权，实际上是保障公众的人身安全，试想如果没有限速，没有红绿灯，谁还敢上路行驶？对软件来说，适当的规范和标准绝不是消灭代码内容的创造性、优雅性，而是限制过度个性化，以一种普遍认可的统一方式一起做事，提升协作效率，降低沟通成本。代码的字里行间流淌的是软件系统的血液，代码质量的提升是尽可能少踩坑，杜绝踩重复的坑，切实提升系统稳定性，码出质量。
2017 年杭州云栖大会上发布了配套的 Java 开发规约 IDE 插件，下载量已达到 275 万人次，阿里云效也集成了代码规约扫描引擎。2018年9月在云栖厅发布 36 万字的配套详解图书《码出高效》，秉持“图胜于表，表胜于言”的理念，深入浅出地将计算机基础、面向对象思想、数据结构与集合、JVM 探源与内存分析、并发与多线程、单元测试等知识丰富立体地呈现出来。本书紧扣学以致用、学以精进的目标，结合一线开发的实践经验和故障案例，与底层源码解析融会贯通，娓娓道来。《码出高效》和《Java 开发手册（第 2 版）》稿费所得收入均捐赠公益事情，希望用技术情怀帮助到更多的人。

目录
一、编程规约 …
1 (一) 命名风格…1
(二) 常量定义…3
(三) 代码格式…4
(四) OOP 规约…6
(五) 日期时间…9
(六) 集合处理…10
(七) 并发处理…14
(八) 控制语句…17
(九) 注释规约…20
(十) 前后端规约…21
(十一) 其他…23
二、异常日志 …24
(一) 错误码 …24
(二) 异常处理…25
(三) 日志规约…26
三、单元测试 …29
四、安全规约 …31
五、MySQL 数据库…32
(一) 建表规约…32
(二) 索引规约…33
(三) SQL 语句 …34
(四) ORM 映射…35
六、工程结构 …37
(一) 应用分层…37
(二) 二方库依赖…38
(三) 服务器 …39
七、设计规约 …40
附 1：版本历史…42
附 2：专有名词解释…44
附 3：错误码列表…45