Servlet Web Applications

如果要构建基于 servlet 的 Web 应用程序，则可以利用 Spring Boot 对 Spring MVC 或 Jersey 的自动配置功能。

If you want to build servlet-based web applications, you can take advantage of Spring Boot’s auto-configuration for Spring MVC or Jersey.

The “Spring Web MVC Framework”

{url-spring-framework-docs}/web/webmvc.html[Spring Web MVC 框架]（通常称为 “Spring MVC”）是一个丰富的 "`model view controller`"Web 框架。Spring MVC 允许你创建特殊的 `@Controller`或 `@RestController`bean 来处理传入的 HTTP 请求。控制器中的方法通过使用 `@RequestMapping`注释映射到 HTTP。

The {url-spring-framework-docs}/web/webmvc.html[Spring Web MVC framework] (often referred to as “Spring MVC”) is a rich “model view controller” web framework. Spring MVC lets you create special @Controller or @RestController beans to handle incoming HTTP requests. Methods in your controller are mapped to HTTP by using @RequestMapping annotations.

以下代码显示了一个提供 JSON 数据的典型 @RestController：

The following code shows a typical @RestController that serves JSON data:

“WebMvc.fn”，函数变量将路由配置从请求的实际处理中分离，如下例所示：

“WebMvc.fn”, the functional variant, separates the routing configuration from the actual handling of the requests, as shown in the following example:

Spring MVC 是核心 Spring 框架的一部分，详细信息可以在 {url-spring-framework-docs}/web/webmvc.html[参考文档]中找到。另外，还有几个指南涵盖 Spring MVC，可在 [role="bare"][role="bare"]https://spring.io/guides中找到。

Spring MVC is part of the core Spring Framework, and detailed information is available in the {url-spring-framework-docs}/web/webmvc.html[reference documentation]. There are also several guides that cover Spring MVC available at [role="bare"]https://spring.io/guides.

你可以根据需要定义任意数量的 `RouterFunction`bean 来模块化路由器的定义。如果需要应用优先级，可以对 bean 进行排序。

You can define as many RouterFunction beans as you like to modularize the definition of the router. Beans can be ordered if you need to apply a precedence.

Spring MVC Auto-configuration

Spring Boot 为 Spring MVC 提供的自动配置适用于大多数应用程序。它取代了 `@EnableWebMvc`的需求，两者不能一起使用。除了 Spring MVC 的默认值之外，自动配置还提供以下功能：

Spring Boot provides auto-configuration for Spring MVC that works well with most applications. It replaces the need for @EnableWebMvc and the two cannot be used together. In addition to Spring MVC’s defaults, the auto-configuration provides the following features:

  • Inclusion of ContentNegotiatingViewResolver and BeanNameViewResolver beans.

  • Support for serving static resources, including support for WebJars (covered later in this document).

  • Automatic registration of Converter, GenericConverter, and Formatter beans.

  • Support for HttpMessageConverters (covered later in this document).

  • Automatic registration of MessageCodesResolver (covered later in this document).

  • Static index.html support.

  • Automatic use of a ConfigurableWebBindingInitializer bean (covered later in this document).

如果您希望保留这些 Spring Boot MVC 自定义，并进行更多 {url-spring-framework-docs}/web/webmvc.html[MVC 自定义]（拦截器、格式化程序、视图控制器以及其他功能），则可以添加自己的 @Configuration 类，类型为 WebMvcConfigurer，但 without @EnableWebMvc。

If you want to keep those Spring Boot MVC customizations and make more {url-spring-framework-docs}/web/webmvc.html[MVC customizations] (interceptors, formatters, view controllers, and other features), you can add your own @Configuration class of type WebMvcConfigurer but without @EnableWebMvc.

如果您希望提供 RequestMappingHandlerMapping、RequestMappingHandlerAdapter 或 ExceptionHandlerExceptionResolver 的自定义实例，但仍保留 Spring Boot MVC 自定义，则可以声明一个 WebMvcRegistrations 类型的 bean，并使用它来提供这些组件的自定义实例。这些自定义实例将受到 Spring MVC 的进一步初始化和配置。为了参与，并且在需要时覆盖后续处理过程，应该使用 WebMvcConfigurer。

If you want to provide custom instances of RequestMappingHandlerMapping, RequestMappingHandlerAdapter, or ExceptionHandlerExceptionResolver, and still keep the Spring Boot MVC customizations, you can declare a bean of type WebMvcRegistrations and use it to provide custom instances of those components. The custom instances will be subject to further initialization and configuration by Spring MVC. To participate in, and if desired, override that subsequent processing, a WebMvcConfigurer should be used.

如果您不想使用自动配置，并且希望完全控制 Spring MVC，请添加您自己的 @Configuration，其中带 @EnableWebMvc 注释。或者，按照 @EnableWebMvc 的 Javadoc 中所述，添加自己的 @Configuration 注释的 DelegatingWebMvcConfiguration。

If you do not want to use the auto-configuration and want to take complete control of Spring MVC, add your own @Configuration annotated with @EnableWebMvc. Alternatively, add your own @Configuration-annotated DelegatingWebMvcConfiguration as described in the Javadoc of @EnableWebMvc.

Spring MVC Conversion Service

Spring MVC 使用的 ConversionService 与从 application.properties 或 application.yaml 文件转换值所使用的 ConversionService 不同。这意味着 Period、Duration 和 DataSize 转换器不可用，并且 @DurationUnit 和 @DataSizeUnit 注释将被忽略。

Spring MVC uses a different ConversionService to the one used to convert values from your application.properties or application.yaml file. It means that Period, Duration and DataSize converters are not available and that @DurationUnit and @DataSizeUnit annotations will be ignored.

如果您希望自定义 Spring MVC 所使用的 ConversionService，则可以提供一个包含 addFormatters 方法的 WebMvcConfigurer bean。您可以通过此方法注册您喜欢使用的任何转换器，或者可以委托 ApplicationConversionService 上提供的静态方法。

If you want to customize the ConversionService used by Spring MVC, you can provide a WebMvcConfigurer bean with an addFormatters method. From this method you can register any converter that you like, or you can delegate to the static methods available on ApplicationConversionService.

还可以使用 spring.mvc.format.* 配置属性自定义转换。未配置时会使用以下默认值：

Conversion can also be customized using the spring.mvc.format.* configuration properties. When not configured, the following defaults are used:

Property DateTimeFormatter

configprop:spring.mvc.format.date[]

ofLocalizedDate(FormatStyle.SHORT)

configprop:spring.mvc.format.time[]

ofLocalizedTime(FormatStyle.SHORT)

configprop:spring.mvc.format.date-time[]

ofLocalizedDateTime(FormatStyle.SHORT)

HttpMessageConverters

