spring-web

Active contributors: rstoyanchev, Juergen Hoeller, Brian Clozel, Sam Brannen, Sébastien Deleuze

Purpose

spring-web is the shared HTTP foundation used by both spring-webmvc (Servlet) and spring-webflux (reactive). It defines the HTTP type system (HttpStatusCode, HttpHeaders, MediaType, HttpRequest, HttpResponse), the HttpMessageConverter SPI, content negotiation, CORS, multipart parsing primitives, and the RestClient / RestTemplate (imperative HTTP clients) and reactive WebClient interfaces along with HTTP service interfaces (@HttpExchange).

Directory layout

spring-web/
└── src/main/java/org/springframework/
    ├── http/
    │   ├── HttpStatusCode.java
    │   ├── HttpStatus.java
    │   ├── HttpMethod.java
    │   ├── HttpHeaders.java
    │   ├── MediaType.java
    │   ├── HttpEntity.java / RequestEntity.java / ResponseEntity.java
    │   ├── client/                                 # RestClient, RestTemplate, ClientHttpRequest*
    │   │   ├── reactive/                           # reactive client adapters
    │   │   ├── support/
    │   │   └── observation/                        # Micrometer observability
    │   ├── codec/                                  # HttpMessageReader/Writer (reactive codecs)
    │   ├── converter/                              # HttpMessageConverter (servlet codecs)
    │   ├── server/                                 # ServerHttpRequest / ServerHttpResponse
    │   └── …
    └── web/
        ├── ErrorResponse.java
        ├── HttpRequestMethodNotSupportedException.java
        ├── HttpMediaTypeNotAcceptableException.java
        ├── …
        ├── accept/                                 # ContentNegotiationStrategy
        ├── bind/                                   # request data binding
        ├── client/                                 # RestClient builder
        ├── context/                                # WebApplicationContext, WebApplicationInitializer
        ├── cors/                                   # CORS configuration & processing
        ├── filter/                                 # generic Servlet filters (used by MVC + plain Servlet)
        ├── jsf/                                    # legacy JSF integration
        ├── method/                                 # HandlerMethod, HandlerMethodArgumentResolver
        ├── multipart/                              # multipart parsing
        ├── server/                                 # ServerWebExchange (reactive)
        ├── service/                                # @HttpExchange, HttpServiceProxyFactory
        └── util/                                   # UriComponentsBuilder, UriUtils

Key abstractions

Type	File	Role
MediaType	spring-web/src/main/java/org/springframework/http/MediaType.java	RFC-compliant content type with quality factor
HttpHeaders	spring-web/src/main/java/org/springframework/http/HttpHeaders.java	Multi-valued, case-insensitive header bag with typed getters
HttpStatusCode / HttpStatus	spring-web/src/main/java/org/springframework/http/HttpStatusCode.java	Status code value type and well-known constants
HttpEntity / RequestEntity / ResponseEntity	spring-web/src/main/java/org/springframework/http/	Headers + body wrappers
HttpMessageConverter<T>	spring-web/src/main/java/org/springframework/http/converter/HttpMessageConverter.java	Servlet-stack body codec SPI
HttpMessageReader / HttpMessageWriter	spring-web/src/main/java/org/springframework/http/codec/	Reactive-stack body codec SPI
ContentNegotiationStrategy	spring-web/src/main/java/org/springframework/web/accept/ContentNegotiationStrategy.java	Resolves desired media type from request
CorsConfiguration / CorsProcessor	spring-web/src/main/java/org/springframework/web/cors/	CORS rules + processing
UriComponentsBuilder	spring-web/src/main/java/org/springframework/web/util/UriComponentsBuilder.java	URI construction
RestClient	spring-web/src/main/java/org/springframework/web/client/RestClient.java	Imperative fluent HTTP client (preferred over RestTemplate)
RestTemplate	spring-web/src/main/java/org/springframework/web/client/RestTemplate.java	Older imperative HTTP client
WebClient	reactive (in spring-webflux, but the interface lives here under org.springframework.web.reactive.function.client)	Reactive HTTP client
@HttpExchange / HttpServiceProxyFactory	spring-web/src/main/java/org/springframework/web/service/	Declarative HTTP clients (interface-driven)
HandlerMethod	spring-web/src/main/java/org/springframework/web/method/HandlerMethod.java	Reflective representation of a controller method
HandlerMethodArgumentResolver	spring-web/src/main/java/org/springframework/web/method/support/	SPI used by both stacks to resolve method args

