2019獨角獸企業重金招聘Python工程師標準>>>

http://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-developing-web-applications.html

27.?Developing web applications

Spring Boot is well suited for web application development. You can easily create a self-contained HTTP server using embedded Tomcat, Jetty, or Undertow. Most web applications will use the?spring-boot-starter-web?module to get up and running quickly.

If you haven’t yet developed a Spring Boot web application you can follow the "Hello World!" example in the?Getting started?section.

27.1?The ‘Spring Web MVC framework’

The Spring Web MVC framework (often referred to as simply ‘Spring MVC’) is a rich ‘model view controller’ web framework. Spring MVC lets you create special?@Controller?or?@RestController?beans to handle incoming HTTP requests. Methods in your controller are mapped to HTTP using?@RequestMapping?annotations.

Here is a typical example?@RestController?to serve JSON data:

@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 is part of the core Spring Framework and detailed information is available in the?reference documentation. There are also several guides available at?spring.io/guides?that cover Spring MVC.

27.1.1?Spring MVC auto-configuration

Spring Boot provides auto-configuration for Spring MVC that works well with most applications.

The auto-configuration adds the following features on top of Spring’s defaults:

• Inclusion of?ContentNegotiatingViewResolver?and?BeanNameViewResolver?beans.
• Support for serving static resources, including support for WebJars (see below).
• Automatic registration of?Converter,?GenericConverter,?Formatter?beans.
• Support for?HttpMessageConverters?(see below).
• Automatic registration of?MessageCodesResolver?(see below).
• Static?index.html?support.
• Custom?Favicon?support (see below).
• Automatic use of a?ConfigurableWebBindingInitializer?bean (see below).

If you want to keep Spring Boot MVC features, and you just want to add additional?MVC configuration?(interceptors, formatters, view controllers etc.) you can add your own?@Configuration?class of type?WebMvcConfigurerAdapter, but?without?@EnableWebMvc. If you wish to provide custom instances of?RequestMappingHandlerMapping,?RequestMappingHandlerAdapter?or?ExceptionHandlerExceptionResolver?you can declare a?WebMvcRegistrationsAdapter?instance providing such components.

If you want to take complete control of Spring MVC, you can add your own?@Configuration?annotated with?@EnableWebMvc.

27.1.2?HttpMessageConverters

Spring MVC uses the?HttpMessageConverter?interface to convert HTTP requests and responses. Sensible defaults are included out of the box, for example Objects can be automatically converted to JSON (using the Jackson library) or XML (using the Jackson XML extension if available, else using JAXB). Strings are encoded using?UTF-8?by default.

If you need to add or customize converters you can use Spring Boot’s?HttpMessageConverters?class:

import org.springframework.boot.autoconfigure.web.HttpMessageConverters; import org.springframework.context.annotation.*; import org.springframework.http.converter.*;@Configuration public class MyConfiguration {@Beanpublic HttpMessageConverters customConverters() {HttpMessageConverter<?> additional = ...HttpMessageConverter<?> another = ...return new HttpMessageConverters(additional, another);}}

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

27.1.3?Custom JSON Serializers and Deserializers

If you’re using Jackson to serialize and deserialize JSON data, you might want to write your own?JsonSerializer?and?JsonDeserializer?classes. Custom serializers are usually?registered with Jackson via a Module, but Spring Boot provides an alternative?@JsonComponent?annotation which makes it easier to directly register Spring Beans.

You can use?@JsonComponent?directly on?JsonSerializer?or?JsonDeserializer?implementations. You can also use it on classes that contains serializers/deserializers as inner-classes. For example:

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> {// ...}}

All?@JsonComponent?beans in the?ApplicationContext?will be automatically registered with Jackson, and since?@JsonComponent?is meta-annotated with?@Component, the usual component-scanning rules apply.

Spring Boot also provides?JsonObjectSerializer?and?JsonObjectDeserializer?base classes which provide useful alternatives to the standard Jackson versions when serializing Objects. See the Javadoc for details.

27.1.4?MessageCodesResolver

Spring MVC has a strategy for generating error codes for rendering error messages from binding errors:?MessageCodesResolver. Spring Boot will create one for you if you set the?spring.mvc.message-codes-resolver.format?property?PREFIX_ERROR_CODE?or?POSTFIX_ERROR_CODE?(see the enumeration in?DefaultMessageCodesResolver.Format).

27.1.5?Static Content

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

In a stand-alone web application the default servlet from the container is also enabled, and acts as a fallback, serving content from the root of the?ServletContext?if Spring decides not to handle it. Most of the time this will not happen (unless you modify the default MVC configuration) because Spring will always be able to handle requests through the?DispatcherServlet.

By default, resources are mapped on?/**?but you can tune that via?spring.mvc.static-path-pattern. For instance, relocating all resources to?/resources/**can be achieved as follows:

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

You can also customize the static resource locations using?spring.resources.static-locations?(replacing the default values with a list of directory locations). If you do this the default welcome page detection will switch to your custom locations, so if there is an?index.html?in any of your locations on startup, it will be the home page of the application.

In addition to the ‘standard’ static resource locations above, a special case is made for?Webjars content. Any resources with a path in?/webjars/**?will be served from jar files if they are packaged in the Webjars format.

Do not use the?src/main/webapp?directory if your application will be packaged as a jar. Although this directory is a common standard, it will?only?work with war packaging and it will be silently ignored by most build tools if you generate a jar.

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

To use version agnostic URLs for Webjars, simply add the?webjars-locator?dependency. Then declare your Webjar, taking jQuery for example, as?"/webjars/jquery/dist/jquery.min.js"?which results in?"/webjars/jquery/x.y.z/dist/jquery.min.js"?where?x.y.z?is the Webjar version.

If you are using JBoss, you’ll need to declare the?webjars-locator-jboss-vfs?dependency instead of the?webjars-locator; otherwise all Webjars resolve as a?404.

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

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

Links to resources are rewritten at runtime in template, thanks to a?ResourceUrlEncodingFilter, auto-configured for Thymeleaf and FreeMarker. You should manually declare this filter when using JSPs. Other template engines aren’t automatically supported right now, but can be with custom template macros/helpers and the use of the?ResourceUrlProvider.

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

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

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

See?ResourceProperties?for more of the supported options.

This feature has been thoroughly described in a dedicated?blog post?and in Spring Framework’s?reference documentation.

27.1.6?Custom Favicon

Spring Boot looks for a?favicon.ico?in the configured static content locations and the root of the classpath (in that order). If such file is present, it is automatically used as the favicon of the application.

27.1.7?ConfigurableWebBindingInitializer

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

27.1.8?Template engines

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

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

• FreeMarker
• Groovy
• Thymeleaf
• Mustache

JSPs should be avoided if possible, there are several?known limitations?when using them with embedded servlet containers.

When you’re using one of these templating engines with the default configuration, your templates will be picked up automatically from?src/main/resources/templates.

IntelliJ IDEA orders the classpath differently depending on how you run your application. Running your application in the IDE via its main method will result in a different ordering to when you run your application using Maven or Gradle or from its packaged jar. This can cause Spring Boot to fail to find the templates on the classpath. If you’re affected by this problem you can reorder the classpath in the IDE to place the module’s classes and resources first. Alternatively, you can configure the template prefix to search every templates directory on the classpath:?classpath*:/templates/.

27.1.9?Error Handling

Spring Boot provides an?/error?mapping by default that handles all errors in a sensible way, and it is registered as a ‘global’ error page in the servlet container. For machine clients it will produce a JSON response with details of the error, the HTTP status and the exception message. For browser clients there is a ‘whitelabel’ error view that renders the same data in HTML format (to customize it just add a?View?that resolves to ‘error’). To replace the default behaviour completely you can implementErrorController?and register a bean definition of that type, or simply add a bean of type?ErrorAttributes?to use the existing mechanism but replace the contents.

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

You can also define a?@ControllerAdvice?to customize the JSON document to return for a particular controller and/or exception type.

@ControllerAdvice(basePackageClasses = FooController.class) public class FooControllerAdvice extends ResponseEntityExceptionHandler {@ExceptionHandler(YourException.class)@ResponseBodyResponseEntity<?> 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);}}

In the example above, if?YourException?is thrown by a controller defined in the same package as?FooController, a json representation of the?CustomerErrorTypePOJO will be used instead of the?ErrorAttributes?representation.

Custom error pages

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

For example, to map?404?to a static HTML file, your folder structure would look like this:

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

To map all?5xx?errors using a FreeMarker template, you’d have a structure like this:

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

For more complex mappings you can also add beans that implement the?ErrorViewResolver?interface.

public class MyErrorViewResolver implements ErrorViewResolver {@Overridepublic ModelAndView resolveErrorView(HttpServletRequest request,HttpStatus status, Map<String, Object> model) {// Use the request or status to optionally return a ModelAndViewreturn ...}}

You can also use regular Spring MVC features like?@ExceptionHandler?methods?and?@ControllerAdvice. The?ErrorController?will then pick up any unhandled exceptions.

Mapping error pages outside of Spring MVC

For applications that aren’t using Spring MVC, you can use the?ErrorPageRegistrar?interface to directly register?ErrorPages. This abstraction works directly with the underlying embedded servlet container and will work even if you don’t have a Spring MVC?DispatcherServlet.

@Bean public ErrorPageRegistrar errorPageRegistrar(){return new MyErrorPageRegistrar(); }// ...private static class MyErrorPageRegistrar implements ErrorPageRegistrar {@Overridepublic void registerErrorPages(ErrorPageRegistry registry) {registry.addErrorPages(new ErrorPage(HttpStatus.BAD_REQUEST, "/400"));}}

N.B. if you register an?ErrorPage?with a path that will end up being handled by a?Filter?(e.g. as is common with some non-Spring web frameworks, like Jersey and Wicket), then the?Filter?has to be explicitly registered as an?ERROR?dispatcher, e.g.

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

(the default?FilterRegistrationBean?does not include the?ERROR?dispatcher type).

Error Handling on WebSphere Application Server

When deployed to a servlet container, a Spring Boot uses its error page filter to forward a request with an error status to the appropriate error page. The request can only be forwarded to the correct error page if the response has not already been committed. By default, WebSphere Application Server 8.0 and later commits the response upon successful completion of a servlet’s service method. You should disable this behaviour by setting?com.ibm.ws.webcontainer.invokeFlushAfterService?to?false

27.1.10?Spring HATEOAS

If you’re developing a RESTful API that makes use of hypermedia, Spring Boot provides auto-configuration for Spring HATEOAS that works well with most applications. The auto-configuration replaces the need to use?@EnableHypermediaSupport?and registers a number of beans to ease building hypermedia-based applications including a?LinkDiscoverers?(for client side support) and an?ObjectMapper?configured to correctly marshal responses into the desired representation. The?ObjectMapper?will be customized based on the?spring.jackson.*?properties or a?Jackson2ObjectMapperBuilder?bean if one exists.

You can take control of Spring HATEOAS’s configuration by using?@EnableHypermediaSupport. Note that this will disable the?ObjectMapper?customization described above.

27.1.11?CORS support

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

As of version 4.2, Spring MVC?supports CORS?out of the box. Using?controller method CORS configuration?with?@CrossOrigin?annotations in your Spring Boot application does not require any specific configuration.?Global CORS configuration?can be defined by registering a?WebMvcConfigurer?bean with a customized?addCorsMappings(CorsRegistry)?method:

@Configuration public class MyConfiguration {@Beanpublic WebMvcConfigurer corsConfigurer() {return new WebMvcConfigurerAdapter() {@Overridepublic void addCorsMappings(CorsRegistry registry) {registry.addMapping("/api/**");}};} }

27.2?JAX-RS and Jersey

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

To get started with Jersey 2.x just include the?spring-boot-starter-jersey?as a dependency and then you need one?@Bean?of type?ResourceConfig?in which you register all the endpoints:

@Component public class JerseyConfig extends ResourceConfig {public JerseyConfig() {register(Endpoint.class);}}

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

You can also register an arbitrary number of beans implementing?ResourceConfigCustomizer?for more advanced customizations.

All the registered endpoints should be?@Components?with HTTP resource annotations (@GET?etc.), e.g.

@Component @Path("/hello") public class Endpoint {@GETpublic String message() {return "Hello";}}

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

By default Jersey will be set up as a Servlet in a?@Bean?of type?ServletRegistrationBean?named?jerseyServletRegistration. By default, the servlet will be initialized lazily but you can customize it with?spring.jersey.servlet.load-on-startup?.You can disable or override that bean by creating one of your own with the same name. You can also use a Filter instead of a Servlet by setting?spring.jersey.type=filter?(in which case the?@Bean?to replace or override isjerseyFilterRegistration). The servlet has an?@Order?which you can set with?spring.jersey.filter.order. Both the Servlet and the Filter registrations can be given init parameters using?spring.jersey.init.*?to specify a map of properties.

There is a?Jersey sample?so you can see how to set things up. There is also a?Jersey 1.x sample. Note that in the Jersey 1.x sample that the spring-boot maven plugin has been configured to unpack some Jersey jars so they can be scanned by the JAX-RS implementation (because the sample asks for them to be scanned in its?Filter?registration). You may need to do the same if any of your JAX-RS resources are packaged as nested jars.

27.3?Embedded servlet container support

Spring Boot includes support for embedded Tomcat, Jetty, and Undertow servers. Most developers will simply use the appropriate ‘Starter’ to obtain a fully configured instance. By default the embedded server will listen for HTTP requests on port?8080.

If you choose to use Tomcat on CentOS be aware that, by default, a temporary directory is used to store compiled JSPs, file uploads etc. This directory may be deleted by?tmpwatch?while your application is running leading to failures. To avoid this, you may want to customize your?tmpwatch?configuration so that?tomcat.*?directories are not deleted, or configure?server.tomcat.basedir?so that embedded Tomcat uses a different location.

27.3.1?Servlets, Filters, and listeners

When using an embedded servlet container you can register Servlets, Filters and all the listeners from the Servlet spec (e.g.?HttpSessionListener) either by using Spring beans or by scanning for Servlet components.

Registering Servlets, Filters, and listeners as Spring beans

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

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

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

27.3.2?Servlet Context Initialization

Embedded servlet containers will not directly execute the Servlet 3.0+?javax.servlet.ServletContainerInitializer?interface, or Spring’sorg.springframework.web.WebApplicationInitializer?interface. This is an intentional design decision intended to reduce the risk that 3rd party libraries designed to run inside a war will break Spring Boot applications.

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

Scanning for Servlets, Filters, and listeners

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

@ServletComponentScan?will have no effect in a standalone container, where the container’s built-in discovery mechanisms will be used instead.

27.3.3?The EmbeddedWebApplicationContext

Under the hood Spring Boot uses a new type of?ApplicationContext?for embedded servlet container support. The?EmbeddedWebApplicationContext?is a special type of?WebApplicationContext?that bootstraps itself by searching for a single?EmbeddedServletContainerFactory?bean. Usually a?TomcatEmbeddedServletContainerFactory,?JettyEmbeddedServletContainerFactory, or?UndertowEmbeddedServletContainerFactory?will have been auto-configured.

You usually won’t need to be aware of these implementation classes. Most applications will be auto-configured and the appropriate?ApplicationContextand?EmbeddedServletContainerFactory?will be created on your behalf.

27.3.4?Customizing embedded servlet containers

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

Common server settings include:

• Network settings: listen port for incoming HTTP requests (server.port), interface address to bind to?server.address, etc.
• Session settings: whether the session is persistent (server.session.persistence), session timeout (server.session.timeout), location of session data (server.session.store-dir) and session-cookie configuration (server.session.cookie.*).
• Error management: location of the error page (server.error.path), etc.
• SSL
• HTTP compression

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

See the?ServerProperties?class for a complete list.

Programmatic customization

If you need to configure your embedded servlet container programmatically you can register a Spring bean that implements the?EmbeddedServletContainerCustomizer?interface.?EmbeddedServletContainerCustomizer?provides access to the?ConfigurableEmbeddedServletContainerwhich includes numerous customization setter methods.

import org.springframework.boot.context.embedded.*; import org.springframework.stereotype.Component;@Component public class CustomizationBean implements EmbeddedServletContainerCustomizer {@Overridepublic void customize(ConfigurableEmbeddedServletContainer container) {container.setPort(9000);}}

Customizing ConfigurableEmbeddedServletContainer directly

If the above customization techniques are too limited, you can register the?TomcatEmbeddedServletContainerFactory,?JettyEmbeddedServletContainerFactoryor?UndertowEmbeddedServletContainerFactory?bean yourself.

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

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

27.3.5?JSP limitations

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

• With Tomcat it should work if you use war packaging, i.e. an executable war will work, and will also be deployable to a standard container (not limited to, but including Tomcat). An executable jar will not work because of a hard coded file pattern in Tomcat.
• With Jetty it should work if you use war packaging, i.e. an executable war will work, and will also be deployable to any standard container.
• Undertow does not support JSPs.
• Creating a custom?error.jsp?page won’t override the default view for?error handling,?custom error pages?should be used instead.

There is a?JSP sample?so you can see how to set things up.

轉載于:https://my.oschina.net/qiangzigege/blog/909370

總結

以上是生活随笔為你收集整理的SprintBoot开发官方指导文档的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。