阿里代码规范_华山版

归纳下开发中常需注意的代码规约，化繁取简只捡个人认为有必要的~

华山版：2019.06.19

2020年目前已知最新版本：嵩山版

 

 

一、OOP 规约

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

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

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

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

    说明：浮点数采用“尾数+阶码”的编码方式，类似于科学计数法的“有效数字+指数”的表示方式。二进制无法精确表示大部分的十进制小数

正例：
(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");
 }
(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");
 }

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

1） 【强制】所有的 POJO 类属性必须使用包装数据类型。

2） 【强制】RPC 方法的返回值和参数必须使用包装数据类型。

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

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

【推荐】循环体内，字符串的连接方式，使用 StringBuilder 的 append 方法进行扩展

   说明：下例中，反编译出的字节码文件显示每次循环都会 new 出一个 StringBuilder 对象，然后进行 append 操作，最后通过 toString 方法返回 String 对象，造成内存资源浪费

【强制】禁止在 POJO 类中同时存在对应属性 xxx 的 isXxx()和 getXxx()方法

说明：框架在调用属性 xxx 的提取方法时，并不能确定哪个方法一定是被优先调用到。

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

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

其他：

【强制】注意 Math.random() 这个方法返回是 double 类型，注意取值的范围 0≤x<1（能够 取到零值，注意除零异常），如果想获取整数类型的随机数，不要将 x 放大 10 的若干倍然后 取整，直接使用 Random 对象的 nextInt 或者 nextLong 方法

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

 

二、集合处理

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

1） 只要覆写 equals，就必须覆写 hashCode

2） 因为 Set 存储的是不重复的对象，依据 hashCode 和 equals 进行判断，所以 Set 存储的对象必须覆 写这两个方法。

3） 如果自定义对象作为 Map 的键，那么必须覆写 hashCode 和 equals（String 已覆写 hashCode 和 equals 方法，所以我们可以愉快地使用 String 对象作为 key 来使用）

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

【强制】Collections 工具类返回的对象，如：emptyList()/singletonList()等都是 immutable list（即final变量），不可对其进行添加或者删除元素的操作。

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

正例：
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 隐患。

【强制】使用工具类 Arrays.asList()把数组转换成集合时，不能使用其修改集合相关的方 法，它的 add/remove/clear 方法会抛出 UnsupportedOperationException 异常

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

 

 

三、并发处理

1. 【强制】获取单例对象需要保证线程安全，其中的方法也要保证线程安全。

说明：资源驱动类、工具类、单例工厂类都需要注意

2. 【强制】创建线程或线程池时请指定有意义的线程名称，方便出错时回溯。

正例：自定义线程工厂，并且根据外部特征进行分组，比如机房信息。
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;
  }
}

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

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

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

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。

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

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

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

8. 【强制】对多个资源、数据库表、对象同时加锁时，需要保持一致的加锁顺序，否则可能会 造成死锁。

说明：线程一需要对表 A、B、C 依次全部加锁后才可以进行更新操作，那么线程二的加锁顺序也必须是 A、B、C，否则可能出现死锁。

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

 

 

四、控制语句

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

说明：注意 break 是退出 switch 语句块，而 return 是退出方法体。

【强制】当 switch 括号内的变量类型为 String 并且此变量为外部参数时，必须先进行 null 判断（否则直接抛NPE异常）

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

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

 

 

 

五、注释规约

【强制】类、类属性、类方法的注释必须使用 Javadoc 规范，使用/**内容*/格式，不得使用 // xxx 方式。

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

【强制】所有的抽象方法（包括接口中的方法）必须要用 Javadoc 注释、除了返回值、参数、 异常说明外，还必须指出该方法做什么事情，实现什么功能

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

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

 

 

 

六、异常

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

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

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

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

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

 

 

七、日志规约

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

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

【强制】所有日志文件至少保存 15 天，因为有些异常具备以“周”为频次发生的特点。

【强制】应用中的扩展日志（如打点、临时监控、访问日志等）命名方式： 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 级别的日志输出，必须进行日志级别的开关判断

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

 

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

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

 

 

八、单元测试

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

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

⚫ A：Automatic（自动化）

⚫ I：Independent（独立性）

⚫ R：Repeatable（可重复）

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

【强制】单元测试代码必须写在如下工程目录：src/test/java，不允许写在业务代码目录下。 说明：源码编译时会跳过此目录，而单元测试框架默认是扫描此目录。

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

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

【强制】单元测试是可以重复执行的，不能受到外界环境的影响。 说明：单元测试通常会被放到持续集成中，每次有代码 check in 时单元测试都会被执行。如果单测对外部 环境（网络、服务、中间件等）有依赖，容易导致持续集成机制的不可用

【强制】核心业务、核心应用、核心模块的增量代码确保单元测试通过。 说明：新增代码及时补充单元测试，如果新增代码影响了原有单元测试，请及时修正

