Java 编码规范与设计：命名 / 异常处理 / 不可变对象 / 防御性编程

柏舟飞流2026-06-21 11:26

引言

好的编码规范不是教条，而是团队协作的润滑剂。一致的命名、合理的异常处理、不可变的设计、防御性的编码，这些习惯能让代码更健壮、更易维护。

一、命名规范

1.1 基本规则

类型 规范 示例
包名 全小写，点分隔 com.example.service
类名 UpperCamelCase UserService, OrderProcessor
方法名 lowerCamelCase findByName, calculateTotal
变量名 lowerCamelCase userName, orderCount
常量 UPPER_SNAKE_CASE MAX_RETRY_COUNT, DEFAULT_TIMEOUT
泛型 单大写字母 T, E, K, V
枚举 UpperCamelCase HttpStatus.OK

1.2 方法命名动词表

动词 含义 示例
get 获取属性 getName()
set 设置属性 setName(String)
is 布尔判断 isActive()
has 是否包含 hasPermission()
can 能力判断 canExecute()
find 查询（可能为空） findById()
list 查询列表 listByStatus()
count 计数 countByRole()
create 创建 createOrder()
update 更新 updateStatus()
delete 删除 deleteById()
save 保存（新建或更新） save(User)
validate 验证 validateInput()
convert 转换 convertToDTO()
build 构建 buildResponse()
compute 计算 computeHash()
resolve 解析/解决 resolveConflict()
handle 处理 handleException()
execute 执行 executeTask()
apply 应用 applyDiscount()

1.3 避免的命名

java 复制代码 
// ❌ 缩写不清晰
int d;                    // elapsed time in days?
String fn;                // first name? file name?

// ✅ 完整有意义的名称
int elapsedTimeInDays;
String firstName;

// ❌ 无意义后缀
String nameString;        // String 多余
int itemCountInt;         // Int 多余

// ✅ 简洁
String name;
int itemCount;

// ❌ 布尔变量不用 is/has/can
boolean flag;
boolean status;

// ✅ 布尔变量用 is/has/can
boolean isValid;
boolean hasPermission;
boolean canRetry;

// ❌ 数字后缀区分变量
String name1, name2;

// ✅ 有意义的区分
String originalName;
String modifiedName;

二、异常处理

2.1 异常分类

复制代码 
Throwable
├── Error（不应捕获）
│   ├── OutOfMemoryError
│   ├── StackOverflowError
│   └── InternalError
└── Exception
    ├── 受检异常（Checked Exception）→ 必须处理
    │   ├── IOException
    │   ├── SQLException
    │   └── InterruptedException
    └── 非受检异常（RuntimeException）→ 可选处理
        ├── NullPointerException
        ├── IllegalArgumentException
        ├── IllegalStateException
        └── IndexOutOfBoundsException

2.2 异常处理原则

java 复制代码 
// ❌ 吞掉异常
try {
    doSomething();
} catch (Exception e) {
    // 什么都不做
}

// ❌ 只打印日志不处理
try {
    doSomething();
} catch (Exception e) {
    e.printStackTrace(); // 不应该用 printStackTrace
}

// ✅ 记录日志并处理
try {
    doSomething();
} catch (IOException e) {
    log.error("Failed to read file: {}", filePath, e);
    throw new BusinessException("File read failed", e);
}

// ❌ 捕获范围过大
try {
    doSomething();
} catch (Exception e) { // 捕获所有异常
    log.error("Error", e);
}

// ✅ 捕获具体异常
try {
    doSomething();
} catch (FileNotFoundException e) {
    log.warn("File not found: {}", filePath);
    return defaultValue;
} catch (IOException e) {
    log.error("IO error reading file: {}", filePath, e);
    throw new BusinessException("File read failed", e);
}

2.3 自定义异常

java 复制代码 
// 业务异常（非受检）
public class BusinessException extends RuntimeException {
    private final String errorCode;

    public BusinessException(String message) {
        super(message);
        this.errorCode = "GENERIC_ERROR";
    }

    public BusinessException(String errorCode, String message) {
        super(message);
        this.errorCode = errorCode;
    }

    public BusinessException(String errorCode, String message, Throwable cause) {
        super(message, cause);
        this.errorCode = errorCode;
    }

    public String getErrorCode() {
        return errorCode;
    }
}

// 使用
if (balance < amount) {
    throw new BusinessException("INSUFFICIENT_BALANCE",
        "Insufficient balance: " + balance + " < " + amount);
}

2.4 try-with-resources

java 复制代码 
// ✅ 自动关闭资源（实现 AutoCloseable）
try (Connection conn = dataSource.getConnection();
     PreparedStatement stmt = conn.prepareStatement(sql);
     ResultSet rs = stmt.executeQuery()) {
    while (rs.next()) {
        // 处理结果
    }
} // 自动关闭 rs → stmt → conn

