对于最新的稳定版本,请使用 Spring Boot 3.4.0! |
Servlet Web 应用程序
如果您想构建基于 servlet 的 Web 应用程序,您可以利用 Spring Boot 对 Spring MVC 或 Jersey 的自动配置。
“Spring Web MVC 框架”
Spring Web MVC 框架(通常称为“Spring MVC”)是一个丰富的“模型视图控制器”Web 框架。
Spring MVC 允许您创建特殊的@Controller
或@RestController
bean 来处理传入的 HTTP 请求。
控制器中的方法通过使用@RequestMapping
附注。
以下代码显示了一个典型的@RestController
,它提供 JSON 数据:
-
Java
-
Kotlin
import java.util.List;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
@RequestMapping("/users")
public class MyRestController {
private final UserRepository userRepository;
private final CustomerRepository customerRepository;
public MyRestController(UserRepository userRepository, CustomerRepository customerRepository) {
this.userRepository = userRepository;
this.customerRepository = customerRepository;
}
@GetMapping("/{userId}")
public User getUser(@PathVariable Long userId) {
return this.userRepository.findById(userId).get();
}
@GetMapping("/{userId}/customers")
public List<Customer> getUserCustomers(@PathVariable Long userId) {
return this.userRepository.findById(userId).map(this.customerRepository::findByUser).get();
}
@DeleteMapping("/{userId}")
public void deleteUser(@PathVariable Long userId) {
this.userRepository.deleteById(userId);
}
}
import org.springframework.web.bind.annotation.DeleteMapping
import org.springframework.web.bind.annotation.GetMapping
import org.springframework.web.bind.annotation.PathVariable
import org.springframework.web.bind.annotation.RequestMapping
import org.springframework.web.bind.annotation.RestController
@RestController
@RequestMapping("/users")
class MyRestController(private val userRepository: UserRepository, private val customerRepository: CustomerRepository) {
@GetMapping("/{userId}")
fun getUser(@PathVariable userId: Long): User {
return userRepository.findById(userId).get()
}
@GetMapping("/{userId}/customers")
fun getUserCustomers(@PathVariable userId: Long): List<Customer> {
return userRepository.findById(userId).map(customerRepository::findByUser).get()
}
@DeleteMapping("/{userId}")
fun deleteUser(@PathVariable userId: Long) {
userRepository.deleteById(userId)
}
}
“WebMvc.fn”是功能变体,它将路由配置与请求的实际处理分开,如以下示例所示:
-
Java
-
Kotlin
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.MediaType;
import org.springframework.web.servlet.function.RequestPredicate;
import org.springframework.web.servlet.function.RouterFunction;
import org.springframework.web.servlet.function.ServerResponse;
import static org.springframework.web.servlet.function.RequestPredicates.accept;
import static org.springframework.web.servlet.function.RouterFunctions.route;
@Configuration(proxyBeanMethods = false)
public class MyRoutingConfiguration {
private static final RequestPredicate ACCEPT_JSON = accept(MediaType.APPLICATION_JSON);
@Bean
public RouterFunction<ServerResponse> routerFunction(MyUserHandler userHandler) {
return route()
.GET("/{user}", ACCEPT_JSON, userHandler::getUser)
.GET("/{user}/customers", ACCEPT_JSON, userHandler::getUserCustomers)
.DELETE("/{user}", ACCEPT_JSON, userHandler::deleteUser)
.build();
}
}
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.http.MediaType
import org.springframework.web.servlet.function.RequestPredicates.accept
import org.springframework.web.servlet.function.RouterFunction
import org.springframework.web.servlet.function.RouterFunctions
import org.springframework.web.servlet.function.ServerResponse
@Configuration(proxyBeanMethods = false)
class MyRoutingConfiguration {
@Bean
fun routerFunction(userHandler: MyUserHandler): RouterFunction<ServerResponse> {
return RouterFunctions.route()
.GET("/{user}", ACCEPT_JSON, userHandler::getUser)
.GET("/{user}/customers", ACCEPT_JSON, userHandler::getUserCustomers)
.DELETE("/{user}", ACCEPT_JSON, userHandler::deleteUser)
.build()
}
companion object {
private val ACCEPT_JSON = accept(MediaType.APPLICATION_JSON)
}
}
-
Java
-
Kotlin
import org.springframework.stereotype.Component;
import org.springframework.web.servlet.function.ServerRequest;
import org.springframework.web.servlet.function.ServerResponse;
@Component
public class MyUserHandler {
public ServerResponse getUser(ServerRequest request) {
...
}
public ServerResponse getUserCustomers(ServerRequest request) {
...
}
public ServerResponse deleteUser(ServerRequest request) {
...
}
}
import org.springframework.stereotype.Component
import org.springframework.web.servlet.function.ServerRequest
import org.springframework.web.servlet.function.ServerResponse
@Component
class MyUserHandler {
fun getUser(request: ServerRequest?): ServerResponse {
...
}
fun getUserCustomers(request: ServerRequest?): ServerResponse {
...
}
fun deleteUser(request: ServerRequest?): ServerResponse {
...
}
}
Spring MVC 是核心 Spring Framework 的一部分,详细信息可在参考文档中找到。 spring.io/guides 上还提供了几个涵盖 Spring MVC 的指南。
您可以定义任意数量的RouterFunction bean 来模块化路由器的定义。
如果需要应用优先级,则可以对 bean 进行排序。 |
Spring MVC 自动配置
Spring Boot 为 Spring MVC 提供了自动配置,适用于大多数应用程序。
它取代了对@EnableWebMvc
并且两者不能一起使用。
除了 Spring MVC 的默认值之外,自动配置还提供以下功能:
-
支持提供静态资源,包括对 WebJar 的支持(本文档稍后将介绍)。
-
支持
HttpMessageConverters
(本文档稍后将介绍)。 -
自动注册
MessageCodesResolver
(本文档稍后将介绍)。 -
静态的
index.html
支持。 -
自动使用
ConfigurableWebBindingInitializer
Bean(本文档稍后将介绍)。
如果你想保留这些 Spring Boot MVC 自定义并进行更多的 MVC 自定义(拦截器、格式化程序、视图控制器和其他功能),你可以添加自己的@Configuration
type 类WebMvcConfigurer
但没有 @EnableWebMvc
.
如果要提供RequestMappingHandlerMapping
,RequestMappingHandlerAdapter
或ExceptionHandlerExceptionResolver
,并且仍然保留 Spring Boot MVC 自定义,则可以声明一个 bean 类型的WebMvcRegistrations
并使用它来提供这些组件的自定义实例。
自定义实例将受 Spring MVC 的进一步初始化和配置的约束。
要参与并在需要时覆盖该后续处理,需要一个WebMvcConfigurer
应该使用。
如果您不想使用自动配置并希望完全控制 Spring MVC,请添加您自己的@Configuration
注解@EnableWebMvc
.
或者,添加您自己的@Configuration
-注释DelegatingWebMvcConfiguration
如@EnableWebMvc
API 文档。
Spring MVC 转换服务
Spring MVC 使用不同的ConversionService
转换为用于将值从application.properties
或application.yaml
文件。
这意味着Period
,Duration
和DataSize
转换器不可用,并且@DurationUnit
和@DataSizeUnit
注释将被忽略。
如果要自定义ConversionService
由 Spring MVC 使用,您可以提供WebMvcConfigurer
带有addFormatters
方法。
通过此方法,您可以注册您喜欢的任何转换器,也可以委托给ApplicationConversionService
.
转换也可以使用spring.mvc.format.*
configuration 属性。
如果未配置,则使用以下默认值:
财产 | DateTimeFormatter |
格式 |
---|---|---|
|
|
|
|
|
java.time 的 |
|
|
java.time 的 |
HttpMessage转换器
Spring MVC 使用HttpMessageConverter
接口来转换 HTTP 请求和响应。
合理的默认值是开箱即用的。
例如,对象可以自动转换为 JSON(通过使用 Jackson 库)或 XML(通过使用 Jackson XML 扩展,如果可用,或者通过使用 JAXB,如果 Jackson XML 扩展不可用)。
默认情况下,字符串以UTF-8
.
任何HttpMessageConverter
将 Bean 添加到转换器列表中。
您也可以以相同的方式覆盖默认转换器。
如果需要添加或自定义转换器,可以使用 Spring Boot 的HttpMessageConverters
类,如下面的清单所示:
-
Java
-
Kotlin
import org.springframework.boot.autoconfigure.http.HttpMessageConverters;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.converter.HttpMessageConverter;
@Configuration(proxyBeanMethods = false)
public class MyHttpMessageConvertersConfiguration {
@Bean
public HttpMessageConverters customConverters() {
HttpMessageConverter<?> additional = new AdditionalHttpMessageConverter();
HttpMessageConverter<?> another = new AnotherHttpMessageConverter();
return new HttpMessageConverters(additional, another);
}
}
import org.springframework.boot.autoconfigure.http.HttpMessageConverters
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.http.converter.HttpMessageConverter
@Configuration(proxyBeanMethods = false)
class MyHttpMessageConvertersConfiguration {
@Bean
fun customConverters(): HttpMessageConverters {
val additional: HttpMessageConverter<*> = AdditionalHttpMessageConverter()
val another: HttpMessageConverter<*> = AnotherHttpMessageConverter()
return HttpMessageConverters(additional, another)
}
}
为了进一步控制,您还可以将 sub-classHttpMessageConverters
并覆盖其postProcessConverters
和/或postProcessPartConverters
方法。
当您想要重新排序或删除 Spring MVC 默认配置的某些转换器时,这可能很有用。
MessageCodes解析器
Spring MVC 有一个生成错误代码的策略,用于呈现来自绑定错误的错误消息:MessageCodesResolver
.
如果将spring.mvc.message-codes-resolver-format
财产PREFIX_ERROR_CODE
或POSTFIX_ERROR_CODE
,Spring Boot 会为您创建一个(请参阅DefaultMessageCodesResolver.Format
).
静态内容
默认情况下, Spring Boot 从名为/static
(或/public
或/resources
或/META-INF/resources
) 或从ServletContext
.
它使用ResourceHttpRequestHandler
从 Spring MVC,以便您可以通过添加自己的WebMvcConfigurer
并覆盖addResourceHandlers
方法。
在独立的 Web 应用程序中,未启用容器中的默认 Servlet。
可以使用server.servlet.register-default-servlet
财产。
默认 Servlet 充当后备,从ServletContext
如果 Spring 决定不处理它。
大多数情况下,这不会发生(除非你修改了默认的 MVC 配置),因为 Spring 总是可以通过DispatcherServlet
.
默认情况下,资源映射在 上,但您可以使用/**
spring.mvc.static-path-pattern
财产。
例如,将所有资源重新定位到/resources/**
可以按如下方式实现:
-
Properties
-
YAML
spring.mvc.static-path-pattern=/resources/**
spring:
mvc:
static-path-pattern: "/resources/**"
您还可以使用spring.web.resources.static-locations
属性(将默认值替换为目录位置列表)。
根 Servlet 上下文路径 也会自动添加为位置。"/"
除了前面提到的“标准”静态资源位置之外,Webjars 内容还有一个特殊情况。
默认情况下,路径为/webjars/**
如果 jar 文件以 Webjars 格式打包,则从 jar 文件中提供。
可以使用spring.mvc.webjars-path-pattern
财产。
请勿使用src/main/webapp 目录(如果您的应用程序打包为 jar)。
虽然这个目录是一个通用标准,但它仅适用于 war 打包,如果你生成一个 jar,大多数构建工具都会默默地忽略它。 |
Spring Boot 还支持 Spring MVC 提供的高级资源处理功能,允许使用诸如缓存清除静态资源或对 Webjar 使用与版本无关的 URL 等用例。
要对 Webjar 使用与版本无关的 URL,请添加webjars-locator-core
Dependency。
然后声明您的 Webjar。
以 jQuery 为例,添加"/webjars/jquery/jquery.min.js"
结果"/webjars/jquery/x.y.z/jquery.min.js"
哪里x.y.z
是 Webjar 版本。
如果您使用 JBoss,则需要声明webjars-locator-jboss-vfs dependency 而不是webjars-locator-core .
否则,所有 Webjar 都会解析为404 . |
要使用缓存清除,以下配置为所有静态资源配置缓存清除解决方案,从而有效地添加内容哈希,例如<link href="/css/spring-2a2d595e6ed9a0b24f027f2b63b134d6.css"/>
,在 URL 中:
-
Properties
-
YAML
spring.web.resources.chain.strategy.content.enabled=true
spring.web.resources.chain.strategy.content.paths=/**
spring:
web:
resources:
chain:
strategy:
content:
enabled: true
paths: "/**"
指向资源的链接在运行时在模板中重写,这要归功于ResourceUrlEncodingFilter 这是为 Thymeleaf 和 FreeMarker 自动配置的。
使用 JSP 时,应手动声明此过滤器。
其他模板引擎目前不自动支持,但可以使用自定义模板宏/帮助程序并使用ResourceUrlProvider . |
例如,使用 JavaScript 模块加载器动态加载资源时,重命名文件不是一个选项。 这就是为什么还支持其他策略并且可以组合的原因。 “fixed” 策略在 URL 中添加静态版本字符串,而不更改文件名,如以下示例所示:
-
Properties
-
YAML
spring.web.resources.chain.strategy.content.enabled=true
spring.web.resources.chain.strategy.content.paths=/**
spring.web.resources.chain.strategy.fixed.enabled=true
spring.web.resources.chain.strategy.fixed.paths=/js/lib/
spring.web.resources.chain.strategy.fixed.version=v12
spring:
web:
resources:
chain:
strategy:
content:
enabled: true
paths: "/**"
fixed:
enabled: true
paths: "/js/lib/"
version: "v12"
使用此配置,位于"/js/lib/"
使用固定版本控制策略 ("/v12/js/lib/mymodule.js"
),而其他资源仍然使用内容 (<link href="/css/spring-2a2d595e6ed9a0b24f027f2b63b134d6.css"/>
).
看WebProperties.Resources
以获取更多支持的选项。
欢迎页面
Spring Boot 支持静态和模板化欢迎页面。
它首先查找index.html
文件。
如果未找到,则查找index
模板。
如果找到任何一个,它将自动用作应用程序的欢迎页面。
这仅充当应用程序定义的实际索引路由的回退。
排序由HandlerMapping
beans 的 bean 中,默认情况下,它的作用如下:
|
|
|
|
|
欢迎页面支持 |
路径匹配和内容协商
Spring MVC 可以通过查看请求路径并将其与应用程序中定义的 Map(例如,@GetMapping
Controller 方法上的注释)。
Spring Boot 默认选择禁用后缀模式匹配,这意味着像"GET /projects/spring-boot.json"
将不匹配到@GetMapping("/projects/spring-boot")
映射。
这被认为是 Spring MVC 应用程序的最佳实践。
此功能在过去主要对没有发送正确的 “Accept” 请求标头的 HTTP 客户端有用;我们需要确保将正确的 Content Type 发送给客户端。
如今,Content Negotiation 更加可靠。
还有其他方法可以处理 HTTP 客户端,这些客户端不能始终如一地发送正确的 “Accept” 请求标头。
我们可以使用 query 参数来确保像"GET /projects/spring-boot?format=json"
将映射到@GetMapping("/projects/spring-boot")
:
-
Properties
-
YAML
spring.mvc.contentnegotiation.favor-parameter=true
spring:
mvc:
contentnegotiation:
favor-parameter: true
或者,如果您更喜欢使用不同的参数名称:
-
Properties
-
YAML
spring.mvc.contentnegotiation.favor-parameter=true
spring.mvc.contentnegotiation.parameter-name=myparam
spring:
mvc:
contentnegotiation:
favor-parameter: true
parameter-name: "myparam"
大多数标准媒体类型都是开箱即用的,但您也可以定义新的媒体类型:
-
Properties
-
YAML
spring.mvc.contentnegotiation.media-types.markdown=text/markdown
spring:
mvc:
contentnegotiation:
media-types:
markdown: "text/markdown"
从 Spring Framework 5.3 开始, Spring MVC 支持两种将请求路径与控制器匹配的策略。
默认情况下,Spring Boot 使用PathPatternParser
策略。PathPatternParser
是一种优化的实现,但与AntPathMatcher
策略。PathPatternParser
限制某些路径模式变体的使用。
它也与配置DispatcherServlet
使用路径前缀 (spring.mvc.servlet.path
).
该策略可以使用spring.mvc.pathmatch.matching-strategy
configuration 属性,如以下示例所示:
-
Properties
-
YAML
spring.mvc.pathmatch.matching-strategy=ant-path-matcher
spring:
mvc:
pathmatch:
matching-strategy: "ant-path-matcher"
Spring MVC 将抛出一个NoHandlerFoundException
如果未找到请求的处理程序。
请注意,默认情况下,静态内容的提供会映射到所有请求,因此会为所有请求提供处理程序。
如果没有可用的静态内容,/**
ResourceHttpRequestHandler
会抛出一个NoResourceFoundException
.
对于NoHandlerFoundException
要被抛出,请将spring.mvc.static-path-pattern
设置为更具体的值,例如/resources/**
或设置spring.web.resources.add-mappings
自false
以完全禁用静态内容的提供。
ConfigurableWebBindingInitializer
Spring MVC 使用WebBindingInitializer
要初始化WebDataBinder
对于特定请求。
如果您创建自己的ConfigurableWebBindingInitializer
@Bean
,Spring Boot 会自动配置 Spring MVC 以使用它。
模板引擎
除了 REST Web 服务之外,您还可以使用 Spring MVC 来提供动态 HTML 内容。 Spring MVC 支持多种模板技术,包括 Thymeleaf、FreeMarker 和 JSP。 此外,许多其他模板引擎包括他们自己的 Spring MVC 集成。
Spring Boot 包括对以下模板引擎的自动配置支持:
如果可能,应避免使用 JSP。 将它们与嵌入式 servlet 容器一起使用时,存在几个已知的限制。 |
当您使用具有默认配置的模板引擎之一时,您的模板会自动从src/main/resources/templates
.
根据您运行应用程序的方式,IDE 可能会以不同的方式对 Classpath 进行排序。 在 IDE 中,从 main 方法运行应用程序时,与使用 Maven 或 Gradle 或从其打包的 jar 运行应用程序时的顺序不同。 这可能会导致 Spring Boot 无法找到预期的模板。 如果遇到此问题,可以在 IDE 中对 Classpath 重新排序,以便将模块的类和资源放在最前面。 |
错误处理
默认情况下, Spring Boot 提供了一个/error
映射,它以合理的方式处理所有错误,并在 servlet 容器中注册为“全局”错误页。
对于计算机客户端,它会生成一个 JSON 响应,其中包含错误、HTTP 状态和异常消息的详细信息。
对于浏览器客户端,有一个 “whitelabel” 错误视图,它以 HTML 格式呈现相同的数据(要对其进行自定义,请添加View
解析为error
).
有许多server.error
属性,如果要自定义默认错误处理行为,则可以设置这些属性。
请参阅附录的 Server Properties 部分。
要完全替换默认行为,您可以实现ErrorController
并注册该类型的 bean 定义或添加ErrorAttributes
以使用现有机制,但替换内容。
这BasicErrorController 可用作自定义ErrorController .
如果要为新的内容类型添加处理程序(默认为 handletext/html 具体来说,并为其他所有内容提供回退)。
为此,请扩展BasicErrorController 中,添加一个带有@RequestMapping 具有produces 属性,并创建一个新类型的 bean。 |
从 Spring Framework 6.0 开始,支持 RFC 9457 问题详细信息。
Spring MVC 可以使用application/problem+json
media 类型,例如:
{
"type": "https://example.org/problems/unknown-project",
"title": "Unknown project",
"status": 404,
"detail": "No project found for id 'spring-unknown'",
"instance": "/projects/spring-unknown"
}
可以通过设置spring.mvc.problemdetails.enabled
自true
.
您还可以定义一个带有@ControllerAdvice
自定义 JSON 文档以返回特定控制器和/或异常类型,如以下示例所示:
-
Java
-
Kotlin
import jakarta.servlet.RequestDispatcher;
import jakarta.servlet.http.HttpServletRequest;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.ResponseBody;
import org.springframework.web.servlet.mvc.method.annotation.ResponseEntityExceptionHandler;
@ControllerAdvice(basePackageClasses = SomeController.class)
public class MyControllerAdvice extends ResponseEntityExceptionHandler {
@ResponseBody
@ExceptionHandler(MyException.class)
public ResponseEntity<?> handleControllerException(HttpServletRequest request, Throwable ex) {
HttpStatus status = getStatus(request);
return new ResponseEntity<>(new MyErrorBody(status.value(), ex.getMessage()), status);
}
private HttpStatus getStatus(HttpServletRequest request) {
Integer code = (Integer) request.getAttribute(RequestDispatcher.ERROR_STATUS_CODE);
HttpStatus status = HttpStatus.resolve(code);
return (status != null) ? status : HttpStatus.INTERNAL_SERVER_ERROR;
}
}
import jakarta.servlet.RequestDispatcher
import jakarta.servlet.http.HttpServletRequest
import org.springframework.http.HttpStatus
import org.springframework.http.ResponseEntity
import org.springframework.web.bind.annotation.ControllerAdvice
import org.springframework.web.bind.annotation.ExceptionHandler
import org.springframework.web.bind.annotation.ResponseBody
import org.springframework.web.servlet.mvc.method.annotation.ResponseEntityExceptionHandler
@ControllerAdvice(basePackageClasses = [SomeController::class])
class MyControllerAdvice : ResponseEntityExceptionHandler() {
@ResponseBody
@ExceptionHandler(MyException::class)
fun handleControllerException(request: HttpServletRequest, ex: Throwable): ResponseEntity<*> {
val status = getStatus(request)
return ResponseEntity(MyErrorBody(status.value(), ex.message), status)
}
private fun getStatus(request: HttpServletRequest): HttpStatus {
val code = request.getAttribute(RequestDispatcher.ERROR_STATUS_CODE) as Int
val status = HttpStatus.resolve(code)
return status ?: HttpStatus.INTERNAL_SERVER_ERROR
}
}
在前面的示例中,如果MyException
由定义在SomeController
,则MyErrorBody
使用 POJO 而不是ErrorAttributes
表示法。
在某些情况下,Web 观测或指标基础设施不会记录在控制器级别处理的错误。 应用程序可以通过在观察上下文中设置已处理的异常来确保此类异常与观察一起记录。
自定义错误页面
如果要为给定状态代码显示自定义 HTML 错误页面,可以将文件添加到/error
目录。
错误页面可以是静态 HTML(即,添加到任何静态资源目录下),也可以使用模板构建。
文件名应为确切的状态代码或系列掩码。
例如,要将404
转换为静态 HTML 文件,则您的目录结构将如下所示:
src/
+- main/
+- java/
| + <source code>
+- resources/
+- public/
+- error/
| +- 404.html
+- <other public assets>
要映射所有5xx
错误,则您的目录结构将如下所示:
src/
+- main/
+- java/
| + <source code>
+- resources/
+- templates/
+- error/
| +- 5xx.ftlh
+- <other templates>
对于更复杂的映射,您还可以添加实现ErrorViewResolver
接口,如以下示例所示:
-
Java
-
Kotlin
import java.util.Map;
import jakarta.servlet.http.HttpServletRequest;
import org.springframework.boot.autoconfigure.web.servlet.error.ErrorViewResolver;
import org.springframework.http.HttpStatus;
import org.springframework.web.servlet.ModelAndView;
public class MyErrorViewResolver implements ErrorViewResolver {
@Override
public ModelAndView resolveErrorView(HttpServletRequest request, HttpStatus status, Map<String, Object> model) {
// Use the request or status to optionally return a ModelAndView
if (status == HttpStatus.INSUFFICIENT_STORAGE) {
// We could add custom model values here
new ModelAndView("myview");
}
return null;
}
}
import jakarta.servlet.http.HttpServletRequest
import org.springframework.boot.autoconfigure.web.servlet.error.ErrorViewResolver
import org.springframework.http.HttpStatus
import org.springframework.web.servlet.ModelAndView
class MyErrorViewResolver : ErrorViewResolver {
override fun resolveErrorView(request: HttpServletRequest, status: HttpStatus,
model: Map<String, Any>): ModelAndView? {
// Use the request or status to optionally return a ModelAndView
if (status == HttpStatus.INSUFFICIENT_STORAGE) {
// We could add custom model values here
return ModelAndView("myview")
}
return null
}
}
您还可以使用常规的 Spring MVC 功能,例如@ExceptionHandler
方法和@ControllerAdvice
.
这ErrorController
然后选取任何未经处理的异常。
在 Spring MVC 之外映射错误页面
对于不使用 Spring MVC 的应用程序,您可以使用ErrorPageRegistrar
直接注册的接口ErrorPage
实例。
这种抽象直接与底层嵌入式 servlet 容器一起工作,即使你没有 Spring MVC,也可以工作DispatcherServlet
.
-
Java
-
Kotlin
import org.springframework.boot.web.server.ErrorPage;
import org.springframework.boot.web.server.ErrorPageRegistrar;
import org.springframework.boot.web.server.ErrorPageRegistry;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpStatus;
@Configuration(proxyBeanMethods = false)
public class MyErrorPagesConfiguration {
@Bean
public ErrorPageRegistrar errorPageRegistrar() {
return this::registerErrorPages;
}
private void registerErrorPages(ErrorPageRegistry registry) {
registry.addErrorPages(new ErrorPage(HttpStatus.BAD_REQUEST, "/400"));
}
}
import org.springframework.boot.web.server.ErrorPage
import org.springframework.boot.web.server.ErrorPageRegistrar
import org.springframework.boot.web.server.ErrorPageRegistry
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.http.HttpStatus
@Configuration(proxyBeanMethods = false)
class MyErrorPagesConfiguration {
@Bean
fun errorPageRegistrar(): ErrorPageRegistrar {
return ErrorPageRegistrar { registry: ErrorPageRegistry -> registerErrorPages(registry) }
}
private fun registerErrorPages(registry: ErrorPageRegistry) {
registry.addErrorPages(ErrorPage(HttpStatus.BAD_REQUEST, "/400"))
}
}
如果您注册了ErrorPage 路径最终由Filter (这在一些非 Spring Web 框架中很常见,比如 Jersey 和 Wicket),那么Filter 必须显式注册为ERROR Dispatcher,如以下示例所示: |
-
Java
-
Kotlin
import java.util.EnumSet;
import jakarta.servlet.DispatcherType;
import org.springframework.boot.web.servlet.FilterRegistrationBean;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration(proxyBeanMethods = false)
public class MyFilterConfiguration {
@Bean
public FilterRegistrationBean<MyFilter> myFilter() {
FilterRegistrationBean<MyFilter> registration = new FilterRegistrationBean<>(new MyFilter());
// ...
registration.setDispatcherTypes(EnumSet.allOf(DispatcherType.class));
return registration;
}
}
import jakarta.servlet.DispatcherType
import org.springframework.boot.web.servlet.FilterRegistrationBean
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import java.util.EnumSet
@Configuration(proxyBeanMethods = false)
class MyFilterConfiguration {
@Bean
fun myFilter(): FilterRegistrationBean<MyFilter> {
val registration = FilterRegistrationBean(MyFilter())
// ...
registration.setDispatcherTypes(EnumSet.allOf(DispatcherType::class.java))
return registration
}
}
请注意,默认的FilterRegistrationBean
不包括ERROR
Dispatcher 类型。
WAR 部署中的错误处理
当部署到 servlet 容器时, Spring Boot 使用其错误页面过滤器将具有错误状态的请求转发到相应的错误页面。 这是必需的,因为 servlet 规范没有提供用于注册错误页面的 API。 根据要将 war 文件部署到的容器和应用程序使用的技术,可能需要一些额外的配置。
如果尚未提交响应,则错误页面过滤器只能将请求转发到正确的错误页面。
默认情况下,WebSphere Application Server 8.0 及更高版本在成功完成 servlet 的服务方法后提交响应。
您应该通过设置com.ibm.ws.webcontainer.invokeFlushAfterService
自false
.
CORS 支持
从版本 4.2 开始,Spring MVC 支持 CORS。
使用控制器方法 CORS 配置与@CrossOrigin
Spring Boot 应用程序中的注释不需要任何特定的配置。全局 CORS 配置可以通过注册WebMvcConfigurer
bean 替换为自定义的addCorsMappings(CorsRegistry)
方法,如以下示例所示:
-
Java
-
Kotlin
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.CorsRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
@Configuration(proxyBeanMethods = false)
public class MyCorsConfiguration {
@Bean
public WebMvcConfigurer corsConfigurer() {
return new WebMvcConfigurer() {
@Override
public void addCorsMappings(CorsRegistry registry) {
registry.addMapping("/api/**");
}
};
}
}
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.web.servlet.config.annotation.CorsRegistry
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer
@Configuration(proxyBeanMethods = false)
class MyCorsConfiguration {
@Bean
fun corsConfigurer(): WebMvcConfigurer {
return object : WebMvcConfigurer {
override fun addCorsMappings(registry: CorsRegistry) {
registry.addMapping("/api/**")
}
}
}
}
JAX-RS 和Jersey
如果您更喜欢 REST 端点的 JAX-RS 编程模型,则可以使用其中一个可用的实现,而不是 Spring MVC。Jersey 和 Apache CXF 开箱即用。
CXF 要求您注册其Servlet
或Filter
作为@Bean
在您的应用程序上下文中。
Jersey 有一些原生的 Spring 支持,因此我们还在 Spring Boot 中提供了对它的自动配置支持,以及一个Starters。
要开始使用 Jersey,请包括spring-boot-starter-jersey
作为依赖项,然后您需要一个@Bean
的类型ResourceConfig
,您可以在其中注册所有终端节点,如以下示例所示:
import org.glassfish.jersey.server.ResourceConfig;
import org.springframework.stereotype.Component;
@Component
public class MyJerseyConfig extends ResourceConfig {
public MyJerseyConfig() {
register(MyEndpoint.class);
}
}
Jersey 对扫描可执行档案的支持相当有限。
例如,它无法扫描在完全可执行的 jar 文件或WEB-INF/classes 运行可执行 war 文件时。
为避免此限制,packages 方法,并且应使用register 方法,如前面的示例所示。 |
对于更高级的自定义,您还可以注册任意数量的 bean 来实现ResourceConfigCustomizer
.
所有已注册的端点都应该是一个@Component
使用 HTTP 资源注释 (@GET
和其他),如以下示例所示:
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import org.springframework.stereotype.Component;
@Component
@Path("/hello")
public class MyEndpoint {
@GET
public String message() {
return "Hello";
}
}
由于@Endpoint
是 Spring@Component
,则其生命周期由 Spring 管理,您可以使用@Autowired
注解注入依赖项并使用@Value
注解注入外部配置。
默认情况下,Jersey Servlet 已注册并映射到 。
您可以通过添加/*
@ApplicationPath
发送到您的ResourceConfig
.
默认情况下,Jersey 在@Bean
的类型ServletRegistrationBean
叫jerseyServletRegistration
.
默认情况下,Servlet 是延迟初始化的,但您可以通过设置spring.jersey.servlet.load-on-startup
.
您可以通过创建一个具有相同名称的 bean 来禁用或覆盖该 bean。
您还可以使用过滤器而不是 servlet,方法是将spring.jersey.type=filter
(在这种情况下,@Bean
替换或覆盖是jerseyFilterRegistration
).
该过滤器具有@Order
,您可以使用spring.jersey.filter.order
.
当使用 Jersey 作为过滤器时,必须存在一个 Servlet,该 Servlet 将处理 Jersey 未拦截的任何请求。
如果您的应用程序不包含这样的 Servlet,则可能需要通过设置server.servlet.register-default-servlet
自true
.
Servlet 和过滤器注册都可以通过使用spring.jersey.init.*
以指定属性的映射。
嵌入式 Servlet 容器支持
对于 servlet 应用程序,Spring Boot 包括对嵌入式 Tomcat、Jetty 和 Undertow 服务器的支持。
大多数开发人员使用适当的 starter 来获取完全配置的实例。
默认情况下,嵌入式服务器在端口8080
.
Servlet、过滤器和侦听器
使用嵌入式 servlet 容器时,您可以注册 servlet、过滤器和所有侦听器(例如HttpSessionListener
),通过使用 Spring Bean 或扫描 servlet 组件。
将 Servlet、过滤器和侦听器注册为 Spring Bean
默认情况下,如果上下文仅包含单个 Servlet,则会将其映射到 。
在多个 servlet bean 的情况下,bean 名称用作路径前缀。
筛选器映射到 。/
/*
如果基于约定的映射不够灵活,您可以使用ServletRegistrationBean
,FilterRegistrationBean
和ServletListenerRegistrationBean
类以实现完全控制。
通常,将 filter bean 保持无序状态是安全的。
如果需要特定顺序,则应注释Filter
跟@Order
或使其实现Ordered
.
您无法配置Filter
通过使用@Order
.
如果无法更改Filter
类来添加@Order
或实施Ordered
中,您必须定义一个FilterRegistrationBean
对于Filter
并使用setOrder(int)
方法。
避免配置一个过滤器,该过滤器在Ordered.HIGHEST_PRECEDENCE
,因为它可能违背应用程序的字符编码配置。
如果 servlet 过滤器包装了请求,则应将其配置为小于或等于OrderedFilter.REQUEST_WRAPPER_FILTER_MAX_ORDER
.
注册时要小心Filter bean,因为它们在应用程序生命周期的早期就被初始化了。
如果您需要注册Filter ,请考虑使用DelegatingFilterProxyRegistrationBean 相反。 |
Servlet 上下文初始化
嵌入式 servlet 容器不会直接执行ServletContainerInitializer
interface 或 Spring 的WebApplicationInitializer
接口。
这是一个有意的设计决策,旨在降低设计为在 war 中运行的第三方库可能会破坏 Spring Boot 应用程序的风险。
如果需要在 Spring Boot 应用程序中执行 servlet 上下文初始化,则应注册一个实现ServletContextInitializer
接口。
单onStartup
method 提供对ServletContext
并且,如有必要,可以很容易地用作现有WebApplicationInitializer
.
扫描 Servlet、Filter 和侦听器
使用嵌入式容器时,自动注册带有@WebServlet
,@WebFilter
和@WebListener
可以通过使用@ServletComponentScan
.
@ServletComponentScan 在独立容器中不起作用,其中使用容器的内置发现机制。 |
The ServletWebServerApplicationContext
在后台,Spring Boot 使用不同类型的ApplicationContext
,了解嵌入式 servlet 容器支持。
这ServletWebServerApplicationContext
是一种特殊类型的WebApplicationContext
它通过搜索单个ServletWebServerFactory
豆。
通常为TomcatServletWebServerFactory
,JettyServletWebServerFactory
或UndertowServletWebServerFactory
已自动配置。
您通常不需要了解这些 implementation classes。
大多数应用程序都是自动配置的,并且适当的ApplicationContext 和ServletWebServerFactory 是代表您创建的。 |
在嵌入式容器设置中,ServletContext
设置为服务器启动的一部分,该启动发生在应用程序上下文初始化期间。
由于这个 bean 在ApplicationContext
不能使用ServletContext
.
解决这个问题的一种方法是注射ApplicationContext
作为 Bean 的依赖项,并访问ServletContext
仅在需要时。
另一种方法是在服务器启动后使用回调。
这可以使用ApplicationListener
它监听ApplicationStartedEvent
如下:
import jakarta.servlet.ServletContext;
import org.springframework.boot.context.event.ApplicationStartedEvent;
import org.springframework.context.ApplicationContext;
import org.springframework.context.ApplicationListener;
import org.springframework.web.context.WebApplicationContext;
public class MyDemoBean implements ApplicationListener<ApplicationStartedEvent> {
private ServletContext servletContext;
@Override
public void onApplicationEvent(ApplicationStartedEvent event) {
ApplicationContext applicationContext = event.getApplicationContext();
this.servletContext = ((WebApplicationContext) applicationContext).getServletContext();
}
}
自定义嵌入式 Servlet 容器
可以使用 Spring 配置常见的 servlet 容器设置Environment
性能。
通常,您会在application.properties
或application.yaml
文件。
常见的服务器设置包括:
-
网络设置:传入 HTTP 请求的侦听端口 (
server.port
)、要绑定到的接口地址 (server.address
) 等。 -
Session settings:会话是否持久 (
server.servlet.session.persistent
)、会话超时 (server.servlet.session.timeout
)、会话数据的位置 (server.servlet.session.store-dir
) 和 session-cookie 配置 (server.servlet.session.cookie.*
). -
错误管理:错误页面的位置 (
server.error.path
) 等。
Spring Boot 会尽可能多地公开通用设置,但这并不总是可能的。
对于这些情况,专用命名空间提供特定于服务器的自定义(请参阅server.tomcat
和server.undertow
).
例如,可以使用嵌入式 servlet 容器的特定功能配置访问日志。
请参阅ServerProperties 类以获取完整列表。 |
SameSite Cookie
这SameSite
Web 浏览器可以使用 cookie 属性来控制是否以及如何在跨站点请求中提交 cookie。
该属性与现代 Web 浏览器尤其相关,这些浏览器已开始更改在缺少该属性时使用的默认值。
如果要更改SameSite
属性,您可以使用server.servlet.session.cookie.same-site
财产。
自动配置的 Tomcat、Jetty 和 Undertow 服务器支持此属性。
它还用于配置基于 Spring Session servletSessionRepository
豆。
例如,如果您希望会话 Cookie 具有SameSite
属性None
中,您可以将以下内容添加到application.properties
或application.yaml
文件:
-
Properties
-
YAML
server.servlet.session.cookie.same-site=none
server:
servlet:
session:
cookie:
same-site: "none"
如果要更改SameSite
添加到其他 Cookie 的属性HttpServletResponse
,您可以使用CookieSameSiteSupplier
.
这CookieSameSiteSupplier
将传递一个Cookie
,并且可能会返回SameSite
value 或null
.
您可以使用许多方便的 Factory 和 Filter 方法来快速匹配特定的 Cookie。
例如,添加以下 bean 将自动应用SameSite
之Lax
对于名称与正则表达式匹配的所有 Cookiemyapp.*
.
-
Java
-
Kotlin
import org.springframework.boot.web.servlet.server.CookieSameSiteSupplier;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration(proxyBeanMethods = false)
public class MySameSiteConfiguration {
@Bean
public CookieSameSiteSupplier applicationCookieSameSiteSupplier() {
return CookieSameSiteSupplier.ofLax().whenHasNameMatching("myapp.*");
}
}
import org.springframework.boot.web.servlet.server.CookieSameSiteSupplier
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
@Configuration(proxyBeanMethods = false)
class MySameSiteConfiguration {
@Bean
fun applicationCookieSameSiteSupplier(): CookieSameSiteSupplier {
return CookieSameSiteSupplier.ofLax().whenHasNameMatching("myapp.*")
}
}
字符编码
用于请求和响应处理的嵌入式 servlet 容器的字符编码行为可以使用server.servlet.encoding.*
configuration 属性。
当请求的Accept-Language
header 表示请求的语言环境,它将被 servlet 容器自动映射到字符集。
每个容器都提供 charset 映射的默认区域设置,您应该验证它们是否满足应用程序的需要。
如果它们不这样做,请使用server.servlet.encoding.mapping
configuration 属性来自定义映射,如以下示例所示:
-
Properties
-
YAML
server.servlet.encoding.mapping.ko=UTF-8
server:
servlet:
encoding:
mapping:
ko: "UTF-8"
在前面的示例中,ko
(韩语) locale 已映射到UTF-8
.
这相当于<locale-encoding-mapping-list>
条目web.xml
文件。
编程自定义
如果需要以编程方式配置嵌入式 servlet 容器,可以注册一个实现WebServerFactoryCustomizer
接口。WebServerFactoryCustomizer
提供对ConfigurableServletWebServerFactory
,其中包括许多自定义 setter 方法。
以下示例显示了以编程方式设置端口:
-
Java
-
Kotlin
import org.springframework.boot.web.server.WebServerFactoryCustomizer;
import org.springframework.boot.web.servlet.server.ConfigurableServletWebServerFactory;
import org.springframework.stereotype.Component;
@Component
public class MyWebServerFactoryCustomizer implements WebServerFactoryCustomizer<ConfigurableServletWebServerFactory> {
@Override
public void customize(ConfigurableServletWebServerFactory server) {
server.setPort(9000);
}
}
import org.springframework.boot.web.server.WebServerFactoryCustomizer
import org.springframework.boot.web.servlet.server.ConfigurableServletWebServerFactory
import org.springframework.stereotype.Component
@Component
class MyWebServerFactoryCustomizer : WebServerFactoryCustomizer<ConfigurableServletWebServerFactory> {
override fun customize(server: ConfigurableServletWebServerFactory) {
server.setPort(9000)
}
}
TomcatServletWebServerFactory
,JettyServletWebServerFactory
和UndertowServletWebServerFactory
是 的专用变体ConfigurableServletWebServerFactory
分别具有 Tomcat、Jetty 和 Undertow 的其他自定义 setter 方法。
以下示例显示如何自定义TomcatServletWebServerFactory
,提供对特定于 Tomcat 的配置选项的访问:
-
Java
-
Kotlin
import java.time.Duration;
import org.springframework.boot.web.embedded.tomcat.TomcatServletWebServerFactory;
import org.springframework.boot.web.server.WebServerFactoryCustomizer;
import org.springframework.stereotype.Component;
@Component
public class MyTomcatWebServerFactoryCustomizer implements WebServerFactoryCustomizer<TomcatServletWebServerFactory> {
@Override
public void customize(TomcatServletWebServerFactory server) {
server.addConnectorCustomizers((connector) -> connector.setAsyncTimeout(Duration.ofSeconds(20).toMillis()));
}
}
import org.springframework.boot.web.embedded.tomcat.TomcatServletWebServerFactory
import org.springframework.boot.web.server.WebServerFactoryCustomizer
import org.springframework.stereotype.Component
import java.time.Duration
@Component
class MyTomcatWebServerFactoryCustomizer : WebServerFactoryCustomizer<TomcatServletWebServerFactory> {
override fun customize(server: TomcatServletWebServerFactory) {
server.addConnectorCustomizers({ connector -> connector.asyncTimeout = Duration.ofSeconds(20).toMillis() })
}
}
直接自定义ConfigurableServletWebServerFactory
对于需要您从ServletWebServerFactory
,您可以自己公开此类 bean。
为许多配置选项提供了 setter。
如果你需要做一些更奇特的事情,还提供了几个受保护的方法 “钩子”。
请参阅ConfigurableServletWebServerFactory
API 文档了解详细信息。
自动配置的定制器仍应用于您的自定义工厂,因此请谨慎使用该选项。 |