Returning Custom Status Codes from Spring Controllers – 从Spring控制器返回自定义状态代码

最后修改: 2016年 2月 3日


1. Overview


This quick article will demonstrate a few ways to return custom HTTP status codes from Spring MVC controllers.

这篇快速文章将演示几种从Spring MVC控制器返回自定义HTTP状态代码的方法。

This is often important in order to more clearly express the result of a request to a client and using the full rich semantics of the HTTP protocol. For example, if something goes wrong with a request, sending a specific error code for each type of possible problem would allow the client to display an appropriate error message to the user.


The setup of a basic Spring MVC project is outside the scope of this article, but you can find more information here.

基本的Spring MVC项目的设置超出了本文的范围,但你可以在这里找到更多信息

2. Returning Custom Status Codes


Spring provides a few primary ways to return custom status codes from its Controller classes:


  • using a ResponseEntity
  • using the @ResponseStatus annotation on exception classes, and
  • using the @ControllerAdvice and @ExceptionHandler annotations.

These options are not mutually exclusive; far from it, they can actually complement one another.


This article will cover the first two ways (ResponseEntity and @ResponseStatus). If you would like to learn more about using @ControllerAdvice and @ExceptionHandler, you can read about it here.


2.1. Returning Status Codes via a ResponseEntity


In a standard Spring MVC controller, we will define a simple mapping:

在一个标准的Spring MVC控制器中,我们将定义一个简单的映射。

@RequestMapping(value = "/controller", method = RequestMethod.GET)
public ResponseEntity sendViaResponseEntity() {
    return new ResponseEntity(HttpStatus.NOT_ACCEPTABLE);

Upon receiving a GET request to “/controller“, Spring will return a response with the 406 Code (Not Acceptable). We arbitrarily selected the specific response code for this example. You can return any HTTP status code (the full list can be found here).


2.2. Returning Status Codes via an Exception


We will add a second method to the controller to demonstrate how to use an Exception to return a status code:


@RequestMapping(value = "/exception", method = RequestMethod.GET)
public ResponseEntity sendViaException() {
    throw new ForbiddenException();

Upon receiving a GET request to “/exception“, Spring will throw a ForbiddenException. This is a custom exception that we will define in a separate class:


public class ForbiddenException extends RuntimeException {}

No code is required in this exception. All the work is done by the @ResponseStatus annotation.


In this case, when the exception is thrown, the controller that threw it returns a response with the response code 403 (Forbidden). If necessary, you can also add a message in the annotation that will be returned along with the response.


In this case, the class would look like this:


@ResponseStatus(value = HttpStatus.FORBIDDEN, reason="To show an example of a custom message")
public class ForbiddenException extends RuntimeException {}

It is important to note that while it is technically possible to make an exception return any status code, in most cases it only makes logical sense to use exceptions for error codes (4XX and 5XX).


3. Conclusion


The tutorial showed how to return custom status codes from Spring MVC controllers.

该教程展示了如何从Spring MVC控制器返回自定义状态代码。

The implementation can be found in the example GitHub project.