【推荐】对于数据库相关的查询，更新，删除等操作，不能假设数据库里的数据是存在的， 或者直接操作数据库把数据插入进去，请使用程序插入或者导入数据的方式来准备数据

 

 

九、MySQL 数据库

1.建表规约

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

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

注意：POJO 类中的任何布尔类型的变量，都不要加 is 前缀！！！所以，需要在设置从 is_xxx 到 Xxx 的映射关系。数据库表示是与否的值，使用 tinyint 类型，坚持 is_xxx 的命名方式是为了明确其取 值含义与取值范围。

 

【强制】表名、字段名必须使用小写字母或数字，禁止出现数字开头，禁止两个下划线中间 只出现数字。数据库字段名的修改代价很大，因为无法进行预发布，所以字段名称需要慎重 考虑。

说明：MySQL 在 Windows 下不区分大小写，但在 Linux 下默认是区分大小写。因此，数据库名、表 名、字段名，都不允许出现任何大写字母，避免节外生枝

正例：aliyun_admin，rdc_config，level3_name
反例：AliyunAdmin，rdcConfig，level_3_name

【强制】主键索引名为 pk_字段名；唯一索引名为 uk_字段名；普通索引名则为 idx_字段名。 说明：pk_ 即 primary key；uk_ 即 unique key；idx_ 即 index 的简称。

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

【强制】如果存储的字符串长度几乎相等，使用 char 定长字符串类型。

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

【强制】表必备三字段：id, create_time, update_time

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

【推荐】表的命名最好是遵循“业务名称_表的作用”。 正例：alipay_task / force_project / trade_config

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

 

 

2.索引规约

【强制】业务上具有唯一特性的字段，即使是多个字段的组合，也必须建成唯一索引

 说明：不要以为唯一索引影响了 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 无 法排序

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

说明：

     1） consts 单表中最多只有一个匹配行（主键或者唯一索引），在优化阶段即可读取到数据

     2） ref 指的是使用普通的索引（normal index）

     3） range 对索引进行范围检索

 

 

3.SQL 语句

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

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

【强制】count(distinct col) 计算该列除 NULL 之外的不重复行数。

注意：count(distinct col1, col2) 如果其中一列全为 NULL，那么即使另一列有不同的值，也返回为 0

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

正例：使用如下方式来避免 sum 的 NPE 问题：SELECT IFNULL(SUM(column), 0) FROM table;

【强制】使用 ISNULL()来判断是否为 NULL 值。 说明：NULL 与任何值的直接比较都为 NULL。

【强制】代码中写分页查询逻辑时，若 count 为 0 应直接返回，避免执行后面的分页语句

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

说明：外键与级 联更新适用于单机低并发，不适合分布式、高并发集群；级联更新是强阻塞，存在数据库更新风暴的风 险；外键影响数据库的插入速度

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

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

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

 

4.ORM映射

【强制】在表查询中，一律不要使用 * 作为查询的字段列表，需要哪些字段必须明确写明。

说明：1）增加查询分析器解析成本。2）增减字段容易与 resultMap 配置不一致。3）无用字段增加网络 消耗，尤其是 text 类型的字段

【强制】POJO 类的布尔属性不能加 is，而数据库字段必须加 is_，要求在 resultMap 中进行 字段与属性之间的映射。

【强制】不要用 resultClass 当返回参数，即使所有类属性名与数据库字段一一对应，也需要 定义；反过来，每一个表也必然有一个 POJO 类与之对应

说明：配置映射关系，使字段与 DO 类解耦，方便维护。

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

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

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

 

 

 

应用分层

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

• 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 类 来传输

 

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

1） GroupID 格式：com.{公司/BU }.业务线 [.子业务线]，最多 4 级。

正例：com.taobao.jstorm 或 com.alibaba.dubbo.register

2） ArtifactID 格式：产品线名-模块名。语义不重复不遗漏，先到中央仓库去查证一下

正例：dubbo-client / fastjson-api / jstorm-tool

3） Version：详细规定参考下方

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

说明：注意起始版本号必须为：1.0.0，而不是 0.0.1，正式发布的类库必须先去中央仓库进行查证，使版 本号有延续性，正式版本号不允许覆盖升级。如当前版本：1.3.3，那么下一个合理的版本号：1.3.4 或 1.4.0 或 2.0.0

【强制】线上应用不要依赖 SNAPSHOT 版本（安全包除外）。

说明：不依赖 SNAPSHOT 版本是保证应用发布的幂等性。另外，也可以加快编译时的打包构建

【强制】依赖于一个二方库群时，必须定义一个统一的版本变量，避免版本号不一致。

说明：依赖 springframework-core,-context,-beans，它们都是同一个版本，可以定义一个变量来保存 版本：${spring.version}，定义依赖的时候，引用该版本。

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

 

 

服务器相关

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

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

【推荐】调大服务器所支持的最大文件句柄数（File Descriptor，简写为 fd）。

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

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

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