Java编码规范

Java编码规范

---

前言

使Java编码便于维护，提高系统安全性和性能

---

1. 命名规范

1.1 代码中的命名均不能以下划线或美元符号开始，也不能以下划线或美元符号结束

1.2 代码中严禁使用中英文混合的方式，不允许使用中文的方式。
说明：正确的英文拼写和违法可以让阅读者易于理解，避免歧义，不建议使用纯拼音命名方式命名。

1.3 类名使用UpperCamelCase风格，必须遵从驼峰形式，但以下情形例外：（领域模型的相关命名，如DO/BO/DTO/VO等）

1.4 方法名、参数名、成员变量、局部变量都统一使用LowerCamelCase风格，应遵从驼峰形式。

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

1.6 抽象类命名使用Abstract开头，异常类命名使用Exception结尾，测试类命名以它要测试的类名拼Test结尾。

1.7 POJO类中布尔类型的变量都不允许加is，否则部分框架解析会引起序列化错误。

1.8 包名统一使用小写，分隔符之间有且仅有一个自然语义的英语单词，包名统一使用单数形式，但是类名如果有复数含义，类名可以使用复数形式。
示例：应用工具类包名为com.alibaba.open.util，类名为MessageUtils

1.9 杜绝完全不规范的缩写，避免望文不知义，随意缩写严重降低了代码的可阅读性

1.10 如果使用设计模式，建议在类名中体现出具体模式。
示例：public class OrderFactory

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

1.12 接口和实现类的命名规则
对于Service和Dao类，暴漏出来的服务一定是借口，内部实现类用Impl的后缀与接口区别。

1.13 枚举类名建议带上Enum后缀，枚举成员名称需要全大写，单词间用下划线隔开。
说明：枚举其实就是特殊的常量类，且构造方法被默认强制是私有。

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

1.15 各层命名规则

• Service/DAO层方法命名规则
  • 获取单个对象的方法用get做前缀
  • 获取多个对象的方法用list做前缀
  • 获取统计值的方法用count做前缀
  • 插入方法用save或insert做前缀
  • 删除方法用remove或delete做前缀
  • 修改方法用update做前缀
• 领域模型命名规则
  • 数据对象：xxxDO，xxx即为数据表名。
  • 数据传输对象：xxxDTO，xxx为业务领域相关的名称
  • 展示对象：xxxVO，xxx一般为网页名称
  • POJO使DO/DTO/BO/VO的统称，禁止命名成xxxPOJO

1.16 源文件以其最顶层的类名来命名，大小写敏感，文件扩展名为.java

1.17 源文件编码格式统一为无BOM的UTF-8

1.18 除了行结束符序列，ASCII水平空格字符（0x20，即空格）是源文件中唯一允许出现的空白字符
说明：所有其他字符串中的空白字符都要进行转义；制表符不用于缩进。采用4个空格缩进，禁止使用tab字符。如果使用tab缩进，必须设置1个tab为4个空格。IDEA设置tab为4个空格，请勿勾选Use tab character；

2. 常量定义

2.1 不允许出现任何魔法值（即未经定义的常量）直接出现在代码中，也表示移除硬编码。

2.2 long或Long赋初始值时，必须使用大写的L，不能是小写的l，容易同数字1混淆。

2.3 不要使用一个常量类维护所有常量，应该按常量功能进行归类，分开维护。
说明：大而全的常量类只有使用查找功能才能定位到修改的常量，不利于理解和维护

2.4 常量的复用层次有5层：跨应用共享，应用内共享，子工程内共享，包内共享，类内共享。

• 跨应用共享：放置在中央仓库中，通常在引包的constant目录下
• 应用内共享：放置在项目的modules中的constant目录下，易懂的变量统一定义成应用内共享变量，便于复用
• 子工程内共享：即在当前子工程的constant目录下
• 包内共享：即在当前包下单独的constant目录下
• 类内共享：直接在类内部private static final定义

2.5 如果变量值仅在一个范围内变化用Enum类，如果还带有名称之外的延伸属性，必须使用Enum类，下面正例中的数字就是延伸信息，表示星期几。

3. 格式规则

3.1 大括号的使用约定：如果是大括号内为空，则简洁写成{}即可，不需要换行；如果是非空代码块则

