对于最新的稳定版本,请使用 Spring Boot 3.5.5spring-doc.cadn.net.cn

Servlet Web 应用程序

如果您想构建基于 servlet 的 Web 应用程序,您可以利用 Spring Boot 对 Spring MVC 或 Jersey 的自动配置。spring-doc.cadn.net.cn

“Spring Web MVC 框架”

Spring Web MVC 框架(通常称为“Spring MVC”)是一个丰富的“模型视图控制器”Web 框架。 Spring MVC 允许您创建特殊的@Controller@RestControllerbean 来处理传入的 HTTP 请求。 控制器中的方法通过使用@RequestMapping附注。spring-doc.cadn.net.cn

以下代码显示了典型的@RestController提供 JSON 数据:spring-doc.cadn.net.cn

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”是功能变体,将路由配置与请求的实际处理分开,如以下示例所示:spring-doc.cadn.net.cn

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)
	}

}
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 的指南。spring-doc.cadn.net.cn

您可以定义任意数量的RouterFunctionbeans 来模块化路由器的定义。 如果需要应用优先级,可以订购 Bean。

Spring MVC 自动配置

Spring Boot 为 Spring MVC 提供了自动配置,适用于大多数应用程序。 它取代了对@EnableWebMvc并且两者不能一起使用。 除了 Spring MVC 的默认值外,自动配置还提供以下功能:spring-doc.cadn.net.cn

如果您想保留这些 Spring Boot MVC 自定义并进行更多 MVC 自定义(拦截器、格式化程序、视图控制器和其他功能),您可以添加自己的@Configuration类型类WebMvcConfigurer没有 @EnableWebMvc.spring-doc.cadn.net.cn

如果要提供RequestMappingHandlerMapping,RequestMappingHandlerAdapterExceptionHandlerExceptionResolver,并且仍然保留 Spring Boot MVC 自定义,您可以声明类型为WebMvcRegistrations并使用它来提供这些组件的自定义实例。 自定义实例将由 Spring MVC 进一步初始化和配置。 要参与并根据需要覆盖该后续处理,请WebMvcConfigurer应该使用。spring-doc.cadn.net.cn

如果您不想使用自动配置并希望完全控制 Spring MVC,请添加您自己的@Configuration注释为@EnableWebMvc. 或者,添加您自己的@Configuration-注释DelegatingWebMvcConfiguration@EnableWebMvcAPI 文档。spring-doc.cadn.net.cn

Spring MVC 转换服务

Spring MVC 使用不同的ConversionService转换为用于将值从application.propertiesapplication.yaml文件。 这意味着Period,DurationDataSize转换器不可用,并且@DurationUnit@DataSizeUnit注释将被忽略。spring-doc.cadn.net.cn

如果要自定义ConversionServiceSpring MVC 使用时,你可以提供一个WebMvcConfigurer带有addFormatters方法。 通过此方法,您可以注册任何您喜欢的转换器,也可以委托给ApplicationConversionService.spring-doc.cadn.net.cn

也可以使用spring.mvc.format.*配置属性。 如果未配置,则使用以下默认值:spring-doc.cadn.net.cn

属性 DateTimeFormatter 格式

spring.mvc.format.datespring-doc.cadn.net.cn

ofLocalizedDate(FormatStyle.SHORT)spring-doc.cadn.net.cn

java.util.DateLocalDatespring-doc.cadn.net.cn

spring.mvc.format.timespring-doc.cadn.net.cn

ofLocalizedTime(FormatStyle.SHORT)spring-doc.cadn.net.cn

java.time 的LocalTimeOffsetTimespring-doc.cadn.net.cn

spring.mvc.format.date-timespring-doc.cadn.net.cn

ofLocalizedDateTime(FormatStyle.SHORT)spring-doc.cadn.net.cn

java.time 的LocalDateTime,OffsetDateTimeZonedDateTimespring-doc.cadn.net.cn

HttpMessage转换器

