1.概要

此文档来自阿里巴巴的规范手册（华山版）

规范解读

https://www.bilibili.com/video/BV1FV411W7a6?p=73&spm_id_from=pageDriver

2. 编程规约

2.1 命名风格

• 【强制】代码中的命名均不能以下划线或美元符号开始，也不能以下划线或美元符号结束。
  反例：name / __name / $name / name / name$ / name__

• 【强制】代码中的命名严禁使用拼音与英文混合的方式，更不允许直接使用中文的方式。
  说明：正确的英文拼写和语法可以让阅读者易于理解，避免歧义。注意，纯拼音命名方式更要避免采用。
  正例：renminbi / alibaba / taobao / youku / hangzhou 等国际通用的名称，可视同英文。
  反例：DaZhePromotion [打折] / getPingfenByName() [评分] / int 某变量 = 3

• 【强制】包名统一使用小写，点分隔符之间有且仅有一个自然语义的英语单词。包名统一使
  用单数形式，但是类名如果有复数含义，类名可以使用复数形式。
  正例：应用工具类包名为 com.alibaba.ai.util、类名为 MessageUtils（此规则参考 spring 的框架结构）

• 【强制】类名使用 UpperCamelCase 风格，但以下情形例外：DO / BO / DTO / VO / AO
  / PO / UID 等。
  正例：JavaServerlessPlatform / UserDO / XmlService / TcpUdpDeal / TaPromotion
  反例：javaserverlessplatform / UserDo / XMLService / TCPUDPDeal / TAPromotion

• 【强制】方法名、参数名、成员变量、局部变量都统一使用 lowerCamelCase 风格，必须遵
  从驼峰形式。

正例： localValue / getHttpMessage() / inputUserId

• 【强制】常量命名全部大写，单词间用下划线隔开，力求语义表达完整清楚，不要嫌名字
  长。
  正例：MAX_STOCK_COUNT / CACHE_EXPIRED_TIME
  反例：MAX_COUNT / EXPIRED_TIME ，语义不明确

• 【强制】抽象类命名使用 Abstract 或 Base 开头；异常类命名使用 Exception 结尾；测试类
  命名以它要测试的类的名称开始，以 Test 结尾

• 【强制】类型与中括号紧挨相连来表示数组。
  正例：定义整形数组 int[] arrayDemo;
  反例：在 main 参数中，使用 String args[]来定义。

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

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

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

@Data
public class Demo {

    private boolean deleted;

    public static void main(String[] args) {
        Demo demo=new Demo();
        demo.setDeleted(true);
        System.err.println(JSONObject.toJSONString(demo));
    }
}

• 【强制】避免在子父类的成员变量之间、或者不同代码块的局部变量之间采用完全相同的命
  名，使可读性降低。
  说明：子类、父类成员变量名相同，即使是 public 类型的变量也是能够通过编译，而局部变量在同一方法
  内的不同代码块中同名也是合法的，但是要避免使用。对于非 setter/getter 的参数名称也要避免与成员
  变量名称相同。

反例：

package com.example.demo;

public class ConfusingName {
    public int age;

    private boolean condition=false;
    // 非 setter/getter 的参数名称，不允许与本类成员变量同名
    public void getData(String alibaba) {
        if(condition) {
            final int money = 531;
            // ...
        }
        for (int i = 0; i < 10; i++) {
            // 在同一方法体中，不允许与其它代码块中的 money 命名相同
            final int money = 615;
            // ...
        }
    }
}
class Son extends ConfusingName {
    // 不允许与父类的成员变量名称相同
    public int age;
}

• 【强制】杜绝完全不规范的缩写，避免望文不知义。
  反例：AbstractClass“缩写”命名成 AbsClass；condition“缩写”命名成 condi，此类随意缩写严重
  降低了代码的可阅读性。

• 【推荐】为了达到代码自解释的目标，任何自定义编程元素在命名时，使用尽量完整的单词
  组合来表达其意。
  正例：在 JDK 中，表达原子更新的类名为：AtomicReferenceFieldUpdater。
  反例：int a 的随意命名方式。

• 【推荐】在常量与变量的命名时，表示类型的名词放在词尾，以提升辨识度。
  正例：startTime / workQueue / nameList / TERMINATED_THREAD_COUNT
  反例：startedAt / QueueOfWork / listName / COUNT_TERMINATED_THREAD

• 【推荐】如果模块、接口、类、方法使用了设计模式，在命名时需体现出具体模式。
  说明：将设计模式体现在名字中，有利于阅读者快速理解架构设计理念。

//工厂类
public class OrderFactory;
//代理类
public class LoginProxy;
//观察者
public class ResourceObserver;

• 【推荐】接口类中的方法和属性不要加任何修饰符号（public 也不要加），保持代码的简洁
  性，并加上有效的 Javadoc 注释。尽量不要在接口里定义变量，如果一定要定义变量，肯定
  是与接口方法相关，并且是整个应用的基础常量。
  正例：接口方法签名 void commit();
  接口基础常量 String COMPANY = “alibaba”;
  反例：接口方法定义 public abstract void f();
  说明：JDK8 中接口允许有默认实现，那么这个 default 方法，是对所有实现类都有价值的默认实现。

