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

The code written for this post uses:

• Java 14
• Spring Boot 2.3.2
• Postgres 13
• Maven 3.6.3

version: '3'

services:
  db:
    image: postgres:13-alpine
    restart: always
    ports:
      - 5432:5432
    environment:
      POSTGRES_USER: erin
      POSTGRES_PASSWORD: richards

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.3.2.RELEASE</version>
    <relativePath/> <!-- lookup parent from repository -->
  </parent>

  <groupId>dev.mflash.guides</groupId>
  <artifactId>spring-rest-error-handling</artifactId>
  <version>0.0.1-SNAPSHOT</version>

  <properties>
    <java.version>14</java.version>
  </properties>

  <dependencies>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-data-jdbc</artifactId>
    </dependency>
    <dependency>
      <groupId>org.postgresql</groupId>
      <artifactId>postgresql</artifactId>
      <scope>runtime</scope>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-maven-plugin</artifactId>
      </plugin>
    </plugins>
  </build>

</project>

# src/main/resources/application.yml

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/spring
    username: erin
    password: richards

// src/main/java/dev/mflash/guides/resterror/domain/Book.java

public class Book {

  private @Id long id;
  private String title;
  private String author;
  private Genre genre;

  // getters, setters, etc.
}

CREATE TABLE book (
	id SERIAL PRIMARY KEY,
	title TEXT NOT NULL,
	author TEXT NOT NULL,
	genre TEXT NOT NULL
);

public enum Genre {
  fantasy,
  thriller,
  scifi
}

// src/main/java/dev/mflash/guides/resterror/persistence/BookRepository.java

public interface BookRepository extends CrudRepository<Book, Long> {

}

// src/main/java/dev/mflash/guides/resterror/controller/BookController.java

@RequestMapping("/book")
public @RestController class BookController {

  private final BookRepository repository;

  public BookController(BookRepository repository) {
    this.repository = repository;
  }

  @PutMapping
  public Map<String, String> addBook(Book newBook) {
    repository.save(newBook);
    return Map.of("message", String.format("Save successful for %s", newBook.getTitle()));
  }

  @GetMapping
  public List<Book> getAllBooks() {
    List<Book> allBooks = List.of();
    repository.findAll().forEach(allBooks::add);
    return allBooks;
  }

  @GetMapping("/{id}")
  public Book getBookById(@PathVariable long id) {
    Optional<Book> book = repository.findById(id);

    if (book.isEmpty()) {
      throw new DataAccessResourceFailureException(String.format("No resource found for id (%s)", id));
    }

    return book.get();
  }

  @PatchMapping("/{id}")
  public Map<String, String> editBook(@PathVariable long id, Book editedBook) {
    final Optional<Book> saved = repository.findById(id);

    if (saved.isPresent()) {
      final Book savedBook = saved.get();
      final Book patchedBook = new Book();
      patchedBook.setId(savedBook.getId());
      patchedBook.setTitle(
          !editedBook.getTitle().equals(savedBook.getTitle()) ? editedBook.getTitle() : savedBook.getTitle());
      patchedBook.setAuthor(
          !editedBook.getAuthor().equals(savedBook.getAuthor()) ? editedBook.getAuthor() : savedBook.getAuthor());
      patchedBook.setGenre(
          !editedBook.getGenre().equals(savedBook.getGenre()) ? editedBook.getGenre() : savedBook.getGenre());
      repository.save(patchedBook);
    } else {
      throw new InvalidDataAccessApiUsageException("Couldn't patch unrelated or non-existent records");
    }

    return Map.of("message", String.format("Patch successful for %s", editedBook.getTitle()));
  }

  @DeleteMapping("/{id}")
  public Map<String, String> deleteBook(@PathVariable long id) {
    if (repository.deleteById(id) < 1) {
      throw new InvalidDataAccessApiUsageException("Couldn't delete a non-existent record");
    }

    return Map.of("message", String.format("Deletion successful for book with id: %s", id));
  }
}

$ curl --location --request GET 'http://localhost:8080/book/0'
{
  "timestamp": "2020-07-25T15:54:09.567+00:00",
  "status": 500,
  "error": "Internal Server Error",
  "message": "",
  "path": "/book/0"
}

