OpenFeign Querydsl을 예시로 알아보는 Spring Boot + Maven 외부 라이브러리 설정법

목표 : Spring Boot가 관리해주지 않는 외부 라이브러리를 사용하고 싶을 때, 원하는 버전을 어떻게 찾아가는지 OpenFeign Querydsl 을 예시로 알아가는 것입니다.

 

사용 환경

• 빌드 도구: Maven (Gradle은 본문에서 일부만 간단히 다룹니다)
• IDE: IntelliJ Ultimate
• 프레임워크: Spring Boot

pom.xml 설정 예시는 글 하단의 "결론"에 제시되어 있으며, 그 설정에 이르기까지의 과정을 소개합니다.

 

Querydsl vs OpenFeign Querydsl

Querydsl(https://github.com/querydsl/querydsl)

• 5.0.0 버전: 2021년 7월 릴리스
• 5.1.0 버전: 2024년 1월 30일 릴리스

3년 가까이 큰 업데이트 없이 유지되다 1년전에 릴리스 되며 지속적으로 관리되지 않는 프로젝트입니다.

OpenFeign의 Querydsl(https://github.com/OpenFeign/querydsl)

OpenFeign이 포크해서 유지보수 중인 Querydsl은 README에서도 볼 수 있듯이 최종 목표는 Get a querydsl project active!

즉, 다시 Querydsl 프로젝트를 활성화 하는 것으로 지속적으로 관리되고 있습니다.

 

이러한 차이를 소개한 이유는 Querydsl과 OpenFeign Querydsl은 이름은 비슷하지만, 전혀 다른 프로젝트이니 Maven/Gradle 에 필요한 의존성도 다르기 때문입니다.

 

Querydsl 의 의존성은 com.querydsl , OpenFeign Querydsl 의존성은 io.github.openfeign.querydsl 입니다.

 

Spring Boot가 관리하는 Querydsl 버전

Spring Boot는 자동 라이브러리 구성을 통해 여러 오픈소스 라이브러리들의 버전을 일일이 우리가 관리하지 않도록 해줍니다. 그러면 Spring Boot 3.4.x에서는 어떤 Querydsl 버전을 기본으로 사용하는지 확인해봅시다.

 

IntelliJ에서 pom.xml을 열고 나면, 다음과 같은 구조를 자주 봅니다.해당 빨간색 네모박스로 표시된 설정파일에 Ctrl + B 로 들어갑니다.

pom.xml 에서 사용중인 Spring Boot의 pom

 

** Gradle 은 어디서 찾아야 하는지?

Maven은 이렇게 IDE에서 부모 설정으로 자동으로 잘 따라갈 수 있었지만, Gradle 은 Ctrl + B를 눌러도 바로 이동되지 않기 때문에, 직접 해당 설정 파일을 찾아봤습니다.

 

Gradle은 https://github.com/spring-projects/spring-boot/blob/main/spring-boot-project/spring-boot-dependencies/build.gradle 에 접속해서 원하시는 기술의 버전을 확인하시면 됩니다. Spring Boot 3.4.x 기준으로 Querydsl의 버전은 5.1.0입니다.

Spring Boot 3.4.x 의 Querydsl 버전

 

다시 돌아와서 Maven의 경우, 앞서 언급한 spring-boot-starter-parent에서 Ctrl + B를 누르면 아래 사진처럼 spring-boot-starter-parent-3.4.4.pom 파일이 열리게 됩니다.

 

이 파일의 가장 위쪽을 보면 다음과 같이 spring-boot-dependencies를 찾을 수 있고, Ctrl B 를 통해 들어가면 여러 라이브러리 버전이 정의된 spring-boot-dependencies로 이동하게 됩니다.

spring-boot-starter-parent-3.4.4.pom

 

여러 라이브러리들을 확인할 수 있는데, 아래 예시처럼 Spring Batch나 Spring Data와 관련된 라이브러리들도 관리됨을 볼 수 있습니다.

<dependencyManagement>
     <dependency> <!-- Spring Batch 버전 -->
        <groupId>org.springframework.batch</groupId>
        <artifactId>spring-batch-bom</artifactId>
        <version>${spring-batch.version}</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
      <dependency> <!-- Spring Data 버전 -->
        <groupId>org.springframework.data</groupId>
        <artifactId>spring-data-bom</artifactId>
        <version>${spring-data-bom.version}</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
 <dependencyManagement>

 

이제 Ctrl + F로 "querydsl"이라는 키워드를 검색하면 아래처럼 querydsl 의존성을 찾게 됩니다.

Spring Boot 에서 관리하고 있는 querydsl 라이브러리

 

여기서 ${querydsl.version}처럼 ${...}로 된 문법은 Maven의 변수 문법입니다. 이는 Gradle의 ext 또는 Java의 전역 변수처럼, 한 곳에서 선언한 값을 여러 곳에서 반복해서 쓰기 위함입니다.

 

querydsl.version 을 Ctrl + F 로 찾으면, <properties> 태그에 5.1.0 버전으로 선언한 것을 찾을 수 있습니다.

com.querydsl 의 버전

즉, 프로젝트 전체에서 쓰이는 Querydsl의 버전 5.1.0을 querydsl.version이라는 이름으로 지정하고, 필요한 곳에서 이 값을 참조해 사용하는 것입니다. 

 

결론, 스프링부트 3.4.x 는 com.querydsl 의 5.1.0 을 사용중입니다.

 

OpenFeign Querydsl의 의존성 설정 과정

앞서 살펴봤듯이, Spring Boot 3.4.x는 기본적으로 com.querydsl의 5.1.0 버전을 사용합니다.

 

하지만 저는 OpenFeign 팀에서 별도로 관리하고 있는 Querydsl을 사용하고자 합니다. 이 프로젝트는 OpenFeign Querydsl Github에서 확인할 수 있고, 지금도 활발히 6.11과 같은 최신 버전이 릴리스되고 있습니다.

 

그래서 아래와 같이 pom.xml에 버전을 6.10.1로 설정하고, Maven 빌드를 했더니 에러가 발생했습니다.

<properties>
    <java.version>17</java.version> <!-- 프로젝트 자바 버전 -->
    <querydsl.version>6.10.1</querydsl.version> <!-- 사용할 querydsl 버전 -->
</properties>

 

에러 발생 !

Non-resolvable import POM: The following artifacts could not be resolved: com.querydsl:querydsl-bom:pom:6.10.1 (absent): com.querydsl:querydsl-bom:pom:6.10.1 was not found in https://repo.maven.apache.org/maven2 during a previous attempt.

 

이 에러의 의미는 다음과 같습니다.

• <querydsl.version>이라는 변수는 원래 Spring Boot의 spring-boot-dependencies에서 사용하던 변수입니다.
• 그런데 제가 프로젝트에서 이 변수를 6.10.1로 override(덮어씀) 하게 되었으며, Maven 빌드할 때, com.querydsl 에서 6.10.1 버전을 찾으려 시도합니다.
• 하지만 com.querydsl 의 최신 릴리스는 5.1.0이라서, 6.10.1이라는 버전은 존재하지 않습니다.
• 그래서 Maven은 "존재하지 않는 버전이다"라는 식의 에러를 던지는 것입니다.

그래서 <querydsl.version>를 사용하지 않고 아래처럼 사용할 버전을 명시하면 되지만, 하드코딩된 것이 영 불편합니다. (각 모듈에 관한 설명은 조금 기다려주세요)

<dependency> <!-- Openfeign Querydsl 의 jpa 모듈 -->
        <groupId>io.github.openfeign.querydsl</groupId>
        <artifactId>querydsl-jpa</artifactId>
        <version>6.10.1</version>
</dependency>
<dependency> <!-- Openfeign Querydsl 의 apt 모듈 -->
        <groupId>io.github.openfeign.querydsl</groupId>
        <artifactId>querydsl-apt</artifactId>
        <classifier>jakarta</classifier>
        <version>6.10.1</version>
</dependency>
<dependency> <!-- Openfeign Querydsl 의 core 모듈 -->
        <groupId>io.github.openfeign.querydsl</groupId>
        <artifactId>querydsl-core</artifactId>
        <version>6.10.1</version>
</dependency>

 

<해결 방법 – 커스텀 변수로 버전 관리>

Maven에서는 <properties>에 새로운 변수 이름을 지정해 사용하는 방식으로 버전을 한 곳에서 관리합니다.

예를 들어, openfeign.querydsl.version이라는 새로운 변수를 만들고 여기에 버전 정보를 담아 사용합니다.

 

이렇게 하면 불필요하게 Spring Boot의 자동 라이브러리 구성을 건드리지 않고, 의존성 버전도 한 곳에서 관리할 수 있게 됩니다.

<properties>
        <java.version>17</java.version>
        <openfeign.querydsl.version>6.10.1</openfeign.querydsl.version>
</properties>

<dependency>
        <groupId>io.github.openfeign.querydsl</groupId>
        <artifactId>querydsl-jpa</artifactId>
        <version>${openfeign.querydsl.version}</version>
</dependency>
<dependency>
        <groupId>io.github.openfeign.querydsl</groupId>
        <artifactId>querydsl-apt</artifactId>
        <version>${openfeign.querydsl.version}</version>
</dependency>
<dependency>
        <groupId>io.github.openfeign.querydsl</groupId>
        <artifactId>querydsl-core</artifactId>
        <version>${openfeign.querydsl.version}</version>
 </dependency>

 

OpenFeign Querydsl의 모듈들의 역할

의존성을 선언할 때 우리가 추가했던 모듈들인 querydsl-jpa, querydsl-apt, querydsl-core 이 각각 어떤 역할을 하는지,
공식 메이븐 저장소(https://mvnrepository.com/artifact/io.github.openfeign.querydsl)에서 직접 확인합니다.

• 해당 저장소에 가보면 총 4개의 주요 모듈이 존재하는 것을 확인할 수 있습니다.

모듈명	역할 요약	설명
querydsl-core	핵심 API	모든 QueryDSL 기능의 기반이 되는 공통 로직이 담긴 모듈입니다. 컬렉션 기반 쿼리, 타입 안전 쿼리 DSL 등
querydsl-apt	코드 생성기	Q클래스(ex. QUser)를 생성하기 위한 APT(Annotation Processing Tool). 컴파일 시 엔티티를 분석해 소스코드 생성
querydsl-jpa	JPA용 확장	JPA 환경(Spring Data JPA 포함)에서 사용하는 모듈
querydsl-sql	SQL용 확장	MyBatis, JDBC 등 JPA가 아닌 순수 SQL 환경에서 QueryDSL을 사용할 때 필요한 모듈

 

저의 프로젝트는 JPA 기반이기 때문에, 필요한 모듈은 다음 두 가지입니다.

• querydsl-apt : Q클래스를 만들어주는 APT
• querydsl-jpa : JPA 환경에서 사용할 기능들

"그렇다면 핵심 기능인 querydsl-core는 왜 안 추가하나요?" 

IntelliJ에서 querydsl-jpa 의존성 선언 부분에 Ctrl + B로 들어가서 확인해보면, 이 모듈이 내부적으로 이미 querydsl-core를 포함하고 있는 것을 볼 수 있습니다.

즉, querydsl-jpa는 querydsl-core 기능을 확장해서 제공하는 구조이기 때문에, core를 별도로 추가할 필요가 없습니다.

 

그러니, core 모듈은 제거합니다.

<properties>
        <java.version>17</java.version>
        <openfeign.querydsl.version>6.10.1</openfeign.querydsl.version>
</properties>
<dependency>
        <groupId>io.github.openfeign.querydsl</groupId>
        <artifactId>querydsl-jpa</artifactId>
        <version>${openfeign.querydsl.version}</version>
</dependency>
<dependency>
        <groupId>io.github.openfeign.querydsl</groupId>
        <artifactId>querydsl-apt</artifactId>
        <version>${openfeign.querydsl.version}</version>
</dependency>

 

참고. com.querydsl 사용 시 jakarta 이슈

만약 OpenFeign이 아닌 기존 com.querydsl 프로젝트를 사용하는 경우에는 추가적으로 주의해야 할 점이 있습니다.

Spring Boot가 3.x로 올라오면서 javax → jakarta로 전환되었기 때문에, Querydsl 버전이 낮은 경우 사용할 경우 Q클래스가 생성되지 않는 문제가 발생할 수 있습니다. 이에 대한 공식 이슈는 여기서 확인할 수 있습니다.(https://github.com/querydsl/querydsl/issues/3371)

 

해당 이슈를 요약하자면 아래처럼, jakarta 를 사용한다고 명시적으로 선언을 해야 한다고 합니다.

<dependency>
    <groupId>com.querydsl</groupId>
    <artifactId>querydsl-apt</artifactId>
    <version>${querydsl.version}</version>
    <classifier>jakarta</classifier>
</dependency>

 

APT 모듈을 위한 Maven 플러그인 추가

querydsl-apt는 @Entity 어노테이션이 붙은 클래스를 분석해 Q클래스 (예: QUser)를 생성해주는 역할을 합니다.

그리고, 우리는 이 Qclass 를 이용해 Querydsl 쿼리를 작성하게 되기 때문에 Qclass 가 필요합니다.

Qclass 를 생성할 수 있게 APT 모듈을 컴파일 시점에 실행할 수 있도록 별도의 플러그인을 추가합니다.

 

플러그인을 추가하기 위해 OpenFeign Querydsl 의 README를 참고해도, 결국 com.querydsl 레퍼런스 로 연결되었습니다.

그래서 해당 문서를 참고해, 기존 Querydsl 프로젝트에서 사용하던 apt-maven-plugin 설정을 사용했습니다.

 

다만, 찾아보니 이 방법은 구식으로 최근 Maven에서는 apt-maven-plugin을 사용하지 않고, maven-compiler-plugin의 <annotationProcessorPaths> 태그를 사용함을 알게 되었습니다. 다만, 기존 방법으로도 Qclass 를 생성할 수 있기 때문에  maven-compiler-plugin 설명은 나중에 해당 문법을 사용할 때, 정리해보려 합니다. 

 

결론은 아래처럼 플러그인을 pom.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>

 

결론

1. Querydsl ≠ OpenFeign Querydsl
이 둘은 전혀 다른 프로젝트이며, 의존성 그룹과 버전도 다릅니다.

Querydsl 의 의존성은 com.querydsl , OpenFeign Querydsl 의존성은 io.github.openfeign.querydsl 입니다.

 

2. Spring Boot는 기본 Querydsl만 관리
OpenFeign Querydsl을 사용할 경우, pom.xml에서 버전을 명시적으로 선언해야 합니다.

 

3. JPA 환경에서는 querydsl-jpa와 querydsl-apt만 있으면 충분
이 두 모듈이 내부적으로 querydsl-core를 포함하므로 별도 추가는 불필요합니다

 

4. Qclass 생성을 위해 APT 플러그인이 필요
apt-maven-plugin 또는 maven-compiler-plugin 중 하나로 설정해줘야 합니다.

 

다음은 Maven에서 OpenFeign Querydsl 을 사용하기 위한 전체 pom.xml 설정입니다.

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">

    <modelVersion>4.0.0</modelVersion>

    <!-- Spring Boot 공식 parent 설정 -->
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.4.4</version>
        <relativePath/>
    </parent>
	
    ...

    <properties>
        <java.version>17</java.version> <!-- Java 버전 -->
        <openfeign.querydsl.version>6.10.1</openfeign.querydsl.version> <!-- Openfeign Querydsl 버전 -->
    </properties>

    <dependencies>
        <!-- Spring Data JPA (Hibernate + ORM 연동) -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-jpa</artifactId>
        </dependency>

        <!-- QueryDSL (JPA 쿼리 DSL) -->
        <!-- https://mvnrepository.com/artifact/io.github.openfeign.querydsl/querydsl-jpa -->
        <dependency>
            <groupId>io.github.openfeign.querydsl</groupId>
            <artifactId>querydsl-jpa</artifactId>
            <version>${openfeign.querydsl.version}</version>
        </dependency>
        <dependency>
            <groupId>io.github.openfeign.querydsl</groupId>
            <artifactId>querydsl-apt</artifactId>
            <version>${openfeign.querydsl.version}</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            ...
            <plugin> <!-- Maven 컴파일 때, Qclass 생성 -->
                <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>
        </plugins>
    </build>

</project>

 

마치며

저는 이번 글을 통해 다음과 같은 점을 얻었는데, 여러분도 함께 얻어가셨기를 바랍니다.

• Spring Boot가 어떤 라이브러리 버전을 자동으로 관리하는지 찾아가기
• Spring Boot가 관리하지 않는 외부 라이브러리의 버전을 어떻게 찾아야 하는지