• 接口和实现类的命名有两套规则：
  1）【强制】对于 Service 和 DAO 类，基于 SOA 的理念，暴露出来的服务一定是接口，内部的实现类用
  Impl 的后缀与接口区别。
  正例：CacheServiceImpl 实现 CacheService 接口。
  2） 【推荐】如果是形容能力的接口名称，取对应的形容词为接口名（通常是–able 的形容词）。
  正例：AbstractTranslator 实现 Translatable 接口。

• 【参考】枚举类名带上 Enum 后缀，枚举成员名称需要全大写，单词间用下划线隔开。
  说明：枚举其实就是特殊的类，域成员均为常量，且构造方法被默认强制是私有。
  正例：枚举名字为 ProcessStatusEnum 的成员名称：SUCCESS / UNKNOWN_REASON。

• 各层代码命名规约

A) Service/DAO 层方法命名规约
1） 获取单个对象的方法用 get 做前缀。
2） 获取多个对象的方法用 get 做前缀，复数形式结尾如：getObjects。
3） 获取统计值的方法用 count 做前缀。
4） 插入的方法用 save/insert 做前缀。
5） 删除的方法用 remove/delete 做前缀。
6） 修改的方法用 update 做前缀。
B) 领域模型命名规约
1） 数据对象：xxx，xxx 即为数据表名驼峰写法，比如BpmTask。
2） 数据传输对象：xxxDTO，xxx 为业务领域相关的名称。
3） 展示对象：xxxVO，xxx 一般为网页名称。
4） POJO 是 DO/DTO/BO/VO 的统称，禁止命名成 xxxPOJO。

2.2 .常量定义

【强制】不允许任何魔法值（即未经预先定义的常量）直接出现在代码中。主要是防止在多个地方使用的时候，拷贝的不一致导致问题，如果需要在多个类中共享，可以专门定义一个常量类。
反例：String key = “Id#taobao_” + tradeId;
cache.put(key, value);
// 缓存 get 时，由于在代码复制时，漏掉下划线，导致缓存击穿而出现问题，
【强制】在 long 或者 Long 赋值时，数值后使用大写的 L，不能是小写的 l，小写容易跟数
字 1 混淆，造成误解。
说明：Long a = 2l; 写的是数字的 21，还是 Long 型的 2。

【推荐】不要使用一个常量类维护所有常量，要按常量功能进行归类，分开维护。
说明：大而全的常量类，杂乱无章，使用查找功能才能定位到修改的常量，不利于理解和维护。
正例：缓存相关常量放在类 CacheConsts 下；系统配置相关常量放在类 ConfigConsts 下。

【推荐】常量的复用层次有五层：跨应用共享常量、应用内共享常量、子工程内共享常量、
包内共享常量、类内共享常量。
1） 跨应用共享常量：放置在二方库中，通常是 client.jar 中的 constant 目录下。
2） 应用内共享常量：放置在一方库中，通常是子模块中的 constant 目录下。
反例：易懂变量也要统一定义成应用内共享常量，两位工程师在两个类中分别定义了“YES”的变量：
类 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 定义。

【推荐】如果变量值仅在一个固定范围内变化用 enum 类型来定义。
说明：如果存在名称之外的延伸属性应使用 enum 类型，下面正例中的数字就是延伸信息，表示一年中的
第几个季节。
正例：

public enum SeasonEnum {
 SPRING(1), SUMMER(2), AUTUMN(3), WINTER(4);
 private int seq;
 SeasonEnum(int seq) {
 this.seq = seq;
 }
 public int getSeq() {
 return seq;
 }
}

2.3 代码格式

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

【强制】左小括号和字符之间不出现空格；同样，右小括号和字符之间也不出现空格；而左
大括号前需要空格。详见第 5 条下方正例提示。
反例：if (空格 a == b 空格)

【强制】if/for/while/switch/do 等保留字与括号之间都必须加空格。

【强制】任何二目、三目运算符的左右两边都需要加一个空格。
说明：运算符包括赋值运算符=、逻辑运算符&&、加减乘除符号等。

【强制】采用 4 个空格缩进，禁止使用 tab 字符。
说明：如果使用 tab 缩进，必须设置 1 个 tab 为 4 个空格。IDEA 设置 tab 为 4 个空格时，请勿勾选 Use
tab character；而在 eclipse 中，必须勾选 insert spaces for tabs。
正例： （涉及 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");
        // 在右大括号后直接结束，则必须换行
    }
}

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

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

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

long first = 1000000000000L;
int second = (int)first + 2;

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

正例

StringBuilder sb = new StringBuilder();
// 超过 120 个字符的情况下，换行缩进 4 个空格，点号和方法名称一起换行
sb.append("Jack").append("Ma")
    .append("alibaba")
    .append("alibaba")
    .append("alibaba");

反例：

StringBuilder sb = new StringBuilder();
    // 超过 120 个字符的情况下，不要在括号前换行
    sb.append("Jack").append("Ma").append
    ("alibaba");
    // 参数很多的方法调用可能超过 120 个字符，不要在逗号前换行
    method(args1, args2, args3, ...
    , argsX); 

.【推荐】单个方法的总行数不超过 80 行。
说明：除注释之外的方法签名、左右大括号、方法内代码、空行、回车及任何不可见字符的总行数不超过
80 行。
正例：代码逻辑分清红花和绿叶，个性和共性，绿叶逻辑单独出来成为额外方法，使主干代码更加清晰；
共性逻辑抽取成为共性方法，便于复用和维护。

【推荐】没有必要增加若干空格来使变量的赋值等号与上一行对应位置的等号对齐。
正例：

int one = 1;
long two = 2L;
float three = 3F;
StringBuilder sb = new StringBuilder();

说明：增加 sb 这个变量，如果需要对齐，则给 one、two、three 都要增加几个空格，在变量比较多的情
况下，是非常累赘的事情。

【推荐】不同逻辑、不同语义、不同业务的代码之间插入一个空行分隔开来以提升可读性。
说明：任何情形，没有必要插入多个空行进行隔开。

2.4 OOP规约

• 【强制】避免通过一个类的对象引用访问此类的静态变量或静态方法，无谓增加编译器解析
  成本，直接用类名来访问即可。

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

• 【强制】相同参数类型，相同业务含义，才可以使用 Java 的可变参数，避免使用 Object。
  说明：可变参数必须放置在参数列表的最后。（提倡同学们尽量不用可变参数编程）
  正例：

  public List<User> listUsers(String type, Long... ids) {...}

• 【强制】外部正在调用或者二方库依赖的接口，不允许修改方法签名，避免对接口调用方产
  生影响。接口过时必须加@Deprecated 注解，并清晰地说明采用的新接口或者新服务是什
  么。

• 【强制】不能使用过时的类或方法。
  说明：java.net.URLDecoder 中的方法 decode(String encodeStr) 这个方法已经过时，应该使用双参数
  decode(String source, String encode)。接口提供方既然明确是过时接口，那么有义务同时提供新的接
  口；作为调用方来说，有义务去考证过时方法的新实现是什么。

【强制】Object 的 equals 方法容易抛空指针异常，应使用常量或确定有值的对象来调用
equals。
正例：”test”.equals(object);
反例：object.equals(“test”);
说明：推荐使用 java.util.Objects#equals（JDK7 引入的工具类）。

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

• 【强制】浮点数之间的等值判断，基本数据类型不能用==来比较，包装数据类型不能用
  equals 来判断。
  说明：浮点数采用“尾数+阶码”的编码方式，类似于科学计数法的“有效数字+指数”的表示方式。二进制无法精确表示大部分的十进制小数.

反例：

 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
 } 

正例：

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

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");
 }

• 使用 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");
 }

• 【强制】定义数据对象类时，属性类型要与数据库字段类型相匹配。

正例：数据库字段的 bigint 必须与类属性的 Long 类型相对应。
反例：某个案例的数据库表 id 字段定义类型 bigint unsigned，实际类对象属性为 Integer，随着 id 越来
越大，超过 Integer 的表示范围而溢出成为负数。

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

说明：BigDecimal(double)存在精度损失风险，在精确计算或值比较的场景中可能会导致业务逻辑异常。
如：BigDecimal g = new BigDecimal(0.1f); 实际的存储值为：0.10000000149
正例：优先推荐入参为 String 的构造方法，或使用 BigDecimal 的 valueOf 方法，此方法内部其实执行了
Double 的 toString，而 Double 的 toString 按 double 的实际能表达的精度对尾数进行了截断。

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

• 关于基本数据类型与包装数据类型的使用标准如下：
  1） 【强制】所有的 POJO 类属性必须使用包装数据类型。
  2） 【强制】RPC 方法的返回值和参数必须使用包装数据类型。
  3） 【推荐】所有的局部变量使用基本数据类型。
  说明：POJO 类属性没有初值是提醒使用者在需要使用时，必须自己显式地进行赋值，任何 NPE 问题，或
  者入库检查，都由使用者来保证。
  正例：数据库的查询结果可能是 null，因为自动拆箱，用基本数据类型接收有 NPE 风险。
  反例：比如显示成交总额涨跌情况，即正负 x%，x 为基本数据类型，调用的 RPC 服务，调用不成功时，
  返回的是默认值，页面显示为 0%，这是不合理的，应该显示成中划线。所以包装数据类型的 null 值，能
  够表示额外的信息，如：远程调用失败，异常退出。

• 【强制】定义 实体/DTO/VO 等 POJO 类时，不要设定任何属性默认值。
  反例：POJO 类的 createTime 默认值为 new Date()，但是这个属性在数据提取时并没有置入具体值，在
  更新其它字段时又附带更新了此字段，导致创建时间被修改成当前时间。

• 【强制】序列化类新增属性时，请不要修改 serialVersionUID 字段，避免反序列失败；如果
  完全不兼容升级，避免反序列化混乱，那么请修改 serialVersionUID 值。
  说明：注意 serialVersionUID 不一致会抛出序列化运行时异常
  参考链接：
  https://www.cnblogs.com/duanxz/p/3511695.html

• 【强制】构造方法里面禁止加入任何业务逻辑，如果有初始化逻辑，请放在 init 方法中。

• 【强制】POJO 类必须写 toString 方法。使用 IDE 中的工具：source> generate toString
  时，如果继承了另一个 POJO 类，注意在前面加一下 super.toString。
  说明：在方法执行抛出异常时，可以直接调用 POJO 的 toString()方法打印其属性值，便于排查问题。

• 【强制】禁止在 POJO 类中，同时存在对应属性 xxx 的 isXxx()和 getXxx()方法。
  说明：框架在调用属性 xxx 的提取方法时，并不能确定哪个方法一定是被优先调用到。

