agent-skills/skills/code-review-excellence/reference/java.md

Java Code Review Guide

Java 审查重点：Java 17/21 新特性、Spring Boot 3 最佳实践、并发编程（虚拟线程）、JPA 性能优化以及代码可维护性。

目录

• 现代 Java 特性 (17/21+)
• Stream API & Optional
• Spring Boot 最佳实践
• JPA 与 数据库性能
• 并发与虚拟线程
• Lombok 使用规范
• 异常处理
• 测试规范
• Review Checklist

---

现代 Java 特性 (17/21+)

Record (记录类)

// ❌ 传统的 POJO/DTO：样板代码多
public class UserDto {
    private final String name;
    private final int age;

    public UserDto(String name, int age) {
        this.name = name;
        this.age = age;
    }
    // getters, equals, hashCode, toString...
}

// ✅ 使用 Record：简洁、不可变、语义清晰
public record UserDto(String name, int age) {
    // 紧凑构造函数进行验证
    public UserDto {
        if (age < 0) throw new IllegalArgumentException("Age cannot be negative");
    }
}

Switch 表达式与模式匹配

// ❌ 传统的 Switch：容易漏掉 break，不仅冗长且易错
String type = "";
switch (obj) {
    case Integer i: // Java 16+
        type = String.format("int %d", i);
        break;
    case String s:
        type = String.format("string %s", s);
        break;
    default:
        type = "unknown";
}

// ✅ Switch 表达式：无穿透风险，强制返回值
String type = switch (obj) {
    case Integer i -> "int %d".formatted(i);
    case String s  -> "string %s".formatted(s);
    case null      -> "null value"; // Java 21 处理 null
    default        -> "unknown";
};

文本块 (Text Blocks)

// ❌ 拼接 SQL/JSON 字符串
String json = "{\n" +
              "  \"name\": \"Alice\",\n" +
              "  \"age\": 20\n" +
              "}";

// ✅ 使用文本块：所见即所得
String json = """
    {
      "name": "Alice",
      "age": 20
    }
    """;

---

Stream API & Optional

避免滥用 Stream

// ❌ 简单的循环不需要 Stream（性能开销 + 可读性差）
items.stream().forEach(item -> {
    process(item);
});

// ✅ 简单场景直接用 for-each
for (var item : items) {
    process(item);
}

// ❌ 极其复杂的 Stream 链
List<Dto> result = list.stream()
    .filter(...)
    .map(...)
    .peek(...)
    .sorted(...)
    .collect(...); // 难以调试

// ✅ 拆分为有意义的步骤
var filtered = list.stream().filter(...).toList();
// ...

Optional 正确用法

// ❌ 将 Optional 用作参数或字段（序列化问题，增加调用复杂度）
public void process(Optional<String> name) { ... }
public class User {
    private Optional<String> email; // 不推荐
}

// ✅ Optional 仅用于返回值
public Optional<User> findUser(String id) { ... }

// ❌ 既然用了 Optional 还在用 isPresent() + get()
Optional<User> userOpt = findUser(id);
if (userOpt.isPresent()) {
    return userOpt.get().getName();
} else {
    return "Unknown";
}

// ✅ 使用函数式 API
return findUser(id)
    .map(User::getName)
    .orElse("Unknown");

---

Spring Boot 最佳实践

依赖注入 (DI)

// ❌ 字段注入 (@Autowired)
// 缺点：难以测试（需要反射注入），掩盖了依赖过多的问题，且不可变性差
@Service
public class UserService {
    @Autowired
    private UserRepository userRepo;
}

// ✅ 构造器注入 (Constructor Injection)
// 优点：依赖明确，易于单元测试 (Mock)，字段可为 final
@Service
public class UserService {
    private final UserRepository userRepo;

    public UserService(UserRepository userRepo) {
        this.userRepo = userRepo;
    }
}
// 💡 提示：结合 Lombok @RequiredArgsConstructor 可简化代码，但要小心循环依赖

配置管理

// ❌ 硬编码配置值
@Service
public class PaymentService {
    private String apiKey = "sk_live_12345";
}

// ❌ 直接使用 @Value 散落在代码中
@Value("${app.payment.api-key}")
private String apiKey;

// ✅ 使用 @ConfigurationProperties 类型安全配置
@ConfigurationProperties(prefix = "app.payment")
public record PaymentProperties(String apiKey, int timeout, String url) {}

---

JPA 与 数据库性能

N+1 查询问题

// ❌ FetchType.EAGER 或 循环中触发懒加载
// Entity 定义
@Entity
public class User {
    @OneToMany(fetch = FetchType.EAGER) // 危险！
    private List<Order> orders;
}

// 业务代码
List<User> users = userRepo.findAll(); // 1 条 SQL
for (User user : users) {
    // 如果是 Lazy，这里会触发 N 条 SQL
    System.out.println(user.getOrders().size());
}

// ✅ 使用 @EntityGraph 或 JOIN FETCH
@Query("SELECT u FROM User u JOIN FETCH u.orders")
List<User> findAllWithOrders();

