Spring MVC mapping params: route a format choice before the handler runs

Make formats explicit

Two export methods share one path but require format=csv or format=json. The checked MockMvc requests select the respective handler. format=xml matches neither; this fixture receives HTTP 400 from the MVC mapping layer. A client cannot assume that an unknown format silently chooses a default.

The fixture returns fixed strings to isolate dispatch. A real export must use a serializer with declared response Content-Type and escaping rules. Consumes and produces deals with HTTP media negotiation; a query-parameter condition is a different decision.

Do not turn a format flag into authorization

Changing the query string should not grant access to hidden data. Run identity and tenant checks on every matched handler. A third format needs its own tested response contract, size budget and content-escaping policy. The request pipeline shows where mapping fits.

Checked code

@GetMapping(path = "/contract/receipt-export", params = "format=csv")
String csv() { return "receipt,amount\nRC-47,4725"; }

@GetMapping(path = "/contract/receipt-export", params = "format=json")
String json() { return "{\"receipt\":\"RC-47\",\"amount\":4725}"; }

Verification boundary

The Maven source kit passes LifecycleAndMvcDispatchContractTest.queryParameterConditionsSelectOneHandlerAndRejectUnknownFormat on its local Spring Boot 4 and Java 21 fixture.

Cost and ownership

Handler selection is small relative to serialization, database I/O and response transfer. Standalone MockMvc checks mapping for three local requests; it does not exercise production filters, authentication, large exports or actual JSON/CSV serialization.

Common Mistakes

• Do not let an unsupported parameter value fall through to an unrelated handler.
• Do not confuse format=csv with a Content-Type or Accept contract.
• Do not mistake handler selection for tenant authorization.

Read next

Spring MVC request lifecycle: from servlet filter to response body, Spring MVC consumes and produces: 415 and 406 are different failures, Spring method authorization: reject a cross-tenant read, Spring MockMvc standalone tests: know which HTTP layers were assembled.