Document Welcome Page support ordering

[sdeleuze]

When using WebMvc.fn, the order of the registered mapping is:

• RequestMappingHandlerMapping (order 0, set by Framework)
• WelcomePageHandlerMapping (order 2, set by Boot)
• RouterFunctionMapping (order 3, set by Framework)

Which leads to the surprising behavior that a RouterFunction define a user provided mapping on / to render a index template will be shadowed by WelcomePageHandlerMapping serving this template. In my case, that half broke the rendering by skipping the model attributes that were set in the handler.

After a discussion with the Spring Framework team, we are going to try to improve the consistency between WebFlux (which has RouterFunctionMapping before RequestMappingHandlerMapping ) and WebMvc (where this is the opposite) if possible (see spring-projects/spring-framework#30278) but we can't change that in a 5.3 or 6.0 patch release.

But I think I would be great if possible to fix Spring Boot 3.0 and potentially 2.7 to have WelcomePageHandlerMapping after RouterFunctionMapping.

[wilkinsona]

I'm not sure that we can change this in a maintenance release for the same reasons that you don't want to re-order RequestMappingHandlerMapping and RouterFunctionMapping in a Framework maintenance release. With spring-projects/spring-framework#30278 scheduled for Framework 6.1, I think we should schedule this for Boot 3.2.

I wonder if Framework 6.1 could consider introducing relative ordering support rather than relying on the current, rather brittle, absolute values? It's served us very well for Boot's auto-configuration.

[sdeleuze]

I will discuss that with the Framework team and let you know if the rest of the team is ok with that.

[philwebb]

@sdeleuze Any update from the Framework team?

[sdeleuze]

We have discussed this topic in this week Spring Framework team meeting, the follow-up discussion is still ongoing. I will post an update here as soon as we have reached a consensus (should happen shortly).

[sdeleuze]

As mentioned in spring-framework#30278:

We are going to change, as of Spring Framework 6.1, the order of RouterFunctionMapping defined in WebMvcConfigurationSupport from 3 to -1 in order to achieve better consistency and reduce the surprise factor. That way, functional routes will always be before annotation-based ones.

It also makes sense from a user perspective since functional routes are kind of lower level than annotation-based ones, and the overhead will be minimal for pure annotation-based use cases because if there are no RouterFunction in the application context, then RouterFunctionMapping::routerFunction is null, and the mapping does not allocate anything (no Optional<HandlerFunction<T>> instance have to be created).

This change will likely solve in Spring Boot 3.2 the original issue reported here. Solving it in Spring Boot 3.1 would require changing the WelcomePageHandlerMapping order to a lower priority order (at least 4). I think I would be in favor of that, but of course, up to Spring Boot team to decide if that's desirable and ok to perform this kind of post 3.1.0 adjustements or not.

I wonder if Framework 6.1 could consider introducing relative ordering support rather than relying on the current, rather brittle, absolute values? It's served us very well for Boot's auto-configuration.

That would be a distinct new feature that would require careful design consideration, so unlikely to be shipped as part of Spring Framework 6.1 given our current priorities.

[bclozel]

I've tested successfully the Spring Framework change from spring-projects/spring-framework#30278 - the custom RouterFunction for the index page is properly ordered ahead of the welcome page support.

Let's rework this issue as a documentation one to properly document the ordering in the welcome page section of web frameworks.