阿里巴巴Java开发手册（华山派） - Java开发

《Java 开发手册》是阿里巴巴集团技术团队的集体智慧结晶和经验总结，经历了多次大规模一线实战的检验及不断完善，公开到业界后，众多社区开发者踊跃参与，共同打磨完善，系统化地整理成册。现代软件行业的高速发展对开发者的综合素质要求越来越高，因为不仅是编程知识点，其它维度的知识点也会影响到软件的最终交付质量。比如:数据库的表结构和索引设计缺陷可能带来软件上的架构缺陷或性能风险;工程结构混乱导致后续维护艰难;没有鉴权的漏洞代码易被黑客攻击等等。所以本手册以 Java 开发者为中心视角，划分为编程规约、异常日志、单元测试、安全规约、MySQL 数据库、工程结构、设计规约七个维度，再根据内容特征，细分成若干二级子目录。另外，依据约束力强弱及故障敏感性，规约依次分为强制、推荐、参考三大类。在延伸信息中，“说明”对规约做了适当扩展和解释；“正例”提倡什么样的编码和实现方式；“反例”说明需要提防的雷区，以及真实的错误案例。

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

《阿里巴巴Java开发手册（华山派）》

版本号：1.5.0
制定团队：阿里巴巴与 Java 社区开发者更新日期：2019.06.19
备注：华山版，新增 21 条，修改描述 112 处

本篇文章中只记录一些比较容易发生的错误，并非全部内容，推荐下载看完整版pdf或购买书籍。

GitHub：https://github.com/alibaba/p3c/

一、编程规约

(一) 命名风格

1、【强制】代码中的命名严禁使用拼音与英文混合的方式，更不允许直接使用中文的方式。

正例：renminbi / alibaba / taobao / youku / hangzhou 等国际通用的名称，可视同英文。
反例：DaZhePromotion [打折] / getPingfenByName() [评分] / int 某变量 = 3

说明：正确的英文拼写和语法可以让阅读者易于理解，避免歧义。注意，纯拼音命名方式更要避免采用。

2、【强制】类型与中括号紧挨相连来表示数组。

正例：定义整形数组 int[] arrayDemo。
反例：在 main 参数中，使用 String args[] 来定义。

3、【强制】POJO类中布尔类型的变量，都不要加is前缀，否则部分框架解析会引起序列化错误。

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

(二) 常量定义

1、【强制】不允许任何魔法值（即未经预先定义的常量）直接出现在代码中。

反例：

String key = "Id#taobao_" + tradeId;       
cache.put(key, value); 
// 缓存 get 时，由于在代码复制时，漏掉下划线，导致缓存击穿而出现问题

2、【强制】long或者Long初始赋值时，使用大写的L，不能是小写的l，小写容易跟数字1混淆，造成误解。

说明：Long a = 2l; 写的是数字的 21，还是 Long 型的 2?

3、【推荐】常量的复用层次有五层：跨应用共享常量、应用内共享常量、子工程内共享常量、包内共享常量、类内共享常量。

1）跨应用共享常量：放置在二方库中，通常是 client.jar 中的 constant 目录下。
2）应用内共享常量：放置在一方库中，通常是子模块中的 constant 目录下。

类A中：public static final String YES = "yes";
类B中：public static final String YES = "y";
A.YES.equals(B.YES) 预期是true，但实际返回为false，导致线上问题。
反例：易懂变量也要统一定义成应用内共享常量，两位攻城师在两个类中分别定义了表示“是”的变量：

3）子工程内部共享常量：即在当前子工程的constant目录下。
4）包内共享常量：即在当前包下单独的constant目录下。
5）类内共享常量：直接在类内部private static final定义。

(三) 代码格式

1、【强制】任何二目、三目运算符的左右两边都需要加一个空格。

说明：运算符包括赋值运算符=、逻辑运算符&&、加减乘除符号等。

2、【强制】采用4个空格缩进，禁止使用tab字符。

说明：如果使用tab缩进，必须设置1个tab为4个空格。IDEA设置tab为4个空格时，请勿勾选Use tab character；而在eclipse中，必须勾选insert spaces for tabs。

3、【强制】注释的双斜线与注释内容之间有且仅有一个空格。

正例：

// 这是示例注释，请注意在双斜线之后有一个空格
String ygb = new String();

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

(四) OOP规约

1、【强制】所有的覆写方法，必须加 @Override 注解。

说明：getObject() 与 get0bject() 的问题。一个是字母的 O，一个是数字的 0，加 @Override 可以准确判断是否覆盖成功。另外，如果在抽象类中对方法签名进行修改，其实现类会马上编译报错。

