Java开发规范-----泰山版的java开发规范

最近在看阿里的java开发规范，一次记录自己工作中犯的错误案例：

1.POJO类中的任何布尔类型的变量，都不要加is前缀，否则部分框架解析会引起序列化错误。（****）

说明：在本文MySQL规约中的建表约定第一条，表达是与否的值采用is_xxx的命名方式，所以，需要在设置从is_xxx到xxx的映射关系

反例：定义为基本数据类型Boolean isDeleted的属性，它的方法也是isDeleted()，框架在反向解析的时候，“误以为”对应的属性名称是deleted，导致属性获取不到，进而抛出异常。

2. 【强制】包名统一使用小写，点分隔符之间有且仅有一个自然语义的英语单词。包名统一使用单数形式，但是类名如果有复数含义，类名可以使用复数形式。

正例：应用工具类包名为com.alibaba.ei.kunlun.aap.util、类名为MessageUtils（此规则参考spring的框架结构）

3.在常量与变量的命名时，表示类型的名词放在词尾，以提升辨识度。

正例：startTime / workQueue / nameList / TERMINATED_THREAD_COUNT
反例：startedAt / QueueOfWork / listName / COUNT_TERMINATED_THREAD

4.如果模块、接口、类、方法使用了设计模式，在命名时需体现出具体模式。

说明：将设计模式体现在名字中，有利于阅读者快速理解架构设计理念。
正例： public class OrderFactory; public class LoginProxy; public class ResourceObserver;

5.接口类中的方法和属性不要加任何修饰符号（public 也不要加），保持代码的简洁性，并加上有效的Javadoc注释。尽量不要在接口里定义变量，如果一定要定义变量，确定与接口方法相关，并且是整个应用的基础常量。

正例：接口方法签名 void commit(); 接口基础常量 String COMPANY = “alibaba”;
反例：接口方法定义 public abstract void f();
说明：JDK8中接口允许有默认实现，那么这个default方法，是对所有实现类都有价值的默认实现。

代码格式

【强制】如果是大括号内为空，则简洁地写成{}即可，大括号中间无需换行和空格；如果是非空代码块则： 1） 左大括号前不换行。 2） 左大括号后换行。 3） 右大括号前换行。 4） 右大括号后还有else等代码则不换行；表示终止的右大括号后必须换行。

【强制】注释的双斜线与注释内容之间有且仅有一个空格。
// 这是示例注释，请注意在双斜线之后有一个空格
String commentString = new String();

【强制】在进行类型强制转换时，右括号与强制转换值之间不需要任何空格隔开

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

StringBuilder sb = new StringBuilder();
// 超过120个字符的情况下，换行缩进4个空格，并且方法前的点号一起换行
sb.append("zi").append("xin")...
	.append("huang")...
	.append("huang")...
	.append("huang");

【强制】方法参数在定义和传入时，多个参数逗号后边必须加空格。

集合处理

【强制】关于hashCode和equals的处理，遵循如下规则：
1） 只要重写equals，就必须重写hashCode。
2） 因为Set存储的是不重复的对象，依据hashCode和equals进行判断，所以Set存储的对象必须重写这两个方法。
3） 如果自定义对象作为Map的键，那么必须覆写hashCode和equals。 说明：String因为重写了hashCode和equals方法，所以我们可以愉快地使用String对象作为key来使用

【强制】判断所有集合内部的元素是否为空，使用isEmpty()方法，而不是size()==0的方式。 说明：前者的时间复杂度为O(1)，而且可读性更好。
正例：

Map<String, Object> map = new HashMap<>();
if(map.isEmpty()) {
System.out.println("no element in this map.");
}

【强制】在使用java.util.stream.Collectors类的toMap()方法转为Map集合时，一定要使用含有参数类型为BinaryOperator，参数名为mergeFunction的方法，否则当出现相同key值时会抛出IllegalStateException异常。
说明：参数mergeFunction的作用是当出现key重复时，自定义对value的处理策略。
正例：

List<Pair<String, Double>> pairArrayList = new ArrayList<>(3);
pairArrayList.add(new Pair<>("version", 6.19));
pairArrayList.add(new Pair<>("version", 10.24));
pairArrayList.add(new Pair<>("version", 13.14));
Map<String, Double> map = pairArrayList.stream().collect(
// 生成的map集合中只有一个键值对：{version=13.14} 
Collectors.toMap(Pair::getKey, Pair::getValue, (v1, v2) -> v2)); 

反例：
String[] departments = new String[] {"iERP", "iERP", "EIBU"};
// 抛出IllegalStateException异常
Map<Integer, String> map = Arrays.stream(departments)
.collect(Collectors.toMap(String::hashCode, str -> str));

【强制】使用Map的方法keySet()/values()/entrySet()返回集合对象时，不可以对其进行添加元素操作，否则会抛出UnsupportedOperationException异常。

【强制】Collections类返回的对象，如：emptyList()/singletonList()等都是immutable list，不可对其进行添加或者删除元素的操作。 反例：如果查询无结果，返回Collections.emptyList()空集合对象，调用方一旦进行了添加元素的操作，就会触发UnsupportedOperationException异常。

【强制】在subList场景中，高度注意对父集合元素的增加或删除，均会导致子列表的遍历、增加、删除产生ConcurrentModificationException 异常。

【强制】在使用Collection接口任何实现类的addAll()方法时，都要对输入的集合参数进行NPE判断。 说明：在ArrayList#addAll方法的第一行代码即Object[] a = c.toArray(); 其中c为输入集合参数，如果为null，则直接抛出异常。

【强制】使用工具类Arrays.asList()把数组转换成集合时，不能使用其修改集合相关的方法，它的add/remove/clear方法会抛出UnsupportedOperationException异常。
说明：asList的返回对象是一个Arrays内部类，并没有实现集合的修改方法。
Arrays.asList体现的是适配器模式，只是转换接口，后台的数据仍是数组。
String[] str = new String[] { “yang”, “hao” };
List list = Arrays.asList(str);
第一种情况：
list.add(“yangguanbao”); 运行时异常。
第二种情况：str[0] = “changed”; 也会随之修改，反之亦然。

【强制】泛型通配符来接收返回的数据，此写法的泛型集合不能使用add方法，而不能使用get方法，两者在接口调用赋值的场景中容易出错。 说明：扩展说一下PECS(Producer Extends Consumer Super)原则：第一、频繁往外读取内容的，适合用。第二、经常往里插入的，适合用

【强制】在无泛型限制定义的集合赋值给泛型限制的集合时，在使用集合元素时，需要进行instanceof判断，避免抛出ClassCastException异常。

在进行对一个 List进行删除/移除操作的时候，要进行迭代器进行移除元素操作
【强制】不要在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);
}
}

说明：以上代码的执行结果肯定会出乎大家的意料，那么试一下把“1”换成“2”，会是同样的结果吗？

【强制】在JDK7版本及以上，Comparator实现类要满足如下三个条件，不然Arrays.sort，Collections.sort会抛IllegalArgumentException异常。
说明：三个条件如下
1） x，y的比较结果和y，x的比较结果相反。
2） x>y，y>z，则x>z。
3） x=y，则x，z比较结果和y，z比较结果相同。
反例：下例中没有处理相等的情况，交换两个对象判断结果并不互反，不符合第一个条件，在实际使用中 可能会出现异常。

new Comparator<Student>() {
@Override
public int compare(Student o1, Student o2) {
return o1.getId() > o2.getId() ? 1 : -1;
}
};

【推荐】使用entrySet遍历Map类集合KV，而不是keySet方式进行遍历。 说明：keySet其实是遍历了2次，一次是转为Iterator对象，另一次是从hashMap中取出key所对应的value。而entrySet只是遍历了一次就把key和value都放到了entry中，效率更高。如果是JDK8，使用Map.forEach方法。 正例：values()返回的是V值集合，是一个list集合对象；keySet()返回的是K值集合，是一个Set集合对象；entrySet()返回的是K-V值组合集合。

