Graceful Response: Unified API Response Handling for Spring Boot Applications

Graceful Response is a Spring Boot component that provides a one‑stop solution for unified response wrapping, global exception handling, and custom error‑code mapping, helping developers write cleaner and more maintainable code.

Typical Spring Boot controller implementations often suffer from low efficiency, duplicated validation and try‑catch logic, and poor readability because developers manually construct response objects and error codes.

By adding the Graceful Response Maven dependency and enabling it with @EnableGracefulResponse in the main application class, developers can simply return plain business objects from controller methods; the framework automatically wraps them into a standard JSON format.

@EnableGracefulResponse
@SpringBootApplication
public class ExampleApplication {
    public static void main(String[] args) {
        SpringApplication.run(ExampleApplication.class, args);
    }
}

Example controller after integration:

@Controller
public class Controller {
    @RequestMapping("/get")
    @ResponseBody
    public UserInfoView get(Long id) {
        log.info("id={}", id);
        return UserInfoView.builder().id(id).name("name" + id).build();
    }
}

When the method returns a plain object, Graceful Response automatically produces a response such as:

{
  "status": {"code": "0", "msg": "ok"},
  "payload": {"id": 1, "name": "name1"}
}

Custom exceptions can be linked to specific error codes using @ExceptionMapper , eliminating the need for manual error‑code handling in service layers.

@ExceptionMapper(code = "1404", msg = "Object not found")
public class NotFoundException extends RuntimeException { }

Service methods can simply throw these exceptions, and Graceful Response will convert them into the unified response format.

Validation support is enhanced by combining JSR‑303 annotations with @ValidationStatusCode , allowing a single error code to be returned for any validation failure.

@Data
public class UserInfoQuery {
    @NotNull(message = "userName is null !")
    @Length(min = 6, max = 12)
    @ValidationStatusCode(code = "520")
    private String userName;
}

If validation fails, the response will contain the configured code (e.g., 520) and the validation message.

Graceful Response offers two built‑in response styles (style=0 and style=1) and also allows developers to define custom response structures to meet specific business requirements.

Overall, integrating Graceful Response streamlines API development, reduces repetitive code, and provides a consistent error‑handling strategy for Spring Boot backend projects.