Skip to content
Tutorials Center
My learning

Topics

Lesson 36 of 36 ยท Projects and Practice

Migrating from Spring Boot to Quarkus

Move a Spring Boot service to Quarkus: annotation and config mapping, the Spring compatibility extensions, Panache versus Spring Data, tests, pitfalls and a safe step plan.

Many teams meet Quarkus with an existing Spring Boot service in hand. The question is rarely "which framework is better?" but "what would it cost to move this service, and what would we get?". The answer: the concepts map almost one to one, because both frameworks are dependency injection plus REST plus data access plus configuration. What changes is the vocabulary, a few defaults, and the model of build-time versus run-time work.

This lesson gives you the mapping tables, the compatibility extensions that let you migrate in steps, the places where the two really differ, and a plan. If you do not know Spring Boot, the Spring Boot tutorial covers it; the same ideas also appear in Micronaut. The real project files are read-only; the TryIts implement a source scanner and a mapping helper that you can adapt to your own code base.

The mapping at a glance

Concern Spring Boot Quarkus
Bean annotation @Component, @Service @ApplicationScoped (CDI)
Request scope @RequestScope @RequestScoped
Singleton @Component (default singleton) @Singleton or @ApplicationScoped
Injection @Autowired @Inject (constructor injection needs no annotation if there is one constructor)
Qualifier @Qualifier("x") @Named("x") or a custom @Qualifier
Value @Value("${a.b}") @ConfigProperty(name = "a.b")
Typed config @ConfigurationProperties @ConfigMapping
REST controller @RestController, @RequestMapping @Path (Jakarta REST), or the Spring-web compatibility
Handlers @GetMapping, @PostMapping @GET, @POST
Parameters @PathVariable, @RequestParam, @RequestBody @PathParam, @QueryParam, a plain parameter
Error handling @ControllerAdvice ExceptionMapper or @ServerExceptionMapper
JPA Spring Data repositories Panache (active record or repository)
Transactions @Transactional (Spring) @Transactional (Jakarta)
Profiles spring.profiles.active, application-dev.yml quarkus.profile, %dev.key
Tests @SpringBootTest @QuarkusTest
Mock bean @MockBean @InjectMock
Actuator /actuator/health /q/health
Scheduling @Scheduled @Scheduled (Quarkus Scheduler)
Events ApplicationEventPublisher CDI events: Event<T>, @Observes
AOP @Aspect CDI interceptors
Messaging Spring Kafka, @KafkaListener Reactive Messaging, @Incoming
Build tool output fat jar fast-jar or native

Same ideas, new names

DI @Autowired becomes @Inject.
REST @RestController becomes @Path.
Data Spring Data becomes Panache.
Config @Value becomes @ConfigProperty.

Most code moves with search and replace plus review.

1 / 2

Spring compatibility extensions

Quarkus offers a bridge so you can migrate gradually and keep Spring annotations in the code for a while:

  • quarkus-spring-di: @Autowired, @Component, @Service, @Configuration, @Bean, @Value.
  • quarkus-spring-web: @RestController, @RequestMapping, @GetMapping, ResponseEntity, @ControllerAdvice (a subset).
  • quarkus-spring-data-jpa: Spring Data interfaces such as JpaRepository, derived query methods and @Query (a subset).
  • quarkus-spring-security, quarkus-spring-boot-properties, quarkus-spring-cache, quarkus-spring-scheduled.

These are a bridge, not a destination. They cover the common subset, and complex Spring features (custom BeanPostProcessor, SpEL beyond simple cases, full Spring Security configuration) are unsupported. Use them to get the service running quickly, then replace annotations with the Quarkus-native ones one package at a time, because the native model gives better documentation, tooling and native-image behavior.

Example: a controller before and after

Java
// Spring Boot
@RestController
@RequestMapping("/books")
class BookController {
    private final BookService service;
    BookController(BookService service) { this.service = service; }

    @GetMapping("/{id}")
    ResponseEntity<Book> get(@PathVariable long id) {
        return service.find(id).map(ResponseEntity::ok).orElse(ResponseEntity.notFound().build());
    }

    @PostMapping
    ResponseEntity<Book> create(@Valid @RequestBody Book book) { ... }
}
Java
// Quarkus
@Path("/books")
@Produces(MediaType.APPLICATION_JSON)
public class BookResource {
    private final BookService service;
    BookResource(BookService service) { this.service = service; }

    @GET @Path("/{id}")
    public Book get(@PathParam("id") long id) {
        return service.find(id).orElseThrow(NotFoundException::new);
    }

    @POST
    public Response create(@Valid Book book) { ... }
}

And data access, from a Spring Data repository to a Panache repository:

Java
// Spring Data
interface BookRepository extends JpaRepository<Book, Long> {
    List<Book> findByAuthorOrderByTitle(String author);
}

