27. 开发网络应用

Spring Boot 非常适合 Web 应用程序开发。您可以使用嵌入式 Tomcat，Jetty 或 Undertow 轻松创建独立的 HTTP 服务器。大多数 Web 应用程序将使用spring-boot-starter-web模块来快速启动和运行。

如果您尚未开发 Spring Boot Web 应用程序，则可以遵循“ Hello World！”。 * Getting started *部分中的示例。

27.1“ Spring Web MVC 框架”

Spring Web MVC 框架(通常简称为“ Spring MVC”)是一个丰富的“模型视图控制器” Web 框架。 Spring MVC 使您可以创建特殊的@Controller或@RestController bean 来处理传入的 HTTP 请求。控制器中的方法使用@RequestMappingCommentsMap 到 HTTP。

这是提供 JSON 数据的典型示例@RestController：

@RestController
@RequestMapping(value="/users")
public class MyRestController {

    @RequestMapping(value="/{user}", method=RequestMethod.GET)
    public User getUser(@PathVariable Long user) {
        // ...
    }

    @RequestMapping(value="/{user}/customers", method=RequestMethod.GET)
    List<Customer> getUserCustomers(@PathVariable Long user) {
        // ...
    }

    @RequestMapping(value="/{user}", method=RequestMethod.DELETE)
    public User deleteUser(@PathVariable Long user) {
        // ...
    }

}

Spring MVC 是核心 Spring Framework 的一部分，详细信息可在reference documentation中获得。 spring.io/guides上还有几本涵盖 Spring MVC 的指南。

27.1.1 Spring MVC 自动配置

Spring Boot 为 Spring MVC 提供了自动配置，可与大多数应用程序完美配合。

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

• 包括ContentNegotiatingViewResolver和BeanNameViewResolverbean。

• 支持提供静态资源，包括对 WebJars 的支持(请参见下文)。

• 自动注册Converter，GenericConverter，Formatterbean。

• 支持HttpMessageConverters(请参见下文)。

• 自动注册MessageCodesResolver(请参见下文)。

• 静态index.html支持。

• 自定义Favicon支持(请参见下文)。

• 自动使用ConfigurableWebBindingInitializer bean(请参见下文)。

如果您想保留 Spring Boot MVC 功能，并且只想添加其他MVC configuration(拦截器，格式化程序，视图控制器等)，则可以添加自己的@Configuration类，类型为WebMvcConfigurerAdapter，但 不 @EnableWebMvc。如果您希望提供RequestMappingHandlerMapping，RequestMappingHandlerAdapter或ExceptionHandlerExceptionResolver的自定义实例，则可以声明一个提供此类组件的WebMvcRegistrationsAdapter实例。

如果要完全控制 Spring MVC，则可以添加自己的@Configuration并以@EnableWebMvcComments。

27.1.2 HttpMessageConverters

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

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

import org.springframework.boot.autoconfigure.web.HttpMessageConverters;
import org.springframework.context.annotation.*;
import org.springframework.http.converter.*;

@Configuration
public class MyConfiguration {

    @Bean
    public HttpMessageConverters customConverters() {
        HttpMessageConverter<?> additional = ...
        HttpMessageConverter<?> another = ...
        return new HttpMessageConverters(additional, another);
    }

}

上下文中存在的任何HttpMessageConverter bean 都将添加到转换器列表中。您也可以通过这种方式覆盖默认转换器。

27.1.3 自定义 JSON 序列化器和反序列化器

如果您正在使用 Jackson 来序列化和反序列化 JSON 数据，则可能需要编写自己的JsonSerializer和JsonDeserializer类。自定义序列化器通常是通过模块在 Jackson 注册，但是 Spring Boot 提供了@JsonComponentComments，这使得直接注册 Spring Bean 更加容易。

您可以直接在JsonSerializer或JsonDeserializer实现中使用@JsonComponent。您也可以在包含序列化器/反序列化器作为内部类的类上使用它。例如：

import java.io.*;
import com.fasterxml.jackson.core.*;
import com.fasterxml.jackson.databind.*;
import org.springframework.boot.jackson.*;

@JsonComponent
public class Example {

