java开发规约

编程规约命名风格

常量定义

代码格式

1.【强制】注释的双斜线与注释内容之间有且仅有一个空格。
正例：
// 这是示例注释，请注意在双斜线之后有一个空格
String commentString = new String();
2.【推荐】单个方法的总行数不超过 80 行。
说明：除注释之外的方法签名、左右大括号、方法内代码、空行、回车及任何不可见字符的总行数不超过
80 行。
正例：代码逻辑分清红花和绿叶，个性和共性，绿叶逻辑单独出来成为额外方法，使主干代码更加清晰；共
性逻辑抽取成为共性方法，便于复用和维护。
3.【推荐】不同逻辑、不同语义、不同业务的代码之间插入一个空行分隔开来以提升可读性。
说明：任何情形，没有必要插入多个空行进行隔开。

OOP规约(面对对象程序设计规约)

1.【强制】Object 的 equals 方法容易抛空指针异常，应使用常量或确定有值的对象来调用 equals。
正例：“test”.equals(object);
反例：object.equals(“test”);
说明：推荐使用 JDK7 引入的工具类 java.util.Objects#equals(Object a, Object b)
2.【强制】所有整型包装类对象之间值的比较，全部使用 equals 方法比较。
说明：对于 Integer var = ? 在-128 至 127 之间的赋值，Integer 对象是在 IntegerCache.cache 产生，
会复用已有对象，这个区间内的 Integer 值可以直接使用== 进行判断，但是这个区间之外的所有数据，都
会在堆上产生，并不会复用已有对象，这是一个大坑，推荐使用 equals 方法进行判断。
3.【强制】浮点数之间的等值判断，基本数据类型不能用==来比较，包装数据类型不能用 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
}
正例：
(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©;
if (x.compareTo(y) == 0) {
System.out.println(“true”);
}
4.【强制】如上所示 BigDecimal 的等值比较应使用 compareTo()方法，而不是 equals()方法。
说明：equals()方法会比较值和精度（1.0 与 1.00 返回结果为 false），而 compareTo()则会忽略精度。
5.【强制】禁止使用构造方法 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);
6.关于基本数据类型与包装数据类型的使用标准如下：
1）【强制】所有的 POJO(DO、DTO、VO) 类属性必须使用包装数据类型。
2）【强制】RPC 方法的返回值和参数必须使用包装数据类型。
3）【推荐】所有的局部变量使用基本数据类型。
说明：POJO 类属性没有初值是提醒使用者在需要使用时，必须自己显式地进行赋值，任何 NPE 问题，或
者入库检查，都由使用者来保证。
正例：数据库的查询结果可能是 null，因为自动拆箱，用基本数据类型接收有 NPE 风险。
7.【强制】定义 DO/DTO/VO 等 POJO 类时，不要设定任何属性默认值。
反例：POJO 类的 createTime 默认值为 new Date()，但是这个属性在数据提取时并没有置入具体值，在
更新其它字段时又附带更新了此字段，导致创建时间被修改成当前时间。
8.【强制】构造方法里面禁止加入任何业务逻辑，如果有初始化逻辑，请放在 init 方法中。
9.【强制】POJO 类必须写 toString 方法。使用 IDE 中的工具：source> generate toString
时，如果继承了另一个 POJO 类，注意在前面加一下 super.toString。
说明：在方法执行抛出异常时，可以直接调用 POJO 的 toString()方法打印其属性值，便于排查问题。
10.【推荐】使用索引访问用 String 的 split 方法得到的数组时，需做最后一个分隔符后有无内容
的检查，否则会有抛 IndexOutOfBoundsException 的风险。
说明：
String str = “a,b,c,”;
String[] ary = str.split(",");
// 预期大于 3，结果是 3
System.out.println(ary.length);
11.【推荐】当一个类有多个构造方法，或者多个同名方法，这些方法应该按顺序放置在一起，便
于阅读，此条规则优先于下一条。
12.【推荐】类内方法定义的顺序依次是：公有方法或保护方法 > 私有方法 > getter / setter
方法。
说明：公有方法是类的调用者和维护者最关心的方法，首屏展示最好；保护方法虽然只是子类关心，也可
能是“模板设计模式”下的核心方法；而私有方法外部一般不需要特别关心，是一个黑盒实现；因为承载
的信息价值较低，所有 Service 和 DAO 的 getter/setter 方法放在类体最后。
13.【推荐】setter 方法中，参数名称与类成员变量名称一致，this.成员名 = 参数名。在
getter/setter 方法中，不要增加业务逻辑，增加排查问题的难度。
反例：
public Integer getData () {
if (condition) {
return this.data + 100; } else {
return this.data - 100; } }

