Quarkus 4.0 미리보기 — Java 21 기준선부터 Jackson 3·Hibernate 8까지

이번 포스팅에서는 2026년 10월 1일 공개된 Quarkus 4.0.0.Beta1을 미리 살펴보고자 한다. 메이저 버전이 올라가는 만큼 바뀌는 게 많은데, Java 기준선이 21로 오르고 Jackson이 3으로, Hibernate ORM이 8로 넘어가면서 임포트와 설정을 손봐야 하는 지점이 적지 않다. 아직 베타라 프로덕션에 바로 올릴 단계는 아니지만, 정식 출시가 11월 말로 예정돼 있어 지금 변경점을 익혀 두면 마이그레이션이 한결 수월하다. 여기서는 공식 발표와 마이그레이션 가이드를 근거로, 무엇이 왜 바뀌었고 코드에서 어디를 고쳐야 하는지 정리한다.

Quarkus 4.0, 지금 무슨 일이 벌어지나

Quarkus 4.0은 2026년 10월 1일 Beta1이 공개됐고, 정식 출시는 11월 말로 예정돼 있다. 메이저 버전인 만큼 플랫폼 전반이 한 단계씩 올라간 게 핵심이다. Java 기준선이 21로, Jackson이 3으로, Hibernate ORM이 8로, Vert.x가 5로 넘어갔다. 지금은 베타라 테스트 환경에서 변경점을 점검하는 단계이고, 프로덕션 이행은 정식 출시 이후가 안전하다.

공식 발표(Quarkus 4.0.0.Beta1 릴리스)는 이번 버전을 “가상 스레드를 더 중심에 둔” 릴리스로 소개한다. 눈에 띄는 변화는 크게 세 갈래다. 첫째는 런타임 기반을 올린 것(Java 21, Vert.x 5.x, Netty 4.2), 둘째는 핵심 라이브러리의 메이저 교체(Jackson 3, Hibernate ORM 8, Jakarta REST 4, CDI 5.0), 셋째는 조용히 동작이 바뀌는 breaking change(gRPC 통합, 설정 키 정리, 기본값 변경)다. Quarkus 자체가 생소하다면 Spring Boot vs Quarkus 2026 비교를 먼저 보고 오면 이 변화의 맥락이 잡힌다.

공식 마이그레이션 가이드도 “평소 마이너 업그레이드보다 내용이 빽빽하다”고 미리 경고할 만큼 바뀐 폭이 크다. 그래서 이 글은 “무엇이 바뀌었나”를 훑는 데서 끝내지 않고, 실제로 코드에서 손봐야 하는 Jackson·Hibernate·설정을 중심으로 짚는다.

Java 17은 끝 — Quarkus 4.0의 새 기준선은 Java 21

Quarkus 4.0부터 Java 21이 최소 버전이고, Java 17은 더 이상 지원되지 않는다. 권장 버전은 Java 25다. 즉 Java 17에 머물러 있는 프로젝트는 Quarkus 4.0으로 올리기 전에 런타임부터 21 이상으로 올려야 한다. 이 기준선 상승이 이번 메이저의 출발점이고, 가상 스레드를 더 적극적으로 활용하려는 방향과 맞닿아 있다.

마이그레이션 가이드는 이 부분을 분명히 한다. “Quarkus 4부터 Java 21이 최소 버전이며, Java 25를 권장하고, Java 17은 더 이상 지원하지 않는다”(Migration Guide 4.0). Java 17 LTS를 쓰던 서비스라면 JDK 교체가 선행 과제이므로, 4.0 이행 계획의 첫 줄에 “JDK 21+ 전환”을 적어 두면 된다. 다행히 21과 25 모두 LTS라 장기 운영에는 부담이 적다.

Jackson이 tools.jackson으로 — 임포트부터 바꿔야 한다

Quarkus 4.0 업그레이드에서 코드를 가장 많이 건드리게 되는 건 Jackson 3다. 핵심은 패키지 이름이 com.fasterxml.jackson에서 tools.jackson으로 바뀌었다는 점이다(Migration Guide 4.0). 애너테이션(com.fasterxml.jackson.annotation)은 그대로지만, ObjectMapper·JsonNode 같은 핵심 클래스의 임포트는 전부 새 패키지로 고쳐야 한다. 공식 발표도 Jackson 3를 두고 “애너테이션만 빼고 전부 바뀐 새 메이저”라고 표현했다.

바뀌는 임포트를 구체적으로 보면 이렇다.

// Quarkus 3.x (Jackson 2)
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.core.JsonParser;