• 【推荐】使用索引访问用 String 的 split 方法得到的数组时，需做最后一个分隔符后有无内
  容的检查，否则会有抛 IndexOutOfBoundsException 的风险。
  说明：

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

• 【推荐】当一个类有多个构造方法，或者多个同名方法，这些方法应该按顺序放置在一起，
  便于阅读，此条规则优先于下一条。

• 【推荐】 类内方法定义的顺序依次是：公有方法或保护方法 > 私有方法 > getter / setter
  方法。
  说明：公有方法是类的调用者和维护者最关心的方法，首屏展示最好；保护方法虽然只是子类关心，也可能是“模板设计模式”下的核心方法；而私有方法外部一般不需要特别关心，是一个黑盒实现；因为承载
  的信息价值较低，所有 Service 和 DAO 的 getter/setter 方法放在类体最后。

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

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

• 【推荐】循环体内，字符串的连接方式，使用 StringBuilder 的 append 方法进行扩展。
  说明：下例中，反编译出的字节码文件显示每次循环都会 new 出一个 StringBuilder 对象，然后进行
  append 操作，最后通过 toString 方法返回 String 对象，造成内存资源浪费。
  反例：

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

• 【推荐】final 可以声明类、成员变量、方法、以及本地变量，下列情况使用 final 关键字：
  1） 不允许被继承的类，如：String 类。
  2） 不允许修改引用的域对象。
  3） 不允许被覆写的方法，如：POJO 类的 setter 方法。
  4） 不允许运行过程中重新赋值的局部变量。
  5） 避免上下文重复使用一个变量，使用 final 可以强制重新定义一个变量，方便更好地进行重构

• 【推荐】慎用 Object 的 clone 方法来拷贝对象。
  说明：对象 clone 方法默认是浅拷贝，若想实现深拷贝需覆写 clone 方法实现域对象的深度遍历式拷贝。

• 【推荐】类成员与方法访问控制从严：
  1） 如果不允许外部直接通过 new 来创建对象，那么构造方法必须是 private。
  2） 工具类不允许有 public 或 default 构造方法。
  3） 类非 static 成员变量并且与子类共享，必须是 protected。
  4） 类非 static 成员变量并且仅在本类使用，必须是 private。
  5） 类 static 成员变量如果仅在本类使用，必须是 private。
  6） 若是 static 成员变量，考虑是否为 final。
  7） 类成员方法只供类内部调用，必须是 private。
  8） 类成员方法只对继承类公开，那么限制为 protected。

说明：任何类、方法、参数、变量，严控访问范围。过于宽泛的访问范围，不利于模块解耦。思考：如果是一个 private 的方法，想删除就删除，可是一个 public 的 service 成员方法或成员变量，删除一下，不
得手心冒点汗吗？变量像自己的小孩，尽量在自己的视线内，变量作用域太大，无限制的到处跑，那么你
会担心的。

2.5 集合处理

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

• 【强制】ArrayList 的 subList 结果不可强转成 ArrayList，否则会抛出 ClassCastException 异
  常，即 java.util.RandomAccessSubList cannot be cast to java.util.ArrayList。
  说明：subList 返回的是 ArrayList 的内部类 SubList，并不是 ArrayList 而是 ArrayList 的一个视图，对
  于 SubList 子列表的所有操作最终会反映到原列表上。

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

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

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

-【强制】使用集合转数组的方法，必须使用集合的 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：
1） 等于 0，动态创建与 size 相同的数组，性能最好。
2） 大于 0 但小于 size，重新创建大小等于 size 的数组，增加 GC 负担。
3） 等于 size，在高并发情况下，数组创建完成之后，size 正在变大的情况下，负面影响与上相同。
4） 大于 size，空间浪费，且在 size 处插入 null 值，存在 NPE 隐患。

• 【强制】在使用 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);

• 【强制】泛型通配符<? extends T>来接收返回的数据，此写法的泛型集合不能使用 add 方
  法，而<? super T>不能使用 get 方法，作为接口调用赋值时易出错。
  说明：扩展说一下 PECS(Producer Extends Consumer Super)原则：第一、频繁往外读取内容的，适合
  用<? extends T>。第二、经常往里插入的，适合用<? super T>
  第一种情况：list.add(“yangguanbao”); 运行时异常。
  第二种情况：str[0] = “changed”; 也会随之修改，反之亦然。

• 【强制】在无泛型限制定义的集合赋值给泛型限制的集合时，在使用集合元素时，需要进行
  instanceof 判断，避免抛出 ClassCastException 异常。
  说明：毕竟泛型是在 JDK5 后才出现，考虑到向前兼容，编译器是允许非泛型集合与泛型集合互相赋值。

反例：

List<String> generics = null;
List notGenerics = new ArrayList(10);
notGenerics.add(new Object());
notGenerics.add(new Integer(1));
generics = notGenerics;
// 此处抛出 ClassCastException 异常
String string = generics.get(0);

• 【强制】不要在 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);
    }
}

• 【强制】在 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;
    }
};

• 【推荐】集合泛型定义时，在 JDK7 及以上，使用 diamond 语法或全省略。
  说明：菱形泛型，即 diamond，直接使用<>来指代前边已经指定的类型。

正例：

