kotlin-backend-jpa-entity-mapping

JPA Entity Mapping for Kotlin

Kotlin's data class is natural for DTOs but dangerous for JPA entities. Hibernate relies on identity semantics that data class breaks: equals/hashCode over all fields corrupts Set/Map membership after state changes, and auto-generated copy() creates detached duplicates of managed entities.

This skill teaches correct entity design, identity strategies, and uniqueness constraints for Kotlin + Spring Data JPA projects.

Entity Design Rules

• Never use data class for JPA entities. Use a regular class. Keep data class for DTOs.
• Keep transport DTOs and persistence entities separate unless the project clearly uses a shared model.
• Model required columns as non-null only when object construction and persistence lifecycle make it safe.
• Use lateinit only when the project already accepts that tradeoff and the lifecycle is safe.
• Verify kotlin("plugin.jpa") or equivalent no-arg support when JPA entities exist.
• Verify classes and members are compatible with proxying where needed.

Identity and Equality

• Never accept all-field equals/hashCode generated by data class on an entity.
• Follow project conventions when they already define an identity strategy.
• If no convention exists, use ID-based equality with a stable hashCode.
• For DB-generated IDs, model the unsaved state with nullable var id: Long? = null and a protected set; do not use 0L as a sentinel value.
• Be explicit about mutable fields and lazy associations when discussing equality.

Broken: data class Entity

// WRONG: data class generates equals/hashCode from ALL fields,
// and the generated ID uses a 0 sentinel instead of null
data class Order(
    @Id @GeneratedValue val id: Long = 0,
    var status: String,
    var total: BigDecimal
)
// BUG: order.status = "SHIPPED"; set.contains(order) → false (hash changed)
// BUG: Hibernate proxy.equals(entity) → false (proxy has lazy fields uninitialized)

Correct: Regular Class with ID-Based Identity