// BAD - loads the customer EVERY time you load any order
@ManyToOne
@JoinColumn(name = "customer_id")
private User customer;
 
// GOOD - customer only loaded when accessed
@ManyToOne(fetch = FetchType.LAZY)
@JoinColumn(name = "customer_id")
private User customer;

package com.company.ecommerce.domain.user;
 
import jakarta.persistence.*;
import lombok.*;
 
@Entity
@Table(
    name = "addresses",
    indexes = {
        @Index(name = "idx_addresses_user_id", columnList = "user_id")
    }
)
@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
@Builder
@ToString(exclude = "user")
public class Address {
 
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
 
    /*
     * OWNING SIDE of User-Address relationship.
     * FK column 'user_id' lives in the addresses table.
     * fetch = LAZY: We almost never need the full User when working with an Address.
     * optional = false: Every address MUST belong to a user.
     */
    @ManyToOne(fetch = FetchType.LAZY, optional = false)
    @JoinColumn(
        name = "user_id",
        nullable = false,
        foreignKey = @ForeignKey(name = "fk_addresses_user_id")
    )
    private User user;
 
    @Enumerated(EnumType.STRING)
    @Column(name = "address_type", nullable = false, length = 20)
    private AddressType addressType;
 
    @Column(name = "street_line1", nullable = false, length = 200)
    private String streetLine1;
 
    @Column(name = "street_line2", length = 200)
    private String streetLine2;
 
    @Column(name = "city", nullable = false, length = 100)
    private String city;
 
    @Column(name = "state_province", length = 100)
    private String stateProvince;
 
    @Column(name = "postal_code", nullable = false, length = 20)
    private String postalCode;
 
    @Column(name = "country_code", nullable = false, length = 3)
    private String countryCode;
 
    @Column(name = "is_default", nullable = false)
    @Builder.Default
    private Boolean isDefault = false;
 
    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof Address address)) return false;
        return id != null && id.equals(address.id);
    }
 
    @Override
    public int hashCode() {
        return getClass().hashCode();
    }
}
 
public enum AddressType {
    HOME, WORK, SHIPPING, BILLING
}

@Entity
@Table(name = "users")
public class User extends AuditableEntity {
 
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
 
    // ... other fields ...
 
    /*
     * Inverse side of User-Address relationship.
     * cascade = PERSIST, MERGE: Saving a user saves new addresses.
     * cascade excludes REMOVE: Deleting a user does NOT delete addresses by default
     *                          unless you also want address deletion.
     * orphanRemoval = true: Removing address from collection DELETES it from DB.
     */
    @OneToMany(
        mappedBy = "user",
        cascade = {CascadeType.PERSIST, CascadeType.MERGE},
        orphanRemoval = true,
        fetch = FetchType.LAZY
    )
    @OrderBy("isDefault DESC, addressType ASC")
    @Builder.Default
    private List<Address> addresses = new ArrayList<>();
 
    // Helper methods
    public void addAddress(Address address) {
        addresses.add(address);
        address.setUser(this);
    }
 
    public void removeAddress(Address address) {
        addresses.remove(address);
        address.setUser(null);
    }
 
    public Optional<Address> getDefaultShippingAddress() {
        return addresses.stream()
            .filter(a -> a.getIsDefault() && a.getAddressType() == AddressType.SHIPPING)
            .findFirst();
    }
}

public interface AddressRepository extends JpaRepository<Address, Long> {
 
    List<Address> findByUserId(Long userId);
 
    List<Address> findByUserIdAndAddressType(Long userId, AddressType addressType);
 
    Optional<Address> findByUserIdAndIsDefaultTrue(Long userId);
 
    // Count how many addresses a user has
    long countByUserId(Long userId);
 
    // Check if a user owns this address (for security validation)
    boolean existsByIdAndUserId(Long addressId, Long userId);
}

package com.company.ecommerce.domain.user;
 
import jakarta.persistence.*;
import lombok.*;
import java.util.HashSet;
import java.util.Set;
 
@Entity
@Table(name = "roles")
@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
@Builder
@ToString(exclude = "users")
public class Role {
 
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
 
