代码命名规范，就该这么写

         你是否曾有过一种想法，看着代码就想口吐芬芳，这是哪位"大佬"写的，看半天不知道这个类是做啥的，这个方法又是干啥的，用搜狗搜一下方法名，随着ctrl拉进了方法，像是在遨游的大海里，辽无边界；一个方法走天下。

        代码写得规范，不仅看起来爽，用起来更爽；下面整理了一下，最基本的代码规范。

一、命名风格

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

反例：_name / __name / $name / name_ / name$ / name__

2、类名使用 UpperCamelCase 风格，但以下情形例外：DO / BO / DTO / VO / AO /

PO / UID 等。

正例：ForceCode / UserDO / HtmlDTO / XmlService / TcpUdpDeal / TaPromotion

反例：forcecode / UserDo / HTMLDto / XMLService / TCPUDPDeal / TAPromotion

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

正例：MAX_STOCK_COUNT / CACHE_EXPIRED_TIME

反例：MAX_COUNT / EXPIRED_TIME

4、POJO 类中的任何布尔类型的变量，都不要加 is 前缀，否则部分框架解析会引起序列

化错误。

说明：在本文 MySQL 规约中的建表约定第一条，表达是与否的变量采用 is_xxx 的命名方式，所以，需要

在<resultMap>设置从 is_xxx 到 xxx 的映射关系。

反例：定义为基本数据类型 Boolean isDeleted 的属性，它的方法也是 isDeleted()，框架在反向解析的时

候，“误以为”对应的属性名称是 deleted，导致属性获取不到，进而抛出异常。

private boolean isDeleted;
public boolean isDeleted() {
   return isDeleted;
}
public void setDeleted(boolean deleted) {
   isDeleted = deleted;
}

5、杜绝完全不规范的缩写，避免望文不知义。

反例：AbstractClass“缩写”成 AbsClass；condition“缩写”成 condi；Function 缩写”成 Fu，此类

随意缩写严重降低了代码的可阅读性。

6、为了达到代码自解释的目标，任何自定义编程元素在命名时，使用尽量完整的单词组

合来表达。

正例：对某个对象引用的 volatile 字段进行原子更新的类名为 AtomicReferenceFieldUpdater。

反例：常见的方法内变量为 int a;的定义方式。

7、如果模块、接口、类、方法使用了设计模式，在命名时需体现出具体模式。

说明：将设计模式体现在名字中，有利于阅读者快速理解架构设计理念。

正例：public class OrderFactory;

public class LoginProxy;

public class ResourceObserver;

8、接口类中的方法和属性不要加任何修饰符号（public 也不要加），保持代码的简洁

性，并加上有效的 Javadoc 注释。尽量不要在接口里定义变量，如果一定要定义变量，确定

与接口方法相关，并且是整个应用的基础常量。

正例：接口方法签名 void commit();

接口基础常量 String COMPANY = "xuanwei";

反例：接口方法定义 public abstract void eat();

说明：JDK8 中接口允许有默认实现，那么这个 default 方法，是对所有实现类都有价值的默认实现。

public interface PaymentStrategy {
   default BigDecimal payment(){
       return BigDecimal.ONE;
   }
}

9、枚举类名带上 Enum 后缀，枚举成员名称需要全大写，单词间用下划线隔开。

说明：枚举其实就是特殊的常量类，且构造方法被默认强制是私有。

正例：枚举名字为 ProcessStatusEnum 的成员名称：SUCCESS / UNKNOWN_REASON。

10、各层命名规约：

A) Service/DAO 层方法命名规约

1） 获取单个对象的方法用 get 做前缀。

2） 获取多个对象的方法用 list 做前缀，复数结尾，如：listObjects。

3） 获取统计值的方法用 count 做前缀。

4） 插入的方法用 save/insert 做前缀。

5） 删除的方法用 remove/delete 做前缀。

6） 修改的方法用 update 做前缀。

B) 领域模型命名规约

