阿里巴巴Java开发手册1.4.0学习

这篇文章只标记我目前工作经常用到的，后续需要的会继续补充！

一、编程规约

（一）命名规范

• 3. 【强制】类名使用UpperCamelCase风格，但以下情形例外：DO / BO / DTO / VO / AO / PO / UID等。
     正例：MarcoPolo / UserDO / XmlService / TcpUdpDeal / TaPromotion
     反例：macroPolo / UserDo / XMLService / TCPUDPDeal / TAPromotion
• 4. 【强制】方法名、参数名、成员变量、局部变量都统一使用lowerCamelCase风格，必须遵从驼峰形式。
     正例： localValue / getHttpMessage() / inputUserId
• 5. 【强制】常量命名全部大写，单词间用下划线隔开，力求语义表达完整清楚，不要嫌名字长。
     正例：MAX_STOCK_COUNT
     反例：MAX_COUNT
• 8. 【强制】POJO类中布尔类型的变量，都不要加is前缀，否则部分框架解析会引起序列化错误。
     反例：定义为基本数据类型Boolean isDeleted的属性，它的方法也是isDeleted()，RPC框架在反向解析的时候，“误以为”对应的属性名称是deleted，导致属性获取不到，进而抛出异常。
• 13. 【推荐】接口类中的方法和属性不要加任何修饰符号（public 也不要加），保持代码的简洁性，并加上有效的Javadoc注释。尽量不要在接口里定义变量，如果一定要定义变量，肯定是与接口方法相关，并且是整个应用的基础常量。
      正例：接口方法签名void commit();
         接口基础常量String COMPANY = "alibaba";
      反例：接口方法定义public abstract void f();
      说明：JDK8中接口允许有默认实现，那么这个default方法，是对所有实现类都有价值的默认实现。
• 14. 接口和实现类的命名有两套规则：
      1）【强制】对于Service和DAO类，基于SOA的理念，暴露出来的服务一定是接口，内部的实现类用Impl的后缀与接口区别。 正例：CacheServiceImpl实现CacheService接口。
      2） 【推荐】 如果是形容能力的接口名称，取对应的形容词为接口名（通常是–able的形式）。 正例：AbstractTranslator实现 Translatable接口。
• 15. 【推荐】枚举类名建议带上Enum后缀，枚举成员名称需要全大写，单词间用下划线隔开。
      说明：枚举其实就是特殊的类，域成员均为常量，且构造方法被默认强制是私有。
      正例：枚举名字为ProcessStatusEnum的成员名称：SUCCESS / UNKNOWN_REASON。

（三）代码格式

• 正例： （涉及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.println("world");
    // 右大括号前换行，右大括号后有else，不用换行
    } else {
        System.out.println("ok");
    // 在右大括号后直接结束，则必须换行
    }
}

• 7. 【强制】单行字符数限制不超过 120 个，超出需要换行，换行时 遵循如下原则：
     1） 第二行相对第一行缩进 4 个空格，从第三行开始，不再继续缩进，参考示例。
     2） 运算符与下文一起换行。
     3） 方法调用的点符号与下文一起换行。
     4） 方法调用中的多个参数需要换行时，在逗号后进行。
     5） 在括号前不要换行，见反例。

正例：

StringBuffer sb = new StringBuffer();
// 超过120个字符的情况下，换行缩进4个空格，点号和方法名称一起换行
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);

• 8. 【强制】方法参数在定义和传入时，多个参数逗号后边必须加空格。 正例：下例中实参的args1，后边必须要有一个空格。

method(args1, args2, args3);

• 9. 【强制】IDE的text file encoding设置为UTF-8; IDE中文件的换行符使用Unix格式，不要使用Windows格式。

（四）OOP规约

• 6. 【强制】Object的equals方法容易抛空指针异常，应使用常量或确定有值的对象来调用equals。
     正例："test".equals(object);
     反例：object.equals("test");
     说明：推荐使用java.util.Objects#equals（JDK7引入的工具类）