2、【强制】不能使用过时的类或方法。

说明：接口提供方既然明确是过时接口，那么有义务同时提供新的接口;作为调用方来说，有义务去考证过时方法的新实现是什么。

3、【强制】Object的equals方法容易抛空指针异常，应使用常量或确定有值的对象来调用 equals。

正例："test".equals(object);
反例：object.equals("test");

说明：推荐使用 java.util.Objects#equals(JDK7 引入的工具类)

4、【强制】浮点数之间的等值判断，基本数据类型不能用==来比较，包装数据类型不能用equals 来判断。

说明：浮点数采用“尾数+阶码”的编码方式，类似于科学计数法的“有效数字+指数”的表示方式。二进制无法精确表示大部分的十进制小数，具体原理参考[《码出高效》](https://detail.tmall.com/item.htm?spm=a1z10.3-b.w4011-16861154605.57.37a81b8bGVGoJD&id=575107529181&rn=f1294dc1e36859a5098c36756bafb4a0&abbucket=18。
反例:

float a = 1.0f - 0.9f;
float b = 0.9f - 0.8f;
if (a == b) {
    // 预期进入此代码快，执行其它业务逻辑 
    // 但事实上 a==b 的结果为 false
}

Float x = Float.valueOf(a); 
Float y = Float.valueOf(b);
if (x.equals(y)) {
    // 预期进入此代码快，执行其它业务逻辑 
    // 但事实上 equals 的结果为 false
}

正例:

(1) 指定一个误差范围，两个浮点数的差值在此范围之内，则认为是相等的。

float a = 1.0f - 0.9f; 
float b = 0.9f - 0.8f; 
float diff = 1e-6f;
if (Math.abs(a - b) < diff) { 
    System.out.println("true");
}

说明：e表示10的次方，1e-6 表示 10^(-6)，10的-6次方，1e-6(也就是0.000001)叫做epslon，用来抵消浮点运算中因为误差造成的相等无法判断的情况，它通常是一个非常小的数字，Math.abs(x)<1e-6 其实相当于 x == 0。用十进制举例精度误差，我们要算1/3+1/3+1/3==1（从数学上说，肯定相等），但是因为计算机精度问题，等号左边算出来是0.3333333+0.3333333+0.3333333=0.9999999，存在了误差，右边是1.0000000，那么如果直接用 == 返回 false，我们希望它被视作相等。那么就要两数相减取绝对值小于epslon的办法。

(2) 使用 BigDecimal 来定义值，再进行浮点数的运算操作。

BigDecimal a = new BigDecimal("1.0");
BigDecimal b = new BigDecimal("0.9"); 
BigDecimal c = new BigDecimal("0.8");
BigDecimal x = a.subtract(b); 
BigDecimal y = b.subtract(c);
if (x.equals(y)) {
    System.out.println("true");
}

5、【强制】为了防止精度损失，禁止使用构造方法 BigDecimal(double) 方式把 double 值转化为 BigDecimal 对象。

反例：BigDecimal g = new BigDecimal(0.1f); 实际的存储值为 0.10000000149
正例：优先推荐入参为 String 的构造方法，或使用 BigDecimal 的 valueOf 方法，此方法内部其实执行了 Double 的 toString，而 Double 的 toString 按 double 的实际能表达的精度对尾数进行了截断。

说明：BigDecimal(double) 存在精度损失风险，在精确计算或值比较的场景中可能会导致业务逻辑异常。

BigDecimal recommend1 = new BigDecimal("0.1");
BigDecimal recommend2 = BigDecimal.valueOf(0.1);

6、关于基本数据类型与包装数据类型的使用标准如下:

【强制】所有的 POJO 类属性必须使用包装数据类型。
【强制】RPC 方法的返回值和参数必须使用包装数据类型。
【推荐】所有的局部变量使用基本数据类型。

说明：POJO 类属性没有初值是提醒使用者在需要使用时，必须自己显式地进行赋值，任何 NPE（Null Pointer Exception）问题，或者入库检查，都由使用者来保证。

7、【强制】序列化类新增属性时，请不要修改 serialVersionUID 字段，避免反序列失败，如果完全不兼容升级，避免反序列化混乱，那么请修改 serialVersionUID 值。

说明：注意 serialVersionUID 不一致会抛出序列化运行时异常。

8、【强制】POJO 类必须写 toString 方法。使用 IDE 中的工具 source> generate toString 时，如果继承了另一个 POJO 类，注意在前面加一下 super.toString。

说明:在方法执行抛出异常时，可以直接调用 POJO 的 toString()方法打印其属性值，便于排查问题。

9、【强制】所有的相同类型的包装类对象之间值的比较，全部使用 equals 方法比较。

说明：对于 Integer var = ? 在 -128至127范围内的赋值，Integer 对象是在 IntegerCache.cache 产生，会复用已有对象，这个区间内的Integer值可以直接使用==进行判断，但是这个区间之外的所有数据，都会在堆上产生，并不会复用已有对象，这是一个大坑，推荐使用equals方法进行判断。

10、【强制】定义DO/DTO/VO等POJO类时，不要设定任何属性默认值。

反例：POJO 类的 gmtCreate 默认值为 new Date(); 但是这个属性在数据提取时并没有置入具体值，在更新其它字段时又附带更新了此字段，导致创建时间被修改成当前时间。

11、【推荐】setter方法中，参数名称与类成员变量名称一致，this.成员名 = 参数名。在getter/setter方法中，不要增加业务逻辑，增加排查问题的难度。

反例：

public Integer getData() {      
    if (condition) {  
        return this.data + 100;  
    } else { 
        return this.data - 100; 
    }  
}

12、【推荐】慎用 Object 的 clone 方法来拷贝对象。

说明：对象 clone 方法默认是浅拷贝，若想实现深拷贝需覆写 clone 方法实现域对象的深度遍历式拷贝。

(五) 集合处理

1、【强制】关于 hashCode 和 equals 的处理，遵循如下规则：

只要重写 equals，就必须重写 hashCode。
因为 Set 存储的是不重复的对象，依据 hashCode 和 equals 进行判断，所以 Set 存储的对象必须重写这两个方法。
如果自定义对象作为 Map 的键，那么必须重写 hashCode 和equals。

说明：String 重写了 hashCode 和 equals 方法，所以我们可以非常愉快地使用 String 对象作为 key 来使用。

2、【强制】ArrayList 的 subList 结果不可强转成 ArrayList，否则会抛出 ClassCastException 异常，即java.util.RandomAccessSubList cannot be cast to java.util.ArrayList.

说明：subLis 返回的是 ArrayList 的内部类 SubList，并不是 ArrayList ，而是 ArrayList 的一个视图，对于SubList 子列表的所有操作最终会反映到原列表上。

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

4、【强制】使用工具类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) 也会随之修改。