    public static class Serializer extends JsonSerializer<SomeObject> {
        // ...
    }

    public static class Deserializer extends JsonDeserializer<SomeObject> {
        // ...
    }

}

ApplicationContext中的所有@JsonComponent bean 都将自动向 Jackson 进行注册，并且由于@JsonComponent被@Component进行了元 Comments，因此通常使用组件扫描规则。

Spring Boot 还提供了JsonObjectSerializer和JsonObjectDeserializerBase Class，它们在序列化对象时为标准 Jackson 版本提供了有用的替代方法。有关详细信息，请参见 Javadoc。

27.1.4 MessageCodesResolver

Spring MVC 有一种生成错误代码的策略，该错误代码用于从绑定错误MessageCodesResolver渲染错误消息。如果您设置spring.mvc.message-codes-resolver.format属性PREFIX_ERROR_CODE或POSTFIX_ERROR_CODE(请参见DefaultMessageCodesResolver.Format中的枚举)，Spring Boot 将为您创建一个。

27.1.5 静态内容

默认情况下，Spring Boot 将从 Classpath 中名为/static(或/public或/resources或/META-INF/resources)的目录或ServletContext的根目录中提供静态内容。它使用 Spring MVC 中的ResourceHttpRequestHandler，因此您可以通过添加自己的WebMvcConfigurerAdapter并覆盖addResourceHandlers方法来修改该行为。

在独立的 Web 应用程序中，还启用了容器中的默认 servlet，并将其用作后备，如果 Spring 决定不处理ServletContext的根，则从ServletContext的根开始提供内容。在大多数情况下，这不会发生(除非您修改默认的 MVC 配置)，因为 Spring 将始终能够通过DispatcherServlet处理请求。