    @Enumerated(EnumType.STRING)
    @Column(name = "name", nullable = false, unique = true, length = 50)
    private RoleName name;
 
    @Column(name = "description", length = 200)
    private String description;
 
    /*
     * mappedBy = "roles": This is the INVERSE side.
     * The JOIN TABLE is managed from User.roles (the owning side).
     * No cascade on this side: removing a Role should NOT remove Users.
     */
    @ManyToMany(mappedBy = "roles", fetch = FetchType.LAZY)
    @Builder.Default
    private Set<User> users = new HashSet<>();
 
    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof Role role)) return false;
        return name != null && name.equals(role.name);
    }
 
    @Override
    public int hashCode() {
        return getClass().hashCode();
    }
}
 
public enum RoleName {
    ROLE_ADMIN, ROLE_CUSTOMER, ROLE_SUPPORT, ROLE_MANAGER
}

@Entity
@Table(name = "users")
public class User extends AuditableEntity {
 
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
 
    // ... other fields ...
 
    /*
     * OWNING SIDE of User-Role many-to-many.
     * @JoinTable defines the join table structure.
     *
     * joinColumns: Columns from THIS entity (user_id in user_roles)
     * inverseJoinColumns: Columns from the OTHER entity (role_id in user_roles)
     *
     * IMPORTANT: Do NOT use CascadeType.REMOVE or CascadeType.ALL on @ManyToMany.
     * Deleting a User should NOT delete the ADMIN role.
     * Use only PERSIST and MERGE if you need cascade at all.
     *
     * Use Set, NOT List for @ManyToMany.
     * List causes Hibernate to delete ALL rows from user_roles for this user
     * and re-insert them when any change is made. Set does targeted inserts/deletes.
     */
    @ManyToMany(fetch = FetchType.LAZY)
    @JoinTable(
        name = "user_roles",
        joinColumns = @JoinColumn(
            name = "user_id",
            foreignKey = @ForeignKey(name = "fk_user_roles_user_id")
        ),
        inverseJoinColumns = @JoinColumn(
            name = "role_id",
            foreignKey = @ForeignKey(name = "fk_user_roles_role_id")
        )
    )
    @Builder.Default
    private Set<Role> roles = new HashSet<>();
 
    // Helper methods for bidirectional sync
    public void addRole(Role role) {
        roles.add(role);
        role.getUsers().add(this);
    }
 
    public void removeRole(Role role) {
        roles.remove(role);
        role.getUsers().remove(this);
    }
 
    public boolean hasRole(RoleName roleName) {
        return roles.stream().anyMatch(r -> r.getName() == roleName);
    }
}

-- V5__create_roles_and_user_roles.sql
 
