

大家好，我是晚安code。

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

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



![规矩不是凭空来的，每条都是别人真金白银踩过的坑](https://developer.qcloudimg.com/http-save/yehe-12591818/0dbe76becc4fca16899d56064c559f7e.png)

## 一、命名：别让名字埋雷（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")   // 反例：跨年必翻车
```

![](https://developer.qcloudimg.com/http-save/yehe-12591818/86f545eecd439fa56ddd7092c9723888.webp)



![YYYY 是"这一周属于哪一年"，跨年那一周最容易中招](https://developer.qcloudimg.com/http-save/yehe-12591818/e67d2534e20dbef66885a5de40a8e560.png)

**坑 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));
```

![](https://developer.qcloudimg.com/http-save/yehe-11608098/5046e0c5aaa6423c4a43ca667a9321db.webp)



![foreach 底层是 Iterator，改集合结构就会抛异常](https://developer.qcloudimg.com/http-save/yehe-12591818/f5937b8f78306c0628e066b7122a2f63.png)

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

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

![](https://developer.qcloudimg.com/http-save/yehe-11608098/1fe12c9417704840dadac22e53fa340e.webp)

**坑 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）**：预先创建一批线程复用来执行任务的技术。可以理解为「工地上随时待命的搬运工」。

![Java编程规范避坑：线程池 Executors 快捷创建导致 OOM 的错误链路，与 ThreadPoolExecutor 手写有界队列的正确链路对比](https://developer.qcloudimg.com/http-save/yehe-12591818/02249a1d19e89aa4c992f97dc1eeecf7.png)

![](https://developer.qcloudimg.com/http-save/yehe-12591818/90a5096f35fb8fe98c3f009a81a067aa.webp)

**坑 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 条规约里，你亲自踩过哪一个？踩的时候排查了多久？


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

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

Java编程规范避坑指南：读阿里《Java开发手册》，把 15 条最容易造成线上故障的强制规约整理成清单，覆盖命名、日期、集合、并发，照着改能少踩一个坑。

编程语言

后端

职业发展

Java编程规范避坑指南：阿里《Java开发手册》15条强制规约实战解析，覆盖命名、日期数值、集合、并发、数据层五大高频翻车场景。从Boolean字段is前缀陷阱到YYYY跨年bug，从线程池OOM到Long精度丢失，每条配反例和事故场景，助你快速掌握Java开发最佳实践。

代码解释

数据库

JSON

Java

腾讯云BI特惠9.9元起！


文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

Java编程规范避坑指南：阿里开发手册15条强制规约实战解析-腾讯云开发者社区-腾讯云

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

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

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