Building Web Applications with Spring MVC and WebFlux

Spring Boot gives you two distinct web stacks to choose from: the servlet-based Spring MVC stack for traditional, thread-per-request processing, and the reactive Spring WebFlux stack for non-blocking, asynchronous workloads. Both are first-class citizens with auto-configuration, embedded server support, and identical support for static content, template engines, and error handling.

Spring MVC (servlet)
Spring WebFlux (reactive)

Spring MVC runs on the servlet API and uses a thread-per-request model. It is the right choice when you need maximum compatibility with the existing Spring ecosystem or when your team is most familiar with imperative programming.Add the starter to your project:

pom.xml

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

A typical @RestController that serves JSON data:

MyRestController.java

@RestController
@RequestMapping("/api/users")
public class MyRestController {

    private final UserRepository repository;

    public MyRestController(UserRepository repository) {
        this.repository = repository;
    }

    @GetMapping("/{id}")
    public User getUser(@PathVariable Long id) {
        return repository.findById(id).orElseThrow();
    }

    @PostMapping
    public User createUser(@RequestBody User user) {
        return repository.save(user);
    }
}

Spring Boot provides auto-configuration for Spring MVC that works well with most applications. It replaces the need for @EnableWebMvc — the two cannot be used together. The auto-configuration provides:

ContentNegotiatingViewResolver and BeanNameViewResolver beans
Static resource serving including WebJars support
Automatic registration of Converter, GenericConverter, and Formatter beans
HttpMessageConverters with Jackson for JSON (and JAXB for XML when available)
Static index.html support

Spring WebFlux is the reactive web framework introduced in Spring Framework 5.0. Unlike Spring MVC, it does not require the servlet API, is fully asynchronous and non-blocking, and implements the Reactive Streams specification through the Reactor project.Add the starter to your project:

pom.xml

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-webflux</artifactId>
</dependency>

The annotation-based model is close to Spring MVC:

MyRestController.java

@RestController
@RequestMapping("/api/users")
public class MyRestController {

    private final UserRepository repository;

    public MyRestController(UserRepository repository) {
        this.repository = repository;
    }

    @GetMapping("/{id}")
    public Mono<User> getUser(@PathVariable Long id) {
        return repository.findById(id);
    }

    @GetMapping
    public Flux<User> getAllUsers() {
        return repository.findAll();
    }
}

Adding both spring-boot-starter-web and spring-boot-starter-webflux in your application results in Spring Boot auto-configuring Spring MVC, not WebFlux. You can still enforce your choice by setting SpringApplication.setWebApplicationType(WebApplicationType.REACTIVE).

Embedded servers

Spring Boot bundles an embedded server so you do not need to deploy to an external application server. The server to use is determined by the starter you add.

Tomcat

Default server for spring-boot-starter-web. Widely used, production-proven servlet container.

Jetty

Alternative for the servlet stack. Swap by excluding spring-boot-starter-tomcat and adding spring-boot-starter-jetty.

Reactor Netty

Default server for spring-boot-starter-webflux. Fully non-blocking, best suited for reactive workloads.

The embedded server listens on port 8080 by default. Configure it in application.properties or application.yaml:

application.yaml

server:
  port: 8443
  address: "0.0.0.0"

Error handling

By default, Spring Boot provides an /error mapping that handles all errors in a sensible way. For machine clients it produces a JSON response with the error details, HTTP status, and exception message. For browser clients, a “whitelabel” error page renders the same data in HTML. As of Spring Framework 6.0, RFC 9457 Problem Details is supported. Enable it with:

application.yaml

spring:
  mvc:
    problemdetails:
      enabled: true

When enabled, Spring MVC produces responses with application/problem+json:

{
  "type": "https://example.org/problems/unknown-project",
  "title": "Unknown project",
  "status": 404,
  "detail": "No project found for id 'spring-unknown'",
  "instance": "/projects/spring-unknown"
}

Custom HTML error pages go in the /error directory of your static resources:

src/main/resources/public/error/404.html    ← 404 page
src/main/resources/templates/error/5xx.ftlh ← all 5xx (FreeMarker)

Static content

By default, Spring Boot serves static content from /static, /public, /resources, or /META-INF/resources on the classpath. Resources are mapped on /**. Customize the path pattern:

application.yaml

spring:
  mvc:
    static-path-pattern: "/resources/**"

Enable content-based cache busting:

application.yaml

spring:
  web:
    resources:
      chain:
        strategy:
          content:
            enabled: true
            paths: "/**"

Do not use the src/main/webapp directory if your application is packaged as a JAR. Although this directory is a common standard, it works only with WAR packaging and is silently ignored when generating a JAR.

Template engines

Spring Boot includes auto-configuration support for the following templating engines for rendering dynamic HTML:

Engine	Dependency
Thymeleaf	`spring-boot-starter-thymeleaf`
FreeMarker	`spring-boot-starter-freemarker`
Mustache	`spring-boot-starter-mustache`
Groovy	`spring-boot-starter-groovy-templates`

When you use one of these templating engines with the default configuration, your templates are picked up automatically from src/main/resources/templates.

If possible, JSPs should be avoided. There are several known limitations when using them with embedded servlet containers.

CORS configuration

Cross-origin resource sharing (CORS) can be configured per-controller using @CrossOrigin annotations, or globally by registering a WebMvcConfigurer bean:

MyCorsConfiguration.java

@Configuration
public class MyCorsConfiguration implements WebMvcConfigurer {

    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/api/**")
            .allowedOrigins("https://example.com")
            .allowedMethods("GET", "POST", "PUT", "DELETE")
            .maxAge(3600);
    }
}

Spring GraphQL

Spring Boot auto-configures Spring for GraphQL when spring-boot-starter-graphql is on the classpath. Because GraphQL is transport-agnostic, you also need a web starter to expose the API.

application.yaml

spring:
  graphql:
    http:
      path: "/graphql"
    graphiql:
      enabled: true   # Enable browser UI (dev only)
    cors:
      allowed-origins: "https://example.org"
      allowed-methods: GET,POST
      max-age: 1800s

Place your schema files under src/main/resources/graphql/** with a .graphqls or .gqls extension. Spring Boot picks them up automatically. Implement query handlers using annotated @Controller classes:

GreetingController.java

@Controller
public class GreetingController {

    @QueryMapping
    public String greeting(@Argument String name) {
        return "Hello, " + name + "!";
    }
}

The GraphQL HTTP endpoint is at POST /graphql by default. Enable the WebSocket endpoint by setting spring.graphql.websocket.path.

API versioning

Both Spring MVC and Spring WebFlux support API versioning to evolve HTTP APIs over time. Configure versioning using properties:

application.yaml

spring:
  mvc:
    apiversion:
      default: 1.0.0
      use:
        header: X-Version

If your setup requires multiple strategies, such as header and query parameter combined, declare the order programmatically by overriding the configureApiVersioning method in a WebMvcConfigurer.

Get Started

Core Concepts

Building Applications

Production & Observability

Packaging & Deployment

Testing

Building Web Applications with Spring MVC and WebFlux

Embedded servers

Tomcat

Jetty

Reactor Netty

Error handling

Static content

Template engines

CORS configuration

Spring GraphQL

API versioning

Build docs developers (and LLMs) love

Get Started

Core Concepts

Building Applications

Production & Observability

Packaging & Deployment

Testing

Documentation Index

​Embedded servers

Tomcat

Jetty

Reactor Netty

​Error handling

​Static content

​Template engines

​CORS configuration

​Spring GraphQL

​API versioning

Build docs developers (and LLMs) love

Embedded servers

Error handling

Static content

Template engines

CORS configuration

Spring GraphQL

API versioning