日期时间

1.【强制】日期格式化时，传入 pattern 中表示年份统一使用小写的 y。
说明：日期格式化时，yyyy 表示当天所在的年，而大写的 YYYY 代表是 week in which year（JDK7 之后
引入的概念），意思是当天所在的周属于的年份，一周从周日开始，周六结束，只要本周跨年，返回的 YYYY
就是下一年。
正例：表示日期和时间的格式如下所示：
new SimpleDateFormat(“yyyy-MM-dd HH:mm:ss”)
2.【强制】在日期格式中分清楚大写的 M 和小写的 m，大写的 H 和小写的 h 分别指代的意义。
说明：日期格式中的这两对字母表意如下：
1）表示月份是大写的 M； 2）表示分钟则是小写的 m； 3） 24 小时制的是大写的 H； 4） 12 小时制的则是小写的 h。
3.【强制】获取当前毫秒数：System.currentTimeMillis(); 而不是 new Date().getTime()。
说明：如果想获取更加精确的纳秒级时间值，使用 System.nanoTime 的方式。在 JDK8 中，针对统计时间
等场景，推荐使用 Instant 类。
4.【推荐】使用枚举值来指代月份。如果使用数字，注意 Date，Calendar 等日期相关类的月份
month 取值在 0-11 之间。
说明：参考 JDK 原生注释，Month value is 0-based. e.g., 0 for January.
正例： Calendar.JANUARY，Calendar.FEBRUARY，Calendar.MARCH 等来指代相应月份来进行传参或
比较。

集合处理

1.【强制】在使用 java.util.stream.Collectors 类的 toMap()方法转为 Map 集合时，一定要使
用含有参数类型为 BinaryOperator，参数名为 mergeFunction 的方法，否则当出现相同 key
值时会抛出 IllegalStateException 异常。
说明：参数 mergeFunction 的作用是当出现 key 重复时，自定义对 value 的处理策略。
正例：
List> pairArrayList = new ArrayList<>(3);
pairArrayList.add(new Pair<>(“version”, 12.10));
pairArrayList.add(new Pair<>(“version”, 12.19));
pairArrayList.add(new Pair<>(“version”, 6.28));
Map map = pairArrayList.stream().collect(
// 生成的 map 集合中只有一个键值对：{version=6.28}
Collectors.toMap(Pair::getKey, Pair::getValue, (v1, v2) -> v2));
反例：
String[] departments = new String[] {“iERP”, “iERP”, “EIBU”};
// 抛出 IllegalStateException 异常
Map map = Arrays.stream(departments) .collect(Collectors.toMap(String::hashCode, str -> str));
2.【强制】在使用 java.util.stream.Collectors 类的 toMap()方法转为 Map 集合时，一定要注
意当 value 为 null 时会抛 NPE 异常。
说明：在 java.util.HashMap 的 merge 方法里会进行如下的判断：
if (value == null || remappingFunction == null)
throw new NullPointerException();
反例：
List> pairArrayList = new ArrayList<>(2);
pairArrayList.add(new Pair<>(“version1”, 8.3));
pairArrayList.add(new Pair<>(“version2”, null));
Map map = pairArrayList.stream().collect(
// 抛出 NullPointerException 异常
Collectors.toMap(Pair::getKey, Pair::getValue, (v1, v2) -> v2));
3.【强制】使用集合转数组的方法，必须使用集合的 toArray(T[] array)，传入的是类型完全一
致、长度为 0 的空数组。
反例：直接使用 toArray 无参方法存在问题，此方法返回值只能是 Object[]类，若强转其它类型数组将出现
ClassCastException 错误。
正例：
List list = new ArrayList<>(2);
list.add(“guan”);
list.add(“bao”);
String[] array = list.toArray(new String[0]);
4.【强制】在使用 Collection 接口任何实现类的 addAll()方法时，都要对输入的集合参数进行
NPE 判断。
说明：在 ArrayList#addAll 方法的第一行代码即 Object[] a = c.toArray(); 其中 c 为输入集合参数，如果
为 null，则直接抛出异常。
5.【强制】使用工具类 Arrays.asList()把数组转换成集合时，不能使用其修改集合相关的方法，
它的 add/remove/clear 方法会抛出 UnsupportedOperationException 异常。
说明：asList 的返回对象是一个 Arrays 内部类ArrayList，继承了AbstractList，它的默认add、remove等方法会抛出UnsupportedOperationException。Arrays.asList 体现的是适配
器模式，只是转换接口，后台的数据仍是数组。
String[] str = new String[] { “chen”, “yang”, “hao” };
List list = Arrays.asList(str);
第一种情况：list.add(“yangguanbao”); 运行时异常UnsupportedOperationException
第二种情况：str[0] = “change”; 修改了数组，list也会随之修改，反之亦然。
6.【推荐】集合初始化时，指定集合初始值大小。
说明：HashMap 使用 HashMap(int initialCapacity) 初始化，如果暂时无法确定集合大小，那么指定默
认值（16）即可。
正例：initialCapacity = (需要存储的元素个数 / 负载因子) + 1。注意负载因子（即 loader factor）默认
为 0.75，如果暂时无法确定初始值大小，请设置为 16（即默认值）。
反例： HashMap 需要放置 1024 个元素，由于没有设置容量初始大小，随着元素增加而被迫不断扩容，
resize()方法总共会调用 8 次，反复重建哈希表和数据迁移。当放置的集合元素个数达千万级时会影响程序
性能。
7.【推荐】使用 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 值组合集合。
8.【推荐】高度注意 Map 类集合 K/V 能不能存储 null 值的情况，如下表格：
集合类 Key Value Super 说明
Hashtable 不允许为 null 不允许为 null Dictionary 线程安全
ConcurrentHashMap 不允许为 null 不允许为 null AbstractMap 锁分段技术（JDK8:CAS）
TreeMap 不允许为 null 允许为 null AbstractMap 线程不安全
HashMap 允许为 null 允许为 null AbstractMap 线程不安全
反例：由于 HashMap 的干扰，很多人认为 ConcurrentHashMap 是可以置入 null 值，而事实上，存储
null 值时会抛出 NPE 异常。