CREATE TABLE roles (
    id          BIGINT      NOT NULL AUTO_INCREMENT,
    name        VARCHAR(50) NOT NULL,
    description VARCHAR(200),
    PRIMARY KEY (id),
    UNIQUE KEY uk_roles_name (name)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
 
-- Seed initial roles
INSERT INTO roles (name, description) VALUES
    ('ROLE_ADMIN',    'System administrator'),
    ('ROLE_CUSTOMER', 'Regular customer'),
    ('ROLE_SUPPORT',  'Customer support agent'),
    ('ROLE_MANAGER',  'Store manager');
 
CREATE TABLE user_roles (
    user_id BIGINT NOT NULL,
    role_id BIGINT NOT NULL,
    PRIMARY KEY (user_id, role_id),
    INDEX idx_user_roles_role_id (role_id),
    CONSTRAINT fk_user_roles_user_id
        FOREIGN KEY (user_id) REFERENCES users (id) ON DELETE CASCADE,
    CONSTRAINT fk_user_roles_role_id
        FOREIGN KEY (role_id) REFERENCES roles (id) ON DELETE CASCADE
) ENGINE=InnoDB;

public interface UserRepository extends JpaRepository<User, Long> {
 
    Optional<User> findByEmail(String email);
 
    // Load user with roles in one query (needed for authentication)
    @Query("SELECT u FROM User u LEFT JOIN FETCH u.roles WHERE u.email = :email")
    Optional<User> findByEmailWithRoles(@Param("email") String email);
 
    // Load user with all relationships needed for the dashboard
    @Query("""
        SELECT u FROM User u
        LEFT JOIN FETCH u.roles
        LEFT JOIN FETCH u.profile
        WHERE u.id = :id
        """)
    Optional<User> findByIdWithRolesAndProfile(@Param("id") Long id);
 
    // Find all users with a specific role
    @Query("SELECT u FROM User u JOIN u.roles r WHERE r.name = :roleName")
    List<User> findByRoleName(@Param("roleName") RoleName roleName);
}

package com.company.ecommerce.domain.user;
 
import jakarta.persistence.*;
import lombok.*;
import java.time.Instant;
 
@Entity
@Table(
    name = "user_roles",
    uniqueConstraints = {
        // Prevent assigning the same role twice
        @UniqueConstraint(name = "uk_user_roles_user_role",
                          columnNames = {"user_id", "role_id"})
    },
    indexes = {
        @Index(name = "idx_user_roles_user_id", columnList = "user_id"),
        @Index(name = "idx_user_roles_role_id", columnList = "role_id"),
        @Index(name = "idx_user_roles_expires_at", columnList = "expires_at")
    }
)
@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
@Builder
@ToString(exclude = {"user", "role"})
public class UserRole {
 
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
 
    @ManyToOne(fetch = FetchType.LAZY, optional = false)
    @JoinColumn(
        name = "user_id",
        nullable = false,
        foreignKey = @ForeignKey(name = "fk_user_roles_user_id")
    )
    private User user;
 
    @ManyToOne(fetch = FetchType.LAZY, optional = false)
    @JoinColumn(
        name = "role_id",
        nullable = false,
        foreignKey = @ForeignKey(name = "fk_user_roles_role_id")
    )
    private Role role;
 
    // Extra columns - impossible with basic @ManyToMany
    @Column(name = "assigned_at", nullable = false, updatable = false)
    private Instant assignedAt;
 
    @Column(name = "assigned_by", nullable = false, length = 100, updatable = false)
    private String assignedBy;
 
    @Column(name = "expires_at")
    private Instant expiresAt;
 
    @Column(name = "is_active", nullable = false)
    @Builder.Default
    private Boolean isActive = true;
 
    @Column(name = "notes", length = 500)
    private String notes;
 
    public boolean isExpired() {
        return expiresAt != null && Instant.now().isAfter(expiresAt);
    }
 
    public boolean isEffective() {
        return isActive && !isExpired();
    }
 
    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof UserRole ur)) return false;
        return id != null && id.equals(ur.id);
    }
 
    @Override
    public int hashCode() {
        return getClass().hashCode();
    }
}

@Entity
@Table(name = "users")
public class User extends AuditableEntity {
 
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
 
    // ... other fields ...
 
    /*
     * With custom join entity, User no longer uses @ManyToMany.
     * Instead, it has @OneToMany to UserRole (which is the custom join entity).
     * You then navigate: user -> userRoles -> role
     */
    @OneToMany(
        mappedBy = "user",
        cascade = {CascadeType.PERSIST, CascadeType.MERGE},
        orphanRemoval = true,
        fetch = FetchType.LAZY
    )
    @Builder.Default
    private Set<UserRole> userRoles = new HashSet<>();
 
    // Helper methods
    public void assignRole(Role role, String assignedBy) {
        // Check if already has this role
        boolean alreadyHasRole = userRoles.stream()
            .anyMatch(ur -> ur.getRole().equals(role) && ur.getIsActive());
 
        if (alreadyHasRole) {
            throw new BusinessException("User already has role: " + role.getName());
        }
 
        UserRole userRole = UserRole.builder()
            .user(this)
            .role(role)
            .assignedAt(Instant.now())
            .assignedBy(assignedBy)
            .isActive(true)
            .build();
 
        userRoles.add(userRole);
    }
 
    public void revokeRole(Role role) {
        userRoles.stream()
            .filter(ur -> ur.getRole().equals(role) && ur.getIsActive())
            .findFirst()
            .ifPresent(ur -> ur.setIsActive(false));
    }
 
