SpringBoot 如何使用 @ResponseStatus 注解处理异常状态码

SpringBoot 是一款非常流行的 Java Web 开发框架，它提供了很多便捷的功能来简化开发工作。其中，异常处理是非常重要的一部分。在实际开发中，我们经常需要处理各种异常情况，并返回适当的 HTTP 状态码给客户端。在本文中，我们将介绍如何使用 SpringBoot 中的 @ResponseStatus 注解来处理异常状态码。

@ResponseStatus 注解的概念和用法

@ResponseStatus 是 Spring Framework 提供的一个注解，用于指定控制器方法抛出异常时的 HTTP 状态码。我们可以在控制器方法或自定义异常类上使用 @ResponseStatus 注解，以指定异常情况下的 HTTP 状态码。

下面是一个例子，演示如何使用 @ResponseStatus 注解来指定 HTTP 状态码。

@ResponseStatus(HttpStatus.NOT_FOUND)
public class ResourceNotFoundException extends RuntimeException {
    // ...
}

在上面的例子中，我们声明了一个 ResourceNotFoundException 异常类，并使用 @ResponseStatus 注解指定了 HTTP 状态码为 HttpStatus.NOT_FOUND（404）。

使用 @ResponseStatus 注解处理异常状态码

在 SpringBoot 应用程序中，我们可以使用 @ResponseStatus 注解来处理异常状态码。具体来说，我们可以在控制器方法或自定义异常类上使用 @ResponseStatus 注解，以指定异常情况下的 HTTP 状态码。

1. 在控制器方法上使用 @ResponseStatus 注解

在控制器方法中，如果出现异常情况，我们可以使用 @ResponseStatus 注解来指定 HTTP 状态码。下面是一个例子，演示如何在控制器方法中使用 @ResponseStatus 注解。

@RestController
public class UserController {

    @GetMapping("/users/{id}")
    public User getUserById(@PathVariable Long id) {
        User user = userRepository.findById(id)
                .orElseThrow(() -> new ResourceNotFoundException("User not found with id " + id));
        return user;
    }

    @ResponseStatus(HttpStatus.NOT_FOUND)
    @ExceptionHandler({ResourceNotFoundException.class})
    public void handleNotFoundException() {
        // Handle ResourceNotFoundException
    }
}

在上面的例子中，我们定义了一个 UserController 控制器类，并在 getUserById 方法中使用了 @ResponseStatus 注解来指定 ResourceNotFoundException 异常情况下的 HTTP 状态码为 HttpStatus.NOT_FOUND（404）。同时，我们还定义了一个 handleNotFoundException 方法，用于处理 ResourceNotFoundException 异常情况。当出现该异常时，控制器会自动调用该方法，并返回指定的 HTTP 状态码。

2. 在自定义异常类上使用 @ResponseStatus 注解

除了在控制器方法中使用 @ResponseStatus 注解，我们还可以在自定义异常类上使用该注解来指定异常情况下的 HTTP 状态码。下面是一个例子，演示如何在自定义异常类上使用 @ResponseStatus 注解。

@ResponseStatus(HttpStatus.NOT_FOUND)
public class ResourceNotFoundException extends RuntimeException {
    // ...
}

在上面的例子中，我们定义了一个 ResourceNotFoundException 异常类，并使用 @ResponseStatus 注解指定了 HTTP 状态码为 HttpStatus.NOT_FOUND（404）。当抛出该异常时，SpringBoot 会自动返回指定的 HTTP 状态码，并将异常信息返回给客户端。

原理解析

在 SpringBoot 应用程序中，当控制器方法或自定义异常类上使用 @ResponseStatus 注解时，SpringBoot 会自动处理异常情况，并返回指定的 HTTP 状态码给客户端。具体来说，SpringBoot 会使用 ResponseStatusExceptionResolver 类来处理异常状态码。

ResponseStatusExceptionResolver 是 Spring Framework 提供的一个异常解析器，用于处理使用 @ResponseStatus 注解指定的异常情况。当控制器方法抛出异常时，ResponseStatusExceptionResolver 会检查异常类上是否有 @ResponseStatus 注解，并将指定的 HTTP 状态码返回给客户端。如果控制器方法没有指定 @ResponseStatus 注解，ResponseStatusExceptionResolver 会继续查找全局异常处理器，并使用其中的异常处理器来处理异常情况。

在 ResponseStatusExceptionResolver 中，使用了 ResponseStatus 注解中定义的 value() 属性来获取异常对应的 HTTP 状态码，并将其返回给客户端。同时，如果 @ResponseStatus 注解中定义了 reason() 属性，ResponseStatusExceptionResolver 会将其作为响应消息的正文内容返回给客户端。

下面是 ResponseStatusExceptionResolver 的部分源代码，展示了其如何处理异常状态码。

public class ResponseStatusExceptionResolver implements HandlerExceptionResolver {

    @Override
    public ModelAndView resolveException(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) {
        // Check if the exception class is annotated with @ResponseStatus
        ResponseStatus responseStatus = AnnotationUtils.findAnnotation(ex.getClass(), ResponseStatus.class);
        if (responseStatus != null) {
            // Set the response status code
            response.setStatus(responseStatus.value().value());
            // Set the response body
            String reason = responseStatus.reason();
            if (!StringUtils.isEmpty(reason)) {
                response.setContentType("text/plain;charset=UTF-8");
                try {
                    response.getWriter().write(reason);
                } catch (IOException e) {
                    // ...
                }
                return new ModelAndView();
            }
        }
        // ...
    }
}

在上面的代码中，resolveException() 方法首先检查抛出异常的类是否有 @ResponseStatus 注解，如果有，则使用注解中指定的 HTTP 状态码来设置响应状态码，并将注解中指定的响应消息作为响应正文返回给客户端。如果没有找到 @ResponseStatus 注解，则继续查找全局异常处理器，直到找到可以处理该异常的处理器为止。

总结

在本文中，我们介绍了如何使用 SpringBoot 中的 @ResponseStatus 注解来处理异常状态码。具体来说，我们可以在控制器方法或自定义异常类上使用 @ResponseStatus 注解，以指定异常情况下的 HTTP 状态码。同时，我们还分析了 ResponseStatusExceptionResolver 类的实现原理，以更好地理解 SpringBoot 如何处理异常状态码。

使用 @ResponseStatus 注解可以使异常处理更加方便和简洁，并且可以使代码更具可读性。在实际开发中，我们应该根据具体的业务需求，合理地使用 @ResponseStatus 注解来处理异常状态码，以提高应用程序的可维护性和可扩展性。