Java编程规范避坑指南：阿里开发手册15条强制规约实战解析

大家好，我是晚安code。

说到 Java编程规范，很多同学第一反应是"条条框框，烦死了"。但阿里《Java 开发手册》里的【强制】规约，几乎每一条都是拿线上故障换来的（以 1.7.1 黄山版、2022 年 2 月版本为准）。

这篇我把手册里最容易让项目翻车的 15 条【强制】规约筛出来，按命名、日期数值、集合、并发、数据层五类整理成一份避坑清单，每条都配反例和事故场景。建议先收藏，下次 code review 前翻一遍。

一、命名：别让名字埋雷（Java命名规范）

命名不只是好不好看的问题------名字起错，框架解析都可能翻车。这套 Java 命名规范里有三条最致命：

坑 1：Boolean 字段加 is 前缀。 反例是 private Boolean isDeleted，getter 自动生成 isDeleted()，序列化时框架反解析"误以为"字段叫 deleted，结果字段直接丢失，前端拿到的 JSON 里永远少这一个。正确写法是 private Boolean deleted。

坑 2：拼音和英文混排。 反例 DaZhePromotion（打折）、getPingfenByName()（评分），读代码跟猜谜一样。手册明确要求：命名用完整英文单词组合，纯拼音也不行。

坑 3：魔法值直接写死。 有次我 debug 一个缓存查不到的 bug 查了一下午，最后发现是两个 key 一个带了下划线一个没带------开发者 A 写 "Id#taobao_" + tradeId，开发者 B 复制时少了个下划线。这就是魔法值的代价：

java 复制代码

// 反例：魔法值直接写死，复制时少个下划线就出事故
String key = "Id#taobao_" + tradeId;
// 正确：定义成常量
public static final String CACHE_KEY_PREFIX = "Id#taobao_";

魔法值（Magic Number）：直接硬编码在代码里、没有任何说明的常量。就像卷子上随手写的中间结果，只有出题人自己看得懂。

二、日期与数值：翻车率最高的两类（Java日期格式化、Java浮点数精度）

日期和数值是 Java 里翻车率最高的两类，而且坑都很"安静"------不报错，就是结果不对。尤其是 Java 日期格式化，跨年那几天必现。

坑 4：YYYY 和 yyyy 别混。 小写 yyyy 是"当天所在的年"，大写 YYYY 是"当天所在周属于的年份"。2017 年 12 月 31 日用 YYYY-MM-dd 格式化，得到的是 2018-12-31，线上日志和报表日期全线错位。正确写法是：

java 复制代码

new SimpleDateFormat("yyyy-MM-dd HH:mm:ss")   // 正确
new SimpleDateFormat("YYYY-MM-dd HH:mm:ss")   // 反例：跨年必翻车

坑 5：SimpleDateFormat 线程不安全。 这个类不是线程安全的，别定义成 static 共享，多线程下偶发解析错乱。JDK8 之后直接换 DateTimeFormatter，官方评价就是 immutable、thread-safe。

坑 6：浮点数别用 == 比较。 二进制没法精确表示大部分小数，1.0F - 0.9F 和 0.9F - 0.8F 用 == 比，结果是 false。这就像用十进制写 1/3，永远是 0.333... 写不完。要么给个误差范围，要么用 BigDecimal：

java 复制代码

// 反例
if (a == b) { }   // a=1.0F-0.9F，b=0.9F-0.8F，结果为 false
// 正确：指定误差范围
if (Math.abs(a - b) < 1e-6F) { }

坑 7：BigDecimal 用 compareTo 不用 equals。 equals 会连精度一起比，new BigDecimal("1.0").equals(new BigDecimal("1.00")) 返回 false；compareTo 忽略精度，才是你想要的行为。另外别用 new BigDecimal(0.1)，double 入参本身就有精度损失，要用字符串构造或 valueOf。

三、集合操作：一半事故出在这（Java集合遍历）

集合操作贡献了 Java 运行时异常的一大半，而且大部分是同一个套路------边遍历边改。这一节的坑全是【强制】级：

坑 8：foreach 里删元素。 for-each 底层是 Iterator，边遍历边 list.remove，轻则元素跳过，重则直接 ConcurrentModificationException。正确做法是用 Iterator 的 remove，或 JDK8 的 removeIf：

java 复制代码

// 反例
for (String item : list) {
    if ("1".equals(item)) list.remove(item);
}
// 正确
list.removeIf(item -> "1".equals(item));