// src/main/java/dev/mflash/guides/resterror/controller/BookController.java

@RequestMapping("/book")
public @RestController class BookController {

  // Rest of the controller

  @GetMapping("/{id}")
  public Book getBookById(@PathVariable long id) {
    Optional<Book> book = repository.findById(id);

    if (book.isEmpty()) {
      throw new ResponseStatusException(NOT_FOUND, String.format("No resource found for id (%s)", id));
    }

    return book.get();
  }

  @PatchMapping("/{id}")
  public Map<String, String> editBook(@PathVariable long id, Book editedBook) {
    final Optional<Book> saved = repository.findById(id);

    if (saved.isPresent()) {
      // logic for patch
    } else {
      throw new ResponseStatusException(INTERNAL_SERVER_ERROR, "Couldn't patch unrelated or non-existent records");
    }

    return Map.of("message", String.format("Patch successful for %s", editedBook.getTitle()));
  }

  @DeleteMapping("/{id}")
  public Map<String, String> deleteBook(@PathVariable long id) {
    if (repository.deleteById(id) < 1) {
      throw new ResponseStatusException(INTERNAL_SERVER_ERROR, "Couldn't delete a non-existent record");
    }

    return Map.of("message", String.format("Deletion successful for book with id: %s", id));
  }
}

$ curl --location --request GET 'http://localhost:8080/book/0'
{
  "timestamp": "2020-07-26T07:07:30.313+00:00",
  "status": 404,
  "error": "Not Found",
  "message": "",
  "path": "/book/0"
}

// src/main/java/dev/mflash/guides/resterror/exception/RestResponse.java

public class RestResponse {

  private final LocalDateTime timestamp = LocalDateTime.now();
  private int status;
  private String error;
  private String message;
  private String path;

  // getters, setters, etc.

  public static RestResponseBuilder builder() {
    return new RestResponseBuilder();
  }
}

// src/main/java/dev/mflash/guides/resterror/exception/RestResponseBuilder.java

public class RestResponseBuilder {

  private int status;
  private String error;
  private String message;
  private String path;

  public RestResponseBuilder status(int status) {
    this.status = status;
    return this;
  }

  public RestResponseBuilder status(HttpStatus status) {
    this.status = status.value();

    if (status.isError()) {
      this.error = status.getReasonPhrase();
    }

    return this;
  }

  public RestResponseBuilder error(String error) {
    this.error = error;
    return this;
  }

  public RestResponseBuilder exception(ResponseStatusException exception) {
    HttpStatus status = exception.getStatus();
    this.status = status.value();
    
    if (!Objects.requireNonNull(exception.getReason()).isBlank()) {
      this.message = exception.getReason();
    }
    

    if (status.isError()) {
      this.error = status.getReasonPhrase();
    }

    return this;
  }

  public RestResponseBuilder message(String message) {
    this.message = message;
    return this;
  }

  public RestResponseBuilder path(String path) {
    this.path = path;
    return this;
  }

  public RestResponse build() {
    RestResponse response = new RestResponse();
    response.setStatus(status);
    response.setError(error);
    response.setMessage(message);
    response.setPath(path);
    return response;
  }

  public ResponseEntity<RestResponse> entity() {
    return ResponseEntity.status(status).headers(HttpHeaders.EMPTY).body(build());
  }
}

// src/main/java/dev/mflash/guides/resterror/exception/RestErrorHandler.java

@RestControllerAdvice
public class RestErrorHandler {

  private static final Logger logger = LoggerFactory.getLogger(RestErrorHandler.class);

  @ExceptionHandler(ResponseStatusException.class)
  ResponseEntity<?> handleStatusException(ResponseStatusException ex, WebRequest request) {
    logger.error(ex.getReason(), ex);
    return RestResponse.builder()
        .exception(ex)
        .path(request.getDescription(false).substring(4))
        .entity();
  }
}

$ curl --location --request GET 'http://localhost:8080/book/0'
{
  "timestamp": "2020-07-26T15:24:38.0644948",
  "status": 404,
  "error": "Not Found",
  "message": "No resource found for id (0)",
  "path": "/book/0"
}

// src/main/java/dev/mflash/guides/resterror/exception/RestErrorHandler.java

