JPA 和高级关联：完整类指南

@Entity
public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String username;

    @OneToOne(cascade = CascadeType.ALL, fetch = FetchType.LAZY)
    @JoinColumn(name = "profile_id", referencedColumnName = "id")
    private UserProfile profile;

    // Getters and setters
}

@Entity
public class UserProfile {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String bio;
    private String avatarUrl;

    // Getters and setters
}

@Entity
public class Customer {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String name;
    private String email;

    @OneToOne(mappedBy = "customer", cascade = CascadeType.ALL,
              fetch = FetchType.LAZY, orphanRemoval = true)
    private CustomerDetails details;

    // 维护同步的实用方法
    public void setDetails(CustomerDetails details) {
        if (details == null) {
            if (this.details != null) {
                this.details.setCustomer(null);
            }
        } else {
            details.setCustomer(this);
        }
        this.details = details;
    }
}

@Entity
public class CustomerDetails {
    @Id
    private Long id; // 与 Customer 相同的 PK

    private String address;
    private String phone;
    private LocalDate birthDate;

    @OneToOne(fetch = FetchType.LAZY)
    @MapsId // 将 Customer 的 PK 映射为 FK 和 PK
    @JoinColumn(name = "customer_id")
    private Customer customer;

    // Getters and setters
}

CREATE TABLE customer (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    name VARCHAR(255),
    email VARCHAR(255)
);

CREATE TABLE customer_details (
    customer_id BIGINT PRIMARY KEY,  -- PK 和 FK 同时
    address VARCHAR(255),
    phone VARCHAR(255),
    birth_date DATE,
    FOREIGN KEY (customer_id) REFERENCES customer(id)
);

CREATE TABLE orders (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    order_date DATETIME,
    status VARCHAR(50)
);

CREATE TABLE order_line (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    product_name VARCHAR(255),
    quantity INT,
    price DECIMAL(10,2),
    order_id BIGINT NOT NULL,  -- FK 由 @ManyToOne 管理
    FOREIGN KEY (order_id) REFERENCES orders(id)
);

// ❌ 错误：`@OneToMany` 作为所有者（无 mappedBy）
@OneToMany
@JoinColumn(name = "order_id") // 这使 Order 成为所有者
private List<OrderLine> lines;

// 结果：INSERT order_line + UPDATE order_line SET order_id = ?

// ✅ 好：`@ManyToOne` 作为所有者
@ManyToOne(fetch = FetchType.LAZY)
@JoinColumn(name = "order_id")
private Order order;

// 结果：INSERT order_line（包含 order_id）

@Entity
public class Student {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String name;

    @ManyToMany(cascade = {CascadeType.PERSIST, CascadeType.MERGE})
    @JoinTable(
        name = "student_course",
        joinColumns = @JoinColumn(name = "student_id"),
        inverseJoinColumns = @JoinColumn(name = "course_id")
    )
    private Set<Course> courses = new HashSet<>(); // ✅ 使用 Set，而不是 List

    // 实用方法
    public void addCourse(Course course) {
        courses.add(course);
        course.getStudents().add(this);
    }

    public void removeCourse(Course course) {
        courses.remove(course);
        course.getStudents().remove(this);
    }
}

@Entity
public class Course {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String title;

    @ManyToMany(mappedBy = "courses")
    private Set<Student> students = new HashSet<>();

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

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

CREATE TABLE student (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    name VARCHAR(255)
);

CREATE TABLE course (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    title VARCHAR(255)
);

CREATE TABLE student_course (
    student_id BIGINT NOT NULL,
    course_id BIGINT NOT NULL,
    PRIMARY KEY (student_id, course_id),
    FOREIGN KEY (student_id) REFERENCES student(id),
    FOREIGN KEY (course_id) REFERENCES course(id)
);

// ❌ 错误：使用 List
@ManyToMany
private List<Course> courses = new ArrayList<>();

// 删除一个课程时，Hibernate 执行：
// DELETE FROM student_course WHERE student_id = ?  -- 全部！
// INSERT INTO student_course VALUES (?, ?)         -- 重新插入剩余
// INSERT INTO student_course VALUES (?, ?)
// ...

// ✅ 好：使用 Set
@ManyToMany
private Set<Course> courses = new HashSet<>();

// 删除一个课程时，Hibernate 执行：
// DELETE FROM student_course WHERE student_id = ? AND course_id = ?  -- 仅一个

@Entity
public class Enrollment {
    @EmbeddedId
    private EnrollmentId id;