并发处理

1.【强制】创建线程或线程池时请指定有意义的线程名称，方便出错时回溯。
正例：自定义线程工厂，并且根据外部特征进行分组，比如，来自同一机房的调用，把机房编号赋值给

public class UserThreadFactory implements ThreadFactory {
            private final String namePrefix;
            private final AtomicInteger nextId = new AtomicInteger(1);

            // 定义线程组名称，在利用 jstack 来排查问题时，非常有帮助
            UserThreadFactory(String whatFeatureOfGroup) {
                namePrefix = "From UserThreadFactory's " + whatFeatureOfGroup + "-Worker-";
            }

            @Override
            public Thread newThread(Runnable task) {
                String name = namePrefix + nextId.getAndIncrement();
                Thread thread = new Thread(null, task, name, 0);
                System.out.println(thread.getName());
                return thread;
            }
        }

2.【强制】线程资源必须通过线程池提供，不允许在应用中自行显式创建线程。
说明：线程池的好处是减少在创建和销毁线程上所消耗的时间以及系统资源的开销，解决资源不足的问题。
如果不使用线程池，有可能造成系统创建大量同类线程而导致消耗完内存或者“过度切换”的问题。
3.【强制】线程池不允许使用 Executors 去创建，而是通过 ThreadPoolExecutor 的方式，这
样的处理方式让写的同学更加明确线程池的运行规则，规避资源耗尽的风险。
说明：Executors 返回的线程池对象的弊端如下： 1） FixedThreadPool 和 SingleThreadPool：
允许的请求队列长度为 Integer.MAX_VALUE，可能会堆积大量的请求，从而导致 OOM。 2） CachedThreadPool：
允许的创建线程数量为 Integer.MAX_VALUE，可能会创建大量的线程，从而导致 OOM。
4.【强制】SimpleDateFormat 是线程不安全的类，一般不要定义为 static 变量，如果定义为 static，
必须加锁，或者使用 DateUtils 工具类。
正例：注意线程安全，使用 DateUtils。亦推荐如下处理：