@RestControllerAdvice
public class RestErrorHandler extends ResponseEntityExceptionHandler {

  private static final Logger logger = LoggerFactory.getLogger(RestErrorHandler.class);

  @ExceptionHandler(ResponseStatusException.class)
  ResponseEntity<?> handleStatusException(ResponseStatusException ex, WebRequest request) {
    logger.error(ex.getReason(), ex);
    return handleResponseStatusException(ex, request);
  }

  @ExceptionHandler(Exception.class)
  ResponseEntity<?> handleAllExceptions(Exception ex, WebRequest request) {
    logger.error(ex.getLocalizedMessage(), ex);
    return handleEveryException(ex, request);
  }

  @SuppressWarnings("unchecked")
  protected @Override ResponseEntity<Object> handleExceptionInternal(Exception ex, Object body, HttpHeaders headers,
      HttpStatus status, WebRequest request) {

    ResponseEntity<?> responseEntity;

    if (!status.isError()) {
      responseEntity = handleStatusException(ex, status, request);
    } else if (INTERNAL_SERVER_ERROR.equals(status)) {
      request.setAttribute("javax.servlet.error.exception", ex, 0);
      responseEntity = handleEveryException(ex, request);
    } else {
      responseEntity = handleEveryException(ex, request);
    }

    return (ResponseEntity<Object>) responseEntity;
  }

  protected ResponseEntity<RestResponse> handleResponseStatusException(ResponseStatusException ex, WebRequest request) {
    return RestResponse.builder()
        .exception(ex)
        .path(getPath(request))
        .entity();
  }

  protected ResponseEntity<RestResponse> handleStatusException(Exception ex, HttpStatus status, WebRequest request) {
    return RestResponse.builder()
        .status(status)
        .message("Execution halted")
        .path(getPath(request))
        .entity();
  }

  protected ResponseEntity<RestResponse> handleEveryException(Exception ex, WebRequest request) {
    return RestResponse.builder()
        .status(INTERNAL_SERVER_ERROR)
        .message("Server encountered an error")
        .path(getPath(request))
        .entity();
  }

  private String getPath(WebRequest request) {
    return request.getDescription(false).substring(4);
  }
}

$ curl --location --request PUT 'http://localhost:8080/book' 
--header 'Content-Type: application/json' 
--data-raw '{
  "title": "The Land of Roar",
  "author": "Jenny McLachlan",
  "genre": "kids"
}'

{
  "timestamp": "2020-07-26T16:30:51.3444858",
  "status": 500,
  "error": "Internal Server Error",
  "message": "Server encountered an error",
  "path": "/book"
}

$ curl --location --request GET 'http://localhost:8080/book'
{
  "timestamp": "2020-07-26T11:36:58.225+00:00",
  "status": 403,
  "error": "Forbidden",
  "message": "",
  "path": "/book"
}

// src/main/java/dev/mflash/guides/resterror/security/CustomAuthenticationEntryPoint.java

public class CustomAuthenticationEntryPoint implements AuthenticationEntryPoint {

  private static final Logger logger = LoggerFactory.getLogger(CustomAuthenticationEntryPoint.class);

  public @Override void commence(HttpServletRequest request, HttpServletResponse response, AuthenticationException e)
      throws IOException {
    logger.error(e.getLocalizedMessage(), e);

    String message = RestResponse.builder()
        .status(UNAUTHORIZED)
        .error("Unauthenticated")
        .message("Insufficient authentication details")
        .path(request.getRequestURI())
        .json();

    response.setStatus(UNAUTHORIZED.value());
    response.setContentType(APPLICATION_JSON_VALUE);
    response.getWriter().write(message);
  }
}

// src/main/java/dev/mflash/guides/resterror/security/SecurityConfiguration.java

@EnableWebSecurity
public class SecurityConfiguration extends WebSecurityConfigurerAdapter {

  private static final String LOGIN_URL = "/user/login";
  private final CustomUserDetailsService userDetailsService;

  public SecurityConfiguration(CustomUserDetailsService userDetailsService) {
    this.userDetailsService = userDetailsService;
  }