【参考】合理利用好集合的有序性(sort)和稳定性(order)，避免集合的无序性(unsort)和不稳定性(unorder)带来的负面影响。
说明：有序性是指遍历的结果是按某种比较规则依次排列的。
稳定性指集合每次遍历的元素次序是一定的。
如：ArrayList是order/unsort；HashMap是unorder/unsort；TreeSet是order/sort。

并发处理

【强制】获取单例对象需要保证线程安全，其中的方法也要保证线程安全。
说明：资源驱动类、工具类、单例工厂类都需要注意。

【强制】线程资源必须通过线程池提供，不允许在应用中自行显式创建线程。
说明：线程池的好处是减少在创建和销毁线程上所消耗的时间以及系统资源的开销，解决资源不足的问题。如果不使用线程池，有可能造成系统创建大量同类线程而导致消耗完内存或者“过度切换”的问题。

【强制】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。

【强制】必须回收自定义的ThreadLocal变量，尤其在线程池场景下，线程经常会被复用，如果不清理自定义的 ThreadLocal变量，可能会影响后续业务逻辑和造成内存泄露等问题。尽量在代理中使用try-finally块进行回收。
正例：

objectThreadLocal.set(userInfo);
try {
// ...
} finally {
objectThreadLocal.remove();
}

【强制】高并发时，同步调用应该去考量锁的性能损耗。能用无锁数据结构，就不要用锁；能锁区块，就不要锁整个方法体；能用对象锁，就不要用类锁。 说明：尽可能使加锁的代码块工作量尽可能的小，避免在锁代码块中调用RPC方法。

【强制】对多个资源、数据库表、对象同时加锁时，需要保持一致的加锁顺序，否则可能会造成死锁。 说明：线程一需要对表A、B、C依次全部加锁后才可以进行更新操作，那么线程二的加锁顺序也必须是A、B、C，否则可能出现死锁。

【强制】在使用阻塞等待获取锁的方式中，必须在try代码块之外，并且在加锁方法与try代码块之间没有任何可能抛出异常的方法调用，避免加锁成功后，在finally中无法解锁。 说明一：如果在lock方法与try代码块之间的方法调用抛出异常，那么无法解锁，造成其它线程无法成功获取锁。 说明二：如果lock方法在try代码块之内，可能由于其它方法抛出异常，导致在finally代码块中，unlock对未加锁的对象解锁，它会调用AQS的tryRelease方法（取决于具体实现类），抛出IllegalMonitorStateException异常。 说明三：在Lock对象的lock方法实现中可能抛出unchecked异常，产生的后果与说明二相同。 正例：

Lock lock = new XxxLock();
// ...
lock.lock();
try {
doSomething();
doOthers();
} finally {
lock.unlock();
} 反例：
Lock lock = new XxxLock();
try {
// 如果此处抛出异常，则直接执行finally代码块
doSomething();
// 无论加锁是否成功，finally代码块都会执行
lock.lock();
doOthers();
} finally {
lock.unlock();
}

【强制】在使用尝试机制来获取锁的方式中，进入业务代码块之前，必须先判断当前线程是否持有锁。锁的释放规则与锁的阻塞等待方式相同。 说明：Lock对象的unlock方法在执行时，它会调用AQS的tryRelease方法（取决于具体实现类），如果当前线程不持有锁，则抛出IllegalMonitorStateException异常。
正例：

Lock lock = new XxxLock();
// ...
boolean isLocked = lock.tryLock();
if (isLocked) {
try {
doSomething();
doOthers();
} finally {
lock.unlock();
}
}

【强制】并发修改同一记录时，避免更新丢失，需要加锁。要么在应用层加锁，要么在缓存加锁，要么在数据库层使用乐观锁，使用version作为更新依据。