// Quarkus Panache (repository style)
@ApplicationScoped
class BookRepository implements PanacheRepository<Book> {
    List<Book> byAuthor(String author) { return list("author", Sort.by("title"), author); }
}

The derived-query naming convention (findByAuthorOrderByTitle) has no Panache equivalent; you write a short query string instead. Teams find this clearer after a week.

Java Stand-in: a source scanner that suggests Quarkus replacements

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Configuration migration

application.yml works in Quarkus if you add quarkus-config-yaml, and application.properties keys keep their format, but key names change for framework settings:

Spring Boot Quarkus
server.port quarkus.http.port
spring.datasource.url quarkus.datasource.jdbc.url
spring.datasource.username quarkus.datasource.username
spring.jpa.hibernate.ddl-auto quarkus.hibernate-orm.database.generation
logging.level.org.acme quarkus.log.category."org.acme".level
management.endpoints... built in under /q/
spring.profiles.active=prod quarkus.profile=prod
spring.kafka.bootstrap-servers kafka.bootstrap.servers

Your own keys (shop.currency) stay as they are. Environment variable mapping follows the same upper-case and underscore rule, so deployment scripts mostly keep working once the framework key names are fixed (config lesson).

Java Stand-in: translate framework property keys

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Things that behave differently

  • Singleton by default? Spring beans are singletons. Quarkus @ApplicationScoped beans are also created once, but lazily and through a client proxy, so final classes or private methods called through the proxy need care. Plain @Singleton has no proxy.
  • Field injection is encouraged less. Use constructor injection; Quarkus handles a single constructor without @Inject.
  • No component scanning at runtime. A bean in a library jar is only discovered if the jar has a Jandex index (META-INF/jandex.idx) or you set quarkus.index-dependency.*. This is the most common migration surprise for multi-module projects.
  • Unused beans are removed. If code looks up beans by name or type dynamically, annotate them @Unremovable (build-time lesson).
  • Open Session in View does not exist. Lazy associations must be fetched inside the transaction (use JOIN FETCH or DTO projections).
  • Jackson, Hibernate Validator, Flyway, Kafka are all available, but use the Quarkus extension, not the plain library, so the build-time integration and native support work.
  • Libraries that depend on Spring internals (Spring Cloud, Spring Batch, Spring Integration) have no direct counterpart. Quarkus has extensions for config, discovery, fault tolerance (quarkus-smallrye-fault-tolerance) and Camel, but check each need.
  • Lombok works with Quarkus, but records and public fields on Panache entities usually replace it.

A safe migration plan

  1. Measure first. Record startup time, memory and throughput of the current service so that you can show the gain.
  2. Pick a service that is small and well tested. Migrating the least critical service teaches the team without risk.
  3. Create the Quarkus project with the matching extensions and the compatibility extensions you need. Copy the source over.
  4. Get the tests running with @QuarkusTest (@SpringBootTest becomes @QuarkusTest, @MockBean becomes @InjectMock). Tests are your safety net; migrate them first if you can.
  5. Fix configuration key names and profiles. Run with Dev Services.
  6. Replace Spring annotations gradually with native ones, package by package, and drop the compatibility extensions.
  7. Compare behavior against the old service with contract tests or by replaying production traffic.
  8. Deploy side by side (canary), watch health and metrics, then switch over.
  9. Only then consider native images; measure whether you need them.

When not to migrate

If the service depends deeply on Spring Cloud, Spring Batch or a Spring-only library, if the team has no capacity for a framework change, or if startup time and memory cost are not a problem, staying put is a valid decision. New services are a better place to start with Quarkus than a risky rewrite of a stable one.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which Quarkus annotation replaces @Autowired?

    Quarkus uses Jakarta CDI, so injection is @Inject (or a single constructor).
  2. 2. What is the purpose of the Spring compatibility extensions?

    They are a bridge for a subset of Spring APIs; the goal is to move to the Quarkus-native annotations.
  3. 3. Beans from a library jar are not discovered. What is a typical fix?

    Build-time discovery needs an index of the library's classes.
  4. 4. Which Spring feature has no equivalent in Quarkus's Hibernate integration?

    Lazy loading must happen inside a transaction or be replaced by fetch joins and projections.

Summary

  • Concepts map almost one to one: CDI annotations, Jakarta REST, Panache, @ConfigProperty/@ConfigMapping, @QuarkusTest.
  • Compatibility extensions help migrate in steps but are a bridge, not a goal.
  • Framework property keys are renamed; your own keys stay.
  • Build-time discovery, unused-bean removal and no Open Session in View are the real behavioral differences.
  • Migrate a small, well-tested service first, compare behavior and deploy side by side.

Next: Quarkus Practice Questions and Interview Prep