How it works

spring-web is a library — it doesn't run anything on its own. It provides the parts both web stacks compose.

Two clients, two encoders

graph TB
    subgraph Imperative
      App1[Application] -->|"calls"| RC[RestClient / RestTemplate]
      RC --> HMC[HttpMessageConverter]
      RC --> HRF[ClientHttpRequestFactory]
      HRF --> HTTP1[HTTP transport]
    end

    subgraph Reactive
      App2[Application] -->|"calls"| WC[WebClient]
      WC --> HMRW[HttpMessageReader/Writer]
      WC --> HCC[ClientHttpConnector]
      HCC --> HTTP2[Reactor Netty / Jetty / HttpClient5]
    end

HttpMessageConverters convert objects ↔ bytes for blocking I/O. The reactive equivalents HttpMessageReader/Writer operate on Publisher<DataBuffer> for backpressure-aware streaming. Spring ships converters/codecs for JSON (Jackson, Kotlin Serialization, Gson, JSON-B), XML (JAXB), Smile, CBOR, protobuf, form data, and plain strings/bytes.

@HttpExchange declarative clients

sequenceDiagram
    participant App
    participant Proxy as HttpServiceProxyFactory
    participant Adapter as HttpExchangeAdapter
    participant HC as RestClient or WebClient
    App->>Proxy: createClient(MyApi.class)
    Proxy-->>App: MyApi proxy
    App->>Proxy: api.getUser(42)
    Proxy->>Adapter: invoke(method, args)
    Adapter->>HC: GET /users/42
    HC-->>Adapter: response body
    Adapter-->>App: User

Define an interface with @HttpExchange("/users/{id}") methods; Spring builds a proxy that drives a RestClient, RestTemplate, or WebClient. This is the framework's modern declarative HTTP client (replacing OpenFeign for Spring users).

CORS

CorsConfiguration describes allowed origins/methods/headers; DefaultCorsProcessor applies them per request. Both web stacks delegate to this code.

Content negotiation

ContentNegotiationStrategy resolves the desired response media type from the URL extension (legacy), Accept header (default), or a fixed override. Both stacks share the strategy interface.

Server abstractions

ServerHttpRequest/ServerHttpResponse and ServerWebExchange (reactive) are abstractions over the underlying server (Servlet vs. reactive Netty). They let library code work without committing to a runtime.

Integration points

• Used by spring-webmvc and spring-webflux for HTTP types, codecs, exception types, and the @HttpExchange machinery.
• Optional deps spring-aop, spring-context, spring-oxm (for XML codecs).
• Multipart depends on Apache Commons FileUpload for one parser implementation; another uses Jakarta Servlet 5+'s built-in multipart.
• Observability integrates with Micrometer.

Entry points for modification

• New body codec — Implement HttpMessageConverter<T> for the Servlet stack and/or HttpMessageReader/HttpMessageWriter for the reactive stack. Register via WebMvcConfigurer.configureMessageConverters or WebFluxConfigurer.configureHttpMessageCodecs.
• Custom argument resolver — Implement HandlerMethodArgumentResolver and register via the corresponding configurer.
• Declarative client extension — Implement HttpExchangeAdapter to drive @HttpExchange over a custom transport.

Notable internals

• UriComponentsBuilder — A focused, RFC-3986-aware URI builder that's used everywhere from controllers to clients.
• PathPattern / AntPathMatcher — Path-matching engines. PathPattern (in spring-web's sibling package org.springframework.web.util.pattern) is the modern, segmented matcher; AntPathMatcher is the older string-based one.
• HttpRange — Models Range header byte ranges for partial-content responses.

See also

• spring-webmvc — Servlet-stack consumer
• spring-webflux — Reactive-stack consumer
• features/web-mvc and features/reactive-stack