// diamond 方式，即<>
HashMap<String, String> userCache = new HashMap<>(16);
// 全省略方式
ArrayList<User> users = new ArrayList(10);

• 【推荐】集合初始化时，指定集合初始值大小。
  说明：HashMap 使用 HashMap(int initialCapacity) 初始化。
  正例：initialCapacity = (需要存储的元素个数 / 负载因子) + 1。注意负载因子（即 loader factor）默认
  为 0.75，如果暂时无法确定初始值大小，请设置为 16（即默认值）。
  反例：HashMap 需要放置 1024 个元素，由于没有设置容量初始大小，随着元素不断增加，容量 7 次被
  迫扩大，resize 需要重建 hash 表，严重影响性能。

• 【推荐】使用 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 值组合集

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

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

• 【参考】合理利用好集合的有序性(sort)和稳定性(order)，避免集合的无序性(unsort)和不稳
  定性(unorder)带来的负面影响。

说明：有序性是指遍历的结果是按某种比较规则依次排列的。稳定性指集合每次遍历的元素次序是一定
的。如：ArrayList 是 order/unsort；HashMap 是 unorder/unsort；TreeSet 是 order/sort。

• 【参考】利用 Set 元素唯一的特性，可以快速对一个集合进行去重操作，避免使用 List 的
  contains 方法进行遍历、对比、去重操作。

2.6 并发处理

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

• 【强制】创建线程或线程池时请指定有意义的线程名称，方便出错时回溯。
  正例：自定义线程工厂，并且根据外部特征进行分组，比如机房信息。

public class UserThreadFactory implements ThreadFactory {
    private final String namePrefix;
    private final AtomicInteger nextId = new AtomicInteger(1);
    // 定义线程组名称，在 jstack 问题排查时，非常有帮助
    UserThreadFactory(String whatFeaturOfGroup) {
         namePrefix = "From UserThreadFactory's " + whatFeaturOfGroup + "-Worker-";
    }
    @Override
    public Thread newThread(Runnable task) {
         String name = namePrefix + nextId.getAndIncrement();
         Thread thread = new Thread(null, task, name, 0, false);
         System.out.println(thread.getName());
         return thread;
    }
}

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

• 【强制】线程池不允许使用 Executors 去创建，而是通过 ThreadPoolExecutor 的方式，这
  样的处理方式让写的同学更加明确线程池的运行规则，规避资源耗尽的风险。
  说明：Executors 返回的线程池对象的弊端如下：
  1） FixedThreadPool 和 SingleThreadPool：
  允许的请求队列长度为 Integer.MAX_VALUE，可能会堆积大量的请求，从而导致 OOM。
  2） CachedThreadPool：
  允许的创建线程数量为 Integer.MAX_VALUE，可能会创建大量的线程，从而导致 OOM。

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

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

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

• 【推荐】使用 CountDownLatch 进行异步转同步操作，每个线程退出前必须调用 countDown
  方法，线程执行代码注意 catch 异常，确保 countDown 方法被执行到，避免主线程无法执行
  至 await 方法，直到超时才返回结果。
  说明：注意，子线程抛出异常堆栈，不能在主线程 try-catch 到

• 【推荐】避免 Random 实例被多线程使用，虽然共享该实例是线程安全的，但会因竞争同一
  seed 导致的性能下降。
  说明：Random 实例包括 java.util.Random 的实例或者 Math.random()的方式。
  正例：在 JDK7 之后，可以直接使用 API ThreadLocalRandom，而在 JDK7 之前，需要编码保证每个线
  程持有一个实例

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

• 【参考】HashMap 在容量不够进行 resize 时由于高并发可能出现死链，导致 CPU 飙升，在
  开发过程中可以使用其它数据结构或加锁来规避此风险。

• 【参考】ThreadLocal 对象使用 static 修饰，ThreadLocal 无法解决共享对象的更新问题。
  说明：这个变量是针对一个线程内所有操作共享的，所以设置为静态变量，所有此类实例共享此静态变
  量，也就是说在类第一次被使用时装载，只分配一块存储空间，所有此类的对象(只要是这个线程内定义
  的)都可以操控这个变量。

2.7 控制语句

• 【强制】在一个 switch 块内，每个 case 要么通过 continue/break/return 等来终止，要么
  注释说明程序将继续执行到哪一个 case 为止；在一个 switch 块内，都必须包含一个
  default 语句并且放在最后，即使它什么代码也没有。
  说明：注意 break 是退出 switch 语句块，而 return 是退出方法体。

• 【强制】当 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");
         }
     }
  }

  抛出异常，需要在调用switch 之前，进行空值判断。

• 【强制】在 if/else/for/while/do 语句中必须使用大括号。
  说明：即使只有一行代码，避免采用单行的编码方式：if (condition) statements;

• 【强制】在高并发场景中，避免使用”等于”判断作为中断或退出的条件。
  说明：如果并发控制没有处理好，容易产生等值判断被“击穿”的情况，使用大于或小于的区间判断条件
  来代替。
  反例：判断剩余奖品数量等于 0 时，终止发放奖品，但因为并发处理错误导致奖品数量瞬间变成了负数，
  这样的话，活动无法终止。