    @ManyToOne(fetch = FetchType.LAZY)
    @MapsId("studentId")
    @JoinColumn(name = "student_id")
    private Student student;

    @ManyToOne(fetch = FetchType.LAZY)
    @MapsId("courseId")
    @JoinColumn(name = "course_id")
    private Course course;

    private LocalDate enrollmentDate;
    private Double grade;

    // 构造函数、getter、setter
}

@Embeddable
public class EnrollmentId implements Serializable {
    private Long studentId;
    private Long courseId;

    // equals, hashCode
}

public interface OrderRepository extends JpaRepository<Order, Long> {

    @Query("SELECT DISTINCT o FROM Order o JOIN FETCH o.lines WHERE o.status = :status")
    List<Order> findByStatusWithLines(@Param("status") String status);

    @Query("SELECT DISTINCT o FROM Order o " +
           "JOIN FETCH o.lines l " +
           "JOIN FETCH o.customer " +
           "WHERE o.orderDate >= :date")
    List<Order> findRecentOrdersWithDetails(@Param("date") LocalDateTime date);
}

-- 带 JOIN 的单个查询
SELECT DISTINCT o.*, l.*, c.*
FROM orders o
INNER JOIN order_line l ON o.id = l.order_id
INNER JOIN customer c ON o.customer_id = c.id
WHERE o.order_date >= ?

@Entity
public class Order {

    @OneToMany(mappedBy = "order")
    @BatchSize(size = 25) // 每个查询最多加载 25 个集合
    private List<OrderLine> lines;
}

-- 而不是 N 个单独查询：
SELECT * FROM order_line WHERE order_id IN (1, 2, 3, ..., 25);
SELECT * FROM order_line WHERE order_id IN (26, 27, 28, ..., 50);
-- 等等。

// ❌ 这会失败
@Query("SELECT o FROM Order o JOIN FETCH o.lines JOIN FETCH o.payments")
List<Order> findWithLinesAndPayments();

54 个订单 × 54 个行 × 54 个支付 = 157,464 行

54 + 54 + 54 = 162 总行数

// 定义投影
public interface OrderSummary {
    Long getId();
    LocalDateTime getOrderDate();
    String getStatus();

    // 使用 SpEL 的计算属性
    @Value("#{target.lines.size()}")
    int getLineCount();
}

// 在仓库中使用
public interface OrderRepository extends JpaRepository<Order, Long> {

    List<OrderSummary> findByStatus(String status);

    @Query("SELECT o.id as id, o.orderDate as orderDate, o.status as status " +
           "FROM Order o WHERE o.customer.id = :customerId")
    List<OrderSummary> findSummariesByCustomer(@Param("customerId") Long customerId);
}

public interface OrderRepository extends JpaRepository<Order, Long> {

    // 接受任何投影类型的通用方法
    <T> List<T> findByStatus(String status, Class<T> type);

    <T> Optional<T> findById(Long id, Class<T> type);
}

// 使用
List<OrderSummary> summaries = orderRepository.findByStatus("PENDING", OrderSummary.class);
List<OrderDTO> dtos = orderRepository.findByStatus("PENDING", OrderDTO.class);
List<Order> entities = orderRepository.findByStatus("PENDING", Order.class);

@Query("SELECT o.id, o.status, COUNT(l) FROM Order o LEFT JOIN o.lines l GROUP BY o.id, o.status")
List<Object[]> findOrderStats();

// 或使用 Tuple
@Query("SELECT o.id as id, o.status as status, COUNT(l) as lineCount " +
       "FROM Order o LEFT JOIN o.lines l GROUP BY o.id, o.status")
List<Tuple> findOrderStatsTuple();

// 使用
List<Tuple> stats = orderRepository.findOrderStatsTuple();
for (Tuple t : stats) {
    Long id = t.get("id", Long.class);
    String status = t.get("status", String.class);
    Long count = t.get("lineCount", Long.class);
}

public interface OrderRepository extends JpaRepository<Order, Long> {

    // 简单原生查询
    @Query(value = "SELECT * FROM orders WHERE status = ?1", nativeQuery = true)
    List<Order> findByStatusNative(String status);

    // 使用 @NativeQuery（Spring Data 3.x）
    @NativeQuery("SELECT * FROM orders WHERE YEAR(order_date) = :year")
    List<Order> findByYear(@Param("year") int year);

    // 带分页
    @Query(
        value = "SELECT * FROM orders WHERE status = :status",
        countQuery = "SELECT COUNT(*) FROM orders WHERE status = :status",
        nativeQuery = true
    )
    Page<Order> findByStatusPaged(@Param("status") String status, Pageable pageable);
}

// 投影到接口
public interface OrderNativeSummary {
    Long getId();
    String getStatus();
    Integer getLineCount();
}

@Query(value = """
    SELECT o.id, o.status, COUNT(l.id) as lineCount
    FROM orders o
    LEFT JOIN order_line l ON o.id = l.order_id
    GROUP BY o.id, o.status
    """, nativeQuery = true)
List<OrderNativeSummary> findNativeSummaries();

// 投影到 Map
@NativeQuery("SELECT * FROM orders WHERE id = :id")
Map<String, Object> findRawById(@Param("id") Long id);

// 分层 DTO
public class OrderWithLinesDTO {
    private Long id;
    private String status;
    private List<LineDTO> lines = new ArrayList<>();
}

// 自定义仓库实现
@Repository
public class OrderRepositoryCustomImpl implements OrderRepositoryCustom {

    @PersistenceContext
    private EntityManager em;

    @Override
    @SuppressWarnings("unchecked")
    public List<OrderWithLinesDTO> findOrdersWithLinesNative() {
        String sql = """
            SELECT o.id as orderId, o.status,
                   l.id as lineId, l.product_name, l.quantity, l.price
            FROM orders o
            LEFT JOIN order_line l ON o.id = l.order_id
            ORDER BY o.id
            """;

        List<Object[]> results = em.createNativeQuery(sql).getResultList();

        Map<Long, OrderWithLinesDTO> orderMap = new LinkedHashMap<>();

        for (Object[] row : results) {
            Long orderId = ((Number) row[0]).longValue();

            OrderWithLinesDTO order = orderMap.computeIfAbsent(orderId, id -> {
                OrderWithLinesDTO dto = new OrderWithLinesDTO();
                dto.setId(id);
                dto.setStatus((String) row[1]);
                return dto;
            });

            if (row[2] != null) { // 如果有行
                LineDTO line = new LineDTO(
                    (String) row[3],
                    ((Number) row[4]).intValue(),
                    (BigDecimal) row[5]
                );
                order.getLines().add(line);
            }
        }

        return new ArrayList<>(orderMap.values());
    }
}

// 1. 带自定义方法的接口
public interface OrderRepositoryCustom {
    List<Order> findOrdersDynamic(OrderSearchCriteria criteria);
    List<OrderWithLinesDTO> findOrdersWithLinesNative();
}

// 2. 实现（名称必须以 "Impl" 结尾）
@Repository
public class OrderRepositoryCustomImpl implements OrderRepositoryCustom {

    @PersistenceContext
    private EntityManager em;

    @Override
    public List<Order> findOrdersDynamic(OrderSearchCriteria criteria) {
        CriteriaBuilder cb = em.getCriteriaBuilder();
        CriteriaQuery<Order> query = cb.createQuery(Order.class);
        Root<Order> order = query.from(Order.class);

        List<Predicate> predicates = new ArrayList<>();

        if (criteria.getStatus() != null) {
            predicates.add(cb.equal(order.get("status"), criteria.getStatus()));
        }

        if (criteria.getFromDate() != null) {
            predicates.add(cb.greaterThanOrEqualTo(
                order.get("orderDate"), criteria.getFromDate()));
        }

        if (criteria.getCustomerId() != null) {
            predicates.add(cb.equal(
                order.get("customer").get("id"), criteria.getCustomerId()));
        }

        // 动态 JOIN FETCH
        if (criteria.isFetchLines()) {
            order.fetch("lines", JoinType.LEFT);
        }

        query.where(predicates.toArray(new Predicate[0]));
        query.distinct(true);

        return em.createQuery(query).getResultList();
    }
}

// 3. 主仓库扩展两者
public interface OrderRepository extends
        JpaRepository<Order, Long>,
        OrderRepositoryCustom {
    // 标准查询方法在这里
}