private static final ThreadLocal df = new ThreadLocal() {
	@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.【强制】高并发时，同步调用应该去考量锁的性能损耗。能用无锁数据结构，就不要用锁；能
锁区块，就不要锁整个方法体；能用对象锁，就不要用类锁。
说明：尽可能使加锁的代码块工作量尽可能的小，避免在锁代码块中调用 RPC 方法。
7.【强制】在使用阻塞等待获取锁的方式中，必须在 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();
        }

8.【强制】在使用尝试机制来获取锁的方式中，进入业务代码块之前，必须先判断当前线程是否
持有锁。锁的释放规则与锁的阻塞等待方式相同。
说明：Lock 对象的 unlock 方法在执行时，它会调用 AQS 的 tryRelease 方法（取决于具体实现类），如果
当前线程不持有锁，则抛出 IllegalMonitorStateException 异常。
正例：

Lock lock = new XxxLock();
// ...
        boolean isLocked = lock.tryLock();
        if (isLocked) {
            try {
                doSomething();
                doOthers();
            } finally {
                lock.unlock();
            } }

9.【强制】并发修改同一记录时，避免更新丢失，需要加锁。要么在应用层加锁，要么在缓存加
锁，要么在数据库层使用乐观锁，使用 version 作为更新依据。
说明：如果每次访问冲突概率小于 20%，推荐使用乐观锁，否则使用悲观锁。乐观锁的重试次数不得小于
3 次。
10.【推荐】资金相关的金融敏感信息，使用悲观锁策略。
说明：乐观锁在获得锁的同时已经完成了更新操作，校验逻辑容易出现漏洞，另外，乐观锁对冲突的解决策
略有较复杂的要求，处理不当容易造成系统压力或数据异常，所以资金相关的金融敏感信息不建议使用乐观
锁更新。
正例：悲观锁遵循一锁、二判、三更新、四释放的原则。
11.【推荐】避免 Random 实例被多线程使用，虽然共享该实例是线程安全的，但会因竞争同一 seed
导致的性能下降。
说明：Random 实例包括 java.util.Random 的实例或者 Math.random()的方式。
正例：在 JDK7 之后，可以直接使用 API ThreadLocalRandom，而在 JDK7 之前，需要编码保证每个线
程持有一个单独的 Random 实例。

控制语句

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

2.【强制】三目运算符 condition? 表达式 1 : 表达式 2 中，高度注意表达式 1 和 2 在类型对齐
时，可能抛出因自动拆箱导致的 NPE 异常。
说明：以下两种场景会触发类型对齐的拆箱操作：
1）表达式 1 或表达式 2 的值只要有一个是原始类型。
2）表达式 1 或表达式 2 的值的类型不一致，会强制拆箱升级成表示范围更大的那个类型。
反例：
Integer a = 1;
Integer b = 2;
Integer c = null;
Boolean flag = false;
// ab 的结果是 int 类型，那么 c 会强制拆箱成 int 类型，抛出 NPE 异常
Integer result=(flag? ab : c);
3.【推荐】当某个方法的代码总行数超过 10 行时，return / throw 等中断逻辑的右大括号后均
需要加一个空行。
说明：这样做逻辑清晰，有利于代码阅读时重点关注。
4.【推荐】表达异常的分支时，少用 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("可以先交往一段时间看看");
        }

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

正例：
// 伪代码如下
        final boolean existed = (file.open(fileName, "w") != null) && (...) || (...);
        if (existed) {
...
        }
        反例：
        public final void acquire ( long arg) {
            if (!tryAcquire(arg) &&
                    acquireQueued(addWaiter(Node.EXCLUSIVE), arg)) {
                selfInterrupt();
            }

注释规约

1.【强制】类、类属性、类方法的注释必须使用 Javadoc 规范，使用/*内容/格式，不得使用
// xxx 方式。
说明：在 IDE 编辑窗口中，Javadoc 方式会提示相关注释，生成 Javadoc 可以正确输出相应注释
2.【强制】所有的抽象方法（包括接口中的方法）必须要用 Javadoc 注释、除了返回值、参数、
异常说明外，还必须指出该方法做什么事情，实现什么功能。
说明：对子类的实现要求，或者调用注意事项，请一并说明。
3.

java开发规约

Java相关栏目本月热门文章