• 左大括号前不换行
• 左大括号后换行
• 右大括号前换行
• 右大括号后还有else等代码则不换行
• 表示终止右大括号后必须换行

3.2 左括号和后一个字符之间不出现空格；同样右括号和前一个字符之间也不出现空格。

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

3.4 任何运算符左右必须加一个空格
说明：运算符包括赋值运算符、逻辑运算符、加减乘除、三目运算符

3.5 缩进采用4个空格，禁止使用tab字符

3.6 单行字符数限制不超过120个，超出需要换行，换行时遵循以下规则

• 第二行相对第一行缩进4个空格，从第三行开始，不再继续缩进，参考示例。
• 运算符与下文一起换行
• 方法调用的点符号与下文一起换行
• 在多个参数超长，逗号后进行换行
• 在括号前不要换行

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

3.8 IDEA的text file encoding设置为UTF-8，IDEA中文件的换行符使用UNIX格式，不要使用windows格式。

3.9 没有必要增加若干空格使某一行的字符和上一行的相应字符对齐。

3.10 方法体内的执行语句组、变量语句组、不同业务逻辑之间或不同语义之间插入一个空格，相同业务逻辑和相同语义之间不需要插入空格。

3.11 当某行语句在逻辑上比下面语句高一个层次时，该行下面的语句都需要在该行的基础上缩进一个单位。

3.12 复合语句中的语句要比复合语句缩进一个层次。

3.13 方法名和其参数列表左侧括号之间不能有空格。

3.14 一元操作符和操作数之间不能有空格，如负数，自增，自减。

3.15 在进行类型强制转换时，右侧括号和转换值之间不需要空格隔开。

3.16 注释的双斜线和注释内容之间需要使用一个空格隔开。

// 注释内容

3.17 二目和三目运算符左右两侧都需要添加一个空格。

3.18 左右小括号与字符间不需要存在空格，左大括号前需要空格。

if(a=b) {}

3.19 左大括号位于声明语句的末尾，并与末尾之间留有一个空格。

3.20 右大括号换行，并同相应的声明语句对齐。

3.21 方法与方法之间需要空白行分隔。

3.22 复合语句的左大括号应位于复合语句起始行行尾，并添加一个空格，右大括号需要换行并与复合语句首行对齐。

4. OOP规则

4.1 避免通过一个类型的对象来引用此类的静态方法和静态成员，直接使用类名访问即可，减少编译器解析成本。

4.2 所有覆写方法都必须加@Override注释。

4.3 具有相同业务含义，相同参数类型才可以使用java的可变参数，避免使用Object。
说明：可变参数必须放置在参数列表最后（提倡尽量不使用可变参数编程）

示例：public void test(String name, Integer... ids) {}

4.4 外部已经调用或组件库已经依赖的接口，不允许修改方法签名，避免对调用方产生影响，接口过时弃用时必须添加@Deprecated注解，并说明新的服务和新的接口。

4.5 不能使用过时的类和方法。调用方在调用新的方法时，需要对依据旧方法对新的方法进行考证。

4.6 Object的equals方法容易出现空指针异常，必须遵守常量或确定值调用equals方法。

4.7 所有相同类型的包装类必须使用equals进行比较。
说明：Integer在-128～127上的值都在IntegerCache cache产生，会复用已有对象，可以使用 == 判断值是否一致，超出区间范围的值会从堆上产生，不会复用已存在的对象，栈地址指向不一致，需要使用equals方法进行值判断

4.8 基本数据类型和报数据类型的使用标准规则：

• 所有的POJO类需要使用包装的数据类型
• RPC返回值和参数必须使用包装数据类型
• 所有的局部变量都使用基本数据类型

说明：POJO类没有赋初始值是提醒使用者需要显示的赋初始值，任何空指针问题或者入库检查由使用者保证。
正例：数据库的查询结果可能是null，因为自动拆箱，同基本数据类型接收由空指针风险。
反例：比如现实成交总额涨跌情况，即正负x%，x为基本数据类型，调用RPC服务，调用不成功时，返回的是默认值，页面显示：0%，这个是不合理的，应该显示成中划线。所以包装数据类型的null值，能够显示表示额外的信息，如远程调用失败，异常退出。

4.9 定义DO/DTO/VO等POJO类时，不要设定任何属性默认值。
反例：POJO类的gmtCreate默认值为newDate()，但是这个属性在数据提取时并没有入具体值，在更新其他字段时又附带更新了此字段，导致创建时间别修改成当前时间。

