Spring Boot 中文参考指南-Web

Posted 2023-04-08 阿提说说

Spring Boot 版本 2.7.8

原文：https://docs.spring.io/spring-boot/docs/2.7.8/reference/htmlsingle/
—
Spring Boot 3.x 第一个 GA 版本已于22年底发布，2.7.8 是2.x 的最后一个 GA版本，我觉得一段时间内依然会以2.x为主，该文大部分通过软件翻译，再加上自己的经验理解进行整理和注释，目的用来作为手册查找和知识扫盲。
这篇主要是Spring Boot 参考指南中的“Web”章节

最近发现了一个网站，文档翻译的也行，后续可以看这里《Spring Boot 中文文档》，后续的几章这里也不再更新

Spring Boot 中文参考指南(一)
Spring Boot 中文参考指南(二)-Web
Spring Boot 中文参考指南(三)-Data
Spring Boot 中文参考指南(四)-消息
Spring Boot 中文参考指南(五)-IO
Spring Boot 中文参考指南(六)-容器镜像
Spring Boot 中文参考指南(七)-生产就绪功能
Spring Boot 中文参考指南(八)-部署
Spring Boot 中文参考指南(九)-Spring Boot CLI
Spring Boot 中文参考指南(十)-构建工具
Spring Boot 中文参考指南(十一)-“How-to” 指南
Spring Boot 中文参考指南(十二)-附录

6. Web

Spring Boot 非常适合开发Web应用程序，可以使用Tomcat、Jetty、Undertow 或 Netty 作为HTTP服务器，基于servlet的应用程序使用spring-boot-starter-web模块，响应式的Web应用程序使用spring-boot-starter-webflux。

6.1 Servlet Web 应用

如果你想要构建基于servlet的web应用，可以利用Spring Boot 给Spring MVC 或者 Jersey提供的自动配置。

6.1.1 Spring Web MVC Framework