• 【推荐】表达异常的分支时，少用 if-else 方式，这种方式可以改写成：
  if (condition) {
  …
  return obj;
  }
  // 接着写 else 的业务逻辑代码;
  说明：如果非使用 if()…else if()…else…方式表达逻辑，避免后续代码维护困难，【强制】请勿超过 3 层。
  正例：超过 3 层的 if-else 的逻辑判断代码可以使用卫语句、策略模式、状态模式等来实现，其中卫语句
  即代码逻辑先考虑失败、异常、中断、退出等直接返回的情况，以方法多个出口的方式，解决代码中判断
  分支嵌套的问题，这是逆向思维的体现。

public void findBoyfriend(Man man) {
 if (man.isUgly()) {
 System.out.println("本姑娘是外貌协会的资深会员");
 return;
 }
 if (man.isPoor()) {
 System.out.println("贫贱夫妻百事哀");
 return;
 }
 if (man.isBadTemper()) {
 System.out.println("银河有多远，你就给我滚多远");
 return;
 }
System.out.println("可以先交往一段时间看看");
}

• 【推荐】除常用方法（如 getXxx/isXxx）等外，不要在条件判断中执行其它复杂的语句，将复
  杂逻辑判断的结果赋值给一个有意义的布尔变量名，以提高可读性。
  说明：很多 if 语句内的逻辑表达式相当复杂，与、或、取反混合运算，甚至各种方法纵深调用，理解成
  本非常高。如果赋值一个非常好理解的布尔变量名字，则是件令人爽心悦目的事情。

正例：

// 伪代码如下
final boolean existed = (file.open(fileName, "w") != null) && (...) || (...);
if (existed) {
 ...
}

• 【推荐】不要在其它表达式（尤其是条件表达式）中，插入赋值语句。
  说明：赋值点类似于人体的穴位，对于代码的理解至关重要，所以赋值语句需要清晰地单独成为一行。

反例：

public Lock getLock(boolean fair) {
 // 算术表达式中出现赋值操作，容易忽略 count 值已经被改变
 threshold = (count = Integer.MAX_VALUE) - 1;
 // 条件表达式中出现赋值操作，容易误认为是 sync==fair
 return (sync = fair) ? new FairSync() : new NonfairSync();
}

• 【推荐】循环体中的语句要考量性能，以下操作尽量移至循环体外处理，如定义对象、变
  量、获取数据库连接，进行不必要的 try-catch 操作（这个 try-catch 是否可以移至循环体
  外）。

2.8 注释规约

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

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

• 【强制】所有的类都必须添加创建者和创建日期。

• 【强制】方法内部单行注释，在被注释语句上方另起一行，使用//注释。方法内部多行注释
  使用/* */注释，注意与代码对齐。

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

• 【推荐】与其“半吊子”英文来注释，不如用中文注释把问题说清楚。专有名词与关键字保
  持英文原文即可。
  反例：“TCP 连接超时”解释成“传输控制协议连接超时”，理解反而费脑筋。

• 【推荐】代码修改的同时，注释也要进行相应的修改，尤其是参数、返回值、异常、核心逻
  辑等的修改。
  说明：代码与注释更新不同步，就像路网与导航软件更新不同步一样，如果导航软件严重滞后，就失去了
  导航的意义。

• 【参考】谨慎注释掉代码。在上方详细说明，而不是简单地注释掉。如果无用，则删除。
  说明：代码被注释掉有两种可能性：1）后续会恢复此段代码逻辑。2）永久不用。前者如果没有备注信
  息，难以知晓注释动机。后者建议直接删掉（代码仓库已然保存了历史代码）。

• 【参考】对于注释的要求：第一、能够准确反映设计思想和代码逻辑；第二、能够描述业务
  含义，使别的程序员能够迅速了解到代码背后的信息。完全没有注释的大段代码对于阅读者
  形同天书，注释是给自己看的，即使隔很长时间，也能清晰理解当时的思路；注释也是给继
  任者看的，使其能够快速接替自己的工作。

• 【参考】好的命名、代码结构是自解释的，注释力求精简准确、表达到位。避免出现注释的
  一个极端：过多过滥的注释，代码的逻辑一旦修改，修改注释是相当大的负担。

• 【参考】特殊注释标记，请注明标记人与标记时间。注意及时处理这些标记，通过标记扫
  描，经常清理此类标记。线上故障有时候就是来源于这些标记处的代码。
  1） 待办事宜（TODO）:（标记人，标记时间，[预计处理时间]）
  表示需要实现，但目前还未实现的功能。这实际上是一个 Javadoc 的标签，目前的 Javadoc 还没
  有实现，但已经被广泛使用。只能应用于类，接口和方法（因为它是一个 Javadoc 标签）。
  2） 错误，不能工作（FIXME）:（标记人，标记时间，[预计处理时间]）
  在注释中用 FIXME 标记某代码是错误的，而且不能工作，需要及时纠正的情况。

3. 异常日志

3.1 异常处理

【强制】Java 类库中定义的可以通过预检查方式规避的 RuntimeException 异常不应该通
过 catch 的方式来处理，比如：NullPointerException，IndexOutOfBoundsException 等
等。
说明：无法通过预检查的异常除外，比如，在解析字符串形式的数字时，可能存在数字格式错误，不得不
通过 catch NumberFormatException 来实现。
正例：if (obj != null) {…}
反例：try { obj.method(); } catch (NullPointerException e) {…}