5、【强制】不要在 foreach 循环里进行元素的 remove/add 操作。remove 元素请使用 Iterator 方式，如果并发操作，需要对 Iterator 对象加锁。

正例：

Iterator<String> iterator = list.iterator();  
while (iterator.hasNext()) {          
    String item = iterator.next();                  
    if (删除元素的条件) {                   
        iterator.remove();                 
    }      
}

反例：

List<String> list = new ArrayList<String>();      
list.add("1");      
list.add("2");      
for (String item : list) {        
    if ("1".equals(item)) {          
        list.remove(item);         
    }   
}

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

6、【推荐】使用entrySet遍历Map类集合KV，而不是keySet方式进行遍历。

正例：values()返回的是 V 值集合，是一个 list 集合对象；keySet()返回的是 K 值集合，是一个 Set集合对象；entrySet() 返回的是 K-V 值组合集合。

说明：keySet 其实是遍历了 2 次，一次是转为 Iterator 对象，另一次是从 hashMap 中取出 key 所对应的 value。而 entrySet 只是遍历了一次就把 key 和 value 都放到了 entry 中，效率更高。如果是JDK8，使用 Map.forEach 方法。

7、【推荐】高度注意Map类集合K/V能不能存储null值的情况，如下表格：

集合类	Key	Value	Super	说明
`Hashtable`	不允许为null	不允许为null	`Dictionary`	线程安全
`ConcurrentHashMap`	不允许为null	不允许为null	`AbstractMap`	锁分段技术（JDK8:CAS）
`TreeMap`	不允许为null	允许为null	`AbstractMap`	线程不安全
`HashMap`	允许为null	允许为null	`AbstractMap`	线程不安全

反例：由于 HashMap 的干扰，很多人认为 ConcurrentHashMap 是可以置入 null 值，而事实上，存储 null 值时会抛出 NPE异常。

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

9、【强制】Collections 类返回的对象，如：emptyList()/singletonList() 等都是 immutablelist，不可对其进行添加或者删除元素的操作。

反例：如果查询无结果，返回 Collections.emptyList() 空集合对象，调用方一旦进行了添加元素的操作，就会触发 UnsupportedOperationException 异常。

