0) TL;DR 🧾

• 문제: 조건 조합 폭발, 거대 메서드, JPA -> MyBatis 전환 등 문제
• 해법: Predicate(조건), Sort(정렬), Score(인기 점수) 등을 파일로 분리하고 어댑터에서 선언적으로 조립한다.
• 효과: ✨ 변경 용이 · 🧪 테스트성 · 🧩 재사용성 · 🧭 아키텍처 일관성.

---

🎯 1) 왜 이 구조인가?

😵 현장에서 겪는 문제

• 필터 조건이 늘어날수록 복잡해짐
• 키워드, 주제, 소스, 타입, 연도… 조건이 많아지니 코드가 if/else로 뒤엉킨다.
• 한 메서드가 너무 커짐
• 정렬 옵션(최신순, 다운로드순, 활용순 등), 인기 점수 계산, 조인, 그룹, 페이징까지 한 메서드 안에 다 몰려있다.
• 작은 변경도 큰 영향
• 필터 하나만 바꿨는데 전체 쿼리가 흔들리고, 사이드이펙트가 자주 발생한다.
• 로직이 지저분해짐

🎯 우리가 세운 목표

• 조건·정렬·집계는 따로따로
• 한 가지 책임만 맡도록 쪼개고, 어댑터에서 퍼즐 맞추듯 조립한다.
• 입력이 없으면 자동 무시
• null로 값이 없으면 where 절에서 그냥 빠져서, 깔끔하게 필터 조합이 가능하다.
• 쿼리 디테일은 어댑터에 몰아넣는다.
• 읽기 쿼리는 자유롭게 최적화
• 필요할 때 조인·프로젝션·페이징을 마음껏 써도 코어 로직은 흔들리지 않는다.

---

🔄 2) 한눈에 보는 흐름

[Web Controller]
  → [UseCase (Port In)]
  	→ [Service]
    	→ [Port Out (쿼리 인터페이스)]
      		→ [Query Adapter (QueryDSL)]
         		├─ Predicate 조립(키워드/토픽/소스/타입/연도 등)
         		├─ Sort 조립(최신/오래된/다운로드/활용순)
         		├─ Score 계산(다운로드·프로젝트수 가중치 계산)
         		├─ 조인/그룹/페이징
         		└─ 엔티티 <-> 도메인/DTO 매핑

운영 가시성: LoggerFactory.query().logQueryStart/End(...)로 쿼리 시작/종료를 표준 로깅한다.

---

🗂️ 3) 폴더 구성(핵심)

