리포지터리

repository: 는 엔티티의 Spring Data 리포지터리에 쿼리 메서드를 더합니다. 키는 엔티티 이름이고, 메서드는 methods: 목록으로 적습니다.

model/repository.yml

repository:
  Stock:
    methods:
      # 파생 쿼리 - query 없이 이름만으로
      - id: findByItemItemCodeAndWarehouse
        params:
          itemCode: string
          warehouse: string
        return: Optional<Stock>

      # JPQL
      - id: findLowStock
        params:
          threshold: int
        return: List<Stock>
        query: "SELECT s FROM Stock s WHERE s.onHand < :threshold ORDER BY s.onHand"

      # 페이징
      - id: findByWarehouse
        params:
          warehouse: string
        return: Page<Stock>
        pageable: true

키	뜻
id	메서드 이름
params	파라미터 (이름: DSL 타입)
return	List<Entity>, Optional<Entity>, Entity, Page<Entity>, long, DTO ...
query	JPQL. 없으면 Spring Data 파생 쿼리
nativeQuery: true	네이티브 SQL
pageable: true	마지막 파라미터로 Pageable

methods 목록이 없는 항목(메서드를 키로 적은 형식)은 읽히지 않습니다: 생성기가 경고하고 건너뜁니다.

읽기 모델: DTO 로 투영

화면·보고서는 애그리거트가 아니라 DTO 를 읽습니다. 반환 타입을 DTO 로 적고, 컬럼 별칭을 DTO 속성 이름에 맞춥니다:

repository:
  SalesOrder:
    methods:
      - id: summarizeByPartner
        params: { status: OrderStatus }
        return: List<PartnerSalesDTO>
        query: "SELECT o.partner.partnerId AS partnerId, o.partner.name AS partnerName, COUNT(o) AS orderCount, SUM(o.totalAmount) AS totalAmount FROM SalesOrder o WHERE o.status = :status GROUP BY o.partner.partnerId, o.partner.name"

v3·Kotlin 에서 리포지터리는 List<Tuple> 을, 조회 포트는 List<PartnerSalesDTO> 를 돌려줍니다: 어댑터가 별칭으로 속성을 채웁니다(대소문자·밑줄 무시, 타입 변환 포함). 별칭이 없는 컬럼은 오류입니다. 2.x 호환 출력은 예전처럼 List<Object[]> 입니다.

DDD·헥사고날 번들에서

선언	놓이는 곳	이유
조회 + 반환이 Root / Optional<Root> / List<Root> + 페이징 아님	RootRepositoryPort (도메인)	도메인 서비스가 애그리거트를 찾는 질문
그 밖 (Page, DTO 투영, count, 수정 쿼리)	RootQueryPort (애플리케이션)	화면·조회용이거나 애그리거트를 거치지 않는 일괄 쓰기

// StockRepositoryPort (생성)
Optional<Stock> findByItemItemCodeAndWarehouse(String itemCode, String warehouse);

보존 블록

생성된 리포지터리에 둬야 하는 코드는 클래스를 닫는 괄호 바로 앞에 보존 블록 하나로 둡니다. 다시 생성해도 남습니다:

// !-----------------------------------------------------------

@Query("SELECT e FROM Entity e WHERE e.name = :name")
List<Entity> findByName(@Param("name") String name);

// ------------------------------------------------------------!

JPA 밖의 SQL(네이티브 보고서, 다른 데이터소스)은 DBMS 포트입니다.