• 7. 【强制】所有的相同类型的包装类对象之间值的比较，全部使用equals方法比较。
• 8. 关于基本数据类型与包装数据类型的使用标准如下：
     1） 【强制】所有的POJO类属性必须使用包装数据类型。
     2） 【强制】RPC方法的返回值和参数必须使用包装数据类型。
     3） 【推荐】所有的局部变量使用基本数据类型。
• 10. 【强制】序列化类新增属性时，请不要修改serialVersionUID字段，避免反序列失败；如果完全不兼容升级，避免反序列化混乱，那么请修改serialVersionUID值。
      说明：注意serialVersionUID不一致会抛出序列化运行时异常。
• 12. 【强制】POJO类必须写toString方法。使用IDE中的工具：source> generate toString时，如果继承了另一个POJO类，注意在前面加一下super.toString。
      说明：在方法执行抛出异常时，可以直接调用POJO的toString()方法打印其属性值，便于排查问题。
• 14. 【推荐】使用索引访问用String的split方法得到的数组时，需做最后一个分隔符后有无内容的检查，否则会有抛IndexOutOfBoundsException的风险。
      说明：

String str = "a,b,c,,";
String[] ary = str.split(",");
// 预期大于3，结果是3
System.out.println(ary.length);

• 16. 【推荐】 类内方法定义的顺序依次是：公有方法或保护方法 > 私有方法 > getter/setter方法。
      说明：公有方法是类的调用者和维护者最关心的方法，首屏展示最好；保护方法虽然只是子类关心，也可能是“模板设计模式”下的核心方法；而私有方法外部一般不需要特别关心，是一个黑盒实现；因为承载的信息价值较低，所有Service和DAO的getter/setter方法放在类体最后。
• 18. 【推荐】循环体内，字符串的连接方式，使用StringBuilder的append方法进行扩展。
      说明：下例中，反编译出的字节码文件显示每次循环都会new出一个StringBuilder对象，然后进行append操作，最后通过toString方法返回String对象，造成内存资源浪费。
      反例：

String str = "start";
for (int i = 0; i < 100; i++) {
    str = str + "hello";
}

（五）集合处理

• 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);

反例：直接使用toArray无参方法存在问题，此方法返回值只能是Object[]类，若强转其它类型数组将出现ClassCastException错误。

• 5. 【强制】使用工具类Arrays.asList()把数组转换成集合时，不能使用其修改集合相关的方法，它的add/remove/clear方法会抛出UnsupportedOperationException异常。 说明：asList的返回对象是一个Arrays内部类，并没有实现集合的修改方法。Arrays.asList体现的是适配器模式，只是转换接口，后台的数据仍是数组。
     String[] str = new String[] { "you", "wu" };
     List list = Arrays.asList(str);
     第一种情况：list.add("yangguanbao"); 运行时异常。
     第二种情况：str[0] = "gujin"; 那么list.get(0)也会随之修改。
• 7. 【强制】不要在foreach循环里进行元素的remove/add操作。remove元素请使用Iterator方式，如果并发操作，需要对Iterator对象加锁。
     正例：

List<String> list = new ArrayList<>();
list.add("1");
list.add("2");
Iterator<String> iterator = list.iterator();
while (iterator.hasNext()) {
    String item = iterator.next();
    if (删除元素的条件) {
        iterator.remove();
    }
}

反例：

for (String item : list) {
    if ("1".equals(item)) {
        list.remove(item);
    }
}

• 12. 【推荐】高度注意Map类集合K/V能不能存储null值的情况，如下表格：
      
• 14. 【参考】利用Set元素唯一的特性，可以快速对一个集合进行去重操作，避免使用List的contains方法进行遍历、对比、去重操作。

（六）并发处理