  protected @Override void configure(HttpSecurity http) throws Exception {
    http.cors().and()
        .csrf().disable()
        .authorizeRequests().antMatchers(POST, REGISTRATION_URL).permitAll()
        .anyRequest().authenticated().and()
        .addFilter(new CustomAuthenticationFilter(authenticationManager()))
        .exceptionHandling().authenticationEntryPoint(new CustomAuthenticationEntryPoint()).and()
        .addFilter(new CustomAuthorizationFilter(authenticationManager()))
        .sessionManagement().sessionCreationPolicy(STATELESS);
  }

  // other configurations
}

// src/main/java/dev/mflash/guides/resterror/security/CustomAccessDeniedHandler.java

public class CustomAccessDeniedHandler implements AccessDeniedHandler {

  private static final Logger logger = LoggerFactory.getLogger(CustomAccessDeniedHandler.class);

  public @Override void handle(HttpServletRequest request, HttpServletResponse response, AccessDeniedException e)
      throws IOException {
    logger.error(e.getLocalizedMessage(), e);

    String message = RestResponse.builder()
        .status(FORBIDDEN)
        .message("Invalid Authorization token")
        .path(request.getRequestURI())
        .json();

    response.setStatus(FORBIDDEN.value());
    response.setContentType(APPLICATION_JSON_VALUE);
    response.getWriter().write(message);
  }
}

// src/main/java/dev/mflash/guides/resterror/security/CustomAuthorizationFilter.java

public class CustomAuthorizationFilter extends BasicAuthenticationFilter {

  private final AccessDeniedHandler accessDeniedHandler;

  public CustomAuthorizationFilter(AuthenticationManager authenticationManager, AccessDeniedHandler accessDeniedHandler) {
    super(authenticationManager);
    this.accessDeniedHandler = accessDeniedHandler;
  }

  protected @Override void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain)
      throws IOException, ServletException {

    String header = request.getHeader(AUTH_HEADER_KEY);

    if (Objects.isNull(header) || !header.startsWith(TOKEN_PREFIX)) {
      chain.doFilter(request, response);
      return;
    }

    if (header.startsWith(TOKEN_PREFIX)) {
      try {
        var authentication = getAuthentication(header);
        SecurityContextHolder.getContext().setAuthentication(authentication);
        chain.doFilter(request, response);
      } catch (Exception e) {
        accessDeniedHandler.handle(request, response, new AccessDeniedException(e.getLocalizedMessage(), e));
      }
    }
  }

  private UsernamePasswordAuthenticationToken getAuthentication(String header) {

    if (header.startsWith(TOKEN_PREFIX)) {
      String username = parseToken(header);
      return new UsernamePasswordAuthenticationToken(username, null, List.of());
    } else {
      throw new AccessDeniedException("Failed to parse authentication token");
    }
  }
}

// src/main/java/dev/mflash/guides/resterror/security/SecurityConfiguration.java

@EnableWebSecurity
public class SecurityConfiguration extends WebSecurityConfigurerAdapter {

  private static final String LOGIN_URL = "/user/login";
  private final CustomUserDetailsService userDetailsService;

  public SecurityConfiguration(CustomUserDetailsService userDetailsService) {
    this.userDetailsService = userDetailsService;
  }

  protected @Override void configure(HttpSecurity http) throws Exception {
    http.cors().and()
        .csrf().disable()
        .authorizeRequests().antMatchers(POST, REGISTRATION_URL).permitAll()
        .anyRequest().authenticated().and()
        .addFilter(new CustomAuthenticationFilter(authenticationManager()))
        .exceptionHandling().authenticationEntryPoint(new CustomAuthenticationEntryPoint()).and()
        .addFilter(new CustomAuthorizationFilter(authenticationManager(), new CustomAccessDeniedHandler()))
        .sessionManagement().sessionCreationPolicy(STATELESS);
  }

  // other configurations
}

$ curl --location --request GET 'http://localhost:8080/book'
{
  "timestamp": "2020-07-26T20:38:10.166004300",
  "status": 401,
  "error": "Unauthenticated",
  "message": "Insufficient authentication details",
  "path": "/book"
}

$ curl --location --request GET 'http://localhost:8080/book' 
--header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlseS5icm9udGVAZXhhbXBsZS5jb20iLCJleHAiOjE1OTY1NTI0MTZ9.utTGxu-CTJglYQku9GMZPsOl-J8rni363nBaGbodNiP7D0J66Znf-fZZ-Hz_iVCO7CHj_s4E6Xuw68HCwyTZig'

