Skip to content
javahacks.dev
Quarkus

Quarkus for Spring Developers and What Changes in Practice

Map what you know from Spring Boot to Quarkus 3, from CDI and RESTEasy to dev mode and native images, and see where the models really differ.

14 min read
Summarize in AI
Flat illustration of startup time of a JVM compared with a native image, with the Quarkus, Spring, Spring Boot and Kubernetes logos.

If you know Spring Boot, you already know about three quarters of Quarkus; the Quarkus guides cover the rest. The annotations are different, the ideas are the same, and the real divide is when the work happens. This guide maps the Spring concepts you use to their Quarkus 3 equivalents on JDK 25, then spends its time on the differences that cause trouble. It builds on Spring Boot from first project to production and how the Spring container works, so those make good side-by-side reading.

For a first project from scratch, the Quarkus tutorial for beginners goes step by step. This page is for people who want the comparison.

The same ideas under different names

You use in Spring BootYou use in Quarkus
@Component, @Service, @Autowired@ApplicationScoped, @Inject (CDI)
@RestController, @GetMapping@Path, @GET (JAX-RS, Quarkus REST)
Spring Data JPA repositoryPanache repository or active record
@ConfigurationProperties@ConfigMapping
ActuatorSmallRye Health and Micrometer extensions
Spring Boot DevTools restartDev mode (quarkus dev)
@SpringBootTest@QuarkusTest
Testcontainers wiringDev Services

A resource looks familiar:

src/main/java/dev/javahacks/hello/GreetingResource.javajava
@Path("/hello")
public class GreetingResource {

    @Inject
    GreetingService service;

    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String hello(@QueryParam("name") @DefaultValue("world") String name) {
        return service.greet(name);
    }
}

Injection is by type with @Inject, and CDI scopes replace Spring's. @ApplicationScoped is the singleton-like default for services, and it is proxied, so the same self-invocation caveat applies as in Spring. If two beans match a type, the error is the CDI one, covered in Quarkus unsatisfied dependency and ambiguous beans.

Build time is the difference

Spring reads annotations, creates proxies and wires beans when the application starts. Quarkus does that work while building, and the running application contains the result. This is why startup is quick and memory is low, and why Quarkus build time processing is the post to read when something behaves oddly. The consequences:

  • Properties marked "fixed at build time" cannot change at runtime. Setting them with an environment variable on a deployed jar has no effect. The configuration reference marks each one.
  • Anything discovered by reflection at runtime must be known to the build. Extensions register their own classes; your own classes used reflectively need @RegisterForReflection.
  • Classpath scanning at runtime does not exist, so libraries that rely on it need an extension or do not work.

Dev mode replaces the restart loop

Shell
./mvnw quarkus:dev

Dev mode watches your sources, recompiles on the next request and keeps a continuous test runner you toggle with r. See Quarkus dev mode and continuous testing. Dev Services start containers for databases and brokers when no URL is configured, which is what Testcontainers does for Spring tests, built in. The details are in Quarkus Dev Services.

Configuration and profiles

application.properties works the way you expect, with profile prefixes written as %dev., %test. and %prod.:

src/main/resources/application.propertiesproperties
quarkus.datasource.db-kind=postgresql
%prod.quarkus.datasource.jdbc.url=jdbc:postgresql://db:5432/shop
%dev.quarkus.hibernate-orm.database.generation=drop-and-create

An environment variable QUARKUS_DATASOURCE_JDBC_URL overrides the property at runtime, as long as the property is not build-time fixed.

Native images

A native build compiles your application ahead of time with GraalVM or Mandrel (native image guide):

Shell
./mvnw package -Dnative

The result starts in milliseconds and has a small resident set, and the build takes minutes and a lot of memory. Everything reflective must be declared, so the typical failure is a class that exists in the jar and is missing from the image; Quarkus native build failures with reflection shows the fix. Use native for scale-to-zero functions and command-line tools. A long-running service that uses the JIT well often does not need it.

Measure before you move

The speed argument for Quarkus is true, and it is also the argument most teams do not need. A service that starts once a week and runs for days gets little from a faster start. The memory argument matters more for density: more instances per node. Measure your own service's startup time and resident memory on both frameworks before you commit, because the gap depends on how many libraries you load. What Quarkus is and why it starts fast explains the mechanics.

