Introduce common composed annotations for @RequestMapping [SPR-13992]

[spring-projects-issues]

Sam Brannen opened SPR-13992 and commented

Overview

See #18022.

Deliverables

1. Introduce @GetMapping, @PostMapping, @PutMapping, @DeleteMapping, & @PatchMapping composed annotations for @RequestMapping
2. Introduce headers and name attribute in composed @RequestMapping annotations.
   • The team has decided to introduce these common attributes.
3. Restrict the value, path, consumes, and produces attributes to single String values in composed @RequestMapping annotations. (see Allow a single element to override an array attribute in a meta-annotation [SPR-13972] #18544)
   • The team has decided against this.

---

Affects: 4.2 GA

Issue Links:

• Allow a single element to override an array attribute in a meta-annotation [SPR-13972] #18544 Allow a single element to override an array attribute in a meta-annotation ("depends on")
• Introduce predefined composed annotations in core Spring [SPR-13442] #18022 Introduce predefined composed annotations in core Spring
• Custom @RequestMapping annotations [SPR-12296] #16901 Custom @RequestMapping annotations
• Introduce common composed annotations for web scopes [SPR-13993] #18566 Introduce common composed annotations for web scopes
• Allow a single element to override an array attribute in a meta-annotation [SPR-13972] #18544 Allow a single element to override an array attribute in a meta-annotation

1 votes, 14 watchers

[spring-projects-issues]

Sam Brannen commented

Work on this issue is being performed in the following branch:

https://github.com/sbrannen/spring-framework/commits/SPR-13992

[spring-projects-issues]

Kazuki Shimizu commented

Is not need @HeadMapping and @OptionsMapping ?
I was implemented REST APIs using HEAD and OPTIONS at past.
I hope to add @HeadMapping and @OptionsMapping if possible.

Thanks.

[spring-projects-issues]

Sam Brannen commented

Rossen Stoyanchev, please review the pull request:

#981

[spring-projects-issues]

Sam Brannen commented

Kazuki Shimizu, for 4.3 RC1 the team decided to implement a minimal set of composed annotations for @RequestMapping (and therefore against @HeadMapping and @OptionsMapping); however, we may later consider introducing such annotations.

Regards,

Sam

[spring-projects-issues]

Kazuki Shimizu commented

Sam Brannen, Thanks for your comment!

for 4.3 RC1 the team decided to implement a minimal set of composed annotations for @RequestMapping

OK! I understand spring team decision. Probably, @OptionsMapping is not need. But i hope to consider again as @HeadMapping ;)

[spring-projects-issues]

Sébastien Deleuze commented

Big +1 for this feature for Spring + Kotlin application developers, it will allow them to write @GetMapping instead of @RequestMapping(method = arrayOf(RequestMethod.GET)) (see this blog post for more details).

[spring-projects-issues]

Rossen Stoyanchev commented

