Spring Data JPA

JPA、Hibernate 与 Spring Data JPA 的关系

这三者常被混淆，实际上是不同层次的东西：

简言之：JPA 是规范，Hibernate 是实现，Spring Data JPA 是在 JPA 之上的便利层。日常开发中我们主要使用 Spring Data JPA 的接口，Hibernate 的细节由框架处理。

核心概念名词解释

实体类设计

@Entity
@Table(name = "users")     // 对应表名，不指定则用类名小写
@Data
@NoArgsConstructor
@AllArgsConstructor
@Builder
public class User {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false, unique = true, length = 50)
    private String username;

    @Column(nullable = false, unique = true)
    private String email;

    @Column(nullable = false)
    private String passwordHash;

    // 一个用户可以有多个订单（一对多关系）
    @OneToMany(mappedBy = "user", cascade = CascadeType.ALL, fetch = FetchType.LAZY)
    private List<Order> orders = new ArrayList<>();

    @CreationTimestamp
    @Column(updatable = false)
    private LocalDateTime createdAt;

    @UpdateTimestamp
    private LocalDateTime updatedAt;
}

@Entity
@Table(name = "orders")
@Data
@Builder
public class Order {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    // 多个订单属于一个用户（多对一关系）
    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "user_id", nullable = false)
    private User user;

    @Column(nullable = false)
    private BigDecimal totalAmount;

    @Enumerated(EnumType.STRING)
    private OrderStatus status;
}

Repository 接口

// 继承 JpaRepository，泛型参数：实体类型, 主键类型
public interface UserRepository extends JpaRepository<User, Long> {

    // 方法名查询推导：Spring Data JPA 自动生成 SQL
    Optional<User> findByEmail(String email);

    List<User> findByUsernameContainingIgnoreCase(String keyword);

    boolean existsByEmail(String email);

    // JPQL 查询（当方法名推导不够用时）
    @Query("SELECT u FROM User u WHERE u.createdAt >= :since ORDER BY u.createdAt DESC")
    List<User> findRecentUsers(@Param("since") LocalDateTime since);

    // 原生 SQL 查询（nativeQuery = true）
    @Query(value = "SELECT * FROM users WHERE email ILIKE %:keyword%",
           nativeQuery = true)
    List<User> searchByEmailNative(@Param("keyword") String keyword);

    // 解决 N+1：用 JOIN FETCH 预加载关联数据
    @Query("SELECT DISTINCT u FROM User u LEFT JOIN FETCH u.orders WHERE u.id = :id")
    Optional<User> findByIdWithOrders(@Param("id") Long id);
}

N+1 查询问题详解

N+1 问题是 ORM 使用中最高频的性能陷阱，必须深刻理解其成因和解决方案。

事务管理

Spring 的事务管理基于 AOP 代理实现。当调用 @Transactional 方法时，Spring 创建一个代理对象，在方法执行前后注入事务逻辑。

@Service
@RequiredArgsConstructor
public class UserServiceImpl implements UserService {

    private final UserRepository userRepository;
    private final PasswordEncoder passwordEncoder;

    // 只读事务：Spring 优化只读操作（关闭脏检查，数据库可使用只读副本）
    @Transactional(readOnly = true)
    public UserResponseDTO findById(Long id) {
        User user = userRepository.findById(id)
            .orElseThrow(() -> new EntityNotFoundException("用户不存在: " + id));
        return toDTO(user);
    }

    // 写事务：默认 REQUIRED，RuntimeException 自动回滚
    @Transactional
    public UserResponseDTO create(UserCreateDTO dto) {
        if (userRepository.existsByEmail(dto.getEmail())) {
            throw new BusinessException(409, "邮箱已被注册");
        }
        User user = User.builder()
            .username(dto.getUsername())
            .email(dto.getEmail())
            .passwordHash(passwordEncoder.encode(dto.getPassword()))
            .build();
        return toDTO(userRepository.save(user));
    }
}

@EntityGraph：解决 N+1 的另一种方式

除了 JOIN FETCH，@EntityGraph 提供了更声明式的关联加载方式，可以在不修改 JPQL 的情况下指定哪些关联需要预加载：

@Entity
@NamedEntityGraph(
    name = "User.withOrders",
    attributeNodes = @NamedAttributeNode("orders")
)
public class User {
    // ...实体定义
    @OneToMany(mappedBy = "user", fetch = FetchType.LAZY)
    private List<Order> orders;
}

public interface UserRepository extends JpaRepository<User, Long> {

    // 通过 EntityGraph 声明式预加载 orders，无需修改 JPQL
    @EntityGraph("User.withOrders")
    Optional<User> findById(Long id);

    // 动态 EntityGraph（无需 @NamedEntityGraph）
    @EntityGraph(attributePaths = { "orders", "orders.items" })
    List<User> findByUsernameContaining(String keyword);
}

Specification（动态查询条件）

当查询条件是动态的（用户可能按任意字段组合过滤），JpaSpecificationExecutor 提供了类型安全的动态查询构建能力，比手写 JPQL 字符串更安全：

// Repository 继承 JpaSpecificationExecutor
public interface UserRepository
        extends JpaRepository<User, Long>,
                JpaSpecificationExecutor<User> {}

// 定义查询规格（每个规格是一个查询条件）
public class UserSpec {

    // 按用户名模糊查询
    public static Specification<User> usernameLike(String keyword) {
        return (root, query, cb) ->
            keyword == null ? null
                : cb.like(cb.lower(root.get("username")), "%" + keyword.toLowerCase() + "%");
    }

    // 按注册时间范围查询
    public static Specification<User> createdBetween(LocalDateTime from, LocalDateTime to) {
        return (root, query, cb) -> {
            if (from == null && to == null) return null;
            if (from == null) return cb.lessThanOrEqualTo(root.get("createdAt"), to);
            if (to == null)   return cb.greaterThanOrEqualTo(root.get("createdAt"), from);
            return cb.between(root.get("createdAt"), from, to);
        };
    }
}

// 在 Service 中组合查询条件
public Page<UserResponseDTO> search(UserSearchRequest req, Pageable pageable) {
    Specification<User> spec =
        Specification.where(UserSpec.usernameLike(req.getKeyword()))
                      .and(UserSpec.createdBetween(req.getFrom(), req.getTo()));

    return userRepository.findAll(spec, pageable).map(this::toDTO);
}

乐观锁与版本控制

在高并发场景中，多个用户可能同时读取并修改同一条记录。乐观锁（Optimistic Locking）通过版本号字段防止"最后写入覆盖先写入"的丢失更新问题：

@Entity
public class Product {
    @Id
    @GeneratedValue
    private Long id;

    private Integer stock;

    // 版本号字段：每次 UPDATE 时自动递增
    // 若更新时 version 与数据库不匹配，抛出 OptimisticLockException
    @Version
    private Integer version;
}

// 并发场景：两个事务同时读 product(stock=10, version=1)
// 事务 A：UPDATE product SET stock=9, version=2 WHERE id=1 AND version=1 → 成功
// 事务 B：UPDATE product SET stock=9, version=2 WHERE id=1 AND version=1 → 0 行受影响
//          → Hibernate 检测到 0 行受影响 → 抛出 OptimisticLockException
// 结论：stock 正确扣减为 9（而非 8），防止了双倍扣减