{
  "timestamp": "2020-07-26T20:57:27.164265300",
  "status": 403,
  "error": "Forbidden",
  "message": "Invalid Authorization token",
  "path": "/book"
}

$ curl --location --request POST 'http://localhost:8080/login' 
--header 'Content-Type: application/json' 
--data-raw '{
  "email": "arya.antrix@example.com",
  "password": "pa55word"
}'

Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlseS5icm9udGVAZXhhbXBsZS5jb20iLCJleHAiOjE1OTY2NDE0MjJ9.xK9KvbdlPN_r_rJzwfaidYY2r83pvGsXgIw8LQokvMbVXCyF9fZnV1CgnVc1pjQeswFq8rOGhmgEdCHp7DbR8w

$ curl --location --request GET 'http://localhost:8080/book' 
--header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlseS5icm9udGVAZXhhbXBsZS5jb20iLCJleHAiOjE1OTY2NDE0MjJ9.xK9KvbdlPN_r_rJzwfaidYY2r83pvGsXgIw8LQokvMbVXCyF9fZnV1CgnVc1pjQeswFq8rOGhmgEdCHp7DbR8w'

[
  {
    "id": 1,
    "title": "Kill Orbit",
    "author": "Joel Dane",
    "genre": "scifi"
  }
]

В этой статье — обзор способов обработки исключений в Spring Boot.

Приложение

Мы рассмотрим простое REST API приложение с одной сущностью Person и с одним контроллером.

Класс Person:

@Entity
@NoArgsConstructor
@AllArgsConstructor
@Data
public class Person {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private String name;

}

Контроллер PersonController:

@RestController
@RequestMapping("/persons")
public class PersonController {

    @Autowired
    private PersonRepository personRepository;

    @GetMapping
    public List<Person> listAllPersons() {
        List<Person> persons = personRepository.findAll();
        return persons;
    }

    @GetMapping(value = "/{personId}")
    public Person getPerson(@PathVariable("personId") long personId){
        return personRepository.findById(personId).orElseThrow(() -> new MyEntityNotFoundException(personId));
    }

    @PostMapping
    public Person createPerson(@RequestBody Person person) {
        return personRepository.save(person);
    }

    @PutMapping("/{id}")
    public Person updatePerson(@RequestBody Person person, @PathVariable long id)  {
        Person oldPerson = personRepository.getOne(id);
        oldPerson.setName(person.getName());
        return personRepository.save(oldPerson);
    }
    
}

При старте приложения выполняется скрипт data.sql, который добавляет в базу данных H2 одну строку — Person c id=1. То есть Person c id=2 в базе отсутствует.

При попытке запросить Person c id=2:

GET localhost:8080/persons/2

метод контроллера getPerson() выбрасывает исключение — в данном случае наше пользовательское MyEntityNotFoundException:

public class MyEntityNotFoundException extends RuntimeException {

    public MyEntityNotFoundException(Long id) {
        super("Entity is not found, id="+id);
    }
}

BasicErrorController

По умолчанию все исключения попадают на адрес /error в BasicErrorController, в метод error():

@Controller
@RequestMapping({"${server.error.path:${error.path:/error}}"})
public class BasicErrorController extends AbstractErrorController {

...
    @RequestMapping
    public ResponseEntity<Map<String, Object>> error(HttpServletRequest request) {
        HttpStatus status = this.getStatus(request);
        if (status == HttpStatus.NO_CONTENT) {
            return new ResponseEntity(status);
        } else {
            Map<String, Object> body = this.getErrorAttributes(request, this.getErrorAttributeOptions(request, MediaType.ALL));
            return new ResponseEntity(body, status);
        }
    }
 ...
}

Если поставить в этом методе break point, то будет понятно, из каких атрибутов собирается ответное JSON сообщение.

Проверим ответ по умолчанию, запросив с помощью клиента Postman отсутствующий Person, чтобы выбросилось MyEntityNotFoundException:

GET localhost:8080/persons/2

Получим ответ:

{
    "timestamp": "2021-02-28T15:33:56.339+00:00",
    "status": 500,
    "error": "Internal Server Error",
    "message": "Entity is not found, id=2",
    "path": "/persons/2"
}