坑 9：Integer 别用 == 比较。 -128 到 127 之间有 IntegerCache 复用对象，这个区间用 == 碰巧没问题；一旦超出，每次都是新对象，== 比的是引用，两个 128 直接不相等。统一用 equals 或 Objects.equals：

java 复制代码

Integer a = 128;
Integer b = 128;
a == b;        // false！别问，问就是踩过
a.equals(b);   // true

坑 10：Arrays.asList 不能增删。 它返回的是 Arrays 内部类，add、remove、clear 一律抛 UnsupportedOperationException，而且它只是数组的"视图"，改数组或改 list 会互相影响。

坑 11：subList 不能强转 ArrayList。 subList 返回的是内部类 SubList，强转会抛 ClassCastException；它是对原列表的视图，之后你再动父集合，子列表遍历就会 ConcurrentModificationException。

四、并发：线程池和锁的坑（Java线程池）

并发场景下用 Executors 图省事，是 Java 里性价比最高的"自杀方式"。

坑 12：别用 Executors 创建线程池。 newFixedThreadPool 的队列容量是 Integer.MAX_VALUE，newCachedThreadPool 的线程数上限也是 Integer.MAX_VALUE------高并发一冲进来，任务只进不出，内存直接打爆 OOM。正确姿势是用 ThreadPoolExecutor 手写参数，配有界队列和拒绝策略：

线程池（Thread Pool）：预先创建一批线程复用来执行任务的技术。可以理解为「工地上随时待命的搬运工」。

坑 13：ThreadLocal 用完要清理。 线程池里的线程会被复用，ThreadLocal 存的值就像贴在公司工位上没撕的便签，下一个任务照样看得见。轻则数据串线，重则内存泄漏。规范要求用 try-finally 包起来，最后 remove()。

五、POJO 与接口：数据层的细节

POJO 里用基本类型，等于给 NPE 留了一扇随时会开的大门。

坑 14：POJO 属性必须用包装类型。 数据库查出来可能为 null，用基本类型 int 接收，自动拆箱当场 NPE；RPC 失败返回 null，用包装类型还能表达"调用失败"这个额外信息，页面显示一个中划线而不是错误的 0%。所以规约是：POJO 属性和 RPC 参数返回值用包装类型，局部变量才用基本类型。

POJO（Plain Old Java Object）：普通 Java 对象，通常指 DO、DTO、VO 这类承载数据的类。可以理解为「专门装数据的快递箱」。

坑 15：超大整数返回前端用 String。 Java 的 Long 最大能到 2^63-1，但 JavaScript 的 Number 只能精确表示 2^53 以内的整数。订单号 16 位以上直接丢精度------后端传 362909601374617692，前端收到 362909601374617660，前后端对不上账。有次同事调我接口，前端说订单号对不上，最后定位到就是这个原因。服务端一律用 String 返回这类超长 ID。

可能有人会问：这十几条规约，全背下来不得累死？

不用背。优先级就按【强制】>【推荐】>【参考】，先守住强制级的。剩下的交给工具：IDEA 装个 Alibaba Java Coding Guidelines 插件，写违规代码当场标红，比人肉记清单靠谱得多。我这份清单也主要是为了让你明白"每条规则背后的原因"------懂了为什么，规则自然就记住了。
可能有人会问：现在都用 LocalDateTime 了，SimpleDateFormat 的坑还重要吗？

重要。老项目迁移不是一夜之间的事，大量系统还在跑 Date + SimpleDateFormat；而且理解了它为什么线程不安全，你才能真正理解新 API 的 immutable 设计好在哪。

集合类	Key 是否允许 null	Value 是否允许 null	是否线程安全
Hashtable	不允许	不允许	是
TreeMap	不允许	允许	否
ConcurrentHashMap	不允许	不允许	是
HashMap	允许	允许	否

看这张表就明白了：很多人被 HashMap 带偏，以为 ConcurrentHashMap 也能存 null，实际存了直接 NPE。

旧 API	新 API（JDK8+）	说明
Date	Instant	时间戳
Calendar	LocalDateTime	日期时间
SimpleDateFormat	DateTimeFormatter	线程安全，不可变

说白了，这套 Java编程规范里的强制规约不是给你添麻烦，而是把别人花真金白银踩过的坑提前标了出来。写代码前多问一句"这名字规范吗、这个比较能用 == 吗"，就能省下大半年排查线上故障的时间。

我是晚安code，持续分享编程干货。觉得有用的话记得点赞收藏和关注~也欢迎在评论区聊聊：这 15 条规约里，你亲自踩过哪一个？踩的时候排查了多久？