《Java 开发手册》的前世今生

《Java 开发手册》始发于阿里巴巴内部规约，涵盖编程规约、异常日志、单元测试、安全规约等七大维度。从 2017 年上线至今整整四年，共发布了七个版本，在全球 Java 开发者共同努力下，这本手册已经成为业界普遍遵循的开发规范，感谢大家一直和我们在码出高效、码出质量的路上并肩同行。

本文将介绍每个版本手册更新的亮点，文末可以下载所有版本的合集。

第七版：泰山版《Java 开发手册》

更新日期：2020/04/22

更新亮点：

• 新增 5 条日期时间规约
• 新增 2 条表别名 sql 规约
• 新增统一错误码规约

新增的规约细则如下：

OOP 规约

1.【强制】任何货币金额，均以最小货币单位且整型类型来进行存储。

2.【推荐】当某个方法的代码行数超过 10 行时，return / throw 等中断逻辑的右大括号后加一个空行。

说明：这样做逻辑清晰，有利于代码阅读时重点关注。

3.【推荐】在类中删除未使用的任何字段和方法；在方法中删除未使用的任何参数声明与内部变量。

4.【强制】三目运算符 condition? 表达式1 : 表达式2 中，高度注意表达式 1 和 2 在类型对齐时，可能抛出因自动拆箱导致的 NPE 异常。

说明：以下两种场景会触发类型对齐的拆箱操作：

• 表达式 1 或表达式 2 的值只要有一个是原始类型。
• 表达式 1 或表达式 2 的值的类型不一致，会强制拆箱升级成表示范围更大的那个类型。

日期时间

1.【强制】在日期格式中分清楚大写的 M 和小写的 m，大写的 H 和小写的 h 分别指代的意义。

说明：日期格式中的这两对字母表意如下：

• 表示月份是大写的 M；
• 表示分钟则是小写的 m；
• 24 小时制的是大写的 H；
• 12 小时制的则是小写的 h。

2.【强制】不允许在程序任何地方中使用：1）java.sql.Date 2）java.sql.Time 3） java.sql.Timestamp。

说明：第 1 个不记录时间，getHours() 抛出异常；第 2 个不记录日期， getYear() 抛出异常；第 3 个在构造方法 super((time/1000)*1000)，fastTime 和 nanos 分开存储秒和纳秒信息。

3.【强制】不要在程序中写死一年为 365 天，避免在公历闰年时出现日期转换错误或程序逻辑错误。

4.【推荐】避免公历闰年 2 月问题。闰年的 2 月份有 29 天，一年后的那一天不可能是 2 月 29 日。

5.【推荐】使用枚举值来指代月份。如果使用数字，注意 Date，Calendar等日期相关类的月份 month 取值在 0-11 之间。

说明：参考 JDK 原生注释，Month value is 0-based. e.g., 0 for January.

集合处理

1.【强制】判断所有集合内部的元素是否为空，使用 isEmpty() 方法，而不是 size()==0 的方式。

说明：前者的时间复杂度为 O(1)，而且可读性更好。

2.【强制】在使用 java.util.stream.Collectors 类的 toMap() 方法转为 Map 集合时，一定要使 用含有参数类型为 BinaryOperator，参数名为 mergeFunction 的方法，否则当出现相同 key 值时会抛出 IllegalStateException 异常。

说明：参数 mergeFunction 的作用是当出现 key 重复时，自定义对 value 的处理策略。

3.【强制】在使用 java.util.stream.Collectors 类的 toMap() 方法转为 Map 集合时，一定要注意当 value 为 null 时会抛 NPE 异常。

说明：在 java.util.HashMap 的 merge 方法里会进行如下的判断：

if (value == null || remappingFunction == null) throw newNullPointerException();

SQL 规约

1.【强制】对于数据库中表记录的查询和变更，只要涉及多个表，都需要在列名前加表的别名（或表名）进行限定。

