【阿里巴巴Java开发手册1.7.0（嵩山版）】编程规约&MySQL 数据库规约

阿里巴巴Java开发手册1.7.0（嵩山版）

---

一、编程规约

（一）命名风格

1. 所有命名不得以下划线和$开始和结束。

2. 所有命名不得以拼音或拼音英文混合。

3. 类名使用UpperCamelCase风格。

4. 方法名、参数名、成员变量、局部变量都统一使用lowerCamelCase风格。

5. 常量命名全部大写，单词间用下划线隔开，力求语义表达完整清楚，不要嫌名字长。

6. 抽象类命名使用 Abstract 或 Base 开头；异常类命名使用 Exception 结尾；

   测试类命名以它要测试的类的名称开始，以 Test 结尾。

7. 类型与中括号紧挨相连来表示数组。（定义整形数组 int[] arrayDemo。）

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

9. 杜绝完全不规范的缩写，避免望文不知义。（AbstractClass“缩写”成 AbsClass；condition“缩写”成 condi；Function 缩写”成 Fu）

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

11. Service/DAO 层方法命名规约
    
    1） 获取单个对象的方法用 get 做前缀。
    
    2） 获取多个对象的方法用 list 做前缀，复数结尾，如：listObjects。
    
    3） 获取统计值的方法用 count 做前缀。
    
    4） 插入的方法用 save/insert 做前缀。推荐save。
    
    5） 删除的方法用 remove/delete 做前缀。推荐remove。
    
    6） 修改的方法用 update 做前缀。

（二）常量定义

1. 不允许出现魔法值（未经过预先定义的值）直接出现在代码中。String key = "Id#taobao_" + tradeId;，其中的字符串就是魔法值。
2. 在 long 或者 Long 赋值时，数值后使用大写字母 L，不能是小写字母 l。

（三）代码格式

1. 大括号，单行放一起 { }，多行：

   1） 左大括号前不换行。
   
   2） 左大括号后换行。
   
   3） 右大括号前换行。
   
   4） 右大括号后还有 else 等代码则不换行；表示终止的右大括号后必须换行。

2. if/for/while/switch/do 等保留字与括号之间都必须加空格。

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

4. 采用 4 个空格缩进。

5. 注释的双斜线与注释内容之间有且仅有一个空格。

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

7. 方法参数在定义和传入时，多个参数逗号后面必须加空格。

   下例中实参的 args1，后边必须要有一个空格。
   
   method(args1, args2, args3);

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

9. 不同逻辑、不同语义、不同业务的代码之间插入一个空行分隔开来以提升可读性。

（四）OOP规约

1. Object 的 equals 方法容易抛空指针异常，应使用常量或确定有值的对象来调用 equals 。

   正例："test".equals(object);
   
   反例：object.equals("test");
   
   说明：推荐使用 JDK7 引入的工具类 java.util.Objects#equals(Object a, Object b)

2. 所有整型包装类对象之间值的比较，全部使用 equals 方法比较。

3. 任何货币金额，均以最小货币单位且整型类型来进行存储。

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

   

   1. 如上所示 BigDecimal 的等值比较应使用 compareTo()方法，而不是 equals()方法。

      equals()方法会比较值和精度 （1.0 与 1.00 返回结果为 false） ，而 compareTo()则会忽略精度。

   2. 定义数据对象 DO 类时，属性类型要与数据库字段类型相匹配。

   3. 禁止使用构造方法 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"); // String
      
      BigDecimal recommend2 = BigDecimal.valueOf(0.1); // valueOf(double)

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

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

      package java_wrapper;
      
      public class Cat {
          String name;
          int month;
          double weight;
      }
      package java_wrapper;
      
      public class CatTest {
          public static void main(String[] args) {
              Cat one = new Cat();
              System.out.println("小猫的昵称："+one.name);
              System.out.println("小猫的年龄："+one.month);
              System.out.println("小猫的体重："+one.weight);
          }
      }
      小猫的昵称：null
      小猫的年龄：0
      小猫的体重：0.0
      
      

      package java_wrapper;
      
      public class Cat {
          String name;
          Integer month;
          Integer weight;
      }
      
      小猫的昵称：null
      小猫的年龄：null
      小猫的体重：null
      
      

   基本类型	包装器类型
   boolean	Boolean
   char	Character
   int	Integer
   byte	Byte
   short	Short
   long	Long
   float	Float
   double	Double

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

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

   3. 类内方法定义的顺序依次是：公有方法或保护方法 > 私有方法 > getter / setter方法。

   4. 循环体内，字符串的连接方式，使用 StringBuilder 的 append 方法进行扩展。

      说明：下例中，反编译出的字节码文件显示每次循环都会 new 出一个 StringBuilder 对象，然后进行 append
      
      操作，最后通过 toString 方法返回 String 对象，造成内存资源浪费。
      
      反例：
      
      String str = "start";
      
      for (int i = 0; i < 100; i++) {
      
      str = str + "hello";
      
      }

   public class DemoStringBuilder2 {
       public static void main(String[] args) {
           StringBuilder bu=new StringBuilder();
           //append方法返回的是this，调用方法的对象bu，this==bu
           bu.append("abc");
           System.out.println(bu);  //abc
   
           bu.append("abc");
           bu.append("2");
           bu.append("true");
           bu.append("哈喽");
           bu.append("8.8");
           bu.append("abc");
           System.out.println(bu);  //abc2true哈喽8.8abc
   
           //链式编程：方法返回值是一个对象，可以继续调用方法
           System.out.println("abc".toUpperCase().toLowerCase().toLowerCase());
           bu.append("abc").append(1).append("你好").append(789);
           System.out.println(bu);
   		String myStr = bu.toString();	// 返回String对象
       }
   }
   