10、【强制】使用集合转数组的方法，必须使用集合的 toArray(T[]array)，传入的是类型完全一致、长度为 0 的空数组。

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

List<String> list new ArrayList<>(2)
list.add("guan");
list.add("bao");
String[] array = list.toArray (new String[0]);

说明：使用 toArray 带参方法，数组空间大小的 length:

等于 0，动态创建与 size 相同的数组，性能最好。
大于 0 但小于 size，重新创建大小等于 size 的数组，增加 GC 负担
等于 size，在高并发情况下，数组创建完成之后，size 正在变大的情况下，负面影响与上相同。
大于 size，空间浪费，且在 size 处插入 null 值，存在 NPE 隐患。

（六) 并发处理

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

2、【强制】线程资源必须通过线程池提供，不允许在应用中自行显式创建线程。

说明：线程池的好处是减少在创建和销毁线程上所消耗的时间以及系统资源的开销，解决资源不足的问题。如果不使用线程池，有可能造成系统创建大量同类线程而导致消耗完内存或者“过度切换”的问题。

3、【强制】线程池不允许使用 Executors 去创建，而是通过 ThreadPoolExecutor 的方式，这样的处理方式让写的同学更加明确线程池的运行规则，规避资源耗尽的风险。

说明：Executors 返回的线程池对象的弊端如下：

FixedThreadPool 和 SingleThreadPool：允许的请求队列长度为 Integer.MAX_VALUE，可能会堆积大量的请求，从而导致OOM。
CachedThreadPool 和S cheduledThreadPool：允许的创建线程数量为I Integer.MAX_VALUE，可能会创建大量的线程，从而导致OOM。

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

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

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

6、【强制】多线程并行处理定时任务时，Timer 运行多个 TimeTask 时，只要其中之一没有捕获抛出的异常，其它任务便会自动终止运行，使用 ScheduledExecutorService 则没有这个问题。

7、【推荐】使用 CountDownLatch 进行异步转同步操作，每个线程退出前必须调用 countDown 方法，线程执行代码注意 catch 异常，确保 countDown 方法被执行到，避免主线程无法执行至 await 方法，直到超时才返回结果。

说明：注意，子线程抛出异常堆栈，不能在主线程try-catch到。

8、【推荐】避免 Random 实例被多线程使用，虽然共享该实例是线程安全的，但会因竞争同一 seed 导致的性能下降。

正例：在 JDK7 之后，可以直接使用API ThreadLocalRandom，而在 JDK7 之前，需要编码保证每个线程持有一个实例。

说明：Random 实例包括 java.util.Random 的实例或者 Math.random() 的方式。

9、【强制】在使用阻塞等待获取锁的方式中，必须在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(); 
}

10、【强制】在使用尝试机制来获取锁的方式中，进入业务代码块之前，必须先判断当前线程是否持有锁。锁的释放规则与锁的阻塞等待方式相同。

正例

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

说明：Lock 对象的 unlock 方法在执行时，它会调用 AQS 的 tryRelease 方法(取决于具体实现类)，如果当前线程不持有锁，则抛出 IllegalMonitorStateException 异常。

(七) 控制语句

1、【强制】当switch括号内的变量类型为String并且此变量为外部参数时，必须先进行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");
    }
}

public static void main(String[] args) {
    method(null);
}

2、【强制】在高并发场景中，避免使用”==”判断作为中断或退出的条件。

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

说明：如果并发控制没有处理好，容易产生等值判断被“击穿”的情况，使用大于或小于的区间判断条件来代替。

3、【推荐】表达异常的分支时，少用if-else方式，这种方式可以改写成：

if (condition) {              
    ...              
    return obj;    
}   
// 接着写else的业务逻辑代码;

(八) 其他

1、【强制】在使用正则表达式时，利用好其预编译功能，可以有效加快正则匹配速度。

说明：不要在方法体内定义 Pattern pattern = Pattern.compile(“规则”);

2、【强制】获取当前毫秒数 System.currentTimeMillis(); 而不是 new Date().getTime();

说明：如果想获取更加精确的纳秒级时间值，使用 System.nanoTime() 的方式。在 JDK8 中，针对统计时间等场景，推荐使用 Instant 类。

二、异常日志

(一) 异常处理

1、【强制】finally块必须对资源对象、流对象进行关闭，有异常也要做try-catch。

说明：如果 JDK7 及以上，可以使用 try-with-resources 方式。

2、【强制】在调用RPC、二方包、或动态生成类的相关方法时,捕捉异常必须使用 Throwable 类来进行拦截。