The data layer: Spring Data against Panache

Most of the code a Spring developer writes touches a repository, so this is where the mapping pays off first. A Spring Data repository is an interface the framework implements:

java
public interface OrderRepository extends JpaRepository<Order, Long> {
    List<Order> findByStatusOrderByCreatedAtDesc(OrderStatus status);

    @Query("select o from Order o where o.total > :min")
    List<Order> bigOrders(@Param("min") BigDecimal min);
}

The Quarkus equivalent is Hibernate ORM with Panache, and it offers two styles. The repository style is the closest to what you know:

java
@ApplicationScoped
public class OrderRepository implements PanacheRepository<Order> {

    public List<Order> byStatus(OrderStatus status) {
        return list("status = ?1 order by createdAt desc", status);
    }

    public List<Order> bigOrders(BigDecimal min) {
        return list("total > :min", Parameters.with("min", min));
    }
}

The active record style puts the queries on the entity itself, which is shorter and reads like Rails, and some teams dislike it for exactly that reason:

java
@Entity
public class Order extends PanacheEntity {

    public OrderStatus status;
    public BigDecimal total;
    public Instant createdAt;

    public static List<Order> byStatus(OrderStatus status) {
        return list("status = ?1 order by createdAt desc", status);
    }
}

Two differences matter in practice. Panache does not generate queries from method names, so findByStatusOrderByCreatedAtDesc has no equivalent and you write the short query yourself, which is more typing and also more explicit. And the entity in the active record style has public fields, which Quarkus rewrites to accessors at build time. If you want Spring's derived queries, the quarkus-spring-data-jpa compatibility extension supports a subset of them, and it is a good bridge while migrating, not a place to stay.

Transactions use the Jakarta annotation, and the rule you know still applies: the boundary is the proxy, so a call from one method to another in the same bean does not start one.

java
@ApplicationScoped
public class OrderService {

    @Inject OrderRepository orders;

    @Transactional
    public Order place(NewOrder request) {
        Order order = new Order();
        order.status = OrderStatus.PLACED;
        order.total = request.total();
        order.createdAt = Instant.now();
        orders.persist(order);
        return order;
    }
}

Use jakarta.transaction.Transactional here, not Spring's, and prefer @Transactional(Transactional.TxType.SUPPORTS) or no annotation on read paths. There is no readOnly flag, so the cheap way to avoid dirty checking on a read-heavy query is to select into a DTO with project(OrderSummary.class).

Configuration: from @ConfigurationProperties to @ConfigMapping

A typed configuration group in Spring:

java
@ConfigurationProperties(prefix = "shop")
public record ShopProperties(String currency, Duration cacheTtl, Pricing pricing) {
    public record Pricing(BigDecimal taxRate) {}
}

In Quarkus it is an interface, with defaults on the methods:

java
@ConfigMapping(prefix = "shop")
public interface ShopConfig {

    @WithDefault("EUR")
    String currency();

    @WithName("cache-ttl")
    @WithDefault("5m")
    Duration cacheTtl();

    Pricing pricing();

    interface Pricing {
        @WithDefault("0.20")
        BigDecimal taxRate();
    }
}
properties
shop.currency=USD
shop.pricing.tax-rate=0.08

Inject it like any bean with @Inject ShopConfig config. For a single value, @ConfigProperty(name = "shop.currency", defaultValue = "EUR") String currency is the @Value equivalent. The part that surprises Spring developers is validation at startup: a mapping with a missing required value fails the application at boot with a message naming the property, which is the behavior you wanted from @Validated configuration, free of charge.

Calling other services: RestClient against the REST Client

Spring's RestClient is imperative and built in code. Quarkus uses a declarative interface, in the style of Feign or Spring's HTTP interface clients:

java
@RegisterRestClient(configKey = "pricing")
@Path("/prices")
public interface PricingClient {

    @GET
    @Path("/{sku}")
    @Produces(MediaType.APPLICATION_JSON)
    Price priceOf(@PathParam("sku") String sku);
}
properties
quarkus.rest-client.pricing.url=http://pricing:8080
quarkus.rest-client.pricing.connect-timeout=300
quarkus.rest-client.pricing.read-timeout=1000