Kazuki Shimizu, for 4.3 we are also adding built-in OPTIONS and HEAD support (see #17721). That means every controller method has those methods covered by Spring MVC. We do allow HEAD and OPTIONS to be mapped explicitly still. However I'm wondering if this changes your mind or do you have use cases in mind still?

[spring-projects-issues]

Kazuki Shimizu commented

Rossen Stoyanchev, thanks for your comment !! I have missed the #17721. It's very good improvement (y)
I think @OptionsMapping and @HeadMapping is unnecessary.

[spring-projects-issues]

Sam Brannen commented

Pushed to master in the following commit:

467b5f3

[spring-projects-issues]

Phil Webb commented

I might be a bit late to the party, but is the Mapping suffix necessary? It feels kind of noisy, especially considering the annotations are usually used in the context of a @Controller where it's pretty obvious that they are mappings.

	@GetMapping("/{username}/vehicle")
	public String getVehicle(@PathVariable String username) {
		// ...
	}

	@DeleteMapping("/{username}/vehicle")
	public String deleteVehicle(@PathVariable String username) {
		// ...
	}

	@PutMapping("/{username}/vehicle")
	public String replaceVehicle(@PathVariable String username) {
		// ...
	}

vs

	@Get("/{username}/vehicle")
	public String getVehicle(@PathVariable String username) {
		// ...
	}

	@Delete("/{username}/vehicle")
	public String deleteVehicle(@PathVariable String username) {
		// ...
	}

	@Put("/{username}/vehicle")
	public String replaceVehicle(@PathVariable String username) {
		// ...
	}

[spring-projects-issues]

Sam Brannen commented

Phil Webb,

The "Mapping" suffix is not technically necessary, but the team decided against the shorter variants for the following reasons.

• They are too similar to the JAX RS annotations -- @GET, @POST, etc. -- which might lead to confusion amongst developers familiar with both technologies.
• The "Mapping" suffix provides a mental link to @RequestMapping allowing users to immediately recognize it's a Spring MVC annotation and not from some other framework.

For what it's worth, I also prefer @Get, @Post, etc. For a concrete example, check out the RestEventsController from my spring-events example project.

Regards,

Sam

[spring-projects-issues]

Rossen Stoyanchev commented

The @RequestMapping annotation was originally carefully chosen and over time has come to be associated with Spring MVC as Sam mentioned. It could have been named @HttpRequest or even shorter @Http. Sure everyone would understand what it refers to and it would be readable but in fact a method annotated with @HttpRequest is not an HTTP request itself, nor is the annotation an HTTP request. It is an HTTP request mapping.

The exact same line of thought applies to @Get which could also be @HttpGet but neither the method, nor the mapping is an HTTP GET. @Get is too unqualified in that sense even if it is short and readable. In the end we are trying to strike a balance.

The association with a mental model is all too often underestimated IMO. JAX-RS has a different style of mapping and while the two won't be mixed in the same class, people with all sorts of background and knowledge will come across all sorts of examples across the internet. Having to add explanations on how the two may be the same or not (in order to help readers) is completely undesirable. Furthermore JAX-RS has been around for many years. Those annotations have well established associations and expectations for many.

What we are adding here are framework endorsed shortcut annotations that should be consistent with other usages in the framework including @RequestMapping as well as others like @MessageMapping, @SubscribeMapping, etc. Its just as easy for anyone to create their own.

Lastly not to forget that you still need @RequestMapping at the type level if you want to have a shared base path which is quite common. Mixing @RequestMapping with @GetMapping in the same class works much more congruently.

[spring-projects-issues]

Oliver Drotbohm commented

I'd like to cast another vote on not putting these shortcut annotations into the framework. They cause a lot of confusion, disputes over naming so that we're probably never going to get to a name that pleases everyone, see above and add very little benefit.

Assume Jane developer is new to the framework, enthusiastic about these annotation and she uses quite a few of them in her controller implementation. Now she realizes, she needs to restrict based on HTTP header. How does she find out she can actually restrict on those. Okay, she checks the documentation and finds out she needs to use a different annotation. Once she accepted that and wondered why that actually is the case, she now ands up with a mixture of those shortcut annotations and good ol' @RequestMapping. Now every other developer looking at the code is gonna ask: why two different flavors? Should we refactor back to @RequestMapping to make stuff consistent?

Another aspect that plays into this: if @GetMapping is available and it's a short cut for @RequestMapping(method = GET), why not have @GetJsonMapping et al. Why is there no @OptionsMapping, no @HeadMapping? Of course all this can be justified with some verbose explanation, but why would we even want to get into that discussion? Controller methods already are a complicated topic especially for newbies due to all the different types supported as parameters, the different ways how return values are interpreted depending on what mode is selected. And this stuff has been growing over the last couple of release with the support for async requests etc. Really, the last thing that area of the framework needs is even more options for the last bit that's actually the only straight-forward thing left there: how to map incoming requests. One way, all functionality imaginable covered, perfect.

I can totally see the case for @RequestScope et al. as that scenario just doesn't exist there. It's more of a corner case in framework functionality, MVC request mapping is front and center of every Spring based web app. I already spend too much time explaining @RestController VS. @Controller.

Don't get me wrong, for more experienced users these annotations look like a shortcut but for less experienced ones they're not. The scenario will look like the simply ones don't provide enough mapping functionality so that "other needs to be used in such scenarios". We're basically painting ourselves in a corner of @Resource VS. @EJB VS. @Inject in the JavaEE world: creating choice without real benefits but a lot of cognitive load. Spring is already deemed too complex and having too many ways to achieve things, sharp tongues even claim that's why Boot has to exist in the first place. All our efforts in the last couple of years have been targeted to simplify things but outside our expert's eyes (for which I can understand this looks simpler in the first place) this is not simplifying — it's the opposite.

I am all in for the framework being able to work with composed annotations so that people can craft their own shortcuts and even a dedicated library living outside the framework for everyone keen to use to do so. If people want to create their @Get they can. I'll bet every project is going to end up with a slightly different flavor if it. However, I am not keen on introducing more choice for the sake of choice and at the expense of confusion in the probably most used area of the framework.

[spring-projects-issues]

Adam Berlin commented

I'd like to add a vote for @Get, @Post, and the like. In the controller context they are a clean way to describe what I want in contrast to @RequestMapping(...). I'd say make the usual case easy and optimized for readability with a nice escape-hatch to solve more complicated mappings.

[spring-projects-issues]

Dave Syer commented

My $0.02. I like the brevity (and I'm not known for that). If Ollie is right, though, and you need to change annotations in order to add a media type constraint, then I think that's bad. Why can't @GetMapping have aliases for everything relevant in @RequestMapping (i.e. nearly everything except method)? In fact I see it does have aliases for nearly everything, so maybe I just misunderstand what is relevant. Why no alias for headers?