说明：通过反射机制来调用方法。如果找不到方法。抛出 NoSuchMethodException。什么情况会抛出 NoSuchMethodError 呢? 二方包在类冲突时，仲裁机制可能导致引入非预期的版本使类的方法签名不匹配，或者在字节码修改框架(比如:ASM)动态刨建或修改类时，修改了相应的方法签名。这些情况即使代码编译期是正确的，但在代码运行期时，会拋出 NoSuchMethodError。

3、【推荐】防止 NPE，是程序员的基本修养，注意 NPE 产生的场景，级联调用 obj.getA().getB().getC(); 一连串调用，易产生 NPE。

正例：使用 JDK8 的 Optional 类来防止 NPE 问题。

(二) 日志规约

1、【强制】应用中不可直接使用日志系统(Log4j、Logback)中的API，而应依赖使用日志框架 SLF4J 中的 API，使用门面模式的日志框架，有利于维护和各个类的日志处理方式统一。

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
private static final Logger logger = LoggerFactory.getLogger(Test.class);

2、【强制】所有日志文件至少保存15天，因为有些异常具备以“周”为频次发生的特点。网络运行状态、安全相关信息、系统监测、管理后台操作、用户敏感操作需要留存相关的网络日志不少于 6 个月。

3、【强制】应用中的扩展日志(如打点、临时监控、访问日志等)命名方式: appName_logType_logName.log。logType:日志类型，如 stats/monitor/access 等;logName:日志描述。这种命名的好处:通过文件名就可知道日志文件属于什么应用，什么类型，什么目的，也有利于归类查找。

说明：推荐对日志进行分类，如将错误日志和业务日志分开存放，便于开发人员查看，也便于通过日志对系统进行及时监控。

4、【强制】在日志输出时，字符串变量之间的拼接使用占位符的方式。

说明：因为 String 字符串的拼接会使用 StringBuilder 的 append() 方式，有一定的性能损耗。使用占位符仅是替换动作，可以有效提升性能。正例：logger.debug("Processing trade with id: {} and symbol: {}", id, symbol);

5、【强制】对于 trace/debug/info 级别的日志输出，必须进行日志级别的开关判断。

说明：虽然在 debug (参数)的方法体内第一行代码 isDisabled(Level.DEBUG_INT) 为真时(Slf4j 的常见实现 Log4j 和 Logback)，就直接 return，但是参数可能会进行字符串拼接运算。此外，如果 debug(getName())这种参数内有 getName() 方法调用，无谓浪费方法调用的开销。

正例:

// 如果判断为真，那么可以输出 trace 和 debug 级别的日志 
if (logger.isDebugEnabled()) {
    logger.debug("Current ID is: {} and name is: {}", id, getName());
}

6、【强制】避免重复打印日志，浪费磁盘空间，务必在 log4j.xml 中设置 additivity=false。

正例：<logger name="com.taobao.dubbo.config" additivity="false">

说明：additivity=false，则子 Logger 只会在自己的 appender 里输出，而不会将日志流反馈到 root 中。

三、单元测试

1. 【强制】好的单元测试必须遵守 AIR 原则。

说明：单元测试在线上运行时，感觉像空气(AIR)一样并不存在，但在测试质量的保障上，却是非常关键的。好的单元测试宏观上来说，具有自动化、独立性、可重复执行的特点。

A：Automatic(自动化)
I：Independent(独立性)
R：Repeatable(可重复)

2、【强制】单元测试应该是全自动执行的，并且非交互式的。测试用例通常是被定期执行的，执行过程必须完全自动化才有意义。输出结果需要人工检查的测试不是一个好的单元测试。单元测试中不准使用 System.out 来进行人肉验证，必须使用 assert 来验证。

3、【强制】保持单元测试的独立性。为了保证单元测试稳定可靠且便于维护，单元测试用例之间决不能互相调用，也不能依赖执行的先后次序。

反例：method2 需要依赖 method1 的执行，将执行结果作为 method2 的输入。

4、【推荐】编写单元测试代码遵守 BCDE 原则，以保证被测试模块的交付质量。

B：Border，边界值测试，包括循环边界、特殊取值、特殊时间点、数据顺序等。
C：orrect，正确的输入，并得到预期的结果。
D：Design，与设计文档相结合，来编写单元测试。
E：Error，强制错误信息输入(如:非法数据、异常流程、业务允许外等)，并得到预期的结果。

四、安全规约

1、【强制】隶属于用户个人的页面或者功能必须进行权限控制校验。

