Spring Boot и Web MVC, часть 3

Шаблонизаторы

Помимо веб-служб REST, можно также использовать Spring MVC для обработки динамического HTML-содержимого. Spring MVC поддерживает различные технологии шаблонизации, включая Thymeleaf, FreeMarker и JSP. Кроме того, многие другие шаблонизаторы содержат свои собственные средства интеграции с Spring MVC.

Spring Boot предусматривает поддержку автоконфигурации для следующих шаблонизаторов:

• FreeMarker

• Groovy

• Thymeleaf

• Mustache

Если один из этих шаблонизаторов используется с конфигурацией по умолчанию, то шаблоны автоматически подбираются из src/main/resources/templates.

Обработка ошибок

По умолчанию Spring Boot предусматривает отображение /error, которое обрабатывает все ошибки адекватным образом, и оно регистрируется как "глобальная" страница ошибок в контейнере сервлетов. Для машинных клиентов оно создает ответ в формате JSON с подробным описанием ошибки, кодом состояния HTTP и сообщением об исключении. Для браузерных клиентов существует представление ошибок "whitelabel", которое визуализирует те же данные в формате HTML (чтобы настроить его, добавьте View, разрешающий error).

Существует ряд свойств server.error, которые можно установить, если нужно персонализировать настройки логики обработки ошибок по умолчанию.

Чтобы полностью заменить логику работы по умолчанию, можно реализовать ErrorController и зарегистрировать определение бина этого типа или добавить бин типа ErrorAttributes, чтобы использовать существующий механизм, но заменить содержимое.

Помимо этого, можно определить класс, аннотированный @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;
    }
}

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
import javax.servlet.RequestDispatcher
import javax.servlet.http.HttpServletRequest
@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
    }
}

В предыдущем примере, если MyException генерируется контроллером, определенным в том же пакете, что и SomeController, вместо представления ErrorAttributes используется JSON-представление POJO-объекта MyErrorBody.

В некоторых случаях ошибки, обработанные на уровне контроллера, не регистрируются инфраструктурой метрик. Приложения могут обеспечить запись таких исключений в метрики запроса, настроив обработанное исключение в качестве атрибута запроса:

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

import org.springframework.boot.web.servlet.error.ErrorAttributes
import org.springframework.stereotype.Controller
import org.springframework.web.bind.annotation.ExceptionHandler
import javax.servlet.http.HttpServletRequest
@Controller
class MyController {
    @ExceptionHandler(CustomException::class)
    fun handleCustomException(request: HttpServletRequest, ex: CustomException?): String {
        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>

Чтобы отобразить все ошибки 5xx с помощью шаблона FreeMarker, структура каталога должна быть следующей:

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

Для более сложных отображений можно также добавить бины, реализующие интерфейс ErrorViewResolver, как показано в следующем примере:

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) {
        // Используем запрос или статус, чтобы по желанию вернуть ModelAndView
        if (status == HttpStatus.INSUFFICIENT_STORAGE) {
            // Здесь мы можем добавить кастомное значения модели
            new ModelAndView("myview");
        }
        return null;
    }
}

import org.springframework.boot.autoconfigure.web.servlet.error.ErrorViewResolver
import org.springframework.http.HttpStatus
import org.springframework.web.servlet.ModelAndView
import javax.servlet.http.HttpServletRequest
class MyErrorViewResolver : ErrorViewResolver {
    override fun resolveErrorView(request: HttpServletRequest, status: HttpStatus,
            model: Map<String, Any>): ModelAndView? {
        // Используем запрос или статус, чтобы по желанию вернуть ModelAndView
        if (status == HttpStatus.INSUFFICIENT_STORAGE) {
            // Здесь мы можем добавить кастомное значения модели
            return ModelAndView("myview")
        }
        return null
    }
}

Также можно использовать обычные функции Spring MVC, такие как методы, помеченные аннотацией @ExceptionHandler и аннотацию @ControllerAdvice. ErrorController затем подхватывает все необработанные исключения.

Отображение страниц ошибок вне Spring MVC

В случае приложений, не использующих Spring MVC, можно использовать интерфейс ErrorPageRegistrar для прямой регистрации ErrorPages. Эта абстракция работает напрямую с базовым встроенным контейнером сервлетов и хорошо себя показывает, даже если у вас нет DispatcherServlet для Spring MVC.

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

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

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

import org.springframework.boot.web.servlet.FilterRegistrationBean
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import java.util.EnumSet
import javax.servlet.DispatcherType
@Configuration(proxyBeanMethods = false)
class MyFilterConfiguration {
    @Bean
    fun myFilter(): FilterRegistrationBean<MyFilter> {
        val registration = FilterRegistrationBean(MyFilter())
        // ...
        registration.setDispatcherTypes(EnumSet.allOf(DispatcherType::class.java))
        return registration
    }
}

Обратите внимание, что FilterRegistrationBean по умолчанию не содержит тип диспетчера ERROR.

Обработка ошибок при WAR-развертывании

При развертывании в контейнере сервлетов Spring Boot использует свой фильтр страницы ошибок для перенаправления запроса с кодом ошибки на соответствующую страницу ошибок. Это необходимо, поскольку спецификация сервлетов не предусматривает API для регистрации страниц ошибок. В зависимости от контейнера, в который вы развертываете свой war-файл, и технологий, которые использует ваше приложение, может потребоваться дополнительное конфигурирование.

Фильтр страницы ошибки сможет перенаправить запрос на правильную страницу ошибки только в том случае, если ответ еще не был зафиксирован. По умолчанию WebSphere Application Server 8.0 и более поздних версий фиксирует ответ после успешного завершения метода службы сервлета. Следует отключить эту логику работы, установив для параметра 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. Использование метода контроллера для конфигурации CORS с аннотациями @CrossOrigin в приложении Spring Boot не требует какой-либо специальной конфигурации. Глобальную конфигурацию CORS моно определить путем регистрации бина WebMvcConfigurer с настроенным методом addCorsMappings(CorsRegistry), как показано в следующем примере:

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

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