1） 数据对象：xxxDO，xxx 即为数据表名。

2） 数据传输对象：xxxDTO，xxx 为业务领域相关的名称。

3） 展示对象：xxxVO，xxx 一般为网页名称。

4） POJO 是 DO/DTO/BO/VO 的统称，禁止命名成 xxxPOJO。

二、代码风格

1、如果是大括号内为空，则简洁地写成{}即可，大括号中间无需换行和空格；如果是非

空代码块则：

1） 左大括号前不换行。

2） 左大括号后换行。

3） 右大括号前换行。

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

public void pay(){
   if(true){  
   }else{  
   }
}

2、左小括号和右边相邻字符之间不出现空格 ；右小括号和左边相邻字符之间也不出现空

格；而左大括号前需要加空格。

反例：if (空格 a == b 空格)

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

正例：下例中实参的 args1，后边必须要有一个空格。

method(args1, args2, args3);

4、【推荐】单个方法的总行数不超过 80 行。

说明：除注释之外的方法签名、左右大括号、方法内代码、空行、回车及任何不可见字符的总行数不超过

80 行。

正例：代码逻辑分清红花和绿叶，个性和共性，绿叶逻辑单独出来成为额外方法，使主干代码更加清晰；共

性逻辑抽取成为共性方法，便于复用和维护。

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

说明：任何情形，没有必要插入多个空行进行隔开。

三、OOP规约

Object-Oriented Programming  面向对象编程

1、避免通过一个类的对象引用访问此类的静态变量或静态方法，无谓增加编译器解析成

本，直接用类名来访问即可。

2、相同参数类型，相同业务含义，才可以使用 Java 的可变参数，避免使用 Object 。

说明：可变参数必须放置在参数列表的最后。（建议开发者尽量不用可变参数编程）

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

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

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

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

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

说明：对于 Integer var = ? 在-128 至 127 之间的赋值，Integer 对象是在 IntegerCache.cache 产生，

会复用已有对象，这个区间内的 Integer 值可以直接使用==进行判断，但是这个区间之外的所有数据，都

会在堆上产生，并不会复用已有对象，这是一个大坑，推荐使用 equals 方法进行判断。

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

正例：数据库字段的 bigint 必须与类属性的 Long 类型相对应。

反例：某个案例的数据库表 id 字段定义类型 bigint unsigned，实际类对象属性为 Integer，随着 id 越来

越大，超过 Integer 的表示范围而溢出成为负数。

6、禁止使用构造方法 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);

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

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

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

3） 【推荐】所有的局部变量使用基本数据类型。

说明：POJO 类属性没有初值是提醒使用者在需要使用时，必须自己显式地进行赋值，任何 NPE 问题，或

者入库检查，都由使用者来保证。

正例：数据库的查询结果可能是 null，因为自动拆箱，用基本数据类型接收有 NPE 风险。

反例：某业务的交易报表上显示成交总额涨跌情况，即正负 x%，x 为基本数据类型，调用的 RPC 服务，调

用不成功时，返回的是默认值，页面显示为 0%，这是不合理的，应该显示成中划线-。所以包装数据类型

的 null 值，能够表示额外的信息，如：远程调用失败，异常退出。

8、定义 DO/DTO/VO 等 POJO 类时，不要设定任何属性默认值。

反例：POJO 类的 createTime 默认值为 new Date()，但是这个属性在数据提取时并没有置入具体值，在

更新其它字段时又附带更新了此字段，导致创建时间被修改成当前时间。

9、序列化类新增属性时，请不要修改 serialVersionUID 字段，避免反序列失败；如果

完全不兼容升级，避免反序列化混乱，那么请修改 serialVersionUID 值。

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

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

11、POJO 类必须写 toString 方法。使用 IDE 中的工具：source> generate toString

时，如果继承了另一个 POJO 类，注意在前面加一下 super.toString。

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