说明：防止没有做水平权限校验就可随意访问、修改、删除别人的数据，比如查看他人的私信内容、修改他人的订单。

2、【强制】用户敏感数据禁止直接展示，必须对展示数据进行脱敏。

说明:中国大陆个人手机号码显示为:137****0969，隐藏中间 4 位，防止隐私泄露。

3、【强制】用户输入的SQL参数严格使用参数绑定或者 METADATA 字段值限定，防止SQL注入，禁止字符串拼接 SQL 访问数据库。

4、【强制】在使用平台资源，譬如短信、邮件、电话、下单、支付，必须实现正确的防重放的机制，如数量限制、疲劳度控制、验证码校验，避免被滥刷而导致资损。说明:如注册时发送验证码到手机，如果没有限制次数和频率，那么可以利用此功能骚扰到其它用户，并造成短信平台资源浪费。

5、【推荐】发贴、评论、发送即时消息等用户生成内容的场景必须实现防刷、文本内容违禁词过滤等风控策略。

五、MySQL 数据库

(一) 建表规范

1、【强制】表达是与否概念的字段，必须使用is_xxx的方式命名，数据类型是unsigned tinyint（ 1表示是，0表示否）。

正例：表达逻辑删除的字段名 is_deleted，1 表示删除，0 表示未删除。

说明：任何字段如果为非负数，必须是 unsigned。

2、【强制】表名不使用复数名词。

说明：表名应该仅仅表示表里面的实体内容，不应该表示实体数量，对应于 DO 类名也是单数形式，符合表达习惯。

3、【强制】小数类型为 decimal，禁止使用 float 和 double。

说明：在存储的时候 float 和 double 都存在精度损失的问题，很可能在比较值的时候，得到不正确的结果。如果存储的数据范围超过 decimal 的范围，建议将数据拆成整数和小数并分开存储。

4、【强制】varchar是可变长字符串，不预先分配存储空间，长度不要超过5000，如果存储长度大于此值，定义字段类型为text，独立出来一张表，用主键来对应，避免影响其它字段索引效率。

5、【强制】表必备三字段：id, gmt_create, gmt_modified。

说明：其中 id 必为主键，类型为 unsigned bigint、单表时自增、步长为1。

6、【推荐】单表行数超过 500 万行或者单表容量超过 2GB，才推荐进行分库分表。

说明：如果预计三年后的数据量根本达不到这个级别，请不要在创建表时就分库分表。

7、【参考】合适的字符存储长度，不但节约数据库表空间、节约索引存储，更重要的是提升检索速度。

正例：如下表，其中无符号值可以避免误存负数，且扩大了表示范围。

对象	年龄区间	类型	字节
人	150岁之内	unsigned tinyint	1
龟	数百岁	unsigned smallint	2
恐龙化石	数千万岁	unsigned int	4
太阳	约50亿年	unsigned bigint	8

(二) 索引规约

1、【强制】超过三个表禁止join。需要join的字段，数据类型必须绝对一致；多表关联查询时，保证被关联的字段需要有索引。

说明：即使双表 join 也要注意表索引、SQL性能。

2、【强制】在varchar字段上建立索引时，必须指定索引长度，没必要对全字段建立索引，根据实际文本区分度决定索引长度即可。

说明：索引的长度与区分度是一对矛盾体，一般对字符串类型数据，长度为 20 的索引，区分度会高达 90% 以上，可以使用 count(distinct left(列名, 索引长度))/count(*) 的区分度来确定。

3、【强制】页面搜索严禁左模糊或者全模糊，如果需要请走搜索引擎来解决。

说明：索引文件具有 B-Tree 的最左前缀匹配特性，如果左边的值未确定，那么无法使用此索引。

4、【推荐】如果有 order by 的场景，请注意利用索引的有序性。order by 最后的字段是组合索引的一部分，并且放在索引组合顺序的最后，避免出现 file_sort 的情况，影响查询性能。

正例：where a=? and b=? order by c; 索引：a_b_c
反例：索引如果存在范围查询，那么索引有序性无法利用，如：WHERE a>10 ORDER BY b; 索引 a_b 无法排序。

5、【推荐】利用延迟关联或者子查询优化超多分页场景。

正例：先快速定位需要获取的 id 段，然后再关联：

SELECT a.* FROM 表1 a, (select id from 表1 where 条件 LIMIT 100000,20) b where a.id=b.id

说明：MySQL 并不是跳过 offset 行，而是取 offset+N 行，然后返回放弃前 offset 行，返回 N 行，那当 offset 特别大的时候，效率就非常的低下，要么控制返回的总页数，要么对超过特定阈值的页数进行SQL改写。