    public boolean hasRole(RoleName roleName) {
        return userRoles.stream()
            .anyMatch(ur -> ur.isEffective() && ur.getRole().getName() == roleName);
    }
 
    public Set<RoleName> getEffectiveRoles() {
        return userRoles.stream()
            .filter(UserRole::isEffective)
            .map(ur -> ur.getRole().getName())
            .collect(Collectors.toSet());
    }
}

@Entity
@Table(name = "roles")
public class Role {
 
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
 
    @Enumerated(EnumType.STRING)
    @Column(name = "name", nullable = false, unique = true, length = 50)
    private RoleName name;
 
    @Column(name = "description", length = 200)
    private String description;
 
    // Inverse side - navigate from Role to UserRoles
    @OneToMany(mappedBy = "role", fetch = FetchType.LAZY)
    @Builder.Default
    private Set<UserRole> userRoles = new HashSet<>();
 
    public long countActiveAssignments() {
        return userRoles.stream().filter(UserRole::isEffective).count();
    }
}

public interface UserRoleRepository extends JpaRepository<UserRole, Long> {
 
    List<UserRole> findByUserId(Long userId);
 
    List<UserRole> findByUserIdAndIsActiveTrue(Long userId);
 
    // Find all active, non-expired role assignments for a user
    @Query("""
        SELECT ur FROM UserRole ur
        JOIN FETCH ur.role
        WHERE ur.user.id = :userId
          AND ur.isActive = true
          AND (ur.expiresAt IS NULL OR ur.expiresAt > :now)
        """)
    List<UserRole> findEffectiveRolesForUser(
        @Param("userId") Long userId,
        @Param("now") Instant now
    );
 
    // Find all users with a specific active role
    @Query("""
        SELECT ur FROM UserRole ur
        JOIN FETCH ur.user
        WHERE ur.role.name = :roleName
          AND ur.isActive = true
        """)
    List<UserRole> findActiveAssignmentsByRoleName(@Param("roleName") RoleName roleName);
 
    boolean existsByUserIdAndRoleNameAndIsActiveTrue(Long userId, RoleName roleName);
 
    void deleteByUserIdAndRoleId(Long userId, Long roleId);
}

package com.company.ecommerce.domain.product;
 
import jakarta.persistence.*;
import lombok.*;
import java.util.HashSet;
import java.util.Set;
 
@Entity
@Table(
    name = "categories",
    indexes = {
        @Index(name = "idx_categories_parent_id", columnList = "parent_id"),
        @Index(name = "idx_categories_slug", columnList = "slug")
    }
)
@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
@Builder
@ToString(exclude = {"products", "parent", "children"})
public class Category {
 
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
 
    @Column(name = "name", nullable = false, length = 100)
    private String name;
 
    @Column(name = "slug", nullable = false, unique = true, length = 100)
    private String slug;
 
    @Column(name = "description", columnDefinition = "TEXT")
    private String description;
 
    /*
     * Self-referencing relationship: Category has a parent category.
     * Electronics -> Phones -> Smartphones
     * This models a category tree/hierarchy.
     */
    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "parent_id", foreignKey = @ForeignKey(name = "fk_categories_parent_id"))
    private Category parent;
 
    @OneToMany(mappedBy = "parent", fetch = FetchType.LAZY)
    @Builder.Default
    private Set<Category> children = new HashSet<>();
 
    /*
     * INVERSE SIDE of Product-Category many-to-many.
     * The @JoinTable is defined on the Product side (owning side).
     * No cascade: Removing a category should NOT remove products.
     */
    @ManyToMany(mappedBy = "categories", fetch = FetchType.LAZY)
    @Builder.Default
    private Set<Product> products = new HashSet<>();
 
    public boolean isRootCategory() {
        return parent <mark class="obsidian-highlight"> null;
    }
 
    @Override
    public boolean equals(Object o) {
        if (this </mark> o) return true;
        if (!(o instanceof Category cat)) return false;
        return slug != null && slug.equals(cat.slug);
    }
 
    @Override
    public int hashCode() {
        return getClass().hashCode();
    }
}