Spring MVC 允许你创建特定的@Controller 或 @RestController Bean来处理传入的HTTP请求。控制器中的方法通过使用``@RequestMapping`注解映射到HTTP。

如下示例显示了一个典型的提供JSON 数据的@RestController例子：

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

Spring MVC 自动配置

自动配置在Spring的默认配置之上添加了以下功能：

• 包含ContentNegotiatingViewResolver Bean 和 BeanNameViewResolverBean
• 支持服务静态资源，包括支持WebJars（后续介绍）
• 自动注册Converter、GenericConverter、Formatter Bean
• 支持HttpMessageConverters（后续介绍）
• 自动注册MessageCodesResolver(后续介绍)
• 静态index.html支持
• 自动使用ConfigurableWebBindingInitializer bean (后续介绍)

如果你想保留这些Spring Boot MVC 的自定义功能，并进行更多的MVC自定义（拦截器、格式化、视图控制器等），你可以添加自己的WebMvcConfigurer类型的@Configuration类，但不需要添加@EnableWebMvc。

如果想提供RequestMappingHandlerMapping、RequestMappingHandlerAdapter或ExceptionHandlerExceptionResolver的自定义实例，并保留Spring Boot MVC自定义，您可以声明WebMvcRegistrations类型的bean，并使用它来提供这些组件的自定义实例。

如果想完全控制Spring MVC，您可以添加您自己的@Configuration用@EnableWebMvc注解，或者添加您自己的@Configuration-annotated DelegatingWebMvcConfiguration，如@EnableWebMvc的Javadoc中所述。

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

如果您想定制Spring MVC使用的ConversionService，可以提供带有addFormatters方法的WebMvcConfigurer bean。通过此方法，您可以注册任何您喜欢的转换器，也可以委托给ApplicationConversionService上可用的静态方法。

笔者注：

Spring MVC自动配置由spring-boot-autoconfigure依赖中的WebMvcAutoConfiguration类加载

ContentNegotiatingViewResolver的配置

@Bean
@ConditionalOnBean(ViewResolver.class)
@ConditionalOnMissingBean(name = "viewResolver", value = ContentNegotiatingViewResolver.class)
public ContentNegotiatingViewResolver viewResolver(BeanFactory beanFactory) 
 ContentNegotiatingViewResolver resolver = new ContentNegotiatingViewResolver();
 resolver.setContentNegotiationManager(beanFactory.getBean(ContentNegotiationManager.class));
 // ContentNegotiatingViewResolver 使用其他视图解析器来定位视图，所以应该具有较高的优先级
 reso lver.setOrder(Ordered.HIGHEST_PRECEDENCE);
 return resolver;

ContentNegotiatingViewResolver 本身不解析视图，而是委托给其他的viewResolver

BeanNameViewResolver的配置

@Bean
@ConditionalOnBean(View.class)
@ConditionalOnMissingBean
public BeanNameViewResolver beanNameViewResolver() 
 BeanNameViewResolver resolver = new BeanNameViewResolver();
 resolver.setOrder(Ordered.LOWEST_PRECEDENCE - 10);
 return resolver;

BeanNameViewResolver 用于将视图名称解析为上下文中的bean

WebMvcRegistrations 是一个接口，可以注册WebMvcConfigurationSupport的关键注解，以此来覆盖Spring MVC提供的默认组件

ConversionService 类型转换的服务接口

HttpMessageConverters

Spring MVC 使用HttpMessageConverter接口来转换HTTP请求和响应，开箱即用。例如，对象可以自动转换为JSON或XML(使用Jackson XML 扩展，如果不可用使用JAXB)，默认情况下，字符串使用UTF-8编码。

如果需要自定义转换器，可以使用Spring Boot 的 HttpMessageConverters类，如下所示：

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

在上下文中存在的任何HttpMessageConverter都会添加到转换器列表中，可以用同样的方式覆盖默认转换器。

MessageCodesResolver

Spring MVC 有一个策略来生成错误代码，用于从绑定的错误中渲染错误消息：MessageCodesResolver。如果你设置了spring.mvc.message-codes-resolver-format属性PREFIX_ERROR_CODE或者POSTFIX_ERROR_CODE，Spring Boot 会自动创建一个。

静态内容

默认的，Spring Boot 提供静态内容的路径是类路径的/static或/public或/resources或/META-INF/resources或者ServletContext的根目录。它使用Spring MVC的ResourceHttpRequestHandler处理, 也可以通过添加自己的WebMvcConfigurer并覆盖addResourceHandlers方法来修改。

在独立的web应用程序中，容器的默认servlet未启用，可以使用server.servlet.register-default-servlet属性启用。

默认servlet充当回退，如果Spring决定不处理它，则从ServletContext的根目录中提供内容。大多数时候，这种情况不会发生（除非您修改默认的MVC配置），因为Spring始终可以通过DispatcherServlet处理请求。

默认情况下，资源映射在/**上，但您可以使用spring.mvc.static-path-pattern属性进行调整。例如，将所有资源迁移到/resources/**可以以下操作：

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

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

除了前面提到的“标准”静态资源位置外，还为Webjars 内容做了兼容，如果打包，任何/webjars/**的路径资源将从jar文件中获取。

如果你的应用程序被打包为jar，请勿使用/src/main/webapp目录，因为会被忽略，虽然此目录是一个常见的标准，但它仅用于war 打包。

Spring Boot 还支持Spring MVC 提供的高级资源处理功能，比如缓存破坏或为Webjars提供与版本无关的URL。

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

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

通过在URL中添加散列值，使静态资源缓存破坏，以下配置为所有静态资源都不被缓存，比如<link href="/css/spring-2a2d595e6ed9a0b24f027f2b63b134d6.css"/>。

spring.web.resources.chain.strategy.content.enabled=true
spring.web.resources.chain.strategy.content.paths=/**

由于为Thymelaf和FreeMarker自动配置了ResourceUrlEncodingFilter，资源链接在运行时会在模板中重写。使用JSP时，您应该手动声明此过滤器。目前不自动支持其他模板引擎，但可以使用自定义模板macros/helpers和使用ResourceUrlProvider。

"fixed"策略可以在不更改文件名的情况下载URL中添加静态版本字符串，如下所示：

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

通过这样的配置，javascript模块定位/js/lib/下的资源使用fixed策略（/v12/js/lib/mymodule.js），而其他资源依然使用内容策略(<link href="/css/spring-2a2d595e6ed9a0b24f027f2b63b134d6.css"/>)。

查看WebProperties.Resources,获取更多支持的选项。

此功能已在一篇专门的博客文章和Spring Framework的参考文档中进行了详尽的描述。

欢迎页

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

自定义Favicon

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

路径匹配和内容协商

Spring MVC 可以通过请求路径并将其与应用程序中定义的映射（如，控制器上的@GetMapping注解）来将传入的HTTP请求映射到处理程序。

Spring Boot 默认是禁用后缀匹配模式的，像"GET /projects/spring-boot.json"这样的地址不会跟@GetMapping("/projects/spring-boot")匹配。该功能主要用于不会发送正确的"Accept"头的HTTP客户端。

对于始终不会发送正确的 "Accept"头的客户端，可以不使用后缀匹配，而是使用查询参数，比如GET /projects/spring-boot?format=json 将映射到@GetMapping("/projects/spring-boot")。

spring.mvc.contentnegotiation.favor-parameter=true

或者使用不同的参数名称：

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

大多数媒体类型都支持开箱即用，但也可以定义新的媒体类型。

spring.mvc.contentnegotiation.media-types.markdown=text/markdown

后缀匹配模式已被弃用，并将在未来版本中删除，如果仍然希望使用后缀匹配模式，则需要以下配置：

spring.mvc.contentnegotiation.favor-path-extension=true
spring.mvc.pathmatch.use-suffix-pattern=true

或者，与打开所有后缀模式相比，只支持注册的后缀模式更安全：

spring.mvc.contentnegotiation.favor-path-extension=true
spring.mvc.pathmatch.use-registered-suffix-pattern=true

从Spring Framework 5.3开始，Spring MVC支持几种将请求路径与控制器处理程序匹配的实现策略。它以前只支持AntPathMatcher策略，但现在还提供PathPatternParser。Spring Boot现在提供了一个配置属性来选择新策略：

spring.mvc.pathmatch.matching-strategy=path-pattern-parser

有关此实现的更多详细信息，参考该博客文章。

PathPatternParser是一个优化的实现，但限制了某些路径模式变体的使用，并且与后缀模式匹配（spring.mvc.pathmatch.use-suffix-pattern，spring.mvc.pathmatch.use-registered-suffix-pattern）或将DispatcherServlet映射为servlet前缀（spring.mvc.servlet.path）。

ConfigurableWebBindingInitializer

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

模板引擎

Spring MVC 支持多种模板技术，包括Thymeleaf、FreeMarker和JSP。

• FreeMarker
• Groovy
• Thymeleaf
• Mustache

避免使用JSP，在跟嵌入式servelt容器使用的时候存在一些已知问题。

使用其中一个模板引擎的默认配置，模板自动从src/main/resources/templates获取。

错误处理

默认情况下，Spring Boot 提供一个/error映射，以合理的方式处理所有错误，在servlet容器中它注册为一个"global"错误页。它会在机器客户端产生一个JSON响应包括error、Http状态和异常信息。对于浏览器客户端，会产生一个"whitelabel"错误视图，以HTML格式展现相同的数据（自定义的话，添加一个Vuew来解决error）。

可以通过多个server.error属性来自定义默认错误处理行为。更多配置查看附录。

要完全替换默认的行为，可以实现ErrorController并注册为Bean或者添加ErrorAttributes类型的bean替换内容。

你也可以用@ControllerAdvice来定制JSON文本或异常类型，如下所示：

import javax.servlet.RequestDispatcher;
import javax.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;
    

该示例中，如果MyException是由SomeController所在的包抛出的异常，使用MyErrorBody POJO的JSON代替ErrorAttributes的表示。

在一些情况下，控制器级别处理的错误不会被度量指标记录，通过将处理的异常设置为请求属性，应用程序可以确保此类异常与请求度量一起记录。

import javax.servlet.http.HttpServletRequest;

import org.springframework.boot.web.servlet.error.ErrorAttributes;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.ExceptionHandler;

@Controller
public class MyController 

    @ExceptionHandler(CustomException.class)
    String handleCustomException(HttpServletRequest request, CustomException ex) 
        request.setAttribute(ErrorAttributes.ERROR_ATTRIBUTE, ex);
        return "errorView";
    

自定义错误页

如果要显示一个给定状态码的自定义HTML错误页，可以将文件添加到/error目录。错误页面可以是静态HTML（即，添加到任何静态资源目录下）或者使用模版构建，文件名应该是确切状态代码或序列掩码。

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

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

使用FreeMark模板映射所有5xx错误，结构如下：

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

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

import java.util.Map;

import javax.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;
    

还可以是用常规的 @ExceptionHandler 和 @ControllerAdvice 特性，然后ErrorController会处理

Spring MVC 之外映射错误页

对于不使用Spring MVC的应用程序，可以使用ErrorPageRegistrar接口直接注册ErrorPages。此抽象直接与底层的嵌入式servlet容器一起使用，即使没有Spring MVC DispatcherServlet 也是有效的。

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

如果注册了一个ErrorPage,其路径最终由Filter处理（这在一些非Spring Web框架中很常见，如Jersey和Wicket），那么Filter必须明确注册为ERROR调度器，如以下示例所示：

import java.util.EnumSet;

import javax.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;
    

请注意，默认的FilterRegistrationBean不包括ERROR调度器类型。

WAR部署中的错误处理

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

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

如果您正在使用Spring Security，并希望在错误页面中访问主体，则必须配置Spring Security的过滤器，以便在错误调度中调用。为此，请将spring.security.filter.dispatcher-types属性设置为async, error, forward, request。

CORS支持

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

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

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(