《Java 开发手册》的前世今生-阿里云开发者社区

开发者社区> 阿里技术> 正文

《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

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

版权声明:如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件至:developerteam@list.alibaba-inc.com 进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容。

分享:
+ 订阅

关于阿里的技术创新均呈现于此.

官方博客
官网链接