阿里巴巴 Java 开发规范手册分享

原名《阿里巴巴 Java 开发手册》但我更喜欢叫《阿里巴巴 Java 开发规范手册》，现已正式更名《Java 开发手册》。在此分享给 Java 相关开发人员，对 Java 开发中的命名、异常、日志、工程等进行规范的参考文档。
本文记录了此手册从最初版到最新版的所有更新记录，并将一直保持更新。 ❤️

2020-08-10 更新 嵩山版解读手册

《〈Java 开发手册（嵩山版）〉灵魂 15 问》

2020-08-03 更新 1.7.0 版(嵩山版)

• 下载地址：Java 开发手册 需登录阿里云账号
• 备用地址：Java 开发手册
• 来源：阿里云开发者社区

本次更新说明：

1. 新增前后端规约 14 条。
2. 新增禁止任何歧视性用语的约定。
3. 新增涉及敏感操作的情况下日志需要保存六个月的约定。
4. 修正 BigDecimal 类中关于 compareTo 和 equals 的等值比较。
5. 修正 HashMap 关于 1024 个元素扩容的次数。
6. 修正架构分层规范与相关说明。
7. 修正泰山版中部分格式错误和描述错误。

2020-04-22 更新 1.6.0 版(泰山版)

• 下载地址：Java 开发手册 需登录阿里云账号
• 备用地址：Java 开发手册 随时可能停用
• 来源：阿里云开发者社区

本次更新说明：

1. 发布错误码统一解决方案，详细参考附表 3。
2. 新增 34 条新规约。比如，日期时间的闰年、闰月问题，三目运算的自动拆箱，SQL 查询的表别名限定，Collectors 类的 toMap()方法使用注意等。
3. 修改描述 90 处。比如，阻塞等待锁、建表的小数类型等。
4. 完善若干处示例。比如，ISNULL 的示例等。

2019-06-19 更新 1.5.0 版(华山版)

• 下载地址：Java 开发手册
• 来源：阿里云开发者社区

本次更新说明

鉴于本手册是社区开发者集体智慧的结晶，本版本移除阿里巴巴 Java 开发手册的限定词 “阿里巴巴”。时隔一年，《Java 开发手册》正式推出更新版，涵盖史无前例的三大升级：

1. 新增 21 条新规约。 比如，switch 的空指针问题、浮点数的比较、无泛型限制引起的类型混乱、加锁与解锁的注意事项、YYYY 的日期格式问题等；
2. 修改描述 112 处。 比如，IFNULL 的判断方式、集合的 toArray 的数组长度、日志占位符的处理等；
3. 完善若干处示例。 比如，变量命名示例、卫语句示例、枚举示例、finally 的 return 示例等。

2018-05-20 更新 1.4.0 版(详尽版)

1. 阿里巴巴 Java 开发规范手册（1.4.0）.pdf
2. v1.4.0 版阿里云下载

本次更新说明
阿里巴巴 Java 开发手册 v1.4.0（详尽版）发布，新增 16 条设计规约。设计规约是根据阿里巴巴实际项目架构经验提炼而成，主要从 UML 图和架构设计原则来规定比较基础的软件设计理念，并且明确了超过什么样的阈值需要以什么样的方式来呈现设计思维。

2017-11-30 更新 1.3.1 版(纪念版)

1. 阿里巴巴 Java 开发规范手册（1.3.1）.pdf
2. v1.3.1 版阿里云下载

本次更新说明

1. 修正部分描述；采用和 P3C 开源 IDE 检测插件相同的 Apache2.0 协议。
2. 考虑到可以零距离地与众多开发同学进行互动，决定未来在线维护《手册》内容，此 1.3.1 的 PDF 版本，是对外释放的最终纪念版，铭记发布第一版以来的 358 天旅程；我们已经在杭州云栖大会上进行了阿里巴巴 Java 开发规约插件点此下载，阿里云效（一站式企业协同研发云）也集成了代码规约扫描引擎。最后，《码出高效——阿里巴巴 Java 开发手册详解》即将出版，敬请关注。

编码规范考试认证：https://edu.aliyun.com/certification/cldt02
IDE 插件下载：https://github.com/alibaba/p3c

2017-09-25 更新 1.3.0 版(终极版)

1. 阿里巴巴 Java 开发规范手册（1.3.0）.pdf
2. v1.3.0 版阿里云下载

本次更新说明

考虑到可以零距离地与众多开发同学进行互动，决定在线维护《手册》内容，此版本号为 1.3.0 的 PDF 版本，是对外释放的终极版；其次，我们会在 2017 年 10 月 14 日 杭州云栖大会上，进行阿里巴巴 Java 开发规约插件全球首发，插件点此下载， 阿里巴巴云效（一站式企业协同研发云）也会集成代码规约扫描引擎。最后，《码出高效——阿里巴巴 Java 开发手册详解》即将出版，敬请关注。

由阿里巴巴 Java 开发规约 HashMap 条目引发的故事 —— 引自 云栖社区

总结

1. HashMap 在 new 后并不会立即分配 bucket 数组，而是第一次 put 时初始化，类似 ArrayList 在第一次 add 时分配空间。
2. HashMap 的 bucket 数组大小一定是 2 的幂，如果 new 的时候指定了容量且不是 2 的幂，实际容量会是最接近(大于)指定容量的 2 的幂，比如 new HashMap<>(19)，比 19 大且最接近的 2 的幂是 32，实际容量就是 32。
3. HashMap 在 put 的元素数量大于 Capacity * LoadFactor（默认 16 * 0.75） 之后会进行扩容。
4. JDK8 处于提升性能的考虑，在哈希碰撞的链表长度达到 TREEIFY_THRESHOLD（默认 8)后，会把该链表转变成树结构。
5. JDK8 在 resize 的时候，通过巧妙的设计，减少了 rehash 的性能消耗。