@Entity
@Table(name = "products")
public class Product extends AuditableEntity {
 
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
 
    // ... other fields ...
 
    /*
     * OWNING SIDE of Product-Category many-to-many.
     *
     * @JoinTable:
     *   name: join table name
     *   joinColumns: FK column pointing to THIS entity (product_id)
     *   inverseJoinColumns: FK column pointing to the OTHER entity (category_id)
     *
     * Use Set to avoid Hibernate delete-all-and-reinsert behavior on modification.
     * No cascade: Deleting a Product should NOT delete its Categories.
     */
    @ManyToMany(fetch = FetchType.LAZY)
    @JoinTable(
        name = "product_categories",
        joinColumns = @JoinColumn(
            name = "product_id",
            foreignKey = @ForeignKey(name = "fk_product_categories_product_id")
        ),
        inverseJoinColumns = @JoinColumn(
            name = "category_id",
            foreignKey = @ForeignKey(name = "fk_product_categories_category_id")
        )
    )
    @Builder.Default
    private Set<Category> categories = new HashSet<>();
 
    // Helper methods
    public void addCategory(Category category) {
        categories.add(category);
        category.getProducts().add(this);
    }
 
    public void removeCategory(Category category) {
        categories.remove(category);
        category.getProducts().remove(this);
    }
 
    public boolean isInCategory(String categorySlug) {
        return categories.stream().anyMatch(c -> c.getSlug().equals(categorySlug));
    }
}

public interface ProductRepository extends JpaRepository<Product, Long> {
 
    // Find products in a specific category
    @Query("""
        SELECT DISTINCT p FROM Product p
        JOIN p.categories c
        WHERE c.slug = :categorySlug
          AND p.status = 'ACTIVE'
        ORDER BY p.name
        """)
    List<Product> findByCategorySlug(@Param("categorySlug") String categorySlug);
 
    // Find products with their categories loaded (for product detail page)
    @Query("SELECT p FROM Product p LEFT JOIN FETCH p.categories WHERE p.id = :id")
    Optional<Product> findByIdWithCategories(@Param("id") Long id);
 
    // Paginated product listing with category filter
    @Query("""
        SELECT DISTINCT p FROM Product p
        JOIN p.categories c
        WHERE c.id = :categoryId
          AND p.status = :status
        """)
    Page<Product> findByCategoryIdAndStatus(
        @Param("categoryId") Long categoryId,
        @Param("status") ProductStatus status,
        Pageable pageable
    );
 
    // Find all active products with their categories (admin use)
    @EntityGraph(attributePaths = {"categories"})
    List<Product> findByStatus(ProductStatus status);
}

// Entity with id-based equals/hashCode
@Entity
public class Product {
    @Id
    private Long id;
 
    @Override
    public boolean equals(Object o) {
        if (!(o instanceof Product p)) return false;
        return id != null && id.equals(p.id);
    }
 
    @Override
    public int hashCode() {
        return getClass().hashCode();
    }
}
 
// Problem scenario:
Product p = new Product();           // id is null
categories.add(p);                   // Added to Set with hashCode from getClass()
productRepository.save(p);           // id assigned: 42
categories.contains(p);              // Still works because hashCode doesn't change (getClass())
 
// WHY getClass().hashCode() works:
// The hash code MUST be stable before and after persist.
// Objects.hashCode(id) would return different values before (null) and after (42) save.
// This would break Set behavior: item inserted with null-hashCode slot,
// but searched with 42-hashCode slot -> not found!

@Entity
public class Category {
 
    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof Category cat)) return false;
        // Use slug as the business key - stable before and after persist
        return slug != null && slug.equals(cat.slug);
    }
 
    @Override
    public int hashCode() {
        return getClass().hashCode();  // Constant, stable across lifecycle
    }
}

// Load all products (1 query)
List<Product> products = productRepository.findAll();
 
for (Product product : products) {
    // Each access to categories triggers:
    // SELECT * FROM product_categories WHERE product_id = ?
    // THEN: SELECT * FROM categories WHERE id IN (...)
    // That's 2N additional queries!
    Set<Category> cats = product.getCategories();
}
 
// Total: 1 + 2N queries for N products

@Query("SELECT p FROM Product p LEFT JOIN FETCH p.categories WHERE p.id = :id")
Optional<Product> findByIdWithCategories(@Param("id") Long id);

@EntityGraph(attributePaths = {"categories"})
List<Product> findByStatus(ProductStatus status);
// Hibernate generates:
// SELECT p.*, pc.*, c.* FROM products p
// LEFT JOIN product_categories pc ON p.id = pc.product_id
// LEFT JOIN categories c ON pc.category_id = c.id
// WHERE p.status = ?

spring:
  jpa:
    properties:
      hibernate:
        default_batch_fetch_size: 25

// DTO class
package com.company.ecommerce.api.dto.response;
 
import lombok.Value;
import java.math.BigDecimal;
 
@Value  // Lombok: immutable, all-args constructor, equals, hashCode, toString
public class ProductSummaryDto {
    Long id;
    String sku;
    String name;
    BigDecimal price;
    String status;
    // No categories here - this is a summary
}

// Repository using JPQL constructor expression
public interface ProductRepository extends JpaRepository<Product, Long> {
 
    @Query("""
        SELECT new com.company.ecommerce.api.dto.response.ProductSummaryDto(
            p.id, p.sku, p.name, p.price, p.status
        )
        FROM Product p
        WHERE p.status = :status
        ORDER BY p.name
        """)
    Page<ProductSummaryDto> findSummariesByStatus(
        @Param("status") ProductStatus status,
        Pageable pageable
    );
}

@Value
public class ProductWithCategoriesDto {
    Long id;
    String name;
    BigDecimal price;
    List<String> categoryNames;  // We'll populate this in the service layer
 
    // Constructor for JPQL
    public ProductWithCategoriesDto(Long id, String name, BigDecimal price) {
        this.id = id;
        this.name = name;
        this.price = price;
        this.categoryNames = new ArrayList<>();
    }
}

package com.company.ecommerce.api.mapper;
 
import org.mapstruct.*;
 
@Mapper(componentModel = "spring",
        nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.IGNORE)
public interface ProductMapper {
 
    // Map Product entity to response DTO
    @Mapping(target = "categoryNames",
             expression = "java(product.getCategories().stream().map(c -> c.getName()).collect(java.util.stream.Collectors.toList()))")
    ProductResponse toResponse(Product product);
 
    // Map request DTO to entity
    @Mapping(target = "id", ignore = true)
    @Mapping(target = "categories", ignore = true)
    @Mapping(target = "createdAt", ignore = true)
    @Mapping(target = "updatedAt", ignore = true)
    Product toEntity(CreateProductRequest request);
 
    // Update existing entity from request (for PUT/PATCH)
    @Mapping(target = "id", ignore = true)
    @Mapping(target = "categories", ignore = true)
    void updateEntityFromRequest(UpdateProductRequest request, @MappingTarget Product product);
 
    List<ProductResponse> toResponseList(List<Product> products);
}

// Define the projection interface
package com.company.ecommerce.api.dto.projection;
 
public interface ProductCatalogView {
    Long getId();
    String getSku();
    String getName();
    BigDecimal getPrice();
    String getStatus();
 
    // Nested projection for category data
    CategoryView getCategory();  // Not usable with @ManyToMany, works with @ManyToOne
 
    interface CategoryView {
        String getName();
        String getSlug();
    }
}

// Repository returning interface projection
public interface ProductRepository extends JpaRepository<Product, Long> {
 
    // Spring Data auto-generates optimized SELECT based on projection fields
    List<ProductCatalogView> findByStatusOrderByName(ProductStatus status);
 
    // With pagination
    Page<ProductCatalogView> findByStatus(ProductStatus status, Pageable pageable);
}

// CORRECT: Using Set
@ManyToMany
private Set<Role> roles = new HashSet<>();
// Adding or removing: one targeted INSERT or DELETE
 
// BAD: Using List
@ManyToMany
private List<Role> roles = new ArrayList<>();
// Any change: DELETE ALL from join table + reinsert all
// This is horrifically inefficient and can cause data loss

// Always initialize - never let the collection be null
@Builder.Default
private Set<Role> roles = new HashSet<>();
 
@Builder.Default
private List<OrderItem> items = new ArrayList<>();

// DANGEROUS: Removing a user could cascade-remove the ADMIN role
@ManyToMany(cascade = CascadeType.ALL)
private Set<Role> roles;
 
// SAFE: No cascade (or only PERSIST/MERGE)
@ManyToMany(fetch = FetchType.LAZY)
private Set<Role> roles;

@NamedEntityGraph(
    name = "Product.withCategoriesAndBrand",
    attributeNodes = {
        @NamedAttributeNode("categories"),
        @NamedAttributeNode("brand")
    }
)
@Entity
public class Product { ... }

@BatchSize(size = 50)
@OneToMany(mappedBy = "parent", fetch = FetchType.LAZY)
private Set<Category> children = new HashSet<>();

@OneToMany(mappedBy = "user")
@OrderBy("createdAt DESC")
private List<Address> addresses = new ArrayList<>();
 
@ManyToMany
@OrderBy("name ASC")
private Set<Category> categories = new LinkedHashSet<>();
// LinkedHashSet preserves @OrderBy results

// Hibernate behavior with List in @ManyToMany:
user.getRoles().add(newRole);
// Generates:
// DELETE FROM user_roles WHERE user_id = ?    (deletes ALL roles)
// INSERT INTO user_roles VALUES (?, 1)         (reinserts all, including new)
// INSERT INTO user_roles VALUES (?, 2)
// INSERT INTO user_roles VALUES (?, 3)         <- new one
 
// With Set:
user.getRoles().add(newRole);
// Generates:
// INSERT INTO user_roles VALUES (?, 3)         (only the new one)

// This is a circular cascade bomb:
@ManyToMany(cascade = CascadeType.ALL)
private Set<Role> roles;  // On User
 
@ManyToMany(mappedBy = "roles", cascade = CascadeType.ALL)  // Also on Role
private Set<User> users;
 
// Deleting ONE user -> cascades to ALL roles -> cascades to ALL other users -> cascade...
// Potential: wiping your entire user and role tables

// Dangerous: A top-level Category might have thousands of products
@ManyToMany(mappedBy = "categories", fetch = FetchType.EAGER)
private Set<Product> products;  // Loading ALL products in memory -> OutOfMemoryError
 
// Correct: Never keep a reference to the large side
// Access products via ProductRepository with pagination instead

// Without unique constraint, a user can be assigned the same role multiple times
@Table(name = "user_roles")
// Missing: @UniqueConstraint on (user_id, role_id)
 
// Always add:
@Table(
    name = "user_roles",
    uniqueConstraints = {
        @UniqueConstraint(
            name = "uk_user_roles_user_role",
            columnNames = {"user_id", "role_id"}
        )
    }
)

// Missing: setting the inverse side
product.getCategories().add(electronics);
// electronics.getProducts() does NOT contain this product in memory!
// Next call to electronics.getProducts() shows stale data in same transaction
 
// Correct: Always use helper method
product.addCategory(electronics);
// addCategory sets both: product.categories and electronics.products

// In Order Service: only know about OrderItem
@OneToMany(mappedBy = "order")
private List<OrderItem> items;
 
// OrderItem references product_id (Long), NOT the Product entity
// Product lives in Product Service
@Column(name = "product_id")
private Long productId;  // Just the ID, not a JPA relationship
 
// This prevents cross-service entity loading and keeps services independent

@Entity
public class Order {
    // Derived from OrderItems, stored for fast reads
    @Column(name = "item_count")
    private Integer itemCount;  // Updated on addItem/removeItem
 
    @Column(name = "total_amount")
    private BigDecimal totalAmount;  // Recalculated on item changes
}
 
// Instead of:
SELECT COUNT(*) FROM order_items WHERE order_id = ?
// You query:
SELECT item_count FROM orders WHERE id = ?
// One fast lookup instead of an aggregation query