阿里巴巴Java开发手册（第2版）

杨冠宝

畅销书《码出高效：Java开发手册》作者。阿里巴巴集团高级技术专家，花名孤尽，取自风清扬的“独孤九剑，破尽天下武功”之意。在阿里历任技术研发、架构师、部门主管等不同的角色，承担过双十一、国际化、代码中心、资产平台等大型项目，有着丰富的一线编程实战和架构经验。目前是阿里巴巴资产平台部负责人，在大数据、高并发、分布式、代码效能等领域均有较深的造诣。乐于分享与总结，在国内外做过多次大型交流和培训，引起强烈共鸣。

经过认真倾听读者反馈，学习开源社区的详细建议，本手册在第1版的基础上，增加前后端规约，发布错误码解决方案，修正架构分层图例等相关内容，新增59条规约，修正202处原有规约，完善8个示例，是面向业界以来更为完善的版本。

别人都说我们是“搬砖”的码农，但我们知道自己是追求个性的艺术家。也许我们不会过多在意自己的外表和穿着，但在我们不羁的外表下，骨子里追求着代码的美、系统的美、设计的美，代码规范其实就是对程序美的定义。但是这种美离程序员的生活有些遥远，尽管编码规范的价值在业内有着广泛的共识，在现实中却被否定得一塌糊涂。工程师曾经最引以为豪的代码，因为编码规范的缺失、命名的草率而全面地摧毁了彼此的信任，并严重地制约了高效协同。工程师一边吐槽别人的代码，一边写着被吐槽的代码，频繁的系统重构和心惊胆战的维护似乎成了工作的主旋律。

那么如何走出这种怪圈呢？众所周知，互联网公司的优势在于效率，它是企业核心竞争力。体现在产品开发领域，就是沟通效率和研发效率。对于沟通效率的重要性，可以从程序员三大“编程理念之争”说起：

— 缩进采用空格键，还是 Tab 键。

— if 单行语句需要大括号，还是不需要大括号。

— 左大括号不换行，还是单独另起一行。

在美剧《硅谷》中，你也许会记得这样一个经典镜头：主人公Richard 与同为程序员的女友分手，理由是两人对缩进方式有着不同的习惯，互相鄙视着对方的 code style。Tab 键和空格键的争议在现实编程工作中确实存在。《阿里巴巴 Java 开发手册（第 2 版）》（以下简称“《手册》”）明确地支持了 4 个空格的做法，如果一定要问理由，那么没有理由，因为能够想出来的理由，就像坚固的盾一样，总有更加锋利的矛会戳破它。只想说，一致性很重要，无边无际争论的时间成本与最后的收益是成反比的。

if 单语句是否需要大括号，也是争论不休的话题。相对来说，写过格式缩进类编程语言的开发者，更加习惯不加大括号。《手册》中明确，if/for 单语句必须加大括号，因为单行语句的写法，容易在添加逻辑时引起视觉上的错误判断。此外，if 不加大括号还会有局部变量作用域的问题，详见《码出高效：Java 开发手册》。

左大括号是否单独另起一行？因为 Go 语言强制不换行，在这点上，“编程理念之争”的硝烟味没有那么浓。如果一定要给一个理由， 那么换行的代码可以增加一行，对于按代码行数考核工作量的公司员工，肯定倾向于左大括号前换行。《手册》中明确，左大括号不换行。这些理念之争的本质就是自己多年代码习惯生的茧，不愿意对不一样的风格妥协，不愿意为了团队的整体效能提升而委屈自己。其实，很多编程方式客观上没有对错之分，一致性很重要，可读性很重要，团队沟通效率很重要。有一个理论叫帕金森琐碎定律：一个组织中的成员往往会把过多的精力花费在一些琐碎的争论上。程序员天生需要团队协作，而协作的正能量要放在问题的有效沟通上。个性化应尽量表现在代码可维护性和算法效率的提升上，而不是在合作规范上进行纠缠不休的讨论、争论，最后没有结论。规范不一，就像下图中的小鸭子和小鸡对话一样，言语不通，一脸囧相。鸡同鸭讲恰恰戳中了人与人之间沟通的痛点，自说自话，无法达成一致。再举个生活中的例子，交通规则中靠左行还是靠右行，两者孰好孰坏并不重要，重要的是必须在统一的方向上通行，表面上限制了自由，但实际上保障了公众的人身安全。试想，如果没有规定靠右行驶，那么路况肯定拥堵不堪，险象环生。同样，过分自由随意、天马行空的代码会严重地损害系统的健康，影响到可扩展性及可维护性。

为了帮助开发人员更好地提高研发效率，阿里巴巴集团基于《手册》内容，独立研发了一套自动化 IDE 检测插件。该插件在扫描代码后，将不符合《手册》的代码按 block/critical/major 三个等级显示在下方；在编写代码时，还会给出智能实时提示，告诉你代码如何编写可以更优雅、更符合大家共同的编程风格；对于历史代码，部分规则实现了批量一键修复功能。此插件已经在 2017年杭州云栖大会上正式对外开放并提供了源码，下载地址为https://github.com/alibaba/p3c。

第2版前言

《阿里巴巴 Java 开发手册（第 2 版）》（以下简称“《手册》”）是阿里巴巴集团技术团队的集体智慧结晶和经验总结，经历了多次大规模一线实战的检验及不断完善，公开到业界后，众多社区开发者踊跃参与，共同打磨完善，系统化地整理成册。在第 1 版基础上，认真倾听读者反馈，学习开源社区的详细建议，增加前后端规约，发布错误码解决方案，修正架构分层图例等相关内容，涉及 59 条新规约，修正 202 处原有规约，完善 8 个示例，是面向业界 3 年以来更为完善的版本。

现代软件行业的高速发展对开发者的综合素质要求越来越高，除了编程知识点，其他维度的知识点也会影响到软件的最终交付质量。比如，五花八门的错误码导致排查问题困难重重，数据库的表结构和索引设计缺陷带来系统架构缺陷或性能风险，工程结构混乱导致后续项目维护艰难，没有鉴权的漏洞代码易被黑客攻击等。因此，《手册》以 Java 开发者为中心视角，划分为编程规约、异常日志、单元测试、安全规约、MySQL 数据库、工程结构、设计规约七个维度，再根据内容特征，细分成若干二级子目录。

另外，依据约束力强弱及故障敏感性，规约依次分为【强制】、【推荐】和【参考】三大类。在延伸信息中，“说明”对规约做了适当扩展和解释，“正例”表示提倡的编码和实现方式，“反例”表示需要提防的雷区，以及真实的错误案例。

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

我们已经在 2017 年杭州云栖大会上发布了配套的“Java 开发规约 IDE 插件”，下载量达到 160 万人次，阿里云效也集成了代码规约扫描引擎。2018 年，我们发布了 36 万字的配套详解图书《码出高效：Java 开发手册》，该书秉持“图胜于表，表胜于言”的理念，深入浅出地将计算机基础、面向对象思想、JVM 探源、数据结构与集合、并发与多线程、单元测试等知识客观而立体地呈现出来，紧扣学以致用、学以精进的目标，结合阿里巴巴实践经验和故障案例，与底层源码解析融会贯通、娓娓道来。《码出高效：Java 开发手册》和《手册》图书出版所得收入均捐赠公益事业，希望用技术情怀帮助更多的人。

专家语录 III
第2版序 V
第2版前言 X
第1章 编程规约 1
1．1 命名风格 2
1．2 常量定义 9
1．3 代码格式 12
1．4 OOP规约 17
1．5 日期时间 26
1．6 集合处理 29
1．7 并发处理 39
1．8 控制语句 48
1．9 注释规约 55
1．10 前后端规约 59
1．11 其他 64
第2章 异常日志 66
2．1 错误码 67
2．2 异常处理 70
2．3 日志规约 75
第3章 单元测试 80
第4章 安全规约 86
第5章 MySQL数据库 90
5．1 建表规约 91
5．2 索引规约 95
5．3 SQL语句 99
5．4 ORM映射 103
第6章 工程结构 106
6．1 应用分层 107
6．2 二方库依赖 110
6．3 服务器 114
第7章 设计规约 116
附录A 专有名词 122