说明：对多表进行查询记录、更新记录、删除记录时，如果对操作列没有限定表的别名（或表名），并且操作列在多个表中存在时，就会抛异常。

2.【推荐】SQL 语句中表的别名前加 as，并且以 t1、t2、t3、... 的顺序依次命名。

说明：1）别名可以是表的简称，或者是根据表出现的顺序，以 t1、t2、t3 的方式命名。2）别名前加 as 使别名更容易识别。

3.【强制】日志打印时禁止直接用 JSON 工具将对象转换成 String。说明：如果对象里某些 get 方法被重写，存在抛出异常的情况，则可能会因为打印日志而影响正常业务流程的执行。

4.【强制】生产环境禁止直接使用 System.out 或 System.err 输出日志或使用 e.printStackTrace() 打印异常堆栈。

说明：标准日志输出与标准错误输出文件每次 Jboss 重启时才滚动，如果大量输出送往这两个文件，容易造成文件大小超过操作系统大小限制。

其他

1.【强制】避免用 Apache Beanutils 进行属性的 copy。

说明：Apache BeanUtils 性能较差，可以使用其他方案比如 Spring BeanUtils, Cglib BeanCopier，注意均是浅拷贝。

安全规约

1.【强制】URL 外部重定向传入的目标地址必须执行白名单过滤。

二方库规约

1.【推荐】不要使用不稳定的工具包或者 Utils 类。

说明：不稳定指的是提供方无法做到向下兼容，在编译阶段正常，但在运行时产生异常，因此，尽量使用业界稳定的二方工具包。

设计规约

1.【参考】可扩展性的本质是找到系统的变化点，并隔离变化点。

说明：世间众多设计模式其实就是一种设计模式即隔离变化点的模式。

2.【参考】代码即文档的观点是错误的，清晰的代码只是文档的某个片断，而不是全部。

说明：代码的深度调用，模块层面上的依赖关系网，业务场景逻辑，非功能性需求等问题是需要相应的文档来完整地呈现的。

错误码统一

统一错误码，就是统一度量衡，为你的应用与服务的稳定保驾护航，烦恼清空，快乐回家。泰山版新近出炉的错误码具有快速溯源、简单易记、沟通标准化三大优势。错误码为字符串类型，共 5 位，分成两个部分：错误产生来源和四位数字编号。错误产生来源分为 A/B/C，以当前代码运行视角来进行判定，A 表示错误来源于用户，比如请求参数错误，用户安装版本过低等问题；B 表示错误来源于当前系统，往往是业务逻辑出错，或程序健壮性差等问题；C 表示错误来源于第三方服务，比如 CDN 服务出错，消息投递超时等问题。优秀的错误码可以迅速知道他们是怎么来滴，从哪儿来滴，来干啥滴。同时俺们的错误码具有三级结构，分为一级宏观错误码、二级宏观错误码、三级宏观错误码，这样的方案更加可扩展，有弹性，更多详细规则，见手册的附件的《错误码参考列表》。

Java 开发手册所有历史版本

第 6 版：华山版《Java 开发手册》

更新日期：2019/06/13

• 新增 21 条设计规约
• 修改描述 112 处
• 完善若干处示例

第 5 版：1.4.0 版 《阿里巴巴 Java 开发手册》

更新日期：2018/06/06

更新亮点：新增 16 条设计规约

第 4 版：1.3.0 版 《阿里巴巴 Java 开发手册》

更新日期：2017/09/19

更新亮点：增加单元测试规约

第 3 版：1.2.0 版 《阿里巴巴 Java 开发手册》

更新日期：2017/05/20

更新亮点：公开征集意见后修正版本

第 2 版：1.1.0 版 《阿里巴巴 Java 开发手册》

更新日期：2017/02/27

更新亮点：增加前言和专有名词说明，修正部分描述

第 1 版：1.0.0 版 《阿里巴巴 Java 开发手册》

更新日期：2016/12/07

更新亮点：首次向业界开放