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.

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 Boot | You use in Quarkus |
|---|---|
@Component, @Service, @Autowired | @ApplicationScoped, @Inject (CDI) |
@RestController, @GetMapping | @Path, @GET (JAX-RS, Quarkus REST) |
| Spring Data JPA repository | Panache repository or active record |
@ConfigurationProperties | @ConfigMapping |
| Actuator | SmallRye Health and Micrometer extensions |
| Spring Boot DevTools restart | Dev mode (quarkus dev) |
@SpringBootTest | @QuarkusTest |
| Testcontainers wiring | Dev Services |
A resource looks familiar:
@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
./mvnw quarkus:devDev 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.:
quarkus.datasource.db-kind=postgresql
%prod.quarkus.datasource.jdbc.url=jdbc:postgresql://db:5432/shop
%dev.quarkus.hibernate-orm.database.generation=drop-and-createAn 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):
./mvnw package -DnativeThe 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:
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:
@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:
@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.
@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:
@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:
@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();
}
}shop.currency=USD
shop.pricing.tax-rate=0.08Inject 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:
@RegisterRestClient(configKey = "pricing")
@Path("/prices")
public interface PricingClient {
@GET
@Path("/{sku}")
@Produces(MediaType.APPLICATION_JSON)
Price priceOf(@PathParam("sku") String sku);
}quarkus.rest-client.pricing.url=http://pricing:8080
quarkus.rest-client.pricing.connect-timeout=300
quarkus.rest-client.pricing.read-timeout=1000Inject 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:
@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:
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 Security | Quarkus |
|---|---|
SecurityFilterChain with authorizeHttpRequests | quarkus.http.auth.permission.* properties, or annotations |
@PreAuthorize("hasRole('ADMIN')") | @RolesAllowed("ADMIN") |
oauth2ResourceServer().jwt() | quarkus-smallrye-jwt or quarkus-oidc |
| Keycloak adapter or OAuth2 client | quarkus-oidc with Dev Services for Keycloak |
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@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:
@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:
@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:
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:
- 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).
- Move the domain and the pure logic over unchanged. Plain classes need no change at all.
- Rewrite the edges: resources for controllers, repositories for Spring Data,
@ConfigMappingfor properties. - Port the tests, and run them in dev mode with continuous testing on.
- Build the native image only if you need it, and run the integration tests against it in CI.
- 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
| Mistake | What happens | Fix |
|---|---|---|
| Changing a build-time property through an environment variable | No effect on the deployed jar | Rebuild, or check the configuration reference for the property's phase |
| Assuming a bean is created by component scanning | Bean missing, or a build error about an unsatisfied dependency | Add a bean-defining annotation such as @ApplicationScoped |
| Using reflection on your own classes in a native image | Works on the JVM, fails natively | @RegisterReflectionForBinding or @RegisterForReflection |
Expecting readOnly transactions | No such attribute | Project into DTOs for reads |
Reaching for @Autowired on a private field | Compiles with the compatibility extension, surprises in review | Use @Inject and package-private fields or constructors |
Looking for /actuator/health | 404 | Use /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:
WARN [io.qua.ver.cor.run.VertxCoreRecorder] Thread Thread[vert.x-eventloop-thread-1,5,main] has been blocked for 2610 msFor 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:
@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:
@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) {
}
}quarkus.cache.caffeine."prices".expire-after-write=10M
quarkus.cache.caffeine."prices".maximum-size=5000The 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:
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
doneThen 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.