modules/dataset
 ├─ adapter
 │   ├─ jpa
 │   │   ├─ entity/ QDataEntity ...
 │   │   └─ mapper/ DataEntityMapper
 │   └─ query
 │       ├─ predicates/
 │       │   ├─ DataFilterPredicate.java      // id/keyword/topicId/sourceId/typeId
 │       │   └─ DataDatePredicate.java        // yearBetween
 │       ├─ sort/
 │       │   ├─ DataSortBuilder.java          // 정렬 옵션 → OrderSpecifier[]
 │       │   └─ DataPopularOrderBuilder.java  // 인기 점수 계산식
 │       ├─ ReadDataQueryDslAdapter.java      // 단건/연결/최근/인기/그룹 카운트
 │       └─ SearchDataQueryDslAdapter.java    // 복합 필터 + 정렬 + 페이징
 ├─ application
 │   ├─ port/out/query/read/*, /search/*
 │   └─ dto/request/search/FilteringDataRequest
 │             /response/support/DataWithProjectCountDto
 └─ domain
     ├─ model/Data
     └─ enums/DataSortType (LATEST/OLDEST/DOWNLOAD/UTILIZE)

---

🧩 4) 핵심 빌딩 블록(코드 발췌)

4.1 Predicate — 조건은 메서드로 쪼개고 null-무시

public static BooleanExpression keywordContains(String keyword) {
    if (!StringUtils.hasText(keyword)) return null;
    return dataEntity.title.containsIgnoreCase(keyword)
        .or(dataEntity.description.containsIgnoreCase(keyword));
}

public static BooleanExpression yearBetween(Integer year) {
    if (year == null) return null;
    NumberTemplate<Integer> s = Expressions.numberTemplate(Integer.class, "year({0})", data.startDate);
    NumberTemplate<Integer> e = Expressions.numberTemplate(Integer.class, "year({0})", data.endDate);
    return s.loe(year).and(e.goe(year));
}

무엇을 하나요?

• keywordContains는 제목/설명 컬럼에 대소문자 무시 부분 검색을 건다.
• yearBetween은 주어진 연도가 startDate ~ endDate 사이에 포함되는지를 판단

왜 이렇게 쪼개나요?

• SRP(단일 책임): 조건 하나당 메서드 하나면, 변경/추가/테스트가 쉽다.
• null-무시 패턴: 입력이 없으면 null을 반환해서 where(a, b, null, d)처럼 자동으로 스킵된다( QueryDSL이 null은 무시 ).

어떻게 동작하나요?

• keywordContains: 공백/빈 문자열은 바로 null 반환 → where 절에서 제외.
• 실제 SQL은 LOWER(title) like %keyword% OR LOWER(description) like %keyword% 형태가 된다.
• yearBetween: DB 함수 year(date)로 startDate ≤ year ≤ endDate를 검사.
• 한 줄로 합쳐 가독성을 챙기고, 다른 조건들과 조립되도록 BooleanExpression을 반환한다.

🧪 테스트 포인트:

• keyword = null / "" / " "일 때 null 반환되는지
• year = null, 범위 경계(예: 구간 시작/끝 연도) 포함 여부
• 다국어/대소문자 케이스

4.2 Sort & Score — 선언적 정렬 / 가중치 점수

public static OrderSpecifier<?>[] fromSortOption(DataSortType sort, NumberPath<Long> projectCountPath) {
    QDataEntity data = QDataEntity.dataEntity;
    if (sort == null) return new OrderSpecifier[]{data.createdAt.desc()};
    return switch (sort) {
        case LATEST   -> new OrderSpecifier[]{data.createdAt.desc()};
        case OLDEST   -> new OrderSpecifier[]{data.createdAt.asc()};
        case DOWNLOAD -> new OrderSpecifier[]{data.downloadCount.desc()};
        case UTILIZE  -> new OrderSpecifier[]{projectCountPath.desc()};
    };
}

public static NumberExpression<Double> popularScore(QDataEntity data, NumberExpression<Long> projectCountExpr) {
    NumberExpression<Double> projectScore  = projectCountExpr.castToNum(Double.class).multiply(1.5);
    NumberExpression<Double> downloadScore = data.downloadCount.castToNum(Double.class).multiply(2.0);
    return downloadScore.add(projectScore);
}

무엇을 하나요?

• fromSortOption은 DataSortType에 따라 정렬 기준을 OrderSpecifier[]로 돌려준다.
  (최신/오래된/다운로드/활용순)
• popularScore는 다운로드×2.0 + 프로젝트수×1.5로 인기 점수를 계산하여 인기있는 프로젝트 목록을 조회한다.

왜 이렇게 쪼개나요?

• 선언적 제어: 정렬 정책을 enum에 맵핑하면, “어떤 기준으로 정렬하는가”가 한눈에 들어올 수 있다.
• 새 기준이 생겨도 스위치 한 칸 추가로 끝.
• 비즈니스 분리: 인기 점수 공식을 한 파일에 모아두면, 가중치만 바꿔도 다른 쿼리를 안 건드려도 가능하다.

4.3 Search 어댑터 — 복합 필터 + 정렬 + 페이징

@Override
public Page<DataWithProjectCountDto> searchByFilters(FilteringDataRequest request,
                                                    Pageable pageable, DataSortType sortType) {
    NumberPath<Long> projectCountPath = Expressions.numberPath(Long.class, "projectCount");

    List<Tuple> tuples = queryFactory
        .select(data, projectData.id.count().as(projectCountPath))
        .from(data)
        .leftJoin(projectData).on(projectData.dataId.eq(data.id))
        .leftJoin(data.metadata).fetchJoin()
        .where(
            DataFilterPredicate.keywordContains(request.keyword()),
            DataFilterPredicate.topicIdEq(request.topicId()),
            DataFilterPredicate.dataSourceIdEq(request.dataSourceId()),
            DataFilterPredicate.dataTypeIdEq(request.dataTypeId()),
            DataDatePredicate.yearBetween(request.year())
        )
        .groupBy(data.id)
        .orderBy(DataSortBuilder.fromSortOption(sortType, projectCountPath))
        .offset(pageable.getOffset())
        .limit(pageable.getPageSize())
        .fetch();

    List<DataWithProjectCountDto> contents = tuples.stream()
        .map(t -> new DataWithProjectCountDto(DataEntityMapper.toDomain(t.get(data)),
                                              t.get(projectCountPath)))
        .toList();

    long total = Optional.ofNullable(
        queryFactory.select(data.id.countDistinct())
            .from(data)
            .leftJoin(projectData).on(projectData.dataId.eq(data.id))
            .where(
                DataFilterPredicate.keywordContains(request.keyword()),
                DataFilterPredicate.topicIdEq(request.topicId()),
                DataFilterPredicate.dataSourceIdEq(request.dataSourceId()),
                DataFilterPredicate.dataTypeIdEq(request.dataTypeId()),
                DataDatePredicate.yearBetween(request.year())
            )
            .fetchOne()
    ).orElse(0L);

    return new PageImpl<>(contents, pageable, total);
}

무엇을 하나요?

• 여러 필터(키워드/토픽/소스/타입/연도)를 조립하고,
  프로젝트 연결수(projectCount)를 집계한 뒤,
  정렬 + 페이징을 적용해 페이지 응답을 만들어준다.

왜 이렇게 구성했나요?

• 읽기 전용 최적화: 조인/그룹/프로젝션을 어댑터 수준에서 자유롭게 쓰고,
  도메인/유스케이스는 단순한 계약만 유지한다.
• 카운트 분리: contents 조회와 total 카운트를 분리하면,
  데이터 양이 커져도 확장성이 좋다(한 번에 fetchResults()는 비추천/Deprecated).

어떻게 동작하나요?

• projectCountPath라는 파생 컬럼(NumberPath)을 선언해 프로젝트 활용 수count() 결과를 담을 별칭을 준비.
• select(data, projectData.id.count().as(projectCountPath))로
  엔티티 + 해당 데이터셋에 연결된 프로젝트 수를 한 번에 조회.
• leftJoin(projectData)로 연결 여부가 없어도 데이터가 나오게 하고,
  leftJoin(data.metadata).fetchJoin()으로 메타데이터 N+1 방지(1:1 매핑 관계).
• where(...)에 Predicate 메서드들을 나열(입력 없으면 null → 자동 스킵).
• groupBy(data.id)로 데이터셋별로 연결수 집계.
• orderBy(DataSortBuilder.fromSortOption(sortType, projectCountPath))로
  선언적 정렬을 적용.
• offset/limit으로 페이징.
• 결과 Tuple을 DataEntityMapper로 도메인 변환해 DTO에 담음.
• total은 별도 쿼리로 countDistinct()만 수행(동일 where, 조인은 최소화 가능).

현업에서의 팁/주의점 (추후 확장 고려)

• ⚖️ fetch-join + 페이징: 컬렉션(@OneToMany)을 fetch-join하면 페이징이 꼬일 수 있다.
• 컬렉션이면 배치/2-step 조회로 전략을 추후 고려해본다.
• 🧮 countDistinct 비용: 큰 테이블에서는 비싸다.
• 캐시/프리카운트/근실시간 집계 테이블로 보완하거나, 필터가 단순하면 카운트 쿼리를 간소화한다(불필요한 조인 제거).
• 🚀 대량 페이지 탐색: 깊은 페이지로 갈수록 offset 비용이 크다.
  추후 키셋 페이징(seek)으로 바꿀 수 있도록 정렬 컬럼(예: createdAt, id)을 준비해두면 좋다.

🧪 테스트 포인트:

• 각 필터 조합(입력/미입력)에서 결과 건수/페이지 수가 기대대로 나오는지
• 정렬 옵션별 상위 몇 건의 정렬 일치 여부
• 연결수가 없는 데이터도 빠지지 않는지(left join 확인)

---

✨ 5) 효과

1. 변경 내성: “조건 하나 바뀌면 그 파일만 고친다.”
2. 유지보수성: 거대 쿼리 대신 작은 모듈을 리뷰/교체.
3. 테스트성: Predicate/Sort는 순수 단위 테스트로 검증 가능.
4. 전환 유연성: JPA→MyBatis 전환 시에도 Port 계약/DTO/도메인 모델은 그대로 사용.

---

🧯 6) 주의사항 - 추후 고려사항

• 🔎 함수 기반 표현식은 인덱스 활용을 방해 → 범위 비교/생성 컬럼 인덱스 활용.
• ⚖️ fetch join + paging: 컬렉션 fetch-join은 페이징 제약 → 배치 사이즈/2-step 조회/전용 읽기 모델 분리.
• 🧮 countDistinct 비용: 대형 데이터셋에서는 비쌈 → 캐시/프리카운트/근실시간 집계 고려.
• 🧱 가중치 변경: 인기 점수 가중치는 설정값/전략 패턴 분리로 운영 변경 용이.

---

🧑‍🏫 7) 결론

쿼리를 쪼개서 조립하면, 기능이 늘어나도 복잡도를 통제할 수 있다.
핵심은 작게 추가 · 안전하게 변경 · 쉽게 테스트다.
팀 컨벤션으로 정착시키면 “필터 하나 추가했는데 왜 전체가 깨지죠?”라는 질문이 사라질 수 있어 설계 상 유리할 수 있을 것 같다는 생각이 든다. 🚀

추후 더 고려해야 할 요소들이 있기에 계속 리팩토링하여 개선해 나갈 계획을 해야겠다.