• 5. 【强制】SimpleDateFormat 是线程不安全的类，一般不要定义为static变量，如果定义为static，必须加锁，或者使用DateUtils工具类。
     正例：注意线程安全，使用DateUtils。亦推荐如下处理：

private static final ThreadLocal<DateFormat> df = new ThreadLocal<DateFormat>() {
    @Override
    protected DateFormat initialValue() {
        return new SimpleDateFormat("yyyy-MM-dd");
    }
};

说明：如果是JDK8的应用，可以使用Instant代替Date，LocalDateTime代替Calendar，DateTimeFormatter代替SimpleDateFormat，官方给出的解释：simple beautiful strong immutable thread-safe。

（七）控制语句

• 1. 【强制】在一个switch块内，每个case要么通过break/return等来终止，要么注释说明程序将继续执行到哪一个case为止；在一个switch块内，都必须包含一个default语句并且放在最后，即使空代码。
• 6. 【推荐】循环体中的语句要考量性能，以下操作尽量移至循环体外处理，如定义对象、变量、获取数据库连接，进行不必要的try-catch操作（这个try-catch是否可以移至循环体外）。
• 9. 【参考】下列情形，需要进行参数校验：
     1） 调用频次低的方法。
     2） 执行时间开销很大的方法。此情形中，参数校验时间几乎可以忽略不计，但如果因为参数错误导致中间执行回退，或者错误，那得不偿失。
     3） 需要极高稳定性和可用性的方法。
     4） 对外提供的开放接口，不管是RPC/API/HTTP接口。
     5） 敏感权限入口。
• 10. 【参考】下列情形，不需要进行参数校验：
      1） 极有可能被循环调用的方法。但在方法说明里必须注明外部参数检查要求。
      2） 底层调用频度比较高的方法。毕竟是像纯净水过滤的最后一道，参数错误不太可能到底层才会暴露问题。一般DAO层与Service层都在同一个应用中，部署在同一台服务器中，所以DAO的参数校验，可以省略。
      3） 被声明成private只会被自己代码所调用的方法，如果能够确定调用方法的代码传入参数已经做过检查或者肯定不会有问题，此时可以不校验参数。

（八）注释规约

• 1. 【强制】类、类属性、类方法的注释必须使用Javadoc规范，使用/** 内容*/格式，不得使用// xxx方式。
     说明：在IDE编辑窗口中，Javadoc方式会提示相关注释，生成Javadoc可以正确输出相应注释；在IDE中，工程调用方法时，不进入方法即可悬浮提示方法、参数、返回值的意义，提高阅读效率。
• 4. 【强制】方法内部单行注释，在被注释语句上方另起一行，使用//注释。方法内部多行注释使用/* */注释，注意与代码对齐。
• 11. 【参考】特殊注释标记，请注明标记人与标记时间。注意及时处理这些标记，通过标记扫描，经常清理此类标记。线上故障有时候就是来源于这些标记处的代码。
      1） 待办事宜（TODO）:（ 标记人，标记时间，[预计处理时间]） 表示需要实现，但目前还未实现的功能。这实际上是一个Javadoc的标签，目前的Javadoc还没有实现，但已经被广泛使用。只能应用于类，接口和方法（因为它是一个Javadoc标签）。
      2） 错误，不能工作（FIXME）:（标记人，标记时间，[预计处理时间]） 在注释中用FIXME标记某代码是错误的，而且不能工作，需要及时纠正的情况。

（九）其它

• 4. 【强制】注意 Math.random() 这个方法返回是double类型，注意取值的范围 0≤x<1（能够取到零值，注意除零异常），如果想获取整数类型的随机数，不要将x放大10的若干倍然后取整，直接使用Random对象的nextInt或者nextLong方法。
• 5. 【强制】获取当前毫秒数System.currentTimeMillis(); 而不是new Date().getTime();
     说明：如果想获取更加精确的纳秒级时间值，使用System.nanoTime()的方式。在JDK8中，针对统计时间等场景，推荐使用Instant类。