事务管理

// ❌ 在 Controller 层开启事务（数据库连接占用时间过长）
// ❌ 在 private 方法上加 @Transactional（AOP 不生效）
@Transactional
private void saveInternal() { ... }

// ✅ 在 Service 层公共方法加 @Transactional
// ✅ 读操作显式标记 readOnly = true (性能优化)
@Service
public class UserService {
    @Transactional(readOnly = true)
    public User getUser(Long id) { ... }

    @Transactional
    public void createUser(UserDto dto) { ... }
}

Entity 设计

// ❌ 在 Entity 中使用 Lombok @Data
// @Data 生成的 equals/hashCode 包含所有字段，可能触发懒加载导致性能问题或异常
@Entity
@Data
public class User { ... }

// ✅ 仅使用 @Getter, @Setter
// ✅ 自定义 equals/hashCode (通常基于 ID)
@Entity
@Getter
@Setter
public class User {
    @Id
    private Long id;

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof User)) return false;
        return id != null && id.equals(((User) o).id);
    }

    @Override
    public int hashCode() {
        return getClass().hashCode();
    }
}

---

并发与虚拟线程

虚拟线程 (Java 21+)

// ❌ 传统线程池处理大量 I/O 阻塞任务（资源耗尽）
ExecutorService executor = Executors.newFixedThreadPool(100);

// ✅ 使用虚拟线程处理 I/O 密集型任务（高吞吐量）
// Spring Boot 3.2+ 开启：spring.threads.virtual.enabled=true
ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor();

// 在虚拟线程中，阻塞操作（如 DB 查询、HTTP 请求）几乎不消耗 OS 线程资源

线程安全

// ❌ SimpleDateFormat 是线程不安全的
private static final SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd");

// ✅ 使用 DateTimeFormatter (Java 8+)
private static final DateTimeFormatter dtf = DateTimeFormatter.ofPattern("yyyy-MM-dd");

// ❌ HashMap 在多线程环境可能死循环或数据丢失
// ✅ 使用 ConcurrentHashMap
Map<String, String> cache = new ConcurrentHashMap<>();

---

Lombok 使用规范

// ❌ 滥用 @Builder 导致无法强制校验必填字段
@Builder
public class Order {
    private String id; // 必填
    private String note; // 选填
}
// 调用者可能漏掉 id: Order.builder().note("hi").build();

// ✅ 关键业务对象建议手动编写 Builder 或构造函数以确保不变量
// 或者在 build() 方法中添加校验逻辑 (Lombok @Builder.Default 等)

---

异常处理

全局异常处理

// ❌ 到处 try-catch 吞掉异常或只打印日志
try {
    userService.create(user);
} catch (Exception e) {
    e.printStackTrace(); // 不应该在生产环境使用
    // return null; // 吞掉异常，上层不知道发生了什么
}

// ✅ 自定义异常 + @ControllerAdvice (Spring Boot 3 ProblemDetail)
public class UserNotFoundException extends RuntimeException { ... }

@RestControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(UserNotFoundException.class)
    public ProblemDetail handleNotFound(UserNotFoundException e) {
        return ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, e.getMessage());
    }
}

---

测试规范

单元测试 vs 集成测试

// ❌ 单元测试依赖真实数据库或外部服务
@SpringBootTest // 启动整个 Context，慢
public class UserServiceTest { ... }

// ✅ 单元测试使用 Mockito
@ExtendWith(MockitoExtension.class)
class UserServiceTest {
    @Mock UserRepository repo;
    @InjectMocks UserService service;

    @Test
    void shouldCreateUser() { ... }
}

// ✅ 集成测试使用 Testcontainers
@Testcontainers
@SpringBootTest
class UserRepositoryTest {
    @Container
    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:15");
    // ...
}

---

Review Checklist

基础与规范

• 遵循 Java 17/21 新特性（Switch 表达式, Records, 文本块）
• 避免使用已过时的类（Date, Calendar, SimpleDateFormat）
• 集合操作是否优先使用了 Stream API 或 Collections 方法？
• Optional 仅用于返回值，未用于字段或参数

Spring Boot

• 使用构造器注入而非 @Autowired 字段注入
• 配置属性使用了 @ConfigurationProperties
• Controller 职责单一，业务逻辑下沉到 Service
• 全局异常处理使用了 @ControllerAdvice / ProblemDetail

数据库 & 事务

• 读操作事务标记了 @Transactional(readOnly = true)
• 检查是否存在 N+1 查询（EAGER fetch 或循环调用）
• Entity 类未使用 @Data，正确实现了 equals/hashCode
• 数据库索引是否覆盖了查询条件

并发与性能

• I/O 密集型任务是否考虑了虚拟线程？
• 线程安全类是否使用正确（ConcurrentHashMap vs HashMap）
• 锁的粒度是否合理？避免在锁内进行 I/O 操作

可维护性

• 关键业务逻辑有充分的单元测试
• 日志记录恰当（使用 Slf4j，避免 System.out）
• 魔法值提取为常量或枚举