阿里巴巴 Java 开发手册：精华提炼

很多公司直接拿阿里的开发手册当团队规范，它能在 GitHub 上拿到 20k+ star，说明确实戳中了很多人的痛点。

但手册原文很长，这里只提炼最核心、平时最容易踩坑的几条。

命名规约

永远不要用单字母变量名

// ❌ 除非是循环变量 i/j/k
int n;            // 什么 n？
String s;         // 什么 s？

// ✅ 正确的做法
int userCount;    // 用户数
String userName;  // 用户名

POJO 类的 Boolean 字段不要加 is 前缀

这是阿里规范里容易搞混的一条：

// ❌ 数据库/JavaBean 规范要求的 is 前缀，在这里反而画蛇添足
public class User {
    private Boolean isDeleted;  // 编译器会生成 getIsDeleted()
}

// ✅ 让框架自己去处理
public class User {
    private Boolean deleted;    // 直接 deleted，框架会生成 isDeleted()
}

常量规约

不许出现魔法值

// ❌ 魔法值：数字直接写代码里
if (status == 0) { ... }
for (int i = 0; i < 100; i++) { ... }
return "SUCCESS";

// ✅ 用常量替代
private static final int STATUS_PENDING = 0;
private static final int MAX_RETRY = 100;
private static final String CODE_SUCCESS = "SUCCESS";

if (status == STATUS_PENDING) { ... }

魔法值的问题在于：改了一个地方，漏了另一个地方，bug 就来了。

集合规约

不要返回 null，返回空集合

// ❌ 返回 null，调用方稍不留神就 NPE
public List<User> getUsers() {
    return null; // 千万别这样
}

// ✅ 返回空集合，调用方可以安全遍历
public List<User> getUsers() {
    return Collections.emptyList();
}

// ✅ 或者用 Optional
public Optional<List<User>> getUsers() {
    return Optional.empty();
}

使用工具类判断集合为空

// ❌ 不要自己写
if (list != null && list.size() > 0) { ... }

// ✅ 用 Apache Commons 或 Spring
if (CollectionUtils.isNotEmpty(list)) { ... }

OOP 规约

所有浮点数比较用 BigDecimal

// ❌ 浮点数比较是个坑
double a = 0.7;
double b = 0.3;
System.out.println((a - b) == 0.4); // false！

// ✅ 用 BigDecimal
BigDecimal aBD = new BigDecimal("0.7");
BigDecimal bBD = new BigDecimal("0.3");
System.out.println(aBD.subtract(bBD).compareTo(new BigDecimal("0.4")) == 0); // true

不要在 foreach 循环里 remove/add

List<String> list = new ArrayList<>(Arrays.asList("a", "b", "c"));

// ❌ 并发修改异常
for (String item : list) {
    if (item.equals("b")) {
        list.remove(item);
    }
}

// ✅ 用 Iterator
Iterator<String> it = list.iterator();
while (it.hasNext()) {
    if (it.next().equals("b")) {
        it.remove();
    }
}

// ✅ 或者用 removeIf（JDK 8+）
list.removeIf(item -> item.equals("b"));

异常规约

捕获异常后必须处理

// ❌ 吞掉异常
try {
    doSomething();
} catch (Exception e) { }

// ✅ 至少打印日志
try {
    doSomething();
} catch (Exception e) {
    log.error("doSomething failed", e);
}

控制语句

switch 必须有 default

switch (status) {
    case 0:
        doThingA();
        break;
    case 1:
        doThingB();
        break;
    default:
        throw new IllegalStateException("Unknown status: " + status);
}

避免否定条件

// ❌ 双重否定，读起来绕
if (!user.isNotGuest()) { ... }

// ✅ 肯定条件更直观
if (user.isGuest()) { ... }

阿里规范的价值

阿里的开发手册本质上是在总结踩坑经验。很多条款的背后都是一个真实的生产 bug：

• 魔法值 → 配置改漏了
• 浮点数直接比较 → 金额计算出错
• 返回 null → 空指针告警

所以与其把这些当教条，不如把它们当作别人用生产故障换来的教训。

手册是起点，不是终点。理解背后的原因，比死记硬背更重要。