Complete, ready to use exception handling for Spring Boot REST services.
- unified HTTP response format for every unhandled exception (thrown from controllers or servlet filters)
- unified exception log format
- JSON and XML HTTP response body types
- configurable HTTP response body format
- support for custom exceptions
- support for Bean Validation exceptions
- support for Spring Web 4xx errors
- RestTemplate that supports ErroREST HTTP responses
- support for Spring Security exceptions
repositories {
mavenCentral()
}
dependencies {
compile 'com.github.mkopylec:errorest-spring-boot-starter:2.0.0'
}The starter maps all unhandled exceptions to specific ErroREST HTTP responses.
If the incoming HTTP request contains Accept: application/json header, the HTTP response will contain Content-Type: application/json header.
The response body will be:
{
"id":"<random id>",
"errors":[
{
"code":"<some error code>",
"description":"<some error description>"
}
]
}If the incoming HTTP request contains Accept: application/xml header, the HTTP response will contain Content-Type: application/xml header.
The response body will be:
<body>
<id>random id</id>
<errors>
<error>
<code>some error code</code>
<description>some error description</description>
</error>
</errors>
</body>All unhandled exceptions are logged using the following template:
ID: <random id> | <http request method> <http request uri> <http response status> | <some error code>: <some error description> | <another error code>: <another error description> | ...
Exceptions are always logged with stack trace.
To start using the starter in a REST service the service must be a Spring Boot web application:
@SpringBootApplication
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}No extra configuration and no custom exception handler is needed to ensure that all thrown exceptions will be properly mapped to ErroREST HTTP responses.
The starter supports the following features to make error handling as easy as possible.
By default response body includes error codes and descriptions. To hide error descriptions set an appropriate configuration property:
errorest.response-body-format: without_descriptionsCustom exceptions can be configured how they will be mapped to ErroREST HTTP responses by extending ApplicationException, for example:
public class SampleApplicationException extends ApplicationException {
public SampleApplicationException(String message, Throwable cause) {
super(new ApplicationExceptionConfiguration()
.withResponseHttpStatus(BAD_REQUEST)
.withLoggingLevel(WARN)
.withCause(cause)
.addError("SAMPLE_ERROR_CODE", message)
);
}
}The SampleApplicationException from the example will be mapped to ErroREST HTTP response with 400 (bad request) status and body like so:
{
"id":"<random id>",
"errors":[
{
"code":"SAMPLE_ERROR_CODE",
"description":message
}
]
}The exception will be logged as warning.
The starter is able to map Bean Validation exceptions to ErroREST HTTP responses with 422 statuses (unprocessable entity).
For this kind of exceptions a validation constraint message is mapped to an error code and an error description becomes a description of the invalid value.
For example, if the following validation fails:
public class SampleRequestBody {
@NotNull(message = "EMPTY_MESSAGE")
private String message;
@Max(message = "NUMBER_TOO_BIG", value = 10)
private int number;
...
}the result will mapped to ErroREST HTTP response with body:
{
"id":"<random id>",
"errors":[
{
"code":"EMPTY_MESSAGE",
"description":"Invalid 'message' value: null"
},
{
"code":"NUMBER_TOO_BIG",
"description":"Invalid 'number' value: 11"
}
]
}By default all validation errors are logged with WARN level.
To change the logging level set an appropriate configuration property:
errorest.bean-validation-error.logging-level: <logging level>Spring Web includes a set of generic exceptions that represents HTTP client errors,
for example HttpMessageNotReadableException or HttpRequestMethodNotSupportedException.
Those exceptions are automatically mapped to ErroREST HTTP responses with a proper HTTP statuses.
By default 4xx HTTP errors are logged with WARN level.
To change the logging level set an appropriate configuration property:
errorest.http-client-error.logging-level: <logging level>The starter includes a special RestTemplate called ErrorestTemplate which fully supports ErroREST HTTP responses.
The ErrorestTemplate in case of HTTP error throws ExternalHttpRequestException which extends HttpStatusCodeException.
The ExternalHttpRequestException overrides the getMessage() method to return much more detailed information about HTTP error than HttpStatusCodeException.
It also defines getResponseBodyAsErrors() method which maps ErroREST HTTP response bodies to Errors objects.
The usage of ErrorestTemplate is the same as of normal RestTemplate:
RestOperations client = new ErrorestTemplate();
try {
client.getForObject("http://exmaple.com", String.class);
} catch (ExternalHttpRequestException ex) {
String detailedMessage = ex.getMessage();
Errors errors = ex.getResponseBodyAsErrors();
...
}If the ExternalHttpRequestException will not be handled manually it will be handled automatically by the starter.
In that case a received ErroREST HTTP response will be proxied up to the client.
The starter supports mapping Spring Security exceptions to ErroREST HTTP responses if the following dependency is added:
dependencies {
compile 'org.springframework.boot:spring-boot-starter-security:2.0.1.RELEASE'
}To support the HTTP Security configuration and method secured with annotations ErrorestAccessDeniedHandler and ErrorestAuthenticationEntryPoint are needed:
@Configuration
@EnableWebSecurity
public class SecurityConfiguration extends WebSecurityConfigurerAdapter {
@Autowired
private ErrorestAuthenticationEntryPoint authenticationEntryPoint;
@Autowired
private ErrorestAccessDeniedHandler accessDeniedHandler;
@Override
protected void configure(HttpSecurity http) throws Exception {
http.exceptionHandling()
.authenticationEntryPoint(authenticationEntryPoint)
.accessDeniedHandler(accessDeniedHandler)
.and()
...
}
}The following list contains all available configuration properties with their default values.
errorest:
response-body-format: full # HTTP response body format.
http-client-error:
logging-level: warn # HTTP 4xx errors logging level.
bean-validation-error:
logging-level: warn # Validation errors logging level.ErroREST Spring Boot Starter is published under Apache License 2.0.