Inject it with @Inject @RestClient PricingClient pricing. Resilience comes from the SmallRye Fault Tolerance extension, which implements the MicroProfile annotations and replaces Resilience4j in most Spring services:

java
@ApplicationScoped
public class CatalogService {

    @Inject @RestClient PricingClient pricing;

    @Retry(maxRetries = 2, delay = 200, jitter = 100)
    @Timeout(1500)
    @CircuitBreaker(requestVolumeThreshold = 20, failureRatio = 0.5, delay = 10_000)
    @Fallback(fallbackMethod = "unknownPrice")
    public Price price(String sku) {
        return pricing.priceOf(sku);
    }

    Price unknownPrice(String sku) {
        return Price.unknown(sku);
    }
}

The same advice holds as anywhere: retry only reads, and make the fallback honest.

Error handling: @ControllerAdvice becomes an exception mapper

A Spring Boot @RestControllerAdvice has two Quarkus counterparts. For a handful of exceptions, annotate a method in any class with @ServerExceptionMapper:

java
public class ApiErrors {

    @ServerExceptionMapper
    public RestResponse<ProblemBody> notFound(OrderNotFound e) {
        return RestResponse.status(Response.Status.NOT_FOUND,
            new ProblemBody("order-not-found", e.getMessage()));
    }

    @ServerExceptionMapper
    public RestResponse<ProblemBody> invalid(ConstraintViolationException e) {
        return RestResponse.status(Response.Status.BAD_REQUEST,
            new ProblemBody("validation-failed", e.getMessage()));
    }
}

The portable form is a class that implements ExceptionMapper<T> and carries @Provider, which works in any JAX-RS runtime. Bean Validation is the same Hibernate Validator you know, so @Valid on a parameter and constraints on a record behave identically, and a violation reaches the mapper as the exception above.

Security in one table

