Agent skill

allra-database-schema

Allra 데이터베이스 설계 및 QueryDSL 사용 규칙. Use when creating JPA entities, writing QueryDSL queries, or adding @Transactional annotations.

View SKILL.md on GitHub Repository
Stars 232
Forks 15

Install this agent skill to your Project

npx add-skill https://github.com/aiskillstore/marketplace/tree/main/skills/allra-fintech/allra-database-schema

SKILL.md

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>
    <executions>
        <execution>
            <goals>
                <goal>process</goal>
            </goals>
            <configuration>
                <outputDirectory>target/generated-sources/java</outputDirectory>
                <processor>com.querydsl.apt.jpa.JPAAnnotationProcessor</processor>
            </configuration>
        </execution>
    </executions>
</plugin>

3. From 절에 맞는 Repository 위치

From절에 해당하는 Repository에 정의하는 것을 권장:

java
// ❌ 피하기: Order에서 User를 조회
public interface OrderRepositorySupport {
    List<UserDto> findUsersByOrderDate(LocalDate date); // From user
}

// ✅ 권장: User에서 Order를 조인
public interface UserRepositorySupport {
    List<UserOrderDto> findUsersWithOrders(LocalDate date); // From user
}

4. 데이터베이스 호환성

QueryDSL 작성 시 사용 중인 데이터베이스의 특성을 고려:

java
// 일반적인 쿼리
queryFactory
    .selectFrom(user)
    .where(user.createdAt.between(startDate, endDate))
    .fetch();

// LIMIT/OFFSET
queryFactory
    .selectFrom(user)
    .limit(10)
    .offset(0)
    .fetch();

참고: 윈도우 함수나 특정 DB 함수는 데이터베이스 버전에 따라 지원 여부가 다를 수 있습니다.

5. xxxRepositorySupport 직접 의존 금지

반드시 JPA Repository 인터페이스를 통해 사용:

java
// ❌ 잘못된 예
@Service
public class UserService {
    private final UserRepositoryImpl userRepositoryImpl; // 구현체 직접 주입
}

// ✅ 올바른 예
@Service
public class UserService {
    private final UserRepository userRepository; // 인터페이스 주입
}

@Transactional 사용 가이드

필수 규칙

각 서비스 메서드에 명시적으로 선언:

  1. 조회 쿼리만: @Transactional(readOnly = true)
  2. 변경 쿼리 포함: @Transactional

예제

java
@Service
public class UserService {

    private final UserRepository userRepository;

    // 읽기 전용 트랜잭션
    @Transactional(readOnly = true)
    public List<User> findAllUsers() {
        return userRepository.findAll();
    }

    // 쓰기 트랜잭션
    @Transactional
    public User createUser(SignUpRequest request) {
        User user = User.create(request.email(), request.password());
        return userRepository.save(user);
    }

    // 조회 + 변경
    @Transactional
    public User activateUser(Long id) {
        User user = userRepository.findById(id)
            .orElseThrow(() -> new UserNotFoundException(id));
        user.activate(); // 변경
        return user;
    }
}

참고: 트랜잭션 전파(Propagation)는 기본값(REQUIRED)을 사용하며, 특수한 경우에만 명시합니다.

JPA Entity 설계 가이드

기본 구조

java
@Entity
@Table(name = "users")
@Getter
@NoArgsConstructor(access = AccessLevel.PROTECTED)
public class User {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false, unique = true, length = 100)
    private String email;

    @Column(nullable = false, length = 100)
    private String name;

    @Enumerated(EnumType.STRING)
    @Column(nullable = false, length = 20)
    private UserStatus status;

    @CreatedDate
    @Column(nullable = false, updatable = false)
    private LocalDateTime createdAt;

    @LastModifiedDate
    @Column(nullable = false)
    private LocalDateTime updatedAt;

    // 정적 팩토리 메서드
    public static User create(String email, String password, String name) {
        User user = new User();
        user.email = email;
        user.password = password;
        user.name = name;
        user.status = UserStatus.ACTIVE;
        return user;
    }

    // 비즈니스 메서드
    public void activate() {
        this.status = UserStatus.ACTIVE;
    }
}

연관관계 매핑

java
@Entity
public class Order {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    // ManyToOne - 지연 로딩 권장
    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "user_id", nullable = false)
    private User user;

    // OneToMany - 지연 로딩, Cascade 설정
    @OneToMany(mappedBy = "order", cascade = CascadeType.ALL, orphanRemoval = true)
    private List<OrderItem> items = new ArrayList<>();

    // 연관관계 편의 메서드
    public void addItem(OrderItem item) {
        items.add(item);
        item.setOrder(this);
    }
}

참고: 연관관계는 지연 로딩(LAZY)을 기본으로 사용하는 것을 권장합니다.

When to Use This Skill

이 skill은 다음 상황에서 자동으로 적용됩니다:

  • JPA Entity 생성 및 수정
  • QueryDSL 쿼리 작성
  • Repository 인터페이스 및 구현체 작성
  • Service 메서드에 @Transactional 추가
  • DTO Projection 작성

Checklist

데이터베이스 관련 코드 작성 시 확인사항:

  • QueryDSL Support가 JPA Repository에 상속되어 있는가? (Support 패턴 사용 시)
  • QueryDSL 구현체가 From절에 맞는 Repository에 있는가?
  • DTO Projection에 @QueryProjection이 적용되었는가? (QueryDSL 사용 시)
  • Service의 모든 public 메서드에 @Transactional이 명시되었는가?
  • 읽기 전용 메서드에 readOnly = true가 적용되었는가?
  • MariaDB 호환성을 고려했는가?
  • Entity의 연관관계가 지연 로딩(LAZY)으로 설정되었는가?
  • xxxRepositorySupport 구현체를 직접 주입하지 않았는가?

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

aiskillstore/marketplace

perigon-backend

Perigon ASP.NET Core + EF Core + Aspire conventions

232 15
Explore
aiskillstore/marketplace

perigon-agent

Pointers for Copilot/agents to apply Perigon conventions

232 15
Explore
aiskillstore/marketplace

perigon-angular

Angular 21+ standalone/Material/signal conventions for Perigon WebApp

232 15
Explore
aiskillstore/marketplace

fastapi-mastery

Comprehensive FastAPI development skill covering REST API creation, routing, request/response handling, validation, authentication, database integration, middleware, and deployment. Use when working with FastAPI projects, building APIs, implementing CRUD operations, setting up authentication/authorization, integrating databases (SQL/NoSQL), adding middleware, handling WebSockets, or deploying FastAPI applications. Triggered by requests involving .py files with FastAPI code, API endpoint creation, Pydantic models, or FastAPI-specific features.

232 15
Explore
aiskillstore/marketplace

context7-efficient

Token-efficient library documentation fetcher using Context7 MCP with 86.8% token savings through intelligent shell pipeline filtering. Fetches code examples, API references, and best practices for JavaScript, Python, Go, Rust, and other libraries. Use when users ask about library documentation, need code examples, want API usage patterns, are learning a new framework, need syntax reference, or troubleshooting with library-specific information. Triggers include questions like "Show me React hooks", "How do I use Prisma", "What's the Next.js routing syntax", or any request for library/framework documentation.

232 15
Explore
aiskillstore/marketplace

browser-use

Browser automation using Playwright MCP. Navigate websites, fill forms, click elements, take screenshots, and extract data. Use when tasks require web browsing, form submission, web scraping, UI testing, or any browser interaction.

232 15
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results