编码规范

1. 浮点数之间的等值判断，基本数据类型不能使用 == 进行比较，包装数据类型不能使用 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(c);
if (x.compareTo(y) == 0) {
System.out.println("true");
}

2. BigDecimal 的等值比较应使用 compareTo() 方法，而不是 equals() 方法。
说明：equals() 方法会比较值和精度（1.0 与 1.00 返回结果为 false），而 compareTo() 则会忽略精度。
    
3. 禁止使用构造方法 BigDecimal(double) 的方式把 double 值转化为 BigDecimal 对象。
说明：BigDecimal(double) 存在精度损失风险，在精确计算或值比较的场景中可能会导致业务逻辑异常。如：
BigDecimal g = new BigDecimal(0.1F)；实际的存储值为：0.100000001490116119384765625
正例：优先推荐入参为 String 的构造方法，或使用 BigDecimal 的 valueOf 方法，此方法内部其实执行了 Double 的
toString，而 Double 的 toString 按 double 的实际能表达的精度对尾数进行了截断。
BigDecimal recommend1 = new BigDecimal("0.1");
BigDecimal recommend2 = BigDecimal.valueOf(0.1)
    
4. 关于基本数据类型与包装数据类型的使用标准如下：
1）【强制】所有的 POJO 类属性必须使用包装数据类型。
2）【强制】RPC 方法的返回值和参数必须使用包装数据类型。
3）【推荐】所有的局部变量使用基本数据类型。
Java 开发手册（黄山版）
8/51
说明：POJO 类属性没有初值是提醒使用者在需要使用时，必须自己显式地进行赋值，任何 NPE 问题，或者入库检查，
都由使用者来保证。
正例：数据库的查询结果可能是 null，因为自动拆箱，用基本数据类型接收有 NPE 风险。
反例：某业务的交易报表上显示成交总额涨跌情况，即正负 x%，x 为基本数据类型，调用的 RPC 服务，调用不成功时，
返回的是默认值，页面显示为 0%，这是不合理的，应该显示成中划线-。所以包装数据类型的 null 值，能够表示额外的
信息，如：远程调用失败，异常退出。
   
5. 定义 DO / PO / DTO / VO 等 POJO 类时，不要设定任何属性默认值。
反例：某业务的 DO 的 createTime 默认值为 new Date()；但是这个属性在数据提取时并没有置入具体值，在更新其
它字段时又附带更新了此字段，导致创建时间被修改成当前时间。
    
6. 构造方法里面禁止加入任何业务逻辑，如果有初始化逻辑，请放在 init 方法中。
    
7. POJO 类必须写 toString 方法。使用 IDE 中的工具 source > generate toString 时，如果继
承了另一个 POJO 类，注意在前面加一下 super.toString()。
说明：在方法执行抛出异常时，可以直接调用 POJO 的 toString() 方法打印其属性值，便于排查问题。
    
8. 使用索引访问用 String 的 split 方法得到的数组时，需做最后一个分隔符后有无内容的检查，
否则会有抛 IndexOutOfBoundsException 的风险。
说明：
String str = "a,b,c,,";
String[] ary = str.split(",");
// 预期大于 3，结果等于 3
System.out.println(ary.length);

9. 类成员与方法访问控制从严：
1）如果不允许外部直接通过 new 来创建对象，那么构造方法必须是 private。
2）工具类不允许有 public 或 default 构造方法。
3）类非 static 成员变量并且与子类共享，必须是 protected。
4）类非 static 成员变量并且仅在本类使用，必须是 private。
5）类 static 成员变量如果仅在本类使用，必须是 private。
6）若是 static 成员变量，考虑是否为 final。
7）类成员方法只供类内部调用，必须是 private。
8）类成员方法只对继承类公开，那么限制为 protected。
说明：任何类、方法、参数、变量，严控访问范围。过于宽泛的访问范围，不利于模块解耦。思考：如果是一个
private 的方法，想删除就删除，可是一个 public 的 service 成员方法或成员变量，删除一下，不得手心冒点汗吗？
变量像自己的小孩，尽量在自己的视线内，变量作用域太大，无限制的到处跑，那么你会担心的。
    
10. 日期格式化时，传入 pattern 中表示年份统一使用小写的 y。
说明：日期格式化时，yyyy 表示当天所在的年，而大写的 YYYY 代表是 week in which year（JDK7 之后引入的概念），
意思是当天所在的周属于的年份，一周从周日开始，周六结束，只要本周跨年，返回的 YYYY 就是下一年。
正例：表示日期和时间的格式如下所示：
new SimpleDateFormat("yyyy-MM-dd HH:mm:ss")
反例：某程序员因使用 YYYY/MM/dd 进行日期格式化，2017/12/31 执行结果为 2018/12/31，造成线上故障。
    
11. 禁止在程序中写死一年为 365 天，避免在公历闰年时出现日期转换错误或程序逻辑错误。
正例：
// 获取今年的天数
int daysOfThisYear = LocalDate.now().lengthOfYear();
// 获取指定某年的天数
LocalDate.of(2011, 1, 1).lengthOfYear();
反例：
// 第一种情况：在闰年 366 天时，出现数组越界异常
int[] dayArray = new int[365];
// 第二种情况：一年有效期的会员制，2020 年 1 月 26 日注册，硬编码 365 返回的却是 2021 年 1 月 25 日
Calendar calendar = Calendar.getInstance();
calendar.set(2020, 1, 26);
calendar.add(Calendar.DATE, 365);

12. 关于 hashCode 和 equals 的处理，遵循如下规则：
1）只要覆写 equals，就必须覆写 hashCode。
2）因为 Set 存储的是不重复的对象，依据 hashCode 和 equals 进行判断，所以 Set 存储的对象必须覆写这两种方法。
3）如果自定义对象作为 Map 的键，那么必须覆写 hashCode 和 equals。
说明：String 因为覆写了 hashCode 和 equals 方法，所以可以愉快地将 String 对象作为 key 来使用。
    
13. 判断所有集合内部的元素是否为空，使用 isEmpty() 方法，而不是 size() == 0 的方式。
说明：在某些集合中，前者的时间复杂度为 O(1)，而且可读性更好。
正例：
Map<String, Object> map = new HashMap<>(16);
if (map.isEmpty()) {
System.out.println("no element in this map.");
}

14. 在使用 java.util.stream.Collectors 类的 toMap() 方法转为 Map 集合时，一定要注意当 value
为 null 时会抛 NPE 异常。
说明：在 java.util.HashMap 的 merge 方法里会进行如下的判断：
if (value == null || remappingFunction == null)
throw new NullPointerException();
反例：
List<Pair<String, Double>> pairArrayList = new ArrayList<>(2);
pairArrayList.add(new Pair<>("version1", 8.3));
pairArrayList.add(new Pair<>("version2", null));
// 抛出 NullPointerException 异常
Map<String, Double> map = pairArrayList.stream()
.collect(Collectors.toMap(Pair::getKey, Pair::getValue, (v1, v2) -> v2));

15. ArrayList 的 subList 结果不可强转成 ArrayList，否则会抛出 ClassCastException 异常：
java.util.RandomAccessSubList cannot be cast to java.util.ArrayList。
说明：subList() 返回的是 ArrayList 的内部类 SubList，并不是 ArrayList 本身，而是 ArrayList 的一个视图，对于
SubList 的所有操作最终会反映到原列表上。
    
16. 在 subList 场景中，高度注意对父集合元素的增加或删除，均会导致子列表的遍历、增加、删
除产生 ConcurrentModificationException 异常。
说明：抽查表明，90% 的程序员对此知识点都有错误的认知。
    
17. 使用集合转数组的方法，必须使用集合的 toArray(T[] array)，传入的是类型完全一致、长度为
0 的空数组。
反例：直接使用 toArray 无参方法存在问题，此方法返回值只能是 Object[]类，若强转其它类型数组将出现
ClassCastException 错误。
正例：
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 正在变大的情况下，负面影响与 2 相同。
4）大于 size，空间浪费，且在 size 处插入 null 值，存在 NPE 隐患。