12、禁止在 POJO 类中，同时存在对应属性 xxx 的 isXxx()和 getXxx()方法。

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

13、使用索引访问用 String 的 split 方法得到的数组时，需做最后一个分隔符后有无内容

的检查，否则会有抛 IndexOutOfBoundsException 的风险。

说明：

String str = "a,b,c,,";

String[] ary = str.split(",");

// 预期大于 3，结果是 3

System.out.println(ary.length);

14、 final 可以声明类、成员变量、方法、以及本地变量，下列情况使用 final 关键字：

1） 不允许被继承的类，如：String 类。

2） 不允许修改引用的域对象，如：POJO 类的域变量。

3） 不允许被覆写的方法，如：POJO 类的 setter 方法。

4） 不允许运行过程中重新赋值的局部变量。

5） 避免上下文重复使用一个变量，使用 final 关键字可以强制重新定义一个变量，方便更好地进行重构。

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

1） 如果不允许外部直接通过 new 来创建对象，那么构造方法必须是 private。

2） 工具类不允许有 public 或 default 构造方法。

3） 类非 static 成员变量并且与子类共享，必须是 protected。

4） 类非 static 成员变量并且仅在本类使用，必须是 private。

5） 类 static 成员变量如果仅在本类使用，必须是 private。

6） 若是 static 成员变量，考虑是否为 final。

7） 类成员方法只供类内部调用，必须是 private。

8） 类成员方法只对继承类公开，那么限制为 protected。

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

四、集合

1、ArrayList 的 subList 结果不可强转成 ArrayList，否则会抛出  ClassCastException 异

常：java.util.RandomAccessSubList cannot be cast to java.util.ArrayList 。

说明：subList()返回的是 ArrayList 的内部类 SubList，并不是 ArrayList 本身，而是 ArrayList 的一个视

图，对于 SubList 的所有操作最终会反映到原列表上。

2、使用 Map 的方法 keySet() / values() / entrySet() 返回集合对象时，不可以对其进行添

加元素操作，否则会抛出 UnsupportedOperationException 异常。

3、Collections 类返回的对象，如：emptyList() / singletonList() 等都是 immutable list，

不可对其进行添加或者删除元素的操作。

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

会触发 UnsupportedOperationException 异常。

4、在 subList 场景中，高度注意对父集合元素的增加或删除，均会导致子列表的遍历、

增加、删除产生 ConcurrentModificationException 异常。

5、使用集合转数组的方法，必须使用集合的 toArray(T[] array)，传入的是类型完全一

致、长度为 0 的空数组。

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

ClassCastException 错误。

正例：

List<String> list = new ArrayList<>(2);

list.add("play");

list.add("sport");

String[] array = list.toArray(new String[0]);

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

1） 等于 0，动态创建与 size 相同的数组，性能最好。

2） 大于 0 但小于 size，重新创建大小等于 size 的数组，增加 GC 负担。

3） 等于 size，在高并发情况下，数组创建完成之后，size 正在变大的情况下，负面影响与 2 相同。

4） 大于 size，空间浪费。

6、使用工具类 Arrays.asList()把数组转换成集合时，不能使用其修改集合相关的方法，

它的 add/remove/clear 方法会抛出 UnsupportedOperationException 异常。

说明：asList 的返回对象是一个 Arrays 内部类，并没有实现集合的修改方法。Arrays.asList 体现的是适配

器模式，只是转换接口，后台的数据仍是数组。

String[] str = new String[] { "study", "eat", "play" };

List list = Arrays.asList(str);

第一种情况：list.add("studyeatplay"); 运行时异常。

第二种情况：str[0] = "change"; 也会随之修改，反之亦然。

7、泛型通配符 <? extends T> 来接收返回的数据，此写法的泛型集合不能使用 add 方法，

而 <? super T> 不能使用 get 方法，两者在接口调用赋值的场景中容易出错。

说明：扩展说一下 PECS(Producer Extends Consumer Super)原则：第一、频繁往外读取内容的，适合用

