jpa

psh-inc 的头像作者 psh-inc

JPA entities, repositories, and Hibernate ORM patterns for Spring Boot 3.2.5 with KotlinUse when: Creating/modifying entities, repositories, database queries, or handling persistence layer concerns

📖 中文导读:JPA entities, repositories, and Hibernate ORM patterns for Spring Boot 3.2.5 with KotlinUse when: Creating/modifying entities, repositories, database queries, or handling persistence layer concerns 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: jpa description: | JPA entities, repositories, and Hibernate ORM patterns for Spring Boot 3.2.5 with Kotlin Use when: Creating/modifying entities, repositories, database queries, or handling persistence layer concerns allowed-tools: Read, Edit, Write, Glob, Grep, Bash

JPA Skill - Casino Platform

JPA/Hibernate patterns for the casino platform backend. This codebase uses Kotlin data classes with Spring Data JPA, PostgreSQL, and strict conventions for financial data handling.

Quick Start

Entity with ID and Auditing

@Entity
@Table(name = "transactions")
data class Transaction(
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    val id: Long? = null,

    @Column(nullable = false, precision = 19, scale = 4)
    val amount: BigDecimal,

    @Column(nullable = false)
    @Enumerated(EnumType.STRING)
    var status: TransactionStatus,

    @Column(name = "created_at", nullable = false)
    val createdAt: LocalDateTime = LocalDateTime.now(),

    @Column(name = "updated_at", nullable = false)
    var updatedAt: LocalDateTime = LocalDateTime.now(),

    @Version
    var version: Long = 0
)

Repository with JOIN FETCH

interface PlayerRepository : JpaRepository<Player, Long> {
    fun findByUsername(username: String): Optional<Player>

    @Query("""
        SELECT DISTINCT p FROM Player p
        LEFT JOIN FETCH p.wallet
        WHERE p.status = 'ACTIVE'
    """)
    fun findActivePlayersWithWallet(): List<Player>
}

Key Concepts

Concept Usage Example
ID Type Always BIGSERIAL @GeneratedValue(strategy = GenerationType.IDENTITY)
Money BigDecimal from String BigDecimal("123.45") not BigDecimal(123.45)
Dates LocalDateTime, UTC LocalDateTime.now(ZoneOffset.UTC)
Enums STRING not ORDINAL @Enumerated(EnumType.STRING)
Locking Optimistic @Version var version: Long = 0
Lazy Loading Default for relations fetch = FetchType.LAZY

Common Patterns

Preventing N+1 Queries

When: Loading entities with their relationships

// BAD - N+1 queries
val players = repo.findByStatus(ACTIVE)
players.forEach { it.wallet?.balance }  // Separate query per player!

// GOOD - Single query with JOIN FETCH
@Query("SELECT p FROM Player p LEFT JOIN FETCH p.wallet WHERE p.status = 'ACTIVE'")
fun findActivePlayersWithWallet(): List<Player>

Bulk Updates with @Modifying

When: Updating multiple records without loading entities

@Modifying
@Query("""
    UPDATE Player p SET 
        p.status = :status, 
        p.updatedAt = CURRENT_TIMESTAMP 
    WHERE p.lastActivityAt < :threshold
""")
fun deactivateInactivePlayers(
    @Param("status") status: PlayerStatus,
    @Param("threshold") threshold: LocalDateTime
): Int

See Also

  • patterns - Entity, relationship, and query patterns
  • workflows - Common development workflows
  • See the spring-boot skill for service layer patterns and transactions
  • See the postgresql skill for Flyway migrations and database design
  • See the kotlin skill for Kotlin-specific JPA considerations