18. 使用工具类 Arrays.asList() 把数组转换成集合时，不能使用其修改集合相关的方法，它的 add
/ remove / clear 方法会抛出 UnsupportedOperationException 异常。
说明：asList 的返回对象是一个 Arrays 内部类，并没有实现集合的修改方法。Arrays.asList 体现的是适配器模式，只
是转换接口，后台的数据仍是数组,指向的仍是同一个对象。
String[] str = new String[]{ "yang", "guan", "bao" };
List list = Arrays.asList(str);
第一种情况：list.add("yangguanbao"); 运行时异常。
第二种情况：str[0] = "change"; list 中的元素也会随之修改，反之亦然。
    
19. 不要在 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();
}
}
反例：
for (String item : list) {
if ("1".equals(item)) {
list.remove(item);
}
}

20. 集合初始化时，指定集合初始值大小。
说明：HashMap 使用构造方法 HashMap(int initialCapacity) 进行初始化时，如果暂时无法确定集合大小，那么指
定默认值（16）即可。
正例：initialCapacity = (需要存储的元素个数 / 负载因子) + 1。注意负载因子（即 loaderfactor）默认为 0.75，如果
暂时无法确定初始值大小，请设置为 16（即默认值）。
反例：HashMap 需要放置 1024 个元素，由于没有设置容量初始大小，随着元素增加而被迫不断扩容，resize() 方法
总共会调用 8 次，反复重建哈希表和数据迁移。当放置的集合元素个数达千万级时会影响程序性能。
    
21. 使用 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 值组合的 Set 集合。

22. 高度注意 Map 类集合 K / V 能不能存储 null 值的情况，如下表格：

23. 获取单例对象需要保证线程安全，其中的方法也要保证线程安全。
说明：资源驱动类、工具类、单例工厂类都需要注意。

24. 创建线程或线程池时请指定有意义的线程名称，方便出错时回溯。
正例：自定义线程工厂，并且根据外部特征进行分组，比如，来自同一机房的调用，把机房编号赋值给
whatFeatureOfGroup：
public class UserThreadFactory implements ThreadFactory {
private final String namePrefix;
private final AtomicInteger nextId = new AtomicInteger(1);
// 定义线程组名称，在利用 jstack 来排查问题时，非常有帮助
UserThreadFactory(String whatFeatureOfGroup) {
namePrefix = "FromUserThreadFactory's" + whatFeatureOfGroup + "-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;
}
}

25. 在使用阻塞等待获取锁的方式中，必须在 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();
}

26. 并发修改同一记录时，避免更新丢失，需要加锁。要么在应用层加锁，要么在缓存加锁，要么
在数据库层使用乐观锁，使用 version 作为更新依据。
说明：如果每次访问冲突概率小于 20%，推荐使用乐观锁，否则使用悲观锁。乐观锁的重试次数不得小于 3 次。

27. 避免 Random 实例被多线程使用，虽然共享该实例是线程安全的，但会因竞争同一 seed 导致
的性能下降。
说明：Random 实例包括 java.util.Random 的实例或者 Math.random() 的方式。
正例：在 JDK7 之后，可以直接使用 API ThreadLocalRandom，而在 JDK7 之前，需要编码保证每个线程持有一个
单独的 Random 实例。

通过双重检查锁（double-checked locking），实现延迟初始化需要将目标属性声明为
volatile 型，（比如修改 helper 的属性声明为 private volatile Helper helper = null;）。
正例：
public class LazyInitDemo {
private volatile Helper helper = null;
public Helper getHelper() {
if (helper == null) {
synchronized(this) {
if (helper == null) {
helper = new Helper();
}
}
}
return helper;
}
// other methods and fields...

28. 当 switch 括号内的变量类型为 String 并且此变量为外部参数时，必须先进行 null 判断。
反例：如下的代码输出是什么？
    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");
        }
    }
 
29. 在高并发场景中，避免使用“等于”判断作为中断或退出的条件。
说明：如果并发控制没有处理好，容易产生等值判断被“击穿”的情况，使用大于或小于的区间判断条件来代替。
反例：判断剩余奖品数量等于 0 时，终止发放奖品，但因为并发处理错误导致奖品数量瞬间变成了负数，这样的话，
活动无法终止。