// ✅ 自定义 AutoCloseable
public class TempFile implements AutoCloseable {
    private final Path path;

    public TempFile(String prefix) throws IOException {
        this.path = Files.createTempFile(prefix, ".tmp");
    }

    public Path getPath() { return path; }

    @Override
    public void close() {
        try {
            Files.deleteIfExists(path);
        } catch (IOException e) {
            // 记录日志，不抛出
        }
    }
}

try (TempFile temp = new TempFile("data")) {
    Files.writeString(temp.getPath(), content);
    processFile(temp.getPath());
}

2.5 异常链

java 复制代码 
// ✅ 保留原始异常（cause）
public Data fetchData() {
    try {
        return readFromCache();
    } catch (CacheException e) {
        throw new BusinessException("CACHE_ERROR", "Failed to read cache", e);
    }
}

// ❌ 丢失原始异常
catch (CacheException e) {
    throw new BusinessException("Cache failed"); // 丢失了 e
}

三、不可变对象

3.1 为什么不可变

复制代码 
不可变对象的好处：
├── 线程安全：无需同步
├── 可缓存：hashCode 可预计算
├── 可共享：无需防御性复制
├── 可靠：创建后状态不变
└── 简单：减少状态管理的复杂度

Java 中的不可变示例：
├── String
├── Integer, Long 等包装类
├── BigDecimal
├── LocalDate, LocalDateTime
└── ImmutableList (Guava)

3.2 设计不可变类

java 复制代码 
public final class Money {
    private final BigDecimal amount;
    private final String currency;

    public Money(BigDecimal amount, String currency) {
        this.amount = amount;
        this.currency = Objects.requireNonNull(currency, "currency must not be null");
    }

    // 不提供 setter
    public BigDecimal getAmount() { return amount; }
    public String getCurrency() { return currency; }

    // 操作返回新对象
    public Money add(Money other) {
        if (!this.currency.equals(other.currency)) {
            throw new IllegalArgumentException("Currency mismatch");
        }
        return new Money(this.amount.add(other.amount), this.currency);
    }

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof Money)) return false;
        Money money = (Money) o;
        return amount.equals(money.amount) && currency.equals(money.currency);
    }

    @Override
    public int hashCode() {
        return Objects.hash(amount, currency);
    }

    @Override
    public String toString() {
        return amount + " " + currency;
    }
}

3.3 Record 实现不可变（Java 16+）

java 复制代码 
// Record 天然不可变
public record Money(BigDecimal amount, String currency) {
    public Money {
        Objects.requireNonNull(currency, "currency must not be null");
        if (amount.compareTo(BigDecimal.ZERO) < 0) {
            throw new IllegalArgumentException("Amount must be non-negative");
        }
    }

    public Money add(Money other) {
        if (!this.currency.equals(other.currency)) {
            throw new IllegalArgumentException("Currency mismatch");
        }
        return new Money(this.amount.add(other.amount), this.currency);
    }
}

3.4 集合不可变

java 复制代码 
// JDK 不可变集合
List<String> list = List.of("a", "b", "c");
Set<String> set = Set.of("a", "b", "c");
Map<String, Integer> map = Map.of("a", 1, "b", 2);

// ❌ 修改会抛异常
list.add("d"); // UnsupportedOperationException

// ⚠️ unmodifiableList 是视图，原集合修改会影响它
List<String> immutable = Collections.unmodifiableList(mutable);
// mutable 修改后 immutable 也会看到变化

// ✅ 真正的不可变副本
List<String> copy = List.copyOf(mutable);

四、防御性编程

4.1 参数校验

java 复制代码 
public User createUser(String name, int age, String email) {
    Objects.requireNonNull(name, "name must not be null");
    Objects.requireNonNull(email, "email must not be null");

    if (name.isBlank()) {
        throw new IllegalArgumentException("name must not be blank");
    }
    if (age < 0 || age > 150) {
        throw new IllegalArgumentException("age must be between 0 and 150");
    }
    if (!email.contains("@")) {
        throw new IllegalArgumentException("invalid email format");
    }

    return new User(name, age, email);
}

4.2 防御性复制

java 复制代码 
public class Order {
    private final List<Item> items;

    public Order(List<Item> items) {
        // ✅ 防御性复制：不直接引用外部可变对象
        this.items = new ArrayList<>(items);
    }

    public List<Item> getItems() {
        // ✅ 返回不可修改的视图或副本
        return Collections.unmodifiableList(items);
    }
}

4.3 返回空集合而非 null

java 复制代码 
// ❌ 返回 null
public List<Order> getOrdersByUser(String userId) {
    List<Order> orders = orderDao.findByUser(userId);
    return orders.isEmpty() ? null : orders; // 调用方必须 null 检查
}

// ✅ 返回空集合
public List<Order> getOrdersByUser(String userId) {
    List<Order> orders = orderDao.findByUser(userId);
    return orders; // 空集合也是合法的
}

// ✅ 使用 Optional 表示可能为空的单值
public Optional<User> findById(String id) {
    return Optional.ofNullable(userDao.selectById(id));
}

4.4 快速失败（Fail-Fast）

java 复制代码 
// 尽早暴露问题，不要让错误传播
public void processOrder(Order order) {
    Objects.requireNonNull(order, "order must not be null");
    if (order.getItems().isEmpty()) {
        throw new IllegalArgumentException("order must have at least one item");
    }
    if (order.getTotal().compareTo(BigDecimal.ZERO) <= 0) {
        throw new IllegalArgumentException("order total must be positive");
    }

    validateInventory(order);
    reserveItems(order);
    processPayment(order);
}

4.5 前置条件工具

java 复制代码 
// Guava Preconditions
Preconditions.checkNotNull(name, "name must not be null");
Preconditions.checkArgument(age >= 0, "age must be non-negative, got: %s", age);
Preconditions.checkState(isInitialized, "service not initialized");

// JDK Objects
Objects.requireNonNull(name, "name must not be null");

// 自定义验证工具
public class Validate {
    public static void isTrue(boolean expression, String message) {
        if (!expression) {
            throw new IllegalArgumentException(message);
        }
    }

    public static void notEmpty(String value, String message) {
        if (value == null || value.isBlank()) {
            throw new IllegalArgumentException(message);
        }
    }

    public static <T> void notEmpty(Collection<T> collection, String message) {
        if (collection == null || collection.isEmpty()) {
            throw new IllegalArgumentException(message);
        }
    }
}

五、代码设计原则

5.1 SOLID 原则速查

原则 含义 简述
S - 单一职责 一个类只有一个变化原因 小而专注
O - 开闭原则 对扩展开放，对修改关闭 策略/模板模式
L - 里氏替换 子类可以替换父类 不要破坏契约
I - 接口隔离 接口要小而专 不要胖接口
D - 依赖倒置 依赖抽象不依赖实现 面向接口编程

5.2 方法设计

java 复制代码 
// ✅ 方法短小（不超过 20 行）
// ✅ 单一抽象层次
// ❌ 混合抽象层次
public void process() {
    readData();       // 高层
    String line = reader.readLine(); // 低层，不应该在这里
    validateData();   // 高层
    saveData();       // 高层
}

// ✅ 统一抽象层次
public void process() {
    Data data = readData();
    validateData(data);
    saveData(data);
}

// ✅ 方法参数不超过 3 个
// ❌ 过多参数
public User create(String name, int age, String email, String phone, String address) { }

// ✅ 使用对象封装参数
public User create(CreateUserRequest request) { }

// ✅ 布尔参数用枚举替代
// ❌
sendEmail(to, subject, body, true); // true 是什么意思？
// ✅
sendEmail(to, subject, body, EmailType.HTML);

5.3 注释原则

java 复制代码 
// ❌ 无用的注释
i++; // i 加 1

// ❌ 代码已经表达的注释
// 获取用户名称
String name = user.getName();

// ✅ 解释为什么（Why），不是做什么（What）
// 使用二分查找而非线性查找，因为列表已排序且数据量大
int index = Collections.binarySearch(sortedList, target);

// ✅ 标注 TODO 和 FIXME
// TODO: 后续优化为批量查询
// FIXME: 并发场景下可能重复创建

// ✅ 公共 API 的 Javadoc
/**
 * 根据用户 ID 查找用户。
 *
 * @param userId 用户 ID，不能为 null
 * @return 用户信息，如果不存在返回 empty Optional
 * @throws IllegalArgumentException 如果 userId 为 null
 */
public Optional<User> findById(String userId) { ... }

总结

要点 建议
命名 有意义、可读、一致
异常 不吞掉、不丢失、具体捕获
不可变 优先设计不可变类
防御性 校验参数、防御性复制、返回空集合
方法 短小、单一职责、参数少
注释 解释 Why，不解释 What
快速失败 尽早暴露问题
热门推荐
01GitHub 镜像站点02AI科技热点日报 | 2026年07月01日032026 AI 编程工具终极实战指南：Cursor vs Claude Code vs Copilot，开发者该怎么选？042026 年 AI 编程工具终极横评：Cursor vs Claude Code vs Copilot vs Windsurf052026 年 AI 大模型 & AI 编程工具实战全总结06AI 编程 IDE 全景解析 2026：Agent 全面接管开发链路07幻兽帕鲁 - 服务器管理员权限与 GM 命令完全指南08【AI】2026 年具身智能模型和世界模型总结092026年7月AI圈大地震：GPT-5.6被政府限制、Claude入驻Slack、Anthropic自研芯片102026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？