• 【强制】异常不要用来做流程控制，条件控制。
  说明：异常设计的初衷是解决程序运行中的各种意外情况，且异常的处理效率比条件判断方式要低很多。

• 【强制】catch 时请分清稳定代码和非稳定代码，稳定代码指的是无论如何不会出错的代码。
  对于非稳定代码的 catch 尽可能进行区分异常类型，再做对应的异常处理。
  说明：对大段代码进行 try-catch，使程序无法根据不同的异常做出正确的应激反应，也不利于定位问
  题，这是一种不负责任的表现。
  正例：用户注册的场景中，如果用户输入非法字符，或用户名称已存在，或用户输入密码过于简单，在程
  序上作出分门别类的判断，并提示给用户。

-【强制】捕获异常是为了处理它，不要捕获了却什么都不处理而抛弃之，如果不想处理它，
请将该异常抛给它的调用者。最外层的业务使用者，必须处理异常，将其转化为用户可以理
解的内容。

• 【强制】有 try 块放到了事务代码中，catch 异常后，如果需要回滚事务，一定要注意手动回
  滚事务。

• 【强制】finally 块必须对资源对象、流对象进行关闭，有异常也要做 try-catch。
  说明：如果 JDK7 及以上，可以使用 try-with-resources 方式。

• 【强制】不要在 finally 块中使用 return。
  说明：try 块中的 return 语句执行成功后，并不马上返回，而是继续执行 finally 块中的语句，如果此处存
  在 return 语句，则在此直接返回，无情丢弃掉 try 块中的返回点。

private int x = 0;
public int checkReturn() {
 try {
 // x 等于 1，此处不返回
 return ++x;
 } finally {
 // 返回的结果是 2
 return ++x;
 }
}

• 【强制】捕获异常与抛异常，必须是完全匹配，或者捕获异常是抛异常的父类。
  说明：如果预期对方抛的是绣球，实际接到的是铅球，就会产生意外情况。

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

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

• 【推荐】方法的返回值可以为 null，不强制返回空集合，或者空对象等，必须添加注释充分
  说明什么情况下会返回 null 值。
  说明：本手册明确防止 NPE 是调用者的责任。即使被调用方法返回空集合或者空对象，对调用者来说，也
  并非高枕无忧，必须考虑到远程调用失败、序列化失败、运行时异常等场景返回 null 的情况。

• 【推荐】防止 NPE，是程序员的基本修养，注意 NPE 产生的场景：
  1） 返回类型为基本数据类型，return 包装数据类型的对象时，自动拆箱有可能产生 NPE。
  反例：public int f() { return Integer 对象}， 如果为 null，自动解箱抛 NPE。
  2） 数据库的查询结果可能为 null。
  3） 集合里的元素即使 isNotEmpty，取出的数据元素也可能为 null。
  4） 远程调用返回对象时，一律要求进行空指针判断，防止 NPE。
  5） 对于 Session 中获取的数据，建议进行 NPE 检查，避免空指针。
  6） 级联调用 obj.getA().getB().getC()；一连串调用，易产生 NPE。
  正例：使用 JDK8 的 Optional 类来防止 NPE 问题

• 【推荐】定义时区分 unchecked / checked 异常，避免直接抛出 new RuntimeException()，
  更不允许抛出 Exception 或者 Throwable，应使用有业务含义的自定义异常。推荐业界已定
  义过的自定义异常，如：DAOException / ServiceException 等。

• 【参考】对于公司外的 http/api 开放接口必须使用“错误码”；而应用内部推荐异常抛出；
  跨应用间 RPC 调用优先考虑使用 Result 方式，封装 isSuccess()方法、“错误码”、“错误
  简短信息”。

• 【参考】避免出现重复的代码（Don’t Repeat Yourself），即 DRY 原则。
  说明：随意复制和粘贴代码，必然会导致代码的重复，在以后需要修改时，需要修改所有的副本，容易遗
  漏。必要时抽取共性方法，或者抽象公共类，甚至是组件化。
  正例：一个类中有多个 public 方法，都需要进行数行相同的参数校验操作，这个时候请抽取：
  private boolean checkParam(DTO dto) {…}

3.2 日志规约

• 【强制】应用中不可直接使用日志系统（Log4j、Logback）中的 API，而应依赖使用日志框架
  SLF4J 中的 API，使用门面模式的日志框架，有利于维护和各个类的日志处理方式统一。
  import org.slf4j.Logger;
  import org.slf4j.LoggerFactory;
  private static final Logger logger = LoggerFactory.getLogger(Test.class);

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

• 应用中的扩展日志（如打点、临时监控、访问日志等）命名方式：
  appName_logType_logName.log。logType:日志类型，如 stats/monitor/access 等；logName:日志
  描述。这种命名的好处：通过文件名就可知道日志文件属于什么应用，什么类型，什么目的，也有利于归
  类查找。
  说明：推荐对日志进行分类，如将错误日志和业务日志分开存放，便于开发人员查看，也便于通过日志对
  系统进行及时监控。

• 【强制】在日志输出时，字符串变量之间的拼接使用占位符的方式。
  说明：因为 String 字符串的拼接会使用 StringBuilder 的 append()方式，有一定的性能损耗。使用占位符
  仅是替换动作，可以有效提升性能。
  正例：logger.debug(“Processing trade with id: {} and symbol: {}”, id, symbol);