// Quarkus 4.0 (Jackson 3)
import tools.jackson.databind.ObjectMapper;
import tools.jackson.databind.JsonNode;
import tools.jackson.core.JsonParser;

// Quarkus 3.x (Jackson 2)
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.core.JsonParser;

// Quarkus 4.0 (Jackson 3)
import tools.jackson.databind.ObjectMapper;
import tools.jackson.databind.JsonNode;
import tools.jackson.core.JsonParser;

위에서 보듯 ObjectMapper·JsonNode·JsonSerializer·JsonDeserializer는 tools.jackson.databind로, JsonParser·JsonGenerator는 tools.jackson.core로 임포트 경로가 바뀐다. 반면 @JsonProperty 같은 애너테이션은 com.fasterxml.jackson.annotation 그대로라 수정할 필요가 없다. 패키지만 바뀌고 이름은 같아서, 상당 부분은 임포트 치환으로 해결된다.

CDI 쪽에는 한 가지 더 신경 쓸 변화가 있다. Quarkus 4.0은 이제 ObjectMapper 대신 JsonMapper 빈을 생성한다. JsonMapper가 ObjectMapper를 상속하므로 @Inject ObjectMapper 주입은 그대로 동작하지만, 컨테이너에서 정확히 ObjectMapper 타입으로 프로그래밍적 조회(CDI.current().select(ObjectMapper.class))를 하던 코드는 깨질 수 있다. 커스터마이저 API도 이름이 바뀌었다.

// Quarkus 3.x
// ObjectMapperCustomizer가 가변 ObjectMapper를 받아 설정
// Quarkus 4.0
import tools.jackson.databind.json.JsonMapper;

public class MyCustomizer implements JsonMapperBuilderCustomizer {
    @Override
    public void customize(JsonMapper.Builder builder) {
        // 3.x에서 mutable ObjectMapper를 수정하던 로직을
        // 4.0에서는 빌더에 설정하는 방식으로 옮긴다
    }
}

// Quarkus 3.x
// ObjectMapperCustomizer가 가변 ObjectMapper를 받아 설정
// Quarkus 4.0
import tools.jackson.databind.json.JsonMapper;

public class MyCustomizer implements JsonMapperBuilderCustomizer {
    @Override
    public void customize(JsonMapper.Builder builder) {
        // 3.x에서 mutable ObjectMapper를 수정하던 로직을
        // 4.0에서는 빌더에 설정하는 방식으로 옮긴다
    }
}

ObjectMapperCustomizer가 JsonMapperBuilderCustomizer로 바뀌었고, 가변 ObjectMapper를 직접 고치던 방식에서 JsonMapper.Builder에 설정을 쌓는 방식으로 달라졌다. JSON 직렬화를 커스터마이즈하던 코드가 있다면 이 인터페이스 교체가 필요하다. API 에러 응답 표준화처럼 직렬화에 손대는 작업을 해 뒀다면(Quarkus RFC 9457 Problem Details 같은 설정) 이 지점을 함께 점검하는 게 좋다.

Hibernate ORM 8과 Jakarta Persistence 4.0 — 사라진 API들

Quarkus 4.0은 Hibernate ORM 8을 품으면서 Jakarta Persistence 4.0과 Jakarta Data 1.1을 함께 들여왔다. 이 과정에서 오래된 API 몇 개가 제거됐으므로, 엔티티·쿼리 코드가 그 API를 쓰고 있다면 대체재로 옮겨야 한다. 메이저 ORM 교체라 동작이 미묘하게 달라지는 부분도 있다.

제거되거나 바뀐 대표적인 항목은 다음과 같다. Session.replicate()와 ReplicationMode가 사라졌고, 대신 StatelessSession.upsert()를 쓴다. StatelessSession.insert()는 더 이상 식별자를 반환하지 않는다. 쿼리 API가 조회(selection)와 변경(mutation) 구문을 구분하게 되어, 변경 구문은 @NamedStatement·@NamedNativeStatement로 선언해야 한다. 힌트 클래스도 바뀌어 org.hibernate.jpa.QueryHints가 제거되고 HibernateHints·SpecHints로 대체됐으며, @GenericGenerator 문법이 달라지고 org.hibernate.transform 패키지가 통째로 빠졌다(Migration Guide 4.0).

동작이 조용히 달라지는 지점도 챙겨야 한다. 이제 java.time 값이 JDBC로 그대로 전달되어 타임존 처리가 달라질 수 있고, 없는 엔티티를 조회할 때 null 대신 EntityNotFoundException이 던져진다. 그래프 기반 flush는 SQL 실행 순서를 바꿀 수 있다. 이런 변화는 컴파일 에러로 드러나지 않고 런타임 동작으로 나타나므로, 통합 테스트로 확인하는 편이 안전하다.

