복잡한 Native 쿼리를 JOOQ로 치환하여 유지보수성을 높인 사례

배경

재고이관 에픽을 긴급하게 진행하게 되면서, 일반적으로 지켜야 할 개발 규칙이나 코드 품질 기준을 지키지 못한 채 기능 구현이 이루어진 상황이 있었습니다. 특히 재고이관 목록 조회 기능의 경우, 쿼리 자체가 복잡하여 Querydsl로는 기능 구현이 불가능했기 때문에, 부득이하게 Native Query로 기능을 작성하게 되었습니다.

이러한 방식은 단기적으로는 문제 해결에 도움이 되었지만, 결과적으로는 해당 코드를 작성한 사람 외에는 이해하거나 유지보수하기 어려운 구조로 이어졌습니다. 쿼리 복잡성과 DSL의 표현 한계로 인해, 코드의 재사용성과 확장성 모두 저하된 상태였습니다.

목적

이러한 상황을 개선하기 위해 다음과 같은 목표를 수립하였습니다.

• 기존에 작성된 Native Query 기반의 코드를 제거하고, 유지보수가 가능한 구조로 리팩토링하고자 하였습니다.

• 앞으로도 복잡한 쿼리를 요하는 기능 개발이 예상되므로, Querydsl 외에도 다양한 DSL을 사용할 수 있는 기반 환경을 구성하고자 하였습니다.

기술적 해결 방안

위 문제를 해결하기 위한 방법으로 **JOOQ(Java Object Oriented Querying)**를 도입하였습니다. JOOQ는 SQL 쿼리를 타입 세이프하게 Java 코드로 작성할 수 있는 DSL 도구로, 다음과 같은 이유로 적합하다고 판단하였습니다.

Querydsl의 현황

2024년 6월을 마지막으로 공식적인 Querydsl 릴리즈는 더 이상 제공되지 않고 있으며, 현재는 OpenFeign에서 별도로 포크하여 유지 중인 것으로 파악됩니다. 그러나 해당 저장소는 활동성이나 별(star) 수를 기준으로 볼 때, 활발하게 유지되고 있다고 보기 어렵습니다.

JOOQ 선정 기준

다음의 조건을 만족하는 DSL 도구를 찾고자 했습니다:

• Querydsl처럼 타입 세이프한 문법을 제공할 것

• array_agg, && 등과 같이 데이터베이스 종속적인 SQL 문법도 지원할 것

이러한 조건을 만족한 도구는 자바 진영에서 사실상 JOOQ 하나뿐이었습니다.

JOOQ의 장단점 분석

장점

• 기존 Querydsl과 문법 구조가 유사하여, 러닝 커브가 낮습니다.

• Querydsl보다 더 복잡한 SQL 구문을 표현할 수 있어 유연합니다.

• 오픈소스로 제공되므로, 별도의 비용 없이 도입이 가능합니다.

단점

• JPA와의 연계 사용이 쉽지 않으며, 영속성 관리가 어렵습니다.

• 쿼리 결과를 매핑하거나 트랜잭션을 관리하기 위해서는 별도 설정과 구현이 필요합니다.

도입 결과

기존 재고이관 목록 조회 기능에서 사용하던 Native Query를 JOOQ로 전면 교체하였고, 테스트 결과 정상적으로 동작함을 확인하였습니다. 특히, 커스텀 로직 없이도 쿼리를 유연하게 작성할 수 있었기 때문에, 학습 시간을 제외하면 개발에 소요된 실제 시간은 오히려 단축되는 결과를 얻었습니다.

작업 시간 비교

작업 코드

수정 전

String sql = "SELECT CASE WHEN ... THEN ... ELSE ... END AS location_type, " +
             "       MIN(workplace_id), " +
             "       ARRAY_AGG(location_code), " +
             "       ... " +
             "FROM ... " +
             "WHERE workplace_id = ? AND ... " +
             "GROUP BY location_type, parent_space_id " +
             "HAVING SUM(picking_quantity) > 0 AND ...";

List<Object[]> result = entityManager.createNativeQuery(sql).getResultList();

return result.stream()
    .map(row -> ExternalStockMoveOrderSearchDTO.createFrom(row))
    .collect(Collectors.toList());

수정 후

Field<String> locationType = DSL
    .when(space.SPACE_NAME.in(DANPLA_SPACE_NAMES).and(attr.PURPOSE.eq("STOW")), "DANPLA")
    .otherwise(space.LOCATION_CODE);

return dslContext.select(
        locationType,
        DSL.min(stock.WORKPLACE_ID),
        DSL.arrayAggDistinct(space.LOCATION_CODE),
        ...
    )
    .from(space)
    .join(attr).on(space.SPACE_ID.eq(attr.SPACE_ID))
    .join(stock).on(stock.SPACE_ID.eq(space.SPACE_ID))
    .where(
        stock.WORKPLACE_ID.eq(param.getOutboundWorkplaceId()),
        space.SPACE_TYPE.eq("CELL"),
        stock.QUANTITY.gt(0),
        stock.SPACE_ID.notIn(param.getExcludedSpaceIds())
    )
    .groupBy(locationType, space.PARENT_SPACE_ID)
    .having(
        hasPickingCondition(param),
        hasIssueCondition(param),
        ...
    )
    .fetchInto(ExternalStockMoveOrderSearchDTO.class);

수정 전과 후를 비교해보았을 때 엔지니어의 입장에서 수정 후가 훨씬 유지보수하기 쉽다는 것을 직관적으로 느낄 수 있었습니다.

참고 자료

• JOOQ 공식 사이트

• JOOQ GitHub

• JOOQ Gradle Plugin GitHub

• OpenFeign/Querydsl GitHub