Spring SecurityQuarkus
SecurityFilterChain with authorizeHttpRequestsquarkus.http.auth.permission.* properties, or annotations
@PreAuthorize("hasRole('ADMIN')")@RolesAllowed("ADMIN")
oauth2ResourceServer().jwt()quarkus-smallrye-jwt or quarkus-oidc
Keycloak adapter or OAuth2 clientquarkus-oidc with Dev Services for Keycloak
properties
quarkus.http.auth.permission.admin.paths=/admin/*
quarkus.http.auth.permission.admin.policy=authenticated
mp.jwt.verify.publickey.location=publicKey.pem
mp.jwt.verify.issuer=https://auth.example.com
java
@Path("/orders")
@RolesAllowed("customer")
public class OrderResource {

    @Inject JsonWebToken jwt;

    @GET
    public List<OrderView> mine() {
        return service.forCustomer(jwt.getSubject());
    }
}

Quarkus secures by path or by annotation, and denies by default only if you set a deny policy, so state it explicitly with quarkus.security.jaxrs.deny-unannotated-endpoints=true for an API where every endpoint should carry a role.

Scheduling, startup and events

The small framework features have direct mappings, and they are where a migrating team trips over a missing dependency, not over a concept:

java
@ApplicationScoped
public class Jobs {

    @Scheduled(every = "10m", concurrentExecution = Scheduled.ConcurrentExecution.SKIP)
    void refreshPrices() {
        // like @Scheduled(fixedRate = ...) in Spring
    }

    void onStart(@Observes StartupEvent event) {
        // like an ApplicationRunner or @EventListener(ApplicationReadyEvent.class)
    }

    void onOrderPlaced(@Observes OrderPlaced event) {
        // like @EventListener, with CDI events fired from Event<OrderPlaced>.fire(...)
    }
}

Add the quarkus-scheduler extension for @Scheduled, since nothing is on the classpath you did not ask for, which is the same build-time principle in another form. Producer methods with @Produces replace @Bean methods, qualifiers replace @Qualifier, and @IfBuildProfile("dev") or @LookupIfProperty replace @Profile and @ConditionalOnProperty. The profile conditions are decided at build time, which is the one place the model really differs: a bean excluded for prod is not present in the artifact at all.

Testing: @QuarkusTest and Dev Services

A Spring Boot web test and its Quarkus counterpart look alike, with RestAssured as the usual client:

java
@QuarkusTest
class OrderResourceTest {

    @InjectMock
    PricingClient pricing;

    @Test
    void createsAnOrder() {
        Mockito.when(pricing.priceOf("sku-1")).thenReturn(new Price("sku-1", new BigDecimal("19.90")));

        given()
            .contentType(ContentType.JSON)
            .body("""
                {"sku":"sku-1","quantity":2}""")
        .when()
            .post("/orders")
        .then()
            .statusCode(201)
            .header("Location", containsString("/orders/"))
            .body("total", is(39.80f));
    }
}

@InjectMock replaces @MockitoBean, and the database comes from Dev Services without a line of container code when no JDBC URL is set for the test profile. @QuarkusIntegrationTest runs the same tests against the packaged artifact or the native binary, which is how you catch a reflection gap before production. A @QuarkusTest application starts once and is shared across test classes with the same profile, like the Spring context cache, and @TestProfile creates a separate one when a test needs different configuration.

Containers and operations

A JVM-mode image follows the same layered idea as a Spring Boot image. Quarkus generates Dockerfiles under src/main/docker:

Dockerfile
FROM registry.access.redhat.com/ubi9/openjdk-21-runtime:latest
COPY --chown=185 target/quarkus-app/lib/ /deployments/lib/
COPY --chown=185 target/quarkus-app/*.jar /deployments/
COPY --chown=185 target/quarkus-app/app/ /deployments/app/
COPY --chown=185 target/quarkus-app/quarkus/ /deployments/quarkus/
USER 185
ENTRYPOINT ["java", "-jar", "/deployments/quarkus-run.jar"]

Use the Dockerfile that quarkus create generated for the Java version you target, and check which base image matches your JDK, since the tag above is an illustration. The quarkus-smallrye-health extension gives /q/health/live and /q/health/ready, and the Micrometer extension serves /q/metrics, so Kubernetes probes and Prometheus scrapes need only the new paths. Management endpoints sit under /q by default, which is worth remembering when a Spring-trained eye looks for /actuator.

A migration order that works

Teams that move a service rather than start fresh succeed with a sequence like this:

  1. Create the Quarkus project with the extensions that match the Spring starters (REST, Hibernate ORM with Panache, the same JDBC driver, Validator, OIDC or JWT).
  2. Move the domain and the pure logic over unchanged. Plain classes need no change at all.
  3. Rewrite the edges: resources for controllers, repositories for Spring Data, @ConfigMapping for properties.
  4. Port the tests, and run them in dev mode with continuous testing on.
  5. Build the native image only if you need it, and run the integration tests against it in CI.
  6. Compare startup time, resident memory and throughput with the original under the same load before you decide the move was worth it.

For services with heavy Spring dependencies, the quarkus-spring-di, quarkus-spring-web and quarkus-spring-data-jpa extensions let you keep many annotations while you migrate, and they are best treated as scaffolding that you remove once the service is stable, since the idiomatic Quarkus forms are what the documentation and the community use.

Mistakes Spring developers make in the first month

MistakeWhat happensFix
Changing a build-time property through an environment variableNo effect on the deployed jarRebuild, or check the configuration reference for the property's phase
Assuming a bean is created by component scanningBean missing, or a build error about an unsatisfied dependencyAdd a bean-defining annotation such as @ApplicationScoped
Using reflection on your own classes in a native imageWorks on the JVM, fails natively@RegisterReflectionForBinding or @RegisterForReflection
Expecting readOnly transactionsNo such attributeProject into DTOs for reads
Reaching for @Autowired on a private fieldCompiles with the compatibility extension, surprises in reviewUse @Inject and package-private fields or constructors
Looking for /actuator/health404Use /q/health

Threads: the event loop is the new thing to learn

Spring MVC gives every request a thread from a pool, and blocking is normal. Quarkus REST runs on an event loop by default for methods that return a reactive type, and on a worker thread for methods that return plain objects. The rule that follows is simple and easy to break: never block an I/O thread. A resource that returns Uni<Order> and calls a blocking JDBC method inside it will freeze the event loop, and the log says so:

Text
WARN  [io.qua.ver.cor.run.VertxCoreRecorder] Thread Thread[vert.x-eventloop-thread-1,5,main] has been blocked for 2610 ms

For a Spring developer arriving from Spring MVC, the least surprising approach is to write blocking code in plain methods that return objects, and let Quarkus run them on worker threads. If you want the thread-per-request simplicity with the scalability of virtual threads, annotate the endpoint:

java
@Path("/orders")
public class OrderResource {

    @Inject OrderService orders;

    @GET
    @Path("/{id}")
    @RunOnVirtualThread
    public OrderView get(@PathParam("id") long id) {
        return orders.view(id);        // blocking JDBC is fine here
    }
}

@RunOnVirtualThread needs a JDK with virtual threads, which every current LTS release has, and it is the closest equivalent to setting spring.threads.virtual.enabled=true in Spring Boot. The caveat is the same on both sides: a synchronized block that holds a monitor across blocking I/O can pin a carrier thread in older JDK releases, so check your libraries before you switch a busy service.

Caching and OpenAPI, the two extensions you will add first

Spring's @Cacheable becomes @CacheResult from the quarkus-cache extension. The shape is identical, and the cache itself is configured by name:

java
@ApplicationScoped
public class PriceService {

    @CacheResult(cacheName = "prices")
    public Price priceOf(@CacheKey String sku) {
        return pricing.priceOf(sku);
    }

    @CacheInvalidate(cacheName = "prices")
    public void priceChanged(@CacheKey String sku) {
    }
}
properties
quarkus.cache.caffeine."prices".expire-after-write=10M
quarkus.cache.caffeine."prices".maximum-size=5000

The self-invocation rule applies, since these are interceptors on a proxied bean. For API documentation, add quarkus-smallrye-openapi and the specification is served at /q/openapi, with Swagger UI at /q/swagger-ui in dev mode. Nothing needs configuring until you want to describe an endpoint more precisely with @Operation or @APIResponse, which come from the MicroProfile OpenAPI annotations and play the role of Springdoc's.

Measure the two frameworks on your own service

The performance claims are the reason many teams look at Quarkus, so test them on the service you would migrate, and on equal terms. Start both from a clean container, wait for readiness and record the numbers that matter for your deployment:

Shell
docker run -d --name spring-shop --memory 512m -p 8081:8080 shop-spring:1.0
docker run -d --name quarkus-shop --memory 512m -p 8082:8080 shop-quarkus:1.0

for name in spring-shop quarkus-shop; do
  echo "== $name"
  docker logs $name 2>&1 | grep -iE "started .* in|started in|Quarkus .* started in"
  docker stats --no-stream --format "memory: {{.MemUsage}}" $name
done

Then put both under the same load with a tool such as wrk or hey for a few minutes, and read the resident memory again after the run, since the first figure is idle memory and the second is what you will pay for at traffic. Repeat the experiment three times and report the median. The result differs for each service, because it depends on the libraries the service loads. A thin REST service can show a large gap, and a service dominated by a heavy dependency can show a small one. Make the decision from the table you produce, and keep the table in the pull request that proposes the migration.

A short checklist before you commit

Ask five questions of the service you have in mind. Does it use libraries without a Quarkus extension, and if so do they work on the classpath in JVM mode? Does it rely on runtime conditionals, such as beans created from a property value read at startup, which becomes build-time configuration? Does the team have a place to run native builds, with the memory and time they need? Are the people who will be on call comfortable with a new set of management endpoints and log formats? And does the measured gain matter to the business, in dollars of infrastructure or in seconds of cold start? Four yeses make a good migration, and fewer mean the new framework is a hobby for the team and not an improvement for the service.

When to stay on Spring

Stay on Spring when your team knows it, when your libraries are Spring-first (Spring Security, Spring Cloud, Spring Batch) or when you rely on runtime flexibility such as conditional beans decided from properties at startup. Move to Quarkus when density, cold start or a container budget is the constraint. Mixed estates exist, and a Quarkus service next to Spring services is fine because both speak HTTP and JDBC.

Share

Keep reading

Get new posts by email

We send one email when a new post is published. No spam.

Unsubscribe in one click. No spam, ever.