플랫폼이 통째로 올라갔다 — Vert.x 5·CDI 5·Jakarta REST 4

개별 라이브러리뿐 아니라 Quarkus를 떠받치는 기반도 한 단계씩 올라갔다. 네트워킹은 Vert.x 5.x와 Netty 4.2로, REST는 Jakarta REST 4로, 의존성 주입은 CDI 5.0으로 넘어갔다. 대부분은 프레임워크가 알아서 흡수하지만, 새로 생긴 기능과 기본값 변화는 알아 둘 만하다.

눈에 띄는 추가는 CDI 5.0의 새 애너테이션 @Reserve(기존 @io.quarkus.arc.DefaultBean을 대체)와 @Eager다. @Eager는 지연 생성이 기본인 빈을 애플리케이션 시작 시점에 미리 만들도록 하는 식으로 쓰인다. Jakarta REST 4에는 JSON Merge Patch 지원과 새로운 멀티파트 API가 들어왔다. 공식 발표는 이 밖에도 Observation API, QUIC, HTTP/3, 네이티브 트랜스포트, JMS 익스텐션을 함께 강조했다. 4.0은 특정 기능 하나를 위한 릴리스가 아니라, 표준과 런타임을 한꺼번에 최신으로 끌어올린 “기반 교체” 성격의 메이저인 셈이다.

관측·메시징 쪽 편의 기능도 눈여겨볼 만하다. 새 Observation API는 @Observed 애너테이션으로 메서드를 관측 지점으로 만들고, Dev UI에는 Observability 대시보드가 들어왔다. Kafka에는 트랜잭션을 정확히 한 번 처리하도록 돕는 @ExactlyOnce가 추가됐다. 또 네이티브 트랜스포트는 epoll·io_uring을 활용해 동시성을 끌어올리는데, 네이티브 실행 파일에서도 동작한다.

조용히 깨지는 것들 — gRPC·설정·기본값 변화

메이저 업그레이드에서 가장 조심해야 할 건 컴파일 에러 없이 동작만 바뀌는 breaking change다. Quarkus 4.0에는 gRPC 서버 통합, 설정 키 정리, 여러 기본값 변경이 포함돼 있어, 겉보기엔 멀쩡히 뜨는데 통신이나 관측 동작이 달라질 수 있다. 하나씩 짚어 둔다.

가장 큰 건 gRPC다. 별도 gRPC 서버가 사라지고 서비스가 메인 HTTP 서버에서 함께 돈다. 그래서 기본 포트가 9000에서 HTTP 포트로 바뀌고, quarkus.grpc.server.ssl.* 설정이 quarkus.http.ssl.*로 옮겨 갔다. gRPC를 쓰고 있다면 포트·TLS 설정을 반드시 다시 확인해야 한다. 그 밖의 변화는 다음과 같다(Migration Guide 4.0).

• 쿼리 파라미터 구분자: 세미콜론(;)이 더 이상 기본 구분자가 아니고, 앰퍼샌드(&)만 파라미터를 나눈다.
• OpenTelemetry OTLP 기본값: 프로토콜이 grpc(포트 4317)에서 http/protobuf(포트 4318)로 바뀌었다.
• 트레이스 샘플링: 기본값이 100%(parentbased_always_on)에서 10%(parentbased_traceidratio)로 낮아졌다.
• 설정 키 정리: quarkus.log.console.enable→quarkus.log.console.enabled, quarkus.debug.dump-build-metrics→quarkus.builder.metrics.enabled 등 다수가 바뀌었다(대부분 quarkus update가 자동 처리).
• 아티팩트 이름 변경: quarkus-junit5→quarkus-junit, quarkus-webjars-locator→quarkus-web-dependency-locator.

이 중 샘플링 기본값 변화는 특히 놓치기 쉽다. 운영 기준 기본값이 100%에서 10%로 낮아졌는데(dev 모드는 100% 유지), 업그레이드 후 프로덕션 트레이스가 10분의 1만 수집되는 걸 보고 당황하지 않으려면 관측이 중요한 서비스는 샘플링 비율을 명시적으로 설정해 두는 게 좋다.

지금 올려도 되나 — quarkus update와 이행 전략