说明：如果每次访问冲突概率小于20%，推荐使用乐观锁，否则使用悲观锁。乐观锁的重试次数不得小于3次。

【强制】对多个资源、数据库表、对象同时加锁时，需要保持一致的加锁顺序，否则可能会造成死锁。 说明：线程一需要对表A、B、C依次全部加锁后才可以进行更新操作，那么线程二的加锁顺序也必须是A、B、C，否则可能出现死锁。

【推荐】资金相关的金融敏感信息，使用悲观锁策略。
说明：乐观锁在获得锁的同时已经完成了更新操作，校验逻辑容易出现漏洞，另外，乐观锁对冲突的解决策略有较复杂的要求，处理不当容易造成系统压力或数据异常，所以资金相关的金融敏感信息不建议使用乐观锁更新。
正例：悲观锁遵循一锁二判三更新四释放的原则

【参考】volatile解决多线程内存不可见问题。对于一写多读，是可以解决变量同步问题，但是如果多写，同样无法解决线程安全问题。
说明：如果是count++操作，使用如下类实现：AtomicInteger count = new AtomicInteger(); count.addAndGet(1); 如果是JDK8，推荐使用LongAdder对象，比AtomicLong性能更好（减少乐观锁的重试次数）。

控制语句

【强制】==当switch括号内的变量类型为String并且此变量为外部参数时，必须先进行null判断。 ==
反例：如下的代码输出是什么？

public class SwitchString {
public static void main(String[] args) {
method(null);
}
public static void method(String param) {
switch (param) {
// 肯定不是进入这里
case "sth":
System.out.println("it's sth");
break;
// 也不是进入这里
case "null":
System.out.println("it's null");
break;
// 也不是进入这里
default:
System.out.println("default");
}
}
}

【强制】三目运算符condition? 表达式1 : 表达式2中，高度注意表达式1和2在类型对齐时，可能抛出因自动拆箱导致的NPE异常。 说明：以下两种场景会触发类型对齐的拆箱操作： 1） 表达式1或表达式2的值只要有一个是原始类型。 2） 表达式1或表达式2的值的类型不一致，会强制拆箱升级成表示范围更大的那个类型。

【强制】在高并发场景中，避免使用”等于”判断作为中断或退出的条件。 说明：如果并发控制没有处理好，容易产生等值判断被“击穿”的情况，使用大于或小于的区间判断条件来代替。

反例：判断剩余奖品数量等于0时，终止发放奖品，但因为并发处理错误导致奖品数量瞬间变成了负数，这样的话，活动无法终止。

注释规约

