JPA의 N+1 문제를 줄일 때 추가하는 jpa-patterns 스킬
機械翻訳 / Machine-translated
機械翻訳 / Machine-translated
원문 기사: JPA의 N+1 문제를 줄일 때 추가하는 jpa-patterns 스킬（cccskills）
스킬 페이지: jpa-patterns
이 기사의 결론
jpa-patterns를 추가하면, Spring Boot로 개발하는 엔지니어가 JPA/Hibernate의 엔티티 설계나 N+1 문제 대책을 AI 에이전트와 함께 진행할 수 있습니다.
이 기사에서는 요청했을 때 돌아오는 내용, 설치 방법, 요청문 예시를 순서대로 소개합니다.
마지막에는 제안을 적용하기 전에 확인해두고 싶은 사항을 다룹니다.
jpa-patterns를 추가하면, 에이전트는 연관 관계 정의와 검색 처리를 함께 검토하여 N+1 문제를 방지하는 조회 방법을 제안합니다.
N+1 문제란, 목록을 1회 조회한 후 각 행의 연관 데이터를 가져오기 위해 SQL이 행 수만큼 추가로 발행되는 상태를 말합니다.
예를 들어 다음과 같이 요청합니다.
이 엔티티의 연관 관계를 검토하고, N+1 문제를 방지하는 조회 방법을 제안해줘
에이전트는 먼저 연관 관계의 로딩 방식을 확인합니다.
스킬의 방침은 연관을 지연 로딩(사용하는 시점에 가져오는 방식)으로 통일하고, 컬렉션에 EAGER를 붙이지 않는 것입니다.
부모와 자식을 함께 사용하는 부분에 한정하여, JOIN FETCH를 사용한 쿼리를 리포지토리에 추가하는 안이 돌아옵니다.
@Query("select m from MarketEntity m left join fetch m.positions where m.id = :id")
Optional<MarketEntity> findWithPositions(@Param("id") Long id);
목록 화면처럼 읽기만 하는 처리에는 DTO 프로젝션을 사용하는 안도 제시됩니다.
DTO 프로젝션이란, ID나 이름 등 필요한 항목만 가진 가벼운 타입으로 결과를 받는 방법입니다.
변경 후에는 Hibernate의 SQL 로그를 출력하여, 발행되는 SQL 수로 효과를 확인하는 흐름이 됩니다.
jpa-patterns는 Spring Boot에서의 JPA/Hibernate 설계부터 성능 조정까지를 하나의 방침으로 정리한 스킬입니다.
다루는 범위는 엔티티, 리포지토리, 트랜잭션, 인덱스, 커넥션 풀까지입니다.
이제부터 작업별로 나누어 살펴보겠습니다.
새로운 엔티티에서는 테이블명, 컬럼 길이, 필수 여부를 어노테이션으로 명시하는 것이 기본입니다.
열거형은 문자열로 저장하고, 생성일시와 수정일시는 감사 기능(auditing)으로 자동 기록합니다.
연관 관계는 @OneToMany나 @ManyToOne 등으로 정의하고, 부모·자식의 삭제 연동도 이 단계에서 결정해두는 방침입니다.
SQL을 줄이는 수단은 조회 방법 지정과 프로젝션 두 가지입니다.
연관은 지연 로딩을 기본으로 하고, 필요한 검색에만 JOIN FETCH로 한꺼번에 조회합니다.
읽기 전용 화면에서는 엔티티 전체를 반환하지 않고, 필요한 컬럼만 반환하는 프로젝션을 사용하는 것이 원칙입니다.
업데이트는 서비스 레이어의 메서드에 @Transactional을 붙여서 묶습니다.
읽기만 하는 메서드에는 @Transactional(readOnly = true)를 붙이고, 오래 지속되는 트랜잭션은 피하는 것이 방침입니다.
트랜잭션을 넘나들며 엔티티를 가지고 다니지 않는 것도 검토 대상에 포함됩니다.
목록 검색에서는 PageRequest로 건수와 정렬 순서를 지정하고, Page로 받습니다.
대량 데이터라면 마지막으로 읽은 ID보다 큰 행을 순서대로 가져오는 커서 방식의 페이지 분할도 선택할 수 있습니다.
인덱스를 설정할 대상은 상태나 외래 키 등 자주 필터링하는 컬럼입니다.
검색 조건과 같은 순서의 복합 인덱스도 검토 대상이 됩니다.
여러 건의 등록은 saveAll과 Hibernate의 배치 설정으로 한꺼번에 전송합니다.
커넥션 풀 HikariCP에는 권장값이 제시됩니다.
운영 환경의 테이블 변경은 Flyway 또는 Liquibase로 관리하는 방침입니다.
데이터 접근 테스트에는 @DataJpaTest와 Testcontainers로 운영에 가까운 환경을 구성하는 방법이 권장됩니다.
설치 방법은 커맨드로 설치하는 방법과 에이전트에게 요청하는 방법 두 가지입니다.
커맨드는 다음과 같으며, Claude Code나 Codex 등 설치할 에이전트를 선택할 수 있습니다.
npx skills add https://github.com/affaan-m/ECC --skill jpa-patterns
에이전트에게 맡기는 경우, 다음 문장을 그대로 전송하세요.
내용을 확인한 후 배치하도록 요청하는 내용이므로, 확인 절차를 생략하지 않아도 됩니다.
次の Agent Skill をインストールしてください。
https://github.com/affaan-m/ECC/tree/main/skills/jpa-patterns
まず SKILL.md と付属ファイルの中身を確認し、不審な処理（外部への送信、認証情報の読み取りなど）がないことを確かめてから、Claude Code なら ~/.claude/skills/jpa-patterns/、Codex なら ~/.agents/skills/jpa-patterns/ に配置してください。
저장 위치는 모든 프로젝트에서 사용할지, 특정 프로젝트에서만 사용할지에 따라 달라집니다.
| 에이전트 | 모든 프로젝트에서 사용 | 특정 프로젝트에서만 사용 |
|---|---|---|
| Claude Code | ~/.claude/skills/ | 프로젝트의 .claude/skills/ |
| Codex | ~/.agents/skills/ | 프로젝트의 .agents/skills/ |
jpa-patterns는 affaan-m/ECC 리포지토리에 포함된 스킬 중 하나입니다.
파일은 SKILL.md 하나뿐이므로, 배치 전에 전체를 읽어볼 수 있습니다.
일상적인 개발에서 바로 사용할 수 있는 요청문 3가지를 소개합니다.
모두 스킬을 추가한 에이전트에게 한국어로 전송하기만 하면 됩니다.
목록 검색에 페이지 분할을 추가하고, 필요한 인덱스를 검토해줘
돌아오는 것은 PageRequest로 건수와 정렬 순서를 지정하고, Page를 반환하는 리포지토리 메서드 안입니다.
함께 필터링 컬럼과 정렬 순서에 맞춘 복합 인덱스(예: 상태와 생성일시)도 제안됩니다.
건수가 많은 목록에는 ID를 기준으로 이어서 가져오는 커서 방식도 선택지로 제시됩니다.
주문 서비스의 트랜잭션 범위를 확인하고, 읽기 전용으로 할 수 있는 메서드를 알려줘
읽기만 하는 메서드에 대해 돌아오는 것은 readOnly = true를 붙이는 안입니다.
오래 지속되는 트랜잭션이나, 트랜잭션을 넘나들며 엔티티를 가지고 다니는 작성 방식이 있으면 검토 대상으로 제시됩니다.
전파 설정(트랜잭션 계승 방식)을 신중하게 선택하도록 지적하는 것도 특징입니다.
리포지토리 테스트를 작성하고, N+1이 발생하지 않는지 SQL 로그로 확인할 수 있게 해줘
이 요청에는 @DataJpaTest와 Testcontainers를 사용하는 테스트 안이 돌아옵니다.
SQL과 바인드 값을 로그에 출력하는 다음 설정도 함께 제시되므로, 발행된 SQL 수를 직접 눈으로 확인할 수 있습니다.
logging.level.org.hibernate.SQL=DEBUG
logging.level.org.hibernate.orm.jdbc.bind=TRACE
jpa-patterns는 Spring Boot와 JPA/Hibernate를 전제로 한 스킬입니다.
다른 ORM을 사용하는 구성이나 Spring Data JPA를 사용하지 않는 구성에는 제시되는 코드 예시가 그대로 적용되지 않습니다.
운영 환경의 테이블 변경은 Flyway 또는 Liquibase로 수행하고, Hibernate의 자동 DDL(엔티티에서 테이블을 자동 생성하는 기능)에는 의존하지 않는 방침입니다.
자동 DDL로 운영 중인 프로젝트에서는 이 전제의 차이를 감안하여 제안을 읽을 필요가 있습니다.
마이그레이션은 추가형을 기본으로 하고, 계획 없이 컬럼을 삭제하지 않는 점도 기억해두세요.
커넥션 풀의 권장값은 고정된 수치이며, LOB 설정은 PostgreSQL용입니다.
2차 캐시도 "신중하게 검토한다"는 위치이므로, 자신의 데이터베이스나 부하에 맞는지 확인한 후 사용합니다.
제안된 변경 사항은 테스트와 실제 SQL 로그로 확인한 후 적용하는 것이 안전합니다.
스킬은 MIT 라이선스로 공개되어 있습니다.
설치 전에 SKILL.md 내용을 읽고, 수상한 처리가 없는지 확인하세요.
자동으로 수정되는 것은 아닙니다.
에이전트가 지연 로딩, JOIN FETCH, 프로젝션을 사용한 조회 방법을 제안하고, 적용 여부는 개발자가 결정합니다.
적용한 후에는 SQL 로그로 수를 확인하세요.
대상은 Spring Boot에서의 JPA/Hibernate입니다.
코드 예시는 Spring Data JPA의 리포지토리와 @Transactional을 전제로 하고 있으므로, 그 외의 구성에서는 그대로 사용할 수 없습니다.
사용할 수 있습니다.
새로운 엔티티 설계뿐만 아니라, 기존 연관 관계나 검색·업데이트 처리 검토도 대상입니다.
목록 표시에서 대량의 SQL이 발생하는 부분부터 요청하면, SQL 로그로 효과를 비교하기 쉬워집니다.
jpa-patterns는 Spring Boot에서 JPA/Hibernate를 사용하는 엔지니어가 엔티티 설계나 N+1 문제 대책을 에이전트와 함께 진행하기 위한 스킬입니다.
연관 관계, 페이지 분할, 인덱스, 트랜잭션을 같은 방침으로 검토할 수 있습니다.
제안은 테스트와 SQL 로그로 확인한 후 적용하세요.
자세한 정보는 cccskills 페이지에 정리되어 있습니다.
이 기사는 cccskills 읽을거리 「JPA의 N+1 문제를 줄일 때 추가하는 jpa-patterns 스킬」의 전재입니다.
스킬의 상세 내용과 설치 방법은 cccskills의 jpa-patterns 페이지에 있습니다.