6、【推荐】SQL性能优化的目标：至少要达到 range 级别，要求是ref级别，如果可以是consts最好。

反例：explain 表的结果 type=index，索引物理文件全扫描，速度非常慢，这个 index 级别比较 range 还低，与全表扫描是小巫见大巫。

说明：

1）consts 单表中最多只有一个匹配行（主键或者唯一索引）在优化阶段即可读取到数据。
2）ref 指的是使用普通的索引（normal index）。
3）range 对索引进行范围检索。

7、【推荐】建组合索引的时候，区分度最高的在最左边。

正例：如果 where a=? and b=?，如果 a 列的几乎接近于唯一值，那么只需要单建 idx_a 索引即可。

说明：存在非等号和等号混合时，在建索引时，请把等号条件的列前置。如：where c>? and d=? 那么即使 c的区分度更高，也必须把 d 放在索引的最前列，即索引 idx_d_c。

(三) SQL语句

1、【强制】不要使用count(列名)或count(常量)来替代count()，count()是SQL92定义的标准统计行数的语法，跟数据库无关，跟 NULL 和非 NULL 无关。

说明：count(*) 会统计值为 NULL 的行，而 count(列名)不会统计此列为 NULL 值的行。

2、【强制】count(distinct col) 计算该列除 NULL 之外的不重复行数，注意 count(distinct col1, col2) 如果其中一列全为 NULL，那么即使另一列有不同的值，也返回为 0。

3、【强制】当某一列的值全是NULL时，count(col)的返回结果为0，但sum(col)的返回结果为 NULL，因此使用 sum()时需注意 NPE 问题。

正例：使用如下方式来避免 sum 的 NPE 问题

SELECT IFNULL(SUM(column), 0) FROM table;

4、【强制】使用 ISNULL() 来判断是否为NULL值。

说明：NULL 与任何值的直接比较都为 NULL。

NULL <> NULL 的返回结果是 NULL，而不是 false。
NULL = NULL 的返回结果是 NULL，而不是 true。
NULL <> 1 的返回结果是 NULL，而不是 true。

5、【强制】不得使用外键与级联，一切外键概念必须在应用层解决。

说明：以学生和成绩的关系为例，学生表中的 student_id 是主键，那么成绩表中的 student_id 则为外键。如果更新学生表中的 student_id，同时触发成绩表中的 student_id 更新，即为级联更新。外键与级联更新适用于单机低并发，不适合分布式、高并发集群；级联更新是强阻塞，存在数据库更新风暴的风险;外键影响数据库的插入速度。

6、【强制】禁止使用存储过程，存储过程难以调试和扩展，更没有移植性

7、【强制】数据订正(特别是删除、修改记录操作)时，要先select，避免出现误删除，确认无误才能执行更新语句。

8、【推荐】in 操作能避免则避免，若实在避免不了，需要仔细评估in后边的集合元素数量，控制在 1000 个之内。

9、【参考】如果有全球化需要，所有的字符存储与表示，均以utf-8编码，注意字符统计函数的区别。

说明：

SELECT LENGTH("轻松工作")； 返回为12
SELECT CHARACTER_LENGTH("轻松工作")； 返回为4

如果需要存储表情，那么选择 utf8mb4 来进行存储，注意它与 utf-8 编码的区别。

10、【参考】TRUNCATE TABLE 比 DELETE 速度快，且使用的系统和事务日志资源少，但 TRUNCATE 无事务且不触发 trigger，有可能造成事故，故不建议在开发代码中使用此语句。

说明：TRUNCATE TABLE 在功能上与不带 WHERE 子句的 DELETE 语句相同。

(四) ORM映射

1、【强制】sql.xml 配置参数使用：#{}，#param# 不要使用${} 此种方式容易出现 SQL 注入。

2、【强制】不允许直接拿HashMap与Hashtable作为查询结果集的输出。

说明：resultClass="Hashtable"，会置入字段名和属性值，但是值的类型不可控。

3、【推荐】不要写一个大而全的数据更新接口。传入为POJO类。

说明：不管是不是自己的目标更新字段，都进行 update table set c1=value1,c2=value2,c3=value3;这是不对的。执行 SQL 时，不要更新无改动的字段，一是易出错；二是效率低；三是增加 binlog 存储。

六、工程结构

(一) 应用分层

1、【参考】分层领域模型规约

