persistence-expert
Long FK 전략, QueryDSL DTO Projection, N+1 해결. JPA 관계 어노테이션 금지. /kb-persistence 명령 시 자동 활성화.
When & Why to Use This Skill
This Claude skill acts as a specialized Persistence Layer Expert, enforcing high-performance database interaction patterns and strict architectural boundaries in Java/Spring environments. It optimizes system scalability by mandating Long FK strategies, QueryDSL DTO projections, and Command/Query Adapter separation to eliminate N+1 issues and prevent common JPA-related performance bottlenecks.
Use Cases
- Refactoring legacy JPA entities to a decoupled architecture using Long FK strategies to eliminate complex @ManyToOne/@OneToMany relationship overhead.
- Optimizing database performance by implementing QueryDSL DTO projections, ensuring only necessary data is fetched without loading entire entities.
- Enforcing strict architectural standards by separating persistence logic into dedicated SaveAdapter and LoadAdapter components.
- Preventing N+1 query problems in complex data models through mandatory fetch joins and explicit QueryDSL implementation.
- Standardizing entity development with mandatory BaseAuditEntity inheritance and Flyway-based schema versioning for consistent database evolution.
| name | persistence-expert |
|---|---|
| description | Long FK 전략, QueryDSL DTO Projection, N+1 해결. JPA 관계 어노테이션 금지. /kb-persistence 명령 시 자동 활성화. |
| triggers | [/kb-persistence, /go, /red, /green, /refactor, /tidy, repository, querydsl, jpa, entity, adapter] |
Persistence Layer 전문가
핵심 원칙 (Zero-Tolerance)
✅ Mandatory
- Long FK 전략 -
private Long userId(관계 어노테이션 금지) - Command/Query Adapter 분리 - SaveAdapter, LoadAdapter
- QueryDSL DTO Projection - Entity 반환 금지
- No N+1 - 항상 fetch join 사용
- BaseAuditEntity 상속 - createdAt, updatedAt
- Constructor Pattern - Protected 기본 생성자 + Public 생성자
- Flyway 필수 - Schema 버전 관리
❌ Prohibited
- JPA 관계 어노테이션 금지 -
@ManyToOne,@OneToMany금지 - Entity Graph 금지 - Long FK 전략만 사용
- Lazy Loading 금지 - QueryDSL 명시적 join
- Entity 직접 반환 금지 - DTO Projection 필수
- Setter 금지 - 상태 변경은 메서드로
- Lombok 금지 - Pure Java getter
- JPQL String 금지 - QueryDSL 사용
예시
✅ CORRECT: Long FK 전략
@Entity
public class OrderJpaEntity extends BaseAuditEntity {
@Id
private Long orderId;
@Column(nullable = false)
private Long customerId; // ✅ Long FK
// ❌ WRONG
// @ManyToOne
// private CustomerJpaEntity customer;
}
✅ CORRECT: QueryDSL DTO Projection
return queryFactory
.select(Projections.constructor(
OrderDto.class,
order.orderId,
order.customerId,
order.status
))
.from(order)
.fetch();
참조
- 전체 가이드: docs/coding_convention/04-persistence-layer/
- 상세 규칙 + 템플릿: REFERENCE.md
자동 활성화
/kb-persistence /go|red|green|refactor|tidy 실행 시 자동 활성화.