Allra 데이터베이스 설계 및 QueryDSL 사용 규칙. Use when creating JPA entities, writing QueryDSL queries, or adding @Transactional annotations.
View on GitHubbackend-plugin/skills/database-schema/SKILL.md
February 1, 2026
Select agents to install to:
npx add-skill https://github.com/Allra-Fintech/allra-ai-skills/blob/main/backend-plugin/skills/database-schema/SKILL.md -a claude-code --skill allra-database-schemaInstallation paths:
.claude/skills/allra-database-schema/# Allra Database 설계 및 QueryDSL 규칙
Allra 백엔드 팀의 데이터베이스 설계, JPA, QueryDSL, 트랜잭션 관리 표준을 정의합니다.
## 프로젝트 기본 정보
이 가이드는 다음 환경을 기준으로 작성되었습니다:
- **Java**: 17 이상
- **Spring Boot**: 3.2 이상
- **ORM**: JPA/Hibernate
- **Query Library**: QueryDSL (선택 사항)
- **Testing**: Testcontainers (선택 사항)
**참고**: 프로젝트별로 사용하는 데이터베이스(MariaDB, PostgreSQL, MySQL 등)와 라이브러리가 다를 수 있습니다.
## QueryDSL 사용 규칙
### 1. Repository 구조 (Allra 권장 패턴)
JPA Repository와 Support 인터페이스를 함께 사용:
```java
// JPA Repository 인터페이스
public interface UserRepository extends JpaRepository<User, Long>, UserRepositorySupport {
}
// QueryDSL Support 인터페이스
public interface UserRepositorySupport {
List<UserSummaryDto> findUserSummaries(UserSearchCondition condition);
}
// QueryDSL Support 구현체
@Repository
public class UserRepositoryImpl implements UserRepositorySupport {
private final JPAQueryFactory queryFactory;
@Override
public List<UserSummaryDto> findUserSummaries(UserSearchCondition condition) {
return queryFactory
.select(new QUserSummaryDto(
user.id,
user.email,
user.name
))
.from(user)
.where(
emailContains(condition.email()),
nameContains(condition.name())
)
.fetch();
}
private BooleanExpression emailContains(String email) {
return email != null ? user.email.contains(email) : null;
}
}
```
**참고**: Support 패턴은 선택 사항입니다. 프로젝트에 따라 `@Query` 어노테이션이나 다른 방식을 사용할 수 있습니다.
### 2. QueryDSL DTO Projection
Record와 `@QueryProjection` 사용:
```java
public record UserSummaryDto(
Long id,
String email,
String name
) {
@QueryProjection
public UserSummaryDto {}
}
```
**빌드 설정**:
Gradle:
```gradle
annotationProcessor "com.querydsl:querydsl-apt:${queryDslVersion}:jakarta"
```
Maven:
```xml
<plugin>
<groupId>com.mysema.maven</groupId>
<artifactId>apt-maven-plugin</artifactId>
<version>1.1.3</version>
Issues Found: