Web

1. Servlet Web 应用程序

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

1.1. “Spring Web MVC 框架”

Spring Web MVC 框架（通常称为“Spring MVC”）是一个丰富的“模型视图控制器”Web 框架。 Spring MVC 允许您创建特殊 bean 或bean来处理传入的 HTTP 请求。 控制器中的方法通过使用注释映射到 HTTP。@Controller@RestController@RequestMappingspring-doc.cn

以下代码显示了提供 JSON 数据的典型代码：@RestControllerspring-doc.cn

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

}
Kotlin
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.cn

Java
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();
    }

}
Kotlin
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
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) {
        ...
    }

}
Kotlin
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.cn

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

1.1.1. Spring MVC 自动配置

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

如果要保留这些 Spring Boot MVC 自定义并进行更多 MVC 自定义（拦截器、格式化程序、视图控制器和其他功能），则可以添加自己的类型类，但不添加 .@ConfigurationWebMvcConfigurer@EnableWebMvcspring-doc.cn

如果要提供 、 或 或 的自定义实例，并且仍然保留 Spring Boot MVC 自定义，则可以声明 类型的 bean 并使用它来提供这些组件的自定义实例。 自定义实例将受 Spring MVC 的进一步初始化和配置的约束。 要参与并在需要时覆盖该后续处理，应使用 a。RequestMappingHandlerMappingRequestMappingHandlerAdapterExceptionHandlerExceptionResolverWebMvcRegistrationsWebMvcConfigurerspring-doc.cn

如果您不想使用自动配置并希望完全控制 Spring MVC，请添加您自己的 an-Comments。 或者，添加您自己的 -annotated ，如 的 Javadoc 中所述。@Configuration@EnableWebMvc@ConfigurationDelegatingWebMvcConfiguration@EnableWebMvcspring-doc.cn

1.1.2. Spring MVC 转换服务

Spring MVC 使用的 a 与用于转换 or 文件中的值的 a 不同。 这意味着 和 转换器不可用，并且 和 注释 将被忽略。ConversionServiceapplication.propertiesapplication.yamlPeriodDurationDataSize@DurationUnit@DataSizeUnitspring-doc.cn

如果要自定义 Spring MVC 使用的 ，则可以提供带有方法的 bean。 通过此方法，您可以注册所需的任何转换器，也可以委托给 上可用的静态方法。ConversionServiceWebMvcConfigureraddFormattersApplicationConversionServicespring-doc.cn

还可以使用配置属性自定义转换。 如果未配置，则使用以下默认值：spring.mvc.format.*spring-doc.cn

财产 DateTimeFormatter 格式

spring.mvc.format.datespring-doc.cn

ofLocalizedDate(FormatStyle.SHORT)spring-doc.cn

java.util.Date和java.time.LocalDatespring-doc.cn

spring.mvc.format.timespring-doc.cn

ofLocalizedTime(FormatStyle.SHORT)spring-doc.cn

java.time 的 和LocalTimeOffsetTimespring-doc.cn

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

ofLocalizedDateTime(FormatStyle.SHORT)spring-doc.cn

java.time 的 、 和LocalDateTimeOffsetDateTimeZonedDateTimespring-doc.cn

1.1.3. HttpMessage转换器

Spring MVC 使用该接口来转换 HTTP 请求和响应。 合理的默认值是开箱即用的。 例如，对象可以自动转换为 JSON（通过使用 Jackson 库）或 XML（通过使用 Jackson XML 扩展，如果可用，或者通过使用 JAXB，如果 Jackson XML 扩展不可用）。 默认情况下，字符串以 .HttpMessageConverterUTF-8spring-doc.cn

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

如果需要添加或自定义转换器，可以使用 Spring Boot 的类，如下面的清单所示：HttpMessageConvertersspring-doc.cn

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

}
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)
class MyHttpMessageConvertersConfiguration {

    @Bean
    fun customConverters(): HttpMessageConverters {
        val additional: HttpMessageConverter<*> = AdditionalHttpMessageConverter()
        val another: HttpMessageConverter<*> = AnotherHttpMessageConverter()
        return HttpMessageConverters(additional, another)
    }

}

为了进一步控制，您还可以子类化并覆盖其 and/or 方法。 当您想要重新排序或删除 Spring MVC 默认配置的某些转换器时，这可能很有用。HttpMessageConverterspostProcessConverterspostProcessPartConvertersspring-doc.cn

1.1.4. MessageCodes解析器

Spring MVC 有一个生成错误代码的策略，用于呈现来自绑定错误的错误消息：。 如果设置属性或，则 Spring Boot 会为您创建一个（请参见DefaultMessageCodesResolver.Format中的枚举）。MessageCodesResolverspring.mvc.message-codes-resolver-formatPREFIX_ERROR_CODEPOSTFIX_ERROR_CODEspring-doc.cn

1.1.5. 静态内容

默认情况下， Spring Boot 从 classpath 中名为 （or or or or ） 的目录或 . 它使用来自 Spring MVC，以便您可以通过添加自己的行为并覆盖该方法来修改该行为。/static/public/resources/META-INF/resourcesServletContextResourceHttpRequestHandlerWebMvcConfigureraddResourceHandlersspring-doc.cn

在独立的 Web 应用程序中，未启用容器中的默认 Servlet。 可以使用 属性 来启用它。server.servlet.register-default-servletspring-doc.cn

默认 servlet 充当后备，如果 Spring 决定不处理它，则从根提供内容。 大多数情况下，这不会发生（除非你修改了默认的 MVC 配置），因为 Spring 总是可以通过 .ServletContextDispatcherServletspring-doc.cn

默认情况下，资源映射在 上，但您可以使用属性对其进行优化。 例如，可以按如下方式将所有资源重新定位到：/**spring.mvc.static-path-pattern/resources/**spring-doc.cn

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

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

除了前面提到的“标准”静态资源位置之外，Webjars 内容还有一个特殊情况。 默认情况下，如果 jar 文件以 Webjars 格式打包，则从 jar 文件提供任何具有路径 in 的资源。 可以使用 属性 自定义路径。/webjars/**spring.mvc.webjars-path-patternspring-doc.cn

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

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

要对 Webjar 使用与版本无关的 URL，请添加依赖项。 然后声明您的 Webjar。 以 jQuery 为例，添加 where 是 Webjar 版本。webjars-locator-core"/webjars/jquery/jquery.min.js""/webjars/jquery/x.y.z/jquery.min.js"x.y.zspring-doc.cn

如果使用 JBoss，则需要声明依赖项，而不是 . 否则，所有 Webjar 都将解析为 .webjars-locator-jboss-vfswebjars-locator-core404

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

性能
spring.web.resources.chain.strategy.content.enabled=true
spring.web.resources.chain.strategy.content.paths=/**
Yaml
spring:
  web:
    resources:
      chain:
        strategy:
          content:
            enabled: true
            paths: "/**"
由于为 Thymeleaf 和 FreeMarker 自动配置了 a，因此在运行时在模板中重写了资源的链接。 使用 JSP 时，应手动声明此过滤器。 其他模板引擎目前不自动支持，但可以使用自定义模板宏/帮助程序和 ResourceUrlProvider 的使用。ResourceUrlEncodingFilter

例如，使用 JavaScript 模块加载器动态加载资源时，重命名文件不是一个选项。 这就是为什么还支持其他策略并且可以组合的原因。 “fixed” 策略在 URL 中添加静态版本字符串，而不更改文件名，如以下示例所示：spring-doc.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
Yaml
spring:
  web:
    resources:
      chain:
        strategy:
          content:
            enabled: true
            paths: "/**"
          fixed:
            enabled: true
            paths: "/js/lib/"
            version: "v12"

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

有关更多支持的选项，请参阅 WebProperties.Resources。spring-doc.cn

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

1.1.6. 欢迎页面

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

这仅充当应用程序定义的实际索引路由的回退。 排序由 bean 的顺序定义，默认情况下，顺序如下：HandlerMappingspring-doc.cn

RouterFunctionMappingspring-doc.cn

使用 bean 声明的端点RouterFunctionspring-doc.cn

RequestMappingHandlerMappingspring-doc.cn

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

WelcomePageHandlerMappingspring-doc.cn

欢迎页面支持spring-doc.cn

1.1.7. 自定义网站图标

与其他静态资源一样， Spring Boot 会在配置的静态内容位置中检查a。 如果存在此类文件，则会自动将其用作应用程序的图标。favicon.icospring-doc.cn

1.1.8. 路径匹配和内容协商

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

Spring Boot 默认选择禁用后缀模式匹配，这意味着像这样的请求将不会与 Map 匹配。 这被认为是 Spring MVC 应用程序的最佳实践。 此功能在过去主要对没有发送正确的 “Accept” 请求标头的 HTTP 客户端有用;我们需要确保将正确的 Content Type 发送给客户端。 如今，Content Negotiation 更加可靠。"GET /projects/spring-boot.json"@GetMapping("/projects/spring-boot")spring-doc.cn

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

性能
spring.mvc.contentnegotiation.favor-parameter=true
Yaml
spring:
  mvc:
    contentnegotiation:
      favor-parameter: true

或者，如果您更喜欢使用不同的参数名称：spring-doc.cn

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

大多数标准媒体类型都是开箱即用的，但您也可以定义新的媒体类型：spring-doc.cn

性能
spring.mvc.contentnegotiation.media-types.markdown=text/markdown
Yaml
spring:
  mvc:
    contentnegotiation:
      media-types:
        markdown: "text/markdown"

从 Spring Framework 5.3 开始， Spring MVC 支持两种将请求路径与控制器匹配的策略。 默认情况下， Spring Boot 使用该策略。 是一种优化的实施，但与该策略相比有一些限制。 限制某些路径模式变体的使用。 它也与使用路径前缀 （） 配置 不兼容。PathPatternParserPathPatternParserAntPathMatcherPathPatternParserDispatcherServletspring.mvc.servlet.pathspring-doc.cn

可以使用 configuration 属性配置策略，如以下示例所示：spring.mvc.pathmatch.matching-strategyspring-doc.cn

性能
spring.mvc.pathmatch.matching-strategy=ant-path-matcher
Yaml
spring:
  mvc:
    pathmatch:
      matching-strategy: "ant-path-matcher"

Spring MVC 将抛出一个 如果找不到请求的处理程序。 请注意，默认情况下，静态内容的提供会映射到所有请求，因此会为所有请求提供处理程序。 如果没有可用的静态内容，将抛出 . 对于要引发的 a，请设置为更具体的值，例如 或 设置为 以完全禁用静态内容的提供。NoHandlerFoundException/**ResourceHttpRequestHandlerNoResourceFoundExceptionNoHandlerFoundExceptionspring.mvc.static-path-pattern/resources/**spring.web.resources.add-mappingsfalsespring-doc.cn

1.1.9. 可配置的 WebBindingInitializer

Spring MVC 使用 a 来初始化特定请求的 a。 如果您创建自己的，Spring Boot 会自动配置 Spring MVC 以使用它。WebBindingInitializerWebDataBinderConfigurableWebBindingInitializer@Beanspring-doc.cn

1.1.10. 模板引擎

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

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

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

当您将其中一个模板引擎与默认配置一起使用时，您的模板会自动从 中选取。src/main/resources/templatesspring-doc.cn

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

1.1.11. 错误处理

默认情况下， Spring Boot 提供了一个以合理方式处理所有错误的 Map，并且在 servlet 容器中注册为“全局”错误页面。 对于计算机客户端，它会生成一个 JSON 响应，其中包含错误、HTTP 状态和异常消息的详细信息。 对于浏览器客户端，有一个“whitelabel”错误视图，它以 HTML 格式呈现相同的数据（要对其进行自定义，请添加一个 resolves to ）。/errorViewerrorspring-doc.cn

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

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

可以用作自定义 . 如果要为新的内容类型添加处理程序（默认是专门处理并为其他所有内容提供回退），这将特别有用。 为此，请 extend 添加一个具有属性的公共方法，并创建一个新类型的 bean。BasicErrorControllerErrorControllertext/htmlBasicErrorController@RequestMappingproduces

从 Spring Framework 6.0 开始，支持 RFC 9457 问题详细信息。 Spring MVC 可以生成具有 media 类型的自定义错误消息，例如：application/problem+jsonspring-doc.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.enabledtruespring-doc.cn

您还可以定义一个带注释的类，以自定义要为特定控制器和/或异常类型返回的 JSON 文档，如以下示例所示：@ControllerAdvicespring-doc.cn

Java
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;
    }

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

}

在前面的示例中，如果由在与 相同的包中定义的控制器抛出，则使用 POJO 的 JSON 表示形式而不是表示形式。MyExceptionSomeControllerMyErrorBodyErrorAttributesspring-doc.cn

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

自定义错误页面

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

例如，要映射到静态 HTML 文件，您的目录结构将如下所示：404spring-doc.cn

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

要使用 FreeMarker 模板映射所有错误，您的目录结构将如下所示：5xxspring-doc.cn

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

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

Java
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;
    }

}
Kotlin
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。 then 选取任何未处理的异常。ErrorControllerspring-doc.cn

在 Spring MVC 之外映射错误页面

对于不使用 Spring MVC 的应用程序，可以使用该接口直接注册。 此抽象直接与底层嵌入式 servlet 容器一起使用，即使您没有 Spring MVC 也可以工作。ErrorPageRegistrarErrorPagesDispatcherServletspring-doc.cn

Java
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"));
    }

}
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)
class MyErrorPagesConfiguration {

    @Bean
    fun errorPageRegistrar(): ErrorPageRegistrar {
        return ErrorPageRegistrar { registry: ErrorPageRegistry -> registerErrorPages(registry) }
    }

    private fun registerErrorPages(registry: ErrorPageRegistry) {
        registry.addErrorPages(ErrorPage(HttpStatus.BAD_REQUEST, "/400"))
    }

}
如果您注册的路径最终由 a（在某些非 Spring Web 框架中很常见，如 Jersey 和 Wicket），则必须将 显式注册为调度程序，如以下示例所示：ErrorPageFilterFilterERROR
Java
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;
    }

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

}

请注意，默认值不包括 Dispatcher 类型。FilterRegistrationBeanERRORspring-doc.cn

WAR 部署中的错误处理

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

如果尚未提交响应，则错误页面过滤器只能将请求转发到正确的错误页面。 默认情况下，WebSphere Application Server 8.0 及更高版本在成功完成 servlet 的服务方法后提交响应。 您应该通过设置为 来禁用此行为。com.ibm.ws.webcontainer.invokeFlushAfterServicefalsespring-doc.cn

1.1.12. CORS 支持

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

从版本 4.2 开始，Spring MVC 支持 CORS。 在 Spring Boot 应用程序中使用带有 @CrossOrigin 注释的控制器方法 CORS 配置不需要任何特定配置。可以通过使用自定义方法注册 bean 来定义全局 CORS 配置，如以下示例所示：WebMvcConfigureraddCorsMappings(CorsRegistry)spring-doc.cn

Java
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/**");
            }

        };
    }

}
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)
class MyCorsConfiguration {

    @Bean
    fun corsConfigurer(): WebMvcConfigurer {
        return object : WebMvcConfigurer {
            override fun addCorsMappings(registry: CorsRegistry) {
                registry.addMapping("/api/**")
            }
        }
    }

}

1.2. JAX-RS 和Jersey

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

要开始使用 Jersey，请包括 as a 依赖项，然后您需要一个 type of you register all the endpoints in ，如以下示例所示：spring-boot-starter-jersey@BeanResourceConfigspring-doc.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 文件或运行可执行 war 文件时找到的包中的端点。 为避免此限制，不应使用该方法，并且应使用该方法单独注册端点，如前面的示例所示。WEB-INF/classespackagesregister

对于更高级的自定义，您还可以注册任意数量的实现 .ResourceConfigCustomizerspring-doc.cn

所有已注册的端点都应带有 HTTP 资源注释（和其他），如以下示例所示：@Components@GETspring-doc.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";
    }

}

由于 is a Spring ，它的生命周期由 Spring 管理，您可以使用 annotation 注入依赖项，并使用 annotation 注入外部配置。 默认情况下，Jersey Servlet 已注册并映射到 。 您可以通过将 .Endpoint@Component@Autowired@Value/*@ApplicationPathResourceConfigspring-doc.cn

默认情况下，Jersey 设置为类型为 的 Servlet。 默认情况下，Servlet 是延迟初始化的，但您可以通过设置 来自定义该行为。 您可以通过创建一个具有相同名称的 bean 来禁用或覆盖该 bean。 您还可以通过设置（在这种情况下，要替换或覆盖为 ）来使用过滤器而不是 servlet。 过滤器具有一个 ，您可以使用 中设置该过滤器。 当使用 Jersey 作为过滤器时，必须存在一个 Servlet，该 Servlet 将处理 Jersey 未拦截的任何请求。 如果应用程序不包含此类 Servlet，则可能需要通过设置为 来启用默认 Servlet。 servlet 和过滤器注册都可以通过 using 指定属性映射来获得 init 参数。@BeanServletRegistrationBeanjerseyServletRegistrationspring.jersey.servlet.load-on-startupspring.jersey.type=filter@BeanjerseyFilterRegistration@Orderspring.jersey.filter.orderserver.servlet.register-default-servlettruespring.jersey.init.*spring-doc.cn

1.3. 嵌入式 Servlet 容器支持

对于 servlet 应用程序，Spring Boot 包括对嵌入式 Tomcat、Jetty 和 Undertow 服务器的支持。 大多数开发人员使用适当的 “Starter” 来获取完全配置的实例。 默认情况下，嵌入式服务器侦听端口 上的 HTTP 请求。8080spring-doc.cn

1.3.1. Servlet、过滤器和侦听器

使用嵌入式 Servlet 容器时，可以通过使用 Spring Bean 或扫描 Servlet 组件，从 Servlet 规范注册 Servlet、过滤器和所有侦听器（例如 ）。HttpSessionListenerspring-doc.cn

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

任何作为 Spring Bean 的 ， 或 servlet 实例都已注册到嵌入式容器中。 如果您想在配置期间引用 your 中的值，这可能特别方便。ServletFilter*Listenerapplication.propertiesspring-doc.cn

默认情况下，如果上下文仅包含单个 Servlet，则会将其映射到 。 在多个 servlet bean 的情况下，bean 名称用作路径前缀。 筛选器映射到 。//*spring-doc.cn

如果基于约定的映射不够灵活，则可以使用 、 和 类进行完全控制。ServletRegistrationBeanFilterRegistrationBeanServletListenerRegistrationBeanspring-doc.cn

通常，将 filter bean 保持无序状态是安全的。 如果需要特定顺序，则应注释 with 或使其 implement 。 不能通过使用 . 如果无法更改要添加或实现的类，则必须为 定义 a 并使用该方法设置注册 Bean 的顺序。 避免配置读取请求正文的过滤器，因为它可能会违背应用程序的字符编码配置。 如果 servlet 过滤器包装请求，则应将其配置为小于或等于 的顺序。Filter@OrderOrderedFilter@OrderFilter@OrderOrderedFilterRegistrationBeanFiltersetOrder(int)Ordered.HIGHEST_PRECEDENCEOrderedFilter.REQUEST_WRAPPER_FILTER_MAX_ORDERspring-doc.cn

要查看应用程序中 every 的顺序，请为日志记录组 （） 启用调试级别日志记录。 然后，将在启动时记录已注册过滤器的详细信息，包括它们的顺序和 URL 模式。Filterweblogging.level.web=debug
注册 bean 时要小心，因为它们在应用程序生命周期的早期就被初始化了。 如果你需要注册一个与其他 bean 交互的 bean，请考虑改用DelegatingFilterProxyRegistrationBean。FilterFilter

1.3.2. Servlet 上下文初始化

嵌入式 Servlet 容器不直接执行接口或 Spring 的接口。 这是一个有意的设计决策，旨在降低设计为在 war 中运行的第三方库可能会破坏 Spring Boot 应用程序的风险。jakarta.servlet.ServletContainerInitializerorg.springframework.web.WebApplicationInitializerspring-doc.cn

如果需要在 Spring Boot 应用程序中执行 servlet 上下文初始化，则应注册实现该接口的 Bean。 单一方法提供对 的访问，如有必要，可以轻松地用作现有 .org.springframework.boot.web.servlet.ServletContextInitializeronStartupServletContextWebApplicationInitializerspring-doc.cn

扫描 Servlet、Filter 和侦听器

使用嵌入式容器时，可以使用 .@WebServlet@WebFilter@WebListener@ServletComponentScanspring-doc.cn

@ServletComponentScan在独立容器中不起作用，其中使用容器的内置发现机制。

1.3.3. ServletWebServerApplicationContext

在后台，Spring Boot 使用不同类型的嵌入式 servlet 容器支持。 这是一种特殊类型，它通过搜索单个 bean 来引导自身。 通常 ， ， 或 已自动配置。ApplicationContextServletWebServerApplicationContextWebApplicationContextServletWebServerFactoryTomcatServletWebServerFactoryJettyServletWebServerFactoryUndertowServletWebServerFactoryspring-doc.cn

您通常不需要了解这些 implementation classes。 大多数应用程序都是自动配置的，并且是代表您创建的。ApplicationContextServletWebServerFactory

在嵌入式容器设置中，设置为 服务器启动的一部分，该启动发生在应用程序上下文初始化期间。 因此，无法可靠地使用 . 解决此问题的一种方法是作为 bean 的依赖项注入，并仅在需要时访问 。 另一种方法是在服务器启动后使用回调。 这可以使用 an 来完成，它监听如下：ServletContextApplicationContextServletContextApplicationContextServletContextApplicationListenerApplicationStartedEventspring-doc.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();
    }

}

1.3.4. 自定义嵌入式 Servlet 容器

可以使用 Spring 属性配置常见的 servlet 容器设置。 通常，您将在 or 文件中定义属性。Environmentapplication.propertiesapplication.yamlspring-doc.cn

常见的服务器设置包括：spring-doc.cn

  • 网络设置：侦听传入 HTTP 请求的端口 （）、要绑定到的接口地址 （） 等。server.portserver.addressspring-doc.cn

  • 会话设置：会话是否持久 （）、会话超时 （）、会话数据的位置 （） 和会话 cookie 配置 （）。server.servlet.session.persistentserver.servlet.session.timeoutserver.servlet.session.store-dirserver.servlet.session.cookie.*spring-doc.cn

  • 错误管理：错误页面的位置 （） 等。server.error.pathspring-doc.cn

  • SSL认证spring-doc.cn

  • HTTP 压缩spring-doc.cn

Spring Boot 会尽可能多地公开通用设置，但这并不总是可能的。 对于这些情况，专用命名空间提供特定于服务器的自定义（请参阅 和 ）。 例如，可以使用嵌入式 servlet 容器的特定功能配置访问日志。server.tomcatserver.undertowspring-doc.cn

有关完整列表，请参阅 ServerProperties 类。
SameSite Cookie

Web 浏览器可以使用 cookie 属性来控制是否以及如何在跨站点请求中提交 cookie。 该属性与现代 Web 浏览器尤其相关，这些浏览器已开始更改在缺少该属性时使用的默认值。SameSitespring-doc.cn

如果要更改会话 Cookie 的属性，可以使用该属性。 自动配置的 Tomcat、Jetty 和 Undertow 服务器支持此属性。 它还用于配置基于 Spring Session servlet 的 bean。SameSiteserver.servlet.session.cookie.same-siteSessionRepositoryspring-doc.cn

例如，如果您希望会话 Cookie 具有 属性 ，则可以将以下内容添加到您的 or 文件中：SameSiteNoneapplication.propertiesapplication.yamlspring-doc.cn

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

如果要更改添加到 中的其他 Cookie 的属性，可以使用 . 这传递了一个 ，并且可能返回一个值，或者 .SameSiteHttpServletResponseCookieSameSiteSupplierCookieSameSiteSupplierCookieSameSitenullspring-doc.cn

您可以使用许多方便的 Factory 和 Filter 方法来快速匹配特定的 Cookie。 例如，添加以下 bean 将自动对名称与 regular expression 匹配的所有 cookie 应用 of 。SameSiteLaxmyapp.*spring-doc.cn

Java
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.*");
    }

}
Kotlin
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.cn

当请求的标头指示请求的语言环境时，Servlet 容器会自动将其映射到字符集。 每个容器都提供 charset 映射的默认区域设置，您应该验证它们是否满足应用程序的需要。 如果它们没有，请使用 configuration 属性来自定义映射，如以下示例所示：Accept-Languageserver.servlet.encoding.mappingspring-doc.cn

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

在前面的示例中，（朝鲜语）区域设置已映射到 。 这相当于传统 war 部署文件中的条目。koUTF-8<locale-encoding-mapping-list>web.xmlspring-doc.cn

编程自定义

如果需要以编程方式配置嵌入式 servlet 容器，则可以注册实现该接口的 Spring Bean。 提供对 的访问，其中包括许多自定义 setter 方法。 以下示例显示了以编程方式设置端口：WebServerFactoryCustomizerWebServerFactoryCustomizerConfigurableServletWebServerFactoryspring-doc.cn

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

}
Kotlin
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，并且是专用变体，分别具有 Tomcat、Jetty 和 Undertow 的其他自定义 setter 方法。 以下示例显示了如何自定义以提供对特定于 Tomcat 的配置选项的访问：JettyServletWebServerFactoryUndertowServletWebServerFactoryConfigurableServletWebServerFactoryTomcatServletWebServerFactoryspring-doc.cn

Java
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()));
    }

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

对于需要您扩展的更高级的用例，您可以自己公开此类 bean。ServletWebServerFactoryspring-doc.cn

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

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

1.3.5. JSP 限制

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

  • 对于 Jetty 和 Tomcat，如果您使用 war 打包，它应该可以工作。 可执行的 war 将在使用 启动时起作用，并且也可以部署到任何标准容器。 使用可执行 jar 时，不支持 JSP。java -jarspring-doc.cn

  • Undertow 不支持 JSP。spring-doc.cn

  • 创建自定义页面不会覆盖错误处理的默认视图。应改用自定义错误页面。error.jspspring-doc.cn

2. 反应式 Web 应用程序

Spring Boot 通过为 Spring Webflux 提供自动配置来简化反应式 Web 应用程序的开发。spring-doc.cn

2.1. “Spring WebFlux 框架”

Spring WebFlux 是 Spring Framework 5.0 中引入的新反应式 Web 框架。 与 Spring MVC 不同，它不需要 servlet API，是完全异步和非阻塞的，并通过 Reactor 项目实现反应流规范。spring-doc.cn

Spring WebFlux 有两种风格：函数式和基于 Comments 的。 基于 Comments 的模型与 Spring MVC 模型非常接近，如以下示例所示：spring-doc.cn

Java
import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;

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 Mono<User> getUser(@PathVariable Long userId) {
        return this.userRepository.findById(userId);
    }

    @GetMapping("/{userId}/customers")
    public Flux<Customer> getUserCustomers(@PathVariable Long userId) {
        return this.userRepository.findById(userId).flatMapMany(this.customerRepository::findByUser);
    }

    @DeleteMapping("/{userId}")
    public Mono<Void> deleteUser(@PathVariable Long userId) {
        return this.userRepository.deleteById(userId);
    }

}
Kotlin
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
import reactor.core.publisher.Flux
import reactor.core.publisher.Mono

@RestController
@RequestMapping("/users")
class MyRestController(private val userRepository: UserRepository, private val customerRepository: CustomerRepository) {

    @GetMapping("/{userId}")
    fun getUser(@PathVariable userId: Long): Mono<User?> {
        return userRepository.findById(userId)
    }

    @GetMapping("/{userId}/customers")
    fun getUserCustomers(@PathVariable userId: Long): Flux<Customer> {
        return userRepository.findById(userId).flatMapMany { user: User? ->
            customerRepository.findByUser(user)
        }
    }

    @DeleteMapping("/{userId}")
    fun deleteUser(@PathVariable userId: Long): Mono<Void> {
        return userRepository.deleteById(userId)
    }

}

WebFlux 是 Spring Framework 的一部分，其参考文档中提供了详细信息。spring-doc.cn

“WebFlux.fn”是功能变体，它将路由配置与请求的实际处理分开，如以下示例所示：spring-doc.cn

Java
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.MediaType;
import org.springframework.web.reactive.function.server.RequestPredicate;
import org.springframework.web.reactive.function.server.RouterFunction;
import org.springframework.web.reactive.function.server.ServerResponse;

import static org.springframework.web.reactive.function.server.RequestPredicates.accept;
import static org.springframework.web.reactive.function.server.RouterFunctions.route;

@Configuration(proxyBeanMethods = false)
public class MyRoutingConfiguration {

    private static final RequestPredicate ACCEPT_JSON = accept(MediaType.APPLICATION_JSON);

    @Bean
    public RouterFunction<ServerResponse> monoRouterFunction(MyUserHandler userHandler) {
        return route()
                .GET("/{user}", ACCEPT_JSON, userHandler::getUser)
                .GET("/{user}/customers", ACCEPT_JSON, userHandler::getUserCustomers)
                .DELETE("/{user}", ACCEPT_JSON, userHandler::deleteUser)
                .build();
    }

}
Kotlin
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.http.MediaType
import org.springframework.web.reactive.function.server.RequestPredicates.DELETE
import org.springframework.web.reactive.function.server.RequestPredicates.GET
import org.springframework.web.reactive.function.server.RequestPredicates.accept
import org.springframework.web.reactive.function.server.RouterFunction
import org.springframework.web.reactive.function.server.RouterFunctions
import org.springframework.web.reactive.function.server.ServerResponse

@Configuration(proxyBeanMethods = false)
class MyRoutingConfiguration {

    @Bean
    fun monoRouterFunction(userHandler: MyUserHandler): RouterFunction<ServerResponse> {
        return RouterFunctions.route(
            GET("/{user}").and(ACCEPT_JSON), userHandler::getUser).andRoute(
            GET("/{user}/customers").and(ACCEPT_JSON), userHandler::getUserCustomers).andRoute(
            DELETE("/{user}").and(ACCEPT_JSON), userHandler::deleteUser)
    }

    companion object {
        private val ACCEPT_JSON = accept(MediaType.APPLICATION_JSON)
    }

}
Java
import reactor.core.publisher.Mono;

import org.springframework.stereotype.Component;
import org.springframework.web.reactive.function.server.ServerRequest;
import org.springframework.web.reactive.function.server.ServerResponse;

@Component
public class MyUserHandler {

    public Mono<ServerResponse> getUser(ServerRequest request) {
        ...
    }

    public Mono<ServerResponse> getUserCustomers(ServerRequest request) {
        ...
    }

    public Mono<ServerResponse> deleteUser(ServerRequest request) {
        ...
    }

}
Kotlin
import org.springframework.stereotype.Component
import org.springframework.web.reactive.function.server.ServerRequest
import org.springframework.web.reactive.function.server.ServerResponse
import reactor.core.publisher.Mono

@Component
class MyUserHandler {

    fun getUser(request: ServerRequest?): Mono<ServerResponse> {
        ...
    }

    fun getUserCustomers(request: ServerRequest?): Mono<ServerResponse> {
        ...
    }

    fun deleteUser(request: ServerRequest?): Mono<ServerResponse> {
        ...
    }

}

“WebFlux.fn” 是 Spring Framework 的一部分，详细信息可在其参考文档中找到。spring-doc.cn

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

要开始使用，请将模块添加到您的应用程序中。spring-boot-starter-webfluxspring-doc.cn

在应用程序中添加 and 模块会导致 Spring Boot 自动配置 Spring MVC，而不是 WebFlux。 之所以选择这种行为，是因为许多 Spring 开发人员添加到他们的 Spring MVC 应用程序中以使用 reactive . 您仍然可以通过将所选应用程序类型设置为 来强制执行您的选择。spring-boot-starter-webspring-boot-starter-webfluxspring-boot-starter-webfluxWebClientSpringApplication.setWebApplicationType(WebApplicationType.REACTIVE)

2.1.1. Spring WebFlux 自动配置

Spring Boot 为 Spring WebFlux 提供了自动配置，适用于大多数应用程序。spring-doc.cn

自动配置在 Spring 的默认值之上添加了以下功能：spring-doc.cn

如果要保留 Spring Boot WebFlux 功能，并且想要添加其他 WebFlux 配置，则可以添加自己的类型类，但不添加 .@ConfigurationWebFluxConfigurer@EnableWebFluxspring-doc.cn

如果您想完全控制 Spring WebFlux，您可以添加自己的 annotwith .@Configuration@EnableWebFluxspring-doc.cn

2.1.2. Spring WebFlux 转换服务

如果要自定义 Spring WebFlux 使用的 ，则可以提供带有方法的 bean。ConversionServiceWebFluxConfigureraddFormattersspring-doc.cn

还可以使用配置属性自定义转换。 如果未配置，则使用以下默认值：spring.webflux.format.*spring-doc.cn

财产 DateTimeFormatter 格式

spring.webflux.format.datespring-doc.cn

ofLocalizedDate(FormatStyle.SHORT)spring-doc.cn

java.util.Date和java.time.LocalDatespring-doc.cn

spring.webflux.format.timespring-doc.cn

ofLocalizedTime(FormatStyle.SHORT)spring-doc.cn

java.time 的 和LocalTimeOffsetTimespring-doc.cn

spring.webflux.format.date-timespring-doc.cn

ofLocalizedDateTime(FormatStyle.SHORT)spring-doc.cn

java.time 的 、 和LocalDateTimeOffsetDateTimeZonedDateTimespring-doc.cn

2.1.3. 使用 HttpMessageReaders 和 HttpMessageWriters 的 HTTP 编解码器

Spring WebFlux 使用 and 接口来转换 HTTP 请求和响应。 通过查看 Classpath 中可用的库，将它们配置为具有合理的默认值。HttpMessageReaderHttpMessageWriterCodecConfigurerspring-doc.cn

Spring Boot 为编解码器提供了专用的配置属性。 它还通过使用实例应用进一步的自定义。 例如，将配置键应用于 Jackson 编解码器。spring.codec.*CodecCustomizerspring.jackson.*spring-doc.cn

如果需要添加或自定义编解码器，可以创建自定义组件，如以下示例所示：CodecCustomizerspring-doc.cn

Java
import org.springframework.boot.web.codec.CodecCustomizer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.codec.ServerSentEventHttpMessageReader;

@Configuration(proxyBeanMethods = false)
public class MyCodecsConfiguration {

    @Bean
    public CodecCustomizer myCodecCustomizer() {
        return (configurer) -> {
            configurer.registerDefaults(false);
            configurer.customCodecs().register(new ServerSentEventHttpMessageReader());
            // ...
        };
    }

}
Kotlin
import org.springframework.boot.web.codec.CodecCustomizer
import org.springframework.context.annotation.Bean
import org.springframework.http.codec.CodecConfigurer
import org.springframework.http.codec.ServerSentEventHttpMessageReader

class MyCodecsConfiguration {

    @Bean
    fun myCodecCustomizer(): CodecCustomizer {
        return CodecCustomizer { configurer: CodecConfigurer ->
            configurer.registerDefaults(false)
            configurer.customCodecs().register(ServerSentEventHttpMessageReader())
        }
    }

}

您还可以利用 Boot 的自定义 JSON 序列化器和反序列化器。spring-doc.cn

2.1.4. 静态内容

默认情况下， Spring Boot 从 Classpath 中名为 （or or or or ） 的目录提供静态内容。 它使用来自 Spring WebFlux，以便您可以通过添加自己的行为并覆盖该方法来修改该行为。/static/public/resources/META-INF/resourcesResourceWebHandlerWebFluxConfigureraddResourceHandlersspring-doc.cn

默认情况下，资源映射在 上，但您可以通过设置属性来调整它。 例如，可以按如下方式将所有资源重新定位到：/**spring.webflux.static-path-pattern/resources/**spring-doc.cn

性能
spring.webflux.static-path-pattern=/resources/**
Yaml
spring:
  webflux:
    static-path-pattern: "/resources/**"

您还可以使用 自定义静态资源位置。 这样做会将默认值替换为目录位置列表。 如果这样做，默认的欢迎页面检测将切换到您的自定义位置。 因此，如果您在启动时的任何位置都有一个，则它是应用程序的主页。spring.web.resources.static-locationsindex.htmlspring-doc.cn

除了前面列出的“标准”静态资源位置之外，Webjars 内容还有一个特殊情况。 默认情况下，如果 jar 文件以 Webjars 格式打包，则从 jar 文件提供任何具有路径 in 的资源。 可以使用 属性 自定义路径。/webjars/**spring.webflux.webjars-path-patternspring-doc.cn

Spring WebFlux 应用程序并不严格依赖于 servlet API，因此它们不能部署为 war 文件，也不使用目录。src/main/webapp

2.1.5. 欢迎页面

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

这仅充当应用程序定义的实际索引路由的回退。 排序由 bean 的顺序定义，默认情况下，顺序如下：HandlerMappingspring-doc.cn

RouterFunctionMappingspring-doc.cn

使用 bean 声明的端点RouterFunctionspring-doc.cn

RequestMappingHandlerMappingspring-doc.cn

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

RouterFunctionMapping对于欢迎页面spring-doc.cn

欢迎页面支持spring-doc.cn

2.1.6. 模板引擎

除了 REST Web 服务之外，您还可以使用 Spring WebFlux 来提供动态 HTML 内容。 Spring WebFlux 支持多种模板技术，包括 Thymeleaf、FreeMarker 和 Mustache。spring-doc.cn

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

当您将其中一个模板引擎与默认配置一起使用时，您的模板会自动从 中选取。src/main/resources/templatesspring-doc.cn

2.1.7. 错误处理

Spring Boot 提供了一个以合理的方式处理所有错误的程序。 它在处理顺序中的位置紧接在 WebFlux 提供的处理程序之前，这些处理程序被视为最后。 对于计算机客户端，它会生成一个 JSON 响应，其中包含错误、HTTP 状态和异常消息的详细信息。 对于浏览器客户端，有一个 “whitelabel” 错误处理程序，它以 HTML 格式呈现相同的数据。 您还可以提供自己的 HTML 模板来显示错误（请参阅下一节）。WebExceptionHandlerspring-doc.cn

在直接在 Spring Boot 中自定义错误处理之前，您可以利用 Spring WebFlux 中的 RFC 9457 问题详细信息支持。 Spring WebFlux 可以生成具有 media 类型的自定义错误消息，例如：application/problem+jsonspring-doc.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.webflux.problemdetails.enabledtruespring-doc.cn

自定义此功能的第一步通常涉及使用现有机制，但替换或扩充错误内容。 为此，您可以添加 .ErrorAttributesspring-doc.cn

要更改错误处理行为，可以实现并注册该类型的 Bean 定义。 因为an是相当低级的，Spring Boot 还提供了一个方便的让你以 WebFlux 功能方式处理错误，如下面的例子所示：ErrorWebExceptionHandlerErrorWebExceptionHandlerAbstractErrorWebExceptionHandlerspring-doc.cn

Java
import reactor.core.publisher.Mono;

import org.springframework.boot.autoconfigure.web.WebProperties;
import org.springframework.boot.autoconfigure.web.reactive.error.AbstractErrorWebExceptionHandler;
import org.springframework.boot.web.reactive.error.ErrorAttributes;
import org.springframework.context.ApplicationContext;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.http.codec.ServerCodecConfigurer;
import org.springframework.stereotype.Component;
import org.springframework.web.reactive.function.server.RouterFunction;
import org.springframework.web.reactive.function.server.RouterFunctions;
import org.springframework.web.reactive.function.server.ServerRequest;
import org.springframework.web.reactive.function.server.ServerResponse;
import org.springframework.web.reactive.function.server.ServerResponse.BodyBuilder;

@Component
public class MyErrorWebExceptionHandler extends AbstractErrorWebExceptionHandler {

    public MyErrorWebExceptionHandler(ErrorAttributes errorAttributes, WebProperties webProperties,
            ApplicationContext applicationContext, ServerCodecConfigurer serverCodecConfigurer) {
        super(errorAttributes, webProperties.getResources(), applicationContext);
        setMessageReaders(serverCodecConfigurer.getReaders());
        setMessageWriters(serverCodecConfigurer.getWriters());
    }

    @Override
    protected RouterFunction<ServerResponse> getRoutingFunction(ErrorAttributes errorAttributes) {
        return RouterFunctions.route(this::acceptsXml, this::handleErrorAsXml);
    }

    private boolean acceptsXml(ServerRequest request) {
        return request.headers().accept().contains(MediaType.APPLICATION_XML);
    }

    public Mono<ServerResponse> handleErrorAsXml(ServerRequest request) {
        BodyBuilder builder = ServerResponse.status(HttpStatus.INTERNAL_SERVER_ERROR);
        // ... additional builder calls
        return builder.build();
    }

}
Kotlin
import org.springframework.boot.autoconfigure.web.WebProperties
import org.springframework.boot.autoconfigure.web.reactive.error.AbstractErrorWebExceptionHandler
import org.springframework.boot.web.reactive.error.ErrorAttributes
import org.springframework.context.ApplicationContext
import org.springframework.http.HttpStatus
import org.springframework.http.MediaType
import org.springframework.http.codec.ServerCodecConfigurer
import org.springframework.stereotype.Component
import org.springframework.web.reactive.function.server.RouterFunction
import org.springframework.web.reactive.function.server.RouterFunctions
import org.springframework.web.reactive.function.server.ServerRequest
import org.springframework.web.reactive.function.server.ServerResponse
import reactor.core.publisher.Mono

@Component
class MyErrorWebExceptionHandler(
        errorAttributes: ErrorAttributes, webProperties: WebProperties,
        applicationContext: ApplicationContext, serverCodecConfigurer: ServerCodecConfigurer
) : AbstractErrorWebExceptionHandler(errorAttributes, webProperties.resources, applicationContext) {

    init {
        setMessageReaders(serverCodecConfigurer.readers)
        setMessageWriters(serverCodecConfigurer.writers)
    }

    override fun getRoutingFunction(errorAttributes: ErrorAttributes): RouterFunction<ServerResponse> {
        return RouterFunctions.route(this::acceptsXml, this::handleErrorAsXml)
    }

    private fun acceptsXml(request: ServerRequest): Boolean {
        return request.headers().accept().contains(MediaType.APPLICATION_XML)
    }

    fun handleErrorAsXml(request: ServerRequest): Mono<ServerResponse> {
        val builder = ServerResponse.status(HttpStatus.INTERNAL_SERVER_ERROR)
        // ... additional builder calls
        return builder.build()
    }

}

为了获得更完整的图片，您还可以直接 subclass 并覆盖特定方法。DefaultErrorWebExceptionHandlerspring-doc.cn

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

自定义错误页面

如果要显示给定状态代码的自定义 HTML 错误页面，则可以添加解析自 的视图，例如，通过将文件添加到目录。 错误页面可以是静态 HTML（即，添加到任何静态资源目录下），也可以是用模板构建的。 文件名应为确切的状态代码、状态代码系列掩码，如果没有其他匹配项，则为默认值。 请注意，默认错误视图的路径是 ，而使用 Spring MVC 时，默认错误视图是 。error/*/errorerrorerror/errorerrorspring-doc.cn

例如，要映射到静态 HTML 文件，您的目录结构将如下所示：404spring-doc.cn

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

要使用 Mustache 模板映射所有错误，您的目录结构将如下所示：5xxspring-doc.cn

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

2.1.8. Web 过滤器

Spring WebFlux 提供了一个接口，可以实现该接口来过滤 HTTP 请求-响应交换。 在应用程序上下文中找到的 bean 将自动用于过滤每个交换。WebFilterWebFilterspring-doc.cn

如果过滤器的顺序很重要，则可以实现或使用 . Spring Boot 自动配置可以为您配置 Web 过滤器。 执行此操作时，将使用下表中显示的订单：Ordered@Orderspring-doc.cn

Web 过滤器 次序

WebFilterChainProxy（Spring Security性）spring-doc.cn

-100spring-doc.cn

HttpExchangesWebFilterspring-doc.cn

Ordered.LOWEST_PRECEDENCE - 10spring-doc.cn

2.2. 嵌入式反应式服务器支持

Spring Boot 包括对以下嵌入式反应式 Web 服务器的支持：Reactor Netty、Tomcat、Jetty 和 Undertow。 大多数开发人员使用适当的 “Starter” 来获取完全配置的实例。 默认情况下，嵌入式服务器在端口 8080 上侦听 HTTP 请求。spring-doc.cn

2.2.1. 自定义反应式服务器

常见的反应式 Web 服务器设置可以使用 Spring 属性进行配置。 通常，您将在 or 文件中定义属性。Environmentapplication.propertiesapplication.yamlspring-doc.cn

常见的服务器设置包括：spring-doc.cn

Spring Boot 会尽可能多地公开通用设置，但这并不总是可能的。 对于这些情况，专用命名空间（如）提供特定于服务器的自定义。server.netty.*spring-doc.cn

有关完整列表，请参阅 ServerProperties 类。
编程自定义

如果需要以编程方式配置反应式 Web 服务器，则可以注册实现该接口的 Spring Bean。 提供对 的访问，其中包括许多自定义 setter 方法。 以下示例显示了以编程方式设置端口：WebServerFactoryCustomizerWebServerFactoryCustomizerConfigurableReactiveWebServerFactoryspring-doc.cn

Java
import org.springframework.boot.web.reactive.server.ConfigurableReactiveWebServerFactory;
import org.springframework.boot.web.server.WebServerFactoryCustomizer;
import org.springframework.stereotype.Component;

@Component
public class MyWebServerFactoryCustomizer implements WebServerFactoryCustomizer<ConfigurableReactiveWebServerFactory> {

    @Override
    public void customize(ConfigurableReactiveWebServerFactory server) {
        server.setPort(9000);
    }

}
Kotlin
import org.springframework.boot.web.server.WebServerFactoryCustomizer
import org.springframework.boot.web.reactive.server.ConfigurableReactiveWebServerFactory
import org.springframework.stereotype.Component

@Component
class MyWebServerFactoryCustomizer : WebServerFactoryCustomizer<ConfigurableReactiveWebServerFactory> {

    override fun customize(server: ConfigurableReactiveWebServerFactory) {
        server.setPort(9000)
    }

}

JettyReactiveWebServerFactory、、 和 是专用变体，分别具有 Jetty、Reactor Netty、Tomcat 和 Undertow 的其他自定义 setter 方法。 以下示例显示了如何自定义以提供对 Reactor Netty 特定配置选项的访问：NettyReactiveWebServerFactoryTomcatReactiveWebServerFactoryUndertowReactiveWebServerFactoryConfigurableReactiveWebServerFactoryNettyReactiveWebServerFactoryspring-doc.cn

Java
import java.time.Duration;

import org.springframework.boot.web.embedded.netty.NettyReactiveWebServerFactory;
import org.springframework.boot.web.server.WebServerFactoryCustomizer;
import org.springframework.stereotype.Component;

@Component
public class MyNettyWebServerFactoryCustomizer implements WebServerFactoryCustomizer<NettyReactiveWebServerFactory> {

    @Override
    public void customize(NettyReactiveWebServerFactory factory) {
        factory.addServerCustomizers((server) -> server.idleTimeout(Duration.ofSeconds(20)));
    }

}
Kotlin
import org.springframework.boot.web.embedded.netty.NettyReactiveWebServerFactory
import org.springframework.boot.web.server.WebServerFactoryCustomizer
import org.springframework.stereotype.Component
import java.time.Duration

@Component
class MyNettyWebServerFactoryCustomizer : WebServerFactoryCustomizer<NettyReactiveWebServerFactory> {

    override fun customize(factory: NettyReactiveWebServerFactory) {
        factory.addServerCustomizers({ server -> server.idleTimeout(Duration.ofSeconds(20)) })
    }

}
直接自定义 ConfigurableReactiveWebServerFactory

对于需要您扩展的更高级的用例，您可以自己公开此类 bean。ReactiveWebServerFactoryspring-doc.cn

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

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

2.3. 反应式服务器资源配置

在自动配置 Reactor Netty 或 Jetty 服务器时， Spring Boot 将创建特定的 bean，这些 bean 将向服务器实例提供 HTTP 资源：或 .ReactorResourceFactoryJettyResourceFactoryspring-doc.cn

默认情况下，这些资源也将与 Reactor Netty 和 Jetty 客户端共享，以获得最佳性能，前提是：spring-doc.cn

  • 相同的技术用于 Server 和 Client 端spring-doc.cn

  • 客户端实例是使用 Spring Boot 自动配置的 bean 构建的WebClient.Builderspring-doc.cn

开发人员可以通过提供自定义或 bean 来覆盖 Jetty 和 Reactor Netty 的资源配置——这将应用于客户端和服务器。ReactorResourceFactoryJettyResourceFactoryspring-doc.cn

您可以在 WebClient 运行时 部分了解有关客户端资源配置的更多信息。spring-doc.cn

3. 优雅关机

所有四个嵌入式 Web 服务器（Jetty、Reactor Netty、Tomcat 和 Undertow）以及反应式和基于 servlet 的 Web 应用程序都支持正常关闭。 它是作为关闭应用程序上下文的一部分发生的，并且在停止 bean 的最早阶段执行。 此停止处理使用超时，该超时提供宽限期，在此期间将允许完成现有请求，但不允许新请求。SmartLifecyclespring-doc.cn

不允许新请求的确切方式因所使用的 Web 服务器而异。 实现可能会在网络层停止接受请求，或者它们可能会返回具有特定 HTTP 状态代码或 HTTP 标头的响应。 使用持久连接还可以更改停止接受请求的方式。spring-doc.cn

要了解有关 Web 服务器使用的特定方法的更多信息，请参阅 TomcatWebServer、NettyWebServer、JettyWebServer 或 UndertowWebServer 的 javadoc。shutDownGracefully

Jetty、Reactor Netty 和 Tomcat 将停止在网络层接受新请求。 Undertow 将接受新连接，但会立即响应服务不可用 （503） 响应。spring-doc.cn

要启用正常关闭，请配置该属性，如以下示例所示：server.shutdownspring-doc.cn

性能
server.shutdown=graceful
Yaml
server:
  shutdown: "graceful"

要配置超时期限，请配置属性，如以下示例所示：spring.lifecycle.timeout-per-shutdown-phasespring-doc.cn

性能
spring.lifecycle.timeout-per-shutdown-phase=20s
Yaml
spring:
  lifecycle:
    timeout-per-shutdown-phase: "20s"
如果 IDE 没有发送正确的信号，则 IDE 中的正常关闭可能无法正常工作。 有关更多详细信息，请参阅 IDE 的文档。SIGTERM

4. Spring Security

如果 Spring Security 在 Classpath 上，则默认情况下 Web 应用程序是安全的。 Spring Boot 依赖于 Spring Security 的内容协商策略来确定是使用 or 。 要向 Web 应用程序添加方法级安全性，您还可以使用所需的设置进行添加。 其他信息可以在 Spring Security Reference Guide 中找到。httpBasicformLogin@EnableGlobalMethodSecurityspring-doc.cn

默认只有一个用户。 用户名为 ，密码是随机的，在应用程序启动时以 WARN 级别打印，如以下示例所示：UserDetailsServiceuserspring-doc.cn

Using generated security password: 78fa095d-3f4c-48b1-ad50-e24c31d5cf35

This generated password is for development use only. Your security configuration must be updated before running your application in production.
如果您微调日志记录配置，请确保将 category 设置为 log -level messages。 否则，不会打印默认密码。org.springframework.boot.autoconfigure.securityWARN

您可以通过提供 和 来更改用户名和密码。spring.security.user.namespring.security.user.passwordspring-doc.cn

默认情况下，您在 Web 应用程序中获得的基本功能包括：spring-doc.cn

  • 具有内存存储的 Bean（或在 WebFlux 应用程序的情况下）和具有生成密码的单个用户（有关用户的属性，请参见SecurityProperties.User）。UserDetailsServiceReactiveUserDetailsServicespring-doc.cn

  • 整个应用程序（如果 actuator 在 Classpath 上，则包括 actuator 端点）的基于表单的登录或 HTTP Basic 安全性（取决于请求中的 Headers）。Acceptspring-doc.cn

  • A 用于发布身份验证事件。DefaultAuthenticationEventPublisherspring-doc.cn

您可以通过为其添加 bean 来提供不同的 Bean。AuthenticationEventPublisherspring-doc.cn

4.1. MVC 安全性

默认安全配置在 和 中实现。 导入以实现 Web 安全并配置身份验证，这在非 Web 应用程序中也相关。SecurityAutoConfigurationUserDetailsServiceAutoConfigurationSecurityAutoConfigurationSpringBootWebSecurityConfigurationUserDetailsServiceAutoConfigurationspring-doc.cn

要完全关闭默认的 Web 应用程序安全配置，包括 Actuator 安全性，或者组合多个 Spring Security 组件，例如 OAuth2 客户端和资源服务器，请添加 Bean 类型（这样做不会禁用配置）。 要同时关闭配置，请添加 、 、 或 类型的 bean 。SecurityFilterChainUserDetailsServiceUserDetailsServiceUserDetailsServiceAuthenticationProviderAuthenticationManagerspring-doc.cn

will 的自动配置还会退出以下任何 Spring Security 模块都在 Classpath 上：UserDetailsServicespring-doc.cn

要除了这些依赖项中的一个或多个之外，还要使用，请定义您自己的 Bean。UserDetailsServiceInMemoryUserDetailsManagerspring-doc.cn

可以通过添加自定义 Bean 来覆盖访问规则。 Spring Boot 提供了方便的方法，可用于覆盖 actuator endpoints 和 static 资源的访问规则。 可用于创建基于属性的 。 可用于在常用位置创建 for 资源。SecurityFilterChainEndpointRequestRequestMatchermanagement.endpoints.web.base-pathPathRequestRequestMatcherspring-doc.cn

4.2. WebFlux 安全

与 Spring MVC 应用程序类似，您可以通过添加依赖项来保护 WebFlux 应用程序。 默认安全配置在 和 中实现。 导入以实现 Web 安全并配置身份验证，这在非 Web 应用程序中也相关。spring-boot-starter-securityReactiveSecurityAutoConfigurationUserDetailsServiceAutoConfigurationReactiveSecurityAutoConfigurationWebFluxSecurityConfigurationUserDetailsServiceAutoConfigurationspring-doc.cn

要完全关闭默认的 Web 应用程序安全配置，包括 Actuator 安全性，请添加 type 的 bean（这样做不会禁用配置）。 要同时关闭配置，请添加 或 类型的 bean。WebFilterChainProxyUserDetailsServiceUserDetailsServiceReactiveUserDetailsServiceReactiveAuthenticationManagerspring-doc.cn

当以下任何 Spring Security 模块位于 Classpath 上时，自动配置也将退缩：spring-doc.cn

要除了这些依赖项中的一个或多个之外，还要使用，请定义您自己的 Bean。ReactiveUserDetailsServiceMapReactiveUserDetailsServicespring-doc.cn

可以通过添加自定义 bean 来配置访问规则和多个 Spring Security 组件（如 OAuth 2 客户端和资源服务器）的使用。 Spring Boot 提供了方便的方法，可用于覆盖 actuator endpoints 和 static 资源的访问规则。 可用于创建基于属性的 。SecurityWebFilterChainEndpointRequestServerWebExchangeMatchermanagement.endpoints.web.base-pathspring-doc.cn

PathRequest可用于在常用位置创建 for 资源。ServerWebExchangeMatcherspring-doc.cn

例如，您可以通过添加如下内容来自定义您的安全配置：spring-doc.cn

Java
import org.springframework.boot.autoconfigure.security.reactive.PathRequest;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.web.server.ServerHttpSecurity;
import org.springframework.security.web.server.SecurityWebFilterChain;

import static org.springframework.security.config.Customizer.withDefaults;

@Configuration(proxyBeanMethods = false)
public class MyWebFluxSecurityConfiguration {

    @Bean
    public SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
        http.authorizeExchange((exchange) -> {
            exchange.matchers(PathRequest.toStaticResources().atCommonLocations()).permitAll();
            exchange.pathMatchers("/foo", "/bar").authenticated();
        });
        http.formLogin(withDefaults());
        return http.build();
    }

}
Kotlin
import org.springframework.boot.autoconfigure.security.reactive.PathRequest
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.security.config.Customizer.withDefaults
import org.springframework.security.config.web.server.ServerHttpSecurity
import org.springframework.security.web.server.SecurityWebFilterChain

@Configuration(proxyBeanMethods = false)
class MyWebFluxSecurityConfiguration {

    @Bean
    fun springSecurityFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
        http.authorizeExchange { spec ->
            spec.matchers(PathRequest.toStaticResources().atCommonLocations()).permitAll()
            spec.pathMatchers("/foo", "/bar").authenticated()
        }
        http.formLogin(withDefaults())
        return http.build()
    }

}

4.3. OAuth2

OAuth2 是 Spring 支持的广泛使用的授权框架。spring-doc.cn

4.3.1. 客户端

如果您在 Classpath 上，则可以利用一些自动配置来设置 OAuth2/Open ID Connect 客户端。 此配置利用 下的属性。 相同的属性适用于 servlet 和 reactive 应用程序。spring-security-oauth2-clientOAuth2ClientPropertiesspring-doc.cn

您可以在前缀下注册多个 OAuth2 客户端和提供程序，如以下示例所示：spring.security.oauth2.clientspring-doc.cn

性能
spring.security.oauth2.client.registration.my-login-client.client-id=abcd
spring.security.oauth2.client.registration.my-login-client.client-secret=password
spring.security.oauth2.client.registration.my-login-client.client-name=Client for OpenID Connect
spring.security.oauth2.client.registration.my-login-client.provider=my-oauth-provider
spring.security.oauth2.client.registration.my-login-client.scope=openid,profile,email,phone,address
spring.security.oauth2.client.registration.my-login-client.redirect-uri={baseUrl}/login/oauth2/code/{registrationId}
spring.security.oauth2.client.registration.my-login-client.client-authentication-method=client_secret_basic
spring.security.oauth2.client.registration.my-login-client.authorization-grant-type=authorization_code

spring.security.oauth2.client.registration.my-client-1.client-id=abcd
spring.security.oauth2.client.registration.my-client-1.client-secret=password
spring.security.oauth2.client.registration.my-client-1.client-name=Client for user scope
spring.security.oauth2.client.registration.my-client-1.provider=my-oauth-provider
spring.security.oauth2.client.registration.my-client-1.scope=user
spring.security.oauth2.client.registration.my-client-1.redirect-uri={baseUrl}/authorized/user
spring.security.oauth2.client.registration.my-client-1.client-authentication-method=client_secret_basic
spring.security.oauth2.client.registration.my-client-1.authorization-grant-type=authorization_code

spring.security.oauth2.client.registration.my-client-2.client-id=abcd
spring.security.oauth2.client.registration.my-client-2.client-secret=password
spring.security.oauth2.client.registration.my-client-2.client-name=Client for email scope
spring.security.oauth2.client.registration.my-client-2.provider=my-oauth-provider
spring.security.oauth2.client.registration.my-client-2.scope=email
spring.security.oauth2.client.registration.my-client-2.redirect-uri={baseUrl}/authorized/email
spring.security.oauth2.client.registration.my-client-2.client-authentication-method=client_secret_basic
spring.security.oauth2.client.registration.my-client-2.authorization-grant-type=authorization_code

spring.security.oauth2.client.provider.my-oauth-provider.authorization-uri=https://my-auth-server.com/oauth2/authorize
spring.security.oauth2.client.provider.my-oauth-provider.token-uri=https://my-auth-server.com/oauth2/token
spring.security.oauth2.client.provider.my-oauth-provider.user-info-uri=https://my-auth-server.com/userinfo
spring.security.oauth2.client.provider.my-oauth-provider.user-info-authentication-method=header
spring.security.oauth2.client.provider.my-oauth-provider.jwk-set-uri=https://my-auth-server.com/oauth2/jwks
spring.security.oauth2.client.provider.my-oauth-provider.user-name-attribute=name
Yaml
spring:
  security:
    oauth2:
      client:
        registration:
          my-login-client:
            client-id: "abcd"
            client-secret: "password"
            client-name: "Client for OpenID Connect"
            provider: "my-oauth-provider"
            scope: "openid,profile,email,phone,address"
            redirect-uri: "{baseUrl}/login/oauth2/code/{registrationId}"
            client-authentication-method: "client_secret_basic"
            authorization-grant-type: "authorization_code"

          my-client-1:
            client-id: "abcd"
            client-secret: "password"
            client-name: "Client for user scope"
            provider: "my-oauth-provider"
            scope: "user"
            redirect-uri: "{baseUrl}/authorized/user"
            client-authentication-method: "client_secret_basic"
            authorization-grant-type: "authorization_code"

          my-client-2:
            client-id: "abcd"
            client-secret: "password"
            client-name: "Client for email scope"
            provider: "my-oauth-provider"
            scope: "email"
            redirect-uri: "{baseUrl}/authorized/email"
            client-authentication-method: "client_secret_basic"
            authorization-grant-type: "authorization_code"

        provider:
          my-oauth-provider:
            authorization-uri: "https://my-auth-server.com/oauth2/authorize"
            token-uri: "https://my-auth-server.com/oauth2/token"
            user-info-uri: "https://my-auth-server.com/userinfo"
            user-info-authentication-method: "header"
            jwk-set-uri: "https://my-auth-server.com/oauth2/jwks"
            user-name-attribute: "name"

对于支持 OpenID Connect 发现的 OpenID Connect 提供商，可以进一步简化配置。 提供程序需要配置一个 which ，这是它断言为其颁发者标识符的 URI。 例如，如果提供的是 “https://example.com”，则将向 “https://example.com/.well-known/openid-configuration” 发出“OpenID 提供程序配置请求”。 结果应为“OpenID Provider Configuration Response”。 以下示例显示了如何使用 OpenID Connect 提供程序配置：issuer-uriissuer-uriissuer-urispring-doc.cn

性能
spring.security.oauth2.client.provider.oidc-provider.issuer-uri=https://dev-123456.oktapreview.com/oauth2/default/
Yaml
spring:
  security:
    oauth2:
      client:
        provider:
          oidc-provider:
            issuer-uri: "https://dev-123456.oktapreview.com/oauth2/default/"