• 【强制】对于 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());
  }

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

• 【强制】异常信息应该包括两类信息：案发现场信息和异常堆栈信息。如果不处理，那么通
  过关键字 throws 往上抛出。
  正例：logger.error(各类参数或者对象 toString() + “_” + e.getMessage(), e);

• 【推荐】谨慎地记录日志。生产环境禁止输出 debug 日志；有选择地输出 info 日志；如果使
  用 warn 来记录刚上线时的业务行为信息，一定要注意日志输出量的问题，避免把服务器磁盘
  撑爆，并记得及时删除这些观察日志。
  说明：大量地输出无效日志，不利于系统性能提升，也不利于快速定位错误点。记录日志时请思考：这些
  日志真的有人看吗？看到这条日志你能做什么？能不能给问题排查带来好处？

• 【推荐】可以使用 warn 日志级别来记录用户输入参数错误的情况，避免用户投诉时，无所
  适从。如非必要，请不要在此场景打出 error 级别，避免频繁报警。
  说明：注意日志输出的级别，error 级别只记录系统逻辑出错、异常或者重要的错误信息。

• 【推荐】尽量用英文来描述日志错误信息，如果日志中的错误信息用英文描述不清楚的话使
  用中文描述即可，否则容易产生歧义。【强制】国际化团队或海外部署的服务器由于字符集
  问题，使用全英文来注释和描述日志错误信息。

4 索引规约

• 【强制】业务上具有唯一特性的字段，即使是多个字段的组合，也必须建成唯一索引。
  说明：不要以为唯一索引影响了 insert 速度，这个速度损耗可以忽略，但提高查找速度是明显的；另外，
  即使在应用层做了非常完善的校验控制，只要没有唯一索引，根据墨菲定律，必然有脏数据产生。

• 【强制】超过三个表禁止 join。需要 join 的字段，数据类型必须绝对一致；多表关联查询
  时，保证被关联的字段需要有索引。
  说明：即使双表 join 也要注意表索引、SQL 性能

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

• 【强制】页面搜索严禁左模糊或者全模糊，如果需要请走搜索引擎来解决。
  说明：索引文件具有 B-Tree 的最左前缀匹配特性，如果左边的值未确定，那么无法使用此索引。

• 【推荐】如果有 order by 的场景，请注意利用索引的有序性。order by 最后的字段是组合
  索引的一部分，并且放在索引组合顺序的最后，避免出现 file_sort 的情况，影响查询性能。
  正例：where a=? and b=? order by c; 索引：a_b_c
  反例：索引如果存在范围查询，那么索引有序性无法利用，如：WHERE a>10 ORDER BY b; 索引 a_b 无
  法排序。

• 【推荐】利用覆盖索引来进行查询操作，避免回表。
  说明：如果一本书需要知道第 11 章是什么标题，会翻开第 11 章对应的那一页吗？目录浏览一下就好，这
  个目录就是起到覆盖索引的作用。
  正例：能够建立索引的种类分为主键索引、唯一索引、普通索引三种，而覆盖索引只是一种查询的一种效
  果，用 explain 的结果，extra 列会出现：using index。

• 【推荐】利用延迟关联或者子查询优化超多分页场景。
  说明：MySQL 并不是跳过 offset 行，而是取 offset+N 行，然后返回放弃前 offset 行，返回 N 行，那当
  offset 特别大的时候，效率就非常的低下，要么控制返回的总页数，要么对超过特定阈值的页数进行 SQL
  改写。
  正例：先快速定位需要获取的 id 段，然后再关联：
  SELECT a.* FROM 表 1 a, (select id from 表 1 where 条件 LIMIT 100000,20 ) b where a.id=b.id

  • 【推荐】SQL 性能优化的目标：至少要达到 range 级别，要求是 ref 级别，如果可以是
    consts 最好。
    说明：
    1） consts 单表中最多只有一个匹配行（主键或者唯一索引），在优化阶段即可读取到数据。
    2） ref 指的是使用普通的索引（normal index）。
    3） range 对索引进行范围检索。
    反例：explain 表的结果，type=index，索引物理文件全扫描，速度非常慢，这个 index 级别比较 range
    还低，与全表扫描是小巫见大巫。

• 【推荐】建组合索引的时候，区分度最高的在最左边。
  正例：如果 where a=? and b=? ，如果 a 列的几乎接近于唯一值，那么只需要单建 idx_a 索引即可。
  说明：存在非等号和等号混合时，在建索引时，请把等号条件的列前置。如：where c>? and d=? 那么
  即使 c 的区分度更高，也必须把 d 放在索引的最前列，即索引 idx_d_c。

• 【参考】创建索引时避免有如下极端误解：
  1） 宁滥勿缺。认为一个查询就需要建一个索引。
  2） 宁缺勿滥。认为索引会消耗空间、严重拖慢记录的更新以及行的新增速度。
  3） 抵制惟一索引。认为业务的惟一性一律需要在应用层通过“先查后插”方式解决。

5. 编写代码注意

5.1 @RequestParam 必须有value属性

在写控制器方法时，需要注意 请求参数必须添加 value 属性。

@RequestParam(value = "userId")

public OsGroupDto getMainGroup(@ApiParam @RequestParam(value = "userId") String userId,@ApiParam @RequestParam(value = "tenantId") String tenantId)