<? extends T>。第二、经常往里插入的，适合用<? super T>

8、在无泛型限制定义的集合赋值给泛型限制的集合时，在使用集合元素时，需要进行

instanceof 判断，避免抛出 ClassCastException 异常。

说明：毕竟泛型是在 JDK5 后才出现，考虑到向前兼容，编译器是允许非泛型集合与泛型集合互相赋值。

反例：

List<String> list= null;

List nodes= new ArrayList(10);

nodes.add(new Object());

nodes.add(new Integer(1));

list= nodes;

// 此处抛出 ClassCastException 异常

String string = list.get(0);

9、不要在 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 (item.equals("aa")) {
       iterator.remove();
   }
}
反例：
for (String item : list) {
   if ("1".equals(item)) {
       list.remove(item);
   }
}

10、集合初始化时，指定集合初始值大小。

说明：HashMap 使用 HashMap(int initialCapacity) 初始化，如果暂时无法确定集合大小，那么指定默

认值（16）即可。

正例：initialCapacity = (需要存储的元素个数 / 负载因子) + 1。注意负载因子（即 loader factor）默认

为 0.75，如果暂时无法确定初始值大小，请设置为 16（即默认值）。

反例：HashMap 需要放置 1024 个元素，由于没有设置容量初始大小，随着元素增加而被迫不断扩容，

resize()方法总共会调用 8 次，反复重建哈希表和数据迁移。当放置的集合元素个数达千万级时会影响程序

性能。

11、使用 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 值组合集合。

五、并发处理

1、获取单例对象需要保证线程安全，其中的方法也要保证线程安全。

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

synchronized，加锁

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

说明：线程池的好处是减少在创建和销毁线程上所消耗的时间以及系统资源的开销，解决资源不足的问题。

如果不使用线程池，有可能造成系统创建大量同类线程而导致消耗完内存或者“过度切换”的问题。

3、线程池不允许使用 Executors 去创建，而是通过 ThreadPoolExecutor 的方式，这

样的处理方式让写的同学更加明确线程池的运行规则，规避资源耗尽的风险。

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

1） FixedThreadPool 和 SingleThreadPool：

允许的请求队列长度为 Integer.MAX_VALUE，可能会堆积大量的请求，从而导致 OOM。

2） CachedThreadPool：

允许的创建线程数量为 Integer.MAX_VALUE，可能会创建大量的线程，从而导致 OOM。

4、 SimpleDateFormat 是线程不安全的类，一般不要定义为 static 变量，如果定义为 static ，

必须加锁，或者使用 DateUtils 工具类。

final DateFormat df = new SimpleDateFormat("yyyyMMdd,HHmmss");
ExecutorService ts = Executors.newFixedThreadPool(100);
for (int i = 0; i < 1000 ; i++) {
   ts.execute(new Runnable() {
       @Override
       public void run() {
           try {
               //生成随机数，格式化日期
               String format =  df.format(new Date(Math.abs(new Random().nextLong())));
               System.out.println(format);
           } catch (Exception e) {
               e.printStackTrace();
               System.exit(1);
           }
       }
   });
}

正例：注意线程安全，使用 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。

5、必须回收自定义的 ThreadLocal 变量，尤其在线程池场景下，线程经常会被复用，

如果不清理自定义的 ThreadLocal 变量，可能会影响后续业务逻辑和造成内存泄露等问题。

尽量在代理中使用 try-finally 块进行回收。

正例：

objectThreadLocal.set(userInfo);

try {

// ...

} finally {

objectThreadLocal.remove();

}

6、对多个资源、数据库表、对象同时加锁时，需要保持一致的加锁顺序，否则可能会造

成死锁。

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

B、C，否则可能出现死锁。

7、HashMap 在容量不够进行 resize 时由于高并发可能出现死链，导致 CPU 飙升，在

开发过程中注意规避此风险。