【强制】类、类属性、类方法的注释必须使用Javadoc规范，使用/*内容/格式，不得使用// xxx方式。 说明：在IDE编辑窗口中，Javadoc方式会提示相关注释，生成Javadoc可以正确输出相应注释；在IDE中，工程调用方法时，不进入方法即可悬浮提示方法、参数、返回值的意义，提高阅读效率。

【强制】所有的抽象方法（包括接口中的方法）必须要用Javadoc注释、除了返回值、参数、异常说明外，还必须指出该方法做什么事情，实现什么功能。 说明：对子类的实现要求，或者调用注意事项，请一并说明。

【强制】所有的类都必须添加创建者和创建日期。 说明：在设置模板时，注意IDEA的@author为${USER}，而eclipse的@author为${user}，大小写有区别，而日期的设置统一为yyyy/MM/dd的格式。

【强制】所有的枚举类型字段必须要有注释，说明每个数据项的用途。

【强制】在使用正则表达式时，利用好其预编译功能，可以有效加快正则匹配速度。 说明：不要在方法体内定义：Pattern pattern = Pattern.compile(“规则”);

【强制】避免用Apache Beanutils进行属性的copy。 说明：Apache BeanUtils性能较差，可以使用其他方案比如Spring BeanUtils, Cglib BeanCopier，注意均是浅拷贝。

设计规约

【强制】存储方案和底层数据结构的设计获得评审一致通过，并沉淀成为文档。 说明：有缺陷的底层数据结构容易导致系统风险上升，可扩展性下降，重构成本也会因历史数据迁移和系统平滑过渡而陡然增加，所以，存储方案和数据结构需要认真地进行设计和评审，生产环境提交执行后，需要进行double check。
正例：评审内容包括存储介质选型、表结构设计能否满足技术方案、存取性能和存储空间能否满足业务发展、表或字段之间的辩证关系、字段名称、字段类型、索引等；数据结构变更（如在原有表中新增字段）也需要进行评审通过后上线。

【强制】在需求分析阶段，如果与系统交互的User超过一类并且相关的User Case超过5个，使用用例图来表达更加清晰的结构化需求。

【强制】如果某个业务对象的状态超过3个，使用状态图来表达并且明确状态变化的各个触发条件。
说明：状态图的核心是对象状态，首先明确对象有多少种状态，然后明确两两状态之间是否存在直接转 换关系，再明确触发状态转换的条件是什么。
正例：淘宝订单状态有已下单、待付款、已付款、待发货、已发货、已收货等。比如已下单与已收货这两种状态之间是不可能有直接转换关系的。

【强制】如果系统中某个功能的调用链路上的涉及对象超过3个，使用时序图来表达并且明确各调用环节的输入与输出。
说明：时序图反映了一系列对象间的交互与协作关系，清晰立体地反映系统的调用纵深链路。

【强制】如果系统中模型类超过5个，并且存在复杂的依赖关系，使用类图来表达并且明确类之间的关系。
说明：类图像建筑领域的施工图，如果搭平房，可能不需要，但如果建造蚂蚁Z空间大楼，肯定需要详细的施工图。

【强制】如果系统中超过2个对象之间存在协作关系，并且需要表示复杂的处理流程，使用活动图来表示。
说明：活动图是流程图的扩展，增加了能够体现协作关系的对象泳道，支持表示并发等。

【推荐】需求分析与系统设计在考虑主干功能的同时，需要充分评估异常流程与业务边界。
反例：用户在淘宝付款过程中，银行扣款成功，发送给用户扣款成功短信，但是支付宝入款时由于断网演练产生异常，淘宝订单页面依然显示未付款，导致用户投诉。

【推荐】类在设计与实现时要符合单一原则。 说明：单一原则最易理解却是最难实现的一条规则，随着系统演进，很多时候，忘记了类设计的初衷。

【推荐】谨慎使用继承的方式来进行扩展，优先使用聚合/组合的方式来实现。 说明：不得已使用继承的话，必须符合里氏代换原则，此原则说父类能够出现的地方子类一定能够出现，比如，“把钱交出来”，钱的子类美元、欧元、人民币等都可以出现。

【推荐】系统设计阶段，共性业务或公共行为抽取出来公共模块、公共配置、公共类、公共方法等，在系统中不出现重复代码的情况。
说明：随着代码的重复次数不断增加，维护成本指数级上升。

【参考】可扩展性的本质是找到系统的变化点，并隔离变化点。
说明：世间众多设计模式其实就是一种设计模式即隔离变化点的模式。
正例：极致扩展性的标志，就是需求的新增，不会在原有代码交付物上进行任何形式的修改。

【参考】设计的本质就是识别和表达系统难点。
说明：识别和表达完全是两回事，很多人错误地认为识别到系统难点在哪里，表达只是自然而然的事情，但是大家在设计评审中经常出现语焉不详，甚至是词不达意的情况。
准确地表达系统难点需要具备如下能力： 表达规则和表达工具的熟练性。抽象思维和总结能力的局限性。基础知识体系的完备性。深入浅出的生动表达力。

【参考】代码即文档的观点是错误的，清晰的代码只是文档的某个片断，而不是全部。
说明：代码的深度调用，模块层面上的依赖关系网，业务场景逻辑，非功能性需求等问题是需要相应的文档来完整地呈现的。