4.10 序列化类新增属性时，请不要修改serialVersionUID字段，避免反序列化失败，如果完全不兼容升级，避免反序列化混乱，那么请修改serialVersionUID值。
说明：注意serialVersionUID不一致会抛出序列化运行时异常。

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

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

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

4.14 当一个类有多个构造方法，或者多个同名方法，这些方法应该按顺序放置在一起，便于阅读。

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

4.16 setter方法中，参数名称与类成员变量名称一致，this.成员名-参数名，在getter/setter方法中，尽量不要增加业务逻辑，增加排查问题的难度。

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

4.18 下列情况，声明成final会更有提示性：

• 不需要重新赋值的变量，包括类属性、局部变量。
• 对象参数前加final，表示不允许修改引用的指向。
• 类方法确定不允许被重写。

4.19 慎用Object的clone方法来拷贝对象。
说明：对象的clone方法默认是浅拷贝，若想实现深拷贝需要重写clone方法实现属性对象的拷贝。

4.20 类成员与方法访问控制从严：

• 如果不允许外部直接通过new来创建对象，那么构造方法必须是private。
• 工具类不允许有public或default构造方法。
• 类非static成员变量并且与子类共享，必须是protected。
• 类非static成员变量并且仅在本类使用，必须是private。
• 类static成员变量如果仅在本类使用，必须是private。
• 若是static成员变量，必须考虑是否为final。
• 类成员方法之供类内部调用，必须是private。
• 类成员方法只对继承类公开，那么限制为protected。

说明：任何类、方法、参数、变量严控访问范围。过宽泛的访问范围，不利于模块解耦。

4.21 数据类型转换中字符串转整型常用的是Integer.valueOf与Integer.parseInt，其中第一个返回的是对象，对于基本数据类型进行了装箱，第二个是返回基本数据类型，使用二者时需要根据具体需求合理选择。

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

4.23 为了防止精度损失，禁止使用的构造方法BigDecimal(double)的方式把double值转化为BigDecimal对象。
说明：BigDecimal(double)存在精度损失风险，在精确计算或值比较的场景中可能会导致业务逻辑异常。

5. 集合处理

5.1 关于hashCode和equals的处理，遵循如下规则：

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

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

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

5.3 在sublist场景中，高度注意对原集合元素个数的修改，会导致子列表的遍历、增加、删除均产生ConcurrentMOdificationException异常。

5.4 使用集合转数组的方法，必须使用集合的toArray(T[] array)，传入的是类型完全一样的数组，大小就是list.size()。
说明：使用toArray带参数方法，入参分配的数组空间不够大时，toArray方法内部将重新分配内存空间，并返回新数组地址；如果数组元素大于实际所需，下标为[list.size()]的数组元素将被置为null，其他数组元素保持原值，因此最好将方法入参数组大小定义与集合元素个数一致。

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

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

5.7 在JDK7版本及以上，Comparator要满足如下三个条件，不然Arrays.sort，Collections.sort会报IllegalArgumentException异常。
说明：

• x，y比较结果和y，x的比较结果相反
• x>y，y>z，则x>z
• x=y，则x，z比较结果和y，z比较结果相同

5.8 集合初始化时，尽量指定集合初始值大小。
说明：ArrayList尽量使用ArrayList(intinitialCapacity)初始化。

5.9 使用entrySet遍历Map类集合KV，而不是keySet方式进行遍历。使用Map的方法keySet()/values()/entrySet()返回集合对象时，不可以对其进行添加元素操作，否则会抛出UnsupportedOperationException异常。
说明：keySet其实是遍历了2次，一次是转为Iterator对象，另一次是从hashMap中取出key所对应的value。而entrySet只是遍历了一次就把key和value都放到了entry中，效率更高。如果是JDK8，使用Map.foreach方法。
正例：values()返回的是V值集合，是一个list集合对象；keySet()返回的是K值集合，是一个Set集合对象；entrySet()返回的是K-V值组合集合。

5.10 关注Map类集合K/V能不能存储null值的情况
反例：由于HashMap的干扰，很多人认为ConcurrentHashMap是可以置入null值，注意存储null值时会抛出空指针异常。

5.11 合理利用好集合的有序性(sort)和稳定性(order)，