Причем для того, чтобы поле message было непустым, в application.properties нужно включить свойство:

server.error.include-message=always

В текущей версии Spring сообщение не включается по умолчанию из соображений безопасности.

Обратите внимание, что поле status JSON-тела ответа дублирует реальный http-код ответа. В Postman он виден:

Поле message заполняется полем message выброшенного исключения.

Независимо от того, какое исключение выбросилось: пользовательское или уже существующее, ответ стандартный — в том смысле, что набор полей одинаковый. Меняется только внутренняя часть и, возможно, код ответа (он не обязательно равен 500, некоторые существующие в Spring исключения подразумевают другой код).

Но структура ответа сохраняется.

Проверим это.

Не пользовательское исключение

Например, если изменить код, убрав пользовательское MyEntityNotFoundException, то при отсутствии Person исключение будет все равно выбрасываться, но другое:

@GetMapping(value = "/{personId}")
public Person getPerson(@PathVariable("personId") long personId){
    return personRepository.findById(personId).get();
}

findById() возвращает тип Optional, а Optional.get() выбрасывает исключение NoSuchElementException с другим сообщением:

java.util.NoSuchElementException: No value present

в итоге при запросе несуществующего Person:

GET localhost:8080/persons/2

ответ сохранит ту же структуру, но поменяется поле message:

{
    "timestamp": "2021-02-28T15:44:20.065+00:00",
    "status": 500,
    "error": "Internal Server Error",
    "message": "No value present",
    "path": "/persons/2"
}

Вернем обратно пользовательское исключение MyEntityNotFoundException.

Попробуем поменять ответ, выдаваемый в ответ за запрос. Статус 500 для него явно не подходит.

Рассмотрим способы изменения ответа.

@ResponseStatus

Пока поменяем только статус ответа. Сейчас возвращается 500, а нам нужен 404 — это логичный ответ, если ресурс не найден.

Для этого аннотируем наше исключение:

@ResponseStatus(HttpStatus.NOT_FOUND)
public class MyEntityNotFoundException extends RuntimeException {

    public MyEntityNotFoundException(Long id) {
        super("Entity is not found, id="+id);
    }
}

Теперь ответ будет таким:

{
    "timestamp": "2021-02-28T15:54:37.070+00:00",
    "status": 404,
    "error": "Not Found",
    "message": "Entity is not found, id=2",
    "path": "/persons/2"
}

Уже лучше.

@ControllerAdvice

Есть еще более мощный способ изменить ответ — @ControllerAdvice, и он имеет больший приоритет, чем @ResponseStatus.

В @ControllerAdvice можно не только изменить код ответа, но и тело. К тому же один обработчик можно назначить сразу для нескольких исключений.

Допустим мы хотим, чтобы ответ на запрос несуществующего Person имел такую структуру:

@Data
@AllArgsConstructor
@NoArgsConstructor
public class ApiError {
    private String message;
    private String debugMessage;
}

Для этого создадим обработчик в @ControllerAdvice, который перехватывает наше исключение MyEntityNotFoundException:

@ControllerAdvice
public class RestExceptionHandler {


    @ExceptionHandler({MyEntityNotFoundException.class, EntityNotFoundException.class})
    protected ResponseEntity<Object> handleEntityNotFoundEx(RuntimeException ex, WebRequest request) {
      ApiError apiError = new ApiError("entity not found ex", ex.getMessage());
      return new ResponseEntity<>(apiError, HttpStatus.NOT_FOUND);
    }

}

Теперь в ответ на запрос

GET localhost:8080/persons/2

мы получаем статус 404 с телом:

{
    "message": "entity not found ex",
    "debugMessage": "Entity is not found, id=2"
}

Но помимо MyEntityNotFoundException, наш обработчик  поддерживает и javax.persistence.EntityNotFoundException (см. код выше).

Попробуем сделать так, чтобы оно возникло.

Это исключение EntityNotFoundException возникает в методе updatePerson() в контроллера. А именно, когда мы обращаемся с помощью метода PUT к несуществующей сущности в попытке назначить ей имя:

PUT localhost:8080/persons/2

{
    "name": "new name"
}