Spring MVC 使用HttpMessageConverter接口来转换 HTTP 请求和响应。 合理的默认值是开箱即用的。 例如,对象可以自动转换为 JSON(使用 Jackson 库)或 XML(如果可用,则使用 Jackson XML 扩展,或者使用 JAXB(如果 Jackson XML 扩展不可用)。 默认情况下,字符串编码为UTF-8.spring-doc.cadn.net.cn

任何HttpMessageConverter上下文中存在的 bean 将添加到转换器列表中。 您也可以以相同的方式覆盖默认转换器。spring-doc.cadn.net.cn

如果您需要添加或自定义转换器,可以使用 Spring Boot 的HttpMessageConverters类,如以下列表所示:spring-doc.cadn.net.cn

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)
	}

}

为了进一步控制,您还可以将子类HttpMessageConverters并覆盖其postProcessConverters和/或postProcessPartConverters方法。 当您想要重新排序或删除 Spring MVC 默认配置的某些转换器时,这会很有用。spring-doc.cadn.net.cn

MessageCodes解析器

Spring MVC 有一个策略用于生成错误代码,用于从绑定错误中呈现错误消息:MessageCodesResolver. 如果您将spring.mvc.message-codes-resolver-format属性PREFIX_ERROR_CODEPOSTFIX_ERROR_CODE,Spring Boot 会为您创建一个(请参阅DefaultMessageCodesResolver.Format).spring-doc.cadn.net.cn

静态内容

默认情况下,Spring Boot 从名为/static(或/public/resources/META-INF/resources) 或从ServletContext. 它使用ResourceHttpRequestHandlerSpring MVC 中的 Spring MVC,以便您可以通过添加自己的行为来修改该行为WebMvcConfigurer并覆盖addResourceHandlers方法。spring-doc.cadn.net.cn

在独立 Web 应用程序中,未启用容器中的缺省 servlet。 可以使用server.servlet.register-default-servlet财产。spring-doc.cadn.net.cn

默认 servlet 充当后备,从ServletContext如果 Spring 决定不处理它。 大多数时候,这不会发生(除非您修改默认的 MVC 配置),因为 Spring 始终可以通过DispatcherServlet.spring-doc.cadn.net.cn