Spring MVC 使用 HttpMessageConverter 接口转换 HTTP 请求和响应。默认情况下会包含明智的默认值。例如，可以自动将对象转换为 JSON（使用 Jackson 库）或 XML（如果可用，请使用 Jackson XML 扩展，如果 Jackson XML 扩展不可用，则使用 JAXB）。默认情况下，字符串会以 UTF-8 进行编码。

Spring MVC uses the HttpMessageConverter interface to convert HTTP requests and responses. Sensible defaults are included out of the box. For example, objects can be automatically converted to JSON (by using the Jackson library) or XML (by using the Jackson XML extension, if available, or by using JAXB if the Jackson XML extension is not available). By default, strings are encoded in UTF-8.

如果您需要添加或自定义转换器，则可以使用 Spring Boot 的 HttpMessageConverters 类，如下面的清单所示：

If you need to add or customize converters, you can use Spring Boot’s HttpMessageConverters class, as shown in the following listing:

上下文中的所有 HttpMessageConverter bean 都被添加到转换器列表中。你还可以通过相同的方式覆盖默认转换器。

Any HttpMessageConverter bean that is present in the context is added to the list of converters. You can also override default converters in the same way.

MessageCodesResolver

Spring MVC 有一个生成错误代码的策略，用于根据绑定错误呈现错误消息：MessageCodesResolver。如果你设置了 configprop:spring.mvc.message-codes-resolver-format[] 属性 PREFIX_ERROR_CODE 或 POSTFIX_ERROR_CODE，Spring Boot 会为你创建一个（请参见枚举： {url-spring-framework-javadoc}/org/springframework/validation/DefaultMessageCodesResolver.Format.html[DefaultMessageCodesResolver.Format]）。

Spring MVC has a strategy for generating error codes for rendering error messages from binding errors: MessageCodesResolver. If you set the configprop:spring.mvc.message-codes-resolver-format[] property PREFIX_ERROR_CODE or POSTFIX_ERROR_CODE, Spring Boot creates one for you (see the enumeration in {url-spring-framework-javadoc}/org/springframework/validation/DefaultMessageCodesResolver.Format.html[DefaultMessageCodesResolver.Format]).

Static Content

默认情况下，Spring Boot 从类路径的 /static 目录（或 /public 或 /resources 或 /META-INF/resources）或 ServletContext 的根目录提供静态内容。它使用 Spring MVC 的 ResourceHttpRequestHandler，以便你可以通过添加自己的 WebMvcConfigurer 并覆盖 addResourceHandlers 方法来修改该行为。

By default, Spring Boot serves static content from a directory called /static (or /public or /resources or /META-INF/resources) in the classpath or from the root of the ServletContext. It uses the ResourceHttpRequestHandler from Spring MVC so that you can modify that behavior by adding your own WebMvcConfigurer and overriding the addResourceHandlers method.

在独立网络应用程序中，来自容器的默认 servlet 没有启用。可以使用 configprop:server.servlet.register-default-servlet[] 属性启用它。

In a stand-alone web application, the default servlet from the container is not enabled. It can be enabled using the configprop:server.servlet.register-default-servlet[] property.

默认 servlet 作为备用，如果 Spring 决定不处理 ServletContext 中根目录的内容，则它会处理这些内容。这是不常发生的（除非你修改了默认 MVC 配置），因为 Spring 始终可以通过 DispatcherServlet 处理请求。

The default servlet acts as a fallback, serving content from the root of the ServletContext if Spring decides not to handle it. Most of the time, this does not happen (unless you modify the default MVC configuration), because Spring can always handle requests through the DispatcherServlet.

默认情况下，按以下方式映射 /, but you can tune that with the configprop:spring.mvc.static-path-pattern[] property. For instance, relocating all resources to /resources/ 上的资源：

By default, resources are mapped on /, but you can tune that with the configprop:spring.mvc.static-path-pattern[] property. For instance, relocating all resources to /resources/ can be achieved as follows:

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

您还可以使用 configprop:spring.web.resources.static-locations[] 属性自定义静态资源位置（用目录位置列表替换默认值）。根 Servlet 上下文路径 "/" 也自动添加为一个位置。

You can also customize the static resource locations by using the configprop:spring.web.resources.static-locations[] property (replacing the default values with a list of directory locations). The root servlet context path, "/", is automatically added as a location as well.

