backstopper-spring-boot3-webmvc

Backstopper - spring-boot3

Backstopper is a framework-agnostic API error handling and (optional) model validation solution for Java 17 and greater.

(NOTE: The Backstopper 1.x branch contains a version of Backstopper for Java 7+, and for the javax ecosystem. The current Backstopper supports Java 17+ and the jakarta ecosystem. The Backstopper 1.x releases also contain support for Spring 4 and 5, and Springboot 1 and 2.)

This readme focuses specifically on the Backstopper Spring Boot 3 integration utilizing the Spring Web MVC framework. If you are looking for a different framework integration check out the relevant section of the base readme to see if one already exists. The base project README.md and User Guide contain the main bulk of information regarding Backstopper.

NOTE: There is a Spring Boot 3 Web MVC sample application that provides a simple concrete example of the information covered in this readme.

ALSO NOTE: This library does not cover Spring WebFlux (Netty) applications. If you're looking for a Spring Boot 3 app using the Spring WebFlux framework, then you should use the backstopper-spring-web-flux integration instead. This library is just for Spring Boot 3 apps using Spring Web MVC (Servlet).

Backstopper Spring Boot 3 Web MVC Setup, Configuration, and Usage

Setup

• Pull in the com.nike.backstopper:backstopper-spring-boot3-webmvc dependency into your project.
• Register Backstopper components with Spring Boot, either via @Import({BackstopperSpringboot3WebMvcConfig.class}), or @ComponentScan(basePackages = "com.nike.backstopper"). See the javadocs on BackstopperSpringboot3WebMvcConfig for some related details.
  • This causes SpringApiExceptionHandler and SpringUnhandledExceptionHandler to be registered with the Spring Boot HandlerExceptionResolver error handling chain in a way that overrides the default error handlers so that the Backstopper handlers will take care of all errors. It sets up SpringApiExceptionHandler with a default list of ApiExceptionHandlerListener listeners that should be sufficient for most projects. You can override that list of listeners (and/or many other Backstopper components) if needed in your project's Spring config.
  • It also registers BackstopperSpringboot3ContainerErrorController to handle errors that happen outside Spring Boot (i.e. in the Servlet container), and make sure they're routed through Backstopper as well.
• Expose your project's ProjectApiErrors and a JSR 303 jakarta.validation.Validator implementation in your Spring dependency injection config.
  • ProjectApiErrors creation is discussed in the base Backstopper readme here.
  • JSR 303 setup and generation of a Validator is discussed in the Backstopper User Guide here. If you're not going to be doing any JSR 303 validation outside what is built-in supported by Spring Web MVC, and you don't want to bother jumping through the hoops to get a handle on Spring's JSR 303 validator impl provided by WebMvcConfigurer.getValidator(), and you don't want to bother creating a real Validator yourself then you can simply register NoOpJsr303Validator.SINGLETON_IMPL as the Validator that gets exposed by your Spring config. ClientDataValidationService and FailFastServersideValidationService would fail to do anything, but if you don't use those then it wouldn't matter.
• Setup the reusable unit tests for your project as described in the Backstopper User Guide here and shown in the sample application.

Usage

The base Backstopper readme covers the usage basics. There should be no difference when running in a Spring Boot environment, but since Spring Boot integrates a JSR 303 validation system into its core functionality we can get one extra nice tidbit: to have Spring Boot run validation on objects deserialized from incoming user data you can simply add @Valid annotations on the objects you're deserializing for your controller endpoints (@RequestBody object, @ModelAttribute objects, etc). For example:

@RequestMapping(method=RequestMethod.POST)
@ResponseBody
@ResponseStatus(HttpStatus.CREATED)
public SomeOutputObject postSomeInput(
        @ModelAttribute @Valid HeadersAndQueryParams headersAndQueryParams,
        @RequestBody @Valid SomeInputObject inputObject) {
    
    // ... Normal controller processing
    
}

This method signature with the two @Valid annotations would cause both the @ModelAttribute headersAndQueryParams and @RequestBody inputObject arguments to be run through JSR 303 validation. Any constraint violations caught at this time will cause a Spring-specific exception to be thrown with the constraint violation details buried inside. This backstopper-spring-boot3-webmvc plugin library's error handler listeners know how to convert this to the appropriate set of ApiError cases (from your ProjectApiErrors) automatically using the Backstopper JSR 303 naming convention, which are then returned to the client using the standard error contract.

This feature allows you to enjoy the Backstopper JSR 303 validation integration support automatically at the point where caller-provided data is deserialized and passed to your controller endpoint without having to inject and manually call a ClientDataValidationService.

NOTE - Spring Boot Autoconfigure, Spring WebMVC, and Servlet API dependencies required at runtime

This backstopper-spring-boot3-webmvc module does not export any transitive Spring Boot, Spring, or Servlet API dependencies to prevent runtime version conflicts with whatever Spring Boot and Servlet environment you deploy to.

This should not affect most users since this library is likely to be used in a Spring Boot/Servlet environment where the required dependencies are already on the classpath at runtime, however if you receive class-not-found errors related to Spring Boot, Spring, or Servlet API classes then you'll need to pull the necessary dependency into your project.

The dependencies you may need to pull in:

• Spring Boot Autoconfigure: org.springframework.boot:spring-boot-autoconfigure:[spring-boot3-version]
• Spring Web MVC: org.springframework:spring-webmvc:[spring-version]
• Jakarta Servlet API: jakarta.servlet:jakarta.servlet-api:[servlet-api-version]

More Info

See the base project README.md, User Guide, and Backstopper repository source code and javadocs for all further information.

License

Backstopper is released under the Apache License, Version 2.0