30. 服务端发生错误时，返回给前端的响应信息必须包含 HTTP 状态码，errorCode、
errorMessage、用户提示信息四个部分。
说明：四个部分的涉众对象分别是浏览器、前端开发、错误排查人员、用户。其中输出给用户的提示信息要求：简短清
晰、提示友好，引导用户进行下一步操作或解释错误原因，提示信息可以包括错误原因、上下文环境、推荐操作等。
errorCode：参考 。errorMessage：简要描述后端出错原因，便于错误排查人员快速定位问题，注意不要包含敏
感数据信息。
正例：常见的 HTTP 状态码如下
1）200 OK：表明该请求被成功地完成，所请求的资源发送到客户端。
2）401 Unauthorized：请求要求身份验证，常见对于需要登录而用户未登录的情况。
3）403 Forbidden：服务器拒绝请求，常见于机密信息或复制其它登录用户链接访问服务器的情况。
4）404 NotFound：服务器无法取得所请求的网页，请求资源不存在。
5）500 InternalServerError：服务器内部错误。

31. 在使用正则表达式时，利用好其预编译功能，可以有效加快正则匹配速度。
说明：不要在方法体内定义：Pattern pattern = Pattern.compile("规则");
正确:public class MyClass{
    private static final Pattern pattern = Pattern.compile("规则");

    static
    {
        // 初始化代码块，在类加载时运行，预编译正则表达式
    }

    public static void myMethod(String str)
    {
        // 使用预编译的Pattern对象进行匹配
        Matcher matcher = pattern.matcher(str);
        // ...
    }
}
    
32. 错误码分为一级宏观错误码、二级宏观错误码、三级宏观错误码。
说明：在无法更加具体确定的错误场景中，可以直接使用一级宏观错误码，分别是：A0001（用户端错误）、B0001（系
统执行出错）、C0001（调用第三方服务出错）。
正例：调用第三方服务出错是一级，中间件错误是二级，消息服务出错是三级。

33. 好的单元测试必须遵守 AIR 原则。
说明：单元测试在线上运行时，感觉像空气（AIR）一样感觉不到，但在测试质量的保障上，却是非常关键的。好的单元
测试宏观上来说，具有自动化、独立性、可重复执行的特点。
⚫ A：Automatic（自动化）
⚫ I：Independent（独立性）
⚫ R：Repeatable（可重复）
    
34. 用户请求传入的任何参数必须做有效性验证。
说明：忽略参数校验可能导致：
⚫ 页面 page size 过大导致内存溢出
⚫ 恶意 order by 导致数据库慢查询
⚫ 缓存击穿
⚫ SSRF
⚫ 任意重定向
⚫ SQL 注入，Shell 注入，反序列化注入
⚫ 正则输入源串拒绝服务 ReDoS
扩展：Java 代码用正则来验证客户端的输入，有些正则写法验证普通用户输入没有问题，但是如果攻击人员使
用的是特殊构造的字符串来验证，有可能导致死循环的结果。

35. 对于文件上传功能，需要对于文件大小、类型进行严格检查和控制。
说明：攻击者可以利用上传漏洞，上传恶意文件到服务器，并且远程执行，达到控制网站服务器的目的。
    
36. 配置文件中的密码需要加密。
    
37. 小数类型为 decimal，禁止使用 float 和 double。
说明：在存储的时候，float 和 double 都存在精度损失的问题，很可能在比较值的时候，得到不正确的结果。如果存
储的数据范围超过 decimal 的范围，建议将数据拆成整数和小数并分开存储。

本栏目推荐文章
• ASCII编码：计算机文本通信的基石
• 基于正则化的图自编码器在推荐算法中的应用 Application of graph auto-encoders based on regularization in recommendation algorithms
• Base64编码：数据传输的安全使者
• Unicode编码：打破语言壁垒，实现无缝交流
• iMessage群发,iMessage群发软件,iMessage群发软件开发(程序编码篇)
• 在线Base64编码/加密/解密工具
• 使用Java编写的URL编码示例
• 在mac上转换txt文件编码方式
• 大模型RAG之向量检索技术-结合LSTM模型编码
• [转帖]Oracle中unicode的几种不同字符编码模式