此套 Java 开发手册阿里巴巴 Java 技术团队，近万名阿里 Java 技术精英的经验总结，并经历了多次大规模一线实战检验及完善，铸就了这本高含金量的阿里 Java 开发手册。该手册以 Java 开发者为中心视角，划分为编程规约、异常日志规约、MYSQL 规约、工程规约、安全规约五大块，再根据内容特征，细分成若干二级子目录。根据约束力强弱和故障敏感性，规约依次分为强制、推荐、参考三大类。此套规范不仅能让代码一目了然，更有助于加强团队分工与合作、真正提升效率。
前言
《阿里巴巴 Java 开发手册》是阿里巴巴集团技术团队的集体经验总结，经历了多次大规模一线实战的检验及不断地完善，反馈给广大开发者。现代软件行业的告诉发展对开发者的综合素质要求越来越高，因为不仅是编程知识点，其他维度的知识点也会影响到软件的最终交付质量最终交付质量。比如：数据库的表结构和索引设计缺陷可能带来软件商的架构缺陷或性能奉献；工程结构混乱导致后续维护艰难；没有健全的漏洞代码易被黑客攻击等等。所以本手册以 Java 开发者为中新世交中心视角，划分为编程规约、异常日志、MySQL 数据库、工程结构、安全规约五大块，再根据内容特征，细分为若干二级子目录。根据约束力强弱及故障敏感性，规约一次分为强制、推荐、参考三大类。对于规约条目的眼神信息中，“说明”对内容作了隐身和解释；“正例”提倡什么样的编码和实现方式；“反例”说明需要提防的雷区，以及真实的错误案例。
本手册的愿景是码出高效、码出质量。代码的字里行间流淌的是软件生命中的血液，质量的提升是尽可能少踩坑，杜绝踩重复的坑，切实提升质量意识。另外，现代软件架构都需要协同开发完成，高效协作既降低协同成本，提升沟通效率，所谓无规矩不成方圆，无规范不能协作。众所周知，制定交通法规表面上是要限制行车权，实际上是保障公众的人身安全。试想如果没有限速，没有红绿灯，谁还敢上路行驶。对软件来说，适当的规范和标准绝不是消灭代码内容的创造性、优雅性，而是限制过度个性化，以一种普遍认可的统一方式一起做事，提升协作效率。
《阿里巴巴 Java 开发手册》，开放包容地认真听取社区、博客、论坛的反馈，及时修正，保持与时俱进。请关注手册末页的“阿里技术”和“云栖社区”公众号获取最新版本。
## 目录 前言 一、编程规约 （一） 命名风格 （二） 常量定义 （三） 代码格式 （四） OOP 规约 （五） 集合处理 （六） 并发处理 （七） 控制语句 （八） 注释规约 （九） 其他 二、异常日志 （一） 异常处理 （二） 日志规约 三、MySQL 数据库 （一） 建表规约 （二） 索引规约 （三） SQL 语句 （四） ORM 映射 四、工程结构 （一） 应用分层 （二） 二房库依赖 （三） 服务器 五、安全规约 附 1：历史版本 附 2：本手册转悠名词
## Java 开发手册 |版本号|制定团队|更新日志|备注| |:---:|:---:|:---:|:---:| |1.2.0|阿里巴巴集团技术团队|2017.5.20|公开征集意见后的修正版本。|
## 一、编程规约 ### （一）命名风格 1. 【强制】 代码中的命名均不能以蓝色开始**下划线或美元符号蓝色结束开始，也不能以蓝色开始**下划线或美元符号**蓝色结束结束。 红色开始反例：红色结束 _name / __name / $Object / name_ / name$ / Object$ 2. 【强制】 代码中的命名严禁使用拼音与英文混合的方式，更不允许直接使用中文的方式。 说明：正确的英文拼写和语法可以让阅读者易于理解，避免歧义。注意，即使纯拼音命名方式也要避免采用。 正例： alibaba / taobao / youku / hangzhou 等国际通用的名称，可视同英文。 反例： DaZhePromotion [打折] / getPingfenByName() [评分] / int 某变量 = 3 3. 【强制】 类名使用 UpperCamelCase 风格，必须遵从驼峰形式，但以下情形例外：DO / BO / DTO / VO /AO 正例： 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;`； 反例： 使用 `String args[]` 的方式来定义。 8. 【强制】 POJO 类中布尔类型的变量，都不要加 is，否则部分框架解析会引起序列化错误。 反例： 定义为基本数据类型 `Boolean isDeleted;` 的属性，它的方法也是 `isDeleted()`，RPC 框架在反向解析的时候，“以为”对应的属性名称是 deleted，导致属性获取不到，进而跑出异常。 9. 【强制】 包名统一使用小写，点分隔符之间有且仅有一个自然语义的英语单词。包名统一使用蓝色开始**单数**蓝色结束形式，但是类名如果有复数寒意，类名可以使用复数形式。 正例： 应用工具类包名为 com.alibaba.open.util、类名为 MessageUtils（此规则参考 spring 的框架结构）。 10. 【强制】 杜绝完全不规范的缩写，避免忘文不知义。 反例： AbstractClass “缩写”命名成 AbsClass；condition “缩写”命名成 condi，此类随意缩写严重降低了代码的可阅读星。 11. 【推荐】 如果使用到了设计模式，建议在类名中体现出具体模式。 说明： 将设计模式体现在名字中，有利于阅读者快速理解架构设计思想。 正例：
public class OrderFactory;
public class LoginProxy;
public class ResourceObserver;### （二）常量定义 1. 【强制】 不允许任何魔法值（即未经定义的常量）直接出现在代码中。 反例：
String key = "Id#taobao_" + tradeId;
cache.put(key, value);### （三）代码格式 1. 【强制】 大括号的使用约定。如果是大括号内为空，则简洁地写成{}即可，不需要换行；如果是非空代码块则： 1. 左大括号前不换行。 2. 左大括号后换行。 3. 右大括号前换行。 4. 右大括号后还有 else 等代码则不换行；表示终止的右大括号后必须换行。 2. 【强制】 左小括号和字符之间不出现控制；同样，右小括号和字符之间也不出现空格。详见第 5 条下方正例提示。 反例： if (空格a == b空格) 3. 【强制】 if/for/while/switch/do 等保留字与括号之间都必须加空格。 4. 【强制】 任何二目、三目运算符的左右两边都需要加一个空格。 说明： 运算符包括赋值运算符 =、逻辑运算符 &&、加减乘除符号等。 5. 【强制】 缩进采用 4 个空格，禁止使用 tab 字符。 说明：如果使用 tab 缩进，必须设置 1 个 tab 为 4 个空格。IDEA 设置 tab 为 4 个空格时，请勿勾选 红色开始 Use tab character 红色结束；而在 eclipse 中，必须勾选 红色开始 insert spaces for tabs 红色结束。 正例： （涉及 1-5 点）
public static void main(String[] args) {
// 缩进 4 个空格
String say = "hello";
// 运算符的左右必须有一个空格
int flag = 0;
// 关键期 if 与括号之间必须有一个空格，括号内的 f 与左括号，0 与右括号不需要空格
if (flag == 0) {
System.out.println(say);
}
// 左大括号前加空格且不换行；左大括号后换行
if (flag == 1) {
System.out.pringln("world");
// 右大括号钱换行，右大括号后有 else，不用换行
} else {
System.out.println("ok");
// 在右大括号后直接结束，则必须换行
}
}StringBuffer sb = new StringBuff();
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);method("a", "b", "c");int a = 3;
long b = 4L;
float c = 5F;
StringBuffer sb = new StringBuffer();### （四）OOP 规约 1. 【强制】 避免通过一个类的对象引用访问此类的静态变量或静态方法，武威增加编译器解析成本，直接用蓝色开始类名蓝色结束来访问即可。 2. 【强制】 所有的覆写方法，必须加 @Override 注解。 说明： getObject() 与 get0bject() 的问题。一个是字母的 O，一个是数字的 0，加 @Override 可以准确判断是否覆盖成功。另外，如果在抽象类中对方法签名进行修改，其实现类会马上编译报错。 3. 【强制】 相同参数类型，相同业务寒意，才可以使用 Java 的可变参数，避免使用 Objcet。 说明： 可变参数必须放置在参数列表的最后。（提倡同学们尽量不用可变参数编程） 正例：
public User getUser(String type, Integer... ids) {
...
}String str = "a,b,c,,";
String[] ary = str.split(",");
// 预期大于 3，结果是 3
System.out.println(ary.length);public Integer getData() {
if (true) {
return this.data + 100;
} else {
return this.data - 100;
}
}String str = "start";
for (int i = 0; i < 100; i++) {
str = str + "hello";
}### （五）集合处理 1. 【强制】 关羽 hashCode 和 equals 的处理，遵循如下规则： 1. 只要重写 equals，就必须重写 hashCode。 2. 因为 Set 存储的是不重复的对象，依据 hashCode 和 equals 进行判断，所以 Set 存储的对象必须重写这两个方法。 3. 如果自定义对象违 Map 的键，那么必须重写 hashCode 和 equals。 说明： String 重写了 hashCode 和 equals 方法，所以我们可以非常愉快地使用 String 对象作为 key 来使用。 2. 【强制】 ArrayList 的 subList 结果不可强转成 ArrayList，否则会抛出 ClasscastException 异常：java.util.RandomAccessSubList cannot be cast to java.util.ArrayList； 说明： subList 返回的是 ArrayList 的内部类 SubList，并不是 ArrayList，而是 ArrayList 的一个视图，对于 SubList 子列表的所有操作最终会反映到原列表上。 3. 【强制】 在 subList 场景中，蓝色开始高度注意蓝色结束对原集合元素个数的修改，会导致子列表的遍历、增加、删除均产生 ConcurrentModificationException 异常。 4. 【强制】 使用几何转数组的方法，必须使用几何的 toArray(T[] array)，传入的是类型完全一样的数组，大小就是 list.size()。 说明： 使用 toArray 带参方法，入参分配的数组空间不够大时，toArray 方法内部将重新分配内存空间，并返回新数组地址；如果数组元素大于实际所需，下标为 [ list.size() ] 的数组元素将被置为 null，其他数组元素保持原值，因此最好将方法入参，数组大小定义与几何元素个数一致。 正例：
List<String> list = new ArrayList<String>(2);
list.add("guan");
list.add("bao");
String[] array = new String[list.size()];
array = list.toArray(array);String[] str = new String[] {"a", "b"};
List list = Arrays.asList(str);Iteratior<String> it = a.iterator();
while (it.hasNext()) {
String temp = it.next();
if (删除元素的条件) {
it.remove();
}
}List<String> a = new ArrayList<String>();
a.add("1");
a.add("2");
for (String temp : a) {
if ("1".equals(temp)) {
a.remove(temp);
}
}new Comparator<Student>() {
@Override
public int compare(Student o1, Student o2) {
return o1.getId() > o2.getId() ? 1 : -1;
}
};### （六）并发处理 1. 【强制】 获取单例对象需要保证线程安全，其中的方法也要保证线程安全。 说明：资源驱动类、工具类、单例工厂类都需要注意。 2. 【强制】 创建线程或线程池时请指定有意义的线程名称，方便出错时回溯。 正例：
public class TimerTaskThread extends Thread {
public TimerTaskThread() {
super.setName("TimerTaskThread";...
}
}private static final ThreadLocal<DateFormat> df = new ThreadLocal<DateFormat>() {
@Override
protected DateFormat initialValue() {
return new SimpleDateFormat("yyyy-MM-dd");
}
};class Foo {
private Helper helper = null;
public Helper getHelper() {
if (helper == null) synchronized(this) {
if (helper == null)
helper = new Helper();
}
return helper;
}
// other functions and members...
}AtomicInteger count = new AtomicInteger();
count.addAndGet(1);### （七）控制语句 1. 【强制】 在一个 switch 块内，每个 case 要么通过 break/return 等来终止，要么注释说明程序将继续执行到哪个 case 位置；在一个 switch 块内，都必须包含一个 default 语句并且放在最后，即使它什么代码也没有。 2. 【强制】 在 if/else/for/while/do 语句中必须使用大括号。即使只有一行代码，避免使用单行形式：`if (condition) statements;` 3. 【推荐】 表达异常的分支时，少用 if-else 方式，这种方式可以改写成：
if (condition) {
...
return obj;
}
// 接着写 else 的业务逻辑代码；public void today() {
if (isBusy()) {
System.out.println("change time.");
return;
}
if (isFree()) {
System.out.println("go to travel.");
return;
}
System.out.println("stay at home to learn Alibaba Java Coding Guideline.");
return;
}// 伪代码如下
final boolean existed = (file.open(fileName, "w") != null) && (...) || (...);
if (existed) {
...
}if ((file.open(fileName, "w") != null) && (...) || (...)) {
...
}### （八）注释规约 1. 【强制】 类、类属性、类方法的注释必须使用 Javadoc 规范，使用 `/** 内容 */` 格式，不得使用 //xxx 方式。 说明： 在 IDE 编辑窗口中，Javadoc 方式会提示相关注释，生成 Javadoc 可以正确输出响应注释；在 IDE 中，工程调用方法时，不进入方法即可悬浮提示方法、参数、返回值得意义，提高阅读效率。 2. 【强制】 所有的抽象方法（包括接口中的方法）必须要用 Javadoc 注释，除了返回值、参数、异常说明外，还必须指出该方法做什么事情，实现什么功能。 说明： 对子类的实现要求，或者调用注意事项，请一并说明。 3. 【强制】 所有的类都必须添加创建者和创建日期。 4. 【强制】 方法内部单行注释，在被注释语句上方另起一行，使用 `//` 注释。方法内部多行注释使用 `/* */` 注释，注意与代码对齐。 5. 【强制】 所有的枚举类型字段必须要有注释，说明每个数据项的用途。 6. 【推荐】 与其“半吊子”英文来注释，不如用中文注释把问题说清楚。专有名词与关键字保持英文原文即可。 反例： “TCP 连接超时”解释成“传输控制谢意连接超时”，理解反而费脑筋。 7. 【推荐】 代码修改的同时，注释也要进行相应的修改，尤其是参数、返回值、异常、核心逻辑等的修改。 说明： 代码与注释更新不同步，就像路网与导航软件更新不同步一样，如果导航软件严重滞后，就失去了导航的意义。 8. 【参考】 合理处理注释掉的代码。在上方详细说明，而不是简单地注释掉。如果无用，则删除。 说明： 代码被注释掉有两种可能性： 1. 后续会恢复此段代码逻辑。此时如果没有备注信息，难以知晓注释动机。 2. 永久不用。此时建议直接删掉（代码仓库保存了历史代码）。 9. 【参考】 对于注释的要求：第一、能够准确反映涉及思想和代码逻辑；第二、能够描述业务寒意，使别的程序员能够迅速了解到代码背后的信息。完全没有注释的打断代码对于阅读者形同天数，注释是给自己看的，即使隔很长时间，也能清晰理解当时的思路；注释也是给继任者看的，使其能够快速接替自己的工作。 10. 【参考】 好的命名、代码结构是自解释的，注释力求精简准确、表达到位。避免出现注释的一个极端：过多过滥的注释，代码的逻辑一旦修改，修改注释是相当大的负担。 反例：
// put elephant into fridge
put(elephant, fridge);### （九）其他 1. 【强制】 在使用正则表达式时，利用好其预编译功能，可以有效加快正则匹配速度。 说明： 不要在方法体内定义：
Pattern pattern = Pattern.compile(规则);## 二、异常日志 ### （一）异常处理 1. 【强制】 Java 类库中定义的一类 RuntimeException 可以通过预先检查进行规避，而不应该通过 catch 来处理，比如：IndexOutOfBoundsException，NullPointerException 等等。 说明： 无法通过预检查的异常除外，如在解析一个外部传来的字符串形式数字时，通过 catch NumberFormatException 来实现。 正例： `if (obj != null) {...}` 反例： `try {obj.method() } catch (NullPointerException e) {...}` 2. 【强制】 异常不要用来做流程控制、条件控制，因为异常的处理效率比条件分支低。 3. 【强制】 对大段代码进行 try-catch，这是不负责任的表现。catch 时请分清稳定代码和非稳定代码，稳定代码指的是无论如何不会出错的代码。对于非稳定代码的 catch 尽可能进行区分异常类型，再做对应的异常处理。 4. 【强制】 捕获异常是为了处理它，不要捕获了却什么都不处理而抛弃之，如果不想处理它，请将该异常抛给它的调用者。最外层的业务使用者，必须处理异常，将其转化为用户可以理解的内容。 5. 【强制】 有 try 块放到了事务代码中，catch 异常后，如果需要回滚事务，一定要注意手动回滚事务。 6. 【强制】 finally 块必须对资源对象、流对象进行关闭，有异常也要做 try-catch。 说明： 如果 JDK 7 及以上，可以使用 try-with-resources 方式。 7. 【强制】 不能再 finally 快中使用 return，finally 块中的 return 返回后方法结束执行，不会再执行 try 块中的 return 语句。 8. 【强制】 捕获异常与抛异常，必须是完全匹配，或者捕获异常是抛异常的父类。 说明： 如果预期对方抛的是绣球，实际接到的是铅球，就会产生意外情况。 9. 【推荐】 方法的蓝色开始返回值可以为 null 蓝色结束，不强制返回空集合，或者空对象等，必须添加注释充分说明什么情况下回返回 null 值。调用方需要进行 null 判断放置 NPE 问题。 说明： 本手册明确放置 NPE 是调用者的责任。即使被调用方法返回空集合或者空对象，对调用者来说，也并非高枕无忧，必须考虑到远程调用失败、序列化失败、运行时异常等场景返回 null 的情况。 10. 【推荐】 防止 NPE，是程序员的基本修养，注意 NPE 产生的场景： 1. 返回类型为基本数据类型，return 包装数据类型的对象时，自动拆箱有可能产生 NPE。 反例： `public int f() { return Integer 对象}`，如果为 null，自动拆箱抛 NPE。 2. 数据库的查询结果可能为 null。 3. 集合里的元素即使 isNotEmpty，取出的数据元素也可能为 null。 4. 远程调用返回对象时，一律要求进行空指针判断，防止 NPE。 5. 对于 Session 中获取的数据，建议 NPE 检查，避免空指针。 6. 级联调用 obj.getA().getB().getC()；一连串调用，易产生 NPE。 正例： 使用 JDK 8 的 Optional 类来防止 NPE 问题。 11. 【推荐】 定义时区分 unchecked / checked 异常，避免直接抛出 new RuntimeException()，更不允许抛出 Exception 或者 Throwable，应使用有业务含义的自定义异常。推荐业界已定义过的自定义异常，如：DAOException / ServiceException 等。 12. 【参考】 在代码中使用“抛异常”还是“返回错误码”，对于公司外的 http/api 开放接口必须使用“错误码”；而应用内部推荐异常抛出；跨应用间 RPC 调用优先考虑蓝色开始使用 Result 方式蓝色结束，封装 isSuccess() 方法、“错误码”、“错误简短信息”。 说明： 关于 RPC 方法返回方式使用 Result 方式的理由： 1. 使用抛异常返回方式，调用方如果没有捕获到就会产生运行时错误。 2. 如果不加栈信息，只是 new 自定义异常，加入自己的理解的 error message，对于调用端解决问题的帮助不会太多。如果加了栈信息，在频繁调用出错的情况下，数据序列化和传输的性能损耗也是问题。 13. 【参考】 避免出现重复的代码（Don't Repeat Yourself），即 DRY 原则。 说明： 随意复制和粘贴代码，必然会导致代码的重复，在以后需要修改时，需要修改所有的副本，容易遗漏。必要时抽取共性方法，或者抽象公共类，甚至是公用模块。 正例： 一个类中有多个 public 方法，都需要进行数行相同的参数校验操作，这个时候请抽取：
private boolean checkParam(DTO dto) {
...
}### （二）日志规约 1. 【强制】 应用中不可直接使用日志系统（Log4j、Logback）中的 API，而应该依赖使用日志框架 SLF4J 中的 API，使用门面模式的日志框架，有利于维护和各个类的日志处理方式统一。
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
...
private static final Logger logger = LoggerFactory.getLogger(Abc.class);
...logger.debug("Processing trad with id: " + id + " symbol: " + symbol);if (logger.isDebugEnabled()) {
logger.debug("Processing trad with id: " + id + " symbol: " + symbol);
}logger.debug("Processing trad with id: {} symbol: {}, id, symbol);## MySQL 数据库 ### （一）建表规约
