Spring Boot 4: Replacing 250 Lines of Versioning Code with Native Config

The Problem: The "Over-Engineered" Versioning Strategy

In standard enterprise Spring Boot applications, API versioning often becomes a nightmare of boilerplate. When I joined a client's project recently, I found a common-lib versioning module that was 250+ lines of code.

It included:

1. Custom Annotations: @ApiVersion(1) plastered everywhere.
2. CustomRequestMappingHandlerMapping: Implementing WebMvcRegistrations to override default routing.
3. ApiVersionRequestCondition: A complex class extending AbstractRequestCondition to parse URLs, headers, and media types.
4. Comparators: Logic to determine that v2 > v1.

It looked something like this (simplified):

Copy
1// The Old Way: Complex and Brittle
2@Override
3protected RequestCondition<?> getCustomMethodCondition(Method method) {
4    ApiVersion apiVersion = AnnotationUtils.findAnnotation(method, ApiVersion.class);
5    return new ApiVersionRequestCondition(apiVersion != null ? apiVersion.value() : null);
6}
7// ... 300 more lines of condition matching logic ...

This code was fragile. Every time we upgraded Spring Boot, the internal MVC APIs shifted slightly, causing breaking changes. Plus, new developers found it impossible to debug why /api/v1/users worked but /api/v2/users returned 404.

The Three Versioning Strategies

Before rewriting the code, we had to decide on a standard. Spring Boot 4 supports three versioning strategies. Each has trade-offs. Pick one and stick with it.

1. URI Path Versioning (The Winner)

The version is part of the URL structure.

• Example: GET /api/v1/users
• Pros:
  • Extremely easy to cache (CDNs love unique URLs).
  • Debuggable in browser history and logs (Access logs show exactly which version was hit).
  • Easy to route at the load balancer level (e.g., NGINX rules).
• Cons:
  • Technically violates the HATEOAS principle (changing the identifier of the resource).

2. Header Versioning (Custom Header)

The client sends a custom header to specify the version.

• Example: GET /api/users with Header X-API-VERSION: 1
• Pros:
  • URLs remain clean and resource-focused.
• Cons:
  • Harder to test (can't just paste URL in browser).
  • Cache busting requires Vary headers, which many proxies mishandle.

3. Query Parameter Versioning

The version is passed as a standard query param.

• Example: GET /api/users?version=1
• Pros:
  • Easy to default (e.g., if missing, assume v1).
• Cons:
  • Messy URLs.
  • Query parameters are often stripped or ignored by some caching layers.

Our Verdict: For 99% of internal microservices and public APIs, URI Path Versioning is the most pragmatic choice. It reduces operational overhead and debugging time.

The Solution: Native Path Matching & Properties

We realized we didn't need dynamic, complex version resolution at runtime for every single request. We needed a consistent, declarative way to namespace our endpoints using our chosen strategy (Path Versioning).

We replaced the entire custom infrastructure with Spring Boot's native capabilities combined with a simple property-driven configuration.

The "3 Lines" of Config

Instead of maintaining a complex versioning engine, we shifted to a prefix-based strategy controlled by application.yml.

Copy
1# application.yml
2spring:
3  mvc:
4    pathmatch:
5      matching-strategy: path_pattern_parser
6api:
7  prefix: /api/v1

And then, handled the mapping globally in one place:

Copy
1// The New Way: Clean and Native
2@Configuration
3public class WebConfig implements WebMvcConfigurer {
4
5    @Value("${api.prefix}")
6    private String apiPrefix;
7
8    @Override
9    public void configurePathMatch(PathMatchConfigurer configurer) {
10        configurer.addPathPrefix(apiPrefix, c -> c.isAnnotationPresent(RestController.class));
11    }
12}

Okay, so technically it's a few lines of Java plus 3 lines of YAML, but the 250 lines of custom logic are gone.

Why AntPathMatcher Failed vs PathPatternParser

One of the key reasons we switched was performance. The old custom strategy relied on AntPathMatcher, which was the default in older Spring versions.

• AntPathMatcher: Treats the URL as a String and uses simple string manipulation. It's flexible but slow for complex matching rules, especially when you inject custom logic into the chain.
• PathPatternParser (Default in Spring Boot 2.6+): Parses the URL path into a structured object tree (PathContainer). This allows Spring to match URL segments much faster and handle complex URI variables efficiently.

By moving to path_pattern_parser and configurePathMatch, we align with the framework's optimized happy path. The PathPattern implementation is designed for exactly this kind of high-throughput request mapping.

Testing the Migration

Refactoring core routing logic is scary. We ensured safety with MockMvc integration tests that verified the prefix was applied correctly without needing to touch the controllers themselves.

Copy
1@WebMvcTest(UserController.class)
2// Import the WebConfig to ensure our prefix logic runs
3@Import(WebConfig.class)
4class UserControllerTest {
5
6    @Autowired
7    private MockMvc mockMvc;
8
9    @Test
10    void shouldMapRequestWithConfiguredPrefix() throws Exception {
11        // Even though @RequestMapping("/users") is on the controller,
12        // we assert that it only responds to /api/v1/users
13        mockMvc.perform(get("/api/v1/users"))
14               .andExpect(status().isOk());
15               
16        // Verify the old path is gone
17        mockMvc.perform(get("/users"))
18               .andExpect(status().isNotFound());
19    }
20}

This test gave us 100% confidence to delete the 250 lines of legacy code.

Conclusion

The best code is the code you don't write. By leaning on framework features instead of fighting them, we deleted technical debt and made our API layer faster and easier to understand.

Deleted: 250 lines of custom framework code. Added: 3 lines of YAML. Result: Happiness.