相对于 JDK7 的 1000 余行代码，JDK8 代码量达到了 2000 余行，对于这个大家最常用的数据结构增加了不少的性能优化。
仔细看完上面的分析和源码，对 HashMap 内部的细节又多了些了解，有空的时候还是多翻翻源码。

《阿里巴巴 Java 开发规约》自诞生以来，一直处于挑战漩涡的最中心，从这一个规约的小条目，看出来规约也是冰冻三尺，非一日之寒，研读规约，其实能够发现很多看似简单的知识点背后，其实隐藏着非常深的逻辑知识点。

2017-05-20 更新 1.2.0 版(完善版)

1. 阿里巴巴 Java 开发规范手册（1.2.0）.pdf
2. v1.2.0 版阿里云下载

本次更新说明

在收集外部建议和阿里内部经验更新的基础上，阿里规约项目组正式推出《阿里巴巴 Java 开发手册》1.2.0 升级版，堪称史上最完善版本。

2017-03-31 更新 1.1.1 版

1. 阿里巴巴 Java 开发规范手册（1.1.1）.pdf
2. v1.1.1 版阿里云下载

2017-02-27 更新 1.1.0 版

1. 阿里巴巴 Java 开发规范手册（1.1.0）.pdf
2. v1.1.0 版云存储备用下载链接

来源

原文内容

2017 年开春之际，诚意献上重磅大礼：阿里巴巴 Java 开发手册，首次公开阿里官方 Java 代码规范标准。这套 Java 统一规范标准将有助于提高行业编码规范化水平，帮助行业人员提高开发质量和效率、大大降低代码维护成本。
点击下载《阿里巴巴 Java 开发手册》(v1.1.0 版)： https://yq.aliyun.com/attachment/download/?id=1200
v1.1.0 版更新说明：1）增加手册前言。2）增加版本历史。3）增加专有名词解释。

阿里巴巴 Java 开发手册快速学习

2017-02-08 正式版发布

1. 阿里巴巴 Java 开发规范手册（正式版）.pdf
2. 正式版云存储备用下载链接

来源

2016-12-07 首次向 Java 业界公开

1. 阿里巴巴 Java 开发规范手册.pdf
2. 云存储备用下载链接

来源

专有名词

1. POJO（Plain Ordinary Java Object） : 在本手册中， POJO 专指只有 setter / getter / toString 的简单类，包括 DO/DTO/BO/VO 等。
2. GAV（GroupId、 ArtifactctId、 Version） : Maven 坐标，是用来唯一标识 jar 包。
3. OOP（Object Oriented Programming） : 本手册泛指类、对象的编程处理方式。
4. ORM（Object Relation Mapping） : 对象关系映射，对象领域模型与底层数据之间的转换，本文泛指 iBATIS, mybatis 等框架。
5. NPE（java.lang.NullPointerException） : 空指针异常。
6. SOA（Service-Oriented Architecture） : 面向服务架构，它可以根据需求通过网络对松散耦合的粗粒度应用组件进行分布式部署、组合和使用， 有利于提升组件可重用性，可维护性。
7. 一方库: 本工程内部子项目模块依赖的库（jar 包） 。
8. 二方库: 公司内部发布到中央仓库，可供公司内部其它应用依赖的库（jar 包） 。
9. 三方库: 公司之外的开源库（jar 包） 。
10. IDE（Integrated Development Environment） : 用于提供程序开发环境的应用程序，一般包括代码编辑器、编译器、调试器和图形用户界面等工具， 本《手册》 泛指 IntelliJ IDEA 和 eclipse。

手册前言

《阿里巴巴 Java 开发手册》是阿里巴巴集团技术团队的集体智慧结晶和经验总结，经历了多次大规模一线实战的检验及不断的完善，系统化地整理成册，反馈给广大开发者。现代软件行业的高速发展对开发者的综合素质要求越来越高，因为不仅是编程知识点，其它维度的知识点也会影响到软件的最终交付质量。比如：数据库的表结构和索引设计缺陷可能带来软件上的架构缺陷或性能风险；工程结构混乱导致后续维护艰难；没有鉴权的漏洞代码易被黑客攻击等等。所以本手册以 Java 开发者为中心视角，划分为编程规约、异常日志、单元测试、安全规约、工程结构、MySQL 数据库六个维度，再根据内容特征，细分成若干二级子目录。根据约束力强弱及故障敏感性，规约依次分为强制、推荐、参考三大类。对于规约条目的延伸信息中，“说明”对内容做了适当扩展和解释；“正例”提倡什么样的编码和实现方式；“反例”说明需要提防的雷区，以及真实的错误案例。

本手册的愿景是__码出高效， 码出质量__。现代软件架构都需要协同开发完成，高效协作即降低协同成本，提升沟通效率，所谓无规矩不成方圆，无规范不能协作。众所周知，制订交通法规表面上是要限制行车权，实际上是保障公众的人身安全。试想如果没有限速，没有红绿灯，谁还敢上路行驶。对软件来说，适当的规范和标准绝不是消灭代码内容的创造性、优雅性，而是限制过度个性化，以一种普遍认可的统一方式一起做事，提升协作效率。代码的字里行间流淌的是软件生命中的血液，质量的提升是尽可能少踩坑，杜绝踩重复的坑，切实提升质量意识。

《阿里巴巴 Java 开发手册》，开放包容地认真总结社区、博客、论坛的反馈，及时修正，保持与时俱进。更多及时信息，请关注《阿里巴巴 Java 开发手册》官方公众号：