默认情况下，Spring Security 仅处理匹配 的 URL。 如果要自定义 以使用不同的模式，则需要提供配置来处理该自定义模式。 例如，对于 servlet 应用程序，您可以添加自己的应用程序，如下所示：OAuth2LoginAuthenticationFilter/login/oauth2/code/*redirect-uriSecurityFilterChainspring-doc.cn

Java
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.web.SecurityFilterChain;

@Configuration(proxyBeanMethods = false)
@EnableWebSecurity
public class MyOAuthClientConfiguration {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests((requests) -> requests
                .anyRequest().authenticated()
            )
            .oauth2Login((login) -> login
                .redirectionEndpoint((endpoint) -> endpoint
                    .baseUri("/login/oauth2/callback/*")
                )
            );
        return http.build();
    }

}
Kotlin
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.security.config.annotation.web.builders.HttpSecurity
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity
import org.springframework.security.config.annotation.web.invoke
import org.springframework.security.web.SecurityFilterChain

@Configuration(proxyBeanMethods = false)
@EnableWebSecurity
open class MyOAuthClientConfiguration {

    @Bean
    open fun securityFilterChain(http: HttpSecurity): SecurityFilterChain {
        http {
            authorizeHttpRequests {
                authorize(anyRequest, authenticated)
            }
            oauth2Login {
                redirectionEndpoint {
                    baseUri = "/login/oauth2/callback/*"
                }
            }
        }
        return http.build()
    }

}
Spring Boot 会自动配置 Spring Security 用于 Management 客户端注册的 an。 它的功能有限，我们建议仅将其用于开发环境。 对于生产环境，请考虑使用 或创建自己的 .InMemoryOAuth2AuthorizedClientServiceInMemoryOAuth2AuthorizedClientServiceJdbcOAuth2AuthorizedClientServiceOAuth2AuthorizedClientService
常见提供商的 OAuth2 客户端注册

对于常见的 OAuth2 和 OpenID 提供商，包括 Google、Github、Facebook 和 Okta，我们提供了一组提供商默认值（分别为、、、 和 ）。googlegithubfacebookoktaspring-doc.cn

如果您不需要自定义这些提供程序，则可以将该属性设置为需要推断 defaults 的属性。 此外，如果 Client 端注册的密钥与默认支持的提供程序匹配，则 Spring Boot 也会推断这一点。providerspring-doc.cn

换句话说，以下示例中的两个配置使用 Google 提供程序：spring-doc.cn

性能
spring.security.oauth2.client.registration.my-client.client-id=abcd
spring.security.oauth2.client.registration.my-client.client-secret=password
spring.security.oauth2.client.registration.my-client.provider=google
spring.security.oauth2.client.registration.google.client-id=abcd
spring.security.oauth2.client.registration.google.client-secret=password
Yaml
spring:
  security:
    oauth2:
      client:
        registration:
          my-client:
            client-id: "abcd"
            client-secret: "password"
            provider: "google"
          google:
            client-id: "abcd"
            client-secret: "password"

4.3.2. 资源服务器

如果你在 Classpath 上，Spring Boot 可以设置一个 OAuth2 资源服务器。 对于 JWT 配置，需要指定 JWK Set URI 或 OIDC Issuer URI，如以下示例所示：spring-security-oauth2-resource-serverspring-doc.cn

性能
spring.security.oauth2.resourceserver.jwt.jwk-set-uri=https://example.com/oauth2/default/v1/keys
Yaml
spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          jwk-set-uri: "https://example.com/oauth2/default/v1/keys"
性能
spring.security.oauth2.resourceserver.jwt.issuer-uri=https://dev-123456.oktapreview.com/oauth2/default/
Yaml
spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: "https://dev-123456.oktapreview.com/oauth2/default/"
如果授权服务器不支持 JWK 集 URI，则可以使用用于验证 JWT 签名的公钥来配置资源服务器。 这可以使用 property 来完成，其中值需要指向包含 PEM 编码的 x509 格式的公钥的文件。spring.security.oauth2.resourceserver.jwt.public-key-location

该属性可用于指定 JWT 中 aud 声明的预期值。 例如，要求 JWT 包含值为 ：spring.security.oauth2.resourceserver.jwt.audiencesmy-audiencespring-doc.cn

性能
spring.security.oauth2.resourceserver.jwt.audiences[0]=my-audience
Yaml
spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          audiences:
            - "my-audience"

相同的属性适用于 servlet 和响应式应用程序。 或者，您可以为 servlet 应用程序定义自己的 bean 或为响应式应用程序定义自己的 bean。JwtDecoderReactiveJwtDecoderspring-doc.cn

如果使用不透明令牌而不是 JWT，您可以配置以下属性以通过自省验证令牌：spring-doc.cn

性能
spring.security.oauth2.resourceserver.opaquetoken.introspection-uri=https://example.com/check-token
spring.security.oauth2.resourceserver.opaquetoken.client-id=my-client-id
spring.security.oauth2.resourceserver.opaquetoken.client-secret=my-client-secret
Yaml
spring:
  security:
    oauth2:
      resourceserver:
        opaquetoken:
          introspection-uri: "https://example.com/check-token"
          client-id: "my-client-id"
          client-secret: "my-client-secret"

同样，相同的属性适用于 servlet 和 reactive 应用程序。 或者，您可以为 servlet 应用程序定义自己的 bean 或为响应式应用程序定义自己的 bean。OpaqueTokenIntrospectorReactiveOpaqueTokenIntrospectorspring-doc.cn

4.3.3. 授权服务器

如果你在 Classpath 上，你可以利用一些自动配置来设置基于 Servlet 的 OAuth2 授权服务器。spring-security-oauth2-authorization-serverspring-doc.cn

您可以在前缀下注册多个 OAuth2 客户端，如以下示例所示：spring.security.oauth2.authorizationserver.clientspring-doc.cn

性能
spring.security.oauth2.authorizationserver.client.my-client-1.registration.client-id=abcd
spring.security.oauth2.authorizationserver.client.my-client-1.registration.client-secret={noop}secret1
spring.security.oauth2.authorizationserver.client.my-client-1.registration.client-authentication-methods[0]=client_secret_basic
spring.security.oauth2.authorizationserver.client.my-client-1.registration.authorization-grant-types[0]=authorization_code
spring.security.oauth2.authorizationserver.client.my-client-1.registration.authorization-grant-types[1]=refresh_token
spring.security.oauth2.authorizationserver.client.my-client-1.registration.redirect-uris[0]=https://my-client-1.com/login/oauth2/code/abcd
spring.security.oauth2.authorizationserver.client.my-client-1.registration.redirect-uris[1]=https://my-client-1.com/authorized
spring.security.oauth2.authorizationserver.client.my-client-1.registration.scopes[0]=openid
spring.security.oauth2.authorizationserver.client.my-client-1.registration.scopes[1]=profile
spring.security.oauth2.authorizationserver.client.my-client-1.registration.scopes[2]=email
spring.security.oauth2.authorizationserver.client.my-client-1.registration.scopes[3]=phone
spring.security.oauth2.authorizationserver.client.my-client-1.registration.scopes[4]=address
spring.security.oauth2.authorizationserver.client.my-client-1.require-authorization-consent=true
spring.security.oauth2.authorizationserver.client.my-client-2.registration.client-id=efgh
spring.security.oauth2.authorizationserver.client.my-client-2.registration.client-secret={noop}secret2
spring.security.oauth2.authorizationserver.client.my-client-2.registration.client-authentication-methods[0]=client_secret_jwt
spring.security.oauth2.authorizationserver.client.my-client-2.registration.authorization-grant-types[0]=client_credentials
spring.security.oauth2.authorizationserver.client.my-client-2.registration.scopes[0]=user.read
spring.security.oauth2.authorizationserver.client.my-client-2.registration.scopes[1]=user.write
spring.security.oauth2.authorizationserver.client.my-client-2.jwk-set-uri=https://my-client-2.com/jwks
spring.security.oauth2.authorizationserver.client.my-client-2.token-endpoint-authentication-signing-algorithm=RS256
Yaml
spring:
  security:
    oauth2:
      authorizationserver:
        client:
          my-client-1:
            registration:
              client-id: "abcd"
              client-secret: "{noop}secret1"
              client-authentication-methods:
                - "client_secret_basic"
              authorization-grant-types:
                - "authorization_code"
                - "refresh_token"
              redirect-uris:
                - "https://my-client-1.com/login/oauth2/code/abcd"
                - "https://my-client-1.com/authorized"
              scopes:
                - "openid"
                - "profile"
                - "email"
                - "phone"
                - "address"
            require-authorization-consent: true
          my-client-2:
            registration:
              client-id: "efgh"
              client-secret: "{noop}secret2"
              client-authentication-methods:
                - "client_secret_jwt"
              authorization-grant-types:
                - "client_credentials"
              scopes:
                - "user.read"
                - "user.write"
            jwk-set-uri: "https://my-client-2.com/jwks"
            token-endpoint-authentication-signing-algorithm: "RS256"
该属性的格式必须与配置的 . 的默认实例是通过 创建的。client-secretPasswordEncoderPasswordEncoderPasswordEncoderFactories.createDelegatingPasswordEncoder()

Spring Boot 为 Spring Authorization Server 提供的自动配置旨在快速入门。 大多数应用程序都需要定制，并且希望定义多个 bean 以覆盖自动配置。spring-doc.cn

可以将以下组件定义为 bean 以覆盖特定于 Spring Authorization Server 的自动配置：spring-doc.cn

Spring Boot 自动配置 Spring Authorization Server 用于管理已注册客户端的 Client 端。 它的功能有限，我们建议仅将其用于开发环境。 对于生产环境，请考虑使用 或创建自己的 .InMemoryRegisteredClientRepositoryInMemoryRegisteredClientRepositoryJdbcRegisteredClientRepositoryRegisteredClientRepository

其他信息可以在 Spring Authorization Server Reference Guide 的 Getting Started 章节中找到。spring-doc.cn

4.4. SAML 2.0

4.4.1. 依赖方

如果您在 Classpath 上，则可以利用一些自动配置来设置 SAML 2.0 依赖方。 此配置利用 下的属性。spring-security-saml2-service-providerSaml2RelyingPartyPropertiesspring-doc.cn

信赖方注册表示身份提供程序 （IDP） 和服务提供商 （SP） 之间的配对配置。 您可以在前缀下注册多个信赖方，如以下示例所示：spring.security.saml2.relyingpartyspring-doc.cn

性能
spring.security.saml2.relyingparty.registration.my-relying-party1.signing.credentials[0].private-key-location=path-to-private-key
spring.security.saml2.relyingparty.registration.my-relying-party1.signing.credentials[0].certificate-location=path-to-certificate
spring.security.saml2.relyingparty.registration.my-relying-party1.decryption.credentials[0].private-key-location=path-to-private-key
spring.security.saml2.relyingparty.registration.my-relying-party1.decryption.credentials[0].certificate-location=path-to-certificate
spring.security.saml2.relyingparty.registration.my-relying-party1.singlelogout.url=https://myapp/logout/saml2/slo
spring.security.saml2.relyingparty.registration.my-relying-party1.singlelogout.response-url=https://remoteidp2.slo.url
spring.security.saml2.relyingparty.registration.my-relying-party1.singlelogout.binding=POST
spring.security.saml2.relyingparty.registration.my-relying-party1.assertingparty.verification.credentials[0].certificate-location=path-to-verification-cert
spring.security.saml2.relyingparty.registration.my-relying-party1.assertingparty.entity-id=remote-idp-entity-id1
spring.security.saml2.relyingparty.registration.my-relying-party1.assertingparty.sso-url=https://remoteidp1.sso.url

spring.security.saml2.relyingparty.registration.my-relying-party2.signing.credentials[0].private-key-location=path-to-private-key
spring.security.saml2.relyingparty.registration.my-relying-party2.signing.credentials[0].certificate-location=path-to-certificate
spring.security.saml2.relyingparty.registration.my-relying-party2.decryption.credentials[0].private-key-location=path-to-private-key
spring.security.saml2.relyingparty.registration.my-relying-party2.decryption.credentials[0].certificate-location=path-to-certificate
spring.security.saml2.relyingparty.registration.my-relying-party2.assertingparty.verification.credentials[0].certificate-location=path-to-other-verification-cert
spring.security.saml2.relyingparty.registration.my-relying-party2.assertingparty.entity-id=remote-idp-entity-id2
spring.security.saml2.relyingparty.registration.my-relying-party2.assertingparty.sso-url=https://remoteidp2.sso.url
spring.security.saml2.relyingparty.registration.my-relying-party2.assertingparty.singlelogout.url=https://remoteidp2.slo.url
spring.security.saml2.relyingparty.registration.my-relying-party2.assertingparty.singlelogout.response-url=https://myapp/logout/saml2/slo
spring.security.saml2.relyingparty.registration.my-relying-party2.assertingparty.singlelogout.binding=POST
Yaml
spring:
  security:
    saml2:
      relyingparty:
        registration:
          my-relying-party1:
            signing:
              credentials:
              - private-key-location: "path-to-private-key"
                certificate-location: "path-to-certificate"
            decryption:
              credentials:
              - private-key-location: "path-to-private-key"
                certificate-location: "path-to-certificate"
            singlelogout:
               url: "https://myapp/logout/saml2/slo"
               response-url: "https://remoteidp2.slo.url"
               binding: "POST"
            assertingparty:
              verification:
                credentials:
                - certificate-location: "path-to-verification-cert"
              entity-id: "remote-idp-entity-id1"
              sso-url: "https://remoteidp1.sso.url"

          my-relying-party2:
            signing:
              credentials:
              - private-key-location: "path-to-private-key"
                certificate-location: "path-to-certificate"
            decryption:
              credentials:
              - private-key-location: "path-to-private-key"
                certificate-location: "path-to-certificate"
            assertingparty:
              verification:
                credentials:
                - certificate-location: "path-to-other-verification-cert"
              entity-id: "remote-idp-entity-id2"
              sso-url: "https://remoteidp2.sso.url"
              singlelogout:
                url: "https://remoteidp2.slo.url"
                response-url: "https://myapp/logout/saml2/slo"
                binding: "POST"

对于 SAML2 注销，默认情况下， Spring Security 的 并且仅处理 匹配 的 URL。 如果要自定义 AP 发起的注销请求发送到的收件人或 AP 向其发送注销响应的收件人，以使用不同的模式，则需要提供配置来处理该自定义模式。 例如，对于 servlet 应用程序，您可以添加自己的应用程序，如下所示：Saml2LogoutRequestFilterSaml2LogoutResponseFilter/logout/saml2/slourlresponse-urlSecurityFilterChainspring-doc.cn

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;

import static org.springframework.security.config.Customizer.withDefaults;

@Configuration(proxyBeanMethods = false)
public class MySamlRelyingPartyConfiguration {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http.authorizeHttpRequests((requests) -> requests.anyRequest().authenticated());
        http.saml2Login(withDefaults());
        http.saml2Logout((saml2) -> saml2.logoutRequest((request) -> request.logoutUrl("/SLOService.saml2"))
            .logoutResponse((response) -> response.logoutUrl("/SLOService.saml2")));
        return http.build();
    }

}

5. Spring Session

Spring Boot 为各种数据存储提供 Spring Session 自动配置。 在构建 servlet Web 应用程序时，可以自动配置以下存储：spring-doc.cn

此外，Spring Boot for Apache Geode 还提供了使用 Apache Geode 作为会话存储的自动配置。spring-doc.cn

servlet 自动配置取代了使用 .@Enable*HttpSessionspring-doc.cn

如果 Classpath 上存在单个 Spring Session 模块，则 Spring Boot 会自动使用该 store 实现。 如果您有多个实现，则 Spring Boot 使用以下 Sequences 来选择特定实现：spring-doc.cn

  1. Redisspring-doc.cn

  2. JDBCspring-doc.cn

  3. Hazelcastspring-doc.cn

  4. MongoDB 数据库spring-doc.cn

  5. 如果 Redis、JDBC、Hazelcast 和 MongoDB 都不可用，则我们不会配置 .SessionRepositoryspring-doc.cn

在构建反应式 Web 应用程序时，可以自动配置以下 store：spring-doc.cn

反应式自动配置取代了使用 .@Enable*WebSessionspring-doc.cn

与 Servlet 配置类似，如果你有多个实现，Spring Boot 使用以下 Sequences 来选择特定的实现：spring-doc.cn

  1. Redisspring-doc.cn

  2. MongoDB 数据库spring-doc.cn

  3. 如果 Redis 和 MongoDB 都不可用，我们不会配置 .ReactiveSessionRepositoryspring-doc.cn

每个商店都有特定的附加设置。 例如，可以自定义 JDBC 存储的表的名称，如以下示例所示：spring-doc.cn

性能
spring.session.jdbc.table-name=SESSIONS
Yaml
spring:
  session:
    jdbc:
      table-name: "SESSIONS"

要设置会话的超时，可以使用属性。 如果未使用 servlet Web 应用程序设置该属性，则自动配置将回退到 的值。spring.session.timeoutserver.servlet.session.timeoutspring-doc.cn

你可以使用（servlet）或（reactive）来控制 Spring Session 的配置。 这将导致自动配置回退。 然后可以使用 Comments 的属性而不是前面描述的配置属性来配置 Spring Session。@Enable*HttpSession@Enable*WebSessionspring-doc.cn

6. 适用于 GraphQL 的 Spring

如果要构建 GraphQL 应用程序，可以利用 Spring Boot 对 Spring for GraphQL 的自动配置。 Spring for GraphQL 项目基于 GraphQL Java。 您至少需要Starters。 由于 GraphQL 与传输无关，因此您还需要在应用程序中添加一个或多个额外的Starters，以便在 Web 上公开 GraphQL API：spring-boot-starter-graphqlspring-doc.cn

起动机 运输 实现

spring-boot-starter-webspring-doc.cn

HTTP 协议spring-doc.cn

Spring MVCspring-doc.cn

spring-boot-starter-websocketspring-doc.cn

WebSocket 浏览器spring-doc.cn

用于 Servlet 应用程序的 WebSocketspring-doc.cn

spring-boot-starter-webfluxspring-doc.cn

HTTP、WebSocketspring-doc.cn

Spring WebFluxspring-doc.cn

spring-boot-starter-rsocketspring-doc.cn

TCP、WebSocketspring-doc.cn

Reactor Netty 上的 Spring WebFluxspring-doc.cn

6.1. GraphQL 架构

Spring GraphQL 应用程序在启动时需要定义的架构。 默认情况下，您可以在 “.graphqls” 或 “.gqls” 架构文件下编写，Spring Boot 会自动获取它们。 您可以使用 自定义位置，并使用 自定义文件扩展名。src/main/resources/graphql/**spring.graphql.schema.locationsspring.graphql.schema.file-extensionsspring-doc.cn

如果您希望 Spring Boot 检测该位置的所有应用程序模块和依赖项中的 schema 文件， 您可以设置为 （注意前缀）。spring.graphql.schema.locations"classpath*:graphql/**/"classpath*:

在以下部分中，我们将考虑此示例 GraphQL 架构，定义两种类型和两种查询：spring-doc.cn

type Query {
    greeting(name: String! = "Spring"): String!
    project(slug: ID!): Project
}

""" A Project in the Spring portfolio """
type Project {
    """ Unique string id used in URLs """
    slug: ID!
    """ Project name """
    name: String!
    """ URL of the git repository """
    repositoryUrl: String!
    """ Current support status """
    status: ProjectStatus!
}

enum ProjectStatus {
    """ Actively supported by the Spring team """
    ACTIVE
    """ Supported by the community """
    COMMUNITY
    """ Prototype, not officially supported yet  """
    INCUBATING
    """ Project being retired, in maintenance mode """
    ATTIC
    """ End-Of-Lifed """
    EOL
}
默认情况下，架构上将允许现场自省，因为 GraphiQL 等工具需要它。 如果不想公开有关架构的信息，可以通过设置为 来禁用自省。spring.graphql.schema.introspection.enabledfalse

6.2. GraphQL 运行时布线

GraphQL Java 可用于注册自定义标量类型、指令、类型解析程序等。 您可以在 Spring 配置中声明 bean 以访问 . Spring Boot 会检测此类 bean 并将它们添加到 GraphQlSource 构建器中。RuntimeWiring.BuilderDataFetcherRuntimeWiringConfigurerRuntimeWiring.Builderspring-doc.cn

但是，通常，应用程序不会直接实现，而是创建带 Comments 的控制器。 Spring Boot 将自动检测具有带注释的处理程序方法的类，并将它们注册为 s。 以下是带有类的问候查询的示例实现：DataFetcher@ControllerDataFetcher@Controllerspring-doc.cn

Java
import org.springframework.graphql.data.method.annotation.Argument;
import org.springframework.graphql.data.method.annotation.QueryMapping;
import org.springframework.stereotype.Controller;

@Controller
public class GreetingController {

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

}
Kotlin
import org.springframework.graphql.data.method.annotation.Argument
import org.springframework.graphql.data.method.annotation.QueryMapping
import org.springframework.stereotype.Controller

@Controller
class GreetingController {

    @QueryMapping
    fun greeting(@Argument name: String): String {
        return "Hello, $name!"
    }

}

6.3. Querydsl 和 QueryByExample 存储库支持

Spring Data 提供对 Querydsl 和 QueryByExample 存储库的支持。 Spring GraphQL 可以将 Querydsl 和 QueryByExample 存储库配置为 DataFetcher。spring-doc.cn

Spring Data 存储库，注释并扩展了以下之一：@GraphQlRepositoryspring-doc.cn

被 Spring Boot 检测到，并被视为匹配顶级查询的候选对象。DataFetcherspring-doc.cn

6.4. 传输

6.4.1. HTTP 和 WebSocket

默认情况下，GraphQL HTTP 终端节点处于 HTTP POST 状态。 可以使用 自定义路径。/graphqlspring.graphql.pathspring-doc.cn

Spring MVC 和 Spring WebFlux 的 HTTP 端点都由具有 of 的 bean 提供。 如果定义自己的 bean，则可能需要添加适当的 Comments 以确保它们被正确排序。RouterFunction@Order0RouterFunction@Order

默认情况下，GraphQL WebSocket 终端节点处于关闭状态。要启用它：spring-doc.cn

  • 对于 Servlet 应用程序，请添加 WebSocket Startersspring-boot-starter-websocketspring-doc.cn

  • 对于 WebFlux 应用程序，不需要额外的依赖项spring-doc.cn

  • 对于这两者，必须设置 application 属性spring.graphql.websocket.pathspring-doc.cn

Spring GraphQL 提供了一个 Web 拦截模型。 这对于从 HTTP 请求标头中检索信息并在 GraphQL 上下文中设置信息或从同一上下文获取信息并将其写入响应标头非常有用。 使用 Spring Boot，您可以声明一个 bean 以将其注册到 Web 传输中。WebInterceptorspring-doc.cn

Spring MVC 和 Spring WebFlux 支持 CORS（跨域资源共享）请求。 CORS 是 GraphQL 应用程序的 Web 配置的关键部分，这些应用程序可以从使用不同域的浏览器访问。spring-doc.cn

Spring Boot 支持名称空间下的许多 configuration properties;下面是一个简短的配置示例：spring.graphql.cors.*spring-doc.cn

性能
spring.graphql.cors.allowed-origins=https://example.org
spring.graphql.cors.allowed-methods=GET,POST
spring.graphql.cors.max-age=1800s
Yaml
spring:
  graphql:
    cors:
      allowed-origins: "https://example.org"
      allowed-methods: GET,POST
      max-age: 1800s

6.4.2. RSocket

还支持将 RSocket 作为 WebSocket 或 TCP 之上的传输。 配置 RSocket 服务器后，我们可以使用 . 例如，配置该映射意味着我们可以在使用 .spring.graphql.rsocket.mapping"graphql"RSocketGraphQlClientspring-doc.cn

Spring Boot 会自动配置一个 bean，你可以将其注入到组件中：RSocketGraphQlClient.Builder<?>spring-doc.cn

Java
@Component
public class RSocketGraphQlClientExample {

    private final RSocketGraphQlClient graphQlClient;

    public RSocketGraphQlClientExample(RSocketGraphQlClient.Builder<?> builder) {
        this.graphQlClient = builder.tcp("example.spring.io", 8181).route("graphql").build();
    }
Kotlin
@Component
class RSocketGraphQlClientExample(private val builder: RSocketGraphQlClient.Builder<*>) {

然后发送请求：spring-doc.cn

Java
Mono<Book> book = this.graphQlClient.document("{ bookById(id: \"book-1\"){ id name pageCount author } }")
    .retrieve("bookById")
    .toEntity(Book.class);
Kotlin
val book = graphQlClient.document(
    """
    {
        bookById(id: "book-1"){
            id
            name
            pageCount
            author
        }
    }               
    """
)
    .retrieve("bookById").toEntity(Book::class.java)

6.5. 异常处理

Spring GraphQL 使应用程序能够注册一个或多个按顺序调用的 Spring 组件。 Exception 必须解析为对象列表，请参阅 Spring GraphQL 异常处理文档。 Spring Boot 将自动检测 bean 并将其注册到 .DataFetcherExceptionResolvergraphql.GraphQLErrorDataFetcherExceptionResolverGraphQlSource.Builderspring-doc.cn

6.6. GraphiQL 和 Schema 打印机

Spring GraphQL 提供了基础设施，可帮助开发人员使用或开发 GraphQL API。spring-doc.cn

Spring GraphQL 附带一个默认的 GraphiQL 页面，该页面默认公开。 默认情况下，此页面处于禁用状态，可以使用该属性打开。 许多公开此类页面的应用程序将首选自定义版本。 默认实现在开发过程中非常有用，这就是为什么它在开发过程中使用 spring-boot-devtools 自动公开的原因。"/graphiql"spring.graphql.graphiql.enabledspring-doc.cn

您还可以选择在启用该属性时以文本格式公开 GraphQL 架构。/graphql/schemaspring.graphql.schema.printer.enabledspring-doc.cn

7. Spring HATEOAS

如果您开发使用超媒体的 RESTful API，Spring Boot 将为 Spring HATEOAS 提供自动配置，该配置适用于大多数应用程序。 自动配置取代了使用和注册大量 bean 的需要，以简化构建基于超媒体的应用程序，包括一个（用于客户端支持）和一个配置为正确地将响应编组到所需的表示形式。 可以通过设置各种属性进行自定义，如果存在，则通过 Bean 进行自定义。@EnableHypermediaSupportLinkDiscoverersObjectMapperObjectMapperspring.jackson.*Jackson2ObjectMapperBuilderspring-doc.cn

您可以使用 . 请注意，这样做会禁用前面描述的自定义。@EnableHypermediaSupportObjectMapperspring-doc.cn

spring-boot-starter-hateoas特定于 Spring MVC，不应与 Spring WebFlux 结合使用。 为了将 Spring HATEOAS 与 Spring WebFlux 一起使用，您可以添加对 的直接依赖项以及 .org.springframework.hateoas:spring-hateoasspring-boot-starter-webflux

默认情况下，接受的请求将收到响应。 要禁用此行为，请设置并定义 或 配置 Spring HATEOAS 以满足应用程序及其客户端的需求。application/jsonapplication/hal+jsonspring.hateoas.use-hal-as-default-json-media-typefalseHypermediaMappingInformationHalConfigurationspring-doc.cn

8. 下一步要读什么

现在，您应该对如何使用 Spring Boot 开发 Web 应用程序有了很好的了解。 接下来的几节描述了 Spring Boot 如何与各种数据技术、消息传递系统和其他 IO 功能集成。 您可以根据应用程序的需要选择其中任何一个。spring-doc.cn