DO（Data Object）：与数据库表结构一一对应，通过 DAO 层向上传输数据源对象。
DTO（Data Transfer Object）：数据传输对象，Service 或 Manager 向外传输的对象。
BO（Business Object）：业务对象。由 Service 层输出的封装业务逻辑的对象。
AO（Application Object）：应用对象。在 Web 层与 Service 层之间抽象的复用对象模型，极为贴近展示层，复用度不高。
VO（View Object）：显示层对象，通常是 Web 向模板渲染引擎层传输的对象。
Query：数据查询对象，各层接收上层的查询请求。注意超过 2 个参数的查询封装，禁止使用 Map 类来传输。

(二) 二方库依赖

1、【强制】定义GAV遵从以下规则：

GroupID格式：com.{公司/BU }.业务线.[子业务线]，最多4级。
ArtifactID格式：产品线名-模块名。语义不重复不遗漏，先到中央仓库去查证一下。
Version：详细规定参考下方。

2、【强制】二方库版本号命名方式：主版本号.次版本号.修订号

1）主版本号：产品方向改变，或者大规模API不兼容，或者架构不兼容升级。
2）次版本号：保持相对兼容性，增加主要功能特性，影响范围极小的API不兼容修改。
3）修订号：保持完全兼容性，修复BUG、新增次要功能特性等。

说明：注意起始版本号必须为：1.0.0，而不是 0.0.1 正式发布的类库必须先去中央仓库进行查证，使版本号有延续性，正式版本号不允许覆盖升级。

3、【强制】禁止在子项目的 pom 依赖中出现相同的 GroupId，相同的 ArtifactId，但是不同的 Version。

说明：在本地调试时会使用各子项目指定的版本号，但是合并成一个 war，只能有一个版本号出现在最后的lib目录中。可能出现线下调试是正确的，发布到线上却出故障的问题。

(三) 服务器

1、【推荐】高并发服务器建议调小 TCP 协议的 time_wait 超时时间。

正例：在 linux 服务器上请通过变更 /etc/sysctl.conf 文件去修改该缺省值(秒)：net.ipv4.tcp_fin_timeout = 30

说明：操作系统默认 240 秒后，才会关闭处于 time_wait 状态的连接，在高并发访问下，服务器端会因为处于 time_wait 的连接数太多，可能无法建立新的连接，所以需要在服务器上调小此等待值。

2、【推荐】调大服务器所支持的最大文件句柄数(FileDescriptor，简写为fd)。

说明：主流操作系统的设计是将 TCP/UDP 连接采用与文件一样的方式去管理，即一个连接对应于一个 fd。主流的 linux 服务器默认所支持最大 fd 数量为 1024，当并发连接数很大时很容易因为 fd 不足而出现 “open too many files” 错误，导致新的连接无法建立。建议将 linux 服务器所支持的最大句柄数调高数倍(与服务器的内存数量相关)。

3、【推荐】给 JVM 环境参数设置-XX:+HeapDumpOnOutOfMemoryError 参数，让 JVM 碰到OOM 场景时输出 dump 信息。

说明：OOM 的发生是有概率的，甚至相隔数月才出现一例，出错时的堆内信息对解决问题非常有帮助。

4、【推荐】在线上生产环境，JVM 的 Xms 和 Xmx 设置一样大小的内存容量，避免在 GC 后调整堆大小带来的压力。

七、设计规约

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

2、【强制】如果某个业务对象的状态超过 3 个，使用状态图来表达并且明确状态变化的各个触发条件。

正例：淘宝订单状态有已下单、待付款、已付款、待发货、已发货、已收货等。比如已下单与已收货这两种状态之间是不可能有直接转换关系的。

说明：状态图的核心是对象状态，首先明确对象有多少种状态，然后明确两两状态之间是否存在直接转换关系，再明确触发状态转换的条件是什么。

3、【强制】如果系统中某个功能的调用链路上的涉及对象超过 3 个，使用时序图来表达并且明确各调用环节的输入与输出。

说明：时序图反映了一系列对象间的交互与协作关系，清晰立体地反映系统的调用纵深链路。

4、【强制】如果系统中模型类超过 5 个，并且存在复杂的依赖关系，使用类图来表达并且明确类之间的关系。

说明：类图像建筑领域的施工图，如果搭平房，可能不需要，但如果建造蚂蚁 Z 空间大楼，肯定需要详细的施工图。

5、【强制】如果系统中超过 2 个对象之间存在协作关系，并且需要表示复杂的处理流程，使用活动图来表示。

说明：活动图是流程图的扩展，增加了能够体现协作关系的对象泳道，支持表示并发等。

未经允许请勿转载：程序喵 » 阿里巴巴Java开发手册（华山派）