默认情况下，资源 Map 在/**上，但是您可以通过spring.mvc.static-path-pattern对其进行调整。例如，将所有资源重定位到/resources/**可以实现如下：

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

您还可以使用spring.resources.static-locations自定义静态资源位置(用目录位置列表替换默认值)。如果这样做，默认的欢迎页面检测将切换到您的自定义位置。因此，如果启动时您的任何位置都存在index.html，它将成为应用程序的主页。

除了上面的“标准”静态资源位置以外，还对Webjars content进行了特殊处理。如果 jar 文件以 Webjars 格式打包，则将从 jar 文件中提供路径为/webjars/**的任何资源。

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

要对 Webjar 使用版本无关的 URL，只需添加webjars-locator依赖项。然后声明您的 Webjar，以 jQuery 为例，为"/webjars/jquery/dist/jquery.min.js"，结果为"/webjars/jquery/x.y.z/dist/jquery.min.js"，其中x.y.z是 Webjar 版本。

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

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

例如，当使用 JavaScript 模块加载器动态加载资源时，不能重命名文件。这就是为什么其他策略也受支持并且可以组合的原因。一种“固定”策略将在 URL 中添加静态版本字符串，而不更改文件名：

spring.resources.chain.strategy.content.enabled=true
spring.resources.chain.strategy.content.paths=/**
spring.resources.chain.strategy.fixed.enabled=true
spring.resources.chain.strategy.fixed.paths=/js/lib/
spring.resources.chain.strategy.fixed.version=v12

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

有关更多受支持的选项，请参见ResourceProperties。

27.1.6 自定义图标

Spring Boot 在配置的静态内容位置和 Classpath 的根目录(按此 Sequences)中查找favicon.ico。如果存在此类文件，它将自动用作应用程序的收藏夹图标。

27.1.7 ConfigurableWebBindingInitializer

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

27.1.8 模板引擎

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

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

• FreeMarker

• Groovy

• Thymeleaf

• Mustache

当您使用默认配置的这些模板引擎之一时，将从src/main/resources/templates自动提取模板。

27.1.9 错误处理

Spring Boot 默认情况下提供/errorMap，以合理的方式处理所有错误，并且已在 servlet 容器中注册为“全局”错误页面。对于机器 Client 端，它将生成 JSON 响应，其中包含错误，HTTP 状态和异常消息的详细信息。对于浏览器 Client 端，存在一个“ whitelabel”错误视图，该视图以 HTML 格式渲染相同的数据(要对其进行自定义，只需添加一个解析为“错误”的View)。要完全替换默认行为，您可以实现ErrorController并注册该类型的 Bean 定义，或者简单地添加ErrorAttributes类型的 Bean 以使用现有机制但替换其内容。

您还可以定义@ControllerAdvice以自定义 JSON 文档以针对特定的控制器和/或异常类型返回。

@ControllerAdvice(basePackageClasses = FooController.class)
public class FooControllerAdvice extends ResponseEntityExceptionHandler {

    @ExceptionHandler(YourException.class)
    @ResponseBody
    ResponseEntity<?> handleControllerException(HttpServletRequest request, Throwable ex) {
        HttpStatus status = getStatus(request);
        return new ResponseEntity<>(new CustomErrorType(status.value(), ex.getMessage()), status);
    }

    private HttpStatus getStatus(HttpServletRequest request) {
        Integer statusCode = (Integer) request.getAttribute("javax.servlet.error.status_code");
        if (statusCode == null) {
            return HttpStatus.INTERNAL_SERVER_ERROR;
        }
        return HttpStatus.valueOf(statusCode);
    }

}

在上面的示例中，如果在与FooController相同的程序包中定义的控制器抛出YourException，则将使用CustomErrorType POJO 的 json 表示代替ErrorAttributes表示。

自定义错误页面

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

例如，要将404Map 到静态 HTML 文件，您的文件夹结构应如下所示：

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

要使用 FreeMarker 模板 Map 所有5xx个错误，您将具有以下结构：

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

对于更复杂的 Map，您还可以添加实现ErrorViewResolver接口的 bean。

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
        return ...
    }

}

您还可以使用常规的 Spring MVC 功能，例如@ExceptionHandler methods和@ControllerAdvice。 ErrorController然后将拾取所有未处理的异常。

MapSpring MVC 之外的错误页面

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

@Bean
public ErrorPageRegistrar errorPageRegistrar(){
    return new MyErrorPageRegistrar();
}

// ...

private static class MyErrorPageRegistrar implements ErrorPageRegistrar {

    @Override
    public void registerErrorPages(ErrorPageRegistry registry) {
        registry.addErrorPages(new ErrorPage(HttpStatus.BAD_REQUEST, "/400"));
    }

}

N.B.如果您注册的ErrorPage路径最终将由Filter处理(例如，在某些非 Spring Web 框架(如 Jersey 和 Wicket)中很常见)，那么Filter必须明确注册为ERROR调度程序。

@Bean
public FilterRegistrationBean myFilter() {
    FilterRegistrationBean registration = new FilterRegistrationBean();
    registration.setFilter(new MyFilter());
    ...
    registration.setDispatcherTypes(EnumSet.allOf(DispatcherType.class));
    return registration;
}

(默认的FilterRegistrationBean不包括ERROR调度程序类型)。

WebSphere Application Server 上的错误处理

当部署到 Servlet 容器时，Spring Boot 使用其错误页面过滤器将具有错误状态的请求转发到适当的错误页面。如果尚未提交响应，则只能将请求转发到正确的错误页面。缺省情况下，WebSphere Application Server 8.0 和更高版本在成功完成 servlet 的服务方法后提交响应。您应该通过将com.ibm.ws.webcontainer.invokeFlushAfterService设置为false来禁用此行为

10.1.27SpringHATEOAS

如果您正在开发利用超媒体的 RESTful API，Spring Boot 会为 Spring HATEOAS 提供自动配置，该配置可与大多数应用程序很好地兼容。自动配置取代了使用@EnableHypermediaSupport的需要，并注册了许多 bean 以简化构建基于超媒体的应用程序，其中包括LinkDiscoverers(用于 Client 端支持)和ObjectMapper，这些应用程序被配置为将响应正确地编组为所需的表示形式。 ObjectMapper将基于spring.jackson.*属性或Jackson2ObjectMapperBuilder bean(如果存在)进行定制。

您可以使用@EnableHypermediaSupport来控制 Spring HATEOAS 的配置。请注意，这将禁用上述ObjectMapper自定义。

27.1.11 CORS 支持

跨域资源共享(CORS)是由most browsers实现的W3C specification，它使您可以灵活地指定对哪种跨域请求进行授权，而不是使用诸如 IFRAME 或 JSONP 之类的安全性较低，功能较弱的方法。

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

@Configuration
public class MyConfiguration {

    @Bean
    public WebMvcConfigurer corsConfigurer() {
        return new WebMvcConfigurerAdapter() {
            @Override
            public void addCorsMappings(CorsRegistry registry) {
                registry.addMapping("/api/**");
            }
        };
    }
}

27.2 JAX-RS 和 Jersey

如果您更喜欢 REST 端点的 JAX-RS 编程模型，则可以使用可用的实现之一来代替 Spring MVC。如果只在应用程序上下文中将它们的Servlet或Filter注册为@Bean，则 Jersey 1.x 和 Apache CXF 的开箱即用的效果就很好。 Jersey 2.x 具有对 Spring 的本机支持，因此我们在 Spring Boot 中还与启动程序一起为其提供了自动配置支持。

要开始使用 Jersey 2.x，只需将spring-boot-starter-jersey作为依赖项，然后需要一个ResourceConfig类型的@Bean在其中注册所有端点：

@Component
public class JerseyConfig extends ResourceConfig {

    public JerseyConfig() {
        register(Endpoint.class);
    }

}

您还可以注册任意数量的实现ResourceConfigCustomizer的 bean，以进行更高级的自定义。

所有注册的端点应为@Components，并带有 HTTP 资源 Comments(@GET等)，例如

@Component
@Path("/hello")
public class Endpoint {

    @GET
    public String message() {
        return "Hello";
    }

}

由于Endpoint是 Spring @Component，因此其生命周期由 SpringManagement，您可以@Autowired依赖项并使用@Value注入外部配置。默认情况下，Jersey Servlet 将被注册并 Map 到/*。您可以通过将@ApplicationPath添加到ResourceConfig来更改 Map。

默认情况下，Jersey 将在名为jerseyServletRegistration的ServletRegistrationBean类型的@Bean中设置为 Servlet。默认情况下，该 servlet 将被延迟初始化，但是您可以使用spring.jersey.servlet.load-on-startup对其进行自定义。您可以通过创建自己的同名 bean 来禁用或覆盖该 bean。您还可以通过设置spring.jersey.type=filter(在这种情况下要替换或覆盖的@Bean是jerseyFilterRegistration)来使用过滤器而不是 Servlet。 servlet 有一个@Order，您可以用spring.jersey.filter.order设置。可以使用spring.jersey.init.*来为 Servlet 和 Filter 注册都赋予 init 参数，以指定属性 Map。

有一个Jersey sample，因此您可以了解如何进行设置。还有一个Jersey1.xsamples。请注意，在 Jersey 1.x 示例中，已经配置了 spring-boot maven 插件来解压缩某些 Jersey jar，以便可以由 JAX-RS 实现对其进行扫描(因为该示例要求在其Filter注册中对其进行扫描) 。如果将任何 JAX-RS 资源打包为嵌套 jar，则可能需要执行相同的操作。

27.3 嵌入式 Servlet 容器支持

Spring Boot 包括对嵌入式 Tomcat，Jetty 和 Undertow 服务器的支持。大多数开发人员将仅使用适当的“启动器”来获取完全配置的实例。默认情况下，嵌入式服务器将在端口8080上侦听 HTTP 请求。

27.3.1 Servlet，过滤器和侦听器

使用嵌入式 Servlet 容器时，您可以使用 Spring Bean 或扫描 Servlet 组件来注册 Servlet 规范中的 Servlet，过滤器和所有侦听器(例如HttpSessionListener)。

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

任何作为 Spring bean 的Servlet，Filter或 Servlet *Listener实例都将向嵌入式容器注册。如果要在配置过程中引用application.properties中的值，这可能特别方便。

默认情况下，如果上下文仅包含单个 Servlet，它将被 Map 到/。对于多个 Servlet Bean，该 Bean 名称将用作路径前缀。过滤器将 Map 到/*。

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

27.3.2 Servlet 上下文初始化

嵌入式 Servlet 容器将不会直接执行 Servlet 3.0 javax.servlet.ServletContainerInitializer接口或 Spring 的org.springframework.web.WebApplicationInitializer接口。这是一个有意的设计决定，旨在降低旨在在 War 中运行的第三方库破坏 Spring Boot 应用程序的风险。

如果需要在 Spring Boot 应用程序中执行 servlet 上下文初始化，则应该注册一个实现org.springframework.boot.context.embedded.ServletContextInitializer接口的 bean。单个onStartup方法提供对ServletContext的访问，并且可以根据需要轻松地用作现有WebApplicationInitializer的适配器。

扫描 Servlet，过滤器和侦听器

使用嵌入式容器时，可以使用@ServletComponentScan启用@WebServlet，@WebFilter和@WebListenerComments 类的自动注册。

27.3.3 EmbeddedWebApplicationContext

在后台，Spring Boot 使用一种新型的ApplicationContext来支持嵌入式 servlet 容器。 EmbeddedWebApplicationContext是WebApplicationContext的一种特殊类型，它通过搜索单个EmbeddedServletContainerFactory bean 来进行自我引导。通常TomcatEmbeddedServletContainerFactory，JettyEmbeddedServletContainerFactory或UndertowEmbeddedServletContainerFactory将被自动配置。

27.3.4 自定义嵌入式 servlet 容器

可以使用 Spring Environment属性来配置常见的 servlet 容器设置。通常，您将在application.properties文件中定义属性。

常用服务器设置包括：

• 网络设置：侦听传入 HTTP 请求的端口(server.port)，绑定到server.address的接口地址等。

• 会话设置：会话是否持久(server.session.persistence)，会话超时(server.session.timeout)，会话数据的位置(server.session.store-dir)和会话 cookie 配置(server.session.cookie.*)。

• 错误 Management：错误页面的位置(server.error.path)等。

• SSL

• HTTP compression

Spring Boot 尝试尽可能多地公开通用设置，但这并不总是可能的。在这种情况下，专用名称空间提供服务器特定的自定义项(请参见server.tomcat和server.undertow)。例如，access logs可以配置有嵌入式 Servlet 容器的特定功能。

Programmatic customization

如果您需要以编程方式配置嵌入式 servlet 容器，则可以注册一个实现EmbeddedServletContainerCustomizer接口的 Spring bean。 EmbeddedServletContainerCustomizer提供对ConfigurableEmbeddedServletContainer的访问，其中包括许多自定义设置方法。

import org.springframework.boot.context.embedded.*;
import org.springframework.stereotype.Component;

@Component
public class CustomizationBean implements EmbeddedServletContainerCustomizer {

    @Override
    public void customize(ConfigurableEmbeddedServletContainer container) {
        container.setPort(9000);
    }

}

直接自定义 ConfigurableEmbeddedServletContainer

如果上述定制技术太有限，则可以自己注册TomcatEmbeddedServletContainerFactory，JettyEmbeddedServletContainerFactory或UndertowEmbeddedServletContainerFactory bean。

@Bean
public EmbeddedServletContainerFactory servletContainer() {
    TomcatEmbeddedServletContainerFactory factory = new TomcatEmbeddedServletContainerFactory();
    factory.setPort(9000);
    factory.setSessionTimeout(10, TimeUnit.MINUTES);
    factory.addErrorPages(new ErrorPage(HttpStatus.NOT_FOUND, "/notfound.html"));
    return factory;
}

提供了许多配置选项的设置器。如果您需要做一些更奇特的操作，还提供了几种受保护的方法“钩子”。有关详细信息，请参见源代码文档。

27.3.5 JSP 限制

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

• 对于 Tomcat，如果您使用 war 打包，它应该可以工作，即可执行的 war 将可以工作，并且还可以部署到标准容器(不限于，但包括 Tomcat)。由于 Tomcat 中采用了硬编码的文件模式，因此可执行的 jar 将无法工作。

• 使用 Jetty，如果您使用 War 包装，它应该可以使用，即可执行的 War 将可以使用，并且也可以部署到任何标准容器中。

• Undertow 不支持 JSP。

• 创建自定义error.jsp页面不会覆盖error handling的默认视图，而应使用自定义错误页面。

有一个JSP sample，因此您可以了解如何进行设置。