默认情况下,资源映射在 上,但您可以使用/**spring.mvc.static-path-pattern财产。 例如,将所有资源重新定位到/resources/**可以按如下方式实现:spring-doc.cadn.net.cn

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

您还可以使用spring.web.resources.static-locations属性(将默认值替换为目录位置列表)。 根 servlet 上下文路径 也会自动添加为位置。"/"spring-doc.cadn.net.cn

除了前面提到的“标准”静态资源位置之外,Webjars 内容还出现了一个特殊情况。 默认情况下,路径为/webjars/**如果 jar 文件以 Webjars 格式打包,则从 jar 文件提供。 可以使用spring.mvc.webjars-path-pattern财产。spring-doc.cadn.net.cn

不要使用src/main/webapp目录,如果您的应用程序打包为 jar。 虽然这个目录是一个通用标准,但它适用于战争打包,如果你生成一个 jar,它会被大多数构建工具静默地忽略。

Spring Boot 还支持 Spring MVC 提供的高级资源处理功能,允许缓存破坏静态资源或对 Webjar 使用与版本无关的 URL 等用例。spring-doc.cadn.net.cn

要对 Webjar 使用与版本无关的 URL,请将org.webjars:webjars-locator-liteDependency。 然后声明您的 Webjar。 以 jQuery 为例,添加"/webjars/jquery/jquery.min.js"结果"/webjars/jquery/x.y.z/jquery.min.js"哪里x.y.z是 Webjar 版本。spring-doc.cadn.net.cn

要使用缓存破坏,以下配置为所有静态资源配置缓存破坏解决方案,有效地添加内容哈希,例如<link href="/css/spring-2a2d595e6ed9a0b24f027f2b63b134d6.css"/>,在 URL 中:spring-doc.cadn.net.cn

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 模块加载器动态加载资源时,无法选择重命名文件。 这就是为什么其他策略也受到支持并且可以组合的原因。 “固定”策略在 URL 中添加静态版本字符串,而不更改文件名,如以下示例所示:spring-doc.cadn.net.cn

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"/>).spring-doc.cadn.net.cn

WebProperties.Resources以获取更多支持的选项。spring-doc.cadn.net.cn

此功能已在专门的博客文章和 Spring Framework 的参考文档中进行了详尽的描述。spring-doc.cadn.net.cn

欢迎页面

Spring Boot 支持静态和模板化欢迎页面。 它首先查找index.html文件。 如果未找到,则查找index模板。 如果找到其中任何一个,则会自动将其用作应用程序的欢迎页面。spring-doc.cadn.net.cn

这仅充当应用程序定义的实际索引路由的回退。 排序由HandlerMappingbean,默认如下:spring-doc.cadn.net.cn

RouterFunctionMappingspring-doc.cadn.net.cn

使用RouterFunctionspring-doc.cadn.net.cn

RequestMappingHandlerMappingspring-doc.cadn.net.cn

在 中声明的端点@Controllerspring-doc.cadn.net.cn

WelcomePageHandlerMappingspring-doc.cadn.net.cn

欢迎页面支持spring-doc.cadn.net.cn

自定义网站图标

与其他静态资源一样,Spring Boot 会检查favicon.ico在配置的静态内容位置。 如果存在这样的文件,它会自动用作应用程序的网站图标。spring-doc.cadn.net.cn

路径匹配和内容协商

Spring MVC 可以通过查看请求路径并将其与应用程序中定义的映射(例如,@GetMappingController 方法上的注释)。spring-doc.cadn.net.cn

Spring Boot 选择默认禁用后缀模式匹配,这意味着像"GET /projects/spring-boot.json"将不匹配@GetMapping("/projects/spring-boot")映射。 这被认为是 Spring MVC 应用程序的最佳实践。 此功能在过去主要用于未发送正确“Accept”请求标头的 HTTP 客户端;我们需要确保向客户端发送正确的内容类型。 如今,内容协商更加可靠。spring-doc.cadn.net.cn

还有其他方法可以处理无法始终发送正确“Accept”请求标头的 HTTP 客户端。 我们可以使用查询参数来确保像"GET /projects/spring-boot?format=json"将映射到@GetMapping("/projects/spring-boot"):spring-doc.cadn.net.cn

spring.mvc.contentnegotiation.favor-parameter=true
spring:
  mvc:
    contentnegotiation:
      favor-parameter: true

或者,如果您更喜欢使用其他参数名称:spring-doc.cadn.net.cn

spring.mvc.contentnegotiation.favor-parameter=true
spring.mvc.contentnegotiation.parameter-name=myparam
spring:
  mvc:
    contentnegotiation:
      favor-parameter: true
      parameter-name: "myparam"

大多数标准媒体类型都受支持,但您也可以定义新的媒体类型:spring-doc.cadn.net.cn

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-doc.cadn.net.cn

可以使用spring.mvc.pathmatch.matching-strategyconfiguration 属性,如以下示例所示:spring-doc.cadn.net.cn

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-mappingsfalse以完全禁用静态内容的投放。spring-doc.cadn.net.cn

可配置的WebBinding初始化器

Spring MVC 使用WebBindingInitializer初始化WebDataBinder对于特定请求。 如果您创建自己的ConfigurableWebBindingInitializer @Bean,Spring Boot 会自动配置 Spring MVC 以使用它。spring-doc.cadn.net.cn

模板引擎

除了 REST Web 服务,您还可以使用 Spring MVC 来提供动态 HTML 内容。 Spring MVC 支持多种模板技术,包括 Thymeleaf、FreeMarker 和 JSP。 此外,许多其他模板引擎也包含自己的 Spring MVC 集成。spring-doc.cadn.net.cn

Spring Boot 包括对以下模板引擎的自动配置支持:spring-doc.cadn.net.cn

如果可能,应避免使用 JSP。 将它们与嵌入式 servlet 容器一起使用时,有几个已知的限制

当您将这些模板引擎之一与默认配置一起使用时,您的模板会自动从src/main/resources/templates.spring-doc.cadn.net.cn

根据您运行应用程序的方式,您的 IDE 可能会对类路径进行不同的排序。 在 IDE 中从其 main 方法运行应用程序会导致与使用 Maven 或 Gradle 或从其打包的 jar 运行应用程序时不同的顺序。 这可能导致 Spring Boot 无法找到预期的模板。 如果遇到此问题,可以在 IDE 中重新排序类路径,以将模块的类和资源放在第一位。

错误处理

默认情况下,Spring Boot 提供了一个/error映射,以合理的方式处理所有错误,并在 Servlet 容器中注册为“全局”错误页面。 对于机器客户端,它会生成一个 JSON 响应,其中包含错误、HTTP 状态和异常消息的详细信息。 对于浏览器客户端,有一个“白标”错误视图,它以 HTML 格式呈现相同的数据(要对其进行自定义,请添加一个View解析为error).spring-doc.cadn.net.cn

有许多server.error如果要自定义默认错误处理行为,可以设置属性。 请参阅附录的服务器属性部分。spring-doc.cadn.net.cn

要完全替换默认行为,您可以实现ErrorController并注册该类型的 Bean 定义或添加类型为ErrorAttributes使用现有机制,但替换内容。spring-doc.cadn.net.cn

BasicErrorController可用作自定义ErrorController. 如果要为新内容类型添加处理程序,这特别有用(默认值是text/html特别是为其他所有内容提供后备)。 为此,请扩展BasicErrorController,添加一个带有@RequestMapping有一个produces属性,然后创建一个新类型的 bean。

从 Spring Framework 6.0 开始,支持 RFC 9457 问题详细信息。 Spring MVC 可以使用application/problem+json媒体类型,例如:spring-doc.cadn.net.cn

{
	"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.enabledtrue.spring-doc.cadn.net.cn

您还可以定义一个用@ControllerAdvice自定义要为特定控制器和/或异常类型返回的 JSON 文档,如以下示例所示:spring-doc.cadn.net.cn

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,的 JSON 表示形式MyErrorBodyPOJO 而不是ErrorAttributes表示法。spring-doc.cadn.net.cn

在某些情况下,在控制器级别处理的错误不会由 Web 观察或指标基础结构记录。应用程序可以通过在观察上下文上设置已处理的异常来确保将此类异常记录在观察中。spring-doc.cadn.net.cn

自定义错误页面

如果要显示给定状态代码的自定义 HTML 错误页面,可以将文件添加到/error目录。 错误页面可以是静态 HTML(即,添加到任何静态资源目录下),也可以使用模板构建。 文件名应为确切的状态代码或系列掩码。spring-doc.cadn.net.cn

例如,要映射404到静态 HTML 文件,您的目录结构如下所示:spring-doc.cadn.net.cn

src/
 +- main/
     +- java/
     |   + <source code>
     +- resources/
         +- public/
             +- error/
             |   +- 404.html
             +- <other public assets>

要映射所有5xx错误,则目录结构如下:spring-doc.cadn.net.cn

src/
 +- main/
     +- java/
     |   + <source code>
     +- resources/
         +- templates/
             +- error/
             |   +- 5xx.ftlh
             +- <other templates>

对于更复杂的映射,您还可以添加实现ErrorViewResolver接口,如以下示例所示:spring-doc.cadn.net.cn

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-doc.cadn.net.cn

在 Spring MVC 之外映射错误页面

对于不使用 Spring MVC 的应用程序,您可以使用ErrorPageRegistrar直接注册的接口ErrorPage实例。 此抽象直接与底层嵌入式 servlet 容器一起使用,即使您没有 Spring MVC 也可以工作DispatcherServlet.spring-doc.cadn.net.cn

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必须显式注册为ERRORdispatcher,如以下示例所示:
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调度程序类型。spring-doc.cadn.net.cn

WAR 部署中的错误处理

当部署到 servlet 容器时,Spring Boot 使用其错误页面过滤器将具有错误状态的请求转发到相应的错误页面。 这是必要的,因为 servlet 规范不提供用于注册错误页面的 API。 根据要将 war 文件部署到的容器和应用程序使用的技术,可能需要一些额外的配置。spring-doc.cadn.net.cn

如果响应尚未提交,错误页过滤器只能将请求转发到正确的错误页。 缺省情况下,WebSphere Application Server 8.0 及更高版本在成功完成 servlet 的服务方法后提交响应。 您应该通过设置com.ibm.ws.webcontainer.invokeFlushAfterServicefalse.spring-doc.cadn.net.cn

CORS 支持

跨域资源共享 (CORS) 是大多数浏览器实现的 W3C 规范,它允许您以灵活的方式指定授权的跨域请求类型,而不是使用一些不太安全且功能较弱的方法,例如 IFRAME 或 JSONP。spring-doc.cadn.net.cn

从版本 4.2 开始,Spring MVC 支持 CORS。 使用控制器方法 CORS 配置@CrossOriginSpring Boot 应用程序中的注释不需要任何特定配置。全局 CORS 配置可以通过注册WebMvcConfigurer带有定制的 beanaddCorsMappings(CorsRegistry)方法,如以下示例所示:spring-doc.cadn.net.cn

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

如果您更喜欢 JAX-RS 编程模型作为 REST 端点,则可以使用可用的实现之一而不是 Spring MVC。JerseyApache CXF 开箱即用。 CXF 要求您注册其ServletFilter作为@Bean在您的应用程序上下文中。 Jersey 有一些原生 Spring 支持,因此我们还在 Spring Boot 中为它提供了自动配置支持,以及一个Starters。spring-doc.cadn.net.cn

要开始使用 Jersey,请包含spring-boot-starter-jersey作为依赖项,然后你需要一个@Bean类型ResourceConfig在其中注册所有终结点,如以下示例所示:spring-doc.cadn.net.cn

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.spring-doc.cadn.net.cn

所有注册的端点都应是@Component使用 HTTP 资源注释 (@GET等),如以下示例所示:spring-doc.cadn.net.cn

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.spring-doc.cadn.net.cn

默认情况下,Jersey 被设置为@Bean类型ServletRegistrationBeanjerseyServletRegistration. 默认情况下,servlet 是延迟初始化的,但您可以通过将spring.jersey.servlet.load-on-startup. 您可以通过创建自己的一个具有相同名称的 Bean 来禁用或覆盖该 Bean。 您还可以通过将spring.jersey.type=filter(在这种情况下,@Bean替换或覆盖是jerseyFilterRegistration). 过滤器有一个@Order,您可以将其设置为spring.jersey.filter.order. 使用 Jersey 作为过滤器时,必须存在一个 servlet,该 servlet 将处理 Jersey 未拦截的任何请求。 如果您的应用程序不包含这样的 servlet,您可能希望通过设置server.servlet.register-default-servlettrue. servlet 和过滤器注册都可以通过使用spring.jersey.init.*以指定属性映射。spring-doc.cadn.net.cn

嵌入式 Servlet 容器支持

对于 servlet 应用程序,Spring Boot 包括对嵌入式 TomcatJettyUndertow 服务器的支持。 大多数开发人员使用适当的Starters来获取完全配置的实例。 默认情况下,嵌入式服务器在端口上侦听 HTTP 请求8080.spring-doc.cadn.net.cn

Servlet、过滤器和侦听器

使用嵌入式 servlet 容器时,您可以注册 servlet、过滤器和所有侦听器(例如HttpSessionListener)来自 Servlet 规范,通过使用 Spring Bean 或扫描 servlet 组件。spring-doc.cadn.net.cn

将 Servlet、过滤器和侦听器注册为 Spring Bean

任何Servlet,Filter或 Servlet*Listener实例,即 Spring bean 已向嵌入式容器注册。 如果您想引用application.properties在配置期间。spring-doc.cadn.net.cn

默认情况下,如果上下文仅包含单个 Servlet,则将其映射到 。 对于多个 Servlet Bean,Bean 名称用作路径前缀。 筛选器映射到 。//*spring-doc.cadn.net.cn

如果基于约定的映射不够灵活,您可以使用ServletRegistrationBean,FilterRegistrationBeanServletListenerRegistrationBean完全控制的类。spring-doc.cadn.net.cn

过滤豆不订购通常是安全的。 如果需要特定顺序,则应将Filter@Order或者让它实现Ordered. 您无法配置Filter通过使用@Order. 如果您无法更改Filter要添加的类@Order或实现Ordered,则必须定义一个FilterRegistrationBean对于Filter并使用setOrder(int)方法。 避免配置读取请求正文的筛选器Ordered.HIGHEST_PRECEDENCE,因为它可能与应用程序的字符编码配置相悖。 如果 servlet 过滤器包装请求,则应将其配置为小于或等于OrderedFilter.REQUEST_WRAPPER_FILTER_MAX_ORDER.spring-doc.cadn.net.cn

要查看每个Filter在您的应用程序中,为web 日志记录组 (logging.level.web=debug). 然后,将在启动时记录已注册过滤器的详细信息,包括其顺序和 URL 模式。
注册时请注意Filterbean,因为它们在应用程序生命周期的早期就初始化了。如果您需要注册一个Filter与其他 bean 交互的 bean,请考虑使用DelegatingFilterProxyRegistrationBean相反。

Servlet 上下文初始化

嵌入式 servlet 容器不直接执行ServletContainerInitializer接口或 Spring 的WebApplicationInitializer接口。 这是一个有意的设计决策,旨在降低设计用于在战争中运行的第三方库可能破坏 Spring Boot 应用程序的风险。spring-doc.cadn.net.cn

如果您需要在 Spring Boot 应用程序中执行 servlet 上下文初始化,则应注册一个实现ServletContextInitializer接口。 单onStartup方法提供对ServletContext如有必要,可以轻松用作现有WebApplicationInitializer.spring-doc.cadn.net.cn

扫描 Servlet、过滤器和侦听器

使用嵌入式容器时,自动注册带有@WebServlet,@WebFilter@WebListener可以通过使用@ServletComponentScan.spring-doc.cadn.net.cn

@ServletComponentScan在独立容器中没有影响,其中使用容器的内置发现机制。

The ServletWebServerApplicationContext

在引擎盖下,Spring Boot 使用了不同类型的ApplicationContext用于嵌入式 servlet 容器支持。 这ServletWebServerApplicationContext是一种特殊类型的WebApplicationContext通过搜索单个ServletWebServerFactory豆。 通常TomcatServletWebServerFactory,JettyServletWebServerFactoryUndertowServletWebServerFactory已自动配置。spring-doc.cadn.net.cn

您通常不需要了解这些实现类。 大多数应用程序都是自动配置的,并且适当的ApplicationContextServletWebServerFactory是代表您创建的。

在嵌入式容器设置中,ServletContext设置为在应用程序上下文初始化期间发生的服务器启动的一部分。 因为这个豆子在ApplicationContext无法使用ServletContext. 解决此问题的一种方法是注入ApplicationContext作为 bean 的依赖项,并访问ServletContext只有在需要的时候。 另一种方法是在服务器启动后使用回调。 这可以使用ApplicationListener它监听ApplicationStartedEvent如下:spring-doc.cadn.net.cn

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.propertiesapplication.yaml文件。spring-doc.cadn.net.cn

常见的服务器设置包括:spring-doc.cadn.net.cn

Spring Boot 尽可能多地公开常见设置,但这并不总是可行的。 对于这些情况,专用命名空间提供特定于服务器的自定义(请参阅server.tomcatserver.undertow). 例如,可以使用嵌入式 servlet 容器的特定功能来配置访问日志spring-doc.cadn.net.cn

请参阅ServerPropertiesclass 获取完整列表。

SameSite Cookie

SameSiteCookie 属性可供 Web 浏览器使用,以控制是否以及如何在跨站点请求中提交 Cookie。 该属性与现代 Web 浏览器特别相关,这些浏览器已开始更改缺少该属性时使用的默认值。spring-doc.cadn.net.cn

如果要更改SameSite属性,您可以使用server.servlet.session.cookie.same-site财产。 自动配置的 Tomcat、Jetty 和 Undertow 服务器支持此属性。 它还用于配置基于 Spring Session servletSessionRepository豆。spring-doc.cadn.net.cn

例如,如果您希望会话 cookie 具有SameSite属性None,您可以将以下内容添加到您的application.propertiesapplication.yaml文件:spring-doc.cadn.net.cn

server.servlet.session.cookie.same-site=none
server:
  servlet:
    session:
      cookie:
        same-site: "none"

如果要更改SameSite属性添加到您的HttpServletResponse,您可以使用CookieSameSiteSupplier. 这CookieSameSiteSupplier被传递一个Cookie并可能返回一个SameSite值,或null.spring-doc.cadn.net.cn

您可以使用许多便利的工厂和过滤方法来快速匹配特定 Cookie。 例如,添加以下 bean 将自动应用SameSiteLax对于名称与正则表达式匹配的所有 cookiemyapp.*.spring-doc.cadn.net.cn

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.*配置属性。spring-doc.cadn.net.cn

当请求的Accept-Languageheader 表示请求的语言环境,它将由 servlet 容器自动映射到字符集。 每个容器都提供默认区域设置到字符集映射,您应该验证它们是否满足应用程序的需求。 如果不这样做,请使用server.servlet.encoding.mappingconfiguration 属性来自定义映射,如以下示例所示:spring-doc.cadn.net.cn

server.servlet.encoding.mapping.ko=UTF-8
server:
  servlet:
    encoding:
      mapping:
        ko: "UTF-8"

在前面的示例中,ko(韩语)区域设置已映射到UTF-8. 这相当于<locale-encoding-mapping-list>web.xml传统战争部署的文件。spring-doc.cadn.net.cn

程序化定制

如果您需要以编程方式配置嵌入式 servlet 容器,您可以注册一个实现WebServerFactoryCustomizer接口。WebServerFactoryCustomizer提供对ConfigurableServletWebServerFactory,其中包括许多自定义 setter 方法。 以下示例演示以编程方式设置端口:spring-doc.cadn.net.cn

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,JettyServletWebServerFactoryUndertowServletWebServerFactoryConfigurableServletWebServerFactory分别为 Tomcat、Jetty 和 Undertow 具有额外的自定义 setter 方法。 以下示例演示如何自定义TomcatServletWebServerFactory提供对特定于 Tomcat 的配置选项的访问:spring-doc.cadn.net.cn

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。spring-doc.cadn.net.cn

为许多配置选项提供了 setter。 如果您需要做一些更奇特的事情,还提供了几个受保护的方法“钩子”。 请参阅ConfigurableServletWebServerFactory有关详细信息,请参阅 API 文档。spring-doc.cadn.net.cn

自动配置的定制器仍应用于自定义工厂,因此请谨慎使用该选项。

JSP 限制

当运行使用嵌入式 servlet 容器(并打包为可执行存档)的 Spring Boot 应用程序时,JSP 支持存在一些限制。spring-doc.cadn.net.cn