결론부터 말하면, 지금은 베타라 테스트 환경에서만 올려 보는 게 맞고 프로덕션 이행은 11월 말 정식 출시 이후가 안전하다. 마이그레이션은 손으로 하나씩 고치기보다 공식 도구인 quarkus update를 쓰는 게 권장된다. 설정 키 변경이나 아티팩트 이름 변경처럼 기계적으로 바꿀 수 있는 부분은 이 명령이 자동으로 처리해 준다.

# 프로젝트 루트에서 실행 — 새 버전으로 업데이트
quarkus update

# 프로젝트 루트에서 실행 — 새 버전으로 업데이트
quarkus update

기존 프로젝트가 아니라 그냥 4.0을 한번 띄워 보고 싶다면, 플랫폼 버전만 베타로 고정하면 된다. Maven이라면 pom.xml의 버전 속성을 바꾼다.

<properties>
    <quarkus.platform.version>4.0.0.Beta1</quarkus.platform.version>
</properties>

<properties>
    <quarkus.platform.version>4.0.0.Beta1</quarkus.platform.version>
</properties>

quarkus.platform.version을 4.0.0.Beta1로 지정하면 Quarkus BOM(io.quarkus.platform:quarkus-bom)이 그 버전으로 맞춰진다. 기존 프로젝트를 올릴 때는 이 값을 손으로 바꾸기보다 quarkus update에 맡기는 편이 설정·의존성 정리까지 함께 돼 편하다.

공식 가이드는 “새 Quarkus 버전으로 올릴 때는 quarkus update 사용을 강력히 권한다”고 안내한다(Migration Guide 4.0). 다만 quarkus update가 설정·의존성 정리는 해 주지만, Jackson 임포트 변경이나 Hibernate API 교체처럼 코드 로직이 얽힌 부분까지 전부 자동으로 고쳐 주지는 않는다. 그래서 실무 이행 순서는 이렇게 잡는 게 안전하다. 먼저 JDK를 21 이상으로 올리고, 테스트 브랜치에서 quarkus update를 돌린 뒤, 남은 컴파일 에러(주로 Jackson·Hibernate)를 수동으로 정리하고, 마지막으로 통합 테스트로 런타임 동작 변화(타임존·샘플링·gRPC 포트)를 확인한다. 베타 단계인 지금은 이 과정을 미리 리허설해 두는 시간으로 쓰면 된다.

3.x에서 4.0으로 — 한눈에 보는 변경 요약

Quarkus 4.0은 Java 기준선(17→21), JSON(Jackson 2→3, com.fasterxml→tools.jackson), ORM(Hibernate 7→8), gRPC(별도 서버→메인 HTTP 통합) 네 축이 한꺼번에 바뀐다. 런타임 기준선·핵심 라이브러리·통신/관측 기본값이 각각 어떻게 달라졌는지 표로 보면 이렇다.

표에서 보듯 4.0은 한두 기능이 아니라 기반 전체가 올라간 메이저다. 그만큼 올리는 품은 들지만, Java 21 기준선과 최신 표준 위에서 가상 스레드·HTTP/3 같은 흐름을 더 자연스럽게 탈 수 있다는 게 이번 버전의 값어치다. LTS 운영을 고려한다면 Spring Boot vs Quarkus 2026 비교 글에서 양쪽 LTS·버전 정책을 함께 보고 이행 시점을 잡는 것도 방법이다.

FAQ

마치며

예전에 Quarkus 2에서 3으로 올릴 때 Jakarta 네임스페이스 전환(javax→jakarta)에 한참 애를 먹은 기억이 있다. 그때도 “임포트만 바꾸면 되겠지” 하고 가볍게 봤다가, 직렬화와 영속성 쪽에서 런타임 동작이 미묘하게 달라져 테스트로 한참 잡아냈다. 이번 4.0은 그때보다 폭이 더 넓어 보인다. Java 기준선·Jackson·Hibernate가 동시에 올라가니, 컴파일 에러로 드러나는 부분보다 조용히 바뀌는 동작(타임존, 샘플링, gRPC 포트)이 더 성가실 것 같다.

그래도 베타가 지금 나온 건 반갑다. 정식 출시까지 한 달 넘게 여유가 있으니, 테스트 브랜치에서 quarkus update를 돌려 보고 어디가 깨지는지 미리 겪어 두면 11월 말 이행이 훨씬 수월해진다. 개인적으로는 샘플링 기본값이 10%로 바뀐 걸 제일 먼저 메모해 뒀다. 관측 대시보드가 갑자기 비어 보이면 당황하기 딱 좋은 변화라서다. 지금까지 Quarkus 4.0의 주요 변경점을 미리 정리해 보았다.