В этом случае мы тоже получим ответ с новой структурой:

{
    "message": "entity not found ex",
    "debugMessage": "Unable to find ru.sysout.model.Person with id 2"
}

Итого, обработчик в @ControllerAdvice позволил изменить не только код ответа, но и тело сообщение. Причем один обработчик мы применили для двух исключений.

Последовательность проверок

Обратите внимание, что MyEntityNotFoundException мы «обработали» дважды — изменили код с помощью @ResponseStatus (1) и прописали в @ContollerAdvice — тут изменили как код, так и тело ответа (2). Эти обработки могли быть противоречивы, но существует приоритет:

• Когда выбрасывается исключение MyEntityNotFoundException, сначала Spring проверяет @ControllerAdvice-класс. А именно, нет ли в нем обработчика, поддерживающего наше исключение. Если обработчик есть, то исключение в нем и обрабатывается. В этом случае код @ResponseStatus значения не имеет, и в BasicErrorController исключение тоже не идет.
• Если исключение не поддерживается в @ControllerAdvice-классе, то оно идет в BasicErrorController. Но перед этим Spring проверяет, не аннотировано ли исключение аннотацией @ResponseStatus. Если да, то код ответа меняется, как указано в @ResponseStatus. Далее формируется ответ в BasicErrorController.
• Если же первые два условия не выполняются, то исключение обрабатывается сразу в BasicErrorController — там формируется стандартный ответ со стандартным кодом (для пользовательских исключений он равен 500).

Но и стандартный ответ можно изменить, для этого нужно расширить класс DefaultErrorAttributes.

Попробуем это сделать.

Изменение DefaultErrorAttributes

Давайте добавим в стандартный ответ еще одно поле. Для этого расширим класс:

@Component
public class CustomErrorAttributes extends DefaultErrorAttributes {


    @Override
    public Map<String, Object> getErrorAttributes(WebRequest webRequest, ErrorAttributeOptions options) {
        Map<String, Object> errorAttributes=super.getErrorAttributes(webRequest, options);
        errorAttributes.put("newAttribute", "value");
        return errorAttributes;
    }

}

В Map errorAttributes перечисляются поля ответа. Мы взяли их из родительского метода и добавили свое поле newAttribute.

Чтобы выполнить проверку, надо убрать @ControllerAdvice, поскольку он самый приоритетный и с ним мы даже не дойдем до BasicErrorController со «стандартными» полями.

Далее запросим ресурс:

localhost:8080/persons/2

Получим ответ:

{
    "timestamp": "2021-02-28T18:50:14.479+00:00",
    "status": 404,
    "error": "Not Found",
    "message": "Entity is not found, id=2",
    "path": "/persons/2",
    "newAttribute": "value"
}

В JSON-ответе появилось дополнительное поле.

ResponseStatusException

Рассмотрим еще один вариант, позволяющий сразу протолкнуть код ответа и сообщение стандартные поля, не прописывая обработку пользовательских или  встроенных исключений.  А вместо этого просто выбросив специально предназначенное исключение ResponseStatusException.

Изменим код метода контроллера getPerson():

@GetMapping(value = "/{personId}")
public Person getPerson(@PathVariable("personId") long personId){
    return personRepository.findById(personId).orElseThrow(() -> new ResponseStatusException(
            HttpStatus.NOT_FOUND, "Person Not Found"));
}

Теперь тут не выбрасывается ни MyEntityNotFoundException, ни java.util.NoSuchElementException. А выбрасывается ResponseStatusException с заданным сообщением и кодом ответа.

Теперь при запросе

GET localhost:8080/persons/2

ответ будет таким:

{
    "timestamp": "2021-03-01T07:42:19.164+00:00",
    "status": 404,
    "error": "Not Found",
    "message": "Person Not Found",
    "path": "/persons/2",
    "newAttribute": "value"
}

Как код, так и сообщение появилось в полях стандартного ответа.

ResponseStatusException не вступает в конкуренцию ни со способом @ControllerAdvice, ни с @ResponseStatus — просто потому, что это другое исключение.

Итоги

Код примера доступен на GitHub. В следующей части мы унаследуем RestExceptionHandler от ResponseEntityExceptionHandler. Это класс-заготовка, которая уже обрабатывает ряд исключений.