除先前提到的 “standard” 静态资源位置外，还对 Webjars content 做了一个特殊情况。默认情况下，/webjars/** 中路径的任何资源都在打包成 Webjars 格式时从 JAR 文件中提供。该路径可以 configprop:spring.mvc.webjars-path-pattern[] 属性进行自定义。

In addition to the “standard” static resource locations mentioned earlier, a special case is made for Webjars content. By default, any resources with a path in /webjars/** are served from jar files if they are packaged in the Webjars format. The path can be customized with the configprop:spring.mvc.webjars-path-pattern[] property.

如果您的应用程序打包成 JAR，请不要使用 src/main/webapp 目录。尽管此目录是一个通用标准，但它与战时包装配合使用时可以 only，并且如果您生成 JAR，大多数构建工具会默默忽略它。

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 it is silently ignored by most build tools if you generate a jar.

Spring Boot 还支持 Spring MVC 提供的高级资源处理功能，允许使用案例，例如缓存破坏静态资源或使用与版本无关的 URL 进行 Webjars。

Spring Boot also supports the advanced resource handling features provided by Spring MVC, allowing use cases such as cache-busting static resources or using version agnostic URLs for Webjars.

若要使用与版本无关的 Webjars URL，请添加 webjars-locator-core 依赖项。然后声明您的 Webjar。以 jQuery 为例，添加 "/webjars/jquery/jquery.min.js" 会生成 "/webjars/jquery/x.y.z/jquery.min.js"，其中 x.y.z 是 Webjar 版本。

To use version agnostic URLs for Webjars, add the webjars-locator-core dependency. Then declare your Webjar. Using jQuery as an example, adding "/webjars/jquery/jquery.min.js" results in "/webjars/jquery/x.y.z/jquery.min.js" where x.y.z is the Webjar version.

如果您使用 JBoss，则需要声明 webjars-locator-jboss-vfs 依赖项，而不是 webjars-locator-core。否则，所有 Webjars 会解析为 404。

If you use JBoss, you need to declare the webjars-locator-jboss-vfs dependency instead of the webjars-locator-core. Otherwise, all Webjars resolve as a 404.

若要使用缓存破坏，以下配置为所有静态资源配置了一个缓存破坏解决方案，有效地在 URL 中添加了一个内容散列值，例如 <link href="/css/spring-2a2d595e6ed9a0b24f027f2b63b134d6.css"/>：

To use cache busting, the following configuration configures a cache busting solution for all static resources, effectively adding a content hash, such as <link href="/css/spring-2a2d595e6ed9a0b24f027f2b63b134d6.css"/>, in URLs:

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

由于为 Thymeleaf 和 FreeMarker 自动配置了 ResourceUrlEncodingFilter，因此运行时在模板中重写了对资源的链接。在使用 JSP 时，您应手动声明此过滤器。其他模板引擎目前未自动支持，但可以使用自定义模板宏/帮助器和 {url-spring-framework-javadoc}/org/springframework/web/servlet/resource/ResourceUrlProvider.html[ResourceUrlProvider]。

Links to resources are rewritten in templates at runtime, thanks to a ResourceUrlEncodingFilter that is auto-configured for Thymeleaf and FreeMarker. You should manually declare this filter when using JSPs. Other template engines are currently not automatically supported but can be with custom template macros/helpers and the use of the {url-spring-framework-javadoc}/org/springframework/web/servlet/resource/ResourceUrlProvider.html[ResourceUrlProvider].

例如，通过 JavaScript 模块加载器动态加载资源时，重命名文件不是一个选择。因此，也支持并可以结合其他策略。如以下示例所示，“固定”策略在不更改文件名的情况下在 URL 中添加一个静态版本字符串：

When loading resources dynamically with, for example, a JavaScript module loader, renaming files is not an option. That is why other strategies are also supported and can be combined. A "fixed" strategy adds a static version string in the URL without changing the file name, as shown in the following example:

spring:
  web:
    resources:
      chain:
        strategy:
          content:
            enabled: true
            paths: "/**"
          fixed:
            enabled: true
            paths: "/js/lib/"
            version: "v12"

通过此配置，位于 "/js/lib/" 下的 JavaScript 模块使用固定版本策略 ("/v12/js/lib/mymodule.js")，而其他资源仍使用内容版本策略 (<link href="/css/spring-2a2d595e6ed9a0b24f027f2b63b134d6.css"/>)。

With this configuration, JavaScript modules located under "/js/lib/" use a fixed versioning strategy ("/v12/js/lib/mymodule.js"), while other resources still use the content one (<link href="/css/spring-2a2d595e6ed9a0b24f027f2b63b134d6.css"/>).

请参阅 {code-spring-boot-autoconfigure-src}/web/WebProperties.java[WebProperties.Resources] 以了解更多受支持的选项。

See {code-spring-boot-autoconfigure-src}/web/WebProperties.java[WebProperties.Resources] for more supported options.

此功能已在一个专用的 blog post 和 Spring Framework 的 {url-spring-framework-docs}/web/webmvc/mvc-config/static-resources.html[参考文档] 中得到彻底说明。

This feature has been thoroughly described in a dedicated blog post and in Spring Framework’s {url-spring-framework-docs}/web/webmvc/mvc-config/static-resources.html[reference documentation].

Welcome Page

Spring Boot 支持静态欢迎页面和模板化欢迎页面。它首先在配置的静态内容位置中查找一个 index.html 文件。如果没有找到，它会查找一个 index 模板。如果找到任一个，则它会自动用作应用程序的欢迎页面。

Spring Boot supports both static and templated welcome pages. It first looks for an index.html file in the configured static content locations. If one is not found, it then looks for an index template. If either is found, it is automatically used as the welcome page of the application.

这只是一个适用于应用程序定义的实际索引路由的回退。排序是由 HandlerMapping bean 的顺序定义的，默认情况下如下：

This only acts as a fallback for actual index routes defined by the application. The ordering is defined by the order of HandlerMapping beans which is by default the following:

RouterFunctionMapping

Endpoints declared with RouterFunction beans

RequestMappingHandlerMapping

Endpoints declared in @Controller beans

WelcomePageHandlerMapping

The welcome page support

Custom Favicon

与其他静态资源一样，Spring Boot 在配置的静态内容位置中检查 favicon.ico。如果存在这样的文件，则自动用作应用程序的 favicon。

As with other static resources, Spring Boot checks for a favicon.ico in the configured static content locations. If such a file is present, it is automatically used as the favicon of the application.

Path Matching and Content Negotiation

Spring MVC 可以通过查看请求路径并将其与应用程序中定义的映射匹配来将传入的 HTTP 请求映射到处理程序（例如，Controller 方法上的 @GetMapping 注释）。

Spring MVC can map incoming HTTP requests to handlers by looking at the request path and matching it to the mappings defined in your application (for example, @GetMapping annotations on Controller methods).

Spring Boot 默认情况下选择禁用后缀模式匹配，这意味着像 "GET /projects/spring-boot.json" 这样的请求将不会匹配到 @GetMapping("/projects/spring-boot") 映射。这被认为是 Spring MVC 应用程序的最佳实践。此功能过去主要用于不发送适当“Accept”请求标头的 HTTP 客户端；我们需要确保向客户端发送正确的 Content Type。如今，内容协商可靠得多。

Spring Boot chooses to disable suffix pattern matching by default, which means that requests like "GET /projects/spring-boot.json" will not be matched to @GetMapping("/projects/spring-boot") mappings. This is considered as a {url-spring-framework-docs}/web/webmvc/mvc-controller/ann-requestmapping.html#mvc-ann-requestmapping-suffix-pattern-match[best practice for Spring MVC applications]. This feature was mainly useful in the past for HTTP clients which did not send proper "Accept" request headers; we needed to make sure to send the correct Content Type to the client. Nowadays, Content Negotiation is much more reliable.

还有其他方法可以处理始终发送适当的“Accept”请求标头的问题。我们可以使用查询参数，确保像 "GET /projects/spring-boot?format=json" 这样的请求将映射到 @GetMapping("/projects/spring-boot")，而不是使用后缀匹配：

There are other ways to deal with HTTP clients that do not consistently send proper "Accept" request headers. Instead of using suffix matching, we can use a query parameter to ensure that requests like "GET /projects/spring-boot?format=json" will be mapped to @GetMapping("/projects/spring-boot"):

spring:
  mvc:
    contentnegotiation:
      favor-parameter: true

或者如果你希望使用不同的参数名称：

Or if you prefer to use a different parameter name:

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

大多数标准媒体类型都开箱即用，但你也可以定义新的媒体类型：

Most standard media types are supported out-of-the-box, but you can also define new ones:

spring:
  mvc:
    contentnegotiation:
      media-types:
        markdown: "text/markdown"

从 Spring Framework 5.3 开始，Spring MVC 支持使用两种策略将请求路径匹配到控制器。默认情况下，Spring Boot 使用 PathPatternParser 策略。PathPatternParser 是一种 optimized implementation，但与 AntPathMatcher 策略相比有一定限制。PathPatternParser 限制了 {url-spring-framework-docs}/web/webmvc/mvc-controller/ann-requestmapping.html#mvc-ann-requestmapping-uri-templates[某些路径模式变体]。它也不兼容将 DispatcherServlet 配置有路径前缀（configprop:spring.mvc.servlet.path[]）。

As of Spring Framework 5.3, Spring MVC supports two strategies for matching request paths to controllers. By default, Spring Boot uses the PathPatternParser strategy. PathPatternParser is an optimized implementation but comes with some restrictions compared to the AntPathMatcher strategy. PathPatternParser restricts usage of {url-spring-framework-docs}/web/webmvc/mvc-controller/ann-requestmapping.html#mvc-ann-requestmapping-uri-templates[some path pattern variants]. It is also incompatible with configuring the DispatcherServlet with a path prefix (configprop:spring.mvc.servlet.path[]).

可以使用 configprop:spring.mvc.pathmatch.matching-strategy[] 配置属性对该策略进行配置，如下例所示：

The strategy can be configured using the configprop:spring.mvc.pathmatch.matching-strategy[] configuration property, as shown in the following example:

spring:
  mvc:
    pathmatch:
      matching-strategy: "ant-path-matcher"

默认情况下，如果为请求找不到处理程序，Spring MVC 将发送 404 Not Found 错误响应。要改为抛出 NoHandlerFoundException，将 configprop:spring.mvc.throw-exception-if-no-handler-found 设置为 true。请注意，默认情况下，serving of static content 映射到 / and will, therefore, provide a handler for all requests. For a NoHandlerFoundException to be thrown, you must also set configprop:spring.mvc.static-path-pattern[] to a more specific value such as /resources/，或者将 configprop:spring.web.resources.add-mappings[] 设置为 false 以完全禁用提供静态内容。

By default, Spring MVC will send a 404 Not Found error response if a handler is not found for a request. To have a NoHandlerFoundException thrown instead, set configprop:spring.mvc.throw-exception-if-no-handler-found to true. Note that, by default, the serving of static content is mapped to / and will, therefore, provide a handler for all requests. For a NoHandlerFoundException to be thrown, you must also set configprop:spring.mvc.static-path-pattern[] to a more specific value such as /resources/ or set configprop:spring.web.resources.add-mappings[] to false to disable serving of static content entirely.

ConfigurableWebBindingInitializer

Spring MVC 使用 WebBindingInitializer 为特定请求初始化 WebDataBinder。如果你创建了自己的 ConfigurableWebBindingInitializer @Bean，Spring Boot 会自动配置 Spring MVC 以使用它。

Spring MVC uses a WebBindingInitializer to initialize a WebDataBinder for a particular request. If you create your own ConfigurableWebBindingInitializer @Bean, Spring Boot automatically configures Spring MVC to use it.

Template Engines

除了 REST Web 服务，你还可以使用 Spring MVC 来提供动态 HTML 内容。Spring MVC 支持各种模板技术，包括 Thymeleaf、FreeMarker 和 JSP。此外，许多其他模版引擎还包括自己的 Spring MVC 集成。

As well as REST web services, you can also use Spring MVC to serve dynamic HTML content. Spring MVC supports a variety of templating technologies, including Thymeleaf, FreeMarker, and JSPs. Also, many other templating engines include their own Spring MVC integrations.

Spring Boot 包含以下模板引擎的自动配置支持：

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

如果可能，应避免使用 JSP。在内嵌 Servlet 容器中使用它们时，会有一些 known limitations。

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

当使用默认配置将其中一个模板引擎与之一起使用时，会从 src/main/resources/templates 中自动获取模板。

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

应用程序的运行方式不同，IDE 对类路径的排序方式也不同。从主方法在 IDE 中运行应用程序，其排序方式与使用 Maven 或 Gradle 或从已打包 jar 中运行应用程序的排序方式不同。这可能会导致 Spring Boot 无法找到预期的模板。如果你遇到此问题，则可以重新排序 IDE 中的类路径，以首先放置模块的类和资源。

Depending on how you run your application, your IDE may order the classpath differently. Running your application in the IDE from its main method results in a different ordering than when you run your application by using Maven or Gradle or from its packaged jar. This can cause Spring Boot to fail to find the expected template. If you have this problem, you can reorder the classpath in the IDE to place the module’s classes and resources first.

Error Handling

Spring Boot 默认情况下，提供一个以合理的方式处理所有错误的 /error 映射，并且在 Servlet 容器中注册为 “global” 错误页面。对于机器客户端，它会生成一个 JSON 响应，其中包含错误详细信息、HTTP 状态和异常消息。对于浏览器客户端，有一个 “whitelabel” 错误视图，以 HTML 格式呈现相同的数据（要自定义它，请添加一个解析到 error 的 View）。

By default, Spring Boot provides an /error mapping that handles all errors in a sensible way, and it is registered as a “global” error page in the servlet container. For machine clients, it produces a JSON response with details of the error, the HTTP status, and the exception message. For browser clients, there is a “whitelabel” error view that renders the same data in HTML format (to customize it, add a View that resolves to error).

如果你希望自定义默认的错误处理行为，可以设置许多 server.error 属性。请参阅附录的 “Server Properties” 部分。

There are a number of server.error properties that can be set if you want to customize the default error handling behavior. See the “Server Properties” section of the Appendix.

要完全替换默认行为，可以实现 ErrorController，并注册该类型的 bean 定义，或者添加类型为 ErrorAttributes 的 bean，以使用现有机制，但替换其内容。

To replace the default behavior completely, you can implement ErrorController and register a bean definition of that type or add a bean of type ErrorAttributes to use the existing mechanism but replace the contents.

BasicErrorController 可以用作自定义 ErrorController 的基类。如果你要为新内容类型添加一个处理程序，这尤其有用（默认情况下专门处理 text/html，并为其他所有内容提供后备）。为此，请扩展 BasicErrorController，添加一个公用方法 @RequestMapping，该方法具有 produces 属性，并创建新类型的 bean。

The BasicErrorController can be used as a base class for a custom ErrorController. This is particularly useful if you want to add a handler for a new content type (the default is to handle text/html specifically and provide a fallback for everything else). To do so, extend BasicErrorController, add a public method with a @RequestMapping that has a produces attribute, and create a bean of your new type.

从 Spring Framework 6.0 开始，支持 {url-spring-framework-docs}/web/webmvc/mvc-ann-rest-exceptions.html[RFC 7807 问题详细信息]。Spring MVC 可以生成带有 application/problem+json 媒体类型自定义错误消息，例如：

As of Spring Framework 6.0, {url-spring-framework-docs}/web/webmvc/mvc-ann-rest-exceptions.html[RFC 7807 Problem Details] is supported. Spring MVC can produce custom error messages with the application/problem+json media type, like:

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

可以通过将 configprop:spring.mvc.problemdetails.enabled[] 设置为 true 来启用此支持。

This support can be enabled by setting configprop:spring.mvc.problemdetails.enabled[] to true.

你还可以定义使用 `@ControllerAdvice`注释的类，以自定义对于特定控制器和/或异常类型返回的 JSON 文档，如下例所示：

You can also define a class annotated with @ControllerAdvice to customize the JSON document to return for a particular controller and/or exception type, as shown in the following example:

在前面的示例中，如果 MyException 由与 SomeController 相同包中定义的控制器抛出，则使用 MyErrorBody POJO 的 JSON 表示形式，而不是 ErrorAttributes 表示形式。

In the preceding example, if MyException is thrown by a controller defined in the same package as SomeController, a JSON representation of the MyErrorBody POJO is used instead of the ErrorAttributes representation.

在某些情况下，在控制器级别处理的错误并未由 Web 观察或 metrics infrastructure 记录。应用程序可以通过 {url-spring-framework-docs}/integration/observability.html#observability.http-server.servlet[在观察上下文上设置处理的异常] 来确保用观察记录此类异常。

In some cases, errors handled at the controller level are not recorded by web observations or the metrics infrastructure. Applications can ensure that such exceptions are recorded with the observations by {url-spring-framework-docs}/integration/observability.html#observability.http-server.servlet[setting the handled exception on the observation context].

Custom Error Pages

如果要为给定状态代码显示自定义 HTML 错误页面，可以在 /error 目录中添加文件。错误页面可以是静态 HTML（也就是说，在任意静态资源目录中添加），也可以使用模板构建。文件名称应该为确切的状态代码或序列掩码。

If you want to display a custom HTML error page for a given status code, you can add a file to an /error directory. Error pages can either be static HTML (that is, added under any of the static resource directories) or be built by using templates. The name of the file should be the exact status code or a series mask.

例如，要将 404 映射到静态 HTML 文件，你的目录结构如下：

For example, to map 404 to a static HTML file, your directory structure would be as follows:

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

要使用 FreeMarker 模板映射所有 5xx 错误，你的目录结构如下：

To map all 5xx errors by using a FreeMarker template, your directory structure would be as follows:

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

对于更复杂的映射，你还可以添加实现 ErrorViewResolver 接口的 bean，如下例所示：

For more complex mappings, you can also add beans that implement the ErrorViewResolver interface, as shown in the following example:

你还可以使用常规 Spring MVC 功能，如 {url-spring-framework-docs}/web/webmvc/mvc-servlet/exceptionhandlers.html[@ExceptionHandler 方法] 和 {url-spring-framework-docs}/web/webmvc/mvc-controller/ann-advice.html[@ControllerAdvice]。然后，ErrorController 将获取任何未处理的异常。

You can also use regular Spring MVC features such as {url-spring-framework-docs}/web/webmvc/mvc-servlet/exceptionhandlers.html[@ExceptionHandler methods] and {url-spring-framework-docs}/web/webmvc/mvc-controller/ann-advice.html[@ControllerAdvice]. The ErrorController then picks up any unhandled exceptions.

Mapping Error Pages Outside of Spring MVC

对于不使用 Spring MVC 的应用程序，你可以使用 ErrorPageRegistrar 接口来直接注册 ErrorPages. 此抽象直接处理底层嵌入式 servlet 容器，即使没有 Spring MVC DispatcherServlet 也可以处理。

For applications that do not use Spring MVC, you can use the ErrorPageRegistrar interface to directly register ErrorPages. This abstraction works directly with the underlying embedded servlet container and works even if you do not have a Spring MVC DispatcherServlet.

如果你注册的 ErrorPage 的路径最终由 Filter 处理（这在一些非 Spring Web 框架中很常见，如 Jersey 和 Wicket），则必须明确地将 Filter 注册为 ERROR 调度程序，如下例所示：

If you register an ErrorPage with a path that ends up being handled by a Filter (as is common with some non-Spring web frameworks, like Jersey and Wicket), then the Filter has to be explicitly registered as an ERROR dispatcher, as shown in the following example:

注意，默认 FilterRegistrationBean 不包括 ERROR 调度程序类型。

Note that the default FilterRegistrationBean does not include the ERROR dispatcher type.

Error Handling in a WAR Deployment

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

When deployed to a servlet container, Spring Boot uses its error page filter to forward a request with an error status to the appropriate error page. This is necessary as the servlet specification does not provide an API for registering error pages. Depending on the container that you are deploying your war file to and the technologies that your application uses, some additional configuration may be required.

错误页面过滤器仅在响应尚未提交时才能将请求转发到正确的错误页面。默认情况下，WebSphere Application Server 8.0 及更高版本在 servlet 的 service 方法成功完成后提交响应。你应通过将 com.ibm.ws.webcontainer.invokeFlushAfterService 设置为 false，来禁用此行为。

The error page filter can only forward the request to the correct error page if the response has not already been committed. By default, WebSphere Application Server 8.0 and later commits the response upon successful completion of a servlet’s service method. You should disable this behavior by setting com.ibm.ws.webcontainer.invokeFlushAfterService to false.

CORS Support

Cross-origin resource sharing （CORS）是 W3C specification 实施的 most browsers，它让你能够灵活地指定允许哪些类型的跨域请求，而不是使用一些不那么安全且功能较弱的方法，如 IFRAME 或 JSONP。

Cross-origin resource sharing (CORS) is a W3C specification implemented by most browsers that lets you specify in a flexible way what kind of cross-domain requests are authorized, instead of using some less secure and less powerful approaches such as IFRAME or JSONP.

从 4.2 版本开始，Spring MVC {url-spring-framework-docs}/web/webmvc-cors.html[支持 CORS]。在你的 Spring Boot 应用程序中使用 {url-spring-framework-docs}/web/webmvc-cors.html#mvc-cors-controller[Controller 方法 CORS 配置] 来使用带有 {url-spring-framework-javadoc}/org/springframework/web/bind/annotation/CrossOrigin.html[@CrossOrigin] 注释，无需任何特定配置。{url-spring-framework-docs}/web/webmvc-cors.html#mvc-cors-global[全局 CORS 配置] 可以通过注册带有自定义 addCorsMappings(CorsRegistry) 方法的 WebMvcConfigurer bean 来定义，如下例所示：

As of version 4.2, Spring MVC {url-spring-framework-docs}/web/webmvc-cors.html[supports CORS]. Using {url-spring-framework-docs}/web/webmvc-cors.html#mvc-cors-controller[controller method CORS configuration] with {url-spring-framework-javadoc}/org/springframework/web/bind/annotation/CrossOrigin.html[@CrossOrigin] annotations in your Spring Boot application does not require any specific configuration. {url-spring-framework-docs}/web/webmvc-cors.html#mvc-cors-global[Global CORS configuration] can be defined by registering a WebMvcConfigurer bean with a customized addCorsMappings(CorsRegistry) method, as shown in the following example:

JAX-RS and Jersey

如果您更喜欢针对 REST 终结点使用 JAX-RS 编程模型，您可以使用一种可用的实现来代替 Spring MVC. Jersey和 Apache CXF开箱即用非常出色。CXF 要求您在应用程序上下文中将 Servlet`或 `Filter`注册为 `@Bean。Jersey 拥有部分原生 Spring 支持，因此我们也为它提供了 Spring Boot 中的自动配置支持，以及一个 starter。

If you prefer the JAX-RS programming model for REST endpoints, you can use one of the available implementations instead of Spring MVC. Jersey and Apache CXF work quite well out of the box. CXF requires you to register its Servlet or Filter as a @Bean in your application context. Jersey has some native Spring support, so we also provide auto-configuration support for it in Spring Boot, together with a starter.

要开始使用 Jersey，请包含 `spring-boot-starter-jersey`作为依赖项，然后您需要一个类型为 `ResourceConfig`的 `@Bean`来注册所有终结点，如下例所示：

To get started with Jersey, include the spring-boot-starter-jersey as a dependency and then you need one @Bean of type ResourceConfig in which you register all the endpoints, as shown in the following example:

Jersey 对可执行存档的扫描支持はかなり限定。例如，在运行一个可执行 war 文件时，它不能扫描一个 fully executable jar file或 `WEB-INF/classes`中包的终结点。要避免这种限制，不应使用 `packages`方法，而应使用 `register`方法单独注册终结点，如下例所示：

Jersey’s support for scanning executable archives is rather limited. For example, it cannot scan for endpoints in a package found in a fully executable jar file or in WEB-INF/classes when running an executable war file. To avoid this limitation, the packages method should not be used, and endpoints should be registered individually by using the register method, as shown in the preceding example.

对于更高级别的自定义，您还可以注册任意数量实现 `ResourceConfigCustomizer`的 bean。

For more advanced customizations, you can also register an arbitrary number of beans that implement ResourceConfigCustomizer.

所有已注册的终结点都应使用 HTTP 资源注释（@GET`等）加上 `@Components，如下例所示：

All the registered endpoints should be @Components with HTTP resource annotations (@GET and others), as shown in the following example:

由于 Endpoint`是一个 Spring `@Component，它的生命周期由 Spring 管理，并且您可以使用 @Autowired`注释来注入依赖项，以及使用 `@Value`注释来注入外部配置。默认情况下，Jersey servlet 会被注册并映射到 `/*。您可以通过添加 `@ApplicationPath`到您的 `ResourceConfig`来更改映射。

Since the Endpoint is a Spring @Component, its lifecycle is managed by Spring and you can use the @Autowired annotation to inject dependencies and use the @Value annotation to inject external configuration. By default, the Jersey servlet is registered and mapped to /*. You can change the mapping by adding @ApplicationPath to your ResourceConfig.

默认情况下，Jersey 会被设置为 ServletRegistrationBean`类型为 `jerseyServletRegistration`的 `@Bean`中的一个 servlet。默认情况下，该 servlet 会被延迟初始化，但您可以通过设置 `spring.jersey.servlet.load-on-startup`来自定义该行为。您可以通过创建一个具有相同名称自己的 bean 来禁用或覆盖该 bean。您也可以通过设置 `spring.jersey.type=filter（在这种情况下，要替换或覆盖的 @Bean`是 `jerseyFilterRegistration）来使用 filter 而非 servlet。该 filter 具有一个 @Order，您可以使用 `spring.jersey.filter.order`设置该属性。在将 Jersey 用作 filter 时，必须有一个将处理 Jersey 无拦截的任何请求的 servlet。如果您的应用程序不包含这样的 servlet，您可能要通过将 configprop:server.servlet.register-default-servlet[] 设置为 `true`来启用默认 servlet。可以通过使用 `spring.jersey.init.*`来指定一个属性 map 为 servlet 和 filter 注册提供初始化参数。

By default, Jersey is set up as a servlet in a @Bean of type ServletRegistrationBean named jerseyServletRegistration. By default, the servlet is initialized lazily, but you can customize that behavior by setting spring.jersey.servlet.load-on-startup. You can disable or override that bean by creating one of your own with the same name. You can also use a filter instead of a servlet by setting spring.jersey.type=filter (in which case, the @Bean to replace or override is jerseyFilterRegistration). The filter has an @Order, which you can set with spring.jersey.filter.order. When using Jersey as a filter, a servlet that will handle any requests that are not intercepted by Jersey must be present. If your application does not contain such a servlet, you may want to enable the default servlet by setting configprop:server.servlet.register-default-servlet[] to true. Both the servlet and the filter registrations can be given init parameters by using spring.jersey.init.* to specify a map of properties.

Embedded Servlet Container Support

对于 servlet 应用程序，Spring Boot 包括对嵌入 Tomcat、 Jetty和 Undertow服务器的支持。大多数开发人员使用合适的 "`Starter`"来获取一个完全配置的实例。默认情况下，嵌入服务器监听端口 `8080`上的 HTTP 请求。

For servlet application, Spring Boot includes support for embedded Tomcat, Jetty, and Undertow servers. Most developers use the appropriate “Starter” to obtain a fully configured instance. By default, the embedded server listens for HTTP requests on port 8080.

Servlets, Filters, and Listeners

在使用嵌入 servlet 容器时，您可以使用 Spring bean 或通过扫描 servlet 组件来注册 servlet、filter 和所有来自 servlet 规格的侦听器（例如 HttpSessionListener）。

When using an embedded servlet container, you can register servlets, filters, and all the listeners (such as HttpSessionListener) from the servlet spec, either by using Spring beans or by scanning for servlet components.

Registering Servlets, Filters, and Listeners as Spring Beans

任何是 Spring bean 的 Servlet、`Filter`或 servlet `*Listener`实例都会在嵌入容器中注册。如果您希望在配置期间引用来自您的 `application.properties`中的值，这可以特别方便。

Any Servlet, Filter, or servlet *Listener instance that is a Spring bean is registered with the embedded container. This can be particularly convenient if you want to refer to a value from your application.properties during configuration.

默认情况下，如果上下文只包含一个 Servlet，它会被映射到 /。对于多个 servlet bean 的情况，bean 名称被用作路径前缀。Filter 映射到 /*。

By default, if the context contains only a single Servlet, it is mapped to /. In the case of multiple servlet beans, the bean name is used as a path prefix. Filters map to /*.

如果基于约定的映射不够灵活，您可以使用 ServletRegistrationBean、`FilterRegistrationBean`和 `ServletListenerRegistrationBean`类进行完全控制。

If convention-based mapping is not flexible enough, you can use the ServletRegistrationBean, FilterRegistrationBean, and ServletListenerRegistrationBean classes for complete control.

通常情况下，保持 filter bean 无序是安全的。如果需要特定顺序，您应该通过 @Order`注释 `Filter，或使其实现 Ordered。您无法通过使用 @Order`注释其 bean 方法来配置 `Filter`的顺序。如果您无法更改 `Filter`类来添加 `@Order`或实现 `Ordered，您必须为 Filter`定义一个 `FilterRegistrationBean，并使用 `setOrder(int)`方法设置注册 bean 的顺序。避免配置读取 `Ordered.HIGHEST_PRECEDENCE`的请求正文的 filter，因为它可能会违背您的应用程序的字符编码配置。如果一个 servlet filter 封装请求，它应被配置为一个小于或等于 `OrderedFilter.REQUEST_WRAPPER_FILTER_MAX_ORDER`的顺序。

It is usually safe to leave filter beans unordered. If a specific order is required, you should annotate the Filter with @Order or make it implement Ordered. You cannot configure the order of a Filter by annotating its bean method with @Order. If you cannot change the Filter class to add @Order or implement Ordered, you must define a FilterRegistrationBean for the Filter and set the registration bean’s order using the setOrder(int) method. Avoid configuring a filter that reads the request body at Ordered.HIGHEST_PRECEDENCE, since it might go against the character encoding configuration of your application. If a servlet filter wraps the request, it should be configured with an order that is less than or equal to OrderedFilter.REQUEST_WRAPPER_FILTER_MAX_ORDER.

要查看您应用程序中每个 Filter`的顺序，请为 logging group(`logging.level.web=debug) 的 `web`启用调试级别日志。然后将在启动时记录已注册 filter 的详细信息，包括其顺序和 URL 模式。

To see the order of every Filter in your application, enable debug level logging for the web logging group (logging.level.web=debug). Details of the registered filters, including their order and URL patterns, will then be logged at startup.

在注册 Filter`bean 时要小心，因为它们在应用程序生命周期中很早就被初始化了。如果您需要注册一个与其他 bean 交互的 `Filter，请考虑使用 DelegatingFilterProxyRegistrationBean代替它。

Take care when registering Filter beans since they are initialized very early in the application lifecycle. If you need to register a Filter that interacts with other beans, consider using a DelegatingFilterProxyRegistrationBean instead.

Servlet Context Initialization

嵌入的 servlet 容器不会直接执行 `jakarta.servlet.ServletContainerInitializer`接口或者 Spring 的 `org.springframework.web.WebApplicationInitializer`接口。这是一个有意的设计决策，旨在降低为了在 war 中运行而设计的三方库可能破坏 Spring Boot 应用程序的风险。

Embedded servlet containers do not directly execute the jakarta.servlet.ServletContainerInitializer interface or Spring’s org.springframework.web.WebApplicationInitializer interface. This is an intentional design decision intended to reduce the risk that third party libraries designed to run inside a war may break Spring Boot applications.

如果你需要在一个 Spring Boot 应用程序中执行 servlet 的上下文初始化，就需要注册实现 org.springframework.boot.web.servlet.ServletContextInitializer 接口的 bean。单独的 onStartup 方法提供访问 ServletContext 的权限，并且有必要的时候，可以轻松用作一个已有的 WebApplicationInitializer 的适配器。

If you need to perform servlet context initialization in a Spring Boot application, you should register a bean that implements the org.springframework.boot.web.servlet.ServletContextInitializer interface. The single onStartup method provides access to the ServletContext and, if necessary, can easily be used as an adapter to an existing WebApplicationInitializer.

Scanning for Servlets, Filters, and listeners

当使用一个嵌入式容器时，可以通过使用 @ServletComponentScan 来启用带有注释 @WebServlet、@WebFilter 和 @WebListener 标记的类的自动注册。

When using an embedded container, automatic registration of classes annotated with @WebServlet, @WebFilter, and @WebListener can be enabled by using @ServletComponentScan.

@ServletComponentScan 在一个独立的容器中没有任何作用，容器的内置发现机制用在其中。

@ServletComponentScan has no effect in a standalone container, where the container’s built-in discovery mechanisms are used instead.

The ServletWebServerApplicationContext

底层中，Spring Boot 为嵌入式 servlet 容器支持使用了一种不同类型的 ApplicationContext。ServletWebServerApplicationContext 是一种特殊的 WebApplicationContext，它通过搜索一个 ServletWebServerFactory bean 来启动它自己。通常自动配置一个 TomcatServletWebServerFactory、JettyServletWebServerFactory 或 UndertowServletWebServerFactory。

Under the hood, Spring Boot uses a different type of ApplicationContext for embedded servlet container support. The ServletWebServerApplicationContext is a special type of WebApplicationContext that bootstraps itself by searching for a single ServletWebServerFactory bean. Usually a TomcatServletWebServerFactory, JettyServletWebServerFactory, or UndertowServletWebServerFactory has been auto-configured.

你通常不需要了解这些实现类。大多数应用程序都是自动配置的，适当的 ApplicationContext 和 ServletWebServerFactory 会为你创建。

You usually do not need to be aware of these implementation classes. Most applications are auto-configured, and the appropriate ApplicationContext and ServletWebServerFactory are created on your behalf.

在嵌入式容器设置中，ServletContext 作为服务器启动的一部分进行设置，这发生在应用程序上下文初始化过程中。由于这个原因，ApplicationContext 中的 bean 无法使用 ServletContext 可靠地进行初始化。解决此问题的一种方法是注入 ApplicationContext 作为该 bean 的一个依赖项，并且只有在需要时才访问 ServletContext。另一种方法是服务器启动后使用一个回调函数。这可以通过使用一个 ApplicationListener 来完成，它侦听 ApplicationStartedEvent，如下所示：

In an embedded container setup, the ServletContext is set as part of server startup which happens during application context initialization. Because of this beans in the ApplicationContext cannot be reliably initialized with a ServletContext. One way to get around this is to inject ApplicationContext as a dependency of the bean and access the ServletContext only when it is needed. Another way is to use a callback once the server has started. This can be done using an ApplicationListener which listens for the ApplicationStartedEvent as follows:

Customizing Embedded Servlet Containers

常见的 servlet 容器设置可以通过使用 Spring Environment 属性进行配置。通常，你在 application.properties 或 application.yaml 文件中定义属性。

Common servlet container settings can be configured by using Spring Environment properties. Usually, you would define the properties in your application.properties or application.yaml file.

常见的服务器设置包括：

Common server settings include:

  • Network settings: Listen port for incoming HTTP requests (server.port), interface address to bind to (server.address), and so on.

  • Session settings: Whether the session is persistent (server.servlet.session.persistent), session timeout (server.servlet.session.timeout), location of session data (server.servlet.session.store-dir), and session-cookie configuration (server.servlet.session.cookie.*).

  • Error management: Location of the error page (server.error.path) and so on.

  • SSL

  • HTTP compression

Spring Boot 尽可能多地尝试公开常见设置，但这并不总是可能的。对于那些情况，专用名称空间提供服务器特定的自定义项（请参阅 server.tomcat 和 server.undertow）。例如，access logs 可以配置嵌入式 servlet 容器的特定功能。

Spring Boot tries as much as possible to expose common settings, but this is not always possible. For those cases, dedicated namespaces offer server-specific customizations (see server.tomcat and server.undertow). For instance, access logs can be configured with specific features of the embedded servlet container.

请参阅 {code-spring-boot-autoconfigure-src}/web/ServerProperties.java[ServerProperties] 类以获取完整列表。

See the {code-spring-boot-autoconfigure-src}/web/ServerProperties.java[ServerProperties] class for a complete list.

SameSite Cookies

SameSite cookie 属性可以由网络浏览器用来控制在跨站点请求中是否提交 cookie 以及如何提交 cookie。该属性对于已开始更改该属性缺失时使用的默认值的现代网络浏览器尤其相关。

The SameSite cookie attribute can be used by web browsers to control if and how cookies are submitted in cross-site requests. The attribute is particularly relevant for modern web browsers which have started to change the default value that is used when the attribute is missing.

如果你想更改会话 cookie 的 SameSite 属性，可以使用 configprop:server.servlet.session.cookie.same-site[] 属性。此属性受自动配置的 Tomcat、Jetty 和 Undertow 服务器支持。它还用于配置基于 servlet 的 Spring Session SessionRepository bean。

If you want to change the SameSite attribute of your session cookie, you can use the configprop:server.servlet.session.cookie.same-site[] property. This property is supported by auto-configured Tomcat, Jetty and Undertow servers. It is also used to configure Spring Session servlet based SessionRepository beans.

例如，如果你希望会话 cookie 具有 None 的 SameSite 属性，可以将以下内容添加到 application.properties 或 application.yaml 文件中：

For example, if you want your session cookie to have a SameSite attribute of None, you can add the following to your application.properties or application.yaml file:

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

如果你想更改添加到 HttpServletResponse 中的其他 cookie 上的 SameSite 属性，可以使用 CookieSameSiteSupplier。CookieSameSiteSupplier 传递一个 Cookie 并且可以返回一个 SameSite 值或 null。

If you want to change the SameSite attribute on other cookies added to your HttpServletResponse, you can use a CookieSameSiteSupplier. The CookieSameSiteSupplier is passed a Cookie and may return a SameSite value, or null.

有一些便利工厂和过滤器方法可以用来快速匹配特定 cookie。例如，添加以下 bean 会自动对名称匹配正则表达式 myapp.* 的所有 cookie 应用 Lax 的 SameSite。

There are a number of convenience factory and filter methods that you can use to quickly match specific cookies. For example, adding the following bean will automatically apply a SameSite of Lax for all cookies with a name that matches the regular expression myapp.*.

Character Encoding

可以使用 server.servlet.encoding.* 配置属性配置处理请求和响应的嵌入式 servlet 容器的字符编码行为。

The character encoding behavior of the embedded servlet container for request and response handling can be configured using the server.servlet.encoding.* configuration properties.

当请求的 Accept-Language 头指示请求的语言环境时，servlet 容器会自动将其映射到字符集。每个容器都提供默认的语言环境到字符集映射，你应验证它们是否满足应用程序的需求。如果不满足，请使用 configprop:server.servlet.encoding.mapping[] 配置属性自定义映射，如下例所示：

When a request’s Accept-Language header indicates a locale for the request it will be automatically mapped to a charset by the servlet container. Each container provides default locale to charset mappings and you should verify that they meet your application’s needs. When they do not, use the configprop:server.servlet.encoding.mapping[] configuration property to customize the mappings, as shown in the following example:

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

在前一个示例中，ko（韩语）语言环境已映射到 UTF-8。这等同于传统 war 部署的 web.xml 文件中的 <locale-encoding-mapping-list> 条目。

In the preceding example, the ko (Korean) locale has been mapped to UTF-8. This is equivalent to a <locale-encoding-mapping-list> entry in a web.xml file of a traditional war deployment.

Programmatic Customization

如果你需要从编程角度配置你的嵌入式 servlet 容器，你可以注册一个实现 WebServerFactoryCustomizer 的 Spring bean。WebServerFactoryCustomizer 允许访问 ConfigurableServletWebServerFactory，其中包含了许多定制的设置器方法。以下示例说明了如何以编程方式设置端口：

If you need to programmatically configure your embedded servlet container, you can register a Spring bean that implements the WebServerFactoryCustomizer interface. WebServerFactoryCustomizer provides access to the ConfigurableServletWebServerFactory, which includes numerous customization setter methods. The following example shows programmatically setting the port:

TomcatServletWebServerFactory、JettyServletWebServerFactory 和 UndertowServletWebServerFactory 是 ConfigurableServletWebServerFactory 的专用变体，它们分别为 Tomcat、Jetty 和 Undertow 额外提供了定制设置器方法。以下示例演示了如何定制 TomcatServletWebServerFactory，从而可以访问 Tomcat 特有的配置选项：

TomcatServletWebServerFactory, JettyServletWebServerFactory and UndertowServletWebServerFactory are dedicated variants of ConfigurableServletWebServerFactory that have additional customization setter methods for Tomcat, Jetty and Undertow respectively. The following example shows how to customize TomcatServletWebServerFactory that provides access to Tomcat-specific configuration options:

Customizing ConfigurableServletWebServerFactory Directly

对于更高级的用例，你需要从 ServletWebServerFactory 扩展，你可以公开这样的 bean 类型。

For more advanced use cases that require you to extend from ServletWebServerFactory, you can expose a bean of such type yourself.

为许多配置选项提供了设置器。还提供了若干受保护的方法 “hooks”，以防你需要执行更特殊的操作。有关详细信息，请参见 source code documentation。

Setters are provided for many configuration options. Several protected method “hooks” are also provided should you need to do something more exotic. See the source code documentation for details.

自动配置的定制器仍应用于你的自定义工厂，因此请小心使用该选项。

Auto-configured customizers are still applied on your custom factory, so use that option carefully.

JSP Limitations

在运行使用嵌入式 servlet 容器（并打包为可执行归档文件）的 Spring Boot 应用程序时，JSP 支持有一些限制。

When running a Spring Boot application that uses an embedded servlet container (and is packaged as an executable archive), there are some limitations in the JSP support.

  • With Jetty and Tomcat, it should work if you use war packaging. An executable war will work when launched with java -jar, and will also be deployable to any standard container. JSPs are not supported when using an executable jar.

  • Undertow does not support JSPs.

  • Creating a custom error.jsp page does not override the default view for error handling. Custom error pages should be used instead.