8、ThreadLocal 对象使用 static 修饰，ThreadLocal 无法解决共享对象的更新问题。

说明：这个变量是针对一个线程内所有操作共享的，所以设置为静态变量，所有此类实例共享此静态变量，

也就是说在类第一次被使用时装载，只分配一块存储空间，所有此类的对象(只要是这个线程内定义的)都可

以操控这个变量

六、前后端规约

1、前后端交互的 API，需要明确协议、域名、路径、请求方法、请求内容、状态码、响

应体。

说明：

1） 协议：生产环境必须使用 HTTPS。

2） 路径：每一个 API 需对应一个路径，表示 API 具体的请求地址：

a） 代表一种资源，只能为名词，推荐使用复数，不能为动词，请求方法已经表达动作意义。

b） URL 路径不能使用大写，单词如果需要分隔，统一使用下划线。

c） 路径禁止携带表示请求内容类型的后缀，比如".json",".xml"，通过 accept 头表达即可。

3） 请求方法：对具体操作的定义，常见的请求方法如下：

a） GET：从服务器取出资源。

b） POST：在服务器新建一个资源。

c） PUT：在服务器更新资源。

d） DELETE：从服务器删除资源。

4） 请求内容：URL 带的参数必须无敏感信息或符合安全要求；body 里带参数时必须设置 Content-Type。

5） 响应体：响应体 body 可放置多种数据类型，由 Content-Type 头来确定。

2、前后端数据列表相关的接口返回，如果为空，则返回空数组[]或空集合{}。

说明 ：此条约定有利于数据层面上的协作更加高效，减少前端很多琐碎的 null 判断。

3、服务端发生错误时，返回给前端的响应信息必须包含 HTTP 状态码，errorCode、

errorMessage、用户提示信息四个部分。

说明：四个部分的涉众对象分别是浏览器、前端开发、错误排查人员、用户。其中输出给用户的提示信息

要求：简短清晰、提示友好，引导用户进行下一步操作或解释错误原因，提示信息可以包括错误原因、上

下文环境、推荐操作等。errorCode：参考附表 3。errorMessage：简要描述后端出错原因，便于错误排

查人员快速定位问题，注意不要包含敏感数据信息。

正例：常见的 HTTP 状态码如下

1） 200 OK: 表明该请求被成功地完成，所请求的资源发送到客户端。

2） 401 Unauthorized: 请求要求身份验证，常见对于需要登录而用户未登录的情况。

3） 403 Forbidden：服务器拒绝请求，常见于机密信息或复制其它登录用户链接访问服务器的情况。

4） 404 Not Found: 服务器无法取得所请求的网页，请求资源不存在。

5） 500 Internal Server Error: 服务器内部错误。

4、HTTP 请求通过 URL 传递参数时，不能超过 2048 字节。

说明：不同浏览器对于 URL 的最大长度限制略有不同，并且对超出最大长度的处理逻辑也有差异，2048

字节是取所有浏览器的最小值。

反例：某业务将退货的商品 id 列表放在 URL 中作为参数传递，当一次退货商品数量过多时，URL 参数超长，

传递到后端的参数被截断，导致部分商品未能正确退货。

5、HTTP 请求通过 body 传递内容时，必须控制长度，超出最大长度后，后端解析会出

错。

说明：nginx 默认限制是 1MB，tomcat 默认限制为 2MB，当确实有业务需要传较大内容时，可以通过调

大服务器端的限制。

6、在翻页场景中，用户输入参数的小于 1，则前端返回第一页参数给后端；后端发现用

户输入的参数大于总页数，直接返回最后一页。

7、服务器返回信息必须被标记是否可以缓存，如果缓存，客户端可能会重用之前的请求

结果。

说明：缓存有利于减少交互次数，减少交互的平均延迟。

正例：http 1.1 中，s-maxage 告诉服务器进行缓存，时间单位为秒，用法如下，

response.setHeader("Cache-Control", "s-maxage=" + cacheSeconds);