（五）日期时间

1. 【强制】日期格式化时，传入 pattern 中表示年份统一使用小写的 y。

   说明：日期格式化时，yyyy 表示当天所在的年，而大写的 YYYY 代表是 week in which year（JDK7 之后
   
   引入的概念），意思是当天所在的周属于的年份，一周从周日开始，周六结束，只要本周跨年，返回的 YYYY
   
   就是下一年。
   
   正例：表示日期和时间的格式如下所示：
   
   new SimpleDateFormat("yyyy-MM-dd HH:mm:ss")

   推荐使用java.util.Date;

   import java.util.Date;
   public class SimpleDateFormatDemo {
       public static void main(String[] args) {
           Date currentTime = new Date();
           System.out.println(currentTime); // 输出：Mon Feb 18 10:24:30 CST 2019
       }
   }
   

   使用format()方法将日期转换为字符串

   import java.text.SimpleDateFormat;
   import java.util.Date;
   public class SimpleDateFormatDemo {
       public static void main(String[] args) {
           Date currentTime = new Date();
           System.out.println(currentTime);    // Mon Feb 18 13:53:50 CST 2019
           SimpleDateFormat simpleDateFormat1 = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss.SSS");
           SimpleDateFormat simpleDateFormat2 = new SimpleDateFormat("yyyy-MM-dd");
           SimpleDateFormat simpleDateFormat3 = new SimpleDateFormat("yyyy/MM/dd");
           System.out.println(simpleDateFormat1.format(currentTime));  // 输出2019-02-18 13:53:50.629
           System.out.println(simpleDateFormat2.format(currentTime));  // 输出2019-02-18
           System.out.println(simpleDateFormat3.format(currentTime));  // 输出2019/02/18
       }
   }
   

   使用parse()方法将字符串转换为日期

   SimpleDateFormat simpleDateFormat1 = new SimpleDateFormat("yyyy-MM-dd HH:mm");
   String strDate1 = "2019-02-18 13:58";
   Date date1 = simpleDateFormat1.parse(strDate1);
   System.out.println(date1);	// 输出 Mon Feb 18 13:53:50 CST 2019
   

2. 【强制】在日期格式中分清楚大写的 M 和小写的 m，大写的 H 和小写的 h 分别指代的意义。

   1） 表示月份是大写的 M；
   
   2） 表示分钟则是小写的 m；
   
   3） 24 小时制的是大写的 H；
   
   4） 12 小时制的则是小写的 h。

3. **【强制】获取当前毫秒数：System.currentTimeMillis(); **

（六）集合处理

1. 【强制】判断所有集合内部的元素是否为空，使用 isEmpty()方法，而不是 size()。

   正例：

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

（七）控制语句

1. 【强制】当 switch 括号内的变量类型为 String 并且此变量为外部参数时，必须先进行 null判断。switch语句必须包含default。

   

   1. 三目运算符 condition? 表达式 1 : 表达式 2 中，高度注意表达式 1 和 2 在类型对齐时，

      可能抛出因自动拆箱导致的 NPE 异常。

      

（八）注释规约

1. 【强制】所有的抽象方法 （ 包括接口中的方法 ） 必须要用 Javadoc 注释、除了返回值、参数、异常说明外，还必须指出该方法做什么事情，实现什么功能。对子类的实现要求，或者调用注意事项，请一并说明。
2. 【强制】所有的类都必须添加创建者和创建日期。
3. 【强制】方法内部单行注释，在被注释语句上方另起一行，使用//注释。方法内部多行注释使用/* */注释，注意与代码对齐。
4. 【参考】谨慎注释掉代码。在上方详细说明，而不是简单地注释掉。如果无用，则删除。

二、MySQL 数据库

(一) 建表规约

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

   unsigned是指的无符号，就是没有负数，只能用正数和0，此时unsigned修饰的字段的值可以达到的最大值是原来的最大值加1，即原来一个tinyint字段能表示的范围是：-128 ~ 127，而unsigned修饰的字段范围是 0 ~ 255.

   数据类型	默认范围	unsigned范围
   tinyint	-2^7 ~ 2^7-1	0 ~ 2^8-1

2. 【强制】表名、字段名必须使用小写字母或数字 ， 禁止出现数字开头，禁止两个下划线中间只
   
   出现数字。数据库字段名的修改代价很大，因为无法进行预发布，所以字段名称需要慎重考虑。
   
   说明：MySQL 在 Windows 下不区分大小写，但在 Linux 下默认是区分大小写。因此，数据库名、表名、
   
   字段名，都不允许出现任何大写字母，避免节外生枝。

3. 表名不使用复数名词。

4. 禁用保留字，如 desc、range、match、delayed 等。

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

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

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

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

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

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

   说明：其中 id 必为主键，类型为 bigint unsigned、单表时自增、步长为 1。create_time, update_time
   
   的类型均为 datetime 类型，前者现在时表示主动式创建，后者过去分词表示被动式更新。

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

（二）SQL语句

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

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

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

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

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

4. 【强制】对于数据库中表记录的查询和变更，只要涉及多个表，都需要在列